state-in-url 0.1.3 → 0.1.5

package/README.md

@@ -7,7 +7,7 @@
 </p>
 
 <div align="center">
-Seamlessly sync React state with URL query parameters in Next.js/React.js applications. Simplify state management, enhance shareability, and maintain type safety—all through your browser's URL.
+Seamlessly store complex React state object in URL query parameters without losing types. Works with Next.js/React.js applications.
 
 <h4 align="center">Don't hesitate to open issue if you found a bug</h4>
 
@@ -43,9 +43,10 @@ Add a ⭐️ to support the project!
 
 ## Table of content
 - [Installation](#installation)
-- [Usage with Next.js](#useurlstate-hook-for-nextjs)
-- [Usage with React.js](#useurlencode-hook-for-reactjs)
-- [Low-level encode/decode functions](#encode-and-decode-helpers)
+- [`useUrlState` for Next.js](#useurlstate-hook-for-nextjs)
+- [`useUrlEncode` for React.js](#useurlencode-hook-for-reactjs)
+- [`encodeState` and `decodeState` for pure JS usage](#encodestate-and-decodestate-helpers)
+- [Low-level `encode` and `decode` functions](#encode-and-decode-helpers)
 - [Gothas](#gothas)
 - [Contact & Support](#contact--support)
 - [Changelog](#changelog)
@@ -71,7 +72,7 @@ Go to [localhost:3000](http://localhost:3000)
 
 ## useUrlState hook for Next.js
 
-`useUrlState` is a custom React hook for Next.js applications that manages state in the URL query string. It allows you to store and retrieve state from the URL search parameters, providing a way to persist state across page reloads and share application state via URLs.
+`useUrlState` is a custom React hook for Next.js applications that make communication between client components easy. It allows you to store and retrieve state from the URL search parameters, providing a way to persist state across page reloads and share application state via URLs.
 
 
 ### Usage examples
@@ -178,7 +179,7 @@ function SettingsComponent() {
 
 ## useUrlEncode hook for React.js
 
-`useUrlEncode` is a custom React hook that provides utility functions for encoding and decoding state to and from URL search parameters. This hook doesn't depend on Nextjs, and will works with any React application.
+`useUrlEncode` is a custom React hook that provides utility functions for encoding and decoding state object to and from URL search parameters. This hook doesn't depend on Nextjs, and will works with any React application.
 
 Accepts optional `defaultState` argument.
 
@@ -205,6 +206,22 @@ const Component = () => {
 }
 ```
 
+## `encodeState` and `decodeState` helpers
+
+`encodeState` let you encode some object with optional `defaults`, and optional existing queryString
+```ts
+ export const form = { name: '' };
+...
+ encodeState({ name: 'test' }, form, 'someExistingParam=123');
+```
+
+`decodeState` let you decode queryString with optional defaults
+```ts
+ export const form = { name: '' };
+...
+ decodeState('name=Alex', form);
+```
+
 ## `encode` and `decode` helpers
 
 There low level helpers to stringify and parse query string params. Useful for other frameworks or pure JS.

package/dist/index.d.ts

@@ -1 +1 @@
-export { encode, decode, type Type, useUrlEncode, useUrlState, } from './urlstate';
+export { encodeState, decodeState, encode, decode, type Type, useUrlEncode, useUrlState, } from './urlstate';

package/dist/index.js

@@ -1 +1 @@
-import e from"react";import{useRouter as t,usePathname as n,useSearchParams as r}from"next/navigation";const c=e=>{const t=null===e,n=Array.isArray(e),r=e instanceof Date;return(t?"null":r&&"date")||n&&"array"||!t&&!r&&!n&&"object"==typeof e&&"object"||typeof e},a={boolean:"🗵",null:"∙null",undefined:"∙undefined",number:"∓",date:"⏲"};function o(e){switch(c(e)){case"function":case"symbol":return"";case"date":return a.date+e.toISOString();case"string":return encodeURIComponent(e);case"number":return a.number+String(e);case"boolean":return a.boolean+String(e);case"object":case"array":return s(e);case"null":return a.null;case"undefined":return a.undefined;default:return String(e)}}const s=e=>JSON.stringify(e,u).replaceAll('"',"'"),u=(e,t)=>{const n=c(t);return e&&"object"!==n&&"array"!==n?o(t):t},i=e=>e.match(/^∓/)?Number.parseFloat(e.replaceAll("∓","")):e.match(/^🗵/)?!!e.includes("true"):e.match(/^⏲/)?new Date(e.slice(1)):e===a.null?null:e!==a.undefined?decodeURIComponent(e):void 0,l=(e,t)=>e&&"string"==typeof t?i(t):t,f=e=>{let t;try{t=JSON.parse(e,l)}catch{}return t};function p(e){const t=e.replaceAll("'",'"');return f(t)??i(e)}function d(t){const n=e.useCallback((function(e,n){const r=g(n);return"object"===c(e)&&Object.entries(e).forEach((([e,n])=>{const c=t?.[e];JSON.stringify(n)!==JSON.stringify(c)?r.set(e,o(n)):r.delete(e)})),r.toString()}),[t]);return{parse:e.useCallback((function(e){const n=g(e);return{...t,...Object.fromEntries([...n.entries()].map((([e,n])=>[e,p(n)??t?.[e]])))}}),[t]),stringify:n}}const g=e=>new URLSearchParams("string"==typeof e?e:e?.toString?.()||"");function y(c){const a=t(),o=n(),{parse:s,stringify:u}=d(c),i=r(),[l,f]=e.useState((()=>s(i)));e.useEffect((()=>{f((e=>{const t=s(i);return JSON.stringify(e)===JSON.stringify(t)?e:t}))}),[s,i]);const p=e.useCallback((e=>{f("function"==typeof e?t=>e(t):e)}),[]);return{updateUrl:e.useCallback(((e,t)=>{const n=i.toString(),r=`${o}${n.length?"?":""}${n}`,c=u("function"==typeof e?e(l):e),s=`${o}${c.length?"?":""}${c}`;if(r!==s){const{replace:e,...n}=t||{};a[e?"replace":"push"](s,{scroll:!1,...n})}}),[o,a,u,i,l]),updateState:p,state:l}}export{p as decode,o as encode,d as useUrlEncode,y as useUrlState};
+import e from"react";import{useRouter as t,usePathname as n,useSearchParams as r}from"next/navigation";const c=e=>{const t=null===e,n=Array.isArray(e),r=e instanceof Date;return(t?"null":r&&"date")||n&&"array"||!t&&!r&&!n&&"object"==typeof e&&"object"||typeof e},a=e=>new URLSearchParams("string"==typeof e?e:e?.toString?.()||""),o={boolean:"🗵",null:"∙null",undefined:"∙undefined",number:"∓",date:"⏲"};function u(e){switch(c(e)){case"function":case"symbol":return"";case"date":return o.date+e.toISOString();case"string":return encodeURIComponent(e);case"number":return o.number+String(e);case"boolean":return o.boolean+String(e);case"object":case"array":return s(e);case"null":return o.null;case"undefined":return o.undefined;default:return String(e)}}const s=e=>JSON.stringify(e,i).replaceAll('"',"'"),i=(e,t)=>{const n=c(t);return e&&"object"!==n&&"array"!==n?u(t):t},l=e=>e.match(/^∓/)?Number.parseFloat(e.replaceAll("∓","")):e.match(/^🗵/)?!!e.includes("true"):e.match(/^⏲/)?new Date(e.slice(1)):e===o.null?null:e!==o.undefined?decodeURIComponent(e):void 0,f=(e,t)=>e&&"string"==typeof t?l(t):t,p=e=>{let t;try{t=JSON.parse(e,f)}catch{}return t};function d(e){const t=e.replaceAll("'",'"');return p(t)??l(e)}function g(e,t,n){const r=a(n);return Object.entries(e||{}).forEach((([e,n])=>{const c=t?.[e];JSON.stringify(n)!==JSON.stringify(c)&&r.set(e,u(n))})),r.toString()}function y(e,t){return{...t||{},...Object.fromEntries([...a(e).entries()].map((([e,n])=>[e,d(n)??t?.[e]])))}}function b(t){const n=e.useCallback((function(e,n){return"object"===c(e)?g(e,t,n):""}),[t]);return{parse:e.useCallback((function(e){return y(e,t)}),[t]),stringify:n}}function m(c){const a=t(),o=n(),{parse:u,stringify:s}=b(c),i=r(),[l,f]=e.useState((()=>u(i)));e.useEffect((()=>{f((e=>{const t=u(i);return JSON.stringify(e)===JSON.stringify(t)?e:t}))}),[u,i]);const p=e.useCallback((e=>{f("function"==typeof e?t=>e(t):e)}),[]);return{updateUrl:e.useCallback(((e,t)=>{const n=i.toString(),r=`${o}${n.length?"?":""}${n}`,c=s("function"==typeof e?e(l):e),u=`${o}${c.length?"?":""}${c}`;if(r!==u){const{replace:e,...n}=t||{};a[e?"replace":"push"](u,{scroll:!1,...n})}}),[o,a,s,i,l]),updateState:p,state:l}}export{d as decode,y as decodeState,u as encode,g as encodeState,b as useUrlEncode,m as useUrlState};

package/dist/urlstate/encodeState.d.ts

@@ -0,0 +1,28 @@
+import { type JSONCompatible } from './utils';
+/**
+ * Encodes the state object into a URL query string.
+ *
+ * @param {JSONCompatible<T>} state - The state object to encode.
+ * @param {JSONCompatible<T>} [defaults] - Optional default values for the state object.
+ * @return {string} The encoded URL query string representing the state object.
+ *
+ *  * Example:
+ * ```ts
+ * export const form = { name: '' };
+ * encodeState({ name: 'test' }, form, 'someExistingParam=123');
+ *  ```
+ */
+export declare function encodeState<T>(state: never extends T ? object : JSONCompatible<T>, defaults?: JSONCompatible<T>, paramsToKeep?: string | URLSearchParams): string;
+/**
+ * Decodes a URI string into an object of type T.
+ *
+ * @param {string} uriString - The URI string to decode.
+ * @return {T} The decoded object of type T.
+ *
+ *  * Example:
+ * ```ts
+ * export const form = { name: '' };
+ * decodeState('key=value&name=Alex', form);
+ *  ```
+ */
+export declare function decodeState<T>(uriString: string | URLSearchParams, defaults?: never extends T ? object : JSONCompatible<T>): never extends T ? object : T;

package/dist/urlstate/index.d.ts

@@ -2,5 +2,6 @@ import { encode, decode } from './encoder';
 import { type Type, type JSONCompatible, typeOf } from './utils';
 import { useUrlEncode } from './useUrlEncode';
 import { useUrlState } from './useUrlState';
-export { encode, decode, typeOf, useUrlEncode, useUrlState };
+import { encodeState, decodeState } from './encodeState';
+export { encode, decode, typeOf, useUrlEncode, useUrlState, encodeState, decodeState, };
 export type { Type, JSONCompatible };

package/dist/urlstate/useUrlEncode.d.ts

@@ -1,10 +1,23 @@
 import { type JSONCompatible, type DeepReadonly } from './utils';
 /**
- * Returns stringify and parse functions
+ * A hook that returns stringify and parse functions for encoding and decoding state
+ * to and from URL search parameters.
  *
- * @param {?JSONCompatible<T>} [stateShape] Optional fallback values for state
+ * @template T - The type of the state shape
+ * @param {JSONCompatible<T>} [stateShape] Optional fallback values for state
+ * @returns {} `stringify` and `parse` functions
+ *
+ * * Example:
+ * ```ts
+ * export const form = { name: '' };
+ * const { parse, stringify } = useUrlEncode(form);
+ *
+ * stringify({ name: 'John' }, 'someExistingParamToKeep=123');
+ * // by default it's uses router.push with scroll: false
+ * parse('name=Tom');
+ *  ```
  */
 export declare function useUrlEncode<T>(stateShape?: JSONCompatible<T>): {
-    parse: (strOrSearchParams?: string | URLSearchParams) => Readonly<JSONCompatible<T> & {} extends infer T ? { readonly [P in keyof T]: Readonly<(JSONCompatible<T> & {})[P] extends infer T_1 ? { readonly [P_1 in keyof T_1]: Readonly<(JSONCompatible<T> & {})[P][P_1] extends infer T_2 ? { readonly [P_2 in keyof T_2]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2] extends infer T_3 ? { readonly [P_3 in keyof T_3]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3] extends infer T_4 ? { readonly [P_4 in keyof T_4]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4] extends infer T_5 ? { readonly [P_5 in keyof T_5]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5] extends infer T_6 ? { readonly [P_6 in keyof T_6]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6] extends infer T_7 ? { readonly [P_7 in keyof T_7]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7] extends infer T_8 ? { readonly [P_8 in keyof T_8]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7][P_8] extends infer T_9 ? { readonly [P_9 in keyof T_9]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7][P_8][P_9] extends infer T_10 ? { readonly [P_10 in keyof T_10]: Readonly<any>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>;
-    stringify: (state: DeepReadonly<NonNullable<typeof stateShape>> | NonNullable<typeof stateShape>, strOrSearchParams?: string | URLSearchParams) => string;
+    parse: (strOrSearchParams: string | URLSearchParams) => Readonly<JSONCompatible<T> & {} extends infer T ? { readonly [P in keyof T]: Readonly<(JSONCompatible<T> & {})[P] extends infer T_1 ? { readonly [P_1 in keyof T_1]: Readonly<(JSONCompatible<T> & {})[P][P_1] extends infer T_2 ? { readonly [P_2 in keyof T_2]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2] extends infer T_3 ? { readonly [P_3 in keyof T_3]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3] extends infer T_4 ? { readonly [P_4 in keyof T_4]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4] extends infer T_5 ? { readonly [P_5 in keyof T_5]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5] extends infer T_6 ? { readonly [P_6 in keyof T_6]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6] extends infer T_7 ? { readonly [P_7 in keyof T_7]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7] extends infer T_8 ? { readonly [P_8 in keyof T_8]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7][P_8] extends infer T_9 ? { readonly [P_9 in keyof T_9]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7][P_8][P_9] extends infer T_10 ? { readonly [P_10 in keyof T_10]: Readonly<any>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>;
+    stringify: (state: DeepReadonly<NonNullable<typeof stateShape>> | NonNullable<typeof stateShape>, paramsToKeep?: string | URLSearchParams) => string;
 };

package/dist/urlstate/useUrlState.d.ts

@@ -4,6 +4,30 @@ import { type JSONCompatible } from './utils';
  * NextJS hook. Returns `state`, `updateState`, and `updateUrl` functions
  *
  * @param {?JSONCompatible<T>} [defaultState] Optional fallback values for state
+ *
+ * * Example:
+ * ```ts
+ * export const form = { name: '' };
+ * const { state, updateState, updateUrl } = useUrlState(form);
+ *
+ * updateState({ name: 'test' });
+ * // by default it's uses router.push with scroll: false
+ * updateUrl({ name: 'test' }, { replace: true, scroll: true });
+ *  ```
+ * * Auto update URL
+ * ```ts
+ * const timer = React.useRef(0 as unknown as NodeJS.Timeout);
+ * React.useEffect(() => {
+ *   clearTimeout(timer.current);
+ *   timer.current = setTimeout(() => {
+ *     updateUrl(state);
+ *   }, 500);
+ *
+ *   return () => {
+ *    clearTimeout(timer.current);
+ *   };
+ *  }, [state, updateUrl]);
+ * ```
  */
 export declare function useUrlState<T>(defaultState?: JSONCompatible<T>): {
     updateUrl: (value: Readonly<JSONCompatible<T> & {} extends infer T ? { readonly [P in keyof T]: Readonly<(JSONCompatible<T> & {})[P] extends infer T_1 ? { readonly [P_1 in keyof T_1]: Readonly<(JSONCompatible<T> & {})[P][P_1] extends infer T_2 ? { readonly [P_2 in keyof T_2]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2] extends infer T_3 ? { readonly [P_3 in keyof T_3]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3] extends infer T_4 ? { readonly [P_4 in keyof T_4]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4] extends infer T_5 ? { readonly [P_5 in keyof T_5]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5] extends infer T_6 ? { readonly [P_6 in keyof T_6]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6] extends infer T_7 ? { readonly [P_7 in keyof T_7]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7] extends infer T_8 ? { readonly [P_8 in keyof T_8]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7][P_8] extends infer T_9 ? { readonly [P_9 in keyof T_9]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7][P_8][P_9] extends infer T_10 ? { readonly [P_10 in keyof T_10]: Readonly<any>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never> | ((currState: Readonly<JSONCompatible<T> & {} extends infer T ? { readonly [P in keyof T]: Readonly<(JSONCompatible<T> & {})[P] extends infer T_1 ? { readonly [P_1 in keyof T_1]: Readonly<(JSONCompatible<T> & {})[P][P_1] extends infer T_2 ? { readonly [P_2 in keyof T_2]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2] extends infer T_3 ? { readonly [P_3 in keyof T_3]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3] extends infer T_4 ? { readonly [P_4 in keyof T_4]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4] extends infer T_5 ? { readonly [P_5 in keyof T_5]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5] extends infer T_6 ? { readonly [P_6 in keyof T_6]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6] extends infer T_7 ? { readonly [P_7 in keyof T_7]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7] extends infer T_8 ? { readonly [P_8 in keyof T_8]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7][P_8] extends infer T_9 ? { readonly [P_9 in keyof T_9]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7][P_8][P_9] extends infer T_10 ? { readonly [P_10 in keyof T_10]: Readonly<any>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>) => Readonly<JSONCompatible<T> & {} extends infer T ? { readonly [P in keyof T]: Readonly<(JSONCompatible<T> & {})[P] extends infer T_1 ? { readonly [P_1 in keyof T_1]: Readonly<(JSONCompatible<T> & {})[P][P_1] extends infer T_2 ? { readonly [P_2 in keyof T_2]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2] extends infer T_3 ? { readonly [P_3 in keyof T_3]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3] extends infer T_4 ? { readonly [P_4 in keyof T_4]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4] extends infer T_5 ? { readonly [P_5 in keyof T_5]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5] extends infer T_6 ? { readonly [P_6 in keyof T_6]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6] extends infer T_7 ? { readonly [P_7 in keyof T_7]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7] extends infer T_8 ? { readonly [P_8 in keyof T_8]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7][P_8] extends infer T_9 ? { readonly [P_9 in keyof T_9]: Readonly<(JSONCompatible<T> & {})[P][P_1][P_2][P_3][P_4][P_5][P_6][P_7][P_8][P_9] extends infer T_10 ? { readonly [P_10 in keyof T_10]: Readonly<any>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>; } : never>), options?: Options) => void;

package/dist/urlstate/utils.d.ts

@@ -19,4 +19,5 @@ export type JSONCompatible<T> = unknown extends T ? never : {
 export type DeepReadonly<T> = Readonly<{
     readonly [P in keyof T]: DeepReadonly<T[P]>;
 }>;
+export declare const getParams: (strOrSearchParams?: string | URLSearchParams) => URLSearchParams;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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": [
@@ -73,10 +73,13 @@
     "dev:lib": "wireit",
     "dev:nextjs": "wireit",
     "bump": "npx standard-version --no-verify",
+    "bump:ex": "npm i state-in-url@latest --workspace=packages/example-nextjs",
     "build": "wireit",
     "build:demo": "cd packages/example-nextjs && npx cross-env DEMO=true npm run build",
+    "start:demo": "cd packages/example-nextjs && npm run build && npx serve -s ./out",
     "cleanup": "rm -rf dist",
     "setup": "playwright install --with-deps",
+    "cleanupDist": "wireit",
     "prepare": "npx husky"
   },
   "wireit": {