@cfasim-ui/shared 0.4.12 → 0.4.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/shared",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "type": "module",
   "description": "Shared utilities for cfasim-ui",
   "license": "Apache-2.0",

package/src/index.ts

@@ -22,5 +22,10 @@ export {
   deserialize,
   paramsToQuery,
   queryToParams,
+  jsonCodec,
+} from "./useUrlParams.js";
+export type {
+  UrlParamsOptions,
+  ParamCodec,
+  ParamCodecs,
 } from "./useUrlParams.js";
-export type { UrlParamsOptions } from "./useUrlParams.js";

package/src/useUrlParams.test.ts

@@ -7,6 +7,7 @@ import {
   paramsToQuery,
   queryToParams,
   useUrlParams,
+  jsonCodec,
   type UrlParamsRouter,
   type UrlParamsRoute,
 } from "./useUrlParams.js";
@@ -92,6 +93,105 @@ describe("queryToParams", () => {
   });
 });
 
+type InfectionRate =
+  | { type: "constant"; value: number; duration: number }
+  | { type: "empirical"; points: [number, number][] };
+
+describe("paramsToQuery (with codecs)", () => {
+  it("treats a codec path as a single atomic URL key", () => {
+    const defaults: { rate: InfectionRate } = {
+      rate: { type: "constant", value: 0.5, duration: 3 },
+    };
+    const params: { rate: InfectionRate } = {
+      rate: {
+        type: "empirical",
+        points: [
+          [0, 0],
+          [2, 1],
+        ],
+      },
+    };
+    expect(paramsToQuery(params, defaults, { rate: jsonCodec })).toEqual({
+      rate: JSON.stringify(params.rate),
+    });
+  });
+
+  it("omits a codec value that stringifies equal to the default", () => {
+    const defaults = { rate: { type: "constant", value: 0.5 } };
+    const params = { rate: { type: "constant", value: 0.5 } };
+    expect(paramsToQuery(params, defaults, { rate: jsonCodec })).toEqual({});
+  });
+
+  it("emits codec keys alongside ordinary leaves", () => {
+    const defaults = {
+      population: 10_000,
+      rate: { type: "constant", value: 0.5 } as { type: string; value: number },
+    };
+    const params = {
+      population: 20_000,
+      rate: { type: "constant", value: 0.5 } as { type: string; value: number },
+    };
+    expect(paramsToQuery(params, defaults, { rate: jsonCodec })).toEqual({
+      population: "20000",
+      // rate matches → omitted
+    });
+  });
+});
+
+describe("queryToParams (with codecs)", () => {
+  it("decodes a codec value through its custom deserializer", () => {
+    const defaults: { rate: InfectionRate } = {
+      rate: { type: "constant", value: 0.5, duration: 3 },
+    };
+    const variant: InfectionRate = {
+      type: "empirical",
+      points: [
+        [0, 0],
+        [2, 1],
+      ],
+    };
+    expect(
+      queryToParams({ rate: JSON.stringify(variant) }, defaults, {
+        rate: jsonCodec,
+      }),
+    ).toEqual({ rate: variant });
+  });
+
+  it("drops URL keys nested inside a codec boundary", () => {
+    const defaults: { rate: InfectionRate } = {
+      rate: { type: "constant", value: 0.5, duration: 3 },
+    };
+    // Stale leaf keys from the constant variant should not punch through
+    // the codec value.
+    expect(
+      queryToParams({ "rate.value": "0.9", "rate.duration": "7" }, defaults, {
+        rate: jsonCodec,
+      }),
+    ).toEqual({});
+  });
+
+  it("swallows malformed codec payloads instead of throwing", () => {
+    const defaults = { rate: { type: "constant", value: 0.5 } };
+    expect(
+      queryToParams({ rate: "{not-valid-json" }, defaults, { rate: jsonCodec }),
+    ).toEqual({});
+  });
+
+  it("supports a custom codec (base-N encoded number)", () => {
+    const hexCodec = {
+      serialize: (v: unknown) => Number(v).toString(16),
+      deserialize: (raw: string) => Number.parseInt(raw, 16),
+    };
+    const defaults = { n: 0 };
+    expect(queryToParams({ n: "ff" }, defaults, { n: hexCodec })).toEqual({
+      n: 255,
+    });
+    expect(paramsToQuery({ n: 255 }, defaults, { n: hexCodec })).toEqual({
+      n: "ff",
+    });
+  });
+});
+
 function makeRouterStub(initialQuery: Record<string, unknown> = {}) {
   const route = reactive<UrlParamsRoute>({ query: { ...initialQuery } });
   const replace = vi.fn(({ query }: { query: Record<string, string> }) => {
@@ -599,4 +699,118 @@ describe("useUrlParams (composable)", () => {
       expect(params.a).toBe(0);
     });
   });
+
+  describe("codecs", () => {
+    it("round-trips a tagged-union field through a single URL key", async () => {
+      const { router, route } = makeRouterStub();
+      const defaults: { rate: InfectionRate; population: number } = {
+        rate: { type: "constant", value: 0.5, duration: 3 },
+        population: 10_000,
+      };
+      const params = reactive(structuredClone(defaults));
+      mountWith(() =>
+        useUrlParams(params, defaults, {
+          router,
+          route,
+          debounceMs: 0,
+          codecs: { rate: jsonCodec },
+        }),
+      );
+      await nextTick();
+      params.rate = {
+        type: "empirical",
+        points: [
+          [0, 0],
+          [2, 1],
+          [4, 1.2],
+        ],
+      };
+      await nextTick();
+      await new Promise((r) => setTimeout(r, 5));
+      expect(route.query).toEqual({ rate: JSON.stringify(params.rate) });
+    });
+
+    it("hydrates a codec-encoded variant from the URL", async () => {
+      const variant: InfectionRate = {
+        type: "empirical",
+        points: [
+          [0, 0],
+          [2, 1],
+        ],
+      };
+      const { router, route } = makeRouterStub({
+        rate: JSON.stringify(variant),
+      });
+      const defaults: { rate: InfectionRate } = {
+        rate: { type: "constant", value: 0.5, duration: 3 },
+      };
+      const params = reactive(structuredClone(defaults));
+      mountWith(() =>
+        useUrlParams(params, defaults, {
+          router,
+          route,
+          debounceMs: 0,
+          codecs: { rate: jsonCodec },
+        }),
+      );
+      await nextTick();
+      expect(params.rate).toEqual(variant);
+    });
+
+    it("ignores stale descendant URL keys at a codec path", async () => {
+      // Pretend an older version stored `rate.value=0.9`; with a codec at
+      // `rate` we must not punch that through into the variant.
+      const { router, route } = makeRouterStub({ "rate.value": "0.9" });
+      const defaults: { rate: InfectionRate } = {
+        rate: { type: "constant", value: 0.5, duration: 3 },
+      };
+      const params = reactive(structuredClone(defaults));
+      mountWith(() =>
+        useUrlParams(params, defaults, {
+          router,
+          route,
+          debounceMs: 0,
+          codecs: { rate: jsonCodec },
+        }),
+      );
+      await nextTick();
+      expect(params.rate).toEqual({
+        type: "constant",
+        value: 0.5,
+        duration: 3,
+      });
+    });
+
+    it("reset clears a codec value from the URL", async () => {
+      const variant: InfectionRate = {
+        type: "empirical",
+        points: [[0, 1]],
+      };
+      const { router, route } = makeRouterStub({
+        rate: JSON.stringify(variant),
+      });
+      const defaults: { rate: InfectionRate } = {
+        rate: { type: "constant", value: 0.5, duration: 3 },
+      };
+      const params = reactive(structuredClone(defaults));
+      const { api } = mountWith(() =>
+        useUrlParams(params, defaults, {
+          router,
+          route,
+          debounceMs: 0,
+          codecs: { rate: jsonCodec },
+        }),
+      );
+      await nextTick();
+      expect(params.rate).toEqual(variant);
+      api.reset();
+      await nextTick();
+      expect(params.rate).toEqual({
+        type: "constant",
+        value: 0.5,
+        duration: 3,
+      });
+      expect(route.query).toEqual({});
+    });
+  });
 });

package/src/useUrlParams.ts

@@ -35,6 +35,43 @@ export type DefaultsInput<T> = T | Ref<T> | (() => T | undefined);
  */
 export type ParamPath<T> = keyof T | (string & {});
 
+/**
+ * Custom serializer/deserializer pair for a single path. Lets the consumer
+ * round-trip a value through one URL key as an opaque string instead of
+ * letting `useUrlParams` flatten through it. Use for tagged unions,
+ * polymorphic objects, or anything else whose shape can change at runtime —
+ * the default leaf-flattening can only enumerate fields present in
+ * `defaults`, so variants that aren't the default variant lose their
+ * fields.
+ */
+export type ParamCodec = {
+  serialize: (value: unknown) => string;
+  deserialize: (raw: string) => unknown;
+};
+
+/**
+ * Map of dotted path → codec. A path with a codec is treated as a single
+ * atomic leaf: its whole subtree round-trips through one URL key, and any
+ * descendant URL keys are ignored. Top-level keys (`"infectionRate"`) and
+ * nested paths (`"model.infectionRate"`) both work; segments in the path
+ * use `.` as the separator, matching the same convention as
+ * `include`/`ignore`.
+ */
+export type ParamCodecs = Record<string, ParamCodec>;
+
+/**
+ * Convenience codec that uses `JSON.stringify` / `JSON.parse`. Suitable
+ * for tagged unions and small object/array values. Note that comparison
+ * during URL writes is string-equality on the stringified form, so two
+ * objects with the same fields in different key orders will look distinct;
+ * provide a custom codec with a normalized stringifier if you need
+ * order-insensitive comparison.
+ */
+export const jsonCodec: ParamCodec = {
+  serialize: (value) => JSON.stringify(value),
+  deserialize: (raw) => JSON.parse(raw),
+};
+
 export type UrlParamsOptions<T> = {
   debounceMs?: number;
   /**
@@ -55,6 +92,14 @@ export type UrlParamsOptions<T> = {
    * if `include` is provided.
    */
   ignore?: ParamPath<T>[];
+  /**
+   * Per-path codecs. A path listed here is round-tripped as one opaque
+   * string under that key (using the codec's `serialize`/`deserialize`)
+   * instead of being flattened. URL keys nested inside a codec path are
+   * ignored, so a leftover `foo.bar=1` from an earlier shape doesn't
+   * punch through the atomic value.
+   */
+  codecs?: ParamCodecs;
 };
 
 export type ResetOptions = {
@@ -109,20 +154,42 @@ function isBranch(value: unknown): boolean {
 function* flattenLeaves(
   obj: Record<string, unknown> | unknown[],
   prefix: string[] = [],
+  stopPaths?: Set<string>,
 ): Generator<[string[], unknown]> {
   const entries: Array<[string, unknown]> = Array.isArray(obj)
     ? obj.map((v, i) => [String(i), v])
     : Object.entries(obj);
   for (const [k, v] of entries) {
     const path = [...prefix, k];
-    if (isBranch(v)) {
-      yield* flattenLeaves(v as Record<string, unknown> | unknown[], path);
+    // `stopPaths` (codec paths) halt recursion: the whole subtree at that
+    // path is yielded as a single leaf value so a codec can serialize it
+    // atomically.
+    if (isBranch(v) && !stopPaths?.has(path.join("."))) {
+      yield* flattenLeaves(
+        v as Record<string, unknown> | unknown[],
+        path,
+        stopPaths,
+      );
     } else {
       yield [path, v];
     }
   }
 }
 
+// True iff some proper-prefix ancestor of `segments` is a codec path. Used
+// to drop URL keys that would punch through a codec boundary (e.g. a stale
+// `infectionRate.value=0.5` left over from before infectionRate gained a
+// codec).
+function pathIsInsideAnyCodec(
+  segments: string[],
+  codecPaths: Set<string>,
+): boolean {
+  for (let i = 1; i < segments.length; i++) {
+    if (codecPaths.has(segments.slice(0, i).join("."))) return true;
+  }
+  return false;
+}
+
 function getAtSegments(obj: unknown, segments: string[]): unknown {
   let cur: unknown = obj;
   for (const p of segments) {
@@ -184,12 +251,19 @@ function decodeKey(key: string): string[] {
 function deepMerge(
   target: Record<string, unknown> | unknown[],
   source: Record<string, unknown> | unknown[],
+  stopPaths?: Set<string>,
+  prefix: string[] = [],
 ): Record<string, unknown> | unknown[] {
   for (const [k, v] of Object.entries(source)) {
     const slot = (target as Record<string, unknown>)[k];
-    if (isContainer(v) && isContainer(slot)) {
-      deepMerge(slot, v);
+    const path = stopPaths ? [...prefix, k] : prefix;
+    const atStop = stopPaths?.has(path.join("."));
+    if (!atStop && isContainer(v) && isContainer(slot)) {
+      deepMerge(slot, v, stopPaths, path);
     } else {
+      // Codec paths are atomic: overwrite the target subtree with source's
+      // value instead of merging the two variants field-by-field (which
+      // would produce a malformed hybrid for tagged unions).
       (target as Record<string, unknown>)[k] = v;
     }
   }
@@ -199,15 +273,21 @@ function deepMerge(
 export function paramsToQuery<T extends object>(
   params: T,
   defaults: T,
+  codecs?: ParamCodecs,
 ): Record<string, string> {
   const query: Record<string, string> = {};
+  const stopPaths = codecs ? new Set(Object.keys(codecs)) : undefined;
   for (const [segments, defaultLeaf] of flattenLeaves(
     defaults as Record<string, unknown>,
+    [],
+    stopPaths,
   )) {
     const paramLeaf = getAtSegments(params, segments);
     if (paramLeaf === undefined) continue;
-    const serialized = serialize(paramLeaf);
-    const defaultSerialized = serialize(defaultLeaf);
+    const codec = codecs?.[segments.join(".")];
+    const serializeFn = codec ? codec.serialize : serialize;
+    const serialized = serializeFn(paramLeaf);
+    const defaultSerialized = serializeFn(defaultLeaf);
     if (serialized !== defaultSerialized) {
       query[encodeKey(segments)] = serialized;
     }
@@ -218,11 +298,25 @@ export function paramsToQuery<T extends object>(
 export function queryToParams<T extends object>(
   query: Record<string, unknown>,
   defaults: T,
+  codecs?: ParamCodecs,
 ): Partial<T> {
   const result: Record<string, unknown> = {};
+  const codecPaths = codecs ? new Set(Object.keys(codecs)) : undefined;
   for (const [key, raw] of Object.entries(query)) {
     if (typeof raw !== "string") continue;
     const segments = decodeKey(key);
+    const pathStr = segments.join(".");
+    const codec = codecs?.[pathStr];
+    if (codec) {
+      try {
+        setAtSegments(result, segments, codec.deserialize(raw), defaults);
+      } catch {
+        // Malformed codec value — skip rather than corrupt the params.
+      }
+      continue;
+    }
+    // Drop descendants of a codec path; the codec owns the whole subtree.
+    if (codecPaths && pathIsInsideAnyCodec(segments, codecPaths)) continue;
     const defaultLeaf = getAtSegments(defaults, segments);
     // Drop unknown dotted keys: matches the flat behavior and keeps the
     // params shape stable.
@@ -282,10 +376,15 @@ function filterDefaults<T extends object>(
   obj: T,
   include?: string[][],
   ignore?: string[][],
+  stopPaths?: Set<string>,
 ): T {
   if (!include && !ignore) return obj;
   const out: Record<string, unknown> = {};
-  for (const [path, leaf] of flattenLeaves(obj as Record<string, unknown>)) {
+  for (const [path, leaf] of flattenLeaves(
+    obj as Record<string, unknown>,
+    [],
+    stopPaths,
+  )) {
     if (pathInScope(path, include, ignore)) {
       setAtSegments(out, path, leaf, obj);
     }
@@ -317,15 +416,16 @@ export function useUrlParams<T extends object>(
   options: UrlParamsOptions<T> = {},
 ) {
   const debounceMs = options.debounceMs ?? 300;
-  const { router, route, include, ignore } = options;
+  const { router, route, include, ignore, codecs } = options;
   const includeSegments = include?.map((e) => String(e).split("."));
   const ignoreSegments = ignore?.map((e) => String(e).split("."));
+  const codecPaths = codecs ? new Set(Object.keys(codecs)) : undefined;
   const getDefaults = toGetter<T>(defaults);
   const scopedDefaults = (): T | undefined => {
     const d = getDefaults();
     return d === undefined
       ? undefined
-      : filterDefaults(d, includeSegments, ignoreSegments);
+      : filterDefaults(d, includeSegments, ignoreSegments, codecPaths);
   };
 
   function readQuery(): Record<string, unknown> {
@@ -354,7 +454,11 @@ export function useUrlParams<T extends object>(
     // precision so a leaf array like `tags=1,2` replaces the whole leaf
     // instead of merging element-wise with the default array.
     const current = structuredClone(toRaw(read())) as Record<string, unknown>;
-    deepMerge(current, structuredClone(toRaw(d)) as Record<string, unknown>);
+    deepMerge(
+      current,
+      structuredClone(toRaw(d)) as Record<string, unknown>,
+      codecPaths,
+    );
     for (const [segments, value] of overrides) {
       setAtSegments(current, segments, value, d);
     }
@@ -371,6 +475,17 @@ export function useUrlParams<T extends object>(
     for (const [key, raw] of Object.entries(readQuery())) {
       if (typeof raw !== "string") continue;
       const segments = decodeKey(key);
+      const pathStr = segments.join(".");
+      const codec = codecs?.[pathStr];
+      if (codec) {
+        try {
+          out.push([segments, codec.deserialize(raw)]);
+        } catch {
+          // skip malformed codec values
+        }
+        continue;
+      }
+      if (codecPaths && pathIsInsideAnyCodec(segments, codecPaths)) continue;
       const defaultLeaf = getAtSegments(d, segments);
       if (defaultLeaf === undefined) continue;
       out.push([segments, deserialize(raw, defaultLeaf)]);
@@ -413,7 +528,7 @@ export function useUrlParams<T extends object>(
       debounceTimer = setTimeout(() => {
         const d = scopedDefaults();
         if (d === undefined) return;
-        writeQuery(paramsToQuery(read(), d));
+        writeQuery(paramsToQuery(read(), d, codecs));
       }, debounceMs);
     },
     { deep: true },