state-in-url 0.1.6 → 0.1.7

package/README.md

@@ -6,13 +6,28 @@
   <img src="/assets/logo.svg?raw=true" alt="Library logo"/>
 </p>
 
+
+<div align="center">
+  
+[![For hire](/assets/hireBadge.svg)](https://www.linkedin.com/in/asmyshlyaev177/)
+
+
+[![npm](https://img.shields.io/npm/v/state-in-url.svg)](https://www.npmjs.com/package/state-in-url)
+![Tests](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml/badge.svg?branch=main)
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](https://github.com/asmyshlyaev177/state-in-url/)
+![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/state-in-url.svg)
+</div>
+
 <div align="center">
 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>
 
 
-<a href="https://state-in-url-wine.vercel.app" target="_blank">DEMO</a>
+https://github.com/asmyshlyaev177/state-in-url/assets/19854148/10456887-f149-4745-b3f1-e799e70b16cd
+
+
+<a href="https://state-in-url-asmyshlyaev177.vercel.app/" target="_blank">DEMO</a>
 
 
 <hr />
@@ -21,32 +36,33 @@ Add a ⭐️ to support the project!
 
   <hr />
 
+  </div>
 
-[![For hire](/assets/hireBadge.svg)](https://www.linkedin.com/in/asmyshlyaev177/)
-
+  ## Why use state-in-url?
 
-[![npm](https://img.shields.io/npm/v/state-in-url.svg)](https://www.npmjs.com/package/state-in-url)
-![Tests](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml/badge.svg?branch=main)
-[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](https://github.com/asmyshlyaev177/state-in-url/)
-![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/state-in-url.svg)
+`state-in-url` lets you use URI string for state management.
 
-  </div>
+# Use cases
+- 🔗 Shareable URLs with full application state
+- 🔄 Easy state persistence across page reloads
+- 🧠 Pass data between unrelated client components
+- 🧮 Store unsaved user forms in URL
 
 # Features
-- **Seamless state synchronization with URL query parameters.**
-- **Preserves shape and types of data**
-- **Full TypeScript support for enhanced developer experience.**
-- **Automatic serialization and deserialization of complex objects.**
-- **Separate hooks for Next.js (useUrlState) and React.js (useUrlEncode) usage.**
-- **Efficient updates with minimal re-renders.**
-- **Lightweight, no dependencies.**
+- 🧩 **Simple**: Handles complex objects without extra effort
+- 📘 **Typescript support and type Safety**: Preserves data types and structure, enhances developer experience with strong typing and JSDoc comments
+- ⚛️ **Framework Flexibility**: Separate hooks for Next.js and React.js applications, and functions for pure JS
+- 🪶 **Lightweight**: Zero dependencies for a smaller footprint
+
 
 ## Table of content
 - [Installation](#installation)
 - [`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)
+- [auto sync state with url](#auto-sync-state)
 - [Low-level `encode` and `decode` functions](#encode-and-decode-helpers)
+- [Best practices](#best-practices)
 - [Gothas](#gothas)
 - [Contact & Support](#contact--support)
 - [Changelog](#changelog)
@@ -63,12 +79,6 @@ yarn add state-in-url
 pnpm add state-in-url
 ```
 
-## Run locally
-Clone this repo, run `npm install` and
-```sh
-npm run dev
-```
-Go to [localhost:3000](http://localhost:3000)
 
 ## useUrlState hook for Next.js
 
@@ -103,6 +113,7 @@ function MyComponent() {
       <button onClick={() => updateState({ count: state.count + 1 })}>
         Increment (Local Only)
       </button>
+
       <button onClick={() => updateUrl(state)}>
         Sync changes to url
       </button>
@@ -164,6 +175,23 @@ function Component() {
 }
 ```
 
+#### Auto sync state
+
+```typescript
+  const timer = React.useRef(0 as unknown as NodeJS.Timeout);
+  React.useEffect(() => {
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => {
+      // will compare state by content not by reference and fire update only for new values 
+      updateUrl(state);
+    }, 500);
+
+    return () => {
+      clearTimeout(timer.current);
+    };
+  }, [state, updateUrl]);
+```
+
 #### With arbitrary state shape (not recommended)
 
 ```typescript
@@ -248,9 +276,25 @@ const obj = Object.fromEntries(
 )
 ```
 
+## Best Practices
+
+- Define your state shape as a constant to ensure consistency
+- Use TypeScript for enhanced type safety and autocomplete
+- Avoid storing sensitive information in URL parameters
+- Use `updateState` for frequent updates and `updateUrl` to sync changes to url
+
 ## Gothas
 
 1. Can pass only serializable values, `Function`, `BigInt` or `Symbol` won't work, probably things like `ArrayBuffer` neither.
+2. Vercel servers limit size of headers (query string and other stuff) to **14KB**, so keep your URL state under ~5000 words. https://vercel.com/docs/errors/URL_TOO_LONG
+
+## Run locally
+Clone this repo, run `npm install` and
+```sh
+npm run dev
+```
+Go to [localhost:3000](http://localhost:3000)
+
 
 ## Contact & Support
 

package/dist/index.js

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

package/dist/urlstate/encodeState.d.ts

@@ -11,6 +11,8 @@ import { type JSONCompatible, type UnknownObj } from './utils';
  * export const form = { name: '' };
  * encodeState({ name: 'test' }, form, 'someExistingParam=123');
  *  ```
+ *
+ *  * Github {@link https://github.com/asmyshlyaev177/state-in-url}
  */
 export declare function encodeState<T>(state: never extends T ? object : JSONCompatible<T>, defaults?: JSONCompatible<T>, paramsToKeep?: string | URLSearchParams): string;
 /**
@@ -24,5 +26,7 @@ export declare function encodeState<T>(state: never extends T ? object : JSONCom
  * export const form = { name: '' };
  * decodeState('key=value&name=Alex', form);
  *  ```
+ *
+ *  * Github {@link https://github.com/asmyshlyaev177/state-in-url}
  */
 export declare function decodeState<T>(uriString: string | URLSearchParams, defaults?: JSONCompatible<T>): undefined extends T ? UnknownObj : T;

package/dist/urlstate/encoder.d.ts

@@ -3,6 +3,8 @@
  *
  * @param {unknown} payload any value to serialize
  * @returns {string} URLSearchParams compatible value string
+ *
+ *  * Github {@link https://github.com/asmyshlyaev177/state-in-url}
  */
 export declare function encode(payload: unknown): string;
 type Primitive = Exclude<ReturnType<typeof decodePrimitive>, typeof errorSym>;
@@ -14,6 +16,8 @@ export declare const errorSym: unique symbol;
  * @param {string} jsonString - The JSON string to parse.
  * @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}
  */
 export declare function parseJSON<T>(jsonString: string, fallbackValue?: T): T | Primitive | undefined;
 /**
@@ -22,6 +26,8 @@ export declare function parseJSON<T>(jsonString: string, fallbackValue?: T): T |
  * @param {string} payload URLSearchParams compatible value string
  * @param {any} fallback optional fallback value
  * @returns {unknown} decoded object
+ *
+ *  * Github {@link https://github.com/asmyshlyaev177/state-in-url}
  */
 export declare function decode<T>(payload: string, fallback?: T): Primitive | T;
 export {};

package/dist/urlstate/useUrlEncode.d.ts

@@ -16,6 +16,8 @@ import { type JSONCompatible, type DeepReadonly } from './utils';
  * // by default it's uses router.push with scroll: false
  * parse('name=Tom');
  *  ```
+ *
+ * * Github {@link https://github.com/asmyshlyaev177/state-in-url}
  */
 export declare function useUrlEncode<T>(stateShape?: JSONCompatible<T>): {
     parse: (strOrSearchParams: string | URLSearchParams) => undefined extends T ? Readonly<{

package/dist/urlstate/useUrlState.d.ts

@@ -14,20 +14,8 @@ import { type JSONCompatible } from './utils';
  * // 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]);
- * ```
+ *  * Github {@link https://github.com/asmyshlyaev177/state-in-url}
  */
 export declare function useUrlState<T>(defaultState?: JSONCompatible<T>): {
     updateUrl: (value: (undefined extends T ? Readonly<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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": [