state-in-url 3.0.7 → 3.1.0

package/README.md

@@ -144,31 +144,28 @@ import { useUrlState } from 'state-in-url/next';
 import { userState } from './userState';
 
 function MyComponent() {
-  // can pass `replace` arg, it's control will `updateUrl` will use `rounter.push` or `router.replace`, default replace=true
-  // const { state, updateState, updateUrl } = useUrlState({ defaultState: userState, searchParams, replace: false });
-  const { state, updateState, updateUrl } = useUrlState({ defaultState: userState });
+  // can pass `replace` arg, it's control will `setUrl` will use `rounter.push` or `router.replace`, default replace=true
+  // can pass `searchParams` from server components
+  const { urlState, setUrl } = useUrlState({ defaultState: userState });
 
   // won't let you to accidently mutate state directly, requires TS
-  // state.name = 'John' // <- error
+  // urlState.name = 'John' // <- error
 
   return (
     <div>
-      <input value={state.name}
-        onChange={(ev) => { updateState({ name: ev.target.value }) }}
-        onBlur={() => updateUrl()}
+      <input value={urlState.name}
+        onChange={(ev) => { setUrl({ name: ev.target.value }) }}
       />
-      <input value={state.age}
-        onChange={(ev) => { updateState({ age: +ev.target.value }) }}
-        onBlur={() => updateUrl()}
+      <input value={urlState.age}
+        onChange={(ev) => { setUrl({ age: +ev.target.value }) }}
       />
 
       // same api as React.useState
-      <input value={state.name}
-        onChange={(ev) => { updateState(curr => ({ ...curr, name: ev.target.value })) }}
-        onBlur={() => updateUrl()}
+      <input value={urlState.name}
+        onChange={(ev) => { setUrl(curr => ({ ...curr, name: ev.target.value })) }}
       />
 
-      <button onClick={() => updateUrl(userState)}>
+      <button onClick={() => setUrl(userState)}>
         Reset
       </button>
 
@@ -181,7 +178,7 @@ function MyComponent() {
 
 <details>
   <Summary>Example</Summary>
-  
+
 ```typescript
 export const form: Form = {
   name: '',
@@ -205,19 +202,19 @@ import { useUrlState } from 'state-in-url/next';
 import { form } from './form';
 
 function TagsComponent() {
-  // `state` will infer from Form type!
-  const { state, updateUrl } = useUrlState({ defaultState: form });
+  // `urlState` will infer from Form type!
+  const { urlState, setUrl } = useUrlState({ defaultState: form });
 
   const onChangeTags = React.useCallback(
     (tag: (typeof tags)[number]) => {
-      updateUrl((curr) => ({
+      setUrl((curr) => ({
         ...curr,
         tags: curr.tags.find((t) => t.id === tag.id)
           ? curr.tags.filter((t) => t.id !== tag.id)
           : curr.tags.concat(tag),
       }));
     },
-    [updateUrl],
+    [setUrl],
   );
 
   return (
@@ -226,7 +223,7 @@ function TagsComponent() {
         <div className="flex flex-wrap gap-2">
           {tags.map((tag) => (
             <Tag
-              active={!!state.tags.find((t) => t.id === tag.id)}
+              active={!!urlState.tags.find((t) => t.id === tag.id)}
               text={tag.value.text}
               onClick={() => onChangeTags(tag)}
               key={tag.id}
@@ -257,26 +254,25 @@ const tags = [
 [Demo page example code](https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/example-nextjs14/src/app/Form.tsx)
 </details>
 
-
-#### Auto sync state
+#### Update state only and sync to URL manually
 
 <details>
   <Summary>Example</Summary>
 
   ```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);
+      setUrl(urlState);
     }, 500);
 
     return () => {
       clearTimeout(timer.current);
     };
-  }, [state, updateUrl]);
+  }, [urlState, setUrl]);
 ```
 
 Syncing state `onBlur` will be more aligned with real world usage.
@@ -287,13 +283,11 @@ Syncing state `onBlur` will be more aligned with real world usage.
 
 </details>
 
-
-
 #### With server side rendering
 
 <details>
   <Summary>Example</Summary>
-  
+
 ```typescript
 export default async function Home({ searchParams }: { searchParams: object }) {
   return (
@@ -308,7 +302,7 @@ import { useUrlState } from 'state-in-url/next';
 import { form } from './form';
 
 const Form = ({ searchParams }: { searchParams: object }) => {
-  const { state, updateState, updateUrl } = useUrlState({ defaultState: form, searchParams });
+  const { urlState, setState, setUrl } = useUrlState({ defaultState: form, searchParams });
 }
 ```
 
@@ -362,6 +356,7 @@ export default async function Layout({
 
 
 ```
+
 </details>
 
 #### With arbitrary state shape (not recommended)
@@ -376,12 +371,11 @@ import { useUrlState } from 'state-in-url/next';
 const someObj = {};
 
 function SettingsComponent() {
-  const { state, updateUrl, updateState } = useUrlState<object>(someObj);
+  const { urlState, setUrl, setState } = useUrlState<object>(someObj);
 }
 ```
-</details>
-
 
+</details>
 
 ## useUrlState hook for React-Router
 
@@ -414,18 +408,18 @@ import { useUrlState } from 'state-in-url/react-router';
 import { form } from './form';
 
 function TagsComponent() {
-  const { state, updateUrl } = useUrlState({ defaultState: form });
+  const { urlState, setUrl } = useUrlState({ defaultState: form });
 
   const onChangeTags = React.useCallback(
     (tag: (typeof tags)[number]) => {
-      updateUrl((curr) => ({
+      setUrl((curr) => ({
         ...curr,
         tags: curr.tags.find((t) => t.id === tag.id)
           ? curr.tags.filter((t) => t.id !== tag.id)
           : curr.tags.concat(tag),
       }));
     },
-    [updateUrl],
+    [setUrl],
   );
 
   return (
@@ -434,7 +428,7 @@ function TagsComponent() {
         <div className="flex flex-wrap gap-2">
           {tags.map((tag) => (
             <Tag
-              active={!!state.tags.find((t) => t.id === tag.id)}
+              active={!!urlState.tags.find((t) => t.id === tag.id)}
               text={tag.value.text}
               onClick={() => onChangeTags(tag)}
               key={tag.id}
@@ -506,8 +500,6 @@ function SettingsComponent() {
 - Define your state shape as a constant
 - Use TypeScript for enhanced type safety and autocomplete
 - Avoid storing sensitive information in URL parameters (SSN, API keys etc)
-- Use `updateState` for frequent updates and `updateUrl` to sync changes to url
-- Use `Suspence` to wrap client components in Next.js
 - Use this [extension](https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors) for readable TS errors
 
 ## Gothas

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

@@ -1,7 +1,7 @@
 import { useRouter } from "next/navigation";
 import { type DeepReadonly, type JSONCompatible } from "../../utils";
 /**
- * NextJS hook. Returns `state`, `updateState`, and `updateUrl` functions
+ * NextJS hook. Returns `urlState`, `setState`, and `setUrl` functions
  *
  * @param {JSONCompatible<T>} [defaultState] Fallback (default) values for state
  * @param {?SearchParams<T>} [searchParams] searchParams from Next server component
@@ -9,15 +9,15 @@ import { type DeepReadonly, type JSONCompatible } from "../../utils";
  * * Example:
  * ```ts
  * export const form = { name: '', age: 0 };
- * const { state, updateState, updateUrl } = useUrlState({ defaultState: form });
+ * const { urlState, setState, setUrl } = useUrlState({ defaultState: form });
  * // for nextjs seerver components
- * // const { state, updateState, updateUrl } = useUrlState({ defaultState: form, searchParams });
+ * // const { urlState, setState, setUrl } = useUrlState({ defaultState: form, searchParams });
  *
- * updateState({ name: 'test' });
+ * setState({ name: 'test' });
  * // by default it's uses router.push with scroll: false
- * updateUrl({ name: 'test' }, { replace: true, scroll: true });
+ * setUrl({ name: 'test' }, { replace: true, scroll: true });
  * // similar to React.useState
- * updateUrl(curr => ({ ...curr, name: 'test' }), { replace: true, scroll: true });
+ * setUrl(curr => ({ ...curr, name: 'test' }), { replace: true, scroll: true });
  *  ```
  *
  *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/next/useUrlState#api}
@@ -31,25 +31,37 @@ export declare function useUrlState<T extends JSONCompatible>({ defaultState, se
     /**
      * * Example:
      * ```ts
-     * updateState({ name: 'test' });
+     * setState({ name: 'test' });
      * // or
-     * updateState(curr => ({ ...curr, name: 'test' }) );
+     * setState(curr => ({ ...curr, name: 'test' }) );
      *  ```
      *
      *  * 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;
+    /**
+     * @deprecated use `setState`
+     */
     updateState: (value: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T)) => void;
     /**
      * * Example:
      * ```ts
-     * updateUrl({ name: 'test' });
+     * setUrl({ name: 'test' });
      * // or
-     * updateUrl(curr => ({ ...curr, name: 'test' }), { replace: true, scroll: false  } );
+     * setUrl(curr => ({ ...curr, name: 'test' }), { replace: true, scroll: false  } );
      *  ```
      *
      *  * 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;
+    /**
+     * @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>>;
+    /**
+     * @deprecated use `urlState`
+     */
     state: DeepReadonly<DeepReadonly<T>>;
     getState: () => T;
 };

package/dist/next/useUrlState/useUrlState.mjs

@@ -1 +1 @@
-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 o,filterUnknownParams as m,filterUnknownParamsClient as p}from"../../utils.mjs";function u({defaultState:u,searchParams:i,...l}){const n=t(),{state:f,updateState:S,updateUrl:d,getState:j}=s(u,n,(({parse:t})=>o()?r(m(u,i),u):t(p(u)))),U=a.useCallback(((t,e)=>{const a={...c,...l,...e};d(t,a)}),[d,l]),b=e();return a.useEffect((()=>{S(m(u,r(Object.fromEntries([...b.entries()]),u)))}),[b]),{updateState:S,updateUrl:U,state:f,getState:j}}const c={replace:!0,scroll:!1};export{u 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 o,filterUnknownParams as m,filterUnknownParamsClient as l}from"../../utils.mjs";function p({defaultState:p,searchParams:c,...i}){const n=t(),{state:f,updateState:S,updateUrl:d,getState:j}=s(p,n,(({parse:t})=>o()?r(m(p,c),p):t(l(p)))),U=a.useCallback(((t,e)=>{const a={...u,...i,...e};d(t,a)}),[d,i]),b=e();return a.useEffect((()=>{S(m(p,r(Object.fromEntries([...b.entries()]),p)))}),[b]),{setState:S,updateState:S,setUrl:U,updateUrl:U,urlState:f,state:f,getState:j}}const u={replace:!0,scroll:!1};export{p as useUrlState};

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

@@ -1,19 +1,19 @@
 import { type NavigateOptions } from "react-router-dom";
 import { type DeepReadonly, type JSONCompatible } from "../../utils";
 /**
- * React-router hook. Returns `state`, `updateState`, and `updateUrl` functions
+ * React-router hook. Returns `urlState`, `setState`, and `setUrl` functions
  *
  * @param {JSONCompatible<T>} [defaultState] Fallback (default) values for state
  * @param {NavigateOptions} [NavigateOptions] See type from `react-router-dom`
  * * Example:
  * ```ts
  * export const form = { name: '', age: 0 };
- * const { state, updateState, updateUrl } = useUrlState({ defaultState: form, replace: false, preventScrollReset: false });
+ * const { urlState, setState, setUrl } = useUrlState({ defaultState: form, replace: false, preventScrollReset: false });
  *
- * updateState({ name: 'test' });
- * updateUrl({ name: 'test' }, { replace: true });
+ * setState({ name: 'test' });
+ * setUrl({ name: 'test' }, { replace: true });
  * // similar to React.useState
- * updateUrl(curr => ({ ...curr, name: 'test' }), { replace: true });
+ * setUrl(curr => ({ ...curr, name: 'test' }), { replace: true });
  *  ```
  *
  *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/react-router/useUrlState#api}
@@ -24,29 +24,41 @@ export declare function useUrlState<T extends JSONCompatible>({ defaultState, ..
     /**
      * * Example:
      * ```ts
-     * updateState({ name: 'test' });
+     * setUrlState({ name: 'test' });
      * // or
-     * updateState(curr => ({ ...curr, name: 'test' }) );
+     * setUrlState(curr => ({ ...curr, name: 'test' }) );
      * // can pass optional React-Router `NavigateOptions`
-     * updateState(curr => ({ ...curr, name: 'test', preventScrollReset: false }) );
+     * setUrlState(curr => ({ ...curr, name: 'test', preventScrollReset: false }) );
      *  ```
      *
      *  * 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;
+    /**
+     * @deprecated use `setState`
+     */
     updateState: (value: Partial<T> | Partial<DeepReadonly<T>> | ((currState: T) => T)) => void;
     /**
      * * Example:
      * ```ts
-     * updateUrl({ name: 'test' });
+     * setUrl({ name: 'test' });
      * // or
-     * updateUrl(curr => ({ ...curr, name: 'test' }), { replace: true } );
+     * setUrl(curr => ({ ...curr, name: 'test' }), { replace: true } );
      * // can pass optional React-Router `NavigateOptions`
-     * updateState(curr => ({ ...curr, name: 'test', preventScrollReset: false }) );
+     * setState(curr => ({ ...curr, name: 'test', preventScrollReset: false }) );
      *  ```
      *
      *  * 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;
+    /**
+     * @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>>;
+    /**
+     * @deprecated use `urlState`
+     */
     state: DeepReadonly<DeepReadonly<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{filterUnknownParamsClient as o,assignValue as m,filterUnknownParams as p}from"../../utils.mjs";function u({defaultState:u,...l}){const f=e(),i=t.useMemo((()=>({replace:(t,e)=>f(t,{...c,...l,...e}),push:(t,e)=>f(t,{...c,...l,...e})})),[f,l]),{state:n,updateState:S,updateUrl:d,getState:j}=s(u,i,(({parse:t})=>t(o(u)))),U=t.useCallback(((t,e)=>{const r={...c,...l,...e};d(t,r)}),[l]),[b]=r();return t.useEffect((()=>{S(m(u,n,p(u,a(Object.fromEntries([...b.entries()]),u))))}),[b]),{updateState:S,updateUrl:U,state:n,getState:j}}const c={replace:!0,preventScrollReset:!0};export{u 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{filterUnknownParamsClient as o,assignValue as m,filterUnknownParams as p}from"../../utils.mjs";function u({defaultState:u,...c}){const S=e(),f=t.useMemo((()=>({replace:(t,e)=>S(t,{...l,...c,...e}),push:(t,e)=>S(t,{...l,...c,...e})})),[S,c]),{state:i,updateState:n,updateUrl:d,getState:j}=s(u,f,(({parse:t})=>t(o(u)))),U=t.useCallback(((t,e)=>{const r={...l,...c,...e};d(t,r)}),[c]),[b]=r();return t.useEffect((()=>{n(m(u,i,p(u,a(Object.fromEntries([...b.entries()]),u))))}),[b]),{setState:n,updateState:n,setUrl:U,updateUrl:U,urlState:i,state:i,getState:j}}const l={replace:!0,preventScrollReset:!0};export{u as useUrlState};

package/dist/useUrlStateBase/useUrlStateBase.mjs

@@ -1 +1 @@
-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};
+import t from"react";import{useInsertionEffect as e}from"../useInsertionEffect.mjs";import{useSharedState as n}from"../useSharedState/useSharedState.mjs";import{useUrlEncode as o}from"../useUrlEncode/useUrlEncode.mjs";import{filterUnknownParamsClient as r}from"../utils.mjs";function s(s,c,i){const{parse:u,stringify:f}=o(s),{state:h,getState:l,setState:m}=n(s,(()=>i?.({parse:u})||s));e((()=>{const t=()=>{const t=u(r(s));m(t)};return window.addEventListener(a,t),()=>{window.removeEventListener(a,t)}}),[m]);const p=t.useRef([]),d=t.useCallback(((t,e)=>{const n="function"==typeof t?t(l()):t?{...l(),...t}:l(),o=f(n,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}(s)),r=`${window.location.pathname}${o.length?"?":""}${o}${window.location.hash}`;if(r===`${window.location.pathname}${window.location.search}${window.location.hash}`)return;let a;m(n);const{replace:i,...u}=e||{};p.current.push([i?"replace":"push",r,u]),1===p.current.length&&queueMicrotask((()=>{for(;p.current.length;){const t=p.current.shift();if(!t)break;t?.[1]!==a?.[1]&&(a=t)}if(!a)return;const[t,e,n]=a;a=void 0,c[t](e,n)}))}),[c,f,l]);return{updateState:m,updateUrl:d,state:h,getState:l}}const a="popstate";export{s as useUrlStateBase};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "3.0.7",
+  "version": "3.1.0",
   "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": [
@@ -350,7 +350,7 @@
     "@babel/preset-typescript": "^7.24.7",
     "@commitlint/cli": "^19.0.3",
     "@commitlint/config-conventional": "^19.0.3",
-    "@playwright/test": "^1.45.3",
+    "@playwright/test": "^1.48.2",
     "@rollup/plugin-node-resolve": "^15.3.0",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.0",
@@ -386,7 +386,7 @@
     "jest-environment-jsdom": "^29.7.0",
     "lint-staged": "^15.2.9",
     "only-allow": "^1.2.1",
-    "playwright": "^1.45.3",
+    "playwright": "^1.48.2",
     "prettier": "^3.2.5",
     "prettier-plugin-tailwindcss": "^0.6.8",
     "release-it": "^17.6.0",