relaxnative 0.1.0-beta.1

package/dist/chunk-VKQIXLNL.js

@@ -0,0 +1,273 @@
+// src/memory/memoryTypes.ts
+var MemoryError = class extends Error {
+  name = "MemoryError";
+};
+var UseAfterFreeError = class extends MemoryError {
+  name = "UseAfterFreeError";
+};
+var InvalidFreeError = class extends MemoryError {
+  name = "InvalidFreeError";
+};
+var NullPointerError = class extends MemoryError {
+  name = "NullPointerError";
+};
+
+// src/memory/NativeBuffer.ts
+import koffi from "koffi";
+var kBrand = /* @__PURE__ */ Symbol.for("relaxnative.NativeBuffer");
+var finalizer = typeof FinalizationRegistry !== "undefined" ? new FinalizationRegistry((held) => {
+  try {
+    koffi.free(held.handle);
+  } catch {
+  }
+}) : null;
+var NativeBuffer = class {
+  [kBrand] = true;
+  _handle;
+  _view;
+  _freed = false;
+  ownership;
+  constructor(allocation, opts) {
+    if (!allocation?.handle || !allocation?.view) {
+      throw new NullPointerError("NativeBuffer: missing allocation");
+    }
+    this._handle = allocation.handle;
+    this._view = allocation.view;
+    this.ownership = opts?.ownership ?? "js";
+    if (opts?.autoFree && this.ownership === "js") {
+      finalizer?.register(
+        this,
+        { handle: this._handle, addr: this.address },
+        this
+      );
+    }
+  }
+  get address() {
+    this.assertAlive();
+    const raw = koffi.address(this._handle);
+    const addr = typeof raw === "bigint" ? Number(raw) : raw;
+    if (!Number.isFinite(addr) || addr === 0) {
+      throw new NullPointerError(`NativeBuffer has null/invalid address: ${addr}`);
+    }
+    return addr;
+  }
+  get size() {
+    this.assertAlive();
+    return this._view.byteLength;
+  }
+  get freed() {
+    return this._freed;
+  }
+  assertAlive() {
+    if (this._freed) {
+      throw new UseAfterFreeError("Use-after-free: NativeBuffer was freed");
+    }
+  }
+  toUint8Array() {
+    this.assertAlive();
+    return this._view;
+  }
+  write(src, offset = 0) {
+    this.assertAlive();
+    if (!(src instanceof Uint8Array)) {
+      throw new TypeError("NativeBuffer.write(src): src must be a Uint8Array");
+    }
+    if (!Number.isInteger(offset) || offset < 0) {
+      throw new RangeError(`NativeBuffer.write: offset must be >= 0, got ${offset}`);
+    }
+    if (offset + src.byteLength > this._view.byteLength) {
+      throw new RangeError(
+        `NativeBuffer.write: write out of bounds (offset=${offset}, len=${src.byteLength}, size=${this._view.byteLength})`
+      );
+    }
+    this._view.set(src, offset);
+  }
+  free() {
+    if (this._freed) {
+      throw new InvalidFreeError("Double-free: NativeBuffer already freed");
+    }
+    if (this.ownership !== "js") {
+      throw new InvalidFreeError(
+        "Invalid free: NativeBuffer is native-owned"
+      );
+    }
+    finalizer?.unregister(this);
+    koffi.free(this._handle);
+    this._freed = true;
+  }
+  toJSON() {
+    return { address: this.address, size: this.size, ownership: this.ownership };
+  }
+  static isNativeBuffer(v) {
+    return !!v && v[kBrand] === true;
+  }
+  /**
+   * Return the koffi allocation handle.
+   *
+   * Important: passing raw numeric addresses to koffi is not reliably supported
+   * across platforms/Node versions and can segfault. The handle returned by
+   * `koffi.alloc()` is the safe thing to pass back into FFI calls.
+   */
+  toKoffiPointer() {
+    this.assertAlive();
+    return this._handle;
+  }
+};
+
+// src/memory/NativePointer.ts
+import koffi2 from "koffi";
+var kBrand2 = /* @__PURE__ */ Symbol.for("relaxnative.NativePointer");
+var NativePointer = class {
+  [kBrand2] = true;
+  /** Opaque native address (number). */
+  address;
+  /** Size in bytes when known (0 means unknown). */
+  size;
+  /** Ownership of the pointee memory. */
+  ownership;
+  _freed = false;
+  constructor(opts) {
+    const address = opts.address;
+    if (!Number.isFinite(address) || address === 0) {
+      throw new NullPointerError(`Null/invalid native pointer address: ${address}`);
+    }
+    this.address = address;
+    this.size = opts.size ?? 0;
+    this.ownership = opts.ownership ?? "native";
+  }
+  get freed() {
+    return this._freed;
+  }
+  /**
+   * Marks this pointer as freed (used internally by NativeBuffer).
+   * This does *not* free underlying memory.
+   */
+  _markFreed() {
+    this._freed = true;
+  }
+  assertAlive() {
+    if (this._freed) {
+      throw new UseAfterFreeError(
+        `Use-after-free: pointer 0x${this.address.toString(16)} was freed`
+      );
+    }
+  }
+  /**
+   * Convert to the koffi pointer value.
+   *
+  * Note: numeric-address pointers are inherently less safe than passing a
+  * koffi External handle (like NativeBuffer does). Use NativePointer for
+  * borrowed/opaque pointers returned by native code.
+   */
+  toKoffiPointer() {
+    this.assertAlive();
+    return this.address;
+  }
+  static isNativePointer(v) {
+    return !!v && v[kBrand2] === true;
+  }
+  /**
+   * Convenience for koffi type declarations.
+   * Example: lib.func('foo', 'int', [NativePointer.koffiType()])
+   */
+  static koffiType() {
+    return koffi2.pointer("void");
+  }
+};
+
+// src/ffi/typeMap.ts
+import koffi3 from "koffi";
+function mapType(type) {
+  if (type == null) {
+    throw new Error("Unsupported native type: <undefined>");
+  }
+  if (/^pointer\s*<.+>$/i.test(type)) {
+    return koffi3.pointer("void");
+  }
+  switch (type) {
+    case "int":
+      return koffi3.types.int;
+    case "long":
+      return koffi3.types.int64;
+    case "float":
+      return koffi3.types.float;
+    case "double":
+      return koffi3.types.double;
+    case "char*":
+      return koffi3.types.cstring;
+    case "void":
+      return koffi3.types.void;
+    case "pointer":
+      return koffi3.pointer("void");
+    case "buffer":
+      return koffi3.pointer("void");
+    default:
+      throw new Error(`Unsupported native type: ${type}`);
+  }
+}
+
+// src/ffi/bindFunctions.ts
+function bindFunctions(lib, bindings) {
+  const exports = {};
+  const functions = Array.isArray(bindings.functions) ? bindings.functions : Object.values(bindings.functions);
+  for (const fn of functions) {
+    if (!fn?.name || !fn?.returns || !Array.isArray(fn?.args)) {
+      throw new Error(
+        `Invalid FFI binding entry: ${JSON.stringify(fn)}. Expected {name, returns, args[]}.`
+      );
+    }
+    const returns = mapType(fn.returns);
+    const args = fn.args.map(mapType);
+    if (process.env.RELAXNATIVE_DEBUG_FFI === "1") {
+      console.log("[relaxnative ffi] bind", fn.name, { returns: fn.returns, args: fn.args });
+    }
+    const raw = lib.func(
+      fn.name,
+      returns,
+      args
+    );
+    exports[fn.name] = (...args2) => {
+      const mapped = args2.map((a) => {
+        if (NativeBuffer.isNativeBuffer(a)) return a.toKoffiPointer();
+        if (NativePointer.isNativePointer(a)) return a.toKoffiPointer();
+        if (a instanceof Uint8Array) return a;
+        return a;
+      });
+      const out = raw(...mapped);
+      if (fn.returns === "pointer" || /^pointer\s*<.+>$/i.test(fn.returns)) {
+        if (out == null) return out;
+        const rawAddr = out;
+        const addr = typeof rawAddr === "bigint" ? Number(rawAddr) : rawAddr;
+        return new NativePointer({ address: addr, ownership: "borrowed" });
+      }
+      return out;
+    };
+  }
+  return exports;
+}
+
+// src/ffi/createLibrary.ts
+import koffi4 from "koffi";
+function loadLibrary(libPath) {
+  try {
+    return koffi4.load(libPath);
+  } catch (err) {
+    throw new Error(`Failed to load native library: ${libPath}`);
+  }
+}
+
+// src/ffi/index.ts
+function loadFfi(libPath, bindings) {
+  const lib = loadLibrary(libPath);
+  return bindFunctions(lib, bindings);
+}
+
+export {
+  MemoryError,
+  UseAfterFreeError,
+  InvalidFreeError,
+  NullPointerError,
+  NativeBuffer,
+  NativePointer,
+  loadFfi
+};