@superdurable/dex 0.1.0 → 0.1.2

package/README.md

@@ -2,7 +2,8 @@
 
 This package targets Node.js 22 and 24. It provides strongly typed workflow
 contracts and a Promise-based gRPC Client. The Client and Worker runtime use
-`@grpc/grpc-js`. The native BlobCache binding remains a separate runtime phase.
+`@grpc/grpc-js`. Blob caching uses the shared Rust DXBC implementation through
+a Node-API addon.
 
 Application values use `Codec<T>`. Flow, Step, RPC, Attribute, and Channel
 definitions retain their input and output types. Client methods return Promise
@@ -81,12 +82,13 @@ continue importing only from `@superdurable/dex`.
 - `worker.ts`: Worker gRPC service and lifecycle
 - `worker-dispatcher.ts`: typed callback dispatch and response mapping
 - `invocation-context.ts`: invocation-scoped persistence and condition state
-- `blob-cache.ts`: injectable cache contract and future N-API binding
+- `blob-cache.ts`: DXBC BlobCache contract and Node-API binding loader
 - `gen/`: checked-in protobuf and grpc-js bindings
 
-Run `npm test` for runtime contracts and `npm run typecheck` for strict static
-contracts. Run `./run-integration-tests.sh` for all 58 IWF compatibility
-scenarios against an isolated `dexcli dev` environment. Run
+Run `npm run build:native` once to stage the DXBC Node addon for the current
+platform, then `npm test` for runtime contracts and `npm run typecheck` for
+strict static contracts. Run `./run-integration-tests.sh` for all 58 IWF
+compatibility scenarios against an isolated `dexcli dev` environment. Run
 `npm run generate:proto` after changing `protos/dex.proto`; `protoc` and its
 standard protobuf includes must be installed.
 
@@ -118,11 +120,12 @@ suite's workflow behavior and its 58 assertions run against a real Dex server.
 ## Releases
 
 The npm package is published as [`@superdurable/dex`](https://www.npmjs.com/package/@superdurable/dex).
-Update `package.json` and `package-lock.json` to the same version, merge the
-change, then publish a GitHub Release tagged `sdk-typescript/vX.Y.Z`. The
-release workflow verifies that the tag matches `package.json`, runs type checks
-and tests, inspects the tarball, and publishes through npm Trusted Publishing.
-Prerelease versions use the `next` npm dist-tag; stable versions use `latest`.
+After the initial bootstrap, publish a GitHub Release tagged
+`sdk-typescript/vX.Y.Z`. The tag is the release version source of truth; CI
+temporarily writes it to `package.json` and `package-lock.json` without
+committing either file. The release workflow then runs type checks and tests,
+inspects the tarball, and publishes through npm Trusted Publishing. Prerelease
+versions use the `next` npm dist-tag; stable versions use `latest`.
 
 Trusted Publishing can only be configured after the package exists. Bootstrap
 the first version from a maintainer workstation with 2FA:

package/dist/src/blob-cache.js

@@ -5,7 +5,11 @@
 // See the LICENSE file in the repository root.
 //
 // SPDX-License-Identifier: LicenseRef-Super-Durable-1.0
-import { laterPhase } from "./errors.js";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+let nativeModule;
 export function openBlobCache(config) {
     if (config.directory.length === 0) {
         throw new TypeError("blob cache directory is required");
@@ -17,6 +21,80 @@ export function openBlobCache(config) {
         (!Number.isSafeInteger(config.frequencyCounters) || config.frequencyCounters < 0)) {
         throw new RangeError("blob cache frequencyCounters must be a non-negative safe integer");
     }
-    throw laterPhase("BlobCache bridge");
+    return new RustBlobCache(config, loadNativeModule());
+}
+class RustBlobCache {
+    config;
+    native;
+    constructor(config, binding) {
+        this.config = config;
+        this.native = new binding.NativeBlobCache(config.directory, config.maxBytes, config.frequencyCounters ?? 0);
+    }
+    get(blobId) {
+        const payload = this.native.get(blobId);
+        return payload === null ? undefined : new Uint8Array(payload);
+    }
+    put(blobId, payload) {
+        return this.native.put(blobId, Buffer.from(payload));
+    }
+    delete(blobId) {
+        this.native.delete(blobId);
+    }
+    deleteAll() {
+        this.native.deleteAll();
+    }
+    close() {
+        this.native.close();
+    }
+}
+function loadNativeModule() {
+    if (nativeModule !== undefined) {
+        return nativeModule;
+    }
+    const candidates = nativeCandidates();
+    const failures = [];
+    for (const candidate of candidates) {
+        try {
+            nativeModule = require(candidate);
+            return nativeModule;
+        }
+        catch (failure) {
+            failures.push(`${candidate}: ${failure instanceof Error ? failure.message : String(failure)}`);
+        }
+    }
+    throw new Error(`cannot load the Dex BlobCache native module for ${process.platform}/${process.arch}; ` +
+        `set DEX_BLOB_CACHE_NATIVE to an absolute .node path to override packaged natives. ` +
+        `Tried:\n${failures.join("\n")}`);
+}
+function nativeCandidates() {
+    const override = process.env.DEX_BLOB_CACHE_NATIVE;
+    if (override !== undefined && override.length > 0) {
+        return [override];
+    }
+    const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const packaged = join(packageRoot, "native", `${operatingSystem()}-${architecture()}`, "dex_blob_cache_node.node");
+    return [packaged];
+}
+function operatingSystem() {
+    switch (process.platform) {
+        case "darwin":
+            return "macos";
+        case "linux":
+            return "linux";
+        case "win32":
+            return "windows";
+        default:
+            throw new Error(`unsupported operating system: ${process.platform}`);
+    }
+}
+function architecture() {
+    switch (process.arch) {
+        case "x64":
+            return "x86_64";
+        case "arm64":
+            return "aarch64";
+        default:
+            throw new Error(`unsupported architecture: ${process.arch}`);
+    }
 }
 //# sourceMappingURL=blob-cache.js.map

package/dist/src/blob-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"blob-cache.js","sourceRoot":"","sources":["../../src/blob-cache.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,uDAAuD;AACvD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,wDAAwD;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiBzC,MAAM,UAAU,aAAa,CAAC,MAAuB;IACnD,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,SAAS,CAAC,kCAAkC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,UAAU,CAAC,qDAAqD,CAAC,CAAC;IAC9E,CAAC;IACD,IACE,MAAM,CAAC,iBAAiB,KAAK,SAAS;QACtC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,iBAAiB,CAAC,IAAI,MAAM,CAAC,iBAAiB,GAAG,CAAC,CAAC,EACjF,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,kEAAkE,CAAC,CAAC;IAC3F,CAAC;IACD,MAAM,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"blob-cache.js","sourceRoot":"","sources":["../../src/blob-cache.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdurable/dex",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TypeScript SDK for the Dex durable workflow engine",
   "license": "LicenseRef-Super-Durable-1.0",
   "repository": {
@@ -18,6 +18,7 @@
   },
   "files": [
     "dist/src",
+    "native",
     "LICENSE"
   ],
   "exports": {
@@ -32,13 +33,14 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "build:native": "node scripts/build-native.mjs",
     "coverage:integration": "./run-integration-tests.sh --coverage",
     "generate:proto": "node scripts/generate-proto.mjs",
-    "prepack": "npm run build",
-    "test:integration": "npm run build && node --test --test-concurrency=1 dist/test/integ/*.integration.test.js",
-    "test:integration:coverage": "npm run build && c8 node --test --test-concurrency=1 dist/test/integ/*.integration.test.js && node scripts/report-uncovered.mjs coverage/lcov.info",
+    "prepack": "npm run build:native && npm run build",
+    "test:integration": "npm run build:native && npm run build && node --test --test-concurrency=1 dist/test/integ/*.integration.test.js",
+    "test:integration:coverage": "npm run build:native && npm run build && c8 node --test --test-concurrency=1 dist/test/integ/*.integration.test.js && node scripts/report-uncovered.mjs coverage/lcov.info",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test dist/test/*.test.js"
+    "test": "npm run build:native && npm run build && node --test dist/test/*.test.js"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",