feat(useQueryParams): adds useQueryParams

antonioru · antonioru · commit 2d831cd8f53c · 2022-06-21T20:47:46.000+02:00
diff --git a/README.md b/README.md
@@ -79,6 +79,7 @@ $ yarn add beautiful-react-hooks
 ## 🎨 Hooks
 
 * [useQueryParam](docs/useQueryParam.md)
+* [useQueryParams](docs/useQueryParams.md)
 * [useSearchQuery](docs/useSearchQuery.md)
 * [useInfiniteScroll](docs/useInfiniteScroll.md)
 * [useObservable](docs/useObservable.md)
diff --git a/docs/README.es-ES.md b/docs/README.es-ES.md
@@ -77,6 +77,7 @@ $ yarn add beautiful-react-hooks
 ## 🎨 Hooks
 
 * [useQueryParam](useQueryParam.md)
+* [useQueryParams](useQueryParams.md)
 * [useSearchQuery](useSearchQuery.md)
 * [useInfiniteScroll](useInfiniteScroll.``md)
 * [useObservable](useObservable.md)
diff --git a/docs/README.it-IT.md b/docs/README.it-IT.md
@@ -76,6 +76,7 @@ $ yarn add beautiful-react-hooks
 ## 🎨 Hooks
 
 * [useQueryParam](useQueryParam.md)
+* [useQueryParams](useQueryParams.md)
 * [useSearchQuery](useSearchQuery.md)
 * [useInfiniteScroll](useInfiniteScroll.md)
 * [useObservable](useObservable.md)
diff --git a/docs/README.jp-JP.md b/docs/README.jp-JP.md
@@ -76,6 +76,7 @@ $ yarn add beautiful-react-hooks
 ## 🎨 Hooks
 
 * [useQueryParam](useQueryParam.md)
+* [useQueryParams](useQueryParams.md)
 * [useSearchQuery](useSearchQuery.md)
 * [useInfiniteScroll](useInfiniteScroll.md)
 * [useObservable](useObservable.md)
diff --git a/docs/README.pl-PL.md b/docs/README.pl-PL.md
@@ -79,6 +79,7 @@ $ yarn add beautiful-react-hooks
 ## 🎨 Hooki
 
 * [useQueryParam](useQueryParam.md)
+* [useQueryParams](useQueryParams.md)
 * [useSearchQuery](useSearchQuery.md)
 * [useInfiniteScroll](useInfiniteScroll.md)
 * [useObservable](useObservable.md)
diff --git a/docs/README.pt-BR.md b/docs/README.pt-BR.md
@@ -78,6 +78,7 @@ $ yarn add beautiful-react-hooks
 ## 🎨 Hooks
 
 * [useQueryParam](useQueryParam.md)
+* [useQueryParams](useQueryParams.md)
 * [useSearchQuery](useSearchQuery.md)
 * [useInfiniteScroll](useInfiniteScroll.md)
 * [useObservable](useObservable.md)
diff --git a/docs/README.uk-UA.md b/docs/README.uk-UA.md
@@ -77,6 +77,7 @@ $ yarn add beautiful-react-hooks
 ## 🎨 Хуки
 
 * [useQueryParam](useQueryParam.md)
+* [useQueryParams](useQueryParams.md)
 * [useSearchQuery](useSearchQuery.md)
 * [useInfiniteScroll](useInfiniteScroll.md)
 * [useObservable](useObservable.md)
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
@@ -74,6 +74,7 @@ $ yarn add beautiful-react-hooks
 ## 🎨 Hooks
 
 * [useQueryParam](useQueryParam.md)
+* [useQueryParams](useQueryParams.md)
 * [useSearchQuery](useSearchQuery.md)
 * [useInfiniteScroll](useInfiniteScroll.md)
 * [useObservable](useObservable.md)
diff --git a/docs/useQueryParam.md b/docs/useQueryParam.md
@@ -3,8 +3,8 @@
 ### Why? 💡
 
 - to ease the process of modify the query string in the URL for the current location.
-- Works similar to useState hook
-- built on top of react-router-dom's useSearchParams
+- Works similar to the useState hook
+- it's not built on top of react-router-dom's useSearchParams, it is therefore compatible with older version
 
 ### Basic Usage:
 
diff --git a/docs/useQueryParams.md b/docs/useQueryParams.md
@@ -0,0 +1,41 @@
+# useQueryParams
+
+Very similar to `useQueryParam` (mind the final 's'), it ease the process of manipulate a query string with multiple values.
+
+### Why? 💡
+
+- Ease the process of manipulate a query string (with multiple values) in the URL for the current location.
+- Works similar to the useState hook
+- it's not built on top of react-router-dom's useSearchParams, it is therefore compatible with older version
+
+### Basic Usage:
+
+```jsx harmony
+import { useState, useRef } from 'react';
+import { HashRouter as Router } from 'react-router-dom'
+import { Button, Input } from 'beautiful-react-ui'
+import useQueryParams from 'beautiful-react-hooks/useQueryParams';
+
+const ExampleComponent = () => {
+  // second parameter is optional
+  const [foos, setFoos] = useQueryParams('foo[]', {
+    initialValue: [1, 2, 3],
+    replaceState: false,
+  })
+
+  const onClick = () => setFoos([4, 5, 6])
+
+  return (
+    <DisplayDemo>
+      <p>Current value of 'foo[]' param is '{foos.join(',')}'</p>
+      <Button onClick={onClick} color="primary">
+        Change to param to [4,5,6]
+      </Button>
+    </DisplayDemo>
+  );
+};
+
+<Router>
+  <ExampleComponent />
+</Router>
+```
diff --git a/src/index.ts b/src/index.ts
@@ -1,3 +1,19 @@
+/**
+ * This file is kept for compatibility reasons.
+ * You should avoid importing hooks directly from this file.
+ *
+ * Avoid importing hooks like this:
+ *
+ * ```js
+ * import { useSomething } from 'beautiful-react-hooks';
+ * ```
+ *
+ * in favour of this:
+ *
+ * ```js
+ * import useSomething from 'beautiful-react-hooks/useSomething';
+ * ```
+ */
 export { default as useDidMount } from './useDidMount'
 export { default as useWillUnmount } from './useWillUnmount'
 export { default as useLifecycle } from './useLifecycle'
@@ -39,9 +55,17 @@ export { default as useSwipeEvents } from './useSwipeEvents'
 export { default as useConditionalTimeout } from './useConditionalTimeout'
 export { default as useInfiniteScroll } from './useInfiniteScroll'
 export { default as useQueryParam } from './useQueryParam'
+export { default as useQueryParams } from './useQueryParams'
 export { default as useSearchQuery } from './useSearchQuery'
 export { default as useEvent } from './useEvent'
 export { default as useViewportState } from './useViewportState'
 
 // keep it just for compatibility issues
 export { default as useStorage } from './factory/createStorageHook'
+
+if (!process.env.NODE_ENV || process.env.NODE_ENV === 'development') {
+  console.warn(`
+    TIP: To improve your application bundle size, avoid importing hooks from the index file of 'beautiful-react-hooks'.\n
+    Try 'import useSomething from 'beautiful-react-hooks/useSomething' instead of 'import { useSomething } from 'beautiful-react-hooks'
+  `)
+}
diff --git a/src/useQueryParam.ts b/src/useQueryParam.ts
@@ -2,23 +2,26 @@ import { useHistory } from 'react-router-dom'
 import { useCallback, useState } from 'react'
 import useDidMount from './useDidMount'
 
-export interface UseQueryParamsOptions<T extends string> {
+export interface UseQueryParamOptions<T extends string> {
   initialValue?: T,
   replaceState?: boolean,
+  multi?: boolean,
 }
 
-const getParamFromLocation = <TParam extends string>(search: string, param: string, options: UseQueryParamsOptions<TParam>) => {
+const getValue = (param: URLSearchParams, key: string, multi?: boolean) => (multi ? param.getAll(key) : param.get(key))
+
+const getParamFromLocation = <TParam extends string>(search: string, param: string, options: UseQueryParamOptions<TParam>) => {
   const params = new URLSearchParams(search)
-  return (params.get(param) || options.initialValue || '') as TParam
+  return (getValue(params, search, options.multi) || options.initialValue || '') as TParam
 }
 
 /**
  * Ease the process of modify the query string in the URL for the current location.
  */
-const useQueryParam = <TParam extends string>(param: string, options: UseQueryParamsOptions<TParam> = {}) => {
-  const { push, replace, location } = useHistory()
+const useQueryParam = <TParam extends string>(param: string, options: UseQueryParamOptions<TParam> = {}) => {
+  const history = useHistory()
   const onMount = useDidMount()
-  const [value, setValue] = useState<TParam>(getParamFromLocation<TParam>(location.search, param, options))
+  const [value, setValue] = useState<TParam>(getParamFromLocation<TParam>(history.location.search, param, options))
 
   const setParam = useCallback((nextValue?: TParam) => {
     const params = new URLSearchParams()
@@ -29,18 +32,18 @@ const useQueryParam = <TParam extends string>(param: string, options: UseQueryPa
     }
 
     if (options.replaceState) {
-      replace({ search: params.toString() })
+      history.replace({ search: params.toString() })
       return
     }
 
-    push({ search: params.toString() })
+    history.push({ search: params.toString() })
     setValue(nextValue)
-  }, [options.replaceState])
+  }, [options.replaceState, history])
 
   onMount(() => {
-    const current = new URLSearchParams(location.search)
+    const current = new URLSearchParams(history.location.search)
 
-    if (!current.get(param) && options.initialValue) {
+    if (!getValue(current, param, options.multi) && options.initialValue) {
       setParam(options.initialValue)
     }
   })
diff --git a/src/useQueryParams.ts b/src/useQueryParams.ts
@@ -0,0 +1,53 @@
+import { useHistory } from 'react-router-dom'
+import { useCallback, useState } from 'react'
+import useDidMount from './useDidMount'
+
+export interface UseQueryParamsOptions<T extends string[]> {
+  initialValue?: T,
+  replaceState?: boolean,
+}
+
+const getParamsFromLocation = <TParam extends string[]>(search: string, param: string, options: UseQueryParamsOptions<TParam>) => {
+  const params = new URLSearchParams(search)
+  return (params.getAll(param) || options.initialValue || []) as TParam
+}
+
+/**
+ * Very similar to `useQueryParams`, it eases the process of manipulate a query string that handles multiple values
+ */
+const useQueryParams = <TParam extends string[]>(param: string, options: UseQueryParamsOptions<TParam> = {}) => {
+  const history = useHistory()
+  const onMount = useDidMount()
+  const [value, setValues] = useState<TParam | []>(getParamsFromLocation<TParam>(history.location.search, param, options))
+
+  const setParamValues = useCallback((nextValues?: TParam) => {
+    const params = new URLSearchParams(history.location.search)
+
+    params.delete(param)
+    if (nextValues && nextValues.length > 0) {
+      nextValues.forEach((currentValue) => {
+        params.append(param, currentValue)
+      })
+    }
+
+    if (options.replaceState) {
+      history.replace({ search: params.toString() })
+      return
+    }
+
+    history.push({ search: params.toString() })
+    setValues(nextValues || [])
+  }, [history, options.replaceState, param])
+
+  onMount(() => {
+    const current = new URLSearchParams(history.location.search)
+
+    if (current.getAll(param).length === 0 && options.initialValue) {
+      setParamValues(options.initialValue)
+    }
+  })
+
+  return [value, setParamValues] as [TParam, (nextValue?: TParam) => void]
+}
+
+export default useQueryParams
diff --git a/test/useQueryParam.spec.js b/test/useQueryParam.spec.js
@@ -9,11 +9,12 @@ describe('useQueryParam', () => {
   assertHook(useQueryParam)
 
   it('should work similar to useState', () => {
-    const { result } = renderHook(() => useQueryParam(), { wrapper: ReactRouterWrapper })
+    const { result } = renderHook(() => useQueryParam('foo'), { wrapper: ReactRouterWrapper })
     const [val, setVal] = result.current
 
     expect(val).to.be.a('string')
     expect(val).to.equal('')
     expect(setVal).to.be.a('function')
   })
+
 })
diff --git a/test/useQueryParams.spec.js b/test/useQueryParams.spec.js
@@ -0,0 +1,19 @@
+import { cleanup, renderHook } from '@testing-library/react-hooks'
+import useQueryParams from '../dist/useQueryParams'
+import assertHook from './utils/assertHook'
+import ReactRouterWrapper from './utils/ReactRouterWrapper'
+
+describe('useQueryParams', () => {
+  beforeEach(() => cleanup())
+
+  assertHook(useQueryParams)
+
+  it('should work similar to useState', () => {
+    const { result } = renderHook(() => useQueryParams('foo[]'), { wrapper: ReactRouterWrapper })
+    const [val, setVal] = result.current
+
+    expect(val).to.be.an('array')
+    expect(val).to.deep.equal([])
+    expect(setVal).to.be.a('function')
+  })
+})
