react-magic-search-params 2.0.1 → 2.2.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Gabriel S.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2025 Gabriel S.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -7,7 +7,7 @@
 
 ![react-magic-search-params hero](https://raw.githubusercontent.com/Gabriel117343/react-magic-search-params/main/public/hero.png)
 
-Typed query parameter management for React Router.
+Type-safe query/search parameter management for React Router, built as an extension over useSearchParams.
 
 ## Installation
 
@@ -54,6 +54,18 @@ updateParams({ newParams: { tags: 'react' } });
 clearParams({ keepMandatoryParams: true });
 ```
 
+If you have ambiguous optional unions (for example `boolean | ''`), use `coerceParams`:
+
+```tsx
+const { getParams } = useMagicSearchParams({
+  mandatory: { page: 1, page_size: 50 },
+  optional: { only_unmapped: '' as boolean | '' },
+  coerceParams: { only_unmapped: 'boolean' },
+});
+
+const { only_unmapped } = getParams({ convert: true });
+```
+
 ## API
 
 - `getParams({ convert?: boolean })`

package/dist/index.cjs

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

package/dist/index.d.mts

@@ -20,6 +20,8 @@ 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 CoerceParamType = 'string' | 'number' | 'boolean' | 'array';
+type CoerceParams<TParams extends Record<string, unknown>> = Partial<Record<ParamKey<TParams>, CoerceParamType>>;
 type PaginationStrategy<TParams extends Record<string, unknown>> = {
     mode: 'page';
     pageKey?: ParamKey<TParams>;
@@ -35,6 +37,8 @@ type PaginationStrategy<TParams extends Record<string, unknown>> = {
 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;
@@ -50,7 +54,8 @@ interface UseMagicSearchParamsOptions<M extends Record<string, unknown>, O exten
     defaultParams?: Partial<MergeParams<M, O>>;
     forceParams?: Partial<MergeParams<M, O>>;
     arraySerialization?: 'csv' | 'repeat' | 'brackets';
-    omitParamsByValues?: Array<'all' | 'default' | 'unknown' | 'none' | 'void'>;
+    omitParamsByValues?: Array<OmitParamValue>;
+    coerceParams?: CoerceParams<MergeParams<M, O>>;
     codecs?: ParamCodecs<MergeParams<M, O>>;
     historyMode?: HistoryMode;
     resetOnChange?: ResetOnChangeRules<MergeParams<M, O>>;
@@ -65,7 +70,7 @@ Generic hook to handle search parameters in the URL
 @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>) => {
+declare const useMagicSearchParams: <M extends Record<string, unknown> & CommonParams, O extends Record<string, unknown>>({ mandatory, optional, defaultParams, arraySerialization, forceParams, omitParamsByValues, coerceParams, 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>>);
@@ -96,4 +101,4 @@ declare const useMagicSearchParams: <M extends Record<string, unknown> & CommonP
     };
 };
 
-export { type HistoryMode, type OnChangeEvent, type PaginationStrategy, type ParamCodec, type ResetOnChangeRules, type UnknownParamsPolicy, type UseMagicSearchParamsOptions, useMagicSearchParams };
+export { type BuiltInOmitParamValue, type CoerceParamType, type CoerceParams, type HistoryMode, type OmitParamValue, type OnChangeEvent, type PaginationStrategy, type ParamCodec, type ResetOnChangeRules, type UnknownParamsPolicy, type UseMagicSearchParamsOptions, useMagicSearchParams };

package/dist/index.d.ts

@@ -20,6 +20,8 @@ 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 CoerceParamType = 'string' | 'number' | 'boolean' | 'array';
+type CoerceParams<TParams extends Record<string, unknown>> = Partial<Record<ParamKey<TParams>, CoerceParamType>>;
 type PaginationStrategy<TParams extends Record<string, unknown>> = {
     mode: 'page';
     pageKey?: ParamKey<TParams>;
@@ -35,6 +37,8 @@ type PaginationStrategy<TParams extends Record<string, unknown>> = {
 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;
@@ -50,7 +54,8 @@ interface UseMagicSearchParamsOptions<M extends Record<string, unknown>, O exten
     defaultParams?: Partial<MergeParams<M, O>>;
     forceParams?: Partial<MergeParams<M, O>>;
     arraySerialization?: 'csv' | 'repeat' | 'brackets';
-    omitParamsByValues?: Array<'all' | 'default' | 'unknown' | 'none' | 'void'>;
+    omitParamsByValues?: Array<OmitParamValue>;
+    coerceParams?: CoerceParams<MergeParams<M, O>>;
     codecs?: ParamCodecs<MergeParams<M, O>>;
     historyMode?: HistoryMode;
     resetOnChange?: ResetOnChangeRules<MergeParams<M, O>>;
@@ -65,7 +70,7 @@ Generic hook to handle search parameters in the URL
 @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>) => {
+declare const useMagicSearchParams: <M extends Record<string, unknown> & CommonParams, O extends Record<string, unknown>>({ mandatory, optional, defaultParams, arraySerialization, forceParams, omitParamsByValues, coerceParams, 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>>);
@@ -96,4 +101,4 @@ declare const useMagicSearchParams: <M extends Record<string, unknown> & CommonP
     };
 };
 
-export { type HistoryMode, type OnChangeEvent, type PaginationStrategy, type ParamCodec, type ResetOnChangeRules, type UnknownParamsPolicy, type UseMagicSearchParamsOptions, useMagicSearchParams };
+export { type BuiltInOmitParamValue, type CoerceParamType, type CoerceParams, type HistoryMode, type OmitParamValue, type OnChangeEvent, type PaginationStrategy, type ParamCodec, type ResetOnChangeRules, type UnknownParamsPolicy, type UseMagicSearchParamsOptions, useMagicSearchParams };

package/dist/index.js

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

package/package.json

@@ -1,98 +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",
-    "query-parameters"
-  ],
-  "version": "2.0.1",
-  "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"
-  },
-  "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"
-    }
-  }
-}
+{
+  "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.2.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"
+  }
+}