@alienplatform/bindings 1.0.0 → 1.14.1-dev.e74fae6cd01b61e77a285276f264b5480977f41a

package/README.md

@@ -0,0 +1,59 @@
+# `@alienplatform/bindings`
+
+Direct TypeScript bindings for Alien storage, kv, queue, and vault over an
+in-process [napi-rs](https://napi.rs) addon. The addon itself lives in the Rust
+crate `crates/alien-bindings-node`; this package is the published JavaScript
+wrapper that loads it.
+
+## Native addon resolution
+
+The addon is loaded lazily on the first binding operation (never at import — the
+package is `sideEffects: false`). `src/loader.ts` resolves it in order:
+
+1. `ALIEN_BINDINGS_ADDON_PATH` — an explicit path to a `.node` file. A dev/test
+   escape hatch only; never set in a published install.
+2. The per-platform prebuild package `@alienplatform/bindings-<triple>`, pulled
+   in as an `optionalDependency`. This is how end users get the addon: `npm`/`bun`
+   installs only the package matching the host `os`/`cpu`/`libc`. The
+   `optionalDependencies` block exists **only in the published manifest** — it is
+   injected at publish time by the release pipeline, so a workspace checkout
+   carries none.
+3. Dev fallback: a locally-built addon at
+   `crates/alien-bindings-node/alien-bindings-node.<triple>.node`, found by
+   walking up from the installed package. Loaded only if its `version()` matches
+   this package's version (a stale build is warned about and rejected).
+
+## Local development
+
+Build the addon for your host once, then run anything that imports the package:
+
+```sh
+bun run build:addon   # or: pnpm -C packages/bindings run build:addon
+```
+
+`build:addon` runs `napi build --platform --release` against
+`crates/alien-bindings-node` and drops the `.node` next to the crate, where the
+loader's dev fallback (step 3 above) finds it. Rebuild after changing any Rust
+in `alien-bindings` or `alien-bindings-node`. The built `.node` is gitignored.
+`build:addon` only builds for the host triple; on a Mac, cross-building the
+other mac triple (e.g. `darwin-x64` from an `arm64` host) needs an explicit
+`napi build --release --target x86_64-apple-darwin --cwd
+../../crates/alien-bindings-node`.
+
+To point the loader at an addon somewhere else, set `ALIEN_BINDINGS_ADDON_PATH`
+to its path (step 1).
+
+## Prebuild packages (`npm/`)
+
+`npm/<triple>/` holds the skeleton for each published per-platform package
+(`darwin-arm64`, `darwin-x64`, `linux-x64-gnu`, `linux-arm64-gnu`). Each carries
+a `package.json` (`name`/`os`/`cpu`/`libc`/`main`/`files`) and a README; the
+`.node` is staged in at build time and is never committed. There is no musl
+target: the deployment base images are glibc (chainguard/wolfi-base), not Alpine.
+
+The release pipeline builds each addon on its native runner, stages it into the
+matching `npm/<triple>/` dir, rewrites the placeholder `0.0.0` versions to the
+release version, injects the exact-version `optionalDependencies` into this
+package's published manifest, and publishes the platform packages before the
+wrapper. Pinning the exact version is what guarantees a published wrapper only
+ever loads the matching-version platform addon.

package/dist/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Error definitions and napi error recovery for `@alienplatform/bindings`.
+ *
+ * The native addon runs every binding operation as an async napi method. napi
+ * constrains async errors to a fixed `Status` string, so `err.code` is always
+ * `"GenericFailure"` and carries no information. The addon instead serializes a
+ * structured envelope into the JS `err.message`:
+ *
+ *   { code, message, context?, retryable }
+ *
+ * where `context` keys are snake_case (e.g. `binding_name`, `env_var`).
+ * `unwrapNapiError` recovers that envelope with a single `JSON.parse` — never by
+ * scraping the human message — and maps it to a typed {@link AlienError}.
+ */
+import { AlienError, defineError } from "@alienplatform/core";
+import * as z from "zod/v4";
+export { AlienError, defineError };
+/**
+ * Thrown on the first operation against a binding that has no
+ * `ALIEN_<NAME>_BINDING` entry in the environment.
+ *
+ * `binding` is the binding name; `envVar` is the missing `ALIEN_<NAME>_BINDING`
+ * variable. Both are mapped from the addon envelope's snake_case
+ * `binding_name` / `env_var` context keys.
+ */
+export declare const BindingNotConfiguredError: {
+    metadata: import("@alienplatform/core").AlienErrorMetadata<z.ZodObject<{
+        binding: z.ZodString;
+        envVar: z.ZodString;
+    }, z.core.$strip>>;
+    contextSchema: z.ZodObject<{
+        binding: z.ZodString;
+        envVar: z.ZodString;
+    }, z.core.$strip>;
+    create: (context: {
+        binding: string;
+        envVar: string;
+    }) => import("@alienplatform/core").AlienErrorDefinition<z.ZodObject<{
+        binding: z.ZodString;
+        envVar: z.ZodString;
+    }, z.core.$strip>>;
+};
+/**
+ * Recover a typed {@link AlienError} from an error thrown by the native addon.
+ *
+ * - An error that is already an {@link AlienError} passes through unchanged.
+ * - A message carrying the addon envelope is decoded: `BINDING_NOT_CONFIGURED`
+ *   becomes {@link BindingNotConfiguredError} (with `binding` / `envVar` mapped
+ *   from the envelope's snake_case context); every other envelope code becomes a
+ *   generic `AlienError` that preserves the `code`, `message`, `context`, and
+ *   `retryable` flag.
+ * - A non-envelope message (napi-internal error) is wrapped as a generic
+ *   `BINDINGS_ERROR`, preserving the original message.
+ */
+export declare function unwrapNapiError(err: unknown): AlienError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC7D,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAA;AAI3B,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAA;AAElC;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;CAWpC,CAAA;AAwCF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAsCxD"}

package/dist/factories.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The four binding factories, parameterized over how the native addon is
+ * obtained. `index.ts` binds them to the lazy {@link loadAddon}; `native.ts`
+ * binds them to a statically-embedded addon.
+ *
+ * Laziness contract: constructing a factory result performs no work. The first
+ * operation on a handle materializes the `BindingsHandle` and the resource
+ * handle exactly once, caches both, and every operation translates thrown napi
+ * errors through {@link unwrapNapiError}. A failed materialization is not
+ * cached, so a later call retries.
+ *
+ * Handle methods are closures (not `this`-bound class methods), so they behave
+ * correctly even when destructured off the handle (`const { get } = storage(x)`).
+ */
+import type { NativeAddon } from "./loader.js";
+import type { Kv, Queue, Storage, Vault } from "./types.js";
+/** The public factory surface. */
+export interface Factories {
+    storage(name: string): Storage;
+    kv(name: string): Kv;
+    queue(name: string): Queue;
+    vault(name: string): Vault;
+}
+/** Build the four factories bound to a given addon provider. */
+export declare function createFactories(getAddon: () => NativeAddon): Factories;
+//# sourceMappingURL=factories.d.ts.map

package/dist/factories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../src/factories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EACV,WAAW,EAMZ,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EACV,EAAE,EAIF,KAAK,EAGL,OAAO,EACP,KAAK,EACN,MAAM,YAAY,CAAA;AA+HnB,kCAAkC;AAClC,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAC9B,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,EAAE,CAAA;IACpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;IAC1B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;CAC3B;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,WAAW,GAAG,SAAS,CAWtE"}