state-in-url 4.0.3 → 4.0.5

package/README.md

@@ -23,6 +23,10 @@ English | [한국어](./README.KO.md) | [简体中文](./README.CN.md)
 [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](https://github.com/asmyshlyaev177/state-in-url/)
 [![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)]([https://github.com/semantic-release/semantic-release](https://github.com/asmyshlyaev177/state-in-url))
 ![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/state-in-url.svg)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/asmyshlyaev177/state-in-url/badge)](https://scorecard.dev/viewer/?uri=github.com/asmyshlyaev177/state-in-url)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9679/badge)](https://www.bestpractices.dev/projects/9679)
+<!-- or by embedding this in your HTML:
+<a href="https://www.bestpractices.dev/projects/9679"><img src="https://www.bestpractices.dev/projects/9679/badge"></a>  -->
 
 </div>
 
@@ -53,7 +57,7 @@ Share if it useful for you.
 
 # Why use `state-in-url`?
 
-Store any user state in query parameters; imagine JSON in a browser URL, while keeping types and structure of data.
+Store any user state in query parameters; imagine JSON in a browser URL, while keeping types and structure of data, e.g. numbers will be decoded as numbers not strings, Date stay a date, objects and arrays supported.
 Dead simple, fast, and with static Typescript validation. Deep links, aka URL synchronization, made easy.
 
 Contains `useUrlState` hook for Next.js and react-router, and helpers for anything else on JS.
@@ -131,7 +135,7 @@ All components that use the same `state` object are automatically synchronized.
 
 ## useUrlState hook for Next.js
 
-[Docs](packages/urlstate/next/useUrlState#api)
+[Full API Docs](packages/urlstate/next/useUrlState#api)
 
 [React-Router example](#useurlstate-hook-for-react-router)
 
@@ -146,6 +150,7 @@ All components that use the same `state` object are automatically synchronized.
    // Only parameters with value different from default will go to the url.
    export const userState: UserState = { name: '', age: 0 }
 
+   // use `Type` not `Interface`!
    type UserState = { name: string, age: number }
    ```
 
@@ -162,9 +167,6 @@ function MyComponent() {
   // can pass `searchParams` from server components
   const { urlState, setUrl, setState } = useUrlState({ defaultState: userState });
 
-  // won't let you to accidently mutate state directly, requires TS
-  // urlState.name = 'John' // <- error
-
   return (
     <div>
       <input value={urlState.name}
@@ -397,7 +399,7 @@ function SettingsComponent() {
 
 API is same as for Next.js version, except can pass options from [NavigateOptions](https://github.com/remix-run/react-router/blob/bc693ed9f39170bda13b9e1b282fb8e9d5925f66/packages/react-router/lib/context.ts#L99) type.
 
-[Docs](packages/urlstate/react-router/useUrlState#api)
+[API Docs](packages/urlstate/react-router/useUrlState#api)
 
 ### Example
 
@@ -486,7 +488,7 @@ const tags = [
 
 Hooks to create your own `useUrlState` hooks with other routers, e.g. react-router or tanstack router.
 
-[Docs](packages/urlstate/useUrlStateBase)
+[API Docs](packages/urlstate/useUrlStateBase)
 
 ## `useSharedState` hook for React.js
 
@@ -503,19 +505,19 @@ function SettingsComponent() {
 }
 ```
 
-[Docs](packages/urlstate/useSharedState/README.md)
+[API Docs](packages/urlstate/useSharedState/README.md)
 
 ## `useUrlEncode` hook for React.js
 
-[Docs](packages/urlstate/useUrlEncode/README.md)
+[API Docs](packages/urlstate/useUrlEncode/README.md)
 
 ## `encodeState` and `decodeState` helpers
 
-[Docs](packages/urlstate/encodeState/README.md)
+[API Docs](packages/urlstate/encodeState/README.md)
 
 ## `encode` and `decode` helpers
 
-[Docs](packages/urlstate/encoder/README.md)
+[API Docs](packages/urlstate/encoder/README.md)
 
 # Best Practices
 

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

@@ -1,5 +1,5 @@
 import { useRouter } from "next/navigation";
-import { type DeepReadonly, type JSONCompatible } from "../../utils";
+import { type JSONCompatible } from "../../utils";
 /**
  * NextJS hook. Returns `urlState`, `setState`, and `setUrl` functions
  *
@@ -40,11 +40,11 @@ export declare function useUrlState<T extends JSONCompatible>({ defaultState, se
      *
      *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/next/useUrlState#updatestate}
      */
-    setState: (value: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T)) => void;
+    setState: (value: Partial<T> | ((currState: T) => T)) => void;
     /**
      * @deprecated use `setState`
      */
-    updateState: (value: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T)) => void;
+    updateState: (value: Partial<T> | ((currState: T) => T)) => void;
     /**
      * * Example:
      * ```ts
@@ -55,16 +55,19 @@ export declare function useUrlState<T extends JSONCompatible>({ defaultState, se
      *
      *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/next/useUrlState#updateurl}
      */
-    setUrl: (value?: Parameters<(value?: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T) | undefined, options?: import("../../useUrlStateBase/useUrlStateBase").Options) => void>[0], options?: Options) => void;
+    setUrl: (value?: Parameters<(value?: Partial<T> | ((currState: T) => T) | undefined, options?: import("../../useUrlStateBase/useUrlStateBase").Options) => void>[0], options?: Options) => void;
     /**
      * @deprecated use `setUrl`
      */
-    updateUrl: (value?: Parameters<(value?: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T) | undefined, options?: import("../../useUrlStateBase/useUrlStateBase").Options) => void>[0], options?: Options) => void;
-    urlState: DeepReadonly<DeepReadonly<T>>;
+    updateUrl: (value?: Parameters<(value?: Partial<T> | ((currState: T) => T) | undefined, options?: import("../../useUrlStateBase/useUrlStateBase").Options) => void>[0], options?: Options) => void;
+    /**
+     * State object. Don't mutate directly, use `setState` or `setUrl`
+     */
+    urlState: T;
     /**
      * @deprecated use `urlState`
      */
-    state: DeepReadonly<DeepReadonly<T>>;
+    state: T;
     getState: () => T;
 };
 type Router = ReturnType<typeof useRouter>;

package/dist/next/useUrlState/useUrlState.mjs

@@ -1 +1 @@
-import{useRouter as t,useSearchParams as e}from"next/navigation";import r from"react";import{parseSPObj as a}from"../../parseSPObj.mjs";import{useUrlStateBase as s}from"../../useUrlStateBase/useUrlStateBase.mjs";import{routerHistory as o,isSSR as m,filterUnknownParams as u,filterUnknownParamsClient as i}from"../../utils.mjs";function l({defaultState:l,searchParams:c,useHistory:n,...f}){const S=void 0===n||n?o:t(),{state:d,updateState:j,updateUrl:U,getState:b}=s(l,S,(({parse:t})=>m()?a(u(l,c),l):t(i(l)))),g=r.useCallback(((t,e)=>{const r={...p,...f,...e};U(t,r)}),[U,f]),v=e();return r.useEffect((()=>{j(u(l,a(Object.fromEntries([...v.entries()]),l)))}),[v]),{setState:j,updateState:j,setUrl:g,updateUrl:g,urlState:d,state:d,getState:b}}const p={replace:!0,scroll:!1};export{l as useUrlState};
+import{useRouter as t,useSearchParams as e}from"next/navigation";import r from"react";import{parseSPObj as a}from"../../parseSPObj.mjs";import{useUrlStateBase as s}from"../../useUrlStateBase/useUrlStateBase.mjs";import{routerHistory as o,isSSR as m,filterUnknownParams as u,filterUnknownParamsClient as i}from"../../utils.mjs";function l({defaultState:l,searchParams:c,useHistory:f,...n}){const S=void 0===f||f?o:t(),{state:d,updateState:j,updateUrl:U,getState:b}=s(l,S,(({parse:t})=>m()?a(u(l,c),l):t(i(l)))),g=r.useCallback(((t,e)=>U(t,{...p,...n,...e})),[U,n]),v=e();return r.useEffect((()=>{j(u(l,a(Object.fromEntries([...v.entries()]),l)))}),[v]),{setState:j,updateState:j,setUrl:g,updateUrl:g,urlState:d,state:d,getState:b}}const p={replace:!0,scroll:!1};export{l as useUrlState};

package/dist/react-router/useUrlState/useUrlState.d.ts

@@ -1,5 +1,5 @@
 import { type NavigateOptions } from "react-router-dom";
-import { type DeepReadonly, type JSONCompatible } from "../../utils";
+import { type JSONCompatible } from "../../utils";
 /**
  * React-router hook. Returns `urlState`, `setState`, and `setUrl` functions
  *
@@ -35,11 +35,11 @@ export declare function useUrlState<T extends JSONCompatible>({ defaultState, us
      *
      *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/react-router/useUrlState#updatestate}
      */
-    setState: (value: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T)) => void;
+    setState: (value: Partial<T> | ((currState: T) => T)) => void;
     /**
      * @deprecated use `setState`
      */
-    updateState: (value: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T)) => void;
+    updateState: (value: Partial<T> | ((currState: T) => T)) => void;
     /**
      * * Example:
      * ```ts
@@ -52,15 +52,18 @@ export declare function useUrlState<T extends JSONCompatible>({ defaultState, us
      *
      *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/react-router/useUrlState#updateurl}
      */
-    setUrl: (value?: Parameters<(value?: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T) | undefined, options?: import("../../useUrlStateBase/useUrlStateBase").Options) => void>[0], options?: NavigateOptions) => void;
+    setUrl: (value?: Parameters<(value?: Partial<T> | ((currState: T) => T) | undefined, options?: import("../../useUrlStateBase/useUrlStateBase").Options) => void>[0], options?: NavigateOptions) => void;
     /**
      * @deprecated use `setUrl`
      */
-    updateUrl: (value?: Parameters<(value?: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T) | undefined, options?: import("../../useUrlStateBase/useUrlStateBase").Options) => void>[0], options?: NavigateOptions) => void;
-    urlState: DeepReadonly<DeepReadonly<T>>;
+    updateUrl: (value?: Parameters<(value?: Partial<T> | ((currState: T) => T) | undefined, options?: import("../../useUrlStateBase/useUrlStateBase").Options) => void>[0], options?: NavigateOptions) => void;
+    /**
+     * State object. Don't mutate directly, use `setState` or `setUrl`
+     */
+    urlState: T;
     /**
      * @deprecated use `urlState`
      */
-    state: DeepReadonly<DeepReadonly<T>>;
+    state: T;
     getState: () => T;
 };

package/dist/react-router/useUrlState/useUrlState.mjs

@@ -1 +1 @@
-import t from"react";import{useNavigate as e,useSearchParams as r}from"react-router-dom";import{parseSPObj as a}from"../../parseSPObj.mjs";import{useUrlStateBase as s}from"../../useUrlStateBase/useUrlStateBase.mjs";import{routerHistory as o,filterUnknownParamsClient as u,assignValue as m,filterUnknownParams as p}from"../../utils.mjs";function l({defaultState:l,useHistory:S,...f}){const i=e(),n=t.useMemo((()=>S?o:{replace:(t,e)=>i(t,{...c,...f,...e}),push:(t,e)=>i(t,{...c,...f,...e})}),[i,f]),{state:d,updateState:j,updateUrl:U,getState:b}=s(l,n,(({parse:t})=>t(u(l)))),g=t.useCallback(((t,e)=>{const r={...c,...f,...e};U(t,r)}),[f]),[B]=r();return t.useEffect((()=>{j(m(l,d,p(l,a(Object.fromEntries([...B.entries()]),l))))}),[B]),{setState:j,updateState:j,setUrl:g,updateUrl:g,urlState:d,state:d,getState:b}}const c={replace:!0,preventScrollReset:!0};export{l as useUrlState};
+import t from"react";import{useNavigate as e,useSearchParams as r}from"react-router-dom";import{parseSPObj as a}from"../../parseSPObj.mjs";import{useUrlStateBase as s}from"../../useUrlStateBase/useUrlStateBase.mjs";import{routerHistory as o,filterUnknownParamsClient as u,assignValue as m,filterUnknownParams as p}from"../../utils.mjs";function l({defaultState:l,useHistory:S,...f}){const i=e(),n=t.useMemo((()=>S?o:{replace:(t,e)=>i(t,{...c,...f,...e}),push:(t,e)=>i(t,{...c,...f,...e})}),[i,f]),{state:d,updateState:j,updateUrl:U,getState:b}=s(l,n,(({parse:t})=>t(u(l)))),g=t.useCallback(((t,e)=>U(t,{...c,...f,...e})),[f]),[B]=r();return t.useEffect((()=>{j(m(l,d,p(l,a(Object.fromEntries([...B.entries()]),l))))}),[B]),{setState:j,updateState:j,setUrl:g,updateUrl:g,urlState:d,state:d,getState:b}}const c={replace:!0,preventScrollReset:!0};export{l as useUrlState};

package/dist/useSharedState/useSharedState.d.ts

@@ -1,4 +1,4 @@
-import { type DeepReadonly, type JSONCompatible } from "../utils";
+import { type JSONCompatible } from "../utils";
 /**
  * Custom React hook for sharing state between unrelated components.
  *
@@ -20,5 +20,5 @@ import { type DeepReadonly, type JSONCompatible } from "../utils";
 export declare function useSharedState<T extends JSONCompatible>(defaultState: T, _getInitial?: () => T): {
     state: T;
     getState: () => T;
-    setState: (value: (Partial<T> | Partial<DeepReadonly<T>>) | ((currState: T) => T)) => void;
+    setState: (value: Partial<T> | ((currState: T) => T)) => void;
 };

package/dist/useSharedState/useSharedState.mjs

@@ -1 +1 @@
-import t from"react";import{stateMap as r,subscribers as e}from"../subscribers.mjs";import{useInsertionEffect as n}from"../useInsertionEffect.mjs";import{isSSR as u,isEqual as c}from"../utils.mjs";function s(s,o){const f=t.useRef(s),[a,i]=t.useState((()=>{if(u())return o?o?.():f.current;const t=r.get(f.current);if(t)return t;{const t=o?.()||f.current;return r.set(f.current,t),t}})),m=t.useCallback((t=>{const n=r.get(f.current),u="function"==typeof t?t(n):{...n,...t};c(n,u)||(r.set(f.current,u),e.get(f.current).forEach((t=>{t()})))}),[]);n((()=>{const t=e.add(f.current,(()=>{i(r.get(f.current)||f.current)}));return()=>{t()}}),[]);return{state:a,getState:t.useCallback((()=>r.get(f.current)||f.current),[]),setState:m}}export{s as useSharedState};
+import t from"react";import{stateMap as r,subscribers as e}from"../subscribers.mjs";import{useInsertionEffect as n}from"../useInsertionEffect.mjs";import{isSSR as u,isEqual as c}from"../utils.mjs";function s(s,o){const f=t.useRef(s),[a,i]=t.useState((()=>{if(u())return o?o?.():f.current;const t=r.get(f.current);if(t)return t;{const t=o?.()||f.current;return r.set(f.current,t),t}})),m=t.useCallback((t=>{const n=r.get(f.current),u="function"==typeof t?t(n):{...n,...t};c(n,u)||(r.set(f.current,u),e.get(f.current).forEach((t=>t())))}),[]);n((()=>{const t=e.add(f.current,(()=>{i(r.get(f.current)||f.current)}));return()=>{t()}}),[]);return{state:a,getState:t.useCallback((()=>r.get(f.current)||f.current),[]),setState:m}}export{s as useSharedState};

package/dist/useUrlEncode/useUrlEncode.mjs

@@ -1 +1 @@
-import t from"react";import{encodeState as r,decodeState as e}from"../encodeState/encodeState.mjs";import{typeOf as o}from"../utils.mjs";function n(n){const c=t.useCallback((function(t,e){return"object"===o(t)?r(t,n,e):""}),[n]);return{parse:t.useCallback((function(t){return e(t,n)}),[n]),stringify:c}}export{n as useUrlEncode};
+import t from"react";import{encodeState as e,decodeState as o}from"../encodeState/encodeState.mjs";import{typeOf as r}from"../utils.mjs";function a(a){const c=t.useCallback(((t,o)=>"object"===r(t)?e(t,a,o):""),[a]);return{parse:t.useCallback((t=>o(t,a)),[a]),stringify:c}}export{a as useUrlEncode};

package/dist/useUrlStateBase/useUrlStateBase.d.ts

@@ -1,5 +1,5 @@
 import { useUrlEncode } from "../useUrlEncode";
-import { type DeepReadonly, type JSONCompatible, type Router } from "../utils";
+import { type JSONCompatible, type Router } from "../utils";
 /**
  * A custom React hook to create custom hooks.
  *
@@ -24,9 +24,9 @@ import { type DeepReadonly, type JSONCompatible, type Router } from "../utils";
 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?: Parameters<(value: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T)) => void>[0], options?: Options) => void;
-    state: DeepReadonly<T>;
+    updateState: (value: Partial<T> | ((currState: T) => T)) => void;
+    updateUrl: (value?: Parameters<(value: Partial<T> | ((currState: T) => T)) => void>[0], options?: Options) => void;
+    state: T;
     getState: () => T;
 };
 interface OptionsObject {

package/dist/utils.d.ts

@@ -15,9 +15,6 @@ 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 object ? {
-    readonly [K in keyof T]: DeepReadonly<T[K]>;
-} : T;
 export declare const getParams: (strOrSearchParams?: string | URLSearchParams) => URLSearchParams;
 export type UnknownObj = object | {
     [key: string]: unknown;

package/package.json

@@ -1,32 +1,8 @@
 {
   "name": "state-in-url",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "description": "Easily share complex state objects between unrelated React components, preserve types and structure, with TS validation. Deep links and url state synchronization wthout any hasssle or boilerplate.",
   "homepage": "https://state-in-url.dev",
-  "keywords": [
-    "front-end",
-    "state-management",
-    "state management",
-    "deep links",
-    "deep linking",
-    "url synchronization",
-    "useUrlState",
-    "state in url",
-    "client components communication",
-    "query string",
-    "search params",
-    "query params",
-    "typescript",
-    "workflow",
-    "javascript",
-    "hooks",
-    "react.js",
-    "reactjs",
-    "react",
-    "NextJS",
-    "Next.js",
-    "nuqs alternative"
-  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/asmyshlyaev177/state-in-url.git"
@@ -127,6 +103,7 @@
     "reinstall": "npm run cleanup && npm install",
     "setup": "playwright install --with-deps",
     "prepack": "npm run build && cp package.json dist/package.json && npm run build:demo",
+    "pin-gh-deps": "pin-github-action .github/workflows/tests.yml",
     "prepare": "npx husky"
   },
   "wireit": {
@@ -387,6 +364,7 @@
     "jest-environment-jsdom": "^29.7.0",
     "lint-staged": "^15.2.9",
     "only-allow": "^1.2.1",
+    "pin-github-action": "^1.9.1",
     "playwright": "^1.48.2",
     "prettier": "^3.2.5",
     "prettier-plugin-tailwindcss": "^0.6.8",
@@ -402,5 +380,31 @@
     "wait-on": "^8.0.1",
     "wireit": "^0.14.9"
   },
+  "keywords": [
+    "front-end",
+    "state-management",
+    "state management",
+    "deep links",
+    "deep linking",
+    "url synchronization",
+    "useUrlState",
+    "state in url",
+    "client components communication",
+    "query string",
+    "search params",
+    "query params",
+    "typescript",
+    "workflow",
+    "javascript",
+    "hooks",
+    "react.js",
+    "reactjs",
+    "react",
+    "NextJS",
+    "Next.js",
+    "nuqs alternative",
+    "query params parser",
+    "query params parsing"
+  ],
   "packageManager": "npm@10.8.2"
 }