@alienplatform/bindings 1.0.0 → 2.0.0

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 Alien Software, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

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"}