react-magic-search-params 1.2.0 → 2.1.2

package/README.md

@@ -1,98 +1,69 @@
-[![Version](https://img.shields.io/npm/v/react-magic-search-params?style=flat-square&color=blue)](https://www.npmjs.com/package/react-magic-search-params)
-[![Downloads](https://img.shields.io/npm/dm/react-magic-search-params?style=flat-square&color=green)](https://www.npmjs.com/package/react-magic-search-params)
-[![License: MIT](https://img.shields.io/npm/l/react-magic-search-params?style=flat-square&color=yellow)](https://opensource.org/licenses/MIT)
-[![React](https://img.shields.io/badge/React-%5E16.8.0-blue)](https://reactjs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-%5E3.8-blueviolet)](https://www.typescriptlang.org/)
-[![Issues](https://img.shields.io/github/issues/user/react-magic-search-params?style=flat-square&color=red)](https://github.com/user/react-magic-search-params/issues)
-# `react-magic-search-params` 🪄 <img src="https://static-production.npmjs.com/255a118f56f5346b97e56325a1217a16.svg" width="20px" height="20px" title="This package contains built-in TypeScript declarations" alt="TypeScript icon, indicating that this package has built-in type declarations">
-
-<img src="https://github.com/user-attachments/assets/1f437570-6f30-4c10-b27d-b876f5c557bd" alt="Screenshot" width="800px" />
-
-Centralize and type your search parameters (query params) handling in React Router v6+ with TypeScript.
-
----
-
-## 📖 Introduction
-
-`useMagicSearchParams` allows you to:
-- Define **required** and **optional** parameters in one place.
-- Get typed values (`number`, `string`, `boolean`, `array`).
-- Update or clear the URL without repeating logic.
-- Serialize arrays in `csv`, `repeat` or `brackets` format.
-- Force values (`forceParams`) or omit neutral values (`omitParamsByValues`).
-
----
-
-## 🚀 Installation
-
-```bash
-npm install react-magic-search-params
-```
-
-## Basic Usage
-
-```jsx
-import { useMagicSearchParams } from 'react-magic-search-params';
-import { paramsUsers } from './constants';
-
-const { getParams, updateParams, clearParams } = useMagicSearchParams({
-  ...paramsUsers,
-  defaultParams: paramsUsers.mandatory,
-  forceParams:   { page_size: 10 },
-  omitParamsByValues: ['all','default'],
-  arraySerialization: 'csv',
-});
-
-// Get typed values:
-const { page, search, tags } = getParams({ convert: true });
-
-// Change page:
-updateParams({ newParams: { page: (page ?? 1) + 1 } });
-
-// Clear filters:
-clearParams();
-```
-
-### 📁 Recommended Constants File
-
-```ts
-type UserTagOptions = 'tag1' | 'tag2' | 'react' | 'node' | 'typescript' | 'javascript';
-type OrderUserProps = 'role' | 'date';
-
-export const paramsUsers = {
-  mandatory: { 
-    page: 1,
-    page_size: 10 as const,
-    only_is_active: false,
-  },
-  optional:  { 
-    order: '' as OrderUserProps,
-    search: '',
-    tags: ['tag1','tag2'] as Array<UserTagOptions>
-  },
-};
-```
-
-### 🌟 Key Functions
-
-- `getParams(opts?)` → returns typed params.
-- `updateParams({ newParams, keepParams? })` → updates the URL.
-- `clearParams({ keepMandatoryParams? })` → clears parameters.
-- `onChange(key, callbacks[])` → subscribes to parameter changes.
-
----
-
-### 🔄 Array Serialization
-
-| Method     | Example URL                          |
-|------------|--------------------------------------|
-| `csv`      | `tags=tag1,tag2,tag3`                |
-| `repeat`   | `tags=tag1&tags=tag2&tags=tag3`      |
-| `brackets` | `tags[]=tag1&tags[]=tag2&tags[]=tag3` |
-
-## 🔗 Complete Documentation
-
-Find the complete guide and examples on GitHub:  
-https://github.com/Gabriel117343/react-magic-search-params
-
-If you found this library helpful, please give it a ⭐️ on GitHub!
+[![Version](https://img.shields.io/npm/v/react-magic-search-params?style=flat-square&color=blue)](https://www.npmjs.com/package/react-magic-search-params)
+[![Downloads](https://img.shields.io/npm/dm/react-magic-search-params?style=flat-square&color=green)](https://www.npmjs.com/package/react-magic-search-params)
+[![License: MIT](https://img.shields.io/npm/l/react-magic-search-params?style=flat-square&color=yellow)](https://opensource.org/licenses/MIT)
+[![React](https://img.shields.io/badge/React-18%20%7C%2019-blue)](https://react.dev)
+
+# react-magic-search-params
+
+![react-magic-search-params hero](https://raw.githubusercontent.com/Gabriel117343/react-magic-search-params/main/public/hero.png)
+
+Type-safe query/search parameter management for React Router, built as an extension over useSearchParams.
+
+## Installation
+
+```bash
+npm install react-magic-search-params
+```
+
+## Compatibility
+
+- React 18.x and 19.x
+- React Router DOM 6+
+- Node.js 18+
+
+## Basic Usage
+
+```tsx
+import { useMagicSearchParams } from 'react-magic-search-params';
+
+const paramsUsers = {
+  mandatory: {
+    page: 1,
+    page_size: 10 as const,
+    only_is_active: false,
+    tags: ['uno', 'dos', 'tres'] as string[],
+  },
+  optional: {
+    search: '',
+    order: '',
+  },
+};
+
+const { getParams, updateParams, clearParams } = useMagicSearchParams({
+  ...paramsUsers,
+  defaultParams: paramsUsers.mandatory,
+  forceParams: { page_size: 10 },
+  arraySerialization: 'csv',
+  omitParamsByValues: ['all', 'default'],
+});
+
+const { page, search, tags } = getParams({ convert: true });
+
+updateParams({ newParams: { page: (page ?? 1) + 1 } });
+updateParams({ newParams: { tags: 'react' } });
+clearParams({ keepMandatoryParams: true });
+```
+
+## API
+
+- `getParams({ convert?: boolean })`
+- `getParam(key, { convert?: boolean })`
+- `updateParams({ newParams?, keepParams? })`
+- `clearParams({ keepMandatoryParams?: boolean })`
+- `onChange(paramName, callbacks[])`
+
+## Full Documentation
+
+The full guide, advanced patterns, and detailed explanations are in the repository README:
+
+https://github.com/Gabriel117343/react-magic-search-params

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var V=Object.defineProperty;var ie=Object.getOwnPropertyDescriptor;var ue=Object.getOwnPropertyNames;var me=Object.prototype.hasOwnProperty;var Pe=(m,d)=>{for(var g in d)V(m,g,{get:d[g],enumerable:!0})},le=(m,d,g,p)=>{if(d&&typeof d=="object"||typeof d=="function")for(let y of ue(d))!me.call(m,y)&&y!==g&&V(m,y,{get:()=>d[y],enumerable:!(p=ie(d,y))||p.enumerable});return m};var pe=m=>le(V({},"__esModule",{value:!0}),m);var ge={};Pe(ge,{useMagicSearchParams:()=>Y});module.exports=pe(ge);var Q=require("react-router-dom"),P=require("react"),Y=({mandatory:m={},optional:d={},defaultParams:g={},arraySerialization:p="csv",forceParams:y={},omitParamsByValues:q=[],codecs:F={},historyMode:E="push",resetOnChange:G={},paginationStrategy:w,unknownParamsPolicy:A="drop"})=>{let[i,L]=(0,Q.useSearchParams)(),j=(0,P.useRef)({}),U=(0,P.useRef)({}),I=(0,P.useCallback)((e,r)=>{L(e,{replace:(r??E)==="replace"})},[L,E]),l=(0,P.useMemo)(()=>({...m,...d}),[m,d]),J=(0,P.useMemo)(()=>Array.from(Object.keys(l)),[l]),v=(0,P.useCallback)(e=>Object.prototype.hasOwnProperty.call(l,e),[l]),X=e=>!Array.isArray(l[e])||p==="csv"?i.get(e):p==="repeat"?i.getAll(e):i.getAll(`${e}[]`),B=(0,P.useCallback)(()=>{if(A==="drop")return[];let e=[];for(let[r,a]of i.entries()){let s=r.endsWith("[]")?r.replace("[]",""):r;v(s)||e.push([r,a])}return e},[A,i,v]),H=(0,P.useCallback)(e=>{if(A==="drop")return e;let r=new URLSearchParams(e.toString()),a=B();for(let[s,t]of a)r.append(s,t);return r},[A,B]),_=(e,r)=>Array.isArray(e)&&Array.isArray(r)?e.length!==r.length?!1:e.every((a,s)=>a===r[s]):e===r,C=(0,P.useMemo)(()=>Object.keys(l).filter(e=>Array.isArray(l[e])),[l]),Z=(e,r)=>{let a={...e};return C.length===0||C.forEach(s=>{let t=[];switch(p){case"csv":{t=(i.get(s)||"").split(",").map(o=>o.trim()).filter(Boolean);break}case"repeat":{let n=i.getAll(s);t=n.length>0?n:[];break}case"brackets":{let n=i.getAll(`${s}[]`);t=n.length>0?n:[];break}default:t=(i.get(s)??"").split(",").map(o=>o.trim()).filter(Boolean)}if(r[s]!==void 0){let n=r[s],o=[];typeof n=="string"?o=t.includes(n)?t.filter(u=>u!==n):[...t,n]:Array.isArray(n)?o=Array.from(new Set([...n.map(String)])):o=t,a[s]=o}}),a},O=e=>{let r=new URLSearchParams,a=Object.keys(e);for(let s of a){let t=F[s];if(t?.serialize){let n=t.serialize(e[s],{key:s});if(n==null)continue;if(Array.isArray(n))if(Array.isArray(l[s]))if(p==="csv")r.set(s,n.join(","));else if(p==="repeat")for(let o of n)r.append(s,String(o));else for(let o of n)r.append(`${s}[]`,String(o));else n.length>0&&r.set(s,String(n[0]));else r.set(s,String(n));continue}if(Array.isArray(l[s])){let n=e[s];switch(p){case"csv":{r.set(s,n.join(","));break}case"repeat":{for(let o of n)r.append(s,String(o));break}case"brackets":{for(let o of n)r.append(`${s}[]`,String(o));break}default:r.set(s,n.join(","))}}else r.set(s,String(e[s]))}return r},h=(e,r)=>Object.prototype.hasOwnProperty.call(m,e)?m[e]:Object.prototype.hasOwnProperty.call(g,e)?g[e]:r,W=({paramsForced:e,compareParams:r})=>Object.entries(e).every(([s,t])=>r[s]===t),x=e=>{let r=X(e),a=F[e];if(a?.parse)return a.parse(r,{key:e,searchParams:i});if(typeof l[e]=="number"){let s=Number.parseInt(String(r??""),10);if(Number.isNaN(s)){let t=h(e,0);return typeof t=="number"?t:0}return s}return typeof l[e]=="boolean"?String(r)==="true":Array.isArray(l[e])?p==="csv"?String(r??"").split(",").filter(Boolean):Array.isArray(r)?r:r?[r]:[]:Array.isArray(r)?r[0]??"":r??""},$=(e,r)=>{if(Array.isArray(l[e])){if(p==="brackets"){let t=i.getAll(`${e}[]`),n=O({[e]:t}).toString();return decodeURIComponent(n)}if(p==="csv"){let t=i.getAll(e),n=O({[e]:t}).toString();return decodeURIComponent(n)}let s=i.getAll(e);return O({[e]:s}).toString()}return r[e]},z=e=>{let r={};for(let[a,s]of e.entries())if(a.endsWith("[]")){let t=a.replace("[]","");r[t]?r[t].push(s):r[t]=[s]}else r[a]?Array.isArray(r[a])?r[a].push(s):r[a]=[r[a],s]:r[a]=s;return r},S=(0,P.useMemo)(()=>p==="brackets"?z(i):Object.fromEntries(i.entries()),[i,p]),M=({convert:e=!0}={})=>Object.keys(S).reduce((a,s)=>{if(Object.prototype.hasOwnProperty.call(l,s)){let t=p==="brackets"?s.replace("[]",""):s;a[t]=e===!0?x(t):$(s,S)}return a},{}),K=(e,r)=>{let a=String(e);return r?.convert!==!1?x(a):$(a,S)},ee=e=>e==null||typeof e!="object"?!1:Object.prototype.hasOwnProperty.call(e,"newParams")||Object.prototype.hasOwnProperty.call(e,"keepParams")||Object.prototype.hasOwnProperty.call(e,"historyMode"),re=e=>{let r=M({convert:!0});if(typeof e=="function"){let a=e(r);return ee(a)?{newParams:typeof a.newParams=="function"?a.newParams(r):a.newParams??{},keepParams:a.keepParams??{},historyMode:a.historyMode}:{newParams:a,keepParams:{},historyMode:void 0}}return e?{newParams:typeof e.newParams=="function"?e.newParams(r):e.newParams??{},keepParams:e.keepParams??{},historyMode:e.historyMode}:{newParams:{},keepParams:{},historyMode:void 0}},se=({currentParams:e,newParams:r,keepParams:a})=>{let s={...r},t={...a};for(let[n,o]of Object.entries(G))if(!(!o||o.length===0||!Object.prototype.hasOwnProperty.call(s,n)||_(s[n],e[n]))){for(let c of o)if(!Object.prototype.hasOwnProperty.call(y,c)){if(Object.prototype.hasOwnProperty.call(m,c)){s[c]=m[c],delete t[c];continue}if(Object.prototype.hasOwnProperty.call(g,c)){s[c]=g[c],delete t[c];continue}delete s[c],t[c]=!1}}return{newParams:s,keepParams:t}},ae=(e,r)=>{let a=M(),s=Object.entries(e).filter(([o])=>!Array.isArray(l[o])),t=Object.assign({...a,...Object.fromEntries(s)},y),n=Object.keys(t).reduce((o,u)=>{if(Object.prototype.hasOwnProperty.call(r,u)&&r[u]===!1)return o;let c=t[u],b=typeof c=="string"&&q.includes(c);return c!=null&&c!==""&&!b&&(o[u]=c),o},{});return{...m,...n}},te=e=>J.reduce((a,s)=>(Object.prototype.hasOwnProperty.call(e,s)&&(a[s]=e[s]),a),{}),ne=()=>{let e=C.length>0,r=M({convert:e});return Object.keys(r).reduce((s,t)=>(Object.prototype.hasOwnProperty.call(m,t)&&(s[t]=r[t]),s),{})},D=({keepMandatoryParams:e=!0,historyMode:r}={})=>{let a=O({...m,...e&&{...ne()},...y}),s=H(a);I(s,r)},f=e=>{let r=re(e),a=M({convert:!0}),s=se({currentParams:a,newParams:r.newParams,keepParams:r.keepParams}),t=s.newParams,n=s.keepParams;if(Object.keys(t).length===0&&Object.keys(n).length===0){D({historyMode:r.historyMode});return}let o=ae(t,n),u=Z(o,t),c=te(u),b=O(c),T=H(b);I(T,r.historyMode)},k=w?.mode==="page"?w:void 0,R=w?.mode==="offset"?w:void 0,N=w?.mode==="cursor"?w:void 0,oe={mode:w?.mode??"page",next:e=>{let r=w?.mode??"page";if(r==="cursor"){let n=N?.cursorKey??"cursor";typeof e=="string"&&f({newParams:{[n]:e}});return}if(r==="offset"){let n=R?.offsetKey??"offset",o=R?.limitKey??"limit",u=Number(K(n,{convert:!0})??0),c=Number(K(o,{convert:!0})??h(String(o),10)),b=Number.isFinite(u)?u:0,T=Number.isFinite(c)&&c>0?c:10;f({newParams:{[n]:b+T}});return}let a=k?k.pageKey??"page":"page",s=Number(K(a,{convert:!0})??h(String(a),1)),t=Number.isFinite(s)&&s>0?s:1;f({newParams:{[a]:t+1}})},prev:()=>{let e=w?.mode??"page";if(e==="cursor"){let t=N?.cursorKey??"cursor";f({keepParams:{[t]:!1}});return}if(e==="offset"){let t=R?.offsetKey??"offset",n=R?.limitKey??"limit",o=Number(K(t,{convert:!0})??0),u=Number(K(n,{convert:!0})??h(String(n),10)),c=Number.isFinite(o)?o:0,b=Number.isFinite(u)&&u>0?u:10;f({newParams:{[t]:Math.max(0,c-b)}});return}let r=k?k.pageKey??"page":"page",a=Number(K(r,{convert:!0})??h(String(r),1)),s=Number.isFinite(a)&&a>0?a:1;f({newParams:{[r]:Math.max(1,s-1)}})},reset:()=>{let e=w?.mode??"page";if(e==="cursor"){let s=N?.cursorKey??"cursor";f({keepParams:{[s]:!1}});return}if(e==="offset"){let s=R?.offsetKey??"offset",t=Number(h(String(s),0));f({newParams:{[s]:Number.isFinite(t)?t:0}});return}let r=k?k.pageKey??"page":"page",a=Number(h(String(r),1));f({newParams:{[r]:Number.isFinite(a)&&a>0?a:1}})},setCursor:e=>{let a=(w?.mode??"page")==="cursor"?N?.cursorKey??"cursor":"cursor";if(e==null||e===""){f({keepParams:{[a]:!1}});return}f({newParams:{[a]:e}})}},ce=(0,P.useCallback)((e,r)=>{let a=String(e);return j.current[a]=r,()=>{delete j.current[a],delete U.current[a]}},[]);return(0,P.useEffect)(()=>{for(let[e,r]of Object.entries(j.current)){let a=v(e)?x(e):i.get(e),s=U.current[e]??null;if(!_(a,s))for(let t of r)t({key:e,previousValue:s,currentValue:a});U.current[e]=a}},[S,v,i]),(0,P.useEffect)(()=>{let e=Object.keys(g),r=Object.keys(y);if(e.length===0&&r.length===0)return;function a(){let s=O(g).toString(),t=M(),n=O(t).toString();if(!W({paramsForced:y,compareParams:t})){f({newParams:{...g,...y}});return}let u=W({paramsForced:y,compareParams:g});if(e.length>0&&u){if(s===n)return;f({newParams:g})}}a()},[]),{searchParams:i,updateParams:f,clearParams:D,getParams:M,getParam:K,onChange:ce,pagination:oe}};0&&(module.exports={useMagicSearchParams});

package/dist/index.d.mts

@@ -0,0 +1,101 @@
+type CommonParams = {
+    page?: number;
+    page_size?: number;
+};
+type MergeParams<M, O> = {
+    [K in keyof M]: M[K];
+} & {
+    [K in keyof O]?: O[K];
+};
+type ParamCodec<TValue> = {
+    parse?: (value: string | string[] | null, context: {
+        key: string;
+        searchParams: URLSearchParams;
+    }) => TValue;
+    serialize?: (value: TValue, context: {
+        key: string;
+    }) => string | string[] | null | undefined;
+};
+type ParamCodecs<TParams extends Record<string, unknown>> = Partial<{
+    [K in keyof TParams]: ParamCodec<TParams[K]>;
+}>;
+type ParamKey<TParams extends Record<string, unknown>> = Extract<keyof TParams, string>;
+type PaginationStrategy<TParams extends Record<string, unknown>> = {
+    mode: 'page';
+    pageKey?: ParamKey<TParams>;
+    pageSizeKey?: ParamKey<TParams>;
+} | {
+    mode: 'offset';
+    offsetKey?: ParamKey<TParams>;
+    limitKey?: ParamKey<TParams>;
+} | {
+    mode: 'cursor';
+    cursorKey?: ParamKey<TParams>;
+};
+type ResetOnChangeRules<TParams extends Record<string, unknown>> = Partial<Record<ParamKey<TParams>, Array<ParamKey<TParams>>>>;
+type UnknownParamsPolicy = 'drop' | 'preserve';
+type HistoryMode = 'push' | 'replace';
+type BuiltInOmitParamValue = 'all' | 'default' | 'unknown' | 'none' | 'void';
+type OmitParamValue = BuiltInOmitParamValue | (string & {});
+type OnChangeEvent<TParams extends Record<string, unknown>> = {
+    key: keyof TParams;
+    previousValue: unknown;
+    currentValue: unknown;
+};
+type OnChangeCallback<TParams extends Record<string, unknown>> = ((event: OnChangeEvent<TParams>) => void) | (() => void);
+/**
+ * Interface for the configuration object that the hook receives
+ */
+interface UseMagicSearchParamsOptions<M extends Record<string, unknown>, O extends Record<string, unknown>> {
+    mandatory: M;
+    optional?: O;
+    defaultParams?: Partial<MergeParams<M, O>>;
+    forceParams?: Partial<MergeParams<M, O>>;
+    arraySerialization?: 'csv' | 'repeat' | 'brackets';
+    omitParamsByValues?: Array<OmitParamValue>;
+    codecs?: ParamCodecs<MergeParams<M, O>>;
+    historyMode?: HistoryMode;
+    resetOnChange?: ResetOnChangeRules<MergeParams<M, O>>;
+    paginationStrategy?: PaginationStrategy<MergeParams<M, O>>;
+    unknownParamsPolicy?: UnknownParamsPolicy;
+}
+/**
+Generic hook to handle search parameters in the URL
+@param mandatory - Mandatory parameters (e.g., page=1, page_size=10, etc.)
+@param optional - Optional parameters (e.g., order, search, etc.)
+@param defaultParams - Default parameters sent in the URL on initialization
+@param forceParams - Parameters forced into the URL regardless of user input
+@param omitParamsByValues - Parameters omitted if they have specific values
+*/
+declare const useMagicSearchParams: <M extends Record<string, unknown> & CommonParams, O extends Record<string, unknown>>({ mandatory, optional, defaultParams, arraySerialization, forceParams, omitParamsByValues, codecs, historyMode, resetOnChange, paginationStrategy, unknownParamsPolicy }: UseMagicSearchParamsOptions<M, O>) => {
+    searchParams: URLSearchParams;
+    updateParams: (input?: {
+        newParams?: Partial<MergeParams<M, O>> | ((current: MergeParams<M, O>) => Partial<MergeParams<M, O>>);
+        keepParams?: Partial<Record<Extract<keyof M, string> | Extract<keyof O, string>, boolean>>;
+        historyMode?: HistoryMode;
+    } | ((current: MergeParams<M, O>) => {
+        newParams?: Partial<MergeParams<M, O>> | ((current: MergeParams<M, O>) => Partial<MergeParams<M, O>>);
+        keepParams?: Partial<Record<Extract<keyof M, string> | Extract<keyof O, string>, boolean>>;
+        historyMode?: HistoryMode;
+    } | Partial<MergeParams<M, O>>)) => void;
+    clearParams: ({ keepMandatoryParams, historyMode: historyModeOverride }?: {
+        keepMandatoryParams?: boolean;
+        historyMode?: HistoryMode;
+    }) => void;
+    getParams: ({ convert }?: {
+        convert?: boolean | undefined;
+    }) => MergeParams<M, O>;
+    getParam: <K extends Extract<keyof M, string> | Extract<keyof O, string>, T extends boolean = true>(key: K, options?: {
+        convert: T;
+    }) => T extends true ? MergeParams<M, O>[K] : string;
+    onChange: (paramName: Extract<keyof M, string> | Extract<keyof O, string>, callbacks: Array<OnChangeCallback<MergeParams<M, O>>>) => () => void;
+    pagination: {
+        mode: "page" | "offset" | "cursor";
+        next: (cursor?: string) => void;
+        prev: () => void;
+        reset: () => void;
+        setCursor: (cursor: string | null | undefined) => void;
+    };
+};
+
+export { type BuiltInOmitParamValue, type HistoryMode, type OmitParamValue, type OnChangeEvent, type PaginationStrategy, type ParamCodec, type ResetOnChangeRules, type UnknownParamsPolicy, type UseMagicSearchParamsOptions, useMagicSearchParams };

package/dist/index.d.ts

@@ -1 +1,101 @@
-export { useMagicSearchParams, UseMagicSearchParamsOptions } from './useMagicSearchParams';
+type CommonParams = {
+    page?: number;
+    page_size?: number;
+};
+type MergeParams<M, O> = {
+    [K in keyof M]: M[K];
+} & {
+    [K in keyof O]?: O[K];
+};
+type ParamCodec<TValue> = {
+    parse?: (value: string | string[] | null, context: {
+        key: string;
+        searchParams: URLSearchParams;
+    }) => TValue;
+    serialize?: (value: TValue, context: {
+        key: string;
+    }) => string | string[] | null | undefined;
+};
+type ParamCodecs<TParams extends Record<string, unknown>> = Partial<{
+    [K in keyof TParams]: ParamCodec<TParams[K]>;
+}>;
+type ParamKey<TParams extends Record<string, unknown>> = Extract<keyof TParams, string>;
+type PaginationStrategy<TParams extends Record<string, unknown>> = {
+    mode: 'page';
+    pageKey?: ParamKey<TParams>;
+    pageSizeKey?: ParamKey<TParams>;
+} | {
+    mode: 'offset';
+    offsetKey?: ParamKey<TParams>;
+    limitKey?: ParamKey<TParams>;
+} | {
+    mode: 'cursor';
+    cursorKey?: ParamKey<TParams>;
+};
+type ResetOnChangeRules<TParams extends Record<string, unknown>> = Partial<Record<ParamKey<TParams>, Array<ParamKey<TParams>>>>;
+type UnknownParamsPolicy = 'drop' | 'preserve';
+type HistoryMode = 'push' | 'replace';
+type BuiltInOmitParamValue = 'all' | 'default' | 'unknown' | 'none' | 'void';
+type OmitParamValue = BuiltInOmitParamValue | (string & {});
+type OnChangeEvent<TParams extends Record<string, unknown>> = {
+    key: keyof TParams;
+    previousValue: unknown;
+    currentValue: unknown;
+};
+type OnChangeCallback<TParams extends Record<string, unknown>> = ((event: OnChangeEvent<TParams>) => void) | (() => void);
+/**
+ * Interface for the configuration object that the hook receives
+ */
+interface UseMagicSearchParamsOptions<M extends Record<string, unknown>, O extends Record<string, unknown>> {
+    mandatory: M;
+    optional?: O;
+    defaultParams?: Partial<MergeParams<M, O>>;
+    forceParams?: Partial<MergeParams<M, O>>;
+    arraySerialization?: 'csv' | 'repeat' | 'brackets';
+    omitParamsByValues?: Array<OmitParamValue>;
+    codecs?: ParamCodecs<MergeParams<M, O>>;
+    historyMode?: HistoryMode;
+    resetOnChange?: ResetOnChangeRules<MergeParams<M, O>>;
+    paginationStrategy?: PaginationStrategy<MergeParams<M, O>>;
+    unknownParamsPolicy?: UnknownParamsPolicy;
+}
+/**
+Generic hook to handle search parameters in the URL
+@param mandatory - Mandatory parameters (e.g., page=1, page_size=10, etc.)
+@param optional - Optional parameters (e.g., order, search, etc.)
+@param defaultParams - Default parameters sent in the URL on initialization
+@param forceParams - Parameters forced into the URL regardless of user input
+@param omitParamsByValues - Parameters omitted if they have specific values
+*/
+declare const useMagicSearchParams: <M extends Record<string, unknown> & CommonParams, O extends Record<string, unknown>>({ mandatory, optional, defaultParams, arraySerialization, forceParams, omitParamsByValues, codecs, historyMode, resetOnChange, paginationStrategy, unknownParamsPolicy }: UseMagicSearchParamsOptions<M, O>) => {
+    searchParams: URLSearchParams;
+    updateParams: (input?: {
+        newParams?: Partial<MergeParams<M, O>> | ((current: MergeParams<M, O>) => Partial<MergeParams<M, O>>);
+        keepParams?: Partial<Record<Extract<keyof M, string> | Extract<keyof O, string>, boolean>>;
+        historyMode?: HistoryMode;
+    } | ((current: MergeParams<M, O>) => {
+        newParams?: Partial<MergeParams<M, O>> | ((current: MergeParams<M, O>) => Partial<MergeParams<M, O>>);
+        keepParams?: Partial<Record<Extract<keyof M, string> | Extract<keyof O, string>, boolean>>;
+        historyMode?: HistoryMode;
+    } | Partial<MergeParams<M, O>>)) => void;
+    clearParams: ({ keepMandatoryParams, historyMode: historyModeOverride }?: {
+        keepMandatoryParams?: boolean;
+        historyMode?: HistoryMode;
+    }) => void;
+    getParams: ({ convert }?: {
+        convert?: boolean | undefined;
+    }) => MergeParams<M, O>;
+    getParam: <K extends Extract<keyof M, string> | Extract<keyof O, string>, T extends boolean = true>(key: K, options?: {
+        convert: T;
+    }) => T extends true ? MergeParams<M, O>[K] : string;
+    onChange: (paramName: Extract<keyof M, string> | Extract<keyof O, string>, callbacks: Array<OnChangeCallback<MergeParams<M, O>>>) => () => void;
+    pagination: {
+        mode: "page" | "offset" | "cursor";
+        next: (cursor?: string) => void;
+        prev: () => void;
+        reset: () => void;
+        setCursor: (cursor: string | null | undefined) => void;
+    };
+};
+
+export { type BuiltInOmitParamValue, type HistoryMode, type OmitParamValue, type OnChangeEvent, type PaginationStrategy, type ParamCodec, type ResetOnChangeRules, type UnknownParamsPolicy, type UseMagicSearchParamsOptions, useMagicSearchParams };

package/dist/index.js

@@ -1,8 +1 @@
-
-'use strict'
-
-if (process.env.NODE_ENV === 'production') {
-  module.exports = require('./react-magic-search-params.cjs.production.min.js')
-} else {
-  module.exports = require('./react-magic-search-params.cjs.development.js')
-}
+import{useSearchParams as ie}from"react-router-dom";import{useMemo as N,useEffect as Q,useRef as Y,useCallback as k}from"react";var ue=({mandatory:g={},optional:V={},defaultParams:f={},arraySerialization:l="csv",forceParams:y={},omitParamsByValues:q=[],codecs:F={},historyMode:E="push",resetOnChange:G={},paginationStrategy:p,unknownParamsPolicy:R="drop"})=>{let[i,L]=ie(),j=Y({}),U=Y({}),I=k((e,r)=>{L(e,{replace:(r??E)==="replace"})},[L,E]),m=N(()=>({...g,...V}),[g,V]),J=N(()=>Array.from(Object.keys(m)),[m]),A=k(e=>Object.prototype.hasOwnProperty.call(m,e),[m]),X=e=>!Array.isArray(m[e])||l==="csv"?i.get(e):l==="repeat"?i.getAll(e):i.getAll(`${e}[]`),B=k(()=>{if(R==="drop")return[];let e=[];for(let[r,a]of i.entries()){let s=r.endsWith("[]")?r.replace("[]",""):r;A(s)||e.push([r,a])}return e},[R,i,A]),H=k(e=>{if(R==="drop")return e;let r=new URLSearchParams(e.toString()),a=B();for(let[s,t]of a)r.append(s,t);return r},[R,B]),_=(e,r)=>Array.isArray(e)&&Array.isArray(r)?e.length!==r.length?!1:e.every((a,s)=>a===r[s]):e===r,C=N(()=>Object.keys(m).filter(e=>Array.isArray(m[e])),[m]),Z=(e,r)=>{let a={...e};return C.length===0||C.forEach(s=>{let t=[];switch(l){case"csv":{t=(i.get(s)||"").split(",").map(o=>o.trim()).filter(Boolean);break}case"repeat":{let n=i.getAll(s);t=n.length>0?n:[];break}case"brackets":{let n=i.getAll(`${s}[]`);t=n.length>0?n:[];break}default:t=(i.get(s)??"").split(",").map(o=>o.trim()).filter(Boolean)}if(r[s]!==void 0){let n=r[s],o=[];typeof n=="string"?o=t.includes(n)?t.filter(u=>u!==n):[...t,n]:Array.isArray(n)?o=Array.from(new Set([...n.map(String)])):o=t,a[s]=o}}),a},d=e=>{let r=new URLSearchParams,a=Object.keys(e);for(let s of a){let t=F[s];if(t?.serialize){let n=t.serialize(e[s],{key:s});if(n==null)continue;if(Array.isArray(n))if(Array.isArray(m[s]))if(l==="csv")r.set(s,n.join(","));else if(l==="repeat")for(let o of n)r.append(s,String(o));else for(let o of n)r.append(`${s}[]`,String(o));else n.length>0&&r.set(s,String(n[0]));else r.set(s,String(n));continue}if(Array.isArray(m[s])){let n=e[s];switch(l){case"csv":{r.set(s,n.join(","));break}case"repeat":{for(let o of n)r.append(s,String(o));break}case"brackets":{for(let o of n)r.append(`${s}[]`,String(o));break}default:r.set(s,n.join(","))}}else r.set(s,String(e[s]))}return r},w=(e,r)=>Object.prototype.hasOwnProperty.call(g,e)?g[e]:Object.prototype.hasOwnProperty.call(f,e)?f[e]:r,W=({paramsForced:e,compareParams:r})=>Object.entries(e).every(([s,t])=>r[s]===t),x=e=>{let r=X(e),a=F[e];if(a?.parse)return a.parse(r,{key:e,searchParams:i});if(typeof m[e]=="number"){let s=Number.parseInt(String(r??""),10);if(Number.isNaN(s)){let t=w(e,0);return typeof t=="number"?t:0}return s}return typeof m[e]=="boolean"?String(r)==="true":Array.isArray(m[e])?l==="csv"?String(r??"").split(",").filter(Boolean):Array.isArray(r)?r:r?[r]:[]:Array.isArray(r)?r[0]??"":r??""},$=(e,r)=>{if(Array.isArray(m[e])){if(l==="brackets"){let t=i.getAll(`${e}[]`),n=d({[e]:t}).toString();return decodeURIComponent(n)}if(l==="csv"){let t=i.getAll(e),n=d({[e]:t}).toString();return decodeURIComponent(n)}let s=i.getAll(e);return d({[e]:s}).toString()}return r[e]},z=e=>{let r={};for(let[a,s]of e.entries())if(a.endsWith("[]")){let t=a.replace("[]","");r[t]?r[t].push(s):r[t]=[s]}else r[a]?Array.isArray(r[a])?r[a].push(s):r[a]=[r[a],s]:r[a]=s;return r},v=N(()=>l==="brackets"?z(i):Object.fromEntries(i.entries()),[i,l]),K=({convert:e=!0}={})=>Object.keys(v).reduce((a,s)=>{if(Object.prototype.hasOwnProperty.call(m,s)){let t=l==="brackets"?s.replace("[]",""):s;a[t]=e===!0?x(t):$(s,v)}return a},{}),O=(e,r)=>{let a=String(e);return r?.convert!==!1?x(a):$(a,v)},ee=e=>e==null||typeof e!="object"?!1:Object.prototype.hasOwnProperty.call(e,"newParams")||Object.prototype.hasOwnProperty.call(e,"keepParams")||Object.prototype.hasOwnProperty.call(e,"historyMode"),re=e=>{let r=K({convert:!0});if(typeof e=="function"){let a=e(r);return ee(a)?{newParams:typeof a.newParams=="function"?a.newParams(r):a.newParams??{},keepParams:a.keepParams??{},historyMode:a.historyMode}:{newParams:a,keepParams:{},historyMode:void 0}}return e?{newParams:typeof e.newParams=="function"?e.newParams(r):e.newParams??{},keepParams:e.keepParams??{},historyMode:e.historyMode}:{newParams:{},keepParams:{},historyMode:void 0}},se=({currentParams:e,newParams:r,keepParams:a})=>{let s={...r},t={...a};for(let[n,o]of Object.entries(G))if(!(!o||o.length===0||!Object.prototype.hasOwnProperty.call(s,n)||_(s[n],e[n]))){for(let c of o)if(!Object.prototype.hasOwnProperty.call(y,c)){if(Object.prototype.hasOwnProperty.call(g,c)){s[c]=g[c],delete t[c];continue}if(Object.prototype.hasOwnProperty.call(f,c)){s[c]=f[c],delete t[c];continue}delete s[c],t[c]=!1}}return{newParams:s,keepParams:t}},ae=(e,r)=>{let a=K(),s=Object.entries(e).filter(([o])=>!Array.isArray(m[o])),t=Object.assign({...a,...Object.fromEntries(s)},y),n=Object.keys(t).reduce((o,u)=>{if(Object.prototype.hasOwnProperty.call(r,u)&&r[u]===!1)return o;let c=t[u],h=typeof c=="string"&&q.includes(c);return c!=null&&c!==""&&!h&&(o[u]=c),o},{});return{...g,...n}},te=e=>J.reduce((a,s)=>(Object.prototype.hasOwnProperty.call(e,s)&&(a[s]=e[s]),a),{}),ne=()=>{let e=C.length>0,r=K({convert:e});return Object.keys(r).reduce((s,t)=>(Object.prototype.hasOwnProperty.call(g,t)&&(s[t]=r[t]),s),{})},D=({keepMandatoryParams:e=!0,historyMode:r}={})=>{let a=d({...g,...e&&{...ne()},...y}),s=H(a);I(s,r)},P=e=>{let r=re(e),a=K({convert:!0}),s=se({currentParams:a,newParams:r.newParams,keepParams:r.keepParams}),t=s.newParams,n=s.keepParams;if(Object.keys(t).length===0&&Object.keys(n).length===0){D({historyMode:r.historyMode});return}let o=ae(t,n),u=Z(o,t),c=te(u),h=d(c),T=H(h);I(T,r.historyMode)},b=p?.mode==="page"?p:void 0,M=p?.mode==="offset"?p:void 0,S=p?.mode==="cursor"?p:void 0,oe={mode:p?.mode??"page",next:e=>{let r=p?.mode??"page";if(r==="cursor"){let n=S?.cursorKey??"cursor";typeof e=="string"&&P({newParams:{[n]:e}});return}if(r==="offset"){let n=M?.offsetKey??"offset",o=M?.limitKey??"limit",u=Number(O(n,{convert:!0})??0),c=Number(O(o,{convert:!0})??w(String(o),10)),h=Number.isFinite(u)?u:0,T=Number.isFinite(c)&&c>0?c:10;P({newParams:{[n]:h+T}});return}let a=b?b.pageKey??"page":"page",s=Number(O(a,{convert:!0})??w(String(a),1)),t=Number.isFinite(s)&&s>0?s:1;P({newParams:{[a]:t+1}})},prev:()=>{let e=p?.mode??"page";if(e==="cursor"){let t=S?.cursorKey??"cursor";P({keepParams:{[t]:!1}});return}if(e==="offset"){let t=M?.offsetKey??"offset",n=M?.limitKey??"limit",o=Number(O(t,{convert:!0})??0),u=Number(O(n,{convert:!0})??w(String(n),10)),c=Number.isFinite(o)?o:0,h=Number.isFinite(u)&&u>0?u:10;P({newParams:{[t]:Math.max(0,c-h)}});return}let r=b?b.pageKey??"page":"page",a=Number(O(r,{convert:!0})??w(String(r),1)),s=Number.isFinite(a)&&a>0?a:1;P({newParams:{[r]:Math.max(1,s-1)}})},reset:()=>{let e=p?.mode??"page";if(e==="cursor"){let s=S?.cursorKey??"cursor";P({keepParams:{[s]:!1}});return}if(e==="offset"){let s=M?.offsetKey??"offset",t=Number(w(String(s),0));P({newParams:{[s]:Number.isFinite(t)?t:0}});return}let r=b?b.pageKey??"page":"page",a=Number(w(String(r),1));P({newParams:{[r]:Number.isFinite(a)&&a>0?a:1}})},setCursor:e=>{let a=(p?.mode??"page")==="cursor"?S?.cursorKey??"cursor":"cursor";if(e==null||e===""){P({keepParams:{[a]:!1}});return}P({newParams:{[a]:e}})}},ce=k((e,r)=>{let a=String(e);return j.current[a]=r,()=>{delete j.current[a],delete U.current[a]}},[]);return Q(()=>{for(let[e,r]of Object.entries(j.current)){let a=A(e)?x(e):i.get(e),s=U.current[e]??null;if(!_(a,s))for(let t of r)t({key:e,previousValue:s,currentValue:a});U.current[e]=a}},[v,A,i]),Q(()=>{let e=Object.keys(f),r=Object.keys(y);if(e.length===0&&r.length===0)return;function a(){let s=d(f).toString(),t=K(),n=d(t).toString();if(!W({paramsForced:y,compareParams:t})){P({newParams:{...f,...y}});return}let u=W({paramsForced:y,compareParams:f});if(e.length>0&&u){if(s===n)return;P({newParams:f})}}a()},[]),{searchParams:i,updateParams:P,clearParams:D,getParams:K,getParam:O,onChange:ce,pagination:oe}};export{ue as useMagicSearchParams};

package/package.json

@@ -1,93 +1,110 @@
-{
-  "description": "#️⃣ A React Hook for advanced, typed management of URL search parameters, providing built-in TypeScript autocomplete.",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Gabriel117343/react-magic-search-params"
-   },
-  "homepage": "https://react-magic-search-params.netlify.app",
-  "keywords": [
-    "react",
-    "hook",
-    "url-parameters",
-    "search-params",
-    "typescript",
-    "autocomplete",
-    "use-url-search-params",
-    "use-search-params",
-    "use-query-parameters"
-
-  ],
-  "version": "1.2.0",
-  "private": false,
-  "license": "MIT",
-  "main": "dist/index.js",
-  "typings": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "src"
-  ],
-  "engines": {
-    "node": ">=10"
-  },
-  "scripts": {
-    "start": "tsdx watch",
-    "build": "tsdx build",
-    "test": "vitest",
-    "lint": "tsdx lint",
-    "prepare": "tsdx build",
-    "size": "size-limit",
-    "analyze": "size-limit --why",
-    "prepack": "copy README_NPM.md README.md",
-    "postpack": "git checkout -- README.md"
-  },
-  "peerDependencies": {
-    "react": ">=16",
-    "react-router-dom": ">=6"
-  },
-  "husky": {
-    "hooks": {
-      "pre-commit": "tsdx lint"
-    }
-  },
-  "prettier": {
-    "printWidth": 80,
-    "semi": true,
-    "singleQuote": true,
-    "trailingComma": "es5"
-  },
-  "name": "react-magic-search-params",
-  "author": "Gabriel S.",
-  "module": "dist/react-magic-search-params.esm.js",
-  "size-limit": [
-    {
-      "path": "dist/usemagicsearchparams-library.cjs.production.min.js",
-      "limit": "10 KB"
-    },
-    {
-      "path": "dist/usemagicsearchparams-library.esm.js",
-      "limit": "10 KB"
-    }
-  ],
-  "devDependencies": {
-    "@size-limit/preset-small-lib": "^11.2.0",
-    "@types/react": "^19.0.10",
-    "@types/react-dom": "^19.0.4",
-    "husky": "^9.1.7",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "size-limit": "^11.2.0",
-    "tsdx": "^0.14.1",
-    "tslib": "^2.8.1",
-    "typescript": "^3.9.10",
-    "vitest": "^3.0.8",
-    "@testing-library/react": "^16.2.0"
-  },
-
-  "exports": {
-    ".": {
-      "import": "./dist/react-magic-search-params.esm.js",
-      "require": "./dist/react-magic-search-params.cjs.production.min.js",
-      "types": "./dist/index.d.ts"
-    }
-  }
-}
+{
+  "description": "Type-safe React hook to manage URL query/search params with React Router useSearchParams.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gabriel117343/react-magic-search-params.git"
+  },
+  "homepage": "https://react-magic-search-params.netlify.app",
+  "bugs": {
+    "url": "https://github.com/Gabriel117343/react-magic-search-params/issues"
+  },
+  "keywords": [
+    "react",
+    "react-hook",
+    "react-router",
+    "react-router-dom",
+    "useSearchParams",
+    "search-params",
+    "query-params",
+    "url-search-params",
+    "url-state",
+    "typescript",
+    "type-safe",
+    "filters",
+    "pagination",
+    "sorting"
+  ],
+  "version": "2.1.2",
+  "private": false,
+  "license": "MIT",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "typings": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@10.7.1",
+  "scripts": {
+    "start": "tsup --watch",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "test": "vitest run --environment jsdom",
+    "test:watch": "vitest --environment jsdom",
+    "lint": "tsc --noEmit",
+    "prepare": "tsup",
+    "size": "size-limit",
+    "analyze": "size-limit --why",
+    "prepack": "node -e \"const fs=require('fs');fs.copyFileSync('README.md','.README.repo.md');fs.copyFileSync('README_NPM.md','README.md');\"",
+    "postpack": "node -e \"const fs=require('fs');if(fs.existsSync('.README.repo.md')){fs.copyFileSync('.README.repo.md','README.md');fs.unlinkSync('.README.repo.md');}\""
+  },
+  "peerDependencies": {
+    "react": ">=18 <20",
+    "react-router-dom": ">=6"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "tsdx lint"
+    }
+  },
+  "prettier": {
+    "printWidth": 80,
+    "semi": true,
+    "singleQuote": true,
+    "trailingComma": "es5"
+  },
+  "name": "react-magic-search-params",
+  "author": "Gabriel S.",
+  "size-limit": [
+    {
+      "path": "dist/index.cjs",
+      "limit": "10 KB"
+    },
+    {
+      "path": "dist/index.js",
+      "limit": "10 KB"
+    }
+  ],
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "@testing-library/react": "^16.3.0",
+    "husky": "^9.1.7",
+    "jsdom": "^26.1.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.0.0",
+    "size-limit": "^11.2.0",
+    "tsup": "^8.5.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://npmjs.org"
+  }
+}

package/dist/constants/defaultParamsPage.d.ts

@@ -1,12 +0,0 @@
-export declare const paramsUsers: {
-    mandatory: {
-        page: number;
-        page_size: 10;
-        only_is_active: boolean;
-        tags: unknown[];
-    };
-    optional: {
-        order: string;
-        search: string;
-    };
-};