@cratestack/cbor 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephane Segning
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @cratestack/cbor
+
+A thin umbrella package that auto-selects the right CBOR backend for
+CrateStack's generated TypeScript RPC clients: `@cratestack/cbor-node`
+(#286, native N-API) in Node, `@cratestack/cbor-web` (#287, WASM) in the
+browser — one `npm install`, one import path, the environment picks the
+implementation. The final piece of [epic #285](https://github.com/cratestack/cratestack/issues/285).
+
+```sh
+npm install @cratestack/cbor
+```
+
+```ts
+import { createCborCodec } from "@cratestack/cbor";
+
+const codec = await createCborCodec();
+
+const bytes = codec.encode({ hello: "world" });
+const value = codec.decode(bytes);
+```
+
+Node projects never download the WASM binary; browser bundles never pull
+in native `.node` files — each platform's `dependencies` (`@cratestack/cbor-node`
+or `@cratestack/cbor-web`) is only actually loaded once the matching
+`exports` condition resolves.
+
+## How auto-selection works
+
+This package's `package.json` declares conditional
+[`exports`](https://nodejs.org/api/packages.html#conditional-exports) for
+its `"."` entry:
+
+```json
+{
+  "exports": {
+    ".": {
+      "node": { "types": "./dist/node.d.ts", "import": "./dist/node.js" },
+      "browser": { "types": "./dist/web.d.ts", "import": "./dist/web.js" },
+      "default": { "types": "./dist/web.d.ts", "import": "./dist/web.js" }
+    }
+  }
+}
+```
+
+- Node's own module resolver (and any bundler/test runner that sets the
+  `"node"` condition — e.g. Vitest's default `environment: "node"`,
+  webpack's `target: "node"`) picks `dist/node.js`, which re-exports
+  `@cratestack/cbor-node`.
+- A browser-targeting bundler (Vite's client build, webpack's default `web`
+  target, Next.js client bundles) sets the `"browser"` condition and picks
+  `dist/web.js`, which re-exports `@cratestack/cbor-web`.
+- `"default"` is the fallback for resolvers that set neither condition — it
+  points at the WASM build (`dist/web.js`), the more broadly portable of
+  the two: it only needs `fetch`/`URL`/`WebAssembly`, all present in every
+  modern JS runtime (Node, browsers, edge/worker runtimes), whereas the
+  Node build depends on a native `.node` binary that plainly cannot load
+  outside Node. The same reasoning is why the package-level `"main"`/`"types"`
+  fields (read by tooling that ignores `exports` entirely) also point at
+  the WASM build.
+
+## Escape hatch: explicit subpaths
+
+Conditional `exports` resolution isn't perfectly consistent across every
+bundler/SSR setup — some SSR frameworks resolve the `"node"` condition even
+for a module that will also ship to the client (their SSR build sets
+`"node"` because the code *runs* under Node during the server render, even
+though the same module graph gets bundled for the browser too). When
+automatic resolution doesn't do what you need, import the platform build
+directly:
+
+```ts
+// Force the native Node build, regardless of which condition the
+// resolver would otherwise pick:
+import { createCborCodec } from "@cratestack/cbor/node";
+
+// Force the WASM build — e.g. from an SSR entry point whose bundler
+// resolves "node" but whose output actually needs to run in the browser:
+import { createCborCodec } from "@cratestack/cbor/web";
+```
+
+Both subpaths export the exact same `createCborCodec()` shape as the root
+entry point — they're what the root entry point's `"node"`/`"browser"`
+conditions point at internally, just addressable directly.
+
+## Sync vs. async: one uniform API
+
+`@cratestack/cbor-node`'s own export (`cborCodec`) is a plain synchronous
+object — native N-API modules load synchronously via Node's
+`require`/ESM interop, so there's no async step to wait on.
+`@cratestack/cbor-web`'s own export is necessarily async
+(`createCborCodec(): Promise<CratestackRpcCodec>`) — one-time WASM
+instantiation has no synchronous equivalent in a browser.
+
+This package normalizes **both** platforms to the same async-factory
+shape: `createCborCodec()` everywhere, always returning a `Promise`. On
+Node that Promise resolves immediately (the underlying codec is already
+loaded and synchronous by the time the module's `import` completes) — it's
+strictly unnecessary async ceremony for that platform alone, but it buys a
+single, genuinely platform-agnostic call site. `await createCborCodec()`
+behaves identically no matter which condition resolved; nothing in
+consuming code needs to branch on environment. Once resolved, every
+`encode`/`decode` call is synchronous on both platforms — the async cost,
+real or nominal, is paid exactly once.
+
+The alternative — exposing the platform difference directly (a sync export
+on Node, an async factory in the browser) and documenting it — was
+considered and rejected: it would force every consumer of this umbrella
+package to either branch on environment or always `await` a value that's
+sometimes a real async boundary and sometimes not, which defeats the
+purpose of an umbrella package that's supposed to hide exactly that kind
+of platform difference.
+
+## Error handling
+
+Malformed CBOR input on `decode`, or a value `encode` can't represent,
+throws a catchable JS `Error` on both platforms — see
+`@cratestack/cbor-node`'s and `@cratestack/cbor-web`'s own READMEs for the
+platform-specific mechanism (native panic-to-exception conversion vs. a
+non-poisoning WASM trap boundary).
+
+## Null handling
+
+Both backends translate every JSON `null` (top-level or nested) to the
+real CBOR null byte (`0xf6`), matching `cratestack-codec-cbor`'s own
+`Option::None` encoding — not the empty-array quirk (`0x80`) some CBOR
+backends produce for a bare unit type. See either platform package's
+README for detail.
+
+## Contributing to this package (monorepo-local dev)
+
+This package's own build (`tsc`) is pure TypeScript — it never needs a Rust
+or wasm toolchain. But its `dependencies` are `@cratestack/cbor-node` and
+`@cratestack/cbor-web`, which do. Within this monorepo, this package's
+turbo `build` task deliberately does **not** build those two siblings
+automatically (see `turbo.json`'s `@cratestack/cbor#build` override) — a
+default dependency edge would force every toolchain-free environment
+(including this repo's own `js` CI job) to compile native/wasm code just
+to typecheck a thin re-export wrapper.
+
+Practical effect: `pnpm turbo run build test lint --filter='./packages/cratestack-cbor'`
+type-checks cleanly and passes lint anywhere, but its Node round-trip
+tests (`tests/node.test.ts`) only run for real if `@cratestack/cbor-node`
+is *already* built — otherwise they skip (not fail) with a console
+warning. For real coverage while developing, build the sibling first:
+
+```sh
+pnpm turbo run build --filter='./packages/cratestack-cbor-node'
+pnpm turbo run build test lint --filter='./packages/cratestack-cbor'
+```
+
+Or just run the full unfiltered `pnpm turbo run build test lint` at the
+repo root — that builds every package as its own top-level target
+regardless of this edge, so the siblings are present and the tests run
+for real.
+
+## See Also
+
+- `@cratestack/cbor-node` — the Node/native implementation (napi-rs).
+- `@cratestack/cbor-web` — the browser/WASM implementation (wasm-bindgen).
+- `crates/cratestack-codec-cbor` — the underlying, unchanged Rust codec
+  both implementations wrap.
+
+## License
+
+MIT

package/dist/node.d.ts

@@ -0,0 +1,10 @@
+import type { CratestackRpcCodec } from "@cratestack/ts-types";
+/**
+ * Resolves immediately (no real async work — `@cratestack/cbor-node`'s
+ * underlying native codec is already loaded and synchronous by the time
+ * this module's `import` completes) to a {@link CratestackRpcCodec} backed
+ * by the native N-API CBOR codec. Async purely for call-site parity with
+ * the browser build's `createCborCodec()`, not because Node needs it.
+ */
+export declare function createCborCodec(): Promise<CratestackRpcCodec>;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAEnE"}

package/dist/node.js

@@ -0,0 +1,35 @@
+// Node entry point (resolved by the `"node"` condition of this package's
+// root `exports["."]`, and directly importable as the `@cratestack/cbor/node`
+// escape hatch — see package.json and README.md).
+//
+// @cratestack/cbor-node's own export (`cborCodec`, see its src/index.ts) is
+// a plain synchronous object: native N-API modules load synchronously via
+// Node's `require`/ESM interop, so there's no async initialization step to
+// wait on. @cratestack/cbor-web's export, by contrast, is necessarily async
+// (`createCborCodec()`) — one-time WASM instantiation has no synchronous
+// equivalent in a browser.
+//
+// This package normalizes both platforms to the SAME public shape: an async
+// `createCborCodec()` factory everywhere. On this (Node) side that means
+// wrapping an already-available synchronous value in a resolved Promise —
+// strictly unnecessary work for this platform alone, but it buys a single,
+// genuinely platform-agnostic call site (`await createCborCodec()` behaves
+// identically regardless of which condition resolved). The alternative —
+// exposing the sync/async difference directly and documenting it — would
+// force every consumer of this umbrella package to branch on environment
+// (or always `await` a value that's sometimes already resolved and
+// sometimes a real async boundary), which defeats the point of an umbrella
+// package in the first place. See README.md's "Sync vs. async" section and
+// issue #288 for the full reasoning.
+import { cborCodec } from "@cratestack/cbor-node";
+/**
+ * Resolves immediately (no real async work — `@cratestack/cbor-node`'s
+ * underlying native codec is already loaded and synchronous by the time
+ * this module's `import` completes) to a {@link CratestackRpcCodec} backed
+ * by the native N-API CBOR codec. Async purely for call-site parity with
+ * the browser build's `createCborCodec()`, not because Node needs it.
+ */
+export async function createCborCodec() {
+    return cborCodec;
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,8EAA8E;AAC9E,kDAAkD;AAClD,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,2EAA2E;AAC3E,4EAA4E;AAC5E,yEAAyE;AACzE,2BAA2B;AAC3B,EAAE;AACF,4EAA4E;AAC5E,yEAAyE;AACzE,0EAA0E;AAC1E,2EAA2E;AAC3E,2EAA2E;AAC3E,yEAAyE;AACzE,yEAAyE;AACzE,yEAAyE;AACzE,mEAAmE;AACnE,2EAA2E;AAC3E,2EAA2E;AAC3E,qCAAqC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/web.d.ts

@@ -0,0 +1,2 @@
+export { createCborCodec } from "@cratestack/cbor-web";
+//# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/web.js

@@ -0,0 +1,15 @@
+// Browser entry point (resolved by the `"browser"` and `"default"`
+// conditions of this package's root `exports["."]`, and directly
+// importable as the `@cratestack/cbor/web` escape hatch — see
+// package.json and README.md).
+//
+// @cratestack/cbor-web's own `createCborCodec()` (see its src/index.ts) is
+// already the uniform async-factory shape this umbrella package
+// standardizes on for both platforms — see src/node.ts's doc comment for
+// why. Nothing to adapt here: this file exists so the escape-hatch subpath
+// (`@cratestack/cbor/web`) and the root `"browser"`/`"default"` conditions
+// have their own dedicated compiled entry point, distinct from
+// src/node.ts, rather than sharing one file whose behavior would need to
+// branch at runtime.
+export { createCborCodec } from "@cratestack/cbor-web";
+//# sourceMappingURL=web.js.map

package/dist/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,iEAAiE;AACjE,8DAA8D;AAC9D,+BAA+B;AAC/B,EAAE;AACF,2EAA2E;AAC3E,gEAAgE;AAChE,yEAAyE;AACzE,2EAA2E;AAC3E,2EAA2E;AAC3E,+DAA+D;AAC/D,yEAAyE;AACzE,qBAAqB;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@cratestack/cbor",
+  "version": "0.5.2",
+  "description": "Umbrella CBOR codec for CrateStack's generated TypeScript RPC clients: conditional exports auto-select @cratestack/cbor-node in Node and @cratestack/cbor-web in the browser behind one import path, one uniform async createCborCodec() API on both platforms.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cratestack/cratestack.git",
+    "directory": "packages/cratestack-cbor"
+  },
+  "homepage": "https://cratestack.dev",
+  "bugs": "https://github.com/cratestack/cratestack/issues",
+  "keywords": ["cratestack", "cstack", "cbor", "codec", "rpc", "isomorphic"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/web.js",
+  "types": "./dist/web.d.ts",
+  "exports": {
+    ".": {
+      "node": {
+        "types": "./dist/node.d.ts",
+        "import": "./dist/node.js"
+      },
+      "browser": {
+        "types": "./dist/web.d.ts",
+        "import": "./dist/web.js"
+      },
+      "default": {
+        "types": "./dist/web.d.ts",
+        "import": "./dist/web.js"
+      }
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "biome check ."
+  },
+  "dependencies": {
+    "@cratestack/cbor-node": "0.5.2",
+    "@cratestack/cbor-web": "0.5.2",
+    "@cratestack/ts-types": "0.5.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}