zustand-querystring 0.6.1 → 0.6.2

package/README.md

@@ -14,16 +14,16 @@ import { querystring } from 'zustand-querystring';
 
 const useStore = create(
   querystring(
-    (set) => ({
+    set => ({
       search: '',
       page: 1,
-      setSearch: (search) => set({ search }),
-      setPage: (page) => set({ page }),
+      setSearch: search => set({ search }),
+      setPage: page => set({ page }),
     }),
     {
       select: () => ({ search: true, page: true }),
-    }
-  )
+    },
+  ),
 );
 // URL: ?search=hello&page=2
 ```
@@ -34,14 +34,15 @@ const useStore = create(
 
 ```ts
 querystring(storeCreator, {
-  select: undefined,    // which fields to sync
-  key: false,           // false | 'state'
-  prefix: '',           // prefix for URL params
-  format: marked,       // serialization format
-  syncNull: false,      // sync null values
+  select: undefined, // which fields to sync
+  key: false, // false | 'state'
+  prefix: '', // prefix for URL params
+  format: marked, // serialization format
+  map: undefined, // bidirectional store ↔ URL mapping
+  syncNull: false, // sync null values
   syncUndefined: false, // sync undefined values
-  url: undefined,       // request URL for SSR
-})
+  url: undefined, // request URL for SSR
+});
 ```
 
 ### `select`
@@ -50,14 +51,14 @@ Controls which state fields sync to URL. Receives pathname, returns object with
 
 ```ts
 // All fields
-select: () => ({ search: true, page: true, filters: true })
+select: () => ({ search: true, page: true, filters: true });
 
 // Route-based
-select: (pathname) => ({
+select: pathname => ({
   search: true,
   filters: pathname.startsWith('/products'),
   adminSettings: pathname.startsWith('/admin'),
-})
+});
 
 // Nested fields
 select: () => ({
@@ -65,7 +66,7 @@ select: () => ({
     name: true,
     settings: { theme: true },
   },
-})
+});
 ```
 
 ### `key`
@@ -84,8 +85,8 @@ select: () => ({
 Adds prefix to all params. Use when multiple stores share URL.
 
 ```ts
-querystring(storeA, { prefix: 'a_', select: () => ({ search: true }) })
-querystring(storeB, { prefix: 'b_', select: () => ({ filter: true }) })
+querystring(storeA, { prefix: 'a_', select: () => ({ search: true }) });
+querystring(storeB, { prefix: 'b_', select: () => ({ filter: true }) });
 // URL: ?a_search=hello&b_filter=active
 ```
 
@@ -93,12 +94,68 @@ querystring(storeB, { prefix: 'b_', select: () => ({ filter: true }) })
 
 By default, `null` and `undefined` reset to initial state (removed from URL). Set to `true` to write them.
 
+### `map`
+
+Bidirectional mapping between store state and URL state. Use when the URL should represent a different shape than the store — e.g., a store keyed by dynamic IDs where the URL should only reflect the active entry.
+
+`to` receives the selected state and pathname, returns the URL shape. `from` receives the parsed URL state and pathname, returns store state to merge. Types flow automatically: `from`'s parameter type is inferred from `to`'s return type.
+
+```ts
+interface Store {
+  filtersByOperation: Record<string, { filters: string[] }>;
+  aggregationByOperation: Record<string, string>;
+  setFilters: (opId: string, filters: string[]) => void;
+}
+
+const useStore = create<Store>()(
+  querystring(
+    set => ({
+      filtersByOperation: {},
+      aggregationByOperation: {},
+      setFilters: (opId, filters) =>
+        set(s => ({
+          filtersByOperation: { ...s.filtersByOperation, [opId]: { filters } },
+        })),
+    }),
+    {
+      key: 'state',
+      select: pathname => ({
+        filtersByOperation: pathname.startsWith('/view/'),
+        aggregationByOperation: pathname.startsWith('/view/'),
+      }),
+      map: {
+        to: (state, pathname) => {
+          const id = pathname.split('/').pop()!;
+          return {
+            filters: state.filtersByOperation?.[id]?.filters,
+            aggregation: state.aggregationByOperation?.[id],
+          };
+        },
+        from: (urlState, pathname) => {
+          // urlState is typed as { filters: string[] | undefined, aggregation: string | undefined }
+          const id = pathname.split('/').pop()!;
+          return {
+            ...(urlState.filters
+              ? { filtersByOperation: { [id]: { filters: urlState.filters } } }
+              : {}),
+            ...(urlState.aggregation
+              ? { aggregationByOperation: { [id]: urlState.aggregation } }
+              : {}),
+          };
+        },
+      },
+    },
+  ),
+);
+// On /view/DAM_v1 → URL: ?state=filters@price_>10~,aggregation=daily
+```
+
 ### `url`
 
 For SSR, pass the request URL:
 
 ```ts
-querystring(store, { url: request.url, select: () => ({ search: true }) })
+querystring(store, { url: request.url, select: () => ({ search: true }) });
 ```
 
 ---
@@ -118,6 +175,7 @@ Only values **different from initial state** are written to URL:
 ```
 
 Type handling:
+
 - Objects: recursively diffed
 - Arrays, Dates: compared as whole values
 - Functions: never synced
@@ -128,18 +186,18 @@ Type handling:
 
 Three built-in formats:
 
-| Format | Example Output |
-|--------|----------------|
-| `marked` | `count:5,tags@a,b~` |
-| `plain` | `count=5&tags=a&tags=b` |
-| `json` | `count=5&tags=%5B%22a%22%5D` |
+| Format   | Example Output               |
+| -------- | ---------------------------- |
+| `marked` | `count:5,tags@a,b~`          |
+| `plain`  | `count=5&tags=a&tags=b`      |
+| `json`   | `count=5&tags=%5B%22a%22%5D` |
 
 ```ts
 import { marked } from 'zustand-querystring/format/marked';
 import { plain } from 'zustand-querystring/format/plain';
 import { json } from 'zustand-querystring/format/json';
 
-querystring(store, { format: plain })
+querystring(store, { format: plain });
 ```
 
 ### Marked Format (default)
@@ -171,13 +229,13 @@ Dot notation for nesting, repeated keys for arrays.
 import { createFormat } from 'zustand-querystring/format/plain';
 
 const format = createFormat({
-  entrySeparator: ',',           // between entries in namespaced mode
-  nestingSeparator: '.',         // for nested keys
-  arraySeparator: 'repeat',      // 'repeat' for ?tags=a&tags=b, or ',' for ?tags=a,b
+  entrySeparator: ',', // between entries in namespaced mode
+  nestingSeparator: '.', // for nested keys
+  arraySeparator: 'repeat', // 'repeat' for ?tags=a&tags=b, or ',' for ?tags=a,b
   escapeChar: '_',
   nullString: 'null',
   undefinedString: 'undefined',
-  infinityString: 'Infinity',    // string representation of Infinity
+  infinityString: 'Infinity', // string representation of Infinity
   negativeInfinityString: '-Infinity',
   nanString: 'NaN',
 });
@@ -196,7 +254,11 @@ URL-encoded JSON. No configuration.
 Implement `QueryStringFormat`:
 
 ```ts
-import type { QueryStringFormat, QueryStringParams, ParseContext } from 'zustand-querystring';
+import type {
+  QueryStringFormat,
+  QueryStringParams,
+  ParseContext,
+} from 'zustand-querystring';
 
 const myFormat: QueryStringFormat = {
   // For key: 'state' (namespaced mode)
@@ -224,10 +286,11 @@ const myFormat: QueryStringFormat = {
   },
 };
 
-querystring(store, { format: myFormat })
+querystring(store, { format: myFormat });
 ```
 
 Types:
+
 - `QueryStringParams` = `Record<string, string[]>` (values always arrays)
 - `ctx.initialState` available for type coercion
 
@@ -240,14 +303,14 @@ Types:
 ```ts
 const useStore = create(
   querystring(
-    (set) => ({
+    set => ({
       query: '',
       page: 1,
-      setQuery: (query) => set({ query, page: 1 }), // reset page on new query
-      setPage: (page) => set({ page }),
+      setQuery: query => set({ query, page: 1 }), // reset page on new query
+      setPage: page => set({ page }),
     }),
-    { select: () => ({ query: true, page: true }) }
-  )
+    { select: () => ({ query: true, page: true }) },
+  ),
 );
 ```
 
@@ -258,14 +321,14 @@ const useFilters = create(
   querystring(filtersStore, {
     prefix: 'f_',
     select: () => ({ category: true, price: true }),
-  })
+  }),
 );
 
 const usePagination = create(
   querystring(paginationStore, {
     prefix: 'p_',
     select: () => ({ page: true, limit: true }),
-  })
+  }),
 );
 // URL: ?f_category=shoes&f_price=100&p_page=2&p_limit=20
 ```
@@ -295,6 +358,7 @@ import { json } from 'zustand-querystring/format/json';
 // Types
 import type {
   QueryStringOptions,
+  QueryStringMap,
   QueryStringFormat,
   QueryStringParams,
   ParseContext,

package/dist/{chunk-TQQUWVLF.mjs → chunk-M3ILBO2T.mjs}

@@ -38,7 +38,9 @@ function validateOptions(opts) {
     seen.add(token);
   }
   if (seen.has(opts.datePrefix)) {
-    throw new Error(`datePrefix '${opts.datePrefix}' conflicts with another token`);
+    throw new Error(
+      `datePrefix '${opts.datePrefix}' conflicts with another token`
+    );
   }
 }
 function escapeRegex(str) {
@@ -50,7 +52,9 @@ function buildKeyStopPattern(opts) {
   );
 }
 function buildValueStopPattern(opts) {
-  return new RegExp(`[${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}]`);
+  return new RegExp(
+    `[${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}]`
+  );
 }
 function buildKeyEscapePattern(opts) {
   return new RegExp(
@@ -59,7 +63,10 @@ function buildKeyEscapePattern(opts) {
   );
 }
 function buildValueEscapePattern(opts) {
-  return new RegExp(`([${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}])`, "g");
+  return new RegExp(
+    `([${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}])`,
+    "g"
+  );
 }
 function buildDatePattern(opts) {
   return new RegExp(`^${escapeRegex(opts.datePrefix)}-?\\d+$`);
@@ -94,7 +101,9 @@ function cleanResult(str, standalone, opts) {
   while (str.endsWith(opts.terminator)) {
     str = str.slice(0, -opts.terminator.length);
   }
-  const datePattern = new RegExp(`^${escapeRegex(opts.typeString)}${escapeRegex(opts.datePrefix)}-?\\d+$`);
+  const datePattern = new RegExp(
+    `^${escapeRegex(opts.typeString)}${escapeRegex(opts.datePrefix)}-?\\d+$`
+  );
   if (standalone && datePattern.test(str)) {
     return str.slice(opts.typeString.length);
   }
@@ -312,7 +321,12 @@ function parse(input, standalone = false, options = {}) {
     }
     return result;
   } else {
-    const escapedMarkers = [opts.typeString, opts.typePrimitive, opts.typeArray, opts.typeObject].map(escapeRegex).join("");
+    const escapedMarkers = [
+      opts.typeString,
+      opts.typePrimitive,
+      opts.typeArray,
+      opts.typeObject
+    ].map(escapeRegex).join("");
     const escapedEscape = escapeRegex(opts.escape);
     const escapedSeparator = escapeRegex(opts.separator);
     const escapedTerminator = escapeRegex(opts.terminator);

package/dist/format/marked.js

@@ -65,7 +65,9 @@ function validateOptions(opts) {
     seen.add(token);
   }
   if (seen.has(opts.datePrefix)) {
-    throw new Error(`datePrefix '${opts.datePrefix}' conflicts with another token`);
+    throw new Error(
+      `datePrefix '${opts.datePrefix}' conflicts with another token`
+    );
   }
 }
 function escapeRegex(str) {
@@ -77,7 +79,9 @@ function buildKeyStopPattern(opts) {
   );
 }
 function buildValueStopPattern(opts) {
-  return new RegExp(`[${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}]`);
+  return new RegExp(
+    `[${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}]`
+  );
 }
 function buildKeyEscapePattern(opts) {
   return new RegExp(
@@ -86,7 +90,10 @@ function buildKeyEscapePattern(opts) {
   );
 }
 function buildValueEscapePattern(opts) {
-  return new RegExp(`([${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}])`, "g");
+  return new RegExp(
+    `([${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}])`,
+    "g"
+  );
 }
 function buildDatePattern(opts) {
   return new RegExp(`^${escapeRegex(opts.datePrefix)}-?\\d+$`);
@@ -121,7 +128,9 @@ function cleanResult(str, standalone, opts) {
   while (str.endsWith(opts.terminator)) {
     str = str.slice(0, -opts.terminator.length);
   }
-  const datePattern = new RegExp(`^${escapeRegex(opts.typeString)}${escapeRegex(opts.datePrefix)}-?\\d+$`);
+  const datePattern = new RegExp(
+    `^${escapeRegex(opts.typeString)}${escapeRegex(opts.datePrefix)}-?\\d+$`
+  );
   if (standalone && datePattern.test(str)) {
     return str.slice(opts.typeString.length);
   }
@@ -339,7 +348,12 @@ function parse(input, standalone = false, options = {}) {
     }
     return result;
   } else {
-    const escapedMarkers = [opts.typeString, opts.typePrimitive, opts.typeArray, opts.typeObject].map(escapeRegex).join("");
+    const escapedMarkers = [
+      opts.typeString,
+      opts.typePrimitive,
+      opts.typeArray,
+      opts.typeObject
+    ].map(escapeRegex).join("");
     const escapedEscape = escapeRegex(opts.escape);
     const escapedSeparator = escapeRegex(opts.separator);
     const escapedTerminator = escapeRegex(opts.terminator);

package/dist/format/marked.mjs

@@ -4,7 +4,7 @@ import {
   marked_default,
   parse,
   stringify
-} from "../chunk-TQQUWVLF.mjs";
+} from "../chunk-M3ILBO2T.mjs";
 export {
   createFormat,
   marked_default as default,

package/dist/format/plain.js

@@ -40,16 +40,24 @@ function resolveOptions(opts = {}) {
 function validateOptions(opts) {
   const { entrySep, nestingSep, arraySep, escape: escape2 } = opts;
   if (entrySep === nestingSep) {
-    throw new Error(`entrySeparator and nestingSeparator cannot be the same: '${entrySep}'`);
+    throw new Error(
+      `entrySeparator and nestingSeparator cannot be the same: '${entrySep}'`
+    );
   }
   if (escape2 === entrySep || escape2 === nestingSep) {
-    throw new Error(`escapeChar cannot be the same as a separator: '${escape2}'`);
+    throw new Error(
+      `escapeChar cannot be the same as a separator: '${escape2}'`
+    );
   }
   if (arraySep !== "repeat" && arraySep === nestingSep) {
-    throw new Error(`arraySeparator cannot be the same as nestingSeparator: '${arraySep}'`);
+    throw new Error(
+      `arraySeparator cannot be the same as nestingSeparator: '${arraySep}'`
+    );
   }
   if (arraySep !== "repeat" && arraySep === escape2) {
-    throw new Error(`arraySeparator cannot be the same as escapeChar: '${arraySep}'`);
+    throw new Error(
+      `arraySeparator cannot be the same as escapeChar: '${arraySep}'`
+    );
   }
   if (entrySep.length === 0 || nestingSep.length === 0 || escape2.length === 0) {
     throw new Error("Separators and escape character cannot be empty");
@@ -59,12 +67,7 @@ function validateOptions(opts) {
   }
 }
 function encodePreservingMarkers(str, opts) {
-  const markers = /* @__PURE__ */ new Set([
-    opts.entrySep,
-    opts.nestingSep,
-    opts.escape,
-    "="
-  ]);
+  const markers = /* @__PURE__ */ new Set([opts.entrySep, opts.nestingSep, opts.escape, "="]);
   if (opts.arraySep !== "repeat") {
     markers.add(opts.arraySep);
   }
@@ -180,7 +183,9 @@ function unescape(str, esc, chars) {
   while (i < str.length) {
     if (str.substring(i, i + esc.length) === esc) {
       const nextPos = i + esc.length;
-      const isEscapeSequence = chars.some((c) => str.substring(nextPos, nextPos + c.length) === c);
+      const isEscapeSequence = chars.some(
+        (c) => str.substring(nextPos, nextPos + c.length) === c
+      );
       if (isEscapeSequence && nextPos < str.length) {
         i = nextPos;
         for (const special of chars) {
@@ -311,7 +316,11 @@ function flatten(obj, prefix, opts) {
             Object.assign(result, flatten(item, indexedKey, opts));
           } else {
             const serialized = serializeValue(item, opts);
-            const escapedValue = escape(serialized, valueEscapeChars, opts.escape);
+            const escapedValue = escape(
+              serialized,
+              valueEscapeChars,
+              opts.escape
+            );
             result[indexedKey] = [escapedValue];
           }
         }
@@ -363,7 +372,11 @@ function unflatten(entries, initialState, opts) {
       continue;
     }
     const elementHint = isArrayHint ? hint[0] : void 0;
-    setAtPath(result, path, values.map((v) => parseValue(v, elementHint, opts)));
+    setAtPath(
+      result,
+      path,
+      values.map((v) => parseValue(v, elementHint, opts))
+    );
   }
   return result;
 }
@@ -399,10 +412,14 @@ function stringifyNamespaced(state, opts) {
   for (const [key, values] of Object.entries(entries)) {
     if (opts.arraySep === "repeat") {
       for (const value of values) {
-        parts.push(encodePreservingMarkers(key, opts) + "=" + encodePreservingMarkers(value, opts));
+        parts.push(
+          encodePreservingMarkers(key, opts) + "=" + encodePreservingMarkers(value, opts)
+        );
       }
     } else {
-      parts.push(encodePreservingMarkers(key, opts) + "=" + encodePreservingMarkers(values.join(opts.arraySep), opts));
+      parts.push(
+        encodePreservingMarkers(key, opts) + "=" + encodePreservingMarkers(values.join(opts.arraySep), opts)
+      );
     }
   }
   return parts.join(opts.entrySep);

package/dist/format/plain.mjs

@@ -16,16 +16,24 @@ function resolveOptions(opts = {}) {
 function validateOptions(opts) {
   const { entrySep, nestingSep, arraySep, escape: escape2 } = opts;
   if (entrySep === nestingSep) {
-    throw new Error(`entrySeparator and nestingSeparator cannot be the same: '${entrySep}'`);
+    throw new Error(
+      `entrySeparator and nestingSeparator cannot be the same: '${entrySep}'`
+    );
   }
   if (escape2 === entrySep || escape2 === nestingSep) {
-    throw new Error(`escapeChar cannot be the same as a separator: '${escape2}'`);
+    throw new Error(
+      `escapeChar cannot be the same as a separator: '${escape2}'`
+    );
   }
   if (arraySep !== "repeat" && arraySep === nestingSep) {
-    throw new Error(`arraySeparator cannot be the same as nestingSeparator: '${arraySep}'`);
+    throw new Error(
+      `arraySeparator cannot be the same as nestingSeparator: '${arraySep}'`
+    );
   }
   if (arraySep !== "repeat" && arraySep === escape2) {
-    throw new Error(`arraySeparator cannot be the same as escapeChar: '${arraySep}'`);
+    throw new Error(
+      `arraySeparator cannot be the same as escapeChar: '${arraySep}'`
+    );
   }
   if (entrySep.length === 0 || nestingSep.length === 0 || escape2.length === 0) {
     throw new Error("Separators and escape character cannot be empty");
@@ -35,12 +43,7 @@ function validateOptions(opts) {
   }
 }
 function encodePreservingMarkers(str, opts) {
-  const markers = /* @__PURE__ */ new Set([
-    opts.entrySep,
-    opts.nestingSep,
-    opts.escape,
-    "="
-  ]);
+  const markers = /* @__PURE__ */ new Set([opts.entrySep, opts.nestingSep, opts.escape, "="]);
   if (opts.arraySep !== "repeat") {
     markers.add(opts.arraySep);
   }
@@ -156,7 +159,9 @@ function unescape(str, esc, chars) {
   while (i < str.length) {
     if (str.substring(i, i + esc.length) === esc) {
       const nextPos = i + esc.length;
-      const isEscapeSequence = chars.some((c) => str.substring(nextPos, nextPos + c.length) === c);
+      const isEscapeSequence = chars.some(
+        (c) => str.substring(nextPos, nextPos + c.length) === c
+      );
       if (isEscapeSequence && nextPos < str.length) {
         i = nextPos;
         for (const special of chars) {
@@ -287,7 +292,11 @@ function flatten(obj, prefix, opts) {
             Object.assign(result, flatten(item, indexedKey, opts));
           } else {
             const serialized = serializeValue(item, opts);
-            const escapedValue = escape(serialized, valueEscapeChars, opts.escape);
+            const escapedValue = escape(
+              serialized,
+              valueEscapeChars,
+              opts.escape
+            );
             result[indexedKey] = [escapedValue];
           }
         }
@@ -339,7 +348,11 @@ function unflatten(entries, initialState, opts) {
       continue;
     }
     const elementHint = isArrayHint ? hint[0] : void 0;
-    setAtPath(result, path, values.map((v) => parseValue(v, elementHint, opts)));
+    setAtPath(
+      result,
+      path,
+      values.map((v) => parseValue(v, elementHint, opts))
+    );
   }
   return result;
 }
@@ -375,10 +388,14 @@ function stringifyNamespaced(state, opts) {
   for (const [key, values] of Object.entries(entries)) {
     if (opts.arraySep === "repeat") {
       for (const value of values) {
-        parts.push(encodePreservingMarkers(key, opts) + "=" + encodePreservingMarkers(value, opts));
+        parts.push(
+          encodePreservingMarkers(key, opts) + "=" + encodePreservingMarkers(value, opts)
+        );
       }
     } else {
-      parts.push(encodePreservingMarkers(key, opts) + "=" + encodePreservingMarkers(values.join(opts.arraySep), opts));
+      parts.push(
+        encodePreservingMarkers(key, opts) + "=" + encodePreservingMarkers(values.join(opts.arraySep), opts)
+      );
     }
   }
   return parts.join(opts.entrySep);

package/dist/index.d.mts

@@ -3,6 +3,10 @@ import { StoreMutatorIdentifier, StateCreator } from 'zustand/vanilla';
 type DeepSelect<T> = T extends object ? {
     [P in keyof T]?: DeepSelect<T[P]> | boolean;
 } : boolean;
+/** Maps T to only the fields marked as selected in S. `false` excludes, everything else includes. */
+type ApplySelect<T, S> = [S] extends [false] ? never : S extends object ? T extends object ? {
+    [P in keyof S & keyof T as [ApplySelect<T[P], S[P]>] extends [never] ? never : P]: ApplySelect<T[P], S[P]>;
+} : never : T;
 interface QueryStringParam {
     key: string;
     value: string | string[];
@@ -32,16 +36,28 @@ interface QueryStringFormatStandalone {
 type QueryStringFormat = QueryStringFormatNamespaced & QueryStringFormatStandalone;
 /** Conditional format type based on key option */
 type QueryStringFormatFor<K extends string | false> = K extends false ? QueryStringFormatStandalone : QueryStringFormatNamespaced;
-interface QueryStringOptions<T, K extends string | false = string | false> {
+/**
+ * Bidirectional mapping between store state and URL state.
+ * `to` runs before serialization (store → URL), `from` after deserialization (URL → store).
+ * S is inferred from `select` via `ApplySelect` — only selected fields are visible.
+ * U is inferred from `to`'s return type and flows into `from`'s parameter.
+ */
+interface QueryStringMap<S, U extends object = Record<string, unknown>> {
+    to: (state: S, pathname: string) => U;
+    from: (urlState: U, pathname: string) => Partial<S>;
+}
+interface QueryStringOptions<T, K extends string | false = string | false, S extends DeepSelect<T> = DeepSelect<T>, U extends object = Record<string, unknown>> {
     url?: string;
-    select?: (pathname: string) => DeepSelect<T>;
+    select?: (pathname: string) => S;
     key?: K;
     prefix?: string;
     format?: QueryStringFormatFor<K>;
     syncNull?: boolean;
     syncUndefined?: boolean;
+    /** Bidirectional mapping between store state shape and URL state shape. */
+    map?: QueryStringMap<ApplySelect<T, S>, U>;
 }
-type QueryString = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, Mps, Mcs>, options?: QueryStringOptions<T>) => StateCreator<T, Mps, Mcs>;
+type QueryString = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = [], const S extends DeepSelect<T> = DeepSelect<T>, U extends object = Record<string, unknown>>(initializer: StateCreator<T, Mps, Mcs>, options?: QueryStringOptions<T, string | false, S, U>) => StateCreator<T, Mps, Mcs>;
 declare const querystring: QueryString;
 
-export { type ParseContext, type QueryStringFormat, type QueryStringFormatFor, type QueryStringFormatNamespaced, type QueryStringFormatStandalone, type QueryStringOptions, type QueryStringParam, type QueryStringParams, querystring };
+export { type ParseContext, type QueryStringFormat, type QueryStringFormatFor, type QueryStringFormatNamespaced, type QueryStringFormatStandalone, type QueryStringMap, type QueryStringOptions, type QueryStringParam, type QueryStringParams, querystring };

package/dist/index.d.ts

@@ -3,6 +3,10 @@ import { StoreMutatorIdentifier, StateCreator } from 'zustand/vanilla';
 type DeepSelect<T> = T extends object ? {
     [P in keyof T]?: DeepSelect<T[P]> | boolean;
 } : boolean;
+/** Maps T to only the fields marked as selected in S. `false` excludes, everything else includes. */
+type ApplySelect<T, S> = [S] extends [false] ? never : S extends object ? T extends object ? {
+    [P in keyof S & keyof T as [ApplySelect<T[P], S[P]>] extends [never] ? never : P]: ApplySelect<T[P], S[P]>;
+} : never : T;
 interface QueryStringParam {
     key: string;
     value: string | string[];
@@ -32,16 +36,28 @@ interface QueryStringFormatStandalone {
 type QueryStringFormat = QueryStringFormatNamespaced & QueryStringFormatStandalone;
 /** Conditional format type based on key option */
 type QueryStringFormatFor<K extends string | false> = K extends false ? QueryStringFormatStandalone : QueryStringFormatNamespaced;
-interface QueryStringOptions<T, K extends string | false = string | false> {
+/**
+ * Bidirectional mapping between store state and URL state.
+ * `to` runs before serialization (store → URL), `from` after deserialization (URL → store).
+ * S is inferred from `select` via `ApplySelect` — only selected fields are visible.
+ * U is inferred from `to`'s return type and flows into `from`'s parameter.
+ */
+interface QueryStringMap<S, U extends object = Record<string, unknown>> {
+    to: (state: S, pathname: string) => U;
+    from: (urlState: U, pathname: string) => Partial<S>;
+}
+interface QueryStringOptions<T, K extends string | false = string | false, S extends DeepSelect<T> = DeepSelect<T>, U extends object = Record<string, unknown>> {
     url?: string;
-    select?: (pathname: string) => DeepSelect<T>;
+    select?: (pathname: string) => S;
     key?: K;
     prefix?: string;
     format?: QueryStringFormatFor<K>;
     syncNull?: boolean;
     syncUndefined?: boolean;
+    /** Bidirectional mapping between store state shape and URL state shape. */
+    map?: QueryStringMap<ApplySelect<T, S>, U>;
 }
-type QueryString = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, Mps, Mcs>, options?: QueryStringOptions<T>) => StateCreator<T, Mps, Mcs>;
+type QueryString = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = [], const S extends DeepSelect<T> = DeepSelect<T>, U extends object = Record<string, unknown>>(initializer: StateCreator<T, Mps, Mcs>, options?: QueryStringOptions<T, string | false, S, U>) => StateCreator<T, Mps, Mcs>;
 declare const querystring: QueryString;
 
-export { type ParseContext, type QueryStringFormat, type QueryStringFormatFor, type QueryStringFormatNamespaced, type QueryStringFormatStandalone, type QueryStringOptions, type QueryStringParam, type QueryStringParams, querystring };
+export { type ParseContext, type QueryStringFormat, type QueryStringFormatFor, type QueryStringFormatNamespaced, type QueryStringFormatStandalone, type QueryStringMap, type QueryStringOptions, type QueryStringParam, type QueryStringParams, querystring };

package/dist/index.js

@@ -66,7 +66,9 @@ function validateOptions(opts) {
     seen.add(token);
   }
   if (seen.has(opts.datePrefix)) {
-    throw new Error(`datePrefix '${opts.datePrefix}' conflicts with another token`);
+    throw new Error(
+      `datePrefix '${opts.datePrefix}' conflicts with another token`
+    );
   }
 }
 function escapeRegex(str) {
@@ -78,7 +80,9 @@ function buildKeyStopPattern(opts) {
   );
 }
 function buildValueStopPattern(opts) {
-  return new RegExp(`[${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}]`);
+  return new RegExp(
+    `[${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}]`
+  );
 }
 function buildKeyEscapePattern(opts) {
   return new RegExp(
@@ -87,7 +91,10 @@ function buildKeyEscapePattern(opts) {
   );
 }
 function buildValueEscapePattern(opts) {
-  return new RegExp(`([${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}])`, "g");
+  return new RegExp(
+    `([${escapeRegex(opts.separator)}${escapeRegex(opts.terminator)}])`,
+    "g"
+  );
 }
 function buildDatePattern(opts) {
   return new RegExp(`^${escapeRegex(opts.datePrefix)}-?\\d+$`);
@@ -122,7 +129,9 @@ function cleanResult(str, standalone, opts) {
   while (str.endsWith(opts.terminator)) {
     str = str.slice(0, -opts.terminator.length);
   }
-  const datePattern = new RegExp(`^${escapeRegex(opts.typeString)}${escapeRegex(opts.datePrefix)}-?\\d+$`);
+  const datePattern = new RegExp(
+    `^${escapeRegex(opts.typeString)}${escapeRegex(opts.datePrefix)}-?\\d+$`
+  );
   if (standalone && datePattern.test(str)) {
     return str.slice(opts.typeString.length);
   }
@@ -340,7 +349,12 @@ function parse(input, standalone = false, options = {}) {
     }
     return result;
   } else {
-    const escapedMarkers = [opts.typeString, opts.typePrimitive, opts.typeArray, opts.typeObject].map(escapeRegex).join("");
+    const escapedMarkers = [
+      opts.typeString,
+      opts.typePrimitive,
+      opts.typeArray,
+      opts.typeObject
+    ].map(escapeRegex).join("");
     const escapedEscape = escapeRegex(opts.escape);
     const escapedSeparator = escapeRegex(opts.separator);
     const escapedTerminator = escapeRegex(opts.terminator);
@@ -487,13 +501,25 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
     }
     return state != null ? state : {};
   };
+  const map = defaultedOptions.map;
+  const applyMapTo = (state, pathname) => {
+    return map ? map.to(state, pathname) : state;
+  };
+  const applyMapFrom = (urlState, pathname) => {
+    return map ? map.from(urlState, pathname) : urlState;
+  };
   const initialize = (url, initialState) => {
     try {
-      const stateFromUrl = getStateFromUrl(url, initialState);
+      const mappedInitial = applyMapTo(
+        getSelectedState(initialState, url.pathname),
+        url.pathname
+      );
+      const stateFromUrl = getStateFromUrl(url, mappedInitial);
       if (!stateFromUrl) {
         return initialState;
       }
-      const selected = getSelectedState(stateFromUrl, url.pathname);
+      const storeState = applyMapFrom(stateFromUrl, url.pathname);
+      const selected = getSelectedState(storeState, url.pathname);
       const merged = (0, import_lodash_es.mergeWith)(
         {},
         initialState,
@@ -521,12 +547,20 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
       api
     );
     let previouslyManagedKeys = /* @__PURE__ */ new Set();
+    const getMappedInitial = (pathname) => {
+      if (defaultedOptions.map) {
+        return applyMapTo(getSelectedState(initialState, pathname), pathname);
+      }
+      return initialState;
+    };
     const setQuery = () => {
       const url = new URL(window.location.href);
       const selectedState = getSelectedState(get(), url.pathname);
+      const stateForUrl = applyMapTo(selectedState, url.pathname);
+      const mappedInitial = getMappedInitial(url.pathname);
       const { output: newCompacted } = compact(
-        selectedState,
-        initialState,
+        stateForUrl,
+        mappedInitial,
         defaultedOptions.syncNull,
         defaultedOptions.syncUndefined
       );
@@ -534,9 +568,14 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
       let stateParams;
       let managedKeys;
       if (standalone) {
-        const allParams = format.stringifyStandalone(selectedState);
-        const currentKeys = new Set(Object.keys(allParams).map((k) => defaultedOptions.prefix + k));
-        managedKeys = /* @__PURE__ */ new Set([...Array.from(currentKeys), ...Array.from(previouslyManagedKeys)]);
+        const allParams = format.stringifyStandalone(stateForUrl);
+        const currentKeys = new Set(
+          Object.keys(allParams).map((k) => defaultedOptions.prefix + k)
+        );
+        managedKeys = /* @__PURE__ */ new Set([
+          ...Array.from(currentKeys),
+          ...Array.from(previouslyManagedKeys)
+        ]);
         previouslyManagedKeys = currentKeys;
         const compactedParams = format.stringifyStandalone(newCompacted);
         stateParams = {};
@@ -604,9 +643,14 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
     };
     const initialized = initialize(new URL(window.location.href), initialState);
     if (standalone) {
-      const initSelected = getSelectedState(initialized, new URL(window.location.href).pathname);
+      const initSelected = getSelectedState(
+        initialized,
+        new URL(window.location.href).pathname
+      );
       const initParams = format.stringifyStandalone(initSelected);
-      previouslyManagedKeys = new Set(Object.keys(initParams).map((k) => defaultedOptions.prefix + k));
+      previouslyManagedKeys = new Set(
+        Object.keys(initParams).map((k) => defaultedOptions.prefix + k)
+      );
     }
     api.getInitialState = () => initialized;
     return initialized;

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   marked
-} from "./chunk-TQQUWVLF.mjs";
+} from "./chunk-M3ILBO2T.mjs";
 
 // src/middleware.ts
 import { isEqual, mergeWith } from "lodash-es";
@@ -108,13 +108,25 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
     }
     return state != null ? state : {};
   };
+  const map = defaultedOptions.map;
+  const applyMapTo = (state, pathname) => {
+    return map ? map.to(state, pathname) : state;
+  };
+  const applyMapFrom = (urlState, pathname) => {
+    return map ? map.from(urlState, pathname) : urlState;
+  };
   const initialize = (url, initialState) => {
     try {
-      const stateFromUrl = getStateFromUrl(url, initialState);
+      const mappedInitial = applyMapTo(
+        getSelectedState(initialState, url.pathname),
+        url.pathname
+      );
+      const stateFromUrl = getStateFromUrl(url, mappedInitial);
       if (!stateFromUrl) {
         return initialState;
       }
-      const selected = getSelectedState(stateFromUrl, url.pathname);
+      const storeState = applyMapFrom(stateFromUrl, url.pathname);
+      const selected = getSelectedState(storeState, url.pathname);
       const merged = mergeWith(
         {},
         initialState,
@@ -142,12 +154,20 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
       api
     );
     let previouslyManagedKeys = /* @__PURE__ */ new Set();
+    const getMappedInitial = (pathname) => {
+      if (defaultedOptions.map) {
+        return applyMapTo(getSelectedState(initialState, pathname), pathname);
+      }
+      return initialState;
+    };
     const setQuery = () => {
       const url = new URL(window.location.href);
       const selectedState = getSelectedState(get(), url.pathname);
+      const stateForUrl = applyMapTo(selectedState, url.pathname);
+      const mappedInitial = getMappedInitial(url.pathname);
       const { output: newCompacted } = compact(
-        selectedState,
-        initialState,
+        stateForUrl,
+        mappedInitial,
         defaultedOptions.syncNull,
         defaultedOptions.syncUndefined
       );
@@ -155,9 +175,14 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
       let stateParams;
       let managedKeys;
       if (standalone) {
-        const allParams = format.stringifyStandalone(selectedState);
-        const currentKeys = new Set(Object.keys(allParams).map((k) => defaultedOptions.prefix + k));
-        managedKeys = /* @__PURE__ */ new Set([...Array.from(currentKeys), ...Array.from(previouslyManagedKeys)]);
+        const allParams = format.stringifyStandalone(stateForUrl);
+        const currentKeys = new Set(
+          Object.keys(allParams).map((k) => defaultedOptions.prefix + k)
+        );
+        managedKeys = /* @__PURE__ */ new Set([
+          ...Array.from(currentKeys),
+          ...Array.from(previouslyManagedKeys)
+        ]);
         previouslyManagedKeys = currentKeys;
         const compactedParams = format.stringifyStandalone(newCompacted);
         stateParams = {};
@@ -225,9 +250,14 @@ var queryStringImpl = (fn, options) => (set, get, api) => {
     };
     const initialized = initialize(new URL(window.location.href), initialState);
     if (standalone) {
-      const initSelected = getSelectedState(initialized, new URL(window.location.href).pathname);
+      const initSelected = getSelectedState(
+        initialized,
+        new URL(window.location.href).pathname
+      );
       const initParams = format.stringifyStandalone(initSelected);
-      previouslyManagedKeys = new Set(Object.keys(initParams).map((k) => defaultedOptions.prefix + k));
+      previouslyManagedKeys = new Set(
+        Object.keys(initParams).map((k) => defaultedOptions.prefix + k)
+      );
     }
     api.getInitialState = () => initialized;
     return initialized;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zustand-querystring",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -13,12 +13,6 @@
     "type": "github",
     "url": "https://github.com/nitedani/zustand-querystring"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -98,5 +92,11 @@
     "vitest": "^4.0.12",
     "vitest-browser-react": "^2.0.2",
     "zustand": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}