state-in-url 0.2.6 → 1.0.0

package/README.md

@@ -5,15 +5,13 @@
 <div align="center">
   <img src="/assets/logo.svg?raw=true" alt="Library logo"/>
 
-  <div>Seamlessly store complex nested state object in URL query parameters with IDE autotomplete and TS validation.</div>
+  <div>Easily share state between unrelated React components, with IDE autocomplete and TS validation. Without any hasssle or boilerplate. </div>
 </div>
 
 
 <div align="center">
 <hr />
 
-[![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)
@@ -24,12 +22,13 @@
 
 <div align="center">
 
-<h4 align="center">Don't hesitate to open issue if you found a bug</h4>
+<h4 align="center">Don't hesitate to open an issue if you found a bug</h4>
 
 ![Demo-gif](https://github.com/asmyshlyaev177/state-in-url/assets/19854148/c9802601-4d42-4362-b3e4-37ff87c3b97f)
 
 
-<a href="https://state-in-url-asmyshlyaev177.vercel.app/" target="_blank">DEMO</a>
+<a href="https://state-in-url-asmyshlyaev177.vercel.app/" target="_blank">DEMO</a> |
+<a href ="https://codesandbox.io/p/github/asmyshlyaev177/state-in-url/main?layout=%257B%2522sidebarPanel%2522%253A%2522EXPLORER%2522%252C%2522rootPanelGroup%2522%253A%257B%2522direction%2522%253A%2522horizontal%2522%252C%2522contentType%2522%253A%2522UNKNOWN%2522%252C%2522type%2522%253A%2522PANEL_GROUP%2522%252C%2522id%2522%253A%2522ROOT_LAYOUT%2522%252C%2522panels%2522%253A%255B%257B%2522type%2522%253A%2522PANEL_GROUP%2522%252C%2522contentType%2522%253A%2522UNKNOWN%2522%252C%2522direction%2522%253A%2522vertical%2522%252C%2522id%2522%253A%2522clyk5bd9y00062v6jspcfrkx7%2522%252C%2522sizes%2522%253A%255B100%252C0%255D%252C%2522panels%2522%253A%255B%257B%2522type%2522%253A%2522PANEL_GROUP%2522%252C%2522contentType%2522%253A%2522EDITOR%2522%252C%2522direction%2522%253A%2522horizontal%2522%252C%2522id%2522%253A%2522EDITOR%2522%252C%2522panels%2522%253A%255B%257B%2522type%2522%253A%2522PANEL%2522%252C%2522contentType%2522%253A%2522EDITOR%2522%252C%2522id%2522%253A%2522clyk5bd9x00022v6jyg71cr9e%2522%257D%255D%257D%252C%257B%2522type%2522%253A%2522PANEL_GROUP%2522%252C%2522contentType%2522%253A%2522SHELLS%2522%252C%2522direction%2522%253A%2522horizontal%2522%252C%2522id%2522%253A%2522SHELLS%2522%252C%2522panels%2522%253A%255B%257B%2522type%2522%253A%2522PANEL%2522%252C%2522contentType%2522%253A%2522SHELLS%2522%252C%2522id%2522%253A%2522clyk5bd9x00042v6jsos2y043%2522%257D%255D%257D%255D%257D%252C%257B%2522type%2522%253A%2522PANEL_GROUP%2522%252C%2522contentType%2522%253A%2522DEVTOOLS%2522%252C%2522direction%2522%253A%2522vertical%2522%252C%2522id%2522%253A%2522DEVTOOLS%2522%252C%2522panels%2522%253A%255B%257B%2522type%2522%253A%2522PANEL%2522%252C%2522contentType%2522%253A%2522DEVTOOLS%2522%252C%2522id%2522%253A%2522clyk5bd9x00052v6j5r632b12%2522%257D%255D%257D%255D%252C%2522sizes%2522%253A%255B50%252C50%255D%257D%252C%2522tabbedPanels%2522%253A%257B%2522clyk5bd9x00022v6jyg71cr9e%2522%253A%257B%2522tabs%2522%253A%255B%257B%2522id%2522%253A%2522clyk5bd9w00012v6j83rq3bvo%2522%252C%2522mode%2522%253A%2522permanent%2522%252C%2522type%2522%253A%2522FILE%2522%252C%2522filepath%2522%253A%2522%252FREADME.md%2522%252C%2522state%2522%253A%2522IDLE%2522%257D%255D%252C%2522id%2522%253A%2522clyk5bd9x00022v6jyg71cr9e%2522%252C%2522activeTabId%2522%253A%2522clyk5bd9w00012v6j83rq3bvo%2522%257D%252C%2522clyk5bd9x00052v6j5r632b12%2522%253A%257B%2522id%2522%253A%2522clyk5bd9x00052v6j5r632b12%2522%252C%2522activeTabId%2522%253A%2522clyk5bdjx000b2v6jfc8ae464%2522%252C%2522tabs%2522%253A%255B%257B%2522type%2522%253A%2522SETUP_TASKS%2522%252C%2522id%2522%253A%2522clyk5bdjx000b2v6jfc8ae464%2522%252C%2522mode%2522%253A%2522permanent%2522%257D%252C%257B%2522type%2522%253A%2522UNASSIGNED_PORT%2522%252C%2522port%2522%253A2222%252C%2522id%2522%253A%2522clyk5cjbo004d2v6j3u55k74g%2522%252C%2522mode%2522%253A%2522permanent%2522%257D%252C%257B%2522type%2522%253A%2522ENV_SETUP%2522%252C%2522id%2522%253A%2522clyk5h8dp000r2v6j0r7kc7qq%2522%252C%2522mode%2522%253A%2522permanent%2522%257D%255D%257D%252C%2522clyk5bd9x00042v6jsos2y043%2522%253A%257B%2522id%2522%253A%2522clyk5bd9x00042v6jsos2y043%2522%252C%2522activeTabId%2522%253A%2522clyk5cbuv001q2v6joegrxxv6%2522%252C%2522tabs%2522%253A%255B%257B%2522id%2522%253A%2522clyk5bd9x00032v6jtfhj316o%2522%252C%2522mode%2522%253A%2522permanent%2522%252C%2522type%2522%253A%2522NEW_TERMINAL%2522%257D%252C%257B%2522type%2522%253A%2522TASK_LOG%2522%252C%2522taskId%2522%253A%2522dev%2522%252C%2522id%2522%253A%2522clyk5cbuv001q2v6joegrxxv6%2522%252C%2522mode%2522%253A%2522permanent%2522%257D%252C%257B%2522type%2522%253A%2522TASK_LOG%2522%252C%2522taskId%2522%253A%2522cleanupDist%2522%252C%2522id%2522%253A%2522clyk5dgvo005i2v6jj950sxft%2522%252C%2522mode%2522%253A%2522permanent%2522%257D%255D%257D%257D%252C%2522showDevtools%2522%253Atrue%252C%2522showShells%2522%253Atrue%252C%2522showSidebar%2522%253Atrue%252C%2522sidebarPanelSize%2522%253A15%257D" target="_blank">Demo on Codesandbox</a>
 
 
 <hr />
@@ -42,17 +41,19 @@ Add a ⭐️ to support the project!
 
   ## Why use state-in-url?
 
-`state-in-url` lets you use URI string for state management.
+`state-in-url` Simple state management with URL synchronization.
 
 # Use cases
+
+- 🙃 Share the state between different components without changing url, good as alternative to signals and other state management tools
 - 🔗 Shareable URLs with full application state
 - 🔄 Easy state persistence across page reloads
-- 🧠 Pass data between unrelated client components
-- 🙃 Can just share the state without changing url
+- 🧠 Sync data between unrelated client components
 - 🧮 Store unsaved user forms in URL
 
 # Features
-- 🧩 **Simple**: Handles complex objects without extra effort
+
+- 🧩 **Simple**: No providers, reducers, boilerplate or new concepts
 - 📘 **Typescript support and type Safety**: Preserves data types and structure, enhances developer experience with IDE suggestions, strong typing and JSDoc comments
 - ⚛️ **Framework Flexibility**: Separate hooks for Next.js and React.js applications, and functions for pure JS
 - ⚙ **Well tested**: Unit tests and Playwright tests
@@ -61,6 +62,7 @@ Add a ⭐️ to support the project!
 
 
 ## Table of content
+
 - [Installation](#installation)
 - [`useUrlState` for Next.js](#useurlstate-hook-for-nextjs)
 - [`useUrlEncode` for React.js](#useurlencode-hook-for-reactjs)
@@ -75,7 +77,9 @@ Add a ⭐️ to support the project!
 - [Inspiration](#inspiration)
 
 ## installation
+
 ### 1. Install package
+
 ```sh
 # npm
 npm install --save state-in-url
@@ -84,20 +88,23 @@ yarn add state-in-url
 # pnpm
 pnpm add state-in-url
 ```
+
 ### 2. Edit tsconfig.json
-set `"moduleResolution": "Node16"` or `"moduleResolution": "NodeNext"` in your `tsconfig.json`
 
+set `"moduleResolution": "Node16"` or `"moduleResolution": "NodeNext"` in your `tsconfig.json`
 
 ## useUrlState hook for Next.js
 
-`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.
+[Docs](packages/urlstate/useUrlState/README.md)
 
+`useUrlState` is a custom React hook for Next.js applications that make communication between client components easy. It allows you to share any complex state and sync it with the URL search parameters, providing a way to persist state across page reloads and share application state via URLs.
 
 ### Usage examples
 
 #### Basic
 
 1. Define state shape
+
    ```typescript
    // countState.ts
    // State shape should be stored in a constant, don't pass an object directly
@@ -107,6 +114,7 @@ set `"moduleResolution": "Node16"` or `"moduleResolution": "NodeNext"` in your `
    ```
 
 2. Import it and use
+
 ```typescript
 'use client'
 import { useUrlState } from 'state-in-url';
@@ -248,79 +256,17 @@ function SettingsComponent() {
 }
 ```
 
-## useUrlEncode hook for React.js
-
-`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.
-
-```typescript
-import { useUrlEncode } from 'state-in-url';
+## `useUrlEncode` hook for React.js
 
-const ageState = { age: 0 };
-
-const Component = () => {
-  const { parse, stringify } = useUrlEncode();
-
-  const str = stringify({ age: 36 }); // age=∓36
-  const obj = parse(str, ageState); // { age: 36 }
-  // Or const obj = parse(str); // { age: 36 }
-
-  const currentParams = parse(window.location.search);
-  // OR
-  // const obj = parse(new URLSearchParams(window.location.search))
-
-  const updateSearch = () => {
-    const currentParams = new URLSearchParams(window.location.search);
-    const newState = { query: 'react hooks', page: 2 };
-    const updatedParamsString = stringify(newState, currentParams);
-    console.log(updatedParamsString);
-    // Output: existing params + query=react%20hooks&page=2
-  };
-}
-```
+[Docs](packages/urlstate/useUrlEncode/README.md)
 
 ## `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);
-```
+[Docs](packages/urlstate/encodeState/README.md)
 
 ## `encode` and `decode` helpers
 
-There low level helpers to stringify and parse query string params. Useful for other frameworks or pure JS.
-
-```javascript
-import { encode, decode } from 'state-in-url';
-
-const state = { obj: [1, 2, 3], obj2: true }
-
-// to params
-const params = new URLSearchParams();
-Object.entries(state).forEach(([key, value]) => {
-  params.set(key, encode(value));
-});
-const str = params.toString();
-
-// from params
-const obj = Object.fromEntries(
-  [...params.entries()].map(([key, value]) => [
-    key,
-    // decode(value, optionalFallback),
-    decode(value),
-  ]),
-)
-```
+[Docs](packages/urlstate/encoder/README.md)
 
 ## Best Practices
 
@@ -328,6 +274,7 @@ const obj = Object.fromEntries(
 - 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
+- Use this [extension](https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors) for readable TS errors
 
 ## Gothas
 
@@ -335,10 +282,13 @@ const obj = Object.fromEntries(
 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)
 
 
@@ -349,9 +299,11 @@ Go to [localhost:3000](http://localhost:3000)
 ## [Changelog](https://github.com/asmyshlyaev177/state-in-url/blob/main/CHANGELOG.md)
 
 ## License
+
 This project is licensed under the [MIT license](https://github.com/asmyshlyaev177/state-in-url/blob/main/LICENSE).
 
 ## Inspiration
+
 [Using URL to store state in Vue ](https://dev.to/jacobandrewsky/using-url-to-store-state-in-vue-275c)
 
 [Storing state in the URL](https://antonz.org/storing-state/)

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var t=require("react"),e=require("next/navigation");function n(t){return t&&"object"==typeof t&&"default"in t?t:{default:t}}var r=n(t);const o=t=>{const e=null===t,n=Array.isArray(t),r=t instanceof Date;return(e?"null":r&&"date")||n&&"array"||!e&&!r&&!n&&"object"==typeof t&&"object"||typeof t},c=()=>"undefined"==typeof window,s=t=>new URLSearchParams("string"==typeof t?t:t?.toString?.()||""),u=(t,e)=>JSON.stringify(t)===JSON.stringify(e),a={string:"◖",boolean:"🗵",null:"∙null",undefined:"∙undefined",number:"∓",date:"⏲"};function i(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,f).replaceAll('"',"'");case"null":return a.null;case"undefined":return a.undefined;default:return String(t)}}function l(t,e){return function(t,e){try{return JSON.parse(t,g)}catch{const n=d(t);return n!==p?n:e}}(t.replaceAll("'",'"'),e)}const f=(t,e)=>{const n=o(e);return t&&"object"!==n&&"array"!==n?i(e):e},d=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(/^◖/,""):p:void 0,p=Symbol("isError"),g=(t,e)=>{const n="string"==typeof e,r=n&&d(e);return r===p?e:t&&n?r:e};const y=(t,e)=>{const n="string"==typeof e,r=n&&l(e?.replaceAll?.("'",'"'));return t&&n?r:e};function b(t,e){try{return JSON.parse(t,y)}catch{const n=d(t);return n!==p?n:e}}function S(t,e,n){const r=s(n);return Object.entries(t||{}).forEach((([t,n])=>{const o=e?.[t];JSON.stringify(n)!==JSON.stringify(o)&&r.set(t,i(n))})),r.toString()}function w(t,e){return{...e||{},...Object.fromEntries([...s(t).entries()].map((([t,n])=>{const r=e?.[t];return[t,l(n,r)??r]})))}}function h(t){const e=r.default.useCallback((function(e,n){return"object"===o(e)?S(e,t,n):""}),[t]);return{parse:r.default.useCallback((function(e){return w(e,t)}),[t]),stringify:e}}const m=new WeakMap,O=new WeakMap,j={get:function(t){return m.get(t)},set:function(t,e){m.set(t,e)}};exports.decode=l,exports.decodeState=w,exports.encode=i,exports.encodeState=S,exports.useUrlEncode=h,exports.useUrlState=function(t,n){const{state:o,getState:s,setState:a,stringify:i}=function(t){const e=r.default.useRef(t),{parse:n,stringify:o}=h(e.current),[s,a]=r.default.useState((()=>{const t=j.get(e.current),r=n(c()?"":window.location.search);return t||(j.set(e.current,r),r)})),i=r.default.useCallback((t=>{const n=j.get(e.current)||e.current;if("function"==typeof t){const r=t(n);if(u(n,r))return;j.set(e.current,r),(O.get(e.current)||[]).forEach((t=>{t()}))}else{if(u(n,t))return;j.set(e.current,t),(O.get(e.current)||[]).forEach((t=>{t()}))}}),[]);return r.default.useInsertionEffect((()=>{const r=O.get(e.current)||[],o=()=>{a(j.get(e.current)||t)};O.set(e.current,r.concat(o));const c=()=>{const t=n(window.location.search);i(t)},s="popstate";return window.addEventListener(s,c),()=>{const t=O.get(e.current)||[];O.set(e.current,t.filter((t=>t!==o))),window.removeEventListener(s,c)}}),[i]),{state:s,getState:r.default.useCallback((()=>j.get(e.current)||e.current),[]),setState:i,stringify:o}}(c()?function(t,e){return{...e,...b(JSON.stringify(t),e)}}(n,t):t),l=e.useRouter();return{updateUrl:r.default.useCallback(((t,e)=>{const n=window.location.search,r=`${window.location.pathname}${n.length&&!n.includes("?")?"?":""}${n}`;let o;if("function"==typeof t){const e=t(s());o=i(e),a(e)}else{const e=t??s();o=i(e),a(e)}const c=`${window.location.pathname}${o.length?"?":""}${o}`;if(r!==c){const{replace:t,...n}=e||{};l[t?"replace":"push"](c,{scroll:!1,...n})}}),[l,i,s]),updateState:a,state:o}};
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var t=require("react"),e=require("next/navigation");function n(t){return t&&"object"==typeof t&&"default"in t?t:{default:t}}var r=n(t);const c={string:"◖",boolean:"🗵",null:"∙null",undefined:"∙undefined",number:"∓",date:"⏲"},o=t=>{const e=null===t,n=Array.isArray(t),r=t instanceof Date;return(e?"null":r&&"date")||n&&"array"||!e&&!r&&!n&&"object"==typeof t&&"object"||typeof t},s=()=>"undefined"==typeof window,u=t=>new URLSearchParams("string"==typeof t?t:t?.toString?.()||""),a=(t,e)=>JSON.stringify(t)===JSON.stringify(e);function i(t){switch(o(t)){case"function":case"symbol":return"";case"date":return c.date+t.toISOString();case"string":return`${c.string}${encodeURIComponent(t)}`;case"number":return c.number+String(t);case"boolean":return c.boolean+String(t);case"object":case"array":return JSON.stringify(t,f).replaceAll('"',"'");case"null":return c.null;case"undefined":return c.undefined;default:return String(t)}}function l(t,e){return function(t,e){try{return JSON.parse(t,g)}catch{const n=d(t);return n!==p?n:e}}(t.replaceAll("'",'"'),e)}const f=(t,e)=>{const n=o(e);return t&&"object"!==n&&"array"!==n?i(e):e},d=t=>t===c.null?null:t!==c.undefined?t?.startsWith?.(c.number)?Number.parseFloat(t.replace(c.number,"")):t?.startsWith?.(c.boolean)?!!t.includes("true"):t?.startsWith?.(c.date)?new Date(t.slice(1)):t?.startsWith?.(c.string)?decodeURIComponent(t).replace(/^◖/,""):p:void 0,p=Symbol("isError"),g=(t,e)=>{const n="string"==typeof e,r=n&&d(e);return r===p?e:t&&n?r:e};const y=(t,e)=>{const n="string"==typeof e,r=n&&l(e?.replaceAll?.("'",'"'));return t&&n?r:e};function b(t,e){try{return JSON.parse(t,y)}catch{const n=d(t);return n!==p?n:e}}function S(t,e,n){const r=u(n);return Object.entries(t||{}).forEach((([t,n])=>{const c=e?.[t];JSON.stringify(n)!==JSON.stringify(c)&&r.set(t,i(n))})),r.toString()}function w(t,e){return{...e||{},...Object.fromEntries([...u(t).entries()].map((([t,n])=>{const r=e?.[t];return[t,l(n,r)??r]})))}}function h(t){const e=r.default.useCallback((function(e,n){return"object"===o(e)?S(e,t,n):""}),[t]);return{parse:r.default.useCallback((function(e){return w(e,t)}),[t]),stringify:e}}const m=new WeakMap,O=new WeakMap,j={get:function(t){return m.get(t)},set:function(t,e){m.set(t,e)}};exports.decode=l,exports.decodeState=w,exports.encode=i,exports.encodeState=S,exports.useUrlEncode=h,exports.useUrlState=function(t,n){const{state:c,getState:o,setState:u,stringify:i}=function(t){const e=r.default.useRef(t),{parse:n,stringify:c}=h(e.current),[o,u]=r.default.useState((()=>{const t=j.get(e.current),r=n(s()?"":window.location.search);return t||(j.set(e.current,r),r)})),i=r.default.useCallback((t=>{const n=j.get(e.current)||e.current;if("function"==typeof t){const r=t(n);if(a(n,r))return;j.set(e.current,r),(O.get(e.current)||[]).forEach((t=>{t()}))}else{if(a(n,t))return;j.set(e.current,t),(O.get(e.current)||[]).forEach((t=>{t()}))}}),[]);return r.default.useInsertionEffect((()=>{const t=O.get(e.current)||[],r=()=>{u(j.get(e.current)||e.current)};O.set(e.current,t.concat(r));const c=()=>{const t=n(window.location.search);i(t)},o="popstate";return window.addEventListener(o,c),()=>{const t=O.get(e.current)||[];O.set(e.current,t.filter((t=>t!==r))),window.removeEventListener(o,c)}}),[i]),{state:o,getState:r.default.useCallback((()=>j.get(e.current)||e.current),[]),setState:i,stringify:c}}(s()?function(t,e){return{...e,...b(JSON.stringify(t),e)}}(n,t):t),l=e.useRouter(),f=r.default.useCallback(((t,e)=>{const n=window.location.search,r=`${window.location.pathname}${n.length&&!n.includes("?")?"?":""}${n}`;let c,s;"function"==typeof t?(c=t(o()),s=i(c)):(c=t??o(),s=i(c)),u(c);const a=`${window.location.pathname}${s.length?"?":""}${s}`;if(r!==a){const{replace:t,...n}=e||{};l[t?"replace":"push"](a,{scroll:!1,...n})}}),[l,i,o]);return{updateState:u,updateUrl:f,state:c}};

package/dist/index.mjs

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

package/dist/urlstate/constants/index.d.ts

@@ -0,0 +1 @@
+export * from './constants';

package/dist/urlstate/{encodeState.d.ts → encodeState/encodeState.d.ts}

@@ -1,4 +1,4 @@
-import { type JSONCompatible, type UnknownObj } from './utils';
+import { type JSONCompatible, type UnknownObj } from '../utils';
 /**
  * Encodes the state object into a URL query string.
  *
@@ -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}
+ *  * Github {@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}
+ *  * Github {@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/urlstate/encodeState/index.d.ts

@@ -0,0 +1 @@
+export * from './encodeState';

package/dist/urlstate/{encoder.d.ts → encoder/encoder.d.ts}

@@ -1,11 +1,11 @@
-import { type JSONCompatible } from './utils';
+import { type JSONCompatible } from '../utils';
 /**
  * Encode any JSON serializable value to URL friendly string
  *
  * @param {unknown} payload any value to serialize
  * @returns {string} URLSearchParams compatible value string
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url}
+ *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/encoder#encode}
  */
 export declare function encode(payload: unknown): string;
 /**
@@ -15,7 +15,7 @@ export declare function encode(payload: unknown): string;
  * @param {any} fallback optional fallback value
  * @returns {unknown} decoded object
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url}
+ *  * Github {@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 replacer: (key: string, value: unknown) => unknown;

package/dist/urlstate/encoder/index.d.ts

@@ -0,0 +1 @@
+export * from './encoder';

package/dist/urlstate/index.d.ts

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

package/dist/urlstate/state.d.ts

@@ -1,7 +1,7 @@
-import { type JSONCompatible } from './utils';
+import { type DeepReadonly, type JSONCompatible } from './utils';
 export declare function useState<T extends JSONCompatible>(defaultState: T): {
     state: T;
     getState: () => T;
-    setState: (value: T | ((currState: typeof defaultState) => typeof defaultState)) => void;
+    setState: (value: T | DeepReadonly<T> | ((currState: T) => T)) => void;
     stringify: (state: T, paramsToKeep?: string | URLSearchParams | undefined) => string;
 };

package/dist/urlstate/useUrlEncode/index.d.ts

@@ -0,0 +1 @@
+export * from './useUrlEncode';

package/dist/urlstate/{useUrlEncode.d.ts → useUrlEncode/useUrlEncode.d.ts}

@@ -1,4 +1,4 @@
-import { type JSONCompatible } from './utils';
+import { type JSONCompatible } from '../utils';
 /**
  * A hook that returns stringify and parse functions for encoding and decoding state
  * to and from URL search parameters.
@@ -17,9 +17,29 @@ import { type JSONCompatible } from './utils';
  * parse('name=Tom');
  *  ```
  *
- * * Github {@link https://github.com/asmyshlyaev177/state-in-url}
+ * * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useUrlEncode#api}
  */
 export declare function useUrlEncode<T extends JSONCompatible>(stateShape: T): {
+    /**
+Parse URL query string to state object
+* * Example:
+ * ```ts
+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}
+ */
     parse: (strOrSearchParams: string | URLSearchParams) => T;
+    /**
+Converts a state object to a URL query string.
+* * Example:
+* ```ts
+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}
+*/
     stringify: (state: typeof stateShape, paramsToKeep?: string | URLSearchParams) => string;
 };

package/dist/urlstate/useUrlState/index.d.ts

@@ -0,0 +1 @@
+export * from './useUrlState';

package/dist/urlstate/{useUrlState.d.ts → useUrlState/useUrlState.d.ts}

@@ -1,5 +1,5 @@
 import { useRouter } from 'next/navigation';
-import { DeepReadonly, type JSONCompatible } from './utils';
+import { type DeepReadonly, type JSONCompatible } from '../utils';
 /**
  * NextJS hook. Returns `state`, `updateState`, and `updateUrl` functions
  *
@@ -16,11 +16,31 @@ import { DeepReadonly, type JSONCompatible } from './utils';
  * updateUrl({ name: 'test' }, { replace: true, scroll: true });
  *  ```
  *
- *  * Github {@link https://github.com/asmyshlyaev177/state-in-url}
+ *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useUrlState#api}
  */
 export declare function useUrlState<T extends JSONCompatible>(defaultState: T, sp?: object): {
-    updateUrl: (value?: T | ((currState: typeof defaultState) => typeof defaultState) | undefined, options?: Options) => void;
-    updateState: (value: T | ((currState: T) => T)) => void;
+    /**
+     * * Example:
+     * ```ts
+     * updateState({ name: 'test' });
+     * // or
+     * updateState(curr => ({ ...curr, name: 'test' }) );
+     *  ```
+     *
+     *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useUrlState#updatestate}
+     */
+    updateState: (value: T | DeepReadonly<T> | ((currState: T) => T)) => void;
+    /**
+     * * Example:
+     * ```ts
+     * updateUrl({ name: 'test' });
+     * // or
+     * updateUrl(curr => ({ ...curr, name: 'test' }), { replace: true, scroll: false  } );
+     *  ```
+     *
+     *  * Github {@link https://github.com/asmyshlyaev177/state-in-url/tree/main/packages/urlstate/useUrlState#updateurl}
+     */
+    updateUrl: (value?: T | DeepReadonly<T> | ((currState: T) => T) | undefined, options?: Options) => void;
     state: DeepReadonly<T>;
 };
 type Router = ReturnType<typeof useRouter>;

package/dist/urlstate/utils.d.ts

@@ -15,7 +15,7 @@ export type JSON = null | boolean | Date | number | string | {
 export type JSONCompatible = {
     [prop: string]: JSON | JSON[];
 };
-export type DeepReadonly<T> = T extends Map<infer K, infer V> ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>> : T extends Set<infer S> ? ReadonlySet<DeepReadonly<S>> : T extends JSONCompatible ? {
+export type DeepReadonly<T> = T extends Map<infer K, infer V> ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>> : T extends Set<infer S> ? ReadonlySet<DeepReadonly<S>> : T extends object ? {
     readonly [K in keyof T]: DeepReadonly<T[K]>;
 } : T;
 export declare const getParams: (strOrSearchParams?: string | URLSearchParams) => URLSearchParams;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "0.2.6",
+  "version": "1.0.0",
   "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": [
@@ -70,6 +70,7 @@
     "test:int": "playwright test",
     "test:int:watch": "npx chokidar-cli 'packages/**/*.ts' 'packages/**/*.tsx' -i '.next' -t 500 -c 'npx playwright test -j 2 --project=chromium'",
     "test": "wireit",
+    "tsc": "wireit",
     "dev": "wireit",
     "dev:lib": "wireit",
     "dev:nextjs": "wireit",
@@ -87,13 +88,20 @@
   "wireit": {
     "test": {
       "dependencies": [
+        "tsc",
         "build",
         "test:unit",
         "dev:nextjs"
       ],
       "command": "npx playwright test --project=chromium -j 2"
     },
+    "tsc": {
+      "command": "npx tsc --noEmit"
+    },
     "test:unit": {
+      "dependencies": [
+        "tsc"
+      ],
       "command": "npx jest"
     },
     "dev": {
@@ -177,7 +185,7 @@
     "cz": "^1.8.2",
     "cz-conventional-changelog": "^3.3.0",
     "eslint": "^8.57.0",
-    "eslint-plugin-maintainable": "^0.3.1",
+    "eslint-plugin-maintainable": "^0.4.4",
     "husky": "^9.0.11",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",