state-in-url 4.0.9 → 4.1.1

package/README.CN.md

@@ -89,7 +89,7 @@ pnpm add state-in-url
 
 ## Next.js的useUrlState钩子
 
-[文档](packages/urlstate/next/useUrlState#api)
+[文档](packages/urlstate/next/useUrlState)
 
 `useUrlState`是一个为Next.js应用程序设计的自定义React钩子，使客户端组件之间的通信变得简单。它允许你共享任何复杂的状态并将其与URL搜索参数同步，提供了一种在页面重新加载之间持久化状态并通过URL共享应用程序状态的方法。
 

package/README.KO.md

@@ -96,7 +96,7 @@ pnpm add state-in-url
 
 ## Next.js용 useUrlState 훅
 
-[문서](packages/urlstate/next/useUrlState#api)
+[문서](packages/urlstate/next/useUrlState)
 
 `useUrlState`는 Next.js 애플리케이션을 위한 사용자 정의 React 훅으로, 클라이언트 컴포넌트 간의 통신을 쉽게 만듭니다. 복잡한 상태를 공유하고 URL 검색 매개변수와 동기화할 수 있게 해주어, 페이지 새로고침 시 상태를 유지하고 URL을 통해 애플리케이션 상태를 공유할 수 있습니다.
 

package/README.md

@@ -1,29 +1,25 @@
 English | [한국어](./README.KO.md) | [简体中文](./README.CN.md)
 
 <div align="center">
-  <img src="/assets/Logo_big.png?raw=true" alt="state-in-url logo"/>
-
-  <div><h2> Store any complex state in query parameters, URL synchronization (aka deep links) made easy. Share state between any unrelated components. With support of static types validation and server side rendering.</h2></div>
-
+  <img src="/packages/example-nextjs14/public/Logo_symbol.png" alt="state-in-url logo" width="120px" />
 
+  # State in url
 </div>
 
-<hr />
-
 <div align="center">
-<a href="https://github.com/asmyshlyaev177/state-in-url/blob/master/Limits.md"  target="_blank">URI size limitation, <b>up to 12KB</b> is safe</a>
 </div>
 
 <div align="center">
-<hr />
 
 [![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=master)
+![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/state-in-url.svg)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/73be54068b7f41b0b74a252579ac09ec)](https://app.codacy.com/gh/asmyshlyaev177/state-in-url/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+
+![Tests](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml/badge.svg?branch=master)
 [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/73be54068b7f41b0b74a252579ac09ec)](https://app.codacy.com/gh/asmyshlyaev177/state-in-url/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
 [![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:
@@ -40,6 +36,8 @@ English | [한국어](./README.KO.md) | [简体中文](./README.CN.md)
 <a href="https://state-in-url.dev" target="_blank">DEMO</a> |
 <a href="https://state-in-url.netlify.app/" target="_blank">DEMO2</a>
 
+<a href="https://github.com/asmyshlyaev177/state-in-url/blob/master/Limits.md"  target="_blank">URI size limitation, <b>up to 12KB</b> is safe</a>
+
 <hr />
 
 Add a ⭐️ and <a href="https://github.com/asmyshlyaev177" target="_blank">follow me</a> to support the project!
@@ -56,9 +54,9 @@ Share if it useful for you.
 
   </div>
 
-# Why use `state-in-url`?
+## 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, e.g. numbers will be decoded as numbers not strings, Date stay a date, objects and arrays supported.
+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, 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.
@@ -69,27 +67,27 @@ This library does all mundane stuff for you.
 
 This library is a good alternative for NUQS.
 
-# Use cases
+### Use cases
 
-- 💾 Store unsaved user forms or page filters in URL
-- 🧠 Just sync data between unrelated client components without touching URI
-- 🔗 Shareable URLs with application state (Deep linking, URL state synchronization)
-- 🔄 Easy state persistence across page reloads
+- Store unsaved user forms or page filters in URL
+- Just sync data between unrelated client components without touching URI
+- Shareable URLs with application state (Deep linking, URL state synchronization)
+- Easy state persistence across page reloads
 
-# Features
+### Features
 
 - 🧩 **Simple**: No providers, reducers, boilerplate or new concepts, API similar to `React.useState`
-- 📘 **Typescript validation**: State is just an object, automatic static validation in IDE/tests according to Typescript definition
+- 📘 **Typescript validation/autocomplete**: State is just an object, automatic static validation in IDE/tests according to Typescript definition
 - ✨ **Complex data**: Nested objects, dates and arrays, works same as JSON, but in URL
-- 🔵 **Server Side Rendering**: Can use it in Server Components, Next.js 14 and 15 are supported
 - ☂ **Default values**: Giving you default values if parameter not in url
 - ⌨ **Organized**: All possible values defined at start, protect you from getting non existing key
-- ⚙ **Well tested**: Unit tests and Playwright tests for Chrome/Firefox/Safari
-- ⚡ **Fast**: Minimal rerenders, less than [1ms](https://github.com/asmyshlyaev177/state-in-url/blob/87c8c7c995c5cd7d9e7aa039c30bfe64b24abe4b/packages/urlstate/encoder/encoder.test.ts#L185) to encode and decode big object
-- 🪶 **Lightweight**: Zero dependencies, library less than 2KB
-- 👍 **DX**: Good developer experience, documentation, JSDoc comments, and examples
-- ⚛️ **Framework Flexibility**: Hooks for `Next.js` and `react-router`, helpers to use it with other frameworks or pure JS
-- 📃 **Permissive license**: MIT
+- **Fast**: Minimal rerenders, less than [1ms](https://github.com/asmyshlyaev177/state-in-url/blob/87c8c7c995c5cd7d9e7aa039c30bfe64b24abe4b/packages/urlstate/encoder/encoder.test.ts#L185) to encode and decode big object
+- **Server Side Rendering**: Can use it in Server Components, Next.js 14 and 15 are supported
+- **Lightweight**: Zero dependencies, library less than 2KB
+- **DX**: Good developer experience, documentation, JSDoc comments, and examples
+- **Framework Flexibility**: Hooks for `Next.js` and `react-router`, helpers to use it with other frameworks or pure JS
+- **Well tested**: Unit tests and Playwright tests for Chrome/Firefox/Safari
+- **Permissive license**: MIT
 
 ## Table of content
 
@@ -136,26 +134,26 @@ Possibly need to set `"module": "ES2022"`, or `"module": "ESNext"`
 Main hook that takes initial state as parameter and returns state object, callback to update url, and callback to update only state.
 All components that use the same `state` object are automatically synchronized.
 
-## useUrlState hook for Next.js
+### useUrlState hook for Next.js
 
-[Full API Docs](packages/urlstate/next/useUrlState#api)
+[Full API Docs](packages/urlstate/next/useUrlState)
 
 [React-Router example](#useurlstate-hook-for-react-router)
 
-### Usage examples
+#### Usage examples
 
-#### Basic
+##### Basic
 
 1. Define state shape with default values
 
-   ```typescript
-   // userState.ts
-   // Only parameters with value different from default will go to the url.
-   export const userState: UserState = { name: '', age: 0 }
+ ```typescript
+ // userState.ts
+ // 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 }
-   ```
+ // use `Type` not `Interface`!
+ type UserState = { name: string, age: number }
+ ```
 
 2. Import it and use
 
@@ -168,10 +166,11 @@ import { userState } from './userState';
 function MyComponent() {
   // 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, setState } = useUrlState(userState);
+  const { urlState, setUrl, setState, reset } = useUrlState(userState);
 
   return (
     <div>
+      // urlState.name will return default value from `userState` if url empty
       <input value={urlState.name}
         // same api as React.useState, e.g. setUrl(currVal => currVal + 1)
         onChange={(ev) => setUrl({ name: ev.target.value }) }
@@ -186,7 +185,7 @@ function MyComponent() {
         onBlur={() => setUrl()}
       />
 
-      <button onClick={() => setUrl(userState)}>
+      <button onClick={reset}>
         Reset
       </button>
 
@@ -195,7 +194,56 @@ function MyComponent() {
 }
 ```
 
-#### With complex state shape
+##### Custom hook to work with slice of state conveniently
+<details>
+  <Summary>Example</Summary>
+
+  ```typescript
+'use client';
+
+import React from 'react';
+import { useUrlState } from 'state-in-url/next';
+
+const form: Form = {
+    name: '',
+    age: undefined,
+    agree_to_terms: false,
+    tags: [],
+};
+
+type Form = {
+    name: string;
+    age?: number;
+    agree_to_terms: boolean;
+    tags: {id: string; value: {text: string; time: Date } }[];
+};
+
+export const useFormState = ({ searchParams }: { searchParams?: object }) => {
+    const { urlState, setUrl: setUrlBase, reset } = useUrlState(form, {
+      searchParams,
+    });
+
+    // first navigation will push new history entry
+    // all following will just replace that entry
+    // this way will have history with only 2 entries - ['/url', '/url?key=param']
+
+    const replace = React.useRef(false);
+    const setUrl = React.useCallback((
+        state: Parameters<typeof setUrlBase>[0],
+        opts?: Parameters<typeof setUrlBase>[1]
+      ) => {
+        setUrlBase(state, { replace: replace.current, ...opts });
+        replace.current = true;
+    }, [setUrlBase]);
+
+    return { urlState, setUrl, resetUrl: reset };
+};
+  ```
+</details>
+
+<hr />
+
+##### With complex state shape
 
 <details>
   <Summary>Example</Summary>
@@ -275,7 +323,7 @@ const tags = [
 [Demo page example code](https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/example-nextjs14/src/app/Form.tsx)
 </details>
 
-#### Update state only and sync to URL manually
+##### Update state only and sync to URL manually
 
 <details>
   <Summary>Example</Summary>
@@ -304,7 +352,7 @@ Syncing state `onBlur` will be more aligned with real world usage.
 
 </details>
 
-#### With server side rendering
+##### With server side rendering
 
 <details>
   <Summary>Example</Summary>
@@ -329,7 +377,7 @@ const Form = ({ searchParams }: { searchParams: object }) => {
 
 </details>
 
-#### Using hook in `layout` component
+##### Using hook in `layout` component
 
 <details>
   <Summary>Example</Summary>
@@ -380,7 +428,7 @@ export default async function Layout({
 
 </details>
 
-#### With arbitrary state shape (not recommended)
+##### With arbitrary state shape (not recommended)
 
 <details>
   <Summary>Example</Summary>
@@ -398,13 +446,13 @@ function SettingsComponent() {
 
 </details>
 
-## useUrlState hook for React-Router
+### useUrlState hook for React-Router
 
 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.
 
-[API Docs](packages/urlstate/react-router/useUrlState#api)
+[API Docs](packages/urlstate/react-router/useUrlState)
 
-### Example
+#### Example
 
 ```typescript
 export const form: Form = {
@@ -485,15 +533,15 @@ const tags = [
 
 [Example code](packages/example-react-router6/src/Form-for-test.tsx)
 
-# Other hooks and helpers
+## Other hooks and helpers
 
-## `useUrlStateBase` hook for others routers
+### `useUrlStateBase` hook for others routers
 
 Hooks to create your own `useUrlState` hooks with other routers, e.g. react-router or tanstack router.
 
 [API Docs](packages/urlstate/useUrlStateBase)
 
-## `useSharedState` hook for React.js
+### `useSharedState` hook for React.js
 
 Hook to share state between any React components, tested with Next.js and Vite.
 
@@ -510,19 +558,19 @@ function SettingsComponent() {
 
 [API Docs](packages/urlstate/useSharedState/README.md)
 
-## `useUrlEncode` hook for React.js
+### `useUrlEncode` hook for React.js
 
 [API Docs](packages/urlstate/useUrlEncode/README.md)
 
-## `encodeState` and `decodeState` helpers
+### `encodeState` and `decodeState` helpers
 
 [API Docs](packages/urlstate/encodeState/README.md)
 
-## `encode` and `decode` helpers
+### `encode` and `decode` helpers
 
 [API Docs](packages/urlstate/encoder/README.md)
 
-# Best Practices
+## Best Practices
 
 - Define your state shape as a constant
 - Use TypeScript for enhanced type safety and autocomplete
@@ -556,9 +604,9 @@ export const useUserState = () => {
 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>
 3. Tested with `next.js` 14/15  with app router, no plans to support pages.
 
-# Other
+## Other
 
-## Contribute and/or run locally
+### Contribute and/or run locally
 
 See [Contributing doc](CONTRIBUTING.md)
 

package/dist/encoder/encoder.d.ts

@@ -1,4 +1,4 @@
-import { type JSONCompatible } from "../utils";
+import { type JSONCompatible, type Simple } from "../utils";
 /**
  * Encode any JSON serializable value to URL friendly string
  *
@@ -8,7 +8,7 @@ import { type JSONCompatible } from "../utils";
  *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/encoder#encode}
  */
 export declare function encode(payload: unknown): string;
-export type Primitive = Exclude<ReturnType<typeof decodePrimitive>, typeof errorSym>;
+export declare const encodePrimitive: (payload: Simple) => Simple;
 /**
  * Decode value part of URLSearchParams back to JS value
  *
@@ -18,17 +18,17 @@ export type Primitive = Exclude<ReturnType<typeof decodePrimitive>, typeof error
  *
  *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/encoder#decode}
  */
-export declare function decode<T>(payload: string, fallback?: T): JSONCompatible | Primitive;
-export declare const decodePrimitive: (str: string) => Date | typeof errorSym | undefined;
-export declare const errorSym: unique symbol;
-export declare const reviver: (_key: string, value: unknown) => unknown;
+export declare function decode<T>(payload: string, fallback?: T): T;
 /**
  * Parses a JSON string into a TypeScript object.
  *
  * @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.
+ * @return {T | CustomDecoded | undefined} - The parsed object or a primitive value, or undefined if parsing fails.
  *
  *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url}
  */
-export declare function parseJSON<T extends JSONCompatible>(jsonString: string, fallbackValue?: T): T | Primitive | undefined;
+export declare function parseJSON<T extends JSONCompatible>(jsonString: string, fallbackValue?: T): T | CustomDecoded | undefined;
+export declare function reviver(_key: string, value: unknown): unknown;
+export declare const decodePrimitive: (str: string) => string | Date | undefined;
+export type CustomDecoded = ReturnType<typeof decodePrimitive>;

package/dist/encoder/encoder.mjs

@@ -1 +1 @@
-import{SYMBOLS as t}from"../constants/constants.mjs";import{typeOf as e}from"../utils.mjs";function n(n){if(u(n))return n;switch(e(n)){case"function":case"symbol":return"";case"date":return r=n,t.date+new Date(r).toISOString();case"undefined":return t.undefined;default:return JSON.stringify(n).replace(/'/g,"%27").replace(/"/g,"'")}var r}function r(t,e){return a(t.replace(/'/g,'"').replace(/%27/g,"'"),e)}const s=e=>{if(e!==t.undefined)return e?.startsWith?.(t.date)?new Date(e.slice(1)):c},c=Symbol("isError"),i=(t,e)=>{const n="string"==typeof e,r=n&&s(e);return r===c?e:n?r:e};function a(t,e){try{return JSON.parse(t,i)}catch{const n=s(t);return n!==c?n:e}}const o=new RegExp(`^(${t.undefined}|${t.date})`),u=t=>o.test(String(t));export{r as decode,s as decodePrimitive,n as encode,c as errorSym,a as parseJSON,i as reviver};
+import{SYMBOLS as t}from"../constants/constants.mjs";import{typeOf as e}from"../utils.mjs";function n(t){return f(t)?t:JSON.stringify(t,r).replace(/'/g,"%27").replace(/"/g,"'")}function r(t,n){const a=e(n);if("object"!==a&&"array"!==a)return c(n);if("object"===a){const t=n;return Object.keys(t).forEach((e=>{t[e]=r("",t[e])})),t}return"array"===a?n.map((t=>r("",t))):n}const c=n=>{switch(e(n)){case"function":case"symbol":return"";case"date":return t.date+new Date(n).toISOString();case"undefined":return t.undefined;default:return n}};function a(t,e){return s(t.replace(/'/g,'"').replace(/%27/g,"'"),e)}function s(t,e){try{return JSON.parse(t,u)}catch{return e}}function u(t,e){return"string"==typeof e?i(e):e}const i=e=>{if(e!==t.undefined)return e?.startsWith?.(t.date)?new Date(e.slice(1)):e},o=new RegExp(`^(${t.undefined}|${t.date})`),f=t=>o.test(String(t));export{a as decode,i as decodePrimitive,n as encode,c as encodePrimitive,s as parseJSON,u as reviver};

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

@@ -19,10 +19,15 @@ export declare function useUrlState<T extends JSONCompatible>({ defaultState: T,
  *
  * @param {JSONCompatible<T>} [defaultState] Fallback (default) values for state
  * @param {Object} params - Object with other parameters, including params from App router
- * @param {boolean} params.replace replace URL of push, default `true`
- * @param {boolean} params.useHistory use window.history for navigation, default true, no _rsc requests https://github.com/vercel/next.js/discussions/59167
+ * @param {boolean} params.replace replace URL or push, default `true`
+ * @param {boolean} params.useHistory use window.history for navigation, default `true`, no _rsc requests https://github.com/vercel/next.js/discussions/59167
  * @param {?SearchParams<T>} params.searchParams searchParams from Next server component
  * @param {boolean} params.scroll reset scroll, default `false`
+ * @returns {Object} [result] State and callbacks
+ * @returns {Object} [result.state] - current state object
+ * @returns {Function} [result.setUrl] - function to update state and url
+ * @returns {Function} [result.setState] - function to update state only
+ * @returns {Function} [result.reset] - function to reset state and url to default
 
  *
  * * Example:
@@ -30,19 +35,26 @@ export declare function useUrlState<T extends JSONCompatible>({ defaultState: T,
  * export const form = { name: '', age: 0 };
  * const { urlState, setState, setUrl } = useUrlState(form);
  * // for nextjs server components
- * const { urlState, setState, setUrl } = useUrlState(form, { searchParams });
+ * const { urlState, setState, setUrl, reset } = useUrlState(form, { searchParams });
  *
  * setState({ name: 'test' });
  * setUrl({ name: 'test' }, { replace: true, scroll: true });
  * setUrl(curr => ({ ...curr, name: 'test' }), { replace: true, scroll: true });
+ * // reset state and url
+ * reset();
+ * reset({ replace: true });
+ * // same as setState(form) with setUrl(form)
  *  ```
  *
- *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/next/useUrlState#api}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/next/useUrlState}
  */
 export declare function useUrlState<T extends JSONCompatible>(defaultState: T, params?: Params): {
     urlState: T;
     setState: (value: Partial<T> | ((currState: T) => T)) => void;
     setUrl: (value?: Partial<T> | ((currState: T) => T), options?: Options) => void;
+    reset: (options?: Options & {
+        [key: string]: unknown;
+    }) => void;
 };
 type Router = ReturnType<typeof useRouter>;
 type RouterOptions = NonNullable<Parameters<Router["push"]>[1] | Parameters<Router["replace"]>[1]>;

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

package/dist/parseSPObj.mjs

@@ -1 +1 @@
-import{decodePrimitive as r,errorSym as t,decode as n}from"./encoder/encoder.mjs";function e(r,t){return{...t,...o(JSON.stringify(r),t)}}function o(n,e){try{return JSON.parse(n,c)}catch{const o=r(n);return o!==t?o:e}}const c=(r,t)=>{const e="string"==typeof t,o=e&&n(t?.replace?.(/'/g,'"'));return r&&e?o:t};export{e as parseSPObj};
+import{decode as r}from"./encoder/encoder.mjs";function t(r,t){return{...t,...n(JSON.stringify(r),t)}}function n(r,t){try{return JSON.parse(r,e)}catch{return t}}const e=(t,n)=>{const e="string"==typeof n,o=e&&r(n?.replace?.(/'/g,'"'));return t&&e?o:n};export{t as parseSPObj};

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

@@ -20,9 +20,14 @@ export declare function useUrlState<T extends JSONCompatible>({ defaultState: T,
  * @param {JSONCompatible<T>} [defaultState] Fallback (default) values for state
  * @param {Object} params - Object with other parameters
  * @param {NavigateOptions} params.NavigateOptions See type from `react-router-dom`
- * @param {boolean} params.replace replace URL of push, default `true`
+ * @param {boolean} params.replace replace URL or push, default `true`
  * @param {boolean} params.useHistory use window.history for navigation, default `false`
  * @param {boolean} params.preventScrollReset keep scroll position, default `true`
+ * @returns {Object} [result] State and callbacks
+ * @returns {Object} [result.state] - current state object
+ * @returns {Function} [result.setUrl] - function to update state and url
+ * @returns {Function} [result.setState] - function to update state only
+ * @returns {Function} [result.reset] - function to reset state and url to default
  * * Example:
  * ```ts
  * export const form = { name: '', age: 0 };
@@ -32,14 +37,21 @@ export declare function useUrlState<T extends JSONCompatible>({ defaultState: T,
  * setUrl({ name: 'test' }, { replace: true });
  * // similar to React.useState
  * setUrl(curr => ({ ...curr, name: 'test' }), { replace: true });
+ * // reset state and url
+ * reset();
+ * reset({ replace: true });
+ * // same as setState(form) with setUrl(form)
  *  ```
  *
- *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/react-router/useUrlState#api}
+ *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/react-router/useUrlState}
  */
 export declare function useUrlState<T extends JSONCompatible>(defaultState: T, params?: Params): {
     urlState: T;
     setState: (value: Partial<T> | ((currState: T) => T)) => void;
     setUrl: (value?: Partial<T> | ((currState: T) => T), options?: Params) => void;
+    reset: (options?: NavigateOptions & {
+        [key: string]: unknown;
+    }) => void;
 };
 type OldParams<T> = {
     defaultState: T;

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

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

package/dist/testUtils.d.ts

@@ -0,0 +1 @@
+export declare const clone: (obj: object) => any;

package/dist/useUrlEncode/useUrlEncode.d.ts

@@ -17,7 +17,7 @@ import { type JSONCompatible } from "../utils";
  * parse('name=Tom');
  *  ```
  *
- * * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/useUrlEncode#api}
+ * * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/useUrlEncode}
  */
 export declare function useUrlEncode<T extends JSONCompatible>(stateShape: T): {
     /**

package/dist/useUrlStateBase/useUrlStateBase.d.ts

@@ -7,19 +7,31 @@ import { type JSONCompatible, type Router } from "../utils";
  * @param {T} defaultState - An object representing the default state values.
  * @param {Router} router - Router object with [push] and [replace] methods.
  * @param {Function} [getInitialState] - Optional function to get the initial state, passes `parse`, and `filterUnknownParams` helpers
- * @returns {Object} An object containing `state`, `getState`, `updateState`, and `updateUrl` properties.
+ * @returns {Object} [result] State and callbacks
+ * @returns {Object} [result.state] - current state object
+ * @returns {Function} [result.updateUrl] - function to update state and url
+ * @returns {Function} [result.updateState] - function to update state only
+ * @returns {Function} [result.reset] - function to reset state and url to default
  *
  *
  * * Example:
  * ```ts
  * export const form = { name: '' };
  * const router = { push: () => {}, replace: () => {} };
- * const { state, updateState, updateUrl } = useUrlStateBase(form, router, ({ parse, filterClientSP }) =>
+ * const { state, updateState, updateUrl, reset } = useUrlStateBase(form, router, ({ parse, filterClientSP }) =>
  *   isSSR() ? getServerState() : getClientState()
  * );
+ *
+ * updateState({ name: 'John' });
+ * updateState(curr => ({ ...curr, name: 'John' }));
+ * updateUrl({ name: 'John' }, { replace: true });
+ * updateUrl(curr => ({ ...curr, name: 'John' }), { replace: true });
+ * reset()
+ * reset({ replace: true })
+ *
  *  ```
  *
- * * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/integrations/packages/urlstate/useUrlStateBase#api}
+ * * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/integrations/packages/urlstate/useUrlStateBase}
  */
 export declare function useUrlStateBase<T extends JSONCompatible>(defaultState: T, router: Router, getInitialState?: ({ parse, }: {
     parse: ReturnType<typeof useUrlEncode<T>>["parse"];
@@ -27,6 +39,7 @@ export declare function useUrlStateBase<T extends JSONCompatible>(defaultState:
     updateState: (value: Partial<T> | ((currState: T) => T)) => void;
     updateUrl: (value?: Parameters<(value: Partial<T> | ((currState: T) => T)) => void>[0], options?: Options) => void;
     state: T;
+    reset: (options?: Options) => void;
     getState: () => T;
 };
 interface OptionsObject {

package/dist/useUrlStateBase/useUrlStateBase.mjs

@@ -1 +1 @@
-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:l}=o(s),{state:p,getState:d,setState:h}=n(s,(()=>i?.({parse:u})||s));e((()=>{const t=()=>{const t=u(r(s));h(t)};return window.addEventListener(a,t),()=>{window.removeEventListener(a,t)}}),[h]);const m=t.useRef([]),w=t.useCallback(((t,e)=>{const n="function"==typeof t?t(d()):t?{...d(),...t}:d(),o=l(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;h(n);const i=e?.replace;delete e?.replace,m.current.push([i?"replace":"push",r,e]),1===m.current.length&&queueMicrotask((()=>{for(;m.current.length;){const t=m.current.shift();t&&t?.[1]!==a?.[1]&&(a=t)}const[t,e,n]=a||{};a=void 0,t&&c[t](e,n)}))}),[c,l,d]);return{updateState:h,updateUrl:w,state:p,getState:d}}const a="popstate";export{s as useUrlStateBase};
+import e from"react";import{useInsertionEffect as t}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:l}=o(s),{state:p,getState:d,setState:h}=n(s,(()=>i?.({parse:u})||s));t((()=>{const e=()=>{const e=u(r(s));h(e)};return window.addEventListener(a,e),()=>{window.removeEventListener(a,e)}}),[h]);const m=e.useRef([]),w=e.useCallback(((e,t)=>{const n="function"==typeof e?e(d()):e?{...d(),...e}:d(),o=l(n,function(e){const t=Object.keys(e),n=window.location.search,o=new URLSearchParams(n),r=new URLSearchParams;return o.forEach(((e,n)=>!t.includes(n)&&r.set(n,e))),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;h(n);const i=t?.replace;delete t?.replace,m.current.push([i?"replace":"push",r,t]),1===m.current.length&&queueMicrotask((()=>{for(;m.current.length;){const e=m.current.shift();e&&e?.[1]!==a?.[1]&&(a=e)}const[e,t,n]=a||{};a=void 0,e&&c[e](t,n)}))}),[c,l,d]),f=e.useCallback((e=>{w(s,e)}),[w]);return{updateState:h,updateUrl:w,state:p,reset:f,getState:d}}const a="popstate";export{s as useUrlStateBase};

package/dist/utils.d.ts

@@ -8,6 +8,8 @@ export type Type = "string" | "date" | "boolean" | "number" | "bigint" | "undefi
  * `function`, `symbol`, `array`
  */
 export declare const typeOf: (val: unknown) => Type;
+export declare const isPrimitive: (val: unknown) => val is Simple;
+export type Simple = string | Date | boolean | number | null | undefined | Function | symbol;
 export declare const isSSR: () => boolean;
 export type JSON = null | boolean | Date | number | string | {
     [prop: string]: JSON | JSON[];
@@ -22,6 +24,7 @@ export type UnknownObj = object | {
 export declare const isEqual: (val1: unknown, val2: unknown) => boolean;
 export declare function filterUnknownParamsClient<T extends object>(shape: T): string;
 export declare function filterUnknownParams<T extends object>(shape: T, searchParams?: object): T;
+export declare function filterUnknown<T extends object>(shape: T, entries: [key: string, value: string][]): string[][];
 export declare function assignValue<T extends object>(shape: T, newVal: Partial<T>): T;
 export interface Router {
     push: (href: string, opts: object) => void;

package/dist/utils.mjs

@@ -1 +1 @@
-const t=t=>{const n=typeof t,e=null===t,r=Array.isArray(t),o=t instanceof Date;return(e?"null":o&&"date")||r&&"array"||!e&&!o&&!r&&"object"===n&&"object"||n},n=()=>"undefined"==typeof window,e=t=>new URLSearchParams("string"==typeof t?r(t):t?.toString?.()||""),r=t=>t.split("?")?.[1]||t||"",o=(t,n)=>JSON.stringify(t)===JSON.stringify(n);function i(t){const n=new URLSearchParams;return s(t,[...new URLSearchParams(window.location.search).entries()]).forEach((([t,e])=>n.set(t,e))),n.toString()}function c(t,n){return Object.fromEntries(s(t,Object.entries(n||{})))}function s(t,n){const e=Object.keys(t);return n.filter((([t])=>e.includes(t))).map((([t,n])=>[t.replace(/\+/g," "),n]))}function a(t,n){const e=Object.assign({},t);return Object.entries(t).forEach((([r])=>{const o=r,i=void 0!==n[o];e[o]=i?n[o]:t[o]})),e}const u={push:t=>{window&&window.history.pushState(null,"",t)},replace:t=>{window&&window.history.replaceState(null,"",t)}};export{a as assignValue,c as filterUnknownParams,i as filterUnknownParamsClient,e as getParams,o as isEqual,n as isSSR,u as routerHistory,t as typeOf};
+const t=t=>{const n=typeof t,e=null===t,r=Array.isArray(t),o=t instanceof Date;return(e?"null":o&&"date")||r&&"array"||!e&&!o&&!r&&"object"===n&&"object"||n},n=()=>"undefined"==typeof window,e=t=>new URLSearchParams("string"==typeof t?r(t):t?.toString?.()||""),r=t=>t.split("?")?.[1]||t||"",o=(t,n)=>JSON.stringify(t)===JSON.stringify(n);function i(t){const n=new URLSearchParams;return c(t,[...new URLSearchParams(window.location.search).entries()]).forEach((([t,e])=>n.set(t,e))),n.toString()}function s(t,n){return Object.fromEntries(c(t,Object.entries(n||{})))}function c(t,n){const e=Object.keys(t),r=[];for(let t=0;t<n.length;t++)e.includes(n[t]?.[0])&&r.push([n[t][0].replace(/\+/g," "),n[t][1]]);return r}function a(t,n){const e=Object.assign({},t);return Object.entries(t).forEach((([r])=>{const o=r,i=void 0!==n[o];e[o]=i?n[o]:t[o]})),e}const u={push:t=>{window&&window.history.pushState(null,"",t)},replace:t=>{window&&window.history.replaceState(null,"",t)}};export{a as assignValue,c as filterUnknown,s as filterUnknownParams,i as filterUnknownParamsClient,e as getParams,o as isEqual,n as isSSR,u as routerHistory,t as typeOf};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "4.0.9",
+  "version": "4.1.1",
   "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",
   "repository": {
@@ -103,7 +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",
+    "pin-gh-deps": "pin-github-action -i .github/workflows/tests.yml",
     "prepare": "npx husky"
   },
   "wireit": {
@@ -342,7 +342,7 @@
     "@testing-library/react": "^16.0.0",
     "@testing-library/react-hooks": "^8.0.1",
     "@types/glob": "^8.1.0",
-    "@types/jest": "^29.5.13",
+    "@types/jest": "^29.5.14",
     "@types/node": "^20.11.24",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
@@ -374,7 +374,7 @@
     "rollup-plugin-sourcemaps": "^0.6.3",
     "semantic-release": "^24.1.0",
     "standard-version": "^9.5.0",
-    "ts-jest": "^29.1.5",
+    "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
     "typescript": "^5.3.3",
     "wait-on": "^8.0.1",