dual ESM and CJS, with types first in every export condition

.github/workflows/ci.yml

@@ -37,6 +37,26 @@ jobs:
       # are JavaScript, and the job below is what runs them.
       - run: cargo clippy --all-features -- -D warnings
 
+  # The package as a resolver sees it, which no amount of running it
+  # here can answer: the tests import the checkout, where every path
+  # exists and every condition is beside the last. What breaks a
+  # published package is the resolution instead, and only tsc and attw
+  # read a package that way.
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - uses: Swatinem/rust-cache@v2
+      - run: npm ci
+      # The declarations are generated by the build, so there is nothing
+      # to type-check until it has run.
+      - run: npm run build:debug
+      - run: npm run check:types
+      - run: npm run check:package
+
   test:
     strategy:
       fail-fast: false

.github/workflows/release.yml

@@ -131,13 +131,18 @@ jobs:
         with:
           key: ${{ matrix.target }}
 
+      # napi rather than npm run build, because only this workflow builds
+      # for a target that is not the machine's own. The two file names
+      # are the ones package.json ships, and a build that leaves them
+      # under napi's defaults is a published package whose loader is not
+      # the loader that was built.
       - name: Build
         if: matrix.alpine == ''
         shell: bash
         run: |
           set -eu
           npm ci
-          npx napi build --platform --release --target ${{ matrix.target }}
+          npx napi build --platform --release --target ${{ matrix.target }} --js binding.cjs --dts binding.d.cts
 
       # Alpine builds the row's own architecture natively, so there is
       # no target flag: inside the image the default target is the musl
@@ -166,7 +171,7 @@ jobs:
               rustup-init -y --no-modify-path --profile minimal
               export PATH="$HOME/.cargo/bin:$PATH"
               npm ci
-              npx napi build --platform --release
+              npx napi build --platform --release --js binding.cjs --dts binding.d.cts
             '
 
       # One file, named after the platform it runs on, which is what the

README.md

@@ -30,12 +30,12 @@ The rows are an array, so iterating them is `for (const row of rows)` and nothin
 - **INT64 is `bigint`.** Always, by default. A JavaScript number stops being exact at 2^53 and zu's integers go to 2^63, so a count that came back as a number would be a count you cannot trust. `{ bigIntMode: "number" }` is planned, will be documented with its precision hazard, and will never be the default.
 - **Nothing blocks the event loop.** Every native call runs on libuv's threadpool and hands back a promise before the statement has started. There is no synchronous variant, and the ones that arrive later will say in their own documentation that they belong in scripts, not servers.
 - **`await using` is the intended scoping.** A connection is `Symbol.asyncDispose`, and `close()` stays public for callers who cannot use the syntax.
-- **A failure is an ordinary `Error`.** Every `catch`, logger and rejection handler already knows what to do with one. What makes it a zu error is the fields, and none of them has to be parsed back out of the message: `code` is the GQLSTATUS and picks the branch, `condition` is the standard's own words for it, `line` and `column` and `excerpt` underline the token, and `retryable` decides whether a retry loop goes round again. A mistake this client caught before the engine saw it carries no `code` and is named `ZuUsageError`, so a caller mapping codes to branches can tell a missing code from one it does not recognize.
+- **A failure is an ordinary `Error`.** Every `catch`, logger and rejection handler already knows what to do with one. What makes it a zu error is the fields, and none of them has to be parsed back out of the message: `code` is the GQLSTATUS and picks the branch, `condition` is the standard's own words for it, `line` and `column` and `excerpt` underline the token, and `retryable` decides whether a retry loop goes round again. A mistake this client caught before the engine saw it carries no `code` and is named `ZuUsageError`, so a caller mapping codes to branches can tell a missing code from one it does not recognize. `isZuError(caught)` is the exported guard for the `catch` clause, where the value is `unknown` and could be anything at all, and in TypeScript it narrows to the full shape.
 - **A refusal is a rejection.** A closed connection and a parameter of a type nothing can bind are refused inside the promise rather than thrown out of the call, so one `await` catches everything one statement can do.
 
 ## What works today
 
-`connect`, `query`, `exec`, `close`, `dispose` and `await using`. Named parameters both ways, including lists, records and nesting. Every scalar the engine has, plus nodes, edges and paths with their tables named rather than numbered, and `ZuDate`, `ZuTime`, `ZuTimestamp` and `ZuDuration`. Read-only connections, memory and thread limits. An `AbortSignal` on any statement. The full error surface above.
+`connect`, `query`, `exec`, `close`, `dispose` and `await using`. Named parameters both ways, including lists, records and nesting. Every scalar the engine has, plus nodes, edges and paths with their tables named rather than numbered, and `ZuDate`, `ZuTime`, `ZuTimestamp` and `ZuDuration`. Read-only connections, memory and thread limits. An `AbortSignal` on any statement. The full error surface above, and `isZuError` to recognize it. Both module formats, typed separately.
 
 Build it with `npm run build`, and run the suite with `npm test`. Nothing is published yet, so `npm i zudb` is not a thing you can type at anybody's terminal, but everything it will do is built and installed on every run of the release workflow.
 
@@ -51,6 +51,17 @@ It is the signal JavaScript already has, so a timeout written like the one above
 
 What the promise rejects with is the signal's own reason, which is what `fetch` does: `AbortSignal.timeout(50)` rejects with the runtime's `TimeoutError`, `controller.abort(new RequestGone())` rejects with the `RequestGone` you made, and a bare `controller.abort()` rejects with the runtime's `AbortError`. A signal that has already fired stops the statement before the engine sees it at all. A signal that never fires costs one listener, taken off again when the statement ends, whether it answered, failed or was stopped.
 
+## Importing it, either way
+
+```ts
+import { connect } from "zudb";      // ESM, and TypeScript resolving through the import condition
+const { connect } = require("zudb"); // CommonJS, the same names and the same objects
+```
+
+Both formats reach one loaded addon, so a `ZuDate` made through `import` is an instance of the `ZuDate` reached through `require`, and a program that mixes the two, which is most programs with a dependency tree, is not quietly holding two of everything. There is no default export in either format, because a default alongside the named exports is a second spelling of every name whose meaning depends on the caller's bundler and their `esModuleInterop`.
+
+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.
+
 ## 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.
@@ -72,7 +83,7 @@ Anything outside that table has no binary and no source build to fall back on, s
 
 ## Still to come
 
-`AsyncIterable` and Web Streams over a result. `bigIntMode`. `toTemporal()` and `{ temporal: true }`, for the runtimes where Temporal is unflagged: it reached Stage 4 in March 2026 and is unflagged in Node 26, but Node 24 is still the active LTS and Safari is still behind a flag, which is why the stable types are the four classes above. Dual ESM and CJS, with types first in every export condition. Bun and Deno in CI, and the WASM build for the browser.
+`AsyncIterable` and Web Streams over a result. `bigIntMode`. `toTemporal()` and `{ temporal: true }`, for the runtimes where Temporal is unflagged: it reached Stage 4 in March 2026 and is unflagged in Node 26, but Node 24 is still the active LTS and Safari is still behind a flag, which is why the stable types are the four classes above. Bun and Deno in CI, and the WASM build for the browser.
 
 ## Runtimes
 

bench/query.mjs

@@ -17,7 +17,7 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
-import { connect } from '../index.js'
+import { connect } from 'zudb'
 
 const ROWS = Number(process.env.ZU_BENCH_ROWS ?? 50_000)
 const REPEATS = Number(process.env.ZU_BENCH_REPEATS ?? 9)