zustand-querystring 0.4.1 → 0.6.0

package/dist/format/plain.mjs

@@ -0,0 +1,434 @@
+// src/format/plain.ts
+function resolveOptions(opts = {}) {
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i;
+  return {
+    entrySep: (_a = opts.entrySeparator) != null ? _a : ",",
+    nestingSep: (_b = opts.nestingSeparator) != null ? _b : ".",
+    arraySep: (_c = opts.arraySeparator) != null ? _c : "repeat",
+    escape: (_d = opts.escapeChar) != null ? _d : "_",
+    nullStr: (_e = opts.nullString) != null ? _e : "null",
+    undefStr: (_f = opts.undefinedString) != null ? _f : "undefined",
+    infStr: (_g = opts.infinityString) != null ? _g : "Infinity",
+    negInfStr: (_h = opts.negativeInfinityString) != null ? _h : "-Infinity",
+    nanStr: (_i = opts.nanString) != null ? _i : "NaN"
+  };
+}
+function validateOptions(opts) {
+  const { entrySep, nestingSep, arraySep, escape: escape2 } = opts;
+  if (entrySep === nestingSep) {
+    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}'`);
+  }
+  if (arraySep !== "repeat" && arraySep === nestingSep) {
+    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}'`);
+  }
+  if (entrySep.length === 0 || nestingSep.length === 0 || escape2.length === 0) {
+    throw new Error("Separators and escape character cannot be empty");
+  }
+  if (arraySep !== "repeat" && arraySep.length === 0) {
+    throw new Error("arraySeparator cannot be empty");
+  }
+}
+function encodePreservingMarkers(str, opts) {
+  const markers = /* @__PURE__ */ new Set([
+    opts.entrySep,
+    opts.nestingSep,
+    opts.escape,
+    "="
+  ]);
+  if (opts.arraySep !== "repeat") {
+    markers.add(opts.arraySep);
+  }
+  let result = "";
+  for (const char of str) {
+    if (markers.has(char)) {
+      result += char;
+    } else {
+      result += encodeURIComponent(char);
+    }
+  }
+  return result;
+}
+function decodeString(str) {
+  try {
+    return decodeURIComponent(str);
+  } catch {
+    return str;
+  }
+}
+function isDate(value) {
+  return value instanceof Date && !isNaN(value.getTime());
+}
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && !isDate(value);
+}
+var ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+var NUMBER_RE = /^-?(\d+\.?\d*|\d*\.?\d+)([eE][+-]?\d+)?$/;
+function tryParseBoolean(str) {
+  if (str === "true") return true;
+  if (str === "false") return false;
+  return null;
+}
+function tryParseNumber(str, opts) {
+  if (str === opts.infStr) return Infinity;
+  if (str === opts.negInfStr) return -Infinity;
+  if (str === opts.nanStr) return NaN;
+  if (!NUMBER_RE.test(str)) return null;
+  const n = parseFloat(str);
+  return isFinite(n) ? n : null;
+}
+function tryParseDate(str) {
+  if (!ISO_DATE_RE.test(str)) return null;
+  const d = new Date(str);
+  return isDate(d) ? d : null;
+}
+function serializeValue(value, opts) {
+  if (value === null) return opts.nullStr;
+  if (value === void 0) return opts.undefStr;
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "number") {
+    if (Number.isNaN(value)) return opts.nanStr;
+    if (value === Infinity) return opts.infStr;
+    if (value === -Infinity) return opts.negInfStr;
+    return String(value);
+  }
+  if (isDate(value)) return value.toISOString();
+  return String(value);
+}
+function parseValue(str, hint, opts) {
+  if (str === opts.nullStr) return null;
+  if (str === opts.undefStr) return void 0;
+  if (str === "") return "";
+  if (hint !== null && hint !== void 0) {
+    if (typeof hint === "string") return str;
+    if (typeof hint === "number") {
+      const n2 = tryParseNumber(str, opts);
+      if (n2 !== null || Number.isNaN(n2)) return n2;
+    }
+    if (typeof hint === "boolean") {
+      const b2 = tryParseBoolean(str);
+      if (b2 !== null) return b2;
+    }
+    if (isDate(hint)) {
+      const d2 = tryParseDate(str);
+      if (d2 !== null) return d2;
+    }
+    if (Array.isArray(hint) && hint[0] !== void 0) {
+      return parseValue(str, hint[0], opts);
+    }
+  }
+  const b = tryParseBoolean(str);
+  if (b !== null) return b;
+  const d = tryParseDate(str);
+  if (d !== null) return d;
+  const n = tryParseNumber(str, opts);
+  if (n !== null || Number.isNaN(n)) return n;
+  return str;
+}
+function escape(str, chars, esc) {
+  let result = "";
+  let i = 0;
+  while (i < str.length) {
+    let matched = false;
+    for (const special of chars) {
+      if (str.substring(i, i + special.length) === special) {
+        result += esc + special;
+        i += special.length;
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) {
+      result += str[i];
+      i++;
+    }
+  }
+  return result;
+}
+function unescape(str, esc, chars) {
+  let result = "";
+  let i = 0;
+  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);
+      if (isEscapeSequence && nextPos < str.length) {
+        i = nextPos;
+        for (const special of chars) {
+          if (str.substring(i, i + special.length) === special) {
+            result += special;
+            i += special.length;
+            break;
+          }
+        }
+        continue;
+      }
+    }
+    result += str[i];
+    i++;
+  }
+  return result;
+}
+function splitEscaped(str, sep, esc) {
+  const parts = [];
+  let current = "";
+  let i = 0;
+  while (i < str.length) {
+    if (str.substring(i, i + esc.length) === esc) {
+      const nextPos = i + esc.length;
+      const isEscapeSequence = str.substring(nextPos, nextPos + sep.length) === sep;
+      if (isEscapeSequence && nextPos < str.length) {
+        current += esc + sep;
+        i = nextPos + sep.length;
+        continue;
+      }
+    }
+    if (str.substring(i, i + sep.length) === sep) {
+      parts.push(current);
+      current = "";
+      i += sep.length;
+      continue;
+    }
+    current += str[i];
+    i++;
+  }
+  parts.push(current);
+  return parts;
+}
+function findUnescaped(str, char, esc) {
+  let i = 0;
+  while (i < str.length) {
+    if (str.substring(i, i + esc.length) === esc) {
+      const nextPos = i + esc.length;
+      if (str.substring(nextPos, nextPos + char.length) === char) {
+        i = nextPos + char.length;
+        continue;
+      }
+    }
+    if (str.substring(i, i + char.length) === char) {
+      return i;
+    }
+    i++;
+  }
+  return -1;
+}
+function escapeKey(key, opts) {
+  return escape(key, [opts.nestingSep, opts.entrySep, "="], opts.escape);
+}
+function parseKeyPath(path, opts) {
+  const segments = splitEscaped(path, opts.nestingSep, opts.escape);
+  const keySpecials = [opts.nestingSep, opts.entrySep, "="];
+  return segments.map((seg) => unescape(seg, opts.escape, keySpecials));
+}
+function getHintAtPath(state, path) {
+  let current = state;
+  for (const key of path) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return void 0;
+    }
+    if (Array.isArray(current)) {
+      current = current[0];
+      continue;
+    }
+    current = current[key];
+  }
+  return current;
+}
+function setAtPath(obj, path, value) {
+  let current = obj;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+    const nextKey = path[i + 1];
+    const nextIsIndex = /^\d+$/.test(nextKey);
+    if (current[key] === void 0) {
+      current[key] = nextIsIndex ? [] : {};
+    }
+    current = current[key];
+  }
+  const lastKey = path[path.length - 1];
+  if (/^\d+$/.test(lastKey)) {
+    current[parseInt(lastKey, 10)] = value;
+  } else {
+    current[lastKey] = value;
+  }
+}
+function flatten(obj, prefix, opts) {
+  const result = {};
+  const valueEscapeChars = [opts.entrySep];
+  if (opts.arraySep !== "repeat" && opts.arraySep !== opts.entrySep) {
+    valueEscapeChars.push(opts.arraySep);
+  }
+  for (const [rawKey, value] of Object.entries(obj)) {
+    if (typeof value === "function") continue;
+    const escapedKey = escapeKey(rawKey, opts);
+    const fullKey = prefix ? prefix + opts.nestingSep + escapedKey : escapedKey;
+    if (value === null || value === void 0 || typeof value === "boolean" || typeof value === "number" || typeof value === "string" || isDate(value)) {
+      const serialized = serializeValue(value, opts);
+      const escapedValue = escape(serialized, valueEscapeChars, opts.escape);
+      result[fullKey] = [escapedValue];
+      continue;
+    }
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        result[fullKey] = [""];
+        continue;
+      }
+      const hasObjects = value.some((item) => isObject(item));
+      if (hasObjects) {
+        for (let i = 0; i < value.length; i++) {
+          const item = value[i];
+          const indexedKey = fullKey + opts.nestingSep + i;
+          if (isObject(item)) {
+            Object.assign(result, flatten(item, indexedKey, opts));
+          } else {
+            const serialized = serializeValue(item, opts);
+            const escapedValue = escape(serialized, valueEscapeChars, opts.escape);
+            result[indexedKey] = [escapedValue];
+          }
+        }
+      } else {
+        result[fullKey] = value.map((item) => {
+          const serialized = serializeValue(item, opts);
+          return escape(serialized, valueEscapeChars, opts.escape);
+        });
+      }
+      continue;
+    }
+    if (isObject(value)) {
+      Object.assign(result, flatten(value, fullKey, opts));
+    }
+  }
+  return result;
+}
+function unflatten(entries, initialState, opts) {
+  const result = {};
+  const keys = Object.keys(entries).sort((a, b) => {
+    const pathA = parseKeyPath(a, opts);
+    const pathB = parseKeyPath(b, opts);
+    return pathA.length !== pathB.length ? pathA.length - pathB.length : a.localeCompare(b);
+  });
+  for (const key of keys) {
+    let rawValues = entries[key];
+    const path = parseKeyPath(key, opts);
+    const hint = getHintAtPath(initialState, path);
+    const isArrayHint = Array.isArray(hint);
+    const valueSpecials = [opts.entrySep];
+    if (opts.arraySep !== "repeat") {
+      valueSpecials.push(opts.arraySep);
+    }
+    const unescapeValue = (v) => unescape(v, opts.escape, valueSpecials);
+    let values;
+    if (opts.arraySep !== "repeat" && rawValues.length === 1) {
+      const parts = splitEscaped(rawValues[0], opts.arraySep, opts.escape);
+      const isArray = parts.length > 1 || isArrayHint;
+      values = isArray ? parts.map(unescapeValue) : [unescapeValue(rawValues[0])];
+    } else {
+      values = rawValues.map(unescapeValue);
+    }
+    if (values.length === 1 && values[0] === "" && isArrayHint) {
+      setAtPath(result, path, []);
+      continue;
+    }
+    if (values.length === 1 && !isArrayHint) {
+      setAtPath(result, path, parseValue(values[0], hint, opts));
+      continue;
+    }
+    const elementHint = isArrayHint ? hint[0] : void 0;
+    setAtPath(result, path, values.map((v) => parseValue(v, elementHint, opts)));
+  }
+  return result;
+}
+function parseNamespaced(input, opts) {
+  if (!input) return {};
+  const decoded = decodeString(input);
+  const entries = {};
+  const parts = splitEscaped(decoded, opts.entrySep, opts.escape);
+  let currentKey = null;
+  let currentParts = [];
+  for (const part of parts) {
+    const eqIndex = findUnescaped(part, "=", opts.escape);
+    if (eqIndex !== -1) {
+      if (currentKey !== null) {
+        if (!entries[currentKey]) entries[currentKey] = [];
+        entries[currentKey].push(currentParts.join(opts.entrySep));
+      }
+      currentKey = part.slice(0, eqIndex);
+      currentParts = [part.slice(eqIndex + 1)];
+    } else if (currentKey !== null) {
+      currentParts.push(part);
+    }
+  }
+  if (currentKey !== null) {
+    if (!entries[currentKey]) entries[currentKey] = [];
+    entries[currentKey].push(currentParts.join(opts.entrySep));
+  }
+  return entries;
+}
+function stringifyNamespaced(state, opts) {
+  const entries = flatten(state, "", opts);
+  const parts = [];
+  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));
+      }
+    } else {
+      parts.push(encodePreservingMarkers(key, opts) + "=" + encodePreservingMarkers(values.join(opts.arraySep), opts));
+    }
+  }
+  return parts.join(opts.entrySep);
+}
+function stringifyStandalone(state, opts) {
+  const entries = flatten(state, "", opts);
+  const result = {};
+  for (const [key, values] of Object.entries(entries)) {
+    const encodedKey = encodePreservingMarkers(key, opts);
+    const encodedValues = values.map((v) => encodePreservingMarkers(v, opts));
+    if (opts.arraySep === "repeat") {
+      result[encodedKey] = encodedValues;
+    } else {
+      result[encodedKey] = [encodedValues.join(opts.arraySep)];
+    }
+  }
+  return result;
+}
+function parseStandalone(params, initialState, opts) {
+  const entries = {};
+  for (const [key, values] of Object.entries(params)) {
+    const decodedKey = decodeString(key);
+    entries[decodedKey] = values.map((v) => decodeString(v));
+  }
+  return unflatten(entries, initialState, opts);
+}
+function createFormat(options = {}) {
+  const opts = resolveOptions(options);
+  validateOptions(opts);
+  return {
+    stringify(state) {
+      return stringifyNamespaced(state, opts);
+    },
+    parse(input, ctx) {
+      var _a;
+      const entries = parseNamespaced(input, opts);
+      return unflatten(entries, (_a = ctx == null ? void 0 : ctx.initialState) != null ? _a : {}, opts);
+    },
+    stringifyStandalone(state) {
+      return stringifyStandalone(state, opts);
+    },
+    parseStandalone(params, ctx) {
+      return parseStandalone(params, ctx.initialState, opts);
+    }
+  };
+}
+var plain = createFormat();
+export {
+  createFormat,
+  plain
+};
+/* v8 ignore next 3 -- @preserve: defensive code - unflatten always extracts hint[0] before calling parseValue */
+/* v8 ignore next 3 -- @preserve: defensive - handles non-serializable types like Symbol, Set, Map */

package/dist/index.d.mts

@@ -3,28 +3,45 @@ import { StoreMutatorIdentifier, StateCreator } from 'zustand/vanilla';
 type DeepSelect<T> = T extends object ? {
     [P in keyof T]?: DeepSelect<T[P]> | boolean;
 } : boolean;
-interface QueryStringFormat {
-    stringify: (value: any, standalone?: boolean) => string;
-    parse: (value: string, standalone?: boolean) => any;
+interface QueryStringParam {
+    key: string;
+    value: string | string[];
+}
+/** Record of key to array of values - always arrays for consistency */
+type QueryStringParams = Record<string, string[]>;
+/** Format for namespaced mode (key is a string) */
+interface QueryStringFormatNamespaced {
+    /** Serialize entire state into a single encoded string */
+    stringify: (state: object) => string;
+    /** Deserialize a single encoded string back to state */
+    parse: (value: string, ctx?: ParseContext) => object;
+}
+/** Context passed to parse methods for type inference and future extensibility */
+interface ParseContext {
+    /** Initial state for type inference */
+    initialState: object;
+}
+/** Format for standalone mode (key is false) */
+interface QueryStringFormatStandalone {
+    /** Serialize state into key-value pairs (always arrays for consistency) */
+    stringifyStandalone: (state: object) => QueryStringParams;
+    /** Deserialize key-value pairs back to state */
+    parseStandalone: (params: QueryStringParams, ctx: ParseContext) => object;
 }
-interface QueryStringOptions<T> {
+/** Full format implementing both modes */
+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> {
     url?: string;
     select?: (pathname: string) => DeepSelect<T>;
-    key?: string | false;
-    format?: QueryStringFormat;
+    key?: K;
+    prefix?: string;
+    format?: QueryStringFormatFor<K>;
     syncNull?: boolean;
     syncUndefined?: boolean;
 }
 type QueryString = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, Mps, Mcs>, options?: QueryStringOptions<T>) => StateCreator<T, Mps, Mcs>;
 declare const querystring: QueryString;
 
-declare function stringify(input: unknown): string;
-declare function parse(str: string): any;
-
-declare const createURL: ({ baseUrl, key, state, }: {
-    baseUrl: string;
-    key: string;
-    state: Object;
-}) => string;
-
-export { type QueryStringOptions, createURL, parse, querystring, stringify };
+export { type ParseContext, type QueryStringFormat, type QueryStringFormatFor, type QueryStringFormatNamespaced, type QueryStringFormatStandalone, type QueryStringOptions, type QueryStringParam, type QueryStringParams, querystring };

package/dist/index.d.ts

@@ -3,28 +3,45 @@ import { StoreMutatorIdentifier, StateCreator } from 'zustand/vanilla';
 type DeepSelect<T> = T extends object ? {
     [P in keyof T]?: DeepSelect<T[P]> | boolean;
 } : boolean;
-interface QueryStringFormat {
-    stringify: (value: any, standalone?: boolean) => string;
-    parse: (value: string, standalone?: boolean) => any;
+interface QueryStringParam {
+    key: string;
+    value: string | string[];
+}
+/** Record of key to array of values - always arrays for consistency */
+type QueryStringParams = Record<string, string[]>;
+/** Format for namespaced mode (key is a string) */
+interface QueryStringFormatNamespaced {
+    /** Serialize entire state into a single encoded string */
+    stringify: (state: object) => string;
+    /** Deserialize a single encoded string back to state */
+    parse: (value: string, ctx?: ParseContext) => object;
+}
+/** Context passed to parse methods for type inference and future extensibility */
+interface ParseContext {
+    /** Initial state for type inference */
+    initialState: object;
+}
+/** Format for standalone mode (key is false) */
+interface QueryStringFormatStandalone {
+    /** Serialize state into key-value pairs (always arrays for consistency) */
+    stringifyStandalone: (state: object) => QueryStringParams;
+    /** Deserialize key-value pairs back to state */
+    parseStandalone: (params: QueryStringParams, ctx: ParseContext) => object;
 }
-interface QueryStringOptions<T> {
+/** Full format implementing both modes */
+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> {
     url?: string;
     select?: (pathname: string) => DeepSelect<T>;
-    key?: string | false;
-    format?: QueryStringFormat;
+    key?: K;
+    prefix?: string;
+    format?: QueryStringFormatFor<K>;
     syncNull?: boolean;
     syncUndefined?: boolean;
 }
 type QueryString = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = []>(initializer: StateCreator<T, Mps, Mcs>, options?: QueryStringOptions<T>) => StateCreator<T, Mps, Mcs>;
 declare const querystring: QueryString;
 
-declare function stringify(input: unknown): string;
-declare function parse(str: string): any;
-
-declare const createURL: ({ baseUrl, key, state, }: {
-    baseUrl: string;
-    key: string;
-    state: Object;
-}) => string;
-
-export { type QueryStringOptions, createURL, parse, querystring, stringify };
+export { type ParseContext, type QueryStringFormat, type QueryStringFormatFor, type QueryStringFormatNamespaced, type QueryStringFormatStandalone, type QueryStringOptions, type QueryStringParam, type QueryStringParams, querystring };