state-in-url 4.2.0 → 4.2.1

package/README.CN.md

@@ -1,74 +1,125 @@
 [English](./README.md) | [한국어](./README.KO.md) | 简体中文
 
 <div align="center">
-  <img src="/assets/Logo_big.png?raw=true" alt="state-in-url logo"/>
+  <img src="/packages/example-nextjs14/public/Logo_symbol.png" alt="state-in-url logo" width="120px" />
 
-  <div>轻松在不相关的React组件之间共享状态，具有IDE自动完成和TS验证功能。无需任何麻烦或样板代码。</div>
+  # State in url
+</div>
+
+<div align="center">
 </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/)
-![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/state-in-url.svg)
+[![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))
+
+[![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)
+[![license](https://img.shields.io/github/license/asmyshlyaev177/state-in-url.svg?style=flat-square)](https://github.com/asmyshlyaev177/state-in-url/blob/master/LICENSE)
+<!-- 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>
 
 <div align="center">
 
-<h4 align="center">如果发现bug，请随时提出issue</h4>
+<h4 align="center">如果您发现漏洞或有功能需求，请随时提交issue</h4>
 
-![演示-gif](https://github.com/asmyshlyaev177/state-in-url/assets/19854148/c9802601-4d42-4362-b3e4-37ff87c3b97f)
+![Demo-gif](https://github.com/asmyshlyaev177/state-in-url/blob/master/assets/Demo-gif.gif)
 
-<a href="https://state-in-url.dev/" target="_blank">演示</a> |
-<a href="https://state-in-url.netlify.app/" target="_blank">DEMO2</a> |
+# 演示页面
 
-<hr />
+<a href="https://state-in-url.dev" target="_blank">演示页面</a> |
+<a href="https://state-in-url.netlify.app/" target="_blank">镜像链接</a>
 
-添加⭐️来支持项目！
+<a href="https://github.com/asmyshlyaev177/state-in-url/blob/master/Limits.md"  target="_blank">URI 长度限制： <b>安全上限为 12KB</b> </a>
 
 <hr />
 
-</div>
+点个 <a href="#"><img src="https://raw.githubusercontent.com/acervenky/animated-github-badges/master/assets/starbadge.gif" width="25" height="25"></a>  并且 <a href="https://github.com/asmyshlyaev177" target="_blank">关注我</a> 来支持这个项目!
+
+非常感激在[discussions](https://github.com/asmyshlyaev177/state-in-url/discussions/1)上提交你的反馈或意见
+
+如果觉得有用，就分享一下吧。
+[X.com](https://twitter.com/intent/tweet?&url=https://github.com/asmyshlyaev177/state-in-url)
+[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/asmyshlyaev177/state-in-url)
+[FB](https://www.facebook.com/sharer.php?u=https://github.com/asmyshlyaev177/state-in-url)
+[VK](http://vk.com/share.php?url=https://github.com/asmyshlyaev177/state-in-url)
 
-## 为什么使用state-in-url？
+  <hr />
 
-`state-in-url`是一个简单的状态管理工具，可以与URL同步。在不相关的React组件之间共享复杂状态，将状态同步到URL，对TS友好，兼容NextJS。
+  </div>
 
-# 使用场景
+[直接给我看代码!](#useurlstate)
 
-- 🙃 在不改变URL的情况下，在不同组件之间共享状态，是信号和其他状态管理工具的良好替代方案
-- 🔗 包含完整应用程序状态的可共享URL
-- 🔄 在页面重新加载之间轻松持久化状态
-- 🧠 在不相关的客户端组件之间同步数据
-- 🧮 在URL中存储未保存的用户表单
+## 为什么使用 `state-in-url`?
 
-# 特性
+将任何用户状态存储在查询参数中；想象一下在浏览器 URL 中嵌入 JSON 数据，同时保持数据的类型和结构。例如数字会被解码为数字而不是字符串，日期会被解码为日期，支持对象和数组等复杂结构。
+简单、快速，并且支持静态 TypeScript 验证。深度链接（即 URL 同步）变得轻而易举。
 
-- 🧩 **简单**：无需提供者、reducers、样板代码或新概念
-- 📘 **TypeScript支持和类型安全**：保留数据类型和结构，通过IDE建议、强类型和JSDoc注释增强开发体验
-- ⚛️ **框架灵活性**：为Next.js和React.js应用程序提供单独的钩子，以及用于纯JS的函数
-- ⚙ **经过充分测试**：单元测试和Playwright测试
-- ⚡ **快速**：最少的重新渲染
-- 🪶 **轻量级**：零依赖，占用空间小
+提供了适用于 Next.js 和 react-router 的 `useUrlState` 钩子，以及适用于其他 JavaScript 场景的辅助工具。
+由于现代浏览器支持超长的 URL，而用户并不关心查询字符串（通常的操作是全选、复制和粘贴）。
+
+是时候将查询字符串用于状态管理了，正如它最初的设计初衷。
+这个库为你处理了所有繁琐的工作。
+
+这个库是 NUQS 的一个很好的替代品。
+
+### 使用场景
+
+- 将未保存的用户表单或页面筛选条件存储在 URL 中
+- 将 URL 与 React 状态同步
+- 在不修改 URI 的情况下，直接在无关的客户端组件之间同步数据
+- 支持共享包含应用状态的 URL（深度链接，URL 状态同步）
+- 轻松实现页面刷新后的状态持久化
+
+### 特性
+
+- 🧩 **简单易用**：无需提供者（providers）、reducers 或样板代码，API 类似 `React.useState`，几乎没有学习成本。
+- 📘 **TypeScript 验证/自动补全**：状态是一个对象，根据 TypeScript 定义，IDE 和测试中会自动进行静态验证。
+- ✨ **支持复杂数据**：嵌套对象、日期和数组，像 JSON 一样工作，但存储在 URL 中。
+- ☂ **默认值支持**：如果 URL 中没有参数，会自动使用默认值。
+- ⌨ **结构化定义**：所有可能的值在开始时定义，避免访问不存在的键。
+- **兼容性**：保留第三方查询参数不变。
+- **灵活性**：同一页面可以使用多个状态对象，只需使用不同的键。
+- **快速**：最小化重新渲染，编码和解码大对象仅需约 [1ms](https://github.com/asmyshlyaev177/state-in-url/blob/87c8c7c995c5cd7d9e7aa039c30bfe64b24abe4b/packages/urlstate/encoder/encoder.test.ts#L185)。
+- **服务端渲染支持**：可在 Server Components 中使用，支持 Next.js 14 和 15。
+- **轻量级**：零依赖，库大小小于 2KB。
+- **开发者体验优化**：提供良好的文档、JSDoc 注释和示例。
+- **框架灵活性**：提供 `Next.js` 和 `react-router` 的钩子，以及适用于其他框架或纯 JavaScript 的辅助工具。
+- **全面测试**：包含单元测试和针对 Chrome/Firefox/Safari 的 Playwright 测试（[测试详情](https://github.com/asmyshlyaev177/state-in-url/actions/workflows/tests.yml)）。
+- **宽松的许可证**：MIT 许可证，可自由使用。
 
 ## 目录
 
-- [安装](#安装)
-- [Next.js的`useUrlState`](#nextjs的useurlstate钩子)
-- [React.js的`useSharedState`](#reactjs的usesharedstate钩子)
-- [React.js的`useUrlEncode`](#reactjs的useurlencode钩子)
-- [纯JS使用的`encodeState`和`decodeState`](#纯js使用的encodestate和decodestate辅助函数)
-- [自动同步状态到URL](#自动同步状态)
-- [低级`encode`和`decode`函数](#encode和decode辅助函数)
-- [最佳实践](#最佳实践)
-- [注意事项](#注意事项)
-- [联系与支持](#联系与支持)
-- [更新日志](#更新日志)
-- [许可证](#许可证)
-- [灵感来源](#灵感来源)
+- [安装](#安装)  
+- [`useUrlState` 钩子](#useurlstate)  
+  - [Next.js 专用](#nextjs-专用的-useUrlState-钩子)  
+  - [React-Router 专用](#React-Router-专用的-useUrlState-钩子)  
+- [其他辅助工具](#其他钩子和辅助工具)  
+  - [其他路由器的 `useUrlStateBase` 钩子](#其他路由器的-useUrlStateBase-钩子)  
+  - [React.js/Next.js 的 `useSharedState` 钩子](#reactjs-的-useSharedState-钩子)  
+  - [React.js 的 `useUrlEncode` 钩子](#reactjs-的-useUrlEncode-钩子)  
+  - [纯 JS 使用的 `encodeState` 和 `decodeState` 辅助函数](#encodeState-和-decodeState-辅助函数)  
+  - [底层 `encode` 和 `decode` 函数](#encode-和-decode-辅助函数)  
+- [最佳实践](#最佳实践)  
+  - [注意事项](#注意事项)  
+- [其他](#其他)  
+  - [路线图](#路线图)  
+  - [贡献指南](#贡献指南与本地运行说明)  
+  - [联系与支持](#联系与支持)  
+  - [更新日志](#更新日志)  
+  - [许可证](#许可证)  
+  - [灵感来源](#灵感来源)  
+
+---
 
 ## 安装
 
@@ -83,29 +134,38 @@ yarn add state-in-url
 pnpm add state-in-url
 ```
 
-### 2. 编辑tsconfig.json
+### 2. 编辑 `tsconfig.json`
+
+在 `tsconfig.json` 的 `compilerOptions` 中设置 `"moduleResolution": "Bundler"`，或 `"moduleResolution": "Node16"`，或 `"moduleResolution": "NodeNext"`。  
+可能还需要设置 `"module": "ES2022"` 或 `"module": "ESNext"`。
+
+---
 
-在`tsconfig.json`的`compilerOptions`中设置`"moduleResolution": "Node16"`或`"moduleResolution": "NodeNext"`
+## `useUrlState`
 
-## Next.js的useUrlState钩子
+主钩子，接收初始状态作为参数，返回状态对象、更新 URL 的回调函数以及仅更新状态的回调函数。  
+所有使用相同 `state` 对象的组件会自动同步。
 
-[文档](packages/urlstate/next/useUrlState)
+### Next.js 专用的 `useUrlState` 钩子
 
-`useUrlState`是一个为Next.js应用程序设计的自定义React钩子，使客户端组件之间的通信变得简单。它允许你共享任何复杂的状态并将其与URL搜索参数同步，提供了一种在页面重新加载之间持久化状态并通过URL共享应用程序状态的方法。
+[完整 API 文档](packages/urlstate/next/useUrlState)
 
-### 使用示例
+[React-Router 示例](#React-Router-专用的-useUrlState-钩子)
 
-#### 基本用法
+#### 使用示例
 
-1. 定义状态形状
+##### 基础用法
 
-   ```typescript
-   // countState.ts
-   // 状态形状应该存储在一个常量中，不要直接传递对象
-   export const countState: CountState = { count: 0 }
+1. 定义状态结构及默认值
 
-   type CountState = { count: number }
-   ```
+ ```typescript
+ // userState.ts
+ // 只有与默认值不同的参数会被放入 URL。
+ export const userState: UserState = { name: '', age: 0 }
+
+ // 使用 `Type` 而非 `Interface`！
+ type UserState = { name: string, age: number }
+ ```
 
 2. 导入并使用
 
@@ -113,136 +173,206 @@ pnpm add state-in-url
 'use client'
 import { useUrlState } from 'state-in-url/next';
 
-import { countState } from './countState';
+import { userState } from './userState';
 
 function MyComponent() {
-  // 用于从服务器组件使用searchParams
-  // 例如 export default async function Home({ searchParams }: { searchParams: object }) {
-  // const { state, updateState, updateUrl } = useUrlState(countState, searchParams);
-  const { state, updateState, updateUrl } = useUrlState(countState);
-
-  // 不允许你意外地直接修改状态，需要TS
-  // state.count = 2 // <- 错误
+  // 可以传递 `replace` 参数，控制 `setUrl` 使用 `router.push` 还是 `router.replace`，默认为 replace=true
+  // 可以传递 `searchParams` 从服务端组件传入，如果需要从服务端组件获取数据，传递 `useHistory: false`
+  const { urlState, setUrl, setState, reset } = useUrlState(userState);
 
   return (
     <div>
-      <p>计数：{state.count}</p>
-
-      <button onClick={() => updateUrl({ count: state.count + 1 }), { replace: true }}>
-        增加（更新URL）
-      </button>
-
-      // 与React.useState相同的API
-      <button onClick={() => updateState(currState => ({...currState, count: currState.count + 1 }) )}>
-        增加（仅本地）
-      </button>
-      <button onClick={() => updateUrl()}>
-        同步更改到URL
-        // 或者不同步，只共享状态
-      </button>
-
-      <button onClick={() => updateUrl(state)}>
+      // 如果 URL 为空，urlState.name 将返回 `userState` 的默认值
+      <input value={urlState.name}
+        // 与 React.useState 相同的 API，例如 setUrl(currVal => currVal + 1)
+        onChange={(ev) => setUrl({ name: ev.target.value }) }
+      />
+      <input value={urlState.age}
+        onChange={(ev) => setUrl({ age: +ev.target.value }) }
+      />
+
+      <input value={urlState.name}
+        onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
+        // 可以立即更新状态，但根据需要同步到 URL
+        onBlur={() => setUrl()}
+      />
+
+      <button onClick={reset}>
         重置
       </button>
+
     </div>
   )
 }
 ```
 
-#### 复杂状态形状示例
+##### 自定义钩子以方便处理状态片段
+<details>
+  <Summary>示例</Summary>
 
-```typescript
-interface UserSettings {
-  theme: 'light' | 'dark';
-  fontSize: number;
-  notifications: boolean;
-}
+  ```typescript
+'use client';
 
-export const userSettings: UserSettings {
-  theme: 'light',
-  fontSize: 16,
-  notifications: true,
-}
+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,
+    });
+
+    // 第一次导航会推送新的历史记录
+    // 后续导航将替换该记录
+    // 这样历史记录中只有两个条目 - ['/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 />
+
+##### 复杂状态结构
+
+<details>
+  <Summary>示例</Summary>
+
+```typescript
+export 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 } }[];
+};
 ```
 
 ```typescript
 'use client'
 import { useUrlState } from 'state-in-url/next';
 
-import { userSettings } from './userSettings';
-
-function SettingsComponent() {
-  // `state` 将从UserSettings类型推断！
-  const { state, updateUrl } = useUrlState(userSettings);
-
-  const toggleTheme = () => {
-    updateUrl(current => ({
-      ...current,
-      theme: current.theme === 'light' ? 'dark' : 'light',
-    }));
-  };
-
-  // 空闲时同步状态到URL
-  const timer = React.useRef(0 as unknown as NodeJS.Timeout);
-  React.useEffect(() => {
-    clearTimeout(timer.current);
-    timer.current = setTimeout(() => {
-      // 将通过内容而不是引用比较状态，只为新值触发更新
-      updateUrl(state);
-    }, 500);
+import { form } from './form';
 
-    return () => {
-      clearTimeout(timer.current);
-    };
-  }, [state, updateUrl]);
+function TagsComponent() {
+  // `urlState` 会从 Form 类型推断！
+  const { urlState, setUrl } = useUrlState(form);
+
+  const onChangeTags = React.useCallback(
+    (tag: (typeof tags)[number]) => {
+      setUrl((curr) => ({
+        ...curr,
+        tags: curr.tags.find((t) => t.id === tag.id)
+          ? curr.tags.filter((t) => t.id !== tag.id)
+          : curr.tags.concat(tag),
+      }));
+    },
+    [setUrl],
+  );
 
   return (
     <div>
-      <h2>用户设置</h2>
-      <p>主题：{state.theme}</p>
-      <p>字体大小：{state.fontSize}px</p>
-      <button onClick={toggleTheme}>切换主题</button>
-      {/* 其他UI元素用于更新其他设置 */}
+      <Field text="标签">
+        <div className="flex flex-wrap gap-2">
+          {tags.map((tag) => (
+            <Tag
+              active={!!urlState.tags.find((t) => t.id === tag.id)}
+              text={tag.value.text}
+              onClick={() => onChangeTags(tag)}
+              key={tag.id}
+            />
+          ))}
+        </div>
+      </Field>
     </div>
   );
 }
-...
-
-// 其他组件
-function Component() {
-  const { state } = useUrlState(defaultSettings);
 
-  return (
-    <div>
-      <p>通知 {state.notifications ? '开启' : '关闭'}</p>
-    </div>
-  )
-}
+const tags = [
+  {
+    id: '1',
+    value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') },
+  },
+  {
+    id: '2',
+    value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') },
+  },
+  {
+    id: '3',
+    value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') },
+  },
+];
 ```
 
-#### 自动同步状态
+[示例页面代码](https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/example-nextjs14/src/app/Form.tsx)
+</details>
+
+##### 仅更新状态并手动同步到 URL
+
+<details>
+  <Summary>示例</Summary>
+
+  ```typescript
 
-```typescript
   const timer = React.useRef(0 as unknown as NodeJS.Timeout);
   React.useEffect(() => {
     clearTimeout(timer.current);
     timer.current = setTimeout(() => {
-      // 将通过内容而不是引用比较状态，只为新值触发更新
-      updateUrl(state);
+      // 会比较状态内容而非引用，仅对新值触发更新
+      setUrl(urlState);
     }, 500);
 
     return () => {
       clearTimeout(timer.current);
     };
-  }, [state, updateUrl]);
+  }, [urlState, setUrl]);
 ```
 
-#### 服务器端渲染示例
+在 `onBlur` 时同步状态更符合实际使用场景。
+
+```typescript
+<input onBlur={() => updateUrl()} .../>
+```
+
+</details>
+
+##### 服务端渲染
+
+<details>
+  <Summary>示例</Summary>
 
 ```typescript
 export default async function Home({ searchParams }: { searchParams: object }) {
   return (
-    <Form sp={searchParams} />
+    <Form searchParams={searchParams} />
   )
 }
 
@@ -252,17 +382,21 @@ import React from 'react';
 import { useUrlState } from 'state-in-url/next';
 import { form } from './form';
 
-const Form = ({ sp }: { sp: object }) => {
-  const { state, updateState, updateUrl } = useUrlState(form, sp);
+const Form = ({ searchParams }: { searchParams: object }) => {
+  const { urlState, setState, setUrl } = useUrlState(form, { searchParams });
 }
 ```
 
-#### 在`layout`组件中使用钩子
+</details>
+
+##### 在 `layout` 组件中使用钩子
 
-这是一个棘手的部分，因为使用app router的nextjs不允许从服务器端访问searchParams。有一个使用中间件的解决方法，但它并不漂亮，而且可能在nextjs更新后停止工作。
+<details>
+  <Summary>示例</Summary>
+  这是一个棘手的部分，因为 Next.js 的 app router 不允许从服务端访问 searchParams。可以使用中间件解决，但不够优雅，且可能在 Next.js 更新后失效。
 
 ```typescript
-// 添加到适当的`layout.tsc`
+// 添加到适当的 `layout.tsc`
 export const runtime = 'edge';
 
 // middleware.ts
@@ -282,7 +416,7 @@ export function middleware(request: NextRequest) {
   return response;
 }
 
-// 目标layout组件
+// 目标布局组件
 import { headers } from 'next/headers';
 import { decodeState } from 'state-in-url/encodeState';
 
@@ -300,9 +434,16 @@ export default async function Layout({
     </div>
   );
 }
+
+
 ```
 
-#### 任意状态形状示例（不推荐）
+</details>
+
+##### 任意状态结构（不推荐）
+
+<details>
+  <Summary>示例</Summary>
 
 ```typescript
 'use client'
@@ -311,12 +452,112 @@ 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>
+
+### React-Router 专用的 `useUrlState` 钩子
+
+API 与 Next.js 版本相同，只是可以传递 [NavigateOptions](https://github.com/remix-run/react-router/blob/bc693ed9f39170bda13b9e1b282fb8e9d5925f66/packages/react-router/lib/context.ts#L99) 类型的选项。
+
+[API 文档](packages/urlstate/react-router/useUrlState)
+
+#### 示例
+
+```typescript
+export 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 } }[];
+};
+
+```
+
+```typescript
+import { useUrlState } from 'state-in-url/react-router';
+
+import { form } from './form';
+
+function TagsComponent() {
+  const { urlState, setUrl, setState } = useUrlState(form);
+
+  const onChangeTags = React.useCallback(
+    (tag: (typeof tags)[number]) => {
+      setUrl((curr) => ({
+        ...curr,
+        tags: curr.tags.find((t) => t.id === tag.id)
+          ? curr.tags.filter((t) => t.id !== tag.id)
+          : curr.tags.concat(tag),
+      }));
+    },
+    [setUrl],
+  );
+
+  return (
+    <div>
+      <Field text="标签">
+        <div className="flex flex-wrap gap-2">
+          {tags.map((tag) => (
+            <Tag
+              active={!!urlState.tags.find((t) => t.id === tag.id)}
+              text={tag.value.text}
+              onClick={() => onChangeTags(tag)}
+              key={tag.id}
+            />
+          ))}
+        </div>
+      </Field>
+
+      <input value={urlState.name}
+        onChange={(ev) => { setState(curr => ({ ...curr, name: ev.target.value })) }}
+        // 可以立即更新状态，但根据需要同步到 URL
+        onBlur={() => setUrl()}
+      />
+    </div>
+  );
 }
+
+const tags = [
+  {
+    id: '1',
+    value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') },
+  },
+  {
+    id: '2',
+    value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') },
+  },
+  {
+    id: '3',
+    value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') },
+  },
+];
 ```
 
-## React.js的`useSharedState`钩子
-用于在任何React组件之间共享状态的钩子，已在Next.js和Vite中测试。
+[示例代码](packages/example-react-router6/src/Form-for-test.tsx)
+
+---
+
+## 其他钩子和辅助工具
+
+### 其他路由器的 `useUrlStateBase` 钩子
+
+用于创建与其他路由器（如 react-router 或 tanstack router）兼容的 `useUrlState` 钩子。
+
+[API 文档](packages/urlstate/useUrlStateBase)
+
+### React.js 的 `useSharedState` 钩子
+
+用于在任何 React 组件之间共享状态的钩子，已在 Next.js 和 Vite 中测试。
 
 ```typescript
 'use client'
@@ -329,59 +570,96 @@ function SettingsComponent() {
 }
 ```
 
-[文档](packages/urlstate/useSharedState/README.md)
+[API 文档](packages/urlstate/useSharedState/README.md)
 
-## React.js的`useUrlEncode`钩子
+### React.js 的 `useUrlEncode` 钩子
 
-[文档](packages/urlstate/useUrlEncode/README.md)
+[API 文档](packages/urlstate/useUrlEncode/README.md)
 
-## 纯JS使用的`encodeState`和`decodeState`辅助函数
+### `encodeState` 和 `decodeState` 辅助函数
 
-[文档](packages/urlstate/encodeState/README.md)
+[API 文档](packages/urlstate/encodeState/README.md)
 
-## `encode`和`decode`辅助函数
+### `encode` 和 `decode` 辅助函数
 
-[文档](packages/urlstate/encoder/README.md)
+[API 文档](packages/urlstate/encoder/README.md)
+
+---
 
 ## 最佳实践
 
-- 将您的状态形状定义为常量，以确保一致性
-- 使用TypeScript以增强类型安全性和自动完成功能
-- 避免在URL参数中存储敏感信息
-- 使用`updateState`进行频繁更新，使用`updateUrl`同步更改到URL
-- 在Next.js中使用`Suspence`包装客户端组件
-- 使用这个[扩展](https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors)以获得可读的TS错误
+- 将状态结构定义为常量
+- 使用 TypeScript 增强类型安全和自动补全
+- 避免在 URL 参数中存储敏感信息（如 SSN、API 密钥等）
+- 使用此 [扩展](https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors) 以获得可读的 TS 错误提示
+
+可以为状态片段创建状态钩子，并在应用程序中重复使用。例如：
+```Typescript
+type UserState = {
+  name: string;
+  age: number;
+  other: { id: string, value: number }[]
+};
+const userState = {
+  name: '',
+  age: 0,
+  other: [],
+};
+
+export const useUserState = () => {
+  const { urlState, setUrl, reset } = useUrlState(userState);
+
+  // 其他逻辑
+
+  // 导航到其他页面时重置查询参数
+  React.useEffect(() => {
+    return reset
+  }, [])
+
+  return { userState: urlState, setUserState: setUrl };;
+}
+
+```
 
 ## 注意事项
 
-1. 只能传递可序列化的值，`Function`、`BigInt`或`Symbol`不会工作，可能类似`ArrayBuffer`的东西也不行。
-2. Vercel服务器限制头部（查询字符串和其他内容）的大小为**14KB**，所以保持您的URL状态在~5000个单词以下。https://vercel.com/docs/errors/URL_TOO_LONG
-3. 已在使用app router的`next.js` 14中测试，不计划支持pages。
+1. 只能传递可序列化的值，`Function`、`BigInt` 或 `Symbol` 无法使用，`ArrayBuffer` 等也可能无法使用。任何可以序列化为 JSON 的内容都可以使用。
+2. Vercel 服务器限制标头大小（查询字符串和其他内容）为 **14KB**，因此请将 URL 状态保持在约 5000 字以内。<https://vercel.com/docs/errors/URL_TOO_LONG>
+3. 已在 `next.js` 14/15 的 app router 中测试，暂无支持 pages 的计划。
 
-## 本地运行
+---
 
-克隆此仓库，运行`npm install`然后
+## 其他
 
-```sh
-npm run dev
-```
+### 贡献指南与本地运行说明
 
-转到[localhost:3000](http://localhost:3000)
+参见 [贡献文档](CONTRIBUTING.md)
+
+## 路线图
+
+- [x] `Next.js` 钩子
+- [x] `react-router` 钩子
+- [ ] `remix` 钩子
+- [ ] `svelte` 钩子
+- [ ] `astro` 钩子
+- [ ] 在 hash 中存储状态的钩子？
 
 ## 联系与支持
 
-- 创建[GitHub issue](https://github.com/asmyshlyaev177/state-in-url/issues)报告bug、提出功能请求或提问
+- 创建 [GitHub issue](https://github.com/asmyshlyaev177/state-in-url/issues) 以报告错误、请求功能或提出问题
 
-## [更新日志](https://github.com/asmyshlyaev177/state-in-url/blob/master/CHANGELOG.md)
+## [更新日志](CHANGELOG.md)
 
 ## 许可证
 
-本项目采用[MIT许可证](https://github.com/asmyshlyaev177/state-in-url/blob/master/LICENSE)。
+本项目采用 [MIT 许可证](LICENSE)。
 
 ## 灵感来源
 
-[在Vue中使用URL存储状态](https://dev.to/jacobandrewsky/using-url-to-store-state-in-vue-275c)
+[NUQS](https://github.com/47ng/nuqs)
+
+[在 Vue 中使用 URL 存储状态](https://dev.to/jacobandrewsky/using-url-to-store-state-in-vue-275c)
 
-[在URL中存储状态](https://antonz.org/storing-state/)
+[在 URL 中存储状态](https://antonz.org/storing-state/)
 
-[NextJS useSearchParams](https://nextjs.org/docs/app/api-reference/functions/use-search-params)
+[NextJS useSearchParams](https://nextjs.org/docs/app/api-reference/functions/use-search-params)

package/README.md

@@ -57,6 +57,8 @@ Share if it useful for you.
 
   </div>
 
+[Just Show Me Code!](#useurlstate)
+
 ## Why use `state-in-url`?
 
 Store any user state in query parameters; imagine JSON in a browser URL. All of it with keeping types and structure of data, e.g. numbers will be decoded as numbers not strings, dates as dates, etc, objects and arrays supported.

package/dist/constants/constants.mjs

@@ -1 +1 @@
-import{isSafari as e}from"../utils.mjs";const d={date:"\u23F2",undefined:"\u2219undefined"},i=e?330:70;export{d as SYMBOLS,i as TIMEOUT};
+import{isSafari as e}from"../utils.mjs";const n={date:"\u23F2",undefined:"\u2219undefined"};const d=e?330:70;export{n as SYMBOLS,d as TIMEOUT};

package/dist/encodeState/encodeState.mjs

@@ -1 +1 @@
-import{encode as f,decode as a}from"../encoder/encoder.mjs";import{getParams as i}from"../utils.mjs";function m(o,e,n){const r=i(n);return Object.entries(o||{}).forEach(([t,c])=>{const s=e?.[t];JSON.stringify(c)!==JSON.stringify(s)&&r.set(t,f(c))}),r.toString()}function d(o,e){return{...e||{},...Object.fromEntries([...i(o).entries()].map(([n,r])=>{const t=e?.[n];return[n,a(r,t)??t]}))}}export{d as decodeState,m as encodeState};
+import{decode as f,encode as m}from"../encoder/encoder.mjs";import{getParams as c}from"../utils.mjs";function a(r,e,n){const o=c(n);for(const[t,i]of Object.entries(r||{})){const s=e?.[t];if(JSON.stringify(i)!==JSON.stringify(s)){o.set(t,m(i))}}return o.toString()}function d(r,e){return{...e||{},...Object.fromEntries([...c(r).entries()].map(([n,o])=>{const t=e?.[n];return[n,f(o,t)??t]}))}}export{d as decodeState,a as encodeState};

package/dist/encoder/encoder.mjs

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

package/dist/next/useUrlState/useUrlState.mjs

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

package/dist/parseSPObj.mjs

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

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

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

package/dist/subscribers.d.ts

@@ -6,6 +6,6 @@ export declare const subscribers: {
 };
 export declare const stateMap: {
     get: <T extends JSONCompatible | undefined>(objKey: T) => T | undefined;
-    set: <T_1 extends JSONCompatible>(objKey: T_1, value: T_1) => void;
+    set: <T extends JSONCompatible>(objKey: T, value: T) => void;
 };
 export type Cb = () => void;

package/dist/subscribers.mjs

@@ -1 +1 @@
-const r=new WeakMap,s=new WeakMap,o={get(t){return s.get(t)||[]},add(t,e){const n=this.get(t);return s.set(t,n.concat(e)),()=>this.remove(t,e)},remove(t,e){const n=this.get(t).filter(c=>c!==e);n.length?s.set(t,n):s.delete(t)}},a={get:function(t){return r.get(t)},set:function(t,e){r.set(t,e)}};export{a as stateMap,o as subscribers};
+const o=new WeakMap;const n=new WeakMap;const a={get(t){return n.get(t)||[]},add(t,e){const s=this.get(t);n.set(t,s.concat(e));return()=>this.remove(t,e)},remove(t,e){const s=this.get(t);const c=s.filter(r=>r!==e);if(c.length){n.set(t,c)}else{n.delete(t)}}};const i={get:function(t){return o.get(t)},set:function(t,e){o.set(t,e)}};export{i as stateMap,a as subscribers};

package/dist/useSharedState/useSharedState.mjs

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

package/dist/useUrlEncode/useUrlEncode.d.ts

@@ -30,7 +30,7 @@ console.log(state); // Output: { name: 'Tom' }
  *
  *  * Docs {@link https://github.com/asmyshlyaev177/state-in-url/tree/master/packages/urlstate/useUrlEncode#parse}
  */
-    parse: (strOrSearchParams: string | URLSearchParams) => T;
+    parse: (strOrSearchParams: string | URLSearchParams) => typeof stateShape;
     /**
 Converts a state object to a URL query string.
 * * Example:

package/dist/useUrlEncode/useUrlEncode.mjs

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

package/dist/useUrlStateBase/useUrlStateBase.d.ts

@@ -37,7 +37,7 @@ export declare function useUrlStateBase<T extends JSONCompatible>(defaultState:
     parse: ReturnType<typeof useUrlEncode<T>>["parse"];
 }) => T): {
     updateState: (value: Partial<T> | ((currState: T) => T)) => void;
-    updateUrl: (value?: Partial<T> | ((currState: T) => T) | undefined, options?: Options) => void;
+    updateUrl: (value?: Parameters<(value: Partial<T> | ((currState: T) => T)) => void>[0], options?: Options) => void;
     state: T;
     reset: (options?: Options) => void;
     getState: () => T;

package/dist/useUrlStateBase/useUrlStateBase.mjs

@@ -1 +1 @@
-import i from"react";import{TIMEOUT as R}from"../constants/constants.mjs";import{useInsertionEffect as T}from"../useInsertionEffect.mjs";import{useSharedState as v}from"../useSharedState/useSharedState.mjs";import{useUrlEncode as L}from"../useUrlEncode/useUrlEncode.mjs";import{filterUnknownParamsClient as P}from"../utils.mjs";function b(t,o,u){const{parse:a,stringify:n}=L(t),{state:l,getState:r,setState:s}=v(t,()=>u?.({parse:a})||t),m=i.useRef(void 0);T(()=>{const e=()=>{const w=a(P(t));s(w)};return window.addEventListener(U,e),()=>{window.removeEventListener(U,e),clearTimeout(m.current)}},[s]);const c=i.useRef([]),p=i.useCallback((e,w)=>{const d=typeof e=="function"?e(r()):{...r(),...e},h=n(d,y(t)),S=`${window.location.pathname}${h.length?"?":""}${h}${window.location.hash}`,$=`${window.location.pathname}${window.location.search}${window.location.hash}`;if(S===$)return;s(d);const{replace:g,...k}=w||{};c.current.push([g?"replace":"push",S,k]),clearTimeout(m.current),queueMicrotask(()=>{c.current.length&&(m.current=setTimeout(()=>{const f=c.current.at(-1);c.current=[],o[f[0]](f[1],f[2])},R))})},[o,n,r]),E=i.useCallback(e=>{p(t,e)},[p]);return{updateState:s,updateUrl:p,state:l,reset:E,getState:r}}function y(t){const o=Object.keys(t),u=window.location.search,a=new URLSearchParams(u),n=new URLSearchParams;return a.forEach((l,r)=>!o.includes(r)&&n.set(r,l)),n}const U="popstate";export{b as useUrlStateBase};
+import u from"react";import{TIMEOUT as y}from"../constants/constants.mjs";import{useInsertionEffect as L}from"../useInsertionEffect.mjs";import{useSharedState as T}from"../useSharedState/useSharedState.mjs";import{useUrlEncode as v}from"../useUrlEncode/useUrlEncode.mjs";import{filterUnknownParamsClient as R}from"../utils.mjs";function b(t,c,f){const{parse:s,stringify:r}=v(t);const{state:a,getState:n,setState:o}=T(t,()=>f?.({parse:s})||t);const l=u.useRef(void 0);L(()=>{const e=()=>{const m=s(R(t,P()));o(m)};window.addEventListener($,e);return()=>{window.removeEventListener($,e);clearTimeout(l.current)}},[o]);const i=u.useRef([]);const w=u.useCallback((e,m)=>{const d=typeof e==="function"?e(n()):{...n(),...e};const h=r(d,C(t));const S=`${window.location.pathname}${h.length?"?":""}${h}${window.location.hash}`;const g=`${window.location.pathname}${window.location.search}${window.location.hash}`;if(S===g)return;o(d);const{replace:k,...E}=m||{};i.current.push([k?"replace":"push",S,E]);clearTimeout(l.current);queueMicrotask(()=>{if(!i.current.length)return;l.current=setTimeout(()=>{const p=i.current.at(-1);i.current=[];c[p[0]](p[1],p[2])},y)})},[c,r,n]);const U=u.useCallback(e=>{o(t);w(t,e)},[w,o]);return{updateState:o,updateUrl:w,state:a,reset:U,getState:n}}function C(t){const c=Object.keys(t);const f=window.location.search;const s=new URLSearchParams(f);const r=new URLSearchParams;for(const[a,n]of s){!c.includes(a)&&r.set(a,n)}return r}const $="popstate";function P(){return typeof window!=="undefined"&&window.location.search||""}export{b as useUrlStateBase};

package/dist/utils.d.ts

@@ -22,7 +22,7 @@ export type UnknownObj = object | {
     [key: string]: unknown;
 };
 export declare const isEqual: (val1: unknown, val2: unknown) => boolean;
-export declare function filterUnknownParamsClient<T extends object>(shape: T): string;
+export declare function filterUnknownParamsClient<T extends object>(shape: T, params: string | URLSearchParams | Record<string, string> | object): 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;

package/dist/utils.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "description": "Store state in URL as in object, types and structure are preserved, with TS validation. Same API as React.useState, wthout any hasssle or boilerplate. Next.js@14-15 and react-router@6-7.",
   "homepage": "https://state-in-url.dev",
   "repository": {
@@ -14,7 +14,8 @@
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
-    "tag": "latest"
+    "tag": "latest",
+    "provenance": false
   },
   "license": "MIT",
   "funding": {
@@ -352,8 +353,9 @@
     "@vitest/coverage-istanbul": "^2.1.5",
     "auto-changelog": "^2.4.0",
     "babel-plugin-module-resolver": "^5.0.2",
-    "chokidar": "^4.0.1",
+    "chokidar": "^4.0.3",
     "commitizen": "^4.3.0",
+    "commitlint": "^19.8.0",
     "conventional-recommended-bump": "^10.0.0",
     "cross-env": "^7.0.3",
     "cz": "^1.8.2",
@@ -374,18 +376,18 @@
     "prettier": "^3.2.5",
     "prettier-plugin-tailwindcss": "^0.6.8",
     "release-it": "^17.6.0",
-    "rollup": "^4.23.0",
-    "rollup-plugin-esbuild": "^6.1.1",
+    "rollup": "^4.39.0",
+    "rollup-plugin-esbuild": "^6.2.1",
     "rollup-plugin-filesize": "^10.0.0",
     "rollup-plugin-sourcemaps": "^0.6.3",
     "semantic-release": "^24.1.0",
     "standard-version": "^9.5.0",
     "ts-node": "^10.9.2",
-    "typescript": "^5.3.3",
+    "typescript": "^5.8.2",
     "unplugin-auto-import": "^0.18.5",
     "vitest": "^2.1.5",
     "wait-on": "^8.0.1",
-    "wireit": "^0.14.9"
+    "wireit": "^0.14.11"
   },
   "keywords": [
     "state in url",