Background
x-key: '$self' declares set semantics on an array — the item itself is its identity. It currently only works on primitive items (strings, numbers, booleans, null), because JS's native Set/Map use value equality for primitives and reference equality for everything else.
new Set([1, 1]).size // 1
new Set([{a:1}, {a:1}]).size // 2 — different referencesSo $self on an array of objects would produce nonsense diffs today, and the diff path throws (or should throw) when it encounters non-primitive items.
What this issue tracks
Lifting that restriction so $self works on any JSON value — primitives, objects, nested arrays. The natural use case is "a set of structurally-identical small records where no field is a natural key" (e.g. [lat, lng] pairs treated as a set of locations).
Options considered
Two approaches both require walking each item's structure once, because JS doesn't expose structural equality natively:
1. Canonical-JSON normalization as identity. Stringify items with sorted keys, recursively. Use the string as a Set/Map key. No collisions by construction; memory cost is O(size) per item.
2. Deep-equality linear scan. No intermediate representation. For each item in a, check if any item in b deep-equals it. O(N·M·size) but short-circuits on first mismatch and allocates nothing extra.
For the array sizes where $self realistically applies (tags, permissions, small sets), either is fine. Deep-equality is probably simpler; canonical-JSON wins for larger N+M.
Why we're not doing it now
- The overwhelming majority of "set of objects" use cases have a natural ID field, in which case
x-key: '<field>' is the right tool and already works.
- Extending
$self to objects adds structural-equality machinery (canonicalizer or deep-equal) that has to be maintained, with edge cases around number representation, key ordering, and any future widening of JsonValue (e.g. NaN, undefined).
- The clean two-tool design —
x-key: '<field>' for stable identity, $self for primitive sets — covers ~all real schemas without overlap.
When to revisit
- A real schema lands where
$self on objects would be meaningfully cleaner than adding an id field to the data.
- Or: TC39 Records & Tuples ships, at which point
new Set(records) Just Works with value equality and the whole extension becomes free.
Acceptance criteria (if/when implemented)
x-key: '$self' no longer throws on object items.- Diffing
[{a:1}, {a:2}] → [{a:1}, {a:3}] emits one remove + one add (not nested replace).
- Duplicate-collapse and reorder-invisibility behaviors of
$self are preserved (set semantics).
- Implementation choice (canonicalize vs deep-equal) documented in code with a comment explaining the trade-off.
Background
x-key: '$self'declares set semantics on an array — the item itself is its identity. It currently only works on primitive items (strings, numbers, booleans, null), because JS's nativeSet/Mapuse value equality for primitives and reference equality for everything else.So
$selfon an array of objects would produce nonsense diffs today, and the diff path throws (or should throw) when it encounters non-primitive items.What this issue tracks
Lifting that restriction so
$selfworks on any JSON value — primitives, objects, nested arrays. The natural use case is "a set of structurally-identical small records where no field is a natural key" (e.g.[lat, lng]pairs treated as a set of locations).Options considered
Two approaches both require walking each item's structure once, because JS doesn't expose structural equality natively:
1. Canonical-JSON normalization as identity. Stringify items with sorted keys, recursively. Use the string as a
Set/Mapkey. No collisions by construction; memory cost is O(size) per item.2. Deep-equality linear scan. No intermediate representation. For each item in
a, check if any item inbdeep-equals it. O(N·M·size) but short-circuits on first mismatch and allocates nothing extra.For the array sizes where
$selfrealistically applies (tags, permissions, small sets), either is fine. Deep-equality is probably simpler; canonical-JSON wins for larger N+M.Why we're not doing it now
x-key: '<field>'is the right tool and already works.$selfto objects adds structural-equality machinery (canonicalizer or deep-equal) that has to be maintained, with edge cases around number representation, key ordering, and any future widening ofJsonValue(e.g.NaN,undefined).x-key: '<field>'for stable identity,$selffor primitive sets — covers ~all real schemas without overlap.When to revisit
$selfon objects would be meaningfully cleaner than adding an id field to the data.new Set(records)Just Works with value equality and the whole extension becomes free.Acceptance criteria (if/when implemented)
x-key: '$self'no longer throws on object items.[{a:1}, {a:2}]→[{a:1}, {a:3}]emits one remove + one add (not nested replace).$selfare preserved (set semantics).