You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This commit was created on GitHub.com and signed with GitHub’s verified signature.
doc: register-record's example gave a name that can never match (#27)
`register-record` takes the wire name as a STRING, and its example gave the JVM
CLASS name:
(boring/register-record "my.ns.Point" map->Point)
The writer emits `namespace/Name`. `boring.data/record-type-name` is explicit
about why — a dot is ambiguous, `a.b.c.D` could split either way — and returns
the slash form on both platforms. So every registration written from that
example silently did nothing.
Silently is the point. An unregistered record decodes to an `UnknownRecord`
carrying the same name and fields and re-encodes to identical bytes, which is a
property worth having; it also means a wrongly-FORMED registration is
indistinguishable from a type nobody registered. Nothing raises, and any
`instance?` check the caller makes on the decoded value answers false — so
whatever they meant to do with that type quietly does not happen.
Found downstream: datahike registered `"datahike.migrate.cbor.SysRef"` from this
example. Its `SysRef` — which marks a ref value pointing at a system entity —
therefore never round-tripped, `resolve-sysrefs` never fired, and such a value
was imported as an opaque record instead of the target's entity id. It had been
that way for as long as the registration existed, with no symptom until someone
added a second record type and used the first as a control.
The prose above the example was stale in the same direction, still describing
the JVM class name and ClojureScript munging down to match it. That is what
`record-type-name` used to do and deliberately stopped doing ("Every lossy step
breaks a symmetry, and this one was not forced").
Fixed here:
* all four examples use `my.ns/Point` — `register-record` (clj and cljs),
`register-navigable-record`, and `nav-conformance`;
* the prose describes what `record-type-name` actually returns;
* the recommended idiom is to DERIVE the name from `record-type-name` rather
than write it out, which removes the class of mistake instead of correcting
one instance of it;
* the silent-failure mode is stated, since it is the reason a wrong name costs
so much to find.
`register-record-name-test` pins all three: the wire name is namespace/Name and
not the class name; a derived registration round-trips; and a class-name
registration silently yields an `UnknownRecord` whose re-encoded bytes are
identical.
No behaviour change and no format change — the wire has always carried the slash
form. Verified by deliberately breaking an assertion and watching the suite fail,
because a test that is never run is worse than none.
Measured: 549 tests, 28204 assertions, 0 failures.