state-in-url 2.2.2 → 2.2.4

package/README.md

@@ -30,7 +30,7 @@ English | [한국어](./README.KO.md) | [简体中文](./README.CN.md)
 
 <hr />
 
-Add a ⭐️ to support the project!
+Add a ⭐️ and <a href="https://github.com/asmyshlyaev177" target="_blank">foloow me</a> to support the project!
 
   <hr />
 
@@ -68,6 +68,7 @@ Add a ⭐️ to support the project!
 - [Low-level `encode` and `decode` functions](#encode-and-decode-helpers)
 - [Best practices](#best-practices)
 - [Gothas](#gothas)
+- [Roadmap](#roadmap)
 - [Contact & Support](#contact--support)
 - [Changelog](#changelog)
 - [License](#license)
@@ -387,6 +388,11 @@ npm run dev
 
 Go to [localhost:3000](http://localhost:3000)
 
+## Roadmap
+ - [x] hook for `Next.js`
+ - [ ] hook for 'react-router`
+ - [ ] hook for store state in hash ?
+
 ## Contact & Support
 
 - Create a [GitHub issue](https://github.com/asmyshlyaev177/state-in-url/issues) for bug reports, feature requests, or questions

package/dist/encodeState/encodeState.d.ts

@@ -12,7 +12,7 @@ import { type JSONCompatible, type UnknownObj } from '../utils';
  * encodeState({ name: 'test' }, form, 'someExistingParam=123');
  *  ```
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/encodeState#encodestate}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/encodeState#encodestate}
  */
 export declare function encodeState<T extends JSONCompatible>(state: T, defaults?: T, paramsToKeep?: string | URLSearchParams): string;
 /**
@@ -27,6 +27,6 @@ export declare function encodeState<T extends JSONCompatible>(state: T, defaults
  * decodeState('key=value&name=Alex', form);
  *  ```
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/encodeState#decodestate}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/encodeState#decodestate}
  */
 export declare function decodeState<T extends JSONCompatible>(uriString: string | URLSearchParams, defaults?: T): undefined extends T ? UnknownObj : T;

package/dist/encoder/encoder.d.ts

@@ -5,7 +5,7 @@ import { type JSONCompatible } from '../utils';
  * @param {unknown} payload any value to serialize
  * @returns {string} URLSearchParams compatible value string
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/encoder#encode}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/encoder#encode}
  */
 export declare function encode(payload: unknown): string;
 export declare const replacer: (_key: string, value: unknown) => unknown;
@@ -17,7 +17,7 @@ export type Primitive = Exclude<ReturnType<typeof decodePrimitive>, typeof error
  * @param {any} fallback optional fallback value
  * @returns {unknown} decoded object
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/encoder#decode}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/encoder#decode}
  */
 export declare function decode<T>(payload: string, fallback?: T): JSONCompatible | Primitive;
 export declare const decodePrimitive: (str: string) => string | number | boolean | Date | typeof errorSym | null | undefined;
@@ -30,6 +30,6 @@ export declare const reviver: (_key: string, value: unknown) => unknown;
  * @param {T} [fallbackValue] - The fallback value to use if parsing fails.
  * @return {T | Primitive | undefined} - The parsed object or a primitive value, or undefined if parsing fails.
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url}
  */
 export declare function parseJSON<T extends JSONCompatible>(jsonString: string, fallbackValue?: T): T | Primitive | undefined;

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { decode, encode } from './encoder';
 import { decodeState, encodeState } from './encodeState';
-import { parseSsrQs, useUrlState } from './next';
+import { parseSPObj, useUrlState } from './next';
 import { useSharedState } from './useSharedState';
 import { useUrlEncode } from './useUrlEncode';
 import { useUrlStateBase } from './useUrlStateBase';
 import { isSSR, type JSONCompatible, type Type, typeOf } from './utils';
-export { decode, decodeState, encode, encodeState, isSSR, parseSsrQs, typeOf, useSharedState, useUrlEncode, useUrlState, useUrlStateBase, };
+export { decode, decodeState, encode, encodeState, isSSR, parseSPObj, typeOf, useSharedState, useUrlEncode, useUrlState, useUrlStateBase, };
 export type { JSONCompatible, Type };

package/dist/index.mjs

@@ -1 +1 @@
-export{decode,encode}from"./encoder/encoder.mjs";export{decodeState,encodeState}from"./encodeState/encodeState.mjs";export{parseSsrQs}from"./next/parseSsrQs.mjs";export{useUrlState}from"./next/useUrlState/useUrlState.mjs";export{useSharedState}from"./useSharedState/useSharedState.mjs";export{useUrlEncode}from"./useUrlEncode/useUrlEncode.mjs";export{useUrlStateBase}from"./useUrlStateBase/useUrlStateBase.mjs";export{isSSR,typeOf}from"./utils.mjs";
+export{decode,encode}from"./encoder/encoder.mjs";export{decodeState,encodeState}from"./encodeState/encodeState.mjs";export{parseSPObj}from"./next/parseSPObj.mjs";export{useUrlState}from"./next/useUrlState/useUrlState.mjs";export{useSharedState}from"./useSharedState/useSharedState.mjs";export{useUrlEncode}from"./useUrlEncode/useUrlEncode.mjs";export{useUrlStateBase}from"./useUrlStateBase/useUrlStateBase.mjs";export{isSSR,typeOf}from"./utils.mjs";

package/dist/next/index.d.ts

@@ -1,2 +1,2 @@
-export { parseSsrQs } from './parseSsrQs';
+export { parseSPObj } from './parseSPObj';
 export { useUrlState } from './useUrlState';

package/dist/next/index.mjs

@@ -1 +1 @@
-export{parseSsrQs}from"./parseSsrQs.mjs";export{useUrlState}from"./useUrlState/useUrlState.mjs";
+export{parseSPObj}from"./parseSPObj.mjs";export{useUrlState}from"./useUrlState/useUrlState.mjs";

package/dist/next/{parseSsrQs.d.ts → parseSPObj.d.ts}

@@ -6,4 +6,4 @@ import { type JSONCompatible } from '../utils';
  * @param {T} defaults - The default values to use if parsing fails.
  * @return {T} - The parsed object or the default values.
  */
-export declare function parseSsrQs<T extends JSONCompatible>(sp: object | undefined, defaults: T): T;
+export declare function parseSPObj<T extends JSONCompatible>(sp: object | undefined, defaults: T): T;

package/dist/next/{parseSsrQs.mjs → parseSPObj.mjs}

@@ -1 +1 @@
-import{decodePrimitive as r,errorSym as t,decode as n}from"../encoder/encoder.mjs";function e(r,t){return{...t,...o(JSON.stringify(r),t)}}function o(n,e){try{return JSON.parse(n,c)}catch{const o=r(n);return o!==t?o:e}}const c=(r,t)=>{const e="string"==typeof t,o=e&&n(t?.replaceAll?.("'",'"'));return r&&e?o:t};export{e as parseSsrQs};
+import{decodePrimitive as r,errorSym as t,decode as n}from"../encoder/encoder.mjs";function e(r,t){return{...t,...o(JSON.stringify(r),t)}}function o(n,e){try{return JSON.parse(n,c)}catch{const o=r(n);return o!==t?o:e}}const c=(r,t)=>{const e="string"==typeof t,o=e&&n(t?.replaceAll?.("'",'"'));return r&&e?o:t};export{e as parseSPObj};

package/dist/next/useUrlState/useUrlState.d.ts

@@ -21,7 +21,7 @@ import { type DeepReadonly, type JSONCompatible } from '../../utils';
  * updateUrl(curr => ({ ...curr, name: 'test' }), { replace: true, scroll: true });
  *  ```
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/next/useUrlState#api}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/next/useUrlState#api}
  */
 export declare function useUrlState<T extends JSONCompatible>(defaultState: T, searchParams?: object): {
     state: DeepReadonly<T>;
@@ -49,7 +49,7 @@ export declare function useUrlState<T extends JSONCompatible>(defaultState: T, s
  * updateUrl(curr => ({ ...curr, name: 'test' }), { replace: true, scroll: true });
  *  ```
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/next/useUrlState#api}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/next/useUrlState#api}
  */
 export declare function useUrlState<T extends JSONCompatible>({ defaultState, searchParams, }: {
     defaultState: T;

package/dist/next/useUrlState/useUrlState.mjs

@@ -1 +1 @@
-import{useRouter as t,useSearchParams as e}from"next/navigation";import a from"react";import{parseSsrQs as r}from"../parseSsrQs.mjs";import{useUrlStateBase as s}from"../../useUrlStateBase/useUrlStateBase.mjs";function c(c,l){const{_defaultState:n,_searchParams:u,_replace:o}=function(t,e){const a="defaultState"in t?t.defaultState:t,r="defaultState"in t?t.searchParams:e,s="defaultState"in t&&(t.replace??!0);return{_defaultState:a,_searchParams:r,_replace:s}}(c,l),f=t(),{state:i,updateState:m,updateUrl:p,getState:S}=s(n,f,u),d=a.useCallback(((t,e)=>{const a={scroll:!1,replace:o,...e};p(t,a)}),[p,o]),_=e();return a.useEffect((()=>{const t=Object.keys(n),e=Object.fromEntries([..._.entries()].filter((([e])=>t.includes(e))));m(r(e,n))}),[_]),{updateState:m,updateUrl:d,state:i,getState:S}}export{c as useUrlState};
+import{useRouter as t,useSearchParams as e}from"next/navigation";import a from"react";import{parseSPObj as r}from"../parseSPObj.mjs";import{useUrlStateBase as s}from"../../useUrlStateBase/useUrlStateBase.mjs";import{isSSR as c,filterUnknownParamsClient as l}from"../../utils.mjs";function n(n,o){const{_defaultState:u,_searchParams:i,_replace:f}=function(t,e){const a="defaultState"in t?t.defaultState:t,r="defaultState"in t?t.searchParams:e,s="defaultState"in t&&(t.replace??!0);return{_defaultState:a,_searchParams:r,_replace:s}}(n,o),m=t(),{state:p,updateState:S,updateUrl:d,getState:j}=s(u,m,(({parse:t})=>c()?r(function(t,e){const a=Object.keys(t),r=Object.fromEntries(Object.entries(e||{}).map((([t,e])=>[t.replaceAll("+"," "),e])).filter((([t])=>a.includes(t))));return r}(u,i),u):t(l(u)))),b=a.useCallback(((t,e)=>{const a={scroll:!1,replace:f,...e};d(t,a)}),[d,f]),O=e();return a.useEffect((()=>{const t=Object.keys(u),e=Object.fromEntries([...O.entries()].filter((([e])=>t.includes(e))));S(r(e,u))}),[O]),{updateState:S,updateUrl:b,state:p,getState:j}}export{n as useUrlState};

package/dist/useSharedState/useSharedState.d.ts

@@ -15,7 +15,7 @@ import { type DeepReadonly, type JSONCompatible } from '../utils';
  * // OR
  * setState(curr => ({ ...curr, name: 'test' }))
  *  ```
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useSharedState}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useSharedState}
  */
 export declare function useSharedState<T extends JSONCompatible>(defaultState: T, _getInitial?: () => T): {
     state: T;

package/dist/useUrlEncode/useUrlEncode.d.ts

@@ -17,7 +17,7 @@ import { type JSONCompatible } from '../utils';
  * parse('name=Tom');
  *  ```
  *
- * * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useUrlEncode#api}
+ * * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useUrlEncode#api}
  */
 export declare function useUrlEncode<T extends JSONCompatible>(stateShape: T): {
     /**
@@ -28,7 +28,7 @@ const state = parse('name=◖Tom');
 console.log(state); // Output: { name: 'Tom' }
  *  ```
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useUrlEncode#parse}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useUrlEncode#parse}
  */
     parse: (strOrSearchParams: string | URLSearchParams) => T;
     /**
@@ -39,7 +39,7 @@ const queryString = stringify({ name: 'John' }, 'someExistingParamToKeep=123');
 console.log(queryString); // Output: name=◖John&someExistingParamToKeep=123
 *  ```
 *
-*  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useUrlEncode#stringify}
+*  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useUrlEncode#stringify}
 */
     stringify: (state: typeof stateShape, paramsToKeep?: string | URLSearchParams) => string;
 };

package/dist/useUrlStateBase/useUrlStateBase.d.ts

@@ -1,21 +1,29 @@
+import { useUrlEncode } from '../useUrlEncode';
 import { type DeepReadonly, type JSONCompatible } from '../utils';
 /**
- * Base hook to integrate it with different routers
+ * A custom React hook to create custom hooks.
+ *
+ * @template T extends JSONCompatible
+ * @param {T} defaultState - An object representing the default state values.
+ * @param {Router} router - Router object with [push] and [replace] methods.
+ * @param {Function} [getInitialState] - Optional function to get the initial state, passes `parse`, and `filterUnknownParams` helpers
+ * @returns {Object} An object containing `state`, `getState`, `updateState`, and `updateUrl` properties.
  *
- * @param {JSONCompatible<T>} [defaultState] Fallback (default) values for state
- * @param {Router} [router] Router object with `push` and `replace` methods
- * @param {?SearchParams<T>} [searchParams] searchParams from Next server component
  *
  * * Example:
  * ```ts
  * export const form = { name: '' };
  * const router = { push: () => {}, replace: () => {} };
- * const { state, updateState, updateUrl } = useUrlStateBase(form, router, sp);
+ * const { state, updateState, updateUrl } = useUrlStateBase(form, router, ({ parse, filterClientSP }) =>
+ *   isSSR() ? getServerState() : getClientState()
+ * );
  *  ```
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/integrations/packages/urlstate/useUrlStateBase#api}
+ * * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/integrations/packages/urlstate/useUrlStateBase#api}
  */
-export declare function useUrlStateBase<T extends JSONCompatible>(defaultState: T, router: Router, searchParams?: object): {
+export declare function useUrlStateBase<T extends JSONCompatible>(defaultState: T, router: Router, getInitialState?: ({ parse, }: {
+    parse: ReturnType<typeof useUrlEncode<T>>['parse'];
+}) => T): {
     updateState: (value: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T)) => void;
     updateUrl: (value?: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T) | undefined, options?: Options) => void;
     state: DeepReadonly<T>;

package/dist/useUrlStateBase/useUrlStateBase.mjs

@@ -1 +1 @@
-import t from"react";import{parseSsrQs as e}from"../next/parseSsrQs.mjs";import{useInsertionEffect as n}from"../useInsertionEffect.mjs";import{useSharedState as o}from"../useSharedState/useSharedState.mjs";import{useUrlEncode as r}from"../useUrlEncode/useUrlEncode.mjs";import{isSSR as s}from"../utils.mjs";function a(a,m,l){const{parse:u,stringify:w}=r(a),{state:f,getState:p,setState:d}=o(a,(()=>s()?e(function(t,e){const n=Object.keys(t),o=Object.fromEntries(Object.entries(e||{}).map((([t,e])=>[t.replaceAll("+"," "),e])).filter((([t])=>n.includes(t))));return o}(a,l),a):u(c(a))));n((()=>{const t=()=>{const t=u(c(a));d(t)};return window.addEventListener(i,t),()=>{window.removeEventListener(i,t)}}),[d]);const h=t.useCallback(((t,e)=>{const n=`${window.location.pathname}${window.location.search}${window.location.hash}`,o="function"==typeof t,r=function(t){const e=Object.keys(t),n=window.location.search,o=new URLSearchParams(n),r=new URLSearchParams;return o.forEach(((t,n)=>!e.includes(n)&&r.set(n,t))),r}(a),s=o?t(p()):t?{...p(),...t}:p(),c=w(s,r);d(s);const i=`${window.location.pathname}${c.length?"?":""}${c}${window.location.hash}`;if(n!==i){const{replace:t,...n}=e||{};m[t?"replace":"push"](i,{...n})}}),[m,w,p]);return{updateState:d,updateUrl:h,state:f,getState:p}}function c(t){const e=new URLSearchParams(window.location.search),n=Object.keys(t),o=new URLSearchParams;return[...e.entries()].filter((([t])=>n.includes(t))).forEach((([t,e])=>o.set(t,e))),o.toString()}const i="popstate";export{a as useUrlStateBase};
+import t from"react";import{useInsertionEffect as e}from"../useInsertionEffect.mjs";import{useSharedState as o}from"../useSharedState/useSharedState.mjs";import{useUrlEncode as n}from"../useUrlEncode/useUrlEncode.mjs";import{filterUnknownParamsClient as a}from"../utils.mjs";function s(s,c,i){const{parse:m,stringify:p}=n(s),{state:w,getState:d,setState:u}=o(s,(()=>i?.({parse:m})||s));e((()=>{const t=()=>{const t=m(a(s));u(t)};return window.addEventListener(r,t),()=>{window.removeEventListener(r,t)}}),[u]);const l=t.useCallback(((t,e)=>{const o=`${window.location.pathname}${window.location.search}${window.location.hash}`,n="function"==typeof t,a=function(t){const e=Object.keys(t),o=window.location.search,n=new URLSearchParams(o),a=new URLSearchParams;return n.forEach(((t,o)=>!e.includes(o)&&a.set(o,t))),a}(s),r=n?t(d()):t?{...d(),...t}:d(),i=p(r,a);u(r);const m=`${window.location.pathname}${i.length?"?":""}${i}${window.location.hash}`;if(o!==m){const{replace:t,...o}=e||{};c[t?"replace":"push"](m,{...o})}}),[c,p,d]);return{updateState:u,updateUrl:l,state:w,getState:d}}const r="popstate";export{s as useUrlStateBase};

package/dist/utils.d.ts

@@ -23,3 +23,4 @@ export type UnknownObj = {
     [key: string]: unknown;
 };
 export declare const isEqual: (val1: unknown, val2: unknown) => boolean;
+export declare function filterUnknownParamsClient<T extends object>(shape: T): string;

package/dist/utils.mjs

@@ -1 +1 @@
-const t=t=>{const n=typeof t,r=null===t,e=Array.isArray(t),i=t instanceof Date;return(r?"null":i&&"date")||e&&"array"||!r&&!i&&!e&&"object"===n&&"object"||n},n=()=>"undefined"==typeof window,r=t=>new URLSearchParams("string"==typeof t?e(t):t?.toString?.()||""),e=t=>t.split("?")?.[1]||t||"",i=(t,n)=>JSON.stringify(t)===JSON.stringify(n);export{r as getParams,i as isEqual,n as isSSR,t as typeOf};
+const t=t=>{const e=typeof t,n=null===t,r=Array.isArray(t),a=t instanceof Date;return(n?"null":a&&"date")||r&&"array"||!n&&!a&&!r&&"object"===e&&"object"||e},e=()=>"undefined"==typeof window,n=t=>new URLSearchParams("string"==typeof t?r(t):t?.toString?.()||""),r=t=>t.split("?")?.[1]||t||"",a=(t,e)=>JSON.stringify(t)===JSON.stringify(e);function i(t){const e=new URLSearchParams(window.location.search),n=Object.keys(t),r=new URLSearchParams;return[...e.entries()].filter((([t])=>n.includes(t))).forEach((([t,e])=>r.set(t,e))),r.toString()}export{i as filterUnknownParamsClient,n as getParams,a as isEqual,e as isSSR,t as typeOf};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "Library to store state in browser URL, includes hook for NextJS, hook for pure React, and low level helpers.",
   "homepage": "https://github.com/asmyshlyaev177/state-in-url#readme",
   "keywords": [