Generate the API reference from the declarations that ship

.github/workflows/release.yml

@@ -32,6 +32,7 @@ on:
       - .github/workflows/release.yml
       - package.json
       - npm/**
+      - tools/reference.mjs
       - Cargo.toml
       - Cargo.lock
       - rust-toolchain.toml
@@ -218,6 +219,36 @@ jobs:
           path: npm/
           if-no-files-found: error
 
+  # The reference, generated from the declarations this release
+  # publishes. It is a job here rather than only a test in CI because a
+  # reference is something a release hands over, and the version it is
+  # about is the version being released.
+  #
+  # It needs a binary for the machine it runs on, because the last thing
+  # the tool does is require the package and hold the names it exports
+  # against the names it documented. That check is the point: the
+  # declarations and the addon are generated from one Rust crate and
+  # published as two files, and the failure worth catching is the one
+  # where they stop agreeing.
+  reference:
+    needs: binary
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - run: npm ci
+      - uses: actions/download-artifact@v4
+        with:
+          name: binary-x86_64-unknown-linux-gnu
+      - run: npm run reference
+      - uses: actions/upload-artifact@v4
+        with:
+          name: reference
+          path: reference/
+          if-no-files-found: error
+
   # Publishing is the one step that cannot be taken back, so it happens
   # on a tag and nowhere else. The platform packages go first: the root
   # package is what a user installs, and it is worthless until every

.gitignore

@@ -7,6 +7,11 @@ dist/
 # compared against the one in etc/ that is committed.
 temp/
 
+# The generated API reference. Built from the declarations rather than
+# kept beside them, so a copy in the tree is a copy that is out of date
+# the moment a signature moves.
+reference/
+
 # The built addon, which napi drops into the source tree so that the
 # tests load the same file a published package would.
 *.node

README.md

@@ -146,6 +146,12 @@ Both formats reach one loaded addon, so a `ZuDate` made through `import` is an i
 
 The declarations are separate files rather than one shared `.d.ts`, since a resolver reads `.d.cts` for `require` and `.d.mts` for `import`, and `types` is the first condition in each entry: conditions match in the order they are written, so `types` after `default` is a `types` nothing reaches, and a package that compiles here would be `any` everywhere else. `npm run check:types` compiles a program in each format against the published shape, and `npm run check:package` runs [`attw`](https://github.com/arethetypeswrong/arethetypeswrong.github.io) over a real `npm pack` for node10, node16 CJS, node16 ESM and bundler resolution.
 
+## Reference
+
+Every exported name, its signature and what its doc comment says, generated from the declarations this package publishes rather than written by hand beside them. The release builds it from the version it is about to publish, and `npm run reference` builds the same pages here.
+
+typedoc rather than api-documenter, which would have been the obvious pick since api-extractor already runs here for the stability report. api-extractor's doc model does not carry `conn.stream(...)` or `await using`, because both reach the type of a connection through the `declare module` in `zudb.d.cts` and it does not follow one. A reference missing the streaming entry point is a reference that sends a reader to the cursor. So the generator that reads the declarations with the TypeScript compiler is the one used, and the build fails if it stops carrying them, along with any exported name whose types have gone missing.
+
 ## Installing, once there is something to install
 
 `npm i zudb`, and that is the whole of it. The install downloads one file, runs nothing, and needs no compiler: the root package carries the loader and no binary, each platform has its own package holding exactly one addon, and npm picks the one for the machine out of `optionalDependencies` by its `os`, `cpu` and `libc`. There is no `postinstall`, no `node-gyp`, no `node-pre-gyp` and no fetch from anywhere but the registry, which is what makes the package installable behind a proxy, inside a locked-down CI image, and on a machine with no toolchain on it.