jeswr / jeswr/jsonld-fast-parse

Review + consider transferring to the rdfjs namespace

Open
#1 0 comments 0 reactions 1 assignee Claimed by @jeswr View on GitHub
Dominant language
TypeScript
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## What this is

`jsonld-fast-parse` is a specialized, **synchronous** JSON-LD → RDF/JS quad
converter for **fixed-shape, known-context** documents — primarily the
Components.js-generated component files that dominate Community Solid Server /
Comunica boot. It walks a `JSON.parse`d object once against a **pre-normalized**
context and emits RDF/JS quads directly, skipping streaming, async handler
dispatch, and per-file context re-derivation.

**Public API (one line):** `fastParse(document, normalizedContext, options?) => Quad[]`
plus a `canFastParse(text) => boolean` shape guard (and the `Converter` class,
`canonicalJson`, and `UNSUPPORTED_PATTERN` for advanced use).

## Performance evidence

Measured on the CSS boot corpus — **828** Components.js `*.jsonld` files, warmed
process, best-of-N `process.hrtime`, Node 22:

| path | best time | per file |
| --- | --- | --- |
| generic `rdf-parse` pipeline (Comunica JSON-LD → `jsonld-streaming-parser`, 8-way concurrent, prefetched doc loader) | ~6050 ms | ~7.3 ms |
| specialized `JSON.parse` + `fastParse` (contexts pre-normalized) | ~19 ms | ~23 µs |

- **~279–316× steady-state speedup** (varies with host load); ~35× including the
one-time ~155 ms normalization of all 169 distinct contexts; ~2.4× overhead
over a bare `JSON.parse` of the same files.
- **Parity is verified, not assumed:** identical quad count (34 926) and, for
**every** file, the two quad sets are **`rdf-isomorphic`** (identical modulo
blank-node labels) — the same 8 504-resource object graph.

## Correctness contract (important)

This is **NOT a general-purpose JSON-LD processor**. It implements only a
documented subset — `@id`, `@type`, `@value` (+ `@type`/`@language`/`@json`),
`@list` (`@container: @list` and inline), `@type: "@id"` coercion, compact IRIs /
prefixes, native scalars with spec-canonical lexical forms.

It explicitly does **not** support `@graph`, `@reverse`, `@index`, `@nest`,
`@included`, `@direction`, `@base`, `@vocab`, type-scoped / nested inline
contexts, framing, language maps, or non-`@list` containers, and it requires the
context to be pre-normalized. Callers **must** guard with `canFastParse(text)`
(which rejects the detectable unsupported keywords) and fall back to a
spec-compliant parser otherwise. The README leads with this contract, and the
test suite (`npm test`) reproduces the `rdf-isomorphism` oracle against
`jsonld-streaming-parser` on bundled sample `.jsonld` fixtures. `npm install`,
`npm run build` (tsc), and `npm test` all pass; runtime deps are limited to
`@rdfjs/types` + `rdf-data-factory`.

## Provenance

This repository was drafted by @jeswr's AI agent at his request, as an initial
0.1.0 packaging of a performance prototype. Nothing has been published to npm —
it is a GitHub repo only.

## Ask

@jeswr — please review the code, README, and the correctness contract / guard,
and sanity-check the benchmark methodology and the supported/unsupported subset.

Once you're happy with it, I'd like to **offer to transfer this repository to the
[`rdfjs`](https://github.com/rdfjs) organisation** so it can live alongside the
other RDF/JS tooling. You can do that yourself via **Settings → General →
Danger Zone → Transfer ownership** (transfer to `rdfjs`), or by asking an
`rdfjs` org admin to accept the transfer. Happy to adjust naming, scope, or the
API before any transfer if you'd prefer.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.