@vortex-rdf/vortex-rdf-store 0.3.0 → 0.5.0

package/README.md

@@ -212,6 +212,45 @@ npm test
 
 There's no separate Node-targeted wasm build to maintain.
 
+Types are checked separately from the build, since `wasm-pack` doesn't run `tsc`:
+
+```bash
+npm run typecheck   # tests and benchmarks, both against the published API
+```
+
+## Benchmarks
+
+Three surfaces, kept separate because they answer different questions and are trustworthy in different ways. All require `npm run build` first.
+
+| Command | Question | Output |
+| --- | --- | --- |
+| `npm run bench` | How do we compare to other JS RDF stores? | `bench/results.json`, rendered to the dashboard |
+| `npm run bench:codspeed` | Did this PR regress anything? | uploaded to CodSpeed |
+| `npm run bench:dict-memory` | Where is wasm memory actually going? | printed; `bench/dict-memory.json` |
+
+**`npm run bench`** runs each store — the Vortex build variants, [rdf-stores.js](https://github.com/rubensworks/rdf-stores.js), and [oxigraph](https://github.com/oxigraph/oxigraph) — through the same query, mutation, and serialization workload, one adapter per child process so peak RSS is attributable and no store's garbage taints another's timings. It is wall-clock, so it is only as stable as the machine it runs on; it is deliberately **not** uploaded to CodSpeed. `scripts/render_bench_dashboard.py` turns its `results.json` plus a `cargo bench --bench benchmark` run into `public/index.html`.
+
+The dataset is generated by `genDataset` in [bench/shared.ts](bench/shared.ts), with term cardinality as an explicit knob — real RDF has terms scaling with rows, and a generator that draws millions of quads from a handful of IRIs makes every store's term handling invisible. Tunable by env var:
+
+| Var | Default | Meaning |
+| --- | --- | --- |
+| `BENCH_DIM` | 128 | triples dataset is `D³` rows |
+| `BENCH_DIM_QUADS` | 32 | quads dataset is `Dq⁴` rows |
+| `BENCH_SUBJ_RATIO` | 0.1 | distinct subjects / rows — the reciprocal of triples per subject |
+| `BENCH_OBJ_RATIO` | 0.5 | distinct objects / rows |
+| `BENCH_PREDICATES` | 32 | distinct predicates (a closed vocabulary) |
+| `BENCH_GRAPHS` | 1 | distinct named graphs; 1 means default graph only |
+| `BENCH_LITERAL_FRAC` | 0.4 | fraction of objects that are literals |
+| `MUT_BATCH` | 10000 | quads per add/delete batch |
+
+The two ratios decide how much of the dataset is *terms*: the dictionary holds `subjectRatio + objectRatio` of them per quad. At the defaults that is 2,097,152 triples over ~1.26M distinct terms, ten triples describing each subject, and probes spanning five orders of magnitude of selectivity (1 row for a fully-bound pattern, ~10 for a subject, ~3% for a predicate).
+
+`BENCH_SUBJ_RATIO=1.0` gives every row its own subject, which puts more distinct terms in the dictionary than there are rows. That is a useful dictionary-stress configuration — it is what `bench:dict-memory` asks for — but a poor default for the comparison: it makes five of the seven probes match two rows or fewer, so the timings become almost entirely query setup with the decode path barely exercised.
+
+Each adapter process peaks at 3–6 GB — check available memory before running, because a swapping run produces numbers that look like regressions.
+
+**`npm run bench:dict-memory`** is the only instrument that can attribute wasm memory; `peakRssMb` in the comparative run is the right cross-library number but cannot say *what* holds the memory. Wasm linear memory never shrinks, so it works by differentials — several stores held live at once, memory read after each, slope against store count — and every config runs in its own process. It defaults to a single config as a regression check against the figures recorded when FSST landed; passing several `DICT_MEM_RATIOS` sweeps term cardinality instead and fits the per-term cost. The header of [bench/dict-memory.bench.ts](bench/dict-memory.bench.ts) documents the method and the invocations.
+
 ## License
 
 MIT

package/package.json

@@ -1,8 +1,13 @@
 {
     "name": "@vortex-rdf/vortex-rdf-store",
-    "version": "0.3.0",
+    "version": "0.5.0",
     "description": "High-performance, zero-copy columnar RDF serialization format",
     "type": "module",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/vortex-rdf/vortex-rdf.git",
+        "directory": "js"
+    },
     "publishConfig": {
         "access": "public"
     },
@@ -35,9 +40,11 @@
         "build:fast": "npm run build:wasm:fast && npm run build:clean-manifest",
         "prepublishOnly": "npm run build",
         "test": "vitest run",
+        "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.bench.json",
         "bench": "tsx --expose-gc --max-old-space-size=8192 bench/compare.bench.ts",
         "bench:build": "npm run build && npm run bench",
-        "bench:codspeed": "tsx --expose-gc bench/codspeed.bench.ts"
+        "bench:codspeed": "tsx --expose-gc bench/codspeed.bench.ts",
+        "bench:dict-memory": "tsx --expose-gc bench/dict-memory.bench.ts"
     },
     "keywords": [
         "rdf",