@alienplatform/bindings 1.0.0 → 2.0.0

package/dist/loader.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Native addon loader.
+ *
+ * Resolves the napi-rs addon for the current platform, in order:
+ *
+ *   1. `ALIEN_BINDINGS_ADDON_PATH` — an explicit path to a `.node` file. This is
+ *      a dev/test-only escape hatch and is never set in published installs.
+ *   2. The per-platform prebuild package from `optionalDependencies`
+ *      (`@alienplatform/bindings-<triple>`) — how end users get the addon.
+ *      `optionalDependencies` only exists in the *published* manifest: the
+ *      release pipeline injects the exact-version package list with
+ *      `scripts/inject-optional-deps.mjs`. The workspace source manifest carries
+ *      no `optionalDependencies`, so this path is a no-op
+ *      (module-not-found) in every dev/test checkout — expected, and why step 3
+ *      exists below. Its reported version must match this wrapper package;
+ *      mixed wrapper/prebuild versions are rejected before any binding runs.
+ *   3. Dev fallback: the locally-built addon under
+ *      `crates/alien-bindings-node/alien-bindings-node.<triple>.node`, located by
+ *      walking up from this module. This lets the repo run against a
+ *      `napi build`-produced `.node` without publishing a prebuild. Before
+ *      trusting this addon, its `version()` is compared against this
+ *      package's own `package.json` version; a mismatch (a stale local build
+ *      left over from an earlier checkout) is logged and rejected rather than
+ *      loaded, falling through to the same "cannot load" error as if no addon
+ *      had been found at all.
+ *
+ * Loading is deferred: `loadAddon()` is only called on the first binding
+ * operation (see `factories.ts`), never at module import. That is what makes the
+ * package safe to mark `sideEffects: false` — importing it performs no I/O and
+ * requires no addon.
+ */
+/** Raw napi scan page. */
+export interface RawKvItem {
+    key: string;
+    value: Buffer;
+}
+/** Raw napi scan result. */
+export interface RawScanResult {
+    items: RawKvItem[];
+    nextCursor?: string;
+}
+/** Raw napi object metadata. */
+export interface RawObjectMeta {
+    location: string;
+    size: number;
+    lastModified: string;
+}
+/** Raw napi presigned request. */
+export interface RawPresignedRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+}
+/** Raw napi queue message. */
+export interface RawQueueMessage {
+    payloadType: "json" | "text";
+    payload: string;
+    receiptHandle: string;
+    attempt: number;
+}
+/** Raw napi storage handle. */
+export interface RawStorageHandle {
+    get(path: string): Promise<Buffer>;
+    put(path: string, data: Buffer): Promise<void>;
+    delete(path: string): Promise<void>;
+    list(prefix?: string | null): Promise<RawObjectMeta[]>;
+    head(path: string): Promise<RawObjectMeta>;
+    copy(from: string, to: string): Promise<void>;
+    signedUrl(method: string, path: string, expiresInSecs: number): Promise<RawPresignedRequest>;
+}
+/** Raw napi key-value handle. */
+export interface RawKvHandle {
+    get(key: string): Promise<Buffer | null>;
+    put(key: string, value: Buffer, ttlSecs?: number | null, ifNotExists?: boolean | null): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    scan(prefix: string, limit?: number | null, cursor?: string | null): Promise<RawScanResult>;
+}
+/** Raw napi queue handle. Every method takes the queue name as its first arg. */
+export interface RawQueueHandle {
+    sendJson(queue: string, jsonString: string): Promise<void>;
+    sendText(queue: string, text: string): Promise<void>;
+    receive(queue: string, max: number): Promise<RawQueueMessage[]>;
+    ack(queue: string, receipt: string): Promise<void>;
+    nack(queue: string, receipt: string): Promise<void>;
+    purge(queue: string): Promise<void>;
+}
+/** Raw napi vault handle. */
+export interface RawVaultHandle {
+    getSecret(name: string): Promise<string>;
+    setSecret(name: string, value: string): Promise<void>;
+    deleteSecret(name: string): Promise<void>;
+    listSecrets(): Promise<string[]>;
+}
+/** Raw napi bindings entry point. Construction validates the environment. */
+export interface RawBindingsHandle {
+    storage(name: string): Promise<RawStorageHandle>;
+    kv(name: string): Promise<RawKvHandle>;
+    queue(name: string): Promise<RawQueueHandle>;
+    vault(name: string): Promise<RawVaultHandle>;
+}
+/** The complete napi addon module surface consumed by the wrapper. */
+export interface NativeAddon {
+    BindingsHandle: new () => RawBindingsHandle;
+    version(): string;
+}
+/** The Linux C library a prebuild is compiled against. */
+export type LinuxLibc = "gnu" | "musl";
+/**
+ * Detect the Linux C library (glibc vs musl) of the current process, using the
+ * same signal as napi-rs's generated loader: a glibc runtime reports a
+ * `glibcVersionRuntime` in its process report; a musl runtime (Alpine, etc.)
+ * does not. Falls back to the Alpine marker file when the report is
+ * unavailable.
+ *
+ * Only meaningful on Linux — `platformTriple` consults the result solely on the
+ * `linux` branch, so the value returned on other platforms is unused.
+ */
+export declare function detectLinuxLibc(): LinuxLibc;
+/**
+ * Map `process.platform` / `process.arch` to the napi triple used in both the
+ * prebuild package name and the locally-built `.node` file name. Mirrors the
+ * `optionalDependencies` set pinned in PACKAGE_LAYOUT.md.
+ *
+ * Only glibc Linux prebuilds are published (`…-gnu`; see PACKAGE_LAYOUT.md), so
+ * a musl host (Alpine and friends) has no addon: this throws a clear
+ * unsupported-platform error naming musl rather than silently selecting the
+ * glibc triple, which would otherwise fail to resolve — or, worse, load a glibc
+ * `.node` into a musl process and crash on the first binding call.
+ *
+ * Exported for unit testing: accepts `platform`/`arch`/`libc` explicitly
+ * (defaulting to the detected values) so every supported pair — and the
+ * unsupported cases — can be exercised directly, without stubbing `process`.
+ */
+export declare function platformTriple(platform?: NodeJS.Platform, arch?: NodeJS.Architecture, libc?: LinuxLibc): string;
+/**
+ * Walk up from `startDir` (default: this module's directory) looking for the
+ * locally-built addon under `crates/alien-bindings-node`, returning its path or
+ * `undefined` if the walk reaches the filesystem root without finding it.
+ * Repo-internal dev/test only. Also reused by `scripts/compile-smoke.ts`.
+ */
+export declare function findLocalAddon(triple: string, startDir?: string): string | undefined;
+/**
+ * Reject wrapper/addon version skew before the native module is used.
+ *
+ * The wrapper and every platform prebuild are published as one release. npm
+ * normally installs the exact version pinned in `optionalDependencies`, but a
+ * stale lockfile, package-manager override, or copied `node_modules` can still
+ * leave a different native binary on disk. Loading that binary risks calling
+ * an incompatible napi surface, so fail with the two observed versions.
+ */
+export declare function assertAddonVersion(addon: NativeAddon, expected: string, source: string): void;
+/**
+ * Register an addon that is already resident in the process — the one bun
+ * embeds into a `bun build --compile` binary through the `./native` entry.
+ *
+ * A compiled workload has no filesystem prebuild and no dev checkout to walk,
+ * so none of the resolution steps in {@link loadAddon} can find the addon. The
+ * build makes the compiled entry import `@alienplatform/bindings/native`, whose
+ * `installEmbeddedAddon()` calls this so the ordinary `@alienplatform/bindings`
+ * factories (which go through {@link loadAddon}) use the embedded addon. In a
+ * non-compiled dev/test run nothing imports `./native`, so this is never called
+ * and {@link loadAddon} falls through to its normal resolution.
+ */
+export declare function registerEmbeddedAddon(addon: NativeAddon): void;
+/**
+ * Load (and memoize) the native addon. Throws if no addon can be resolved for
+ * the current platform. Called lazily on the first binding operation.
+ */
+export declare function loadAddon(): NativeAddon;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"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"}