@nodaro/shared 1.4.1

package/src/__tests__/json-evaluator.test.ts

@@ -0,0 +1,289 @@
+import { describe, it, expect } from "vitest"
+import { buildExpressionFromVisual } from "../json-evaluator.js"
+
+describe("buildExpressionFromVisual", () => {
+  it("returns identity for empty config", () => {
+    expect(buildExpressionFromVisual({})).toBe(".")
+  })
+
+  it("returns dot-path for inputPath only", () => {
+    expect(buildExpressionFromVisual({ inputPath: "data.items" })).toBe(".data.items")
+  })
+
+  it("adds [] when filters exist", () => {
+    const result = buildExpressionFromVisual({
+      inputPath: "products",
+      filters: [{ id: "1", field: "price", operator: "less_than" as const, value: "50" }],
+    })
+    expect(result).toBe('.products[] | select(.price < 50)')
+  })
+
+  it("adds [] when projections exist", () => {
+    const result = buildExpressionFromVisual({
+      inputPath: "products",
+      projections: ["name", "price"],
+    })
+    expect(result).toBe('.products[] | {name, price}')
+  })
+
+  it("generates all three stages", () => {
+    const result = buildExpressionFromVisual({
+      inputPath: "products",
+      filters: [{ id: "1", field: "price", operator: "less_than" as const, value: "50" }],
+      projections: ["name", "url", "price"],
+    })
+    expect(result).toBe('.products[] | select(.price < 50) | {name, url, price}')
+  })
+
+  it("iterates root when no inputPath but filters exist", () => {
+    const result = buildExpressionFromVisual({
+      filters: [{ id: "1", field: "status", operator: "equals" as const, value: "active" }],
+    })
+    expect(result).toBe('.[] | select(.status == "active")')
+  })
+
+  it("iterates root when no inputPath but projections exist", () => {
+    const result = buildExpressionFromVisual({
+      projections: ["name", "email"],
+    })
+    expect(result).toBe('.[] | {name, email}')
+  })
+
+  it("joins multiple filters with pipe (AND)", () => {
+    const result = buildExpressionFromVisual({
+      filters: [
+        { id: "1", field: "status", operator: "equals" as const, value: "active" },
+        { id: "2", field: "age", operator: "greater_than" as const, value: "18" },
+      ],
+    })
+    expect(result).toBe('.[] | select(.status == "active") | select(.age > 18)')
+  })
+
+  it("uses bracket notation for non-identifier-safe fields in filters", () => {
+    const result = buildExpressionFromVisual({
+      filters: [{ id: "1", field: "api-key", operator: "equals" as const, value: "abc" }],
+    })
+    expect(result).toBe('.[] | select(.["api-key"] == "abc")')
+  })
+
+  it("uses bracket notation for non-identifier-safe fields in projections", () => {
+    const result = buildExpressionFromVisual({
+      projections: ["name", "api-key"],
+    })
+    expect(result).toBe('.[] | {name, "api-key": .["api-key"]}')
+  })
+})
+
+describe("filter operator mapping", () => {
+  const wrap = (op: string, field: string, value: string | string[]) =>
+    buildExpressionFromVisual({
+      filters: [{ id: "1", field, operator: op as any, value }],
+    })
+
+  it("equals with string", () => expect(wrap("equals", "s", "active")).toBe('.[] | select(.s == "active")'))
+  it("equals with number", () => expect(wrap("equals", "n", "42")).toBe('.[] | select(.n == 42)'))
+  it("not_equals", () => expect(wrap("not_equals", "s", "draft")).toBe('.[] | select(.s != "draft")'))
+  it("contains", () => expect(wrap("contains", "s", "foo")).toBe('.[] | select(.s | contains("foo"))'))
+  it("not_contains", () => expect(wrap("not_contains", "s", "bar")).toBe('.[] | select(.s | contains("bar") | not)'))
+  it("starts_with", () => expect(wrap("starts_with", "s", "pre")).toBe('.[] | select(.s | startswith("pre"))'))
+  it("ends_with", () => expect(wrap("ends_with", "s", ".jpg")).toBe('.[] | select(.s | endswith(".jpg"))'))
+  it("greater_than", () => expect(wrap("greater_than", "n", "50")).toBe('.[] | select(.n > 50)'))
+  it("less_than", () => expect(wrap("less_than", "n", "100")).toBe('.[] | select(.n < 100)'))
+  it("is_empty", () => expect(wrap("is_empty", "s", "")).toBe('.[] | select(.s == null or .s == "")'))
+  it("is_not_empty", () => expect(wrap("is_not_empty", "s", "")).toBe('.[] | select(.s != null and .s != "")'))
+  it("matches_regex", () => expect(wrap("matches_regex", "s", "^A")).toBe('.[] | select(.s | test("^A"))'))
+  it("in_list", () => expect(wrap("in_list", "s", ["a", "b"])).toBe('.[] | select(.s == "a" or .s == "b")'))
+  it("in_list with number", () => expect(wrap("in_list", "n", ["1", "2"])).toBe('.[] | select(.n == 1 or .n == 2)'))
+  // Regression: switching to in_list keeps the previous operator's string value
+  // until the user edits it. Previously this threw `value.map is not a function`
+  // during re-render, crashing the config panel.
+  it("in_list tolerates a comma-separated string (operator just switched)", () =>
+    expect(wrap("in_list", "s", "a, b, c")).toBe('.[] | select(.s == "a" or .s == "b" or .s == "c")'))
+  it("in_list with a plain string falls back to single-value equality", () =>
+    expect(wrap("in_list", "s", "only")).toBe('.[] | select(.s == "only")'))
+  it("in_list with empty value emits select(false) so nothing passes", () =>
+    expect(wrap("in_list", "s", "")).toBe('.[] | select(false)'))
+})
+
+describe("string escaping", () => {
+  const wrap = (op: string, field: string, value: string | string[]) =>
+    buildExpressionFromVisual({
+      filters: [{ id: "1", field, operator: op as any, value }],
+    })
+
+  it("escapes double-quote in contains value", () =>
+    expect(wrap("contains", "s", 'say "hi"')).toBe('.[] | select(.s | contains("say \\"hi\\""))'))
+
+  it("escapes backslash in contains value", () =>
+    expect(wrap("contains", "s", "a\\b")).toBe('.[] | select(.s | contains("a\\\\b"))'))
+
+  it("escapes double-quote in starts_with value", () =>
+    expect(wrap("starts_with", "s", 'a"b')).toBe('.[] | select(.s | startswith("a\\"b"))'))
+
+  it("escapes double-quote in equals value", () =>
+    expect(wrap("equals", "s", 'a"b')).toBe('.[] | select(.s == "a\\"b")'))
+
+  it("escapes double-quote in matches_regex value", () =>
+    expect(wrap("matches_regex", "s", 'a"b')).toBe('.[] | select(.s | test("a\\"b"))'))
+
+  it("escapes double-quote in field name bracket notation", () => {
+    const r = buildExpressionFromVisual({
+      filters: [{ id: "1", field: 'weird"name', operator: "equals" as const, value: "x" }],
+    })
+    expect(r).toBe('.[] | select(.["weird\\"name"] == "x")')
+  })
+
+  it("escapes double-quote in in_list value", () => {
+    const r = buildExpressionFromVisual({
+      filters: [{ id: "1", field: "s", operator: "in_list" as const, value: ['a"b', "c"] }],
+    })
+    expect(r).toBe('.[] | select(.s == "a\\"b" or .s == "c")')
+  })
+})
+
+import { evaluateJsonExpression } from "../json-evaluator.js"
+
+describe("evaluateJsonExpression", () => {
+  const data = [
+    { name: "Alice", age: 30, status: "active", email: "alice@example.com" },
+    { name: "Bob", age: 17, status: "inactive", email: "" },
+    { name: "Charlie", age: 25, status: "active", email: "charlie@example.com" },
+  ]
+
+  it("identity expression returns input as-is", () => {
+    const r = evaluateJsonExpression(data, ".")
+    expect(r).toEqual({ ok: true, value: data })
+  })
+
+  it("dot path navigates objects", () => {
+    const r = evaluateJsonExpression({ data: { items: [1, 2] } }, ".data.items")
+    expect(r).toEqual({ ok: true, value: [1, 2] })
+  })
+
+  it("bracket access works", () => {
+    const r = evaluateJsonExpression({ "api-key": "secret" }, '.["api-key"]')
+    expect(r).toEqual({ ok: true, value: "secret" })
+  })
+
+  it("array iteration expands items", () => {
+    const r = evaluateJsonExpression([1, 2, 3], ".[] | select(. > 1)")
+    expect(r).toEqual({ ok: true, value: [2, 3] })
+  })
+
+  it("index access works", () => {
+    const r = evaluateJsonExpression([10, 20, 30], ".[0]")
+    expect(r).toEqual({ ok: true, value: 10 })
+  })
+
+  it("negative index access works", () => {
+    const r = evaluateJsonExpression([10, 20, 30], ".[-1]")
+    expect(r).toEqual({ ok: true, value: 30 })
+  })
+
+  it("select filters items", () => {
+    const r = evaluateJsonExpression(data, '.[] | select(.status == "active")')
+    expect(r).toEqual({ ok: true, value: [data[0], data[2]] })
+  })
+
+  it("object construction projects fields", () => {
+    const r = evaluateJsonExpression(data, ".[] | {name, age}")
+    expect(r).toEqual({
+      ok: true,
+      value: [
+        { name: "Alice", age: 30 },
+        { name: "Bob", age: 17 },
+        { name: "Charlie", age: 25 },
+      ],
+    })
+  })
+
+  it("rename in object construction", () => {
+    const r = evaluateJsonExpression({ name: "Alice" }, "{full_name: .name}")
+    expect(r).toEqual({ ok: true, value: { full_name: "Alice" } })
+  })
+
+  it("select + project pipeline", () => {
+    const r = evaluateJsonExpression(data, '.[] | select(.age > 18) | {name, status}')
+    expect(r).toEqual({
+      ok: true,
+      value: [
+        { name: "Alice", status: "active" },
+        { name: "Charlie", status: "active" },
+      ],
+    })
+  })
+
+  it("boolean and/or in select", () => {
+    const r = evaluateJsonExpression(data, '.[] | select(.age > 18 and .status == "active")')
+    expect(r).toEqual({ ok: true, value: [data[0], data[2]] })
+  })
+
+  it("contains string function", () => {
+    const r = evaluateJsonExpression(data, '.[] | select(.name | contains("li"))')
+    expect(r).toEqual({ ok: true, value: [data[0], data[2]] })
+  })
+
+  it("startswith string function", () => {
+    const r = evaluateJsonExpression(data, '.[] | select(.name | startswith("A"))')
+    expect(r).toEqual({ ok: true, value: [data[0]] })
+  })
+
+  it("endswith string function", () => {
+    const r = evaluateJsonExpression(data, '.[] | select(.name | endswith("e"))')
+    expect(r).toEqual({ ok: true, value: [data[0], data[2]] })
+  })
+
+  it("test regex function", () => {
+    const r = evaluateJsonExpression(data, '.[] | select(.name | test("^[AC]"))')
+    expect(r).toEqual({ ok: true, value: [data[0], data[2]] })
+  })
+
+  it("not as postfix pipe", () => {
+    const r = evaluateJsonExpression(data, '.[] | select(.name | contains("Bob") | not)')
+    expect(r).toEqual({ ok: true, value: [data[0], data[2]] })
+  })
+
+  it("object[] on non-array yields object as single item", () => {
+    const obj = { name: "Alice", age: 30 }
+    const r = evaluateJsonExpression(obj, ".[] | {name}")
+    expect(r).toEqual({ ok: true, value: { name: "Alice" } })
+  })
+
+  it("returns error for unknown field with suggestions", () => {
+    const r = evaluateJsonExpression({ name: "Alice", email: "a@b.com" }, ".statsu")
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.error).toContain("statsu")
+  })
+
+  it("returns error for invalid expression", () => {
+    const r = evaluateJsonExpression({}, ".[] |")
+    expect(r.ok).toBe(false)
+  })
+
+  it("handles null/undefined input gracefully", () => {
+    const r = evaluateJsonExpression(null, ".")
+    expect(r).toEqual({ ok: true, value: null })
+  })
+
+  it("rejects nested quantifiers in regex", () => {
+    const r = evaluateJsonExpression(["a"], '.[] | select(. | test("(a+)+b"))')
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.error).toContain("complex")
+  })
+
+  it("object construction drops whole object when field value is dropped", () => {
+    const r = evaluateJsonExpression([1, 2, 3], ".[] | {v: select(. > 1), doubled: .}")
+    // First item: select(1 > 1) is DROPPED, so whole object drops → []
+    // Second item: select(2 > 1) truthy keeps 2, doubled 2 → {v: 2, doubled: 2}
+    // Third item: similar → {v: 3, doubled: 3}
+    expect(r).toEqual({ ok: true, value: [{ v: 2, doubled: 2 }, { v: 3, doubled: 3 }] })
+  })
+
+  it("does not leak state between calls", () => {
+    const arr = [1, 2, 3]
+    const r1 = evaluateJsonExpression(arr, ".[]")
+    const r2 = evaluateJsonExpression(arr, ".")
+    expect(r1).toEqual({ ok: true, value: [1, 2, 3] })
+    expect(r2).toEqual({ ok: true, value: [1, 2, 3] })
+  })
+})

package/src/__tests__/json-path.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest"
+import { evaluateJsonPath } from "../json-path.js"
+
+describe("evaluateJsonPath", () => {
+  it("returns leaf value for simple path on object", () => {
+    expect(evaluateJsonPath({ name: "Alice" }, "name")).toEqual(["Alice"])
+  })
+
+  it("returns empty array for missing property", () => {
+    expect(evaluateJsonPath({ name: "Alice" }, "age")).toEqual([])
+  })
+
+  it("auto-iterates top-level array", () => {
+    const input = [{ caption: "a" }, { caption: "b" }, { caption: "c" }]
+    expect(evaluateJsonPath(input, "caption")).toEqual(["a", "b", "c"])
+  })
+
+  it("auto-iterates nested array mid-path", () => {
+    const input = { pages: [{ url: "u1", md: "m1" }, { url: "u2", md: "m2" }] }
+    expect(evaluateJsonPath(input, "pages.url")).toEqual(["u1", "u2"])
+    expect(evaluateJsonPath(input, "pages.md")).toEqual(["m1", "m2"])
+  })
+
+  it("handles deep nesting", () => {
+    const input = [{ authorMeta: { name: "bob" } }, { authorMeta: { name: "sue" } }]
+    expect(evaluateJsonPath(input, "authorMeta.name")).toEqual(["bob", "sue"])
+  })
+
+  it("skips items missing the path (returns only successful ones)", () => {
+    const input = [{ caption: "a" }, {}, { caption: "c" }]
+    expect(evaluateJsonPath(input, "caption")).toEqual(["a", "c"])
+  })
+
+  it("returns null/undefined values as-is in the array (caller filters)", () => {
+    const input = [{ caption: null }, { caption: "b" }]
+    expect(evaluateJsonPath(input, "caption")).toEqual([null, "b"])
+  })
+
+  it("returns the full value when path is empty string", () => {
+    expect(evaluateJsonPath({ a: 1 }, "")).toEqual([{ a: 1 }])
+    expect(evaluateJsonPath([1, 2, 3], "")).toEqual([1, 2, 3])
+  })
+
+  it("treats primitive root with path as dead end", () => {
+    expect(evaluateJsonPath("hello", "foo")).toEqual([])
+    expect(evaluateJsonPath(42, "foo")).toEqual([])
+  })
+
+  it("ignores inherited properties (toString, constructor, __proto__)", () => {
+    expect(evaluateJsonPath({ a: 1 }, "toString")).toEqual([])
+    expect(evaluateJsonPath({ a: 1 }, "__proto__")).toEqual([])
+    expect(evaluateJsonPath({ a: 1 }, "constructor")).toEqual([])
+  })
+
+  it("handles objects at leaf (returns object, not stringified — caller handles coercion)", () => {
+    const input = [{ meta: { a: 1 } }, { meta: { a: 2 } }]
+    expect(evaluateJsonPath(input, "meta")).toEqual([{ a: 1 }, { a: 2 }])
+  })
+
+  it("returns each element when root is a scalar array and path is empty (whole-item mode)", () => {
+    expect(evaluateJsonPath(["a", "b", "c"], "")).toEqual(["a", "b", "c"])
+    expect(evaluateJsonPath([1, 2, 3], "")).toEqual([1, 2, 3])
+  })
+})

package/src/__tests__/lip-sync-pricing.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from "vitest"
+import {
+  pickLipSyncBucket,
+  getLipSyncMaxAudioSeconds,
+  isPerSecondLipSyncProvider,
+  buildLipSyncCreditId,
+} from "../lip-sync-pricing.js"
+
+describe("pickLipSyncBucket", () => {
+  it("rounds up to the next supported bucket", () => {
+    expect(pickLipSyncBucket(1)).toBe(15)
+    expect(pickLipSyncBucket(15)).toBe(15)
+    expect(pickLipSyncBucket(15.001)).toBe(30)
+    expect(pickLipSyncBucket(29)).toBe(30)
+    expect(pickLipSyncBucket(30)).toBe(30)
+    expect(pickLipSyncBucket(31)).toBe(60)
+    expect(pickLipSyncBucket(60)).toBe(60)
+    expect(pickLipSyncBucket(61)).toBe(120)
+    expect(pickLipSyncBucket(120)).toBe(120)
+    expect(pickLipSyncBucket(121)).toBe(300)
+    expect(pickLipSyncBucket(300)).toBe(300)
+  })
+
+  it("clamps anything above 5min to the 300s bucket", () => {
+    expect(pickLipSyncBucket(600)).toBe(300)
+  })
+
+  it("falls back to the smallest bucket for non-positive input", () => {
+    expect(pickLipSyncBucket(0)).toBe(15)
+    expect(pickLipSyncBucket(-5)).toBe(15)
+    expect(pickLipSyncBucket(NaN)).toBe(15)
+  })
+})
+
+describe("getLipSyncMaxAudioSeconds", () => {
+  it("reports 5min for Kling AI Avatar 2.0 (post-upgrade)", () => {
+    expect(getLipSyncMaxAudioSeconds("kling-avatar")).toBe(300)
+    expect(getLipSyncMaxAudioSeconds("kling-avatar-pro")).toBe(300)
+  })
+
+  it("keeps InfiniTalk at the 15s upstream cap", () => {
+    expect(getLipSyncMaxAudioSeconds("infinitalk")).toBe(15)
+  })
+
+  it("reports 5min for the Replicate per-second dubbing models", () => {
+    expect(getLipSyncMaxAudioSeconds("heygen-lipsync-precision")).toBe(300)
+    expect(getLipSyncMaxAudioSeconds("lipsync-2-pro")).toBe(300)
+  })
+
+  it("reports 5min for the fal sync-lipsync-v3 model (NOT the 15s default)", () => {
+    expect(getLipSyncMaxAudioSeconds("sync-lipsync-v3")).toBe(300)
+  })
+
+  it("reports 5min for the Volcengine dubbing model (NOT the 15s default)", () => {
+    expect(getLipSyncMaxAudioSeconds("volcengine-lipsync")).toBe(300)
+  })
+
+  it("defaults unknown providers to 15s", () => {
+    expect(getLipSyncMaxAudioSeconds("nope")).toBe(15)
+  })
+})
+
+describe("isPerSecondLipSyncProvider", () => {
+  it("flags the Kling Avatar models", () => {
+    expect(isPerSecondLipSyncProvider("kling-avatar")).toBe(true)
+    expect(isPerSecondLipSyncProvider("kling-avatar-pro")).toBe(true)
+  })
+
+  it("flags the Replicate per-second dubbing models", () => {
+    expect(isPerSecondLipSyncProvider("heygen-lipsync-precision")).toBe(true)
+    expect(isPerSecondLipSyncProvider("lipsync-2-pro")).toBe(true)
+  })
+
+  it("flags the fal sync-lipsync-v3 model", () => {
+    expect(isPerSecondLipSyncProvider("sync-lipsync-v3")).toBe(true)
+  })
+
+  it("flags the Volcengine dubbing model", () => {
+    expect(isPerSecondLipSyncProvider("volcengine-lipsync")).toBe(true)
+  })
+
+  it("returns false for everything else", () => {
+    expect(isPerSecondLipSyncProvider("infinitalk")).toBe(false)
+    expect(isPerSecondLipSyncProvider("latentsync")).toBe(false)
+  })
+})
+
+describe("buildLipSyncCreditId", () => {
+  it("emits composite IDs for Kling Avatar models", () => {
+    expect(buildLipSyncCreditId("kling-avatar", 10)).toBe("kling-avatar:15s")
+    expect(buildLipSyncCreditId("kling-avatar", 45)).toBe("kling-avatar:60s")
+    expect(buildLipSyncCreditId("kling-avatar-pro", 200)).toBe("kling-avatar-pro:300s")
+  })
+
+  it("falls back to the 5-min ceiling when duration is missing", () => {
+    expect(buildLipSyncCreditId("kling-avatar", undefined)).toBe("kling-avatar:300s")
+    expect(buildLipSyncCreditId("kling-avatar-pro", undefined)).toBe("kling-avatar-pro:300s")
+  })
+
+  it("clamps overly long durations to the 300s bucket", () => {
+    expect(buildLipSyncCreditId("kling-avatar", 999)).toBe("kling-avatar:300s")
+  })
+
+  it("emits composite IDs for the Replicate per-second dubbing models", () => {
+    expect(buildLipSyncCreditId("heygen-lipsync-precision", 12)).toBe("heygen-lipsync-precision:15s")
+    expect(buildLipSyncCreditId("heygen-lipsync-precision", 45)).toBe("heygen-lipsync-precision:60s")
+    expect(buildLipSyncCreditId("lipsync-2-pro", 200)).toBe("lipsync-2-pro:300s")
+    expect(buildLipSyncCreditId("lipsync-2-pro", undefined)).toBe("lipsync-2-pro:300s")
+  })
+
+  it("emits composite IDs for the fal sync-lipsync-v3 model", () => {
+    expect(buildLipSyncCreditId("sync-lipsync-v3", 12)).toBe("sync-lipsync-v3:15s")
+    expect(buildLipSyncCreditId("sync-lipsync-v3", 200)).toBe("sync-lipsync-v3:300s")
+    expect(buildLipSyncCreditId("sync-lipsync-v3", undefined)).toBe("sync-lipsync-v3:300s")
+  })
+
+  it("emits composite IDs for the Volcengine dubbing model", () => {
+    expect(buildLipSyncCreditId("volcengine-lipsync", 12)).toBe("volcengine-lipsync:15s")
+    expect(buildLipSyncCreditId("volcengine-lipsync", 45)).toBe("volcengine-lipsync:60s")
+    expect(buildLipSyncCreditId("volcengine-lipsync", 200)).toBe("volcengine-lipsync:300s")
+    expect(buildLipSyncCreditId("volcengine-lipsync", undefined)).toBe("volcengine-lipsync:300s")
+  })
+
+  it("returns the bare provider for non-per-second models", () => {
+    expect(buildLipSyncCreditId("infinitalk", 10)).toBe("infinitalk")
+    expect(buildLipSyncCreditId("latentsync", undefined)).toBe("latentsync")
+  })
+})
+
+describe("omnihuman-1-5 (per-second, 60s cap)", () => {
+  it("is per-second and capped at 60s", () => {
+    expect(isPerSecondLipSyncProvider("omnihuman-1-5")).toBe(true)
+    expect(getLipSyncMaxAudioSeconds("omnihuman-1-5")).toBe(60)
+  })
+  it("buckets to 15/30/60 and clamps anything longer (and missing) to 60", () => {
+    expect(buildLipSyncCreditId("omnihuman-1-5", 8)).toBe("omnihuman-1-5:15s")
+    expect(buildLipSyncCreditId("omnihuman-1-5", 25)).toBe("omnihuman-1-5:30s")
+    expect(buildLipSyncCreditId("omnihuman-1-5", 59)).toBe("omnihuman-1-5:60s")
+    expect(buildLipSyncCreditId("omnihuman-1-5", 999)).toBe("omnihuman-1-5:60s")
+    expect(buildLipSyncCreditId("omnihuman-1-5", undefined)).toBe("omnihuman-1-5:60s")
+  })
+})

package/src/__tests__/list-merge.test.ts

@@ -0,0 +1,96 @@
+import { zipMergeLists } from "../list-merge.js"
+
+describe("zipMergeLists", () => {
+  it("merges two equal-length object lists element-wise", () => {
+    const result = zipMergeLists([
+      [JSON.stringify({ a: 1 }), JSON.stringify({ a: 2 })],
+      [JSON.stringify({ b: 10 }), JSON.stringify({ b: 20 })],
+    ])
+    expect(result).toEqual([
+      JSON.stringify({ a: 1, b: 10 }),
+      JSON.stringify({ a: 2, b: 20 }),
+    ])
+  })
+
+  it("cycles a single-item list over a longer list (the user's scenario)", () => {
+    const result = zipMergeLists([
+      [
+        JSON.stringify({ name: "a" }),
+        JSON.stringify({ name: "b" }),
+        JSON.stringify({ name: "c" }),
+      ],
+      [JSON.stringify({ grade: 23 })],
+    ])
+    expect(result).toEqual([
+      JSON.stringify({ name: "a", grade: 23 }),
+      JSON.stringify({ name: "b", grade: 23 }),
+      JSON.stringify({ name: "c", grade: 23 }),
+    ])
+  })
+
+  it("cycles the longer side the other way too (1 x 3)", () => {
+    const result = zipMergeLists([
+      [JSON.stringify({ grade: 23 })],
+      [
+        JSON.stringify({ name: "a" }),
+        JSON.stringify({ name: "b" }),
+        JSON.stringify({ name: "c" }),
+      ],
+    ])
+    expect(result).toEqual([
+      JSON.stringify({ grade: 23, name: "a" }),
+      JSON.stringify({ grade: 23, name: "b" }),
+      JSON.stringify({ grade: 23, name: "c" }),
+    ])
+  })
+
+  it("wraps with modulo on mismatched non-factor lengths (3 x 2)", () => {
+    const result = zipMergeLists([
+      [
+        JSON.stringify({ x: 1 }),
+        JSON.stringify({ x: 2 }),
+        JSON.stringify({ x: 3 }),
+      ],
+      [JSON.stringify({ y: "a" }), JSON.stringify({ y: "b" })],
+    ])
+    expect(result).toEqual([
+      JSON.stringify({ x: 1, y: "a" }),
+      JSON.stringify({ x: 2, y: "b" }),
+      JSON.stringify({ x: 3, y: "a" }),
+    ])
+  })
+
+  it("later source overrides earlier on key conflicts", () => {
+    const result = zipMergeLists([
+      [JSON.stringify({ a: 1, b: 1 })],
+      [JSON.stringify({ b: 2 })],
+    ])
+    expect(result).toEqual([JSON.stringify({ a: 1, b: 2 })])
+  })
+
+  it("concatenates non-object items as strings when no side is an object", () => {
+    const result = zipMergeLists([
+      ["hello ", "hi "],
+      ["world", "there"],
+    ])
+    expect(result).toEqual(["hello world", "hi there"])
+  })
+
+  it("spreads object side and ignores non-object side for object keys", () => {
+    const result = zipMergeLists([
+      [JSON.stringify({ a: 1 })],
+      ["raw string"],
+    ])
+    expect(result).toEqual([JSON.stringify({ a: 1 })])
+  })
+
+  it("ignores empty lists but keeps single-non-empty as passthrough", () => {
+    const result = zipMergeLists([[], [JSON.stringify({ a: 1 }), JSON.stringify({ a: 2 })]])
+    expect(result).toEqual([JSON.stringify({ a: 1 }), JSON.stringify({ a: 2 })])
+  })
+
+  it("returns empty when all inputs are empty", () => {
+    expect(zipMergeLists([])).toEqual([])
+    expect(zipMergeLists([[], []])).toEqual([])
+  })
+})