@slatedb/uniffi 0.12.0

package/runtime/handle-map.js

@@ -0,0 +1,137 @@
+import { DuplicateHandleError, StaleHandleError } from "./errors.js";
+import { normalizeHandle, normalizeUInt64 } from "./ffi-types.js";
+
+export const INVALID_HANDLE = 0n;
+export const defaultUniffiHandle = INVALID_HANDLE;
+export const FIRST_FOREIGN_HANDLE = 1n;
+export const FOREIGN_HANDLE_STEP = 2n;
+
+function requireHandle(handle, label = "handle") {
+  const normalized = normalizeHandle(handle);
+  if (normalized == null || normalized === INVALID_HANDLE) {
+    throw new TypeError(`${label} must be a non-zero UniFFI handle.`);
+  }
+  return normalized;
+}
+
+function normalizeHandleStep(step) {
+  const normalized = normalizeUInt64(step ?? FOREIGN_HANDLE_STEP);
+  if (normalized == null || normalized === 0n) {
+    throw new TypeError("handleStep must be a positive integer.");
+  }
+  return normalized;
+}
+
+export class UniffiHandleMap {
+  constructor({
+    firstHandle = FIRST_FOREIGN_HANDLE,
+    handleStep = FOREIGN_HANDLE_STEP,
+  } = {}) {
+    this._map = new Map();
+    this._nextHandle = requireHandle(firstHandle, "firstHandle");
+    this._handleStep = normalizeHandleStep(handleStep);
+  }
+
+  _allocateHandle() {
+    const handle = this._nextHandle;
+    this._nextHandle += this._handleStep;
+    return handle;
+  }
+
+  insert(value) {
+    let handle = this._allocateHandle();
+    while (this._map.has(handle)) {
+      handle = this._allocateHandle();
+    }
+    this._map.set(handle, value);
+    return handle;
+  }
+
+  register(handle, value) {
+    const normalized = requireHandle(handle);
+    if (this._map.has(normalized)) {
+      throw new DuplicateHandleError(normalized);
+    }
+    this._map.set(normalized, value);
+    return normalized;
+  }
+
+  get(handle) {
+    const normalized = requireHandle(handle);
+    if (!this._map.has(normalized)) {
+      throw new StaleHandleError(normalized);
+    }
+    return this._map.get(normalized);
+  }
+
+  peek(handle) {
+    const normalized = normalizeHandle(handle);
+    if (normalized == null || normalized === INVALID_HANDLE) {
+      return undefined;
+    }
+    return this._map.get(normalized);
+  }
+
+  clone(handle) {
+    return this.insert(this.get(handle));
+  }
+
+  remove(handle) {
+    const normalized = normalizeHandle(handle);
+    if (normalized == null || normalized === INVALID_HANDLE) {
+      return undefined;
+    }
+
+    const value = this._map.get(normalized);
+    if (this._map.has(normalized)) {
+      this._map.delete(normalized);
+      return value;
+    }
+    return undefined;
+  }
+
+  take(handle) {
+    const normalized = requireHandle(handle);
+    if (!this._map.has(normalized)) {
+      throw new StaleHandleError(normalized);
+    }
+    const value = this._map.get(normalized);
+    this._map.delete(normalized);
+    return value;
+  }
+
+  has(handle) {
+    const normalized = normalizeHandle(handle);
+    return normalized != null
+      && normalized !== INVALID_HANDLE
+      && this._map.has(normalized);
+  }
+
+  clear() {
+    this._map.clear();
+  }
+
+  keys() {
+    return this._map.keys();
+  }
+
+  values() {
+    return this._map.values();
+  }
+
+  entries() {
+    return this._map.entries();
+  }
+
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+
+  get size() {
+    return this._map.size;
+  }
+}
+
+export function createHandleMap(options = undefined) {
+  return new UniffiHandleMap(options);
+}

package/runtime/objects.d.ts

@@ -0,0 +1,68 @@
+import type { ByteReader, ByteWriter } from "./ffi-converters.js";
+
+export declare const uniffiTypeNameSymbol: unique symbol;
+export declare const uniffiObjectFactorySymbol: unique symbol;
+export declare const uniffiObjectHandleSymbol: unique symbol;
+export declare const uniffiObjectDestroyedSymbol: unique symbol;
+export declare const UNIFFI_OBJECT_HANDLE_SIZE: 8;
+
+export interface UniffiObjectFactoryOptions<T extends object = UniffiObjectBase> {
+  typeName?: string;
+  createInstance?: () => T;
+  cloneFreeUsesUniffiHandle?: boolean | null;
+  cloneHandle?: ((handle: unknown, value: T) => unknown) | null;
+  cloneHandleGeneric?: ((handle: unknown, value: T) => unknown) | null;
+  cloneHandleRawExternal?: ((handle: unknown, value: T) => unknown) | null;
+  freeHandle?: ((handle: unknown, value?: T) => void) | null;
+  freeHandleGeneric?: ((handle: unknown, value?: T) => void) | null;
+  freeHandleRawExternal?: ((handle: unknown, value?: T) => void) | null;
+  handleType?: unknown | (() => unknown) | null;
+  serializeHandle?: ((handle: unknown, value: T) => bigint | number) | null;
+  deserializeHandle?: ((handle: bigint | number) => unknown) | null;
+}
+
+export declare class UniffiObjectBase {
+  readonly [uniffiTypeNameSymbol]?: string;
+  readonly [uniffiObjectHandleSymbol]?: unknown;
+  readonly [uniffiObjectDestroyedSymbol]?: boolean;
+  get uniffiTypeName(): string;
+  get uniffiHandle(): unknown;
+  uniffiDestroy(): boolean;
+  dispose(): boolean;
+}
+
+export declare class UniffiObjectFactory<T extends object = UniffiObjectBase> {
+  readonly typeName: string;
+  constructor(options?: UniffiObjectFactoryOptions<T>);
+  attach(instance: T, handle: unknown): T;
+  bless(instance: T, handle: unknown): T;
+  create(handle: unknown): T;
+  createGenericAbi(handle: unknown): T;
+  createRawExternal(handle: unknown): T;
+  handle(value: T): unknown;
+  peekHandle(value: unknown): unknown;
+  cloneHandle(value: T): unknown;
+  destroy(value: unknown): boolean;
+  isInstance(value: unknown): value is T;
+  isDestroyed(value: unknown): boolean;
+  usesRawExternal(value: unknown): boolean;
+  serializeHandle(value: T): bigint;
+  deserializeHandle(serialized: bigint | number): unknown;
+}
+
+export declare class FfiConverterObject<T extends object = UniffiObjectBase> {
+  readonly factory: UniffiObjectFactory<T>;
+  constructor(factory: UniffiObjectFactory<T>);
+  lower(value: T): bigint;
+  lift(handle: bigint | number): T;
+  write(value: T, writer: ByteWriter): void;
+  read(reader: ByteReader): T;
+  allocationSize(value?: T): 8;
+}
+
+export declare function createObjectFactory<T extends object = UniffiObjectBase>(
+  options?: UniffiObjectFactoryOptions<T>,
+): UniffiObjectFactory<T>;
+export declare function createObjectConverter<T extends object = UniffiObjectBase>(
+  factory: UniffiObjectFactory<T>,
+): FfiConverterObject<T>;

package/runtime/objects.js

@@ -0,0 +1,469 @@
+import koffi from "koffi";
+import { UnexpectedNullPointer } from "./errors.js";
+import { isNullPointer, normalizeUInt64, pointerAddress } from "./ffi-types.js";
+
+const uniffiFinalizerTokenSymbol = Symbol("uniffi.finalizerToken");
+const uniffiObjectGenericAbiSymbol = Symbol("uniffi.objectGenericAbi");
+const uniffiObjectRawExternalSymbol = Symbol("uniffi.objectRawExternal");
+
+export const uniffiTypeNameSymbol = Symbol("uniffi.typeName");
+export const uniffiObjectFactorySymbol = Symbol("uniffi.objectFactory");
+export const uniffiObjectHandleSymbol = Symbol("uniffi.objectHandle");
+export const uniffiObjectDestroyedSymbol = Symbol("uniffi.objectDestroyed");
+export const UNIFFI_OBJECT_HANDLE_SIZE = 8;
+
+function requireObjectInstance(value, label = "UniFFI object") {
+  if (typeof value !== "object" || value == null) {
+    throw new TypeError(`${label} instances must be non-null objects.`);
+  }
+  return value;
+}
+
+function requireHandle(handle, label = "UniFFI handle") {
+  if (handle == null || isNullPointer(handle)) {
+    throw new UnexpectedNullPointer(`${label} is null or has already been destroyed.`);
+  }
+  return handle;
+}
+
+function storedHandle(value) {
+  const handle = value?.[uniffiObjectHandleSymbol];
+  if (handle == null || isNullPointer(handle)) {
+    return undefined;
+  }
+  return handle;
+}
+
+function objectFactory(value) {
+  const factory = value?.[uniffiObjectFactorySymbol];
+  if (
+    factory == null
+    || typeof factory.create !== "function"
+    || typeof factory.destroy !== "function"
+    || typeof factory.handle !== "function"
+  ) {
+    return undefined;
+  }
+  return factory;
+}
+
+function resolveHandleType(handleType) {
+  return typeof handleType === "function"
+    ? handleType()
+    : handleType;
+}
+
+export class UniffiObjectBase {
+  get uniffiTypeName() {
+    return this[uniffiTypeNameSymbol] ?? this.constructor?.name ?? "UniFFI object";
+  }
+
+  get uniffiHandle() {
+    const factory = objectFactory(this);
+    if (factory == null) {
+      throw new TypeError(`${this.uniffiTypeName} is not attached to a UniFFI object factory.`);
+    }
+    return factory.handle(this);
+  }
+
+  uniffiDestroy() {
+    const factory = objectFactory(this);
+    if (factory == null) {
+      return false;
+    }
+    return factory.destroy(this);
+  }
+
+  dispose() {
+    return this.uniffiDestroy();
+  }
+}
+
+export class UniffiObjectFactory {
+  constructor({
+    typeName = "UniFFI object",
+    createInstance = () => Object.create(UniffiObjectBase.prototype),
+    cloneFreeUsesUniffiHandle = false,
+    cloneHandle = undefined,
+    cloneHandleGeneric = undefined,
+    cloneHandleRawExternal = undefined,
+    freeHandle = undefined,
+    freeHandleGeneric = undefined,
+    freeHandleRawExternal = undefined,
+    handleType = undefined,
+    serializeHandle = undefined,
+    deserializeHandle = undefined,
+  } = {}) {
+    this.typeName = typeName;
+    this._createInstance = createInstance;
+    this._cloneFreeUsesUniffiHandle = cloneFreeUsesUniffiHandle === true;
+    this._cloneHandle = cloneHandle;
+    this._cloneHandleGeneric = cloneHandleGeneric;
+    this._cloneHandleRawExternal = cloneHandleRawExternal;
+    this._freeHandle = freeHandle;
+    this._freeHandleGeneric = freeHandleGeneric;
+    this._freeHandleRawExternal = freeHandleRawExternal;
+    this._handleType = handleType;
+    this._serializeHandle = serializeHandle;
+    this._deserializeHandle = deserializeHandle;
+    this._registry =
+      typeof FinalizationRegistry === "undefined"
+      || (
+        typeof freeHandle !== "function"
+        && typeof freeHandleGeneric !== "function"
+        && typeof freeHandleRawExternal !== "function"
+      )
+        ? null
+        : new FinalizationRegistry((record) => {
+            try {
+              const useRawExternal =
+                record.rawExternal === true
+                && typeof this._freeHandleRawExternal === "function";
+              const freeHandle =
+                record.genericAbi === true
+                  ? this._freeHandleGeneric
+                  : useRawExternal
+                    ? this._freeHandleRawExternal
+                  : this._freeHandle;
+              if (typeof freeHandle === "function") {
+                freeHandle(this._cloneFreeHandle(record.handle, {
+                  genericAbi: record.genericAbi === true,
+                  rawExternal: useRawExternal,
+                }));
+              }
+            } catch {
+              // Finalizers must not surface user-visible errors.
+            }
+          });
+  }
+
+  _unregisterFinalizer(instance) {
+    const token = instance[uniffiFinalizerTokenSymbol];
+    if (this._registry != null && token != null) {
+      this._registry.unregister(token);
+    }
+    instance[uniffiFinalizerTokenSymbol] = null;
+  }
+
+  _registerFinalizer(instance, handle) {
+    if (this._registry == null) {
+      instance[uniffiFinalizerTokenSymbol] = null;
+      return;
+    }
+
+    const token = {};
+    instance[uniffiFinalizerTokenSymbol] = token;
+    this._registry.register(instance, handle, token);
+  }
+
+  _markDestroyed(instance) {
+    instance[uniffiObjectHandleSymbol] = null;
+    instance[uniffiObjectDestroyedSymbol] = true;
+    instance[uniffiFinalizerTokenSymbol] = null;
+    instance[uniffiObjectGenericAbiSymbol] = false;
+    instance[uniffiObjectRawExternalSymbol] = false;
+  }
+
+  _normalizeHandle(handle) {
+    if (handle == null) {
+      return handle;
+    }
+
+    if (typeof handle === "bigint" || typeof handle === "number") {
+      return normalizeUInt64(handle);
+    }
+    return handle;
+  }
+
+  _coerceHandle(handle) {
+    if (handle == null) {
+      return handle;
+    }
+
+    const handleType = resolveHandleType(this._handleType);
+    if (handleType == null) {
+      return this._normalizeHandle(handle);
+    }
+
+    const normalizedHandle = this._normalizeHandle(handle);
+    if (typeof normalizedHandle === "bigint" || typeof normalizedHandle === "number") {
+      return koffi.decode(new BigUint64Array([normalizeUInt64(normalizedHandle)]), handleType);
+    }
+    return koffi.as(normalizedHandle, handleType);
+  }
+
+  _cloneFreeHandle(handle, { genericAbi = false, rawExternal = false } = {}) {
+    if (handle == null) {
+      return handle;
+    }
+
+    if (genericAbi || rawExternal || this._cloneFreeUsesUniffiHandle) {
+      return this._normalizeHandle(handle);
+    }
+
+    return this._coerceHandle(handle);
+  }
+
+  attach(instance, handle, options = undefined) {
+    const normalizedHandle = requireHandle(
+      this._normalizeHandle(handle),
+      `${this.typeName} handle`,
+    );
+    const genericAbi = options?.genericAbi === true;
+    const rawExternal = options?.rawExternal === true;
+    const target = requireObjectInstance(instance, this.typeName);
+
+    if (storedHandle(target) != null && target[uniffiObjectDestroyedSymbol] !== true) {
+      throw new TypeError(`${this.typeName} is already bound to a live UniFFI handle.`);
+    }
+
+    Object.defineProperties(target, {
+      [uniffiTypeNameSymbol]: {
+        configurable: true,
+        value: this.typeName,
+        writable: true,
+      },
+      [uniffiObjectFactorySymbol]: {
+        configurable: true,
+        value: this,
+      },
+      [uniffiObjectHandleSymbol]: {
+        configurable: true,
+        value: normalizedHandle,
+        writable: true,
+      },
+      [uniffiObjectDestroyedSymbol]: {
+        configurable: true,
+        value: false,
+        writable: true,
+      },
+      [uniffiObjectGenericAbiSymbol]: {
+        configurable: true,
+        value: genericAbi,
+        writable: true,
+      },
+      [uniffiObjectRawExternalSymbol]: {
+        configurable: true,
+        value: rawExternal,
+        writable: true,
+      },
+      [uniffiFinalizerTokenSymbol]: {
+        configurable: true,
+        value: null,
+        writable: true,
+      },
+    });
+
+    this._registerFinalizer(target, {
+      genericAbi,
+      rawExternal,
+      handle: normalizedHandle,
+    });
+    return target;
+  }
+
+  bless(instance, handle) {
+    return this.attach(instance, handle);
+  }
+
+  create(handle) {
+    return this.attach(this._createInstance(), handle);
+  }
+
+  createGenericAbi(handle) {
+    return this.attach(this._createInstance(), handle, {
+      genericAbi: true,
+    });
+  }
+
+  createRawExternal(handle) {
+    const rawHandle = requireHandle(
+      this._normalizeHandle(handle),
+      `${this.typeName} handle`,
+    );
+    const adoptedHandle =
+      typeof this._cloneHandleRawExternal === "function"
+        ? requireHandle(
+            this._cloneHandleRawExternal(rawHandle),
+            `${this.typeName} adopted handle`,
+          )
+        : rawHandle;
+    if (
+      adoptedHandle !== rawHandle
+      && typeof this._freeHandleRawExternal === "function"
+    ) {
+      this._freeHandleRawExternal(rawHandle);
+    }
+    return this.attach(this._createInstance(), adoptedHandle, {
+      rawExternal: true,
+    });
+  }
+
+  handle(value) {
+    if (!this.isInstance(value)) {
+      throw new TypeError(`${this.typeName} expected an instance created by this factory.`);
+    }
+    const rawHandle = requireHandle(
+      this._normalizeHandle(storedHandle(value)),
+      `${this.typeName} handle`,
+    );
+    return this.usesGenericAbi(value)
+      ? rawHandle
+      : this._coerceHandle(rawHandle);
+  }
+
+  peekHandle(value) {
+    if (!this.isInstance(value) || this.isDestroyed(value)) {
+      return undefined;
+    }
+    return storedHandle(value);
+  }
+
+  cloneHandle(value) {
+    const rawHandle = requireHandle(
+      this._normalizeHandle(storedHandle(value)),
+      `${this.typeName} handle`,
+    );
+    const genericAbi = this.usesGenericAbi(value);
+    const useRawExternal =
+      this.usesRawExternal(value)
+      && typeof this._cloneHandleRawExternal === "function";
+    const handle = this._cloneFreeHandle(rawHandle, {
+      genericAbi,
+      rawExternal: useRawExternal,
+    });
+    const cloneHandle =
+      genericAbi
+        ? this._cloneHandleGeneric
+        : useRawExternal
+          ? this._cloneHandleRawExternal
+        : this._cloneHandle;
+    if (typeof cloneHandle !== "function") {
+      return handle;
+    }
+    const clonedHandle = requireHandle(
+      cloneHandle(handle, value),
+      `${this.typeName} cloned handle`,
+    );
+    if (genericAbi) {
+      return clonedHandle;
+    }
+
+    if (useRawExternal) {
+      return this._cloneFreeUsesUniffiHandle
+        ? pointerAddress(clonedHandle)
+        : this._coerceHandle(clonedHandle);
+    }
+
+    return clonedHandle;
+  }
+
+  destroy(value) {
+    if (!this.isInstance(value) || this.isDestroyed(value)) {
+      return false;
+    }
+
+    const rawHandle = requireHandle(
+      this._normalizeHandle(storedHandle(value)),
+      `${this.typeName} handle`,
+    );
+    const genericAbi = this.usesGenericAbi(value);
+    const useRawExternal =
+      this.usesRawExternal(value)
+      && typeof this._freeHandleRawExternal === "function";
+    const handle = this._cloneFreeHandle(rawHandle, {
+      genericAbi,
+      rawExternal: useRawExternal,
+    });
+
+    const freeHandle =
+      genericAbi
+        ? this._freeHandleGeneric
+        : useRawExternal
+          ? this._freeHandleRawExternal
+        : this._freeHandle;
+    if (typeof freeHandle === "function") {
+      freeHandle(handle, value);
+    }
+    this._unregisterFinalizer(value);
+    this._markDestroyed(value);
+    return true;
+  }
+
+  isInstance(value) {
+    return objectFactory(value) === this;
+  }
+
+  isDestroyed(value) {
+    return this.isInstance(value)
+      && (value[uniffiObjectDestroyedSymbol] === true || storedHandle(value) == null);
+  }
+
+  usesGenericAbi(value) {
+    return this.isInstance(value) && value[uniffiObjectGenericAbiSymbol] === true;
+  }
+
+  usesRawExternal(value) {
+    return this.isInstance(value) && value[uniffiObjectRawExternalSymbol] === true;
+  }
+
+  serializeHandle(value) {
+    const rawHandle = requireHandle(
+      this._normalizeHandle(storedHandle(value)),
+      `${this.typeName} handle`,
+    );
+    if (typeof this._serializeHandle === "function") {
+      return normalizeUInt64(this._serializeHandle(this.handle(value), value));
+    }
+    return pointerAddress(rawHandle);
+  }
+
+  deserializeHandle(serialized) {
+    const normalizedHandle = normalizeUInt64(serialized);
+    if (typeof this._deserializeHandle === "function") {
+      return requireHandle(
+        this._normalizeHandle(this._deserializeHandle(normalizedHandle)),
+        `${this.typeName} handle`,
+      );
+    }
+    return requireHandle(
+      this._normalizeHandle(normalizedHandle),
+      `${this.typeName} handle`,
+    );
+  }
+}
+
+export class FfiConverterObject {
+  constructor(factory) {
+    this.factory = factory;
+  }
+
+  lower(value) {
+    return this.factory.cloneHandle(value);
+  }
+
+  lift(handle) {
+    return this.factory.create(handle);
+  }
+
+  write(value, writer) {
+    writer.writeUInt64(this.factory.serializeHandle(value));
+  }
+
+  read(reader) {
+    const handle = this.factory.deserializeHandle(reader.readUInt64());
+    return this.factory.createGenericAbi(handle);
+  }
+
+  allocationSize() {
+    return UNIFFI_OBJECT_HANDLE_SIZE;
+  }
+}
+
+export function createObjectFactory(options = undefined) {
+  return new UniffiObjectFactory(options);
+}
+
+export function createObjectConverter(factory) {
+  return new FfiConverterObject(factory);
+}