@slatedb/uniffi 0.12.0

package/README.md

@@ -0,0 +1,211 @@
+# SlateDB Node Binding
+
+`bindings/node` contains the official Node.js package for SlateDB.
+
+## Install
+
+Package:
+
+```text
+@slatedb/uniffi
+```
+
+Requirements:
+
+- Node.js 20 or newer
+
+Install from npm:
+
+```bash
+npm install @slatedb/uniffi
+```
+
+## API Model
+
+- `ObjectStore.resolve(...)` opens an object store from a URL such as `memory:///` or `file:///...`
+- `DbBuilder` opens a writable database and `DbReaderBuilder` opens a read-only reader
+- keys and values are binary; pass `Buffer` or `Uint8Array`
+- most database operations are async and should be awaited
+- builders are single-use; `Db` and `DbReader` stay open until `shutdown()` resolves
+- native-backed handles also expose `dispose()` for deterministic cleanup after `shutdown()` or when abandoning a builder
+
+## Quick Start
+
+```js
+import assert from "node:assert/strict";
+import { DbBuilder, ObjectStore } from "@slatedb/uniffi";
+
+async function main() {
+  const store = ObjectStore.resolve("memory:///");
+  let db;
+
+  try {
+    const builder = new DbBuilder("demo-db", store);
+    try {
+      db = await builder.build();
+    } finally {
+      builder.dispose();
+    }
+
+    const key = Buffer.from("hello");
+    const value = Buffer.from("world");
+
+    await db.put(key, value);
+
+    const read = await db.get(key);
+    assert.deepEqual(read, value);
+
+    console.log(Buffer.from(read).toString("utf8"));
+  } finally {
+    if (db != null) {
+      await db.shutdown();
+      db.dispose();
+    }
+    store.dispose();
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+```
+
+Replace `memory:///` with any object store URL supported by Rust's [`object_store`](https://docs.rs/object_store/latest/object_store/fn.parse_url_opts.html) crate.
+
+## Metrics
+
+The Node binding exposes both application-provided metrics recorders and the built-in
+`DefaultMetricsRecorder`:
+
+- `DbBuilder.with_metrics_recorder(...)`
+- `DbReaderBuilder.with_metrics_recorder(...)`
+- `DefaultMetricsRecorder.snapshot()`
+- `DefaultMetricsRecorder.metrics_by_name(...)`
+- `DefaultMetricsRecorder.metric_by_name_and_labels(...)`
+
+Example:
+
+```js
+import { DbBuilder, DefaultMetricsRecorder, ObjectStore } from "@slatedb/uniffi";
+
+const store = ObjectStore.resolve("memory:///");
+const recorder = new DefaultMetricsRecorder();
+const builder = new DbBuilder("metrics-demo", store);
+
+try {
+  builder.with_metrics_recorder(recorder);
+  const db = await builder.build();
+  try {
+    await db.put(Buffer.from("hello"), Buffer.from("world"));
+
+    const metric = recorder.metric_by_name_and_labels("slatedb.db.write_ops", []);
+    if (metric?.value.tag === "Counter") {
+      console.log(metric.value[""]);
+    }
+  } finally {
+    await db.shutdown();
+    db.dispose();
+  }
+} finally {
+  builder.dispose();
+  recorder.dispose();
+  store.dispose();
+}
+```
+
+## Local Development
+
+The package is generated from the UniFFI `slatedb-uniffi` cdylib using [`uniffi-bindgen-node-js`](https://crates.io/crates/uniffi-bindgen-node-js).
+
+You only need these tools when regenerating bindings, running tests from this repository, or packing the npm artifact locally:
+
+- Node.js 20 or newer
+- Rust toolchain for this repository
+- `uniffi-bindgen-node-js` on `PATH`
+
+Install the generator with:
+
+```bash
+cargo install uniffi-bindgen-node-js --version 0.0.7
+```
+
+Install the package dependency used by the generated bindings with:
+
+```bash
+npm --prefix bindings/node install
+```
+
+### Regenerate Bindings
+
+From the repository root:
+
+```bash
+npm --prefix bindings/node run build
+```
+
+This command:
+
+1. builds the host `slatedb-uniffi` library
+2. runs `uniffi-bindgen-node-js`
+3. copies the generated package files into `bindings/node`
+4. stages the host native library under `bindings/node/prebuilds/<target>/`
+
+Generated API files are written into `bindings/node` and are not committed. `package.json`, `build.mjs`, and this `README.md` are maintained by hand.
+
+### Run Tests
+
+From the repository root:
+
+```bash
+npm --prefix bindings/node test
+```
+
+The test script rebuilds the package and then runs `node --test` inside `bindings/node`.
+
+### Reproduce The PR CI Flow
+
+From the repository root, this mirrors the Node validation done in `.github/workflows/pr.yaml`:
+
+```bash
+npm --prefix bindings/node ci
+npm --prefix bindings/node run build
+(cd bindings/node && node --test)
+git diff --exit-code -- bindings/node
+rm -rf /tmp/slatedb-node-pack
+mkdir -p /tmp/slatedb-node-pack
+(cd bindings/node && npm pack --pack-destination /tmp/slatedb-node-pack)
+TARBALL="$(find /tmp/slatedb-node-pack -maxdepth 1 -name '*.tgz' | head -n 1)"
+test -n "${TARBALL}"
+tar -tf "${TARBALL}" | grep -Fx 'package/index.js'
+tar -tf "${TARBALL}" | grep -Fx 'package/index.d.ts'
+tar -tf "${TARBALL}" | grep -Fx 'package/slatedb.js'
+tar -tf "${TARBALL}" | grep -Fx 'package/slatedb.d.ts'
+tar -tf "${TARBALL}" | grep -Fx 'package/slatedb-ffi.js'
+tar -tf "${TARBALL}" | grep -Fx 'package/slatedb-ffi.d.ts'
+tar -tf "${TARBALL}" | grep -Fx 'package/runtime/ffi-types.js'
+tar -tf "${TARBALL}" | grep -Fx 'package/prebuilds/linux-x64-gnu/libslatedb_uniffi.so'
+```
+
+## Packaging And Runtime Notes
+
+The published `@slatedb/uniffi` tarball contains generated JavaScript and TypeScript bindings plus bundled native libraries. Consumers install one npm package; there is no separate Rust build step or native download in normal usage.
+
+At runtime, the package loads the native library that matches the current host from `prebuilds/<target>/`. The published package currently includes:
+
+- `linux-x64-gnu`
+- `linux-arm64-gnu`
+- `darwin-x64`
+- `darwin-arm64`
+- `win32-x64`
+- `win32-arm64`
+
+Linux musl targets are not packaged today. Local builds stage only the host native library; release builds stage all supported targets into the published npm package.
+
+When assembling a release package from a prebuilt native directory, run:
+
+```bash
+npm --prefix bindings/node run build -- --prebuilt-dir <dir>
+```
+
+The generated API files stay the same; only the packaged native libraries change between local and release builds.

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./slatedb.js";

package/index.js

@@ -0,0 +1,7 @@
+
+import { load as loadFfi } from "./slatedb-ffi.js";
+
+loadFfi();
+
+
+export * from "./slatedb.js";

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@slatedb/uniffi",
+  "version": "0.12.0",
+  "description": "Node.js bindings for SlateDB generated from UniFFI and packaged with native libraries.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "types": "./index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "slatedb.js",
+    "slatedb.d.ts",
+    "slatedb-ffi.js",
+    "slatedb-ffi.d.ts",
+    "runtime/",
+    "prebuilds/"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slatedb/slatedb.git",
+    "directory": "bindings/node"
+  },
+  "homepage": "https://slatedb.io",
+  "bugs": {
+    "url": "https://github.com/slatedb/slatedb/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ./build.mjs",
+    "test": "npm run build && node --test"
+  },
+  "dependencies": {
+    "koffi": "^2.0.0"
+  }
+}

package/runtime/async-rust-call.d.ts

@@ -0,0 +1,86 @@
+import type { RustCallStatusStruct } from "./ffi-types.js";
+import type { RustCallOptions, UniffiRustCaller } from "./rust-call.js";
+
+export declare const RUST_FUTURE_POLL_READY: 0;
+export declare const RUST_FUTURE_POLL_WAKE: 1;
+
+export interface AsyncCallState {
+  resolverHandle: bigint | null;
+}
+
+export type RustFutureContinuationCallback = (
+  handle: bigint | number,
+  pollResult: bigint | number,
+) => boolean;
+
+export interface PollRustFutureOptions {
+  continuationCallback?: RustFutureContinuationCallback;
+  state?: AsyncCallState;
+}
+
+export interface CompleteRustFutureOptions<
+  Status = RustCallStatusStruct,
+  E extends Error = Error,
+> extends RustCallOptions<E> {
+  rustCaller?: UniffiRustCaller<Status>;
+}
+
+export interface RustCallAsyncOptions<
+  Lowered,
+  Result = Lowered,
+  Status = RustCallStatusStruct,
+  E extends Error = Error,
+> extends CompleteRustFutureOptions<Status, E> {
+  cancelFunc?: ((rustFuture: bigint) => void) | null;
+  completeFunc: (rustFuture: bigint, status: Status) => Lowered;
+  continuationCallback?: RustFutureContinuationCallback;
+  freeFunc?: ((rustFuture: bigint) => void) | null;
+  liftFunc?: (value: Lowered) => Result;
+  pollFunc: (
+    rustFuture: bigint,
+    continuationCallback: RustFutureContinuationCallback,
+    continuationHandle: bigint,
+  ) => void;
+  rustFutureFunc: () => bigint;
+  signal?: AbortSignal | null;
+}
+
+export declare function decodeRustFuturePoll(value: bigint | number): number;
+export declare function createAsyncCallState(): AsyncCallState;
+export declare function cleanupAsyncCallState(state: AsyncCallState): void;
+export declare const rustFutureContinuationCallback: RustFutureContinuationCallback;
+export declare function pollRustFuture(
+  rustFuture: bigint,
+  pollFunc: (
+    rustFuture: bigint,
+    continuationCallback: RustFutureContinuationCallback,
+    continuationHandle: bigint,
+  ) => void,
+  options?: PollRustFutureOptions,
+): Promise<number>;
+export declare function completeRustFuture<
+  Lowered,
+  Status = RustCallStatusStruct,
+  E extends Error = Error,
+>(
+  rustFuture: bigint,
+  completeFunc: (rustFuture: bigint, status: Status) => Lowered,
+  options?: CompleteRustFutureOptions<Status, E>,
+): Lowered;
+export declare function cancelRustFuture(
+  rustFuture: bigint,
+  cancelFunc?: ((rustFuture: bigint) => void) | null,
+): void;
+export declare function freeRustFuture(
+  rustFuture: bigint,
+  freeFunc?: ((rustFuture: bigint) => void) | null,
+): void;
+export declare function rustCallAsync<
+  Lowered,
+  Result = Lowered,
+  Status = RustCallStatusStruct,
+  E extends Error = Error,
+>(
+  options: RustCallAsyncOptions<Lowered, Result, Status, E>,
+): Promise<Result>;
+export declare function rustFutureHandleCount(): number;

package/runtime/async-rust-call.js

@@ -0,0 +1,217 @@
+import { AbortError, ConverterRangeError } from "./errors.js";
+import { UniffiHandleMap } from "./handle-map.js";
+import { defaultRustCaller } from "./rust-call.js";
+
+export const RUST_FUTURE_POLL_READY = 0;
+export const RUST_FUTURE_POLL_WAKE = 1;
+const RUST_FUTURE_KEEPALIVE_DELAY_MS = 0x7fffffff;
+
+const MIN_I8 = -0x80;
+const MAX_I8 = 0x7f;
+const MAX_U8 = 0xff;
+const RUST_FUTURE_RESOLVER_MAP = new UniffiHandleMap();
+const RUST_FUTURE_KEEPALIVE_MAP = new Map();
+
+function identity(value) {
+  return value;
+}
+
+export function decodeRustFuturePoll(value) {
+  const numericValue =
+    typeof value === "bigint"
+      ? Number(value)
+      : value;
+  if (!Number.isInteger(numericValue) || numericValue < MIN_I8 || numericValue > MAX_U8) {
+    throw new ConverterRangeError(
+      `RustFuturePoll must be an integer between ${MIN_I8} and ${MAX_U8}.`,
+    );
+  }
+  return numericValue > MAX_I8
+    ? numericValue - 0x100
+    : numericValue;
+}
+
+export function createAsyncCallState() {
+  return {
+    resolverHandle: null,
+  };
+}
+
+function clearRustFutureKeepAlive(handle) {
+  const keepAlive = RUST_FUTURE_KEEPALIVE_MAP.get(handle);
+  if (keepAlive === undefined) {
+    return;
+  }
+
+  RUST_FUTURE_KEEPALIVE_MAP.delete(handle);
+  clearTimeout(keepAlive);
+}
+
+export function cleanupAsyncCallState(state) {
+  if (!state || state.resolverHandle == null) {
+    return;
+  }
+
+  clearRustFutureKeepAlive(state.resolverHandle);
+  RUST_FUTURE_RESOLVER_MAP.remove(state.resolverHandle);
+  state.resolverHandle = null;
+}
+
+export const rustFutureContinuationCallback = (handle, pollResult) => {
+  clearRustFutureKeepAlive(handle);
+  const resolve = RUST_FUTURE_RESOLVER_MAP.remove(handle);
+  if (resolve === undefined) {
+    return false;
+  }
+
+  queueMicrotask(() => {
+    resolve(decodeRustFuturePoll(pollResult));
+  });
+  return true;
+};
+
+export function pollRustFuture(
+  rustFuture,
+  pollFunc,
+  {
+    continuationCallback = rustFutureContinuationCallback,
+    state = createAsyncCallState(),
+  } = {},
+) {
+  cleanupAsyncCallState(state);
+
+  return new Promise((resolve, reject) => {
+    // Node 22 can tear down the event loop while this promise is still waiting
+    // on a native callback. Keep a ref'ed timer alive until the callback
+    // settles so Rust future completions arrive before environment cleanup.
+    const keepAlive = setTimeout(() => {}, RUST_FUTURE_KEEPALIVE_DELAY_MS);
+    let resolverHandle = null;
+    const settle = (callback, value) => {
+      clearRustFutureKeepAlive(resolverHandle);
+      callback(value);
+    };
+    resolverHandle = RUST_FUTURE_RESOLVER_MAP.insert((pollCode) => {
+      state.resolverHandle = null;
+      settle(resolve, pollCode);
+    });
+    RUST_FUTURE_KEEPALIVE_MAP.set(resolverHandle, keepAlive);
+    state.resolverHandle = resolverHandle;
+
+    try {
+      pollFunc(rustFuture, continuationCallback, resolverHandle);
+    } catch (error) {
+      cleanupAsyncCallState(state);
+      settle(reject, error);
+    }
+  });
+}
+
+export function completeRustFuture(
+  rustFuture,
+  completeFunc,
+  {
+    errorHandler,
+    freeRustBuffer,
+    liftString,
+    rustCaller = defaultRustCaller,
+  } = {},
+) {
+  return rustCaller.makeRustCall(
+    (status) => completeFunc(rustFuture, status),
+    {
+      errorHandler,
+      freeRustBuffer,
+      liftString,
+    },
+  );
+}
+
+export function cancelRustFuture(rustFuture, cancelFunc = undefined) {
+  if (typeof cancelFunc === "function") {
+    cancelFunc(rustFuture);
+  }
+}
+
+export function freeRustFuture(rustFuture, freeFunc = undefined) {
+  if (typeof freeFunc === "function") {
+    freeFunc(rustFuture);
+  }
+}
+
+export async function rustCallAsync({
+  cancelFunc,
+  completeFunc,
+  continuationCallback = rustFutureContinuationCallback,
+  errorHandler,
+  freeFunc,
+  freeRustBuffer,
+  liftFunc = identity,
+  liftString,
+  pollFunc,
+  rustCaller = defaultRustCaller,
+  rustFutureFunc,
+  signal = undefined,
+}) {
+  if (signal?.aborted) {
+    throw new AbortError();
+  }
+
+  const rustFuture = rustFutureFunc();
+  const state = createAsyncCallState();
+  const abortListener =
+    signal == null
+      ? null
+      : () => {
+          try {
+            cancelRustFuture(rustFuture, cancelFunc);
+          } catch {
+            // Preserve the original async failure path.
+          }
+        };
+
+  if (signal && abortListener) {
+    if (signal.aborted) {
+      abortListener();
+    } else {
+      signal.addEventListener("abort", abortListener, { once: true });
+    }
+  }
+
+  try {
+    while (true) {
+      const pollCode = await pollRustFuture(rustFuture, pollFunc, {
+        continuationCallback,
+        state,
+      });
+      if (pollCode === RUST_FUTURE_POLL_READY) {
+        break;
+      }
+      if (pollCode !== RUST_FUTURE_POLL_WAKE) {
+        throw new ConverterRangeError(
+          `Unexpected RustFuturePoll value ${String(pollCode)}.`,
+        );
+      }
+    }
+
+    const completed = completeRustFuture(rustFuture, completeFunc, {
+      errorHandler,
+      freeRustBuffer,
+      liftString,
+      rustCaller,
+    });
+    return liftFunc(completed);
+  } finally {
+    if (signal && abortListener) {
+      signal.removeEventListener("abort", abortListener);
+    }
+    try {
+      freeRustFuture(rustFuture, freeFunc);
+    } finally {
+      cleanupAsyncCallState(state);
+    }
+  }
+}
+
+export function rustFutureHandleCount() {
+  return RUST_FUTURE_RESOLVER_MAP.size;
+}