Skip to content

feat: symmetric literal mappings — LiteralFrom.bigint and LiteralFrom.symbol - #90

Draft
jeswr wants to merge 1 commit into
rdfjs:mainfrom
jeswr:feat/literalfrom-bigint-symbol
Draft

feat: symmetric literal mappings — LiteralFrom.bigint and LiteralFrom.symbol#90
jeswr wants to merge 1 commit into
rdfjs:mainfrom
jeswr:feat/literalfrom-bigint-symbol

Conversation

@jeswr

@jeswr jeswr commented Jul 6, 2026

Copy link
Copy Markdown
Member

Part of #7 — the smallest concrete gap there: LiteralAs.bigint and LiteralAs.symbol exist with no write-side counterparts, so bigint- and symbol-valued model properties can be read but not assigned.

What this does

Adds the two symmetric term mappings to LiteralFrom:

  • LiteralFrom.bigint(value, factory) — maps a bigint to an xsd:integer literal. Together with LiteralAs.bigint, integers beyond Number.MAX_SAFE_INTEGER now round-trip through RDF without loss of precision.
  • LiteralFrom.symbol(value, factory) — maps a symbol registered in the global symbol registry (Symbol.for) to a plain string literal via Symbol.keyFor, mirroring how LiteralAs.symbol reads literals back with Symbol.for. Unregistered symbols (plain Symbol()) carry no key that could round-trip, so they are rejected with a TypeError — the same built-in error ensure.ts uses for input validation (TermError was considered, but its constructor requires an associated RDF/JS Term, which does not exist on the write side).

Both carry the dense JSDoc treatment (@remarks, paired turtle/ts @example, @throws, @see); npx typedoc passes with no new warnings and the cross-links to LiteralAs.bigint/LiteralAs.symbol resolve.

Tests

  • Direct lexical + datatype assertions for both mappings in literalFrom.test.ts.
  • Round-trip tests through Parent model properties (hasBigint, hasSymbol) using the existing RequiredAs/RequiredFrom pattern, including a bigint above Number.MAX_SAFE_INTEGER.
  • The TypeError path for unregistered symbols is asserted (new code is fully covered, including both branches of the guard).

Scope

Deliberately limited to these two mappings to keep the diff reviewable. Further mappings discussed under #7 (xsd:duration, xsd:time, xsd:gYear, rdf:JSON, …) are left as follow-ups. This PR does not close #7 and does not overlap with #61, #73 or #74 (none of them touch the LiteralFrom write side).

Review timing: This draft was prepared with Claude; I (@jeswr) will personally review it before it progresses. I'm currently batching a lot of work in flight, so expect active review Wednesday-Friday (8-10 July).

LiteralAs.bigint and LiteralAs.symbol exist with no write-side
counterparts, so bigint- and symbol-valued model properties can be
read but not assigned. Add the symmetric term mappings:

- LiteralFrom.bigint maps a bigint to an xsd:integer literal, so
  integers beyond Number.MAX_SAFE_INTEGER round-trip losslessly.
- LiteralFrom.symbol maps a symbol registered in the global symbol
  registry (Symbol.for) to a string literal via Symbol.keyFor,
  mirroring how LiteralAs.symbol reads literals with Symbol.for.
  Unregistered symbols carry no key that could round-trip, so they
  are rejected with a TypeError (consistent with the input
  validation in ensure.ts).

Round-trip coverage via Parent model properties plus direct lexical
and datatype assertions in literalFrom.test.ts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improvement: More mappings (value and term)

1 participant