relaxnative 0.1.5 → 0.1.6

package/dist/chunk-DLPCZKK2.js

@@ -0,0 +1,506 @@
+// 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;
+  }
+  /**
+   * Create a bounds-checked DataView into this buffer.
+   *
+   * Tip: prefer the typed view helpers (u32(), f64(), etc.) when possible.
+   */
+  dataView(offset = 0, length) {
+    this.assertAlive();
+    if (!Number.isInteger(offset) || offset < 0) {
+      throw new RangeError(`NativeBuffer.dataView: offset must be >= 0, got ${offset}`);
+    }
+    const size = this._view.byteLength;
+    const len = length == null ? size - offset : length;
+    if (!Number.isInteger(len) || len < 0) {
+      throw new RangeError(`NativeBuffer.dataView: length must be >= 0, got ${len}`);
+    }
+    if (offset + len > size) {
+      throw new RangeError(
+        `NativeBuffer.dataView: out of bounds (offset=${offset}, length=${len}, size=${size})`
+      );
+    }
+    return new DataView(this._view.buffer, this._view.byteOffset + offset, len);
+  }
+  _typed(ctor, offset, length) {
+    this.assertAlive();
+    if (!Number.isInteger(offset) || offset < 0) {
+      throw new RangeError(`NativeBuffer view: offset must be >= 0, got ${offset}`);
+    }
+    const bpe = ctor.BYTES_PER_ELEMENT;
+    if (offset % bpe !== 0) {
+      throw new RangeError(`NativeBuffer view: offset must be aligned to ${bpe} bytes`);
+    }
+    const bytesAvail = this._view.byteLength - offset;
+    if (bytesAvail < 0) {
+      throw new RangeError("NativeBuffer view: offset out of bounds");
+    }
+    const maxLen = Math.floor(bytesAvail / bpe);
+    const len = length == null ? maxLen : length;
+    if (!Number.isInteger(len) || len < 0) {
+      throw new RangeError(`NativeBuffer view: length must be >= 0, got ${len}`);
+    }
+    if (len > maxLen) {
+      throw new RangeError(
+        `NativeBuffer view: out of bounds (offset=${offset}, length=${len}, elementSize=${bpe}, maxLength=${maxLen})`
+      );
+    }
+    return new ctor(this._view.buffer, this._view.byteOffset + offset, len);
+  }
+  u8(offset = 0, length) {
+    return this._typed(Uint8Array, offset, length);
+  }
+  i8(offset = 0, length) {
+    return this._typed(Int8Array, offset, length);
+  }
+  u16(offset = 0, length) {
+    return this._typed(Uint16Array, offset, length);
+  }
+  i16(offset = 0, length) {
+    return this._typed(Int16Array, offset, length);
+  }
+  u32(offset = 0, length) {
+    return this._typed(Uint32Array, offset, length);
+  }
+  i32(offset = 0, length) {
+    return this._typed(Int32Array, offset, length);
+  }
+  f32(offset = 0, length) {
+    return this._typed(Float32Array, offset, length);
+  }
+  f64(offset = 0, length) {
+    return this._typed(Float64Array, offset, length);
+  }
+  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/memory/nativeMemory.ts
+import koffi3 from "koffi";
+function allocRaw(size) {
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new TypeError(`native.alloc(size): size must be a positive integer, got ${size}`);
+  }
+  const handle = koffi3.alloc("char", size);
+  const ab = koffi3.view(handle, size);
+  const view = new Uint8Array(ab);
+  return { handle, view };
+}
+function freeRaw(ptr) {
+  koffi3.free(ptr);
+}
+
+// src/ffi/bindFunctions.ts
+import koffi5 from "koffi";
+
+// src/ffi/typeMap.ts
+import koffi4 from "koffi";
+function mapType(type) {
+  if (type == null) {
+    throw new Error("Unsupported native type: <undefined>");
+  }
+  const cstringType = koffi4.types.cstring ?? koffi4.cstring ?? // Fallback: some koffi builds don't expose cstring; treat it as char*.
+  // This is good enough for reading NUL-terminated strings.
+  (koffi4.pointer ? koffi4.pointer("char") : void 0);
+  if (/^pointer\s*<.+>$/i.test(type)) {
+    const inner = type.replace(/^pointer\s*<\s*/i, "").replace(/\s*>\s*$/i, "").trim();
+    if (/^pointer\s*<\s*pointer\s*<.+>\s*>\s*$/i.test(inner)) {
+      return koffi4.pointer(koffi4.pointer("void"));
+    }
+    switch (inner) {
+      case "uint8_t":
+        return koffi4.pointer(koffi4.types.uint8 ?? koffi4.types.uchar);
+      case "int8_t":
+        return koffi4.pointer(koffi4.types.int8 ?? koffi4.types.char);
+      case "uint16_t":
+        return koffi4.pointer(koffi4.types.uint16 ?? koffi4.types.ushort);
+      case "int16_t":
+        return koffi4.pointer(koffi4.types.int16 ?? koffi4.types.short);
+      case "int32_t":
+        return koffi4.pointer(koffi4.types.int32 ?? koffi4.types.int);
+      case "uint32_t":
+        return koffi4.pointer(
+          koffi4.types.uint32 ?? koffi4.types.uint
+        );
+      case "int64_t":
+        return koffi4.pointer(koffi4.types.int64 ?? koffi4.types.int64);
+      case "uint64_t":
+        return koffi4.pointer(koffi4.types.uint64 ?? koffi4.types.ulonglong);
+      case "int":
+        return koffi4.pointer(koffi4.types.int);
+      case "double":
+        return koffi4.pointer(koffi4.types.double);
+      case "float":
+        return koffi4.pointer(koffi4.types.float);
+      default:
+        return koffi4.pointer("void");
+    }
+  }
+  switch (type) {
+    case "int":
+      return koffi4.types.int;
+    case "uint":
+      return koffi4.types.uint;
+    case "uint32_t":
+      return koffi4.types.uint32 ?? koffi4.types.uint;
+    case "int32_t":
+      return koffi4.types.int32 ?? koffi4.types.int;
+    case "uint8_t":
+      return koffi4.types.uint8 ?? koffi4.types.uchar;
+    case "int8_t":
+      return koffi4.types.int8 ?? koffi4.types.char;
+    case "uint16_t":
+      return koffi4.types.uint16 ?? koffi4.types.ushort;
+    case "int16_t":
+      return koffi4.types.int16 ?? koffi4.types.short;
+    case "uint64_t":
+      return koffi4.types.uint64 ?? koffi4.types.ulonglong;
+    case "int64_t":
+      return koffi4.types.int64 ?? koffi4.types.int64;
+    case "long":
+      return koffi4.types.int64;
+    case "size_t":
+      return koffi4.types.size_t ?? koffi4.types.uint64;
+    case "float":
+      return koffi4.types.float;
+    case "double":
+      return koffi4.types.double;
+    case "char*":
+      return cstringType;
+    case "cstring":
+      return cstringType;
+    case "void":
+      return koffi4.types.void;
+    case "pointer":
+      return koffi4.pointer(koffi4.types.int);
+    case "buffer":
+      return koffi4.pointer("void");
+    default:
+      throw new Error(`Unsupported native type: ${type}`);
+  }
+}
+
+// src/ffi/bindFunctions.ts
+function isSerializedNativeBuffer(v) {
+  return !!v && typeof v === "object" && typeof v.address === "number" && typeof v.size === "number" && v.size >= 0;
+}
+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 (!returns) {
+      throw new Error(
+        `FFI type mapping returned undefined for return type ${JSON.stringify(fn.returns)} (fn=${fn.name})`
+      );
+    }
+    for (let i = 0; i < args.length; i++) {
+      if (!args[i]) {
+        throw new Error(
+          `FFI type mapping returned undefined for arg[${i}] type ${JSON.stringify(fn.args[i])} (fn=${fn.name})`
+        );
+      }
+    }
+    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 tmpPointerTables = [];
+      const mapped = args2.map((a, i) => {
+        const spec = fn.args[i];
+        if (typeof spec === "string" && /^pointer\s*<\s*pointer\s*<.+>\s*>\s*$/i.test(spec)) {
+          if (!Array.isArray(a)) {
+            return a;
+          }
+          const rowPtrs = a.map((row) => {
+            if (NativeBuffer.isNativeBuffer(row)) return row.toKoffiPointer();
+            if (NativePointer.isNativePointer(row)) return row.toKoffiPointer();
+            if (isSerializedNativeBuffer(row)) {
+              const tmp = allocRaw(row.size);
+              tmpPointerTables.push(tmp);
+              return tmp.handle;
+            }
+            if (ArrayBuffer.isView(row) || Array.isArray(row)) {
+              throw new TypeError(
+                `Unsupported row value for ${fn.name} arg[${i}] (pointer-to-pointer): row must be a NativeBuffer or NativePointer. TypedArray/number[] rows don't expose a stable native address for building a T** table. Use native.alloc() per row and pass the row buffers instead.`
+              );
+            }
+            throw new TypeError(
+              `Unsupported row value for ${fn.name} arg[${i}] (pointer-to-pointer): expected NativeBuffer|NativePointer`
+            );
+          });
+          const ptrSize = process.arch.includes("64") ? 8 : 4;
+          const table = allocRaw(rowPtrs.length * ptrSize);
+          const dv = new DataView(table.view.buffer, table.view.byteOffset, table.view.byteLength);
+          for (let r = 0; r < rowPtrs.length; r++) {
+            const off = r * ptrSize;
+            const rawPtr = rowPtrs[r];
+            const addrRaw = koffi5.address(rawPtr);
+            const addr = typeof addrRaw === "bigint" ? Number(addrRaw) : addrRaw;
+            if (!Number.isFinite(addr) || addr === 0) {
+              throw new TypeError(
+                `Failed to take address of row[${r}] for ${fn.name} arg[${i}] (pointer-to-pointer)`
+              );
+            }
+            if (ptrSize === 8) dv.setBigUint64(off, BigInt(addr), true);
+            else dv.setUint32(off, addr >>> 0, true);
+          }
+          tmpPointerTables.push(table);
+          return table.handle;
+        }
+        if (Array.isArray(a) && typeof spec === "string") {
+          const isPtr = /^pointer\s*<.+>$/i.test(spec);
+          if (isPtr) {
+            const inner = spec.replace(/^pointer\s*<\s*/i, "").replace(/\s*>\s*$/i, "").trim();
+            switch (inner) {
+              case "int":
+              case "int32_t":
+                return Int32Array.from(a);
+              case "uint32_t":
+                return Uint32Array.from(a);
+              case "uint8_t":
+                return Uint8Array.from(a);
+              case "int8_t":
+                return Int8Array.from(a);
+              case "uint16_t":
+                return Uint16Array.from(a);
+              case "int16_t":
+                return Int16Array.from(a);
+              case "float":
+                return Float32Array.from(a);
+              case "double":
+                return Float64Array.from(a);
+              default:
+                break;
+            }
+          }
+        }
+        if (NativeBuffer.isNativeBuffer(a)) return a.toKoffiPointer();
+        if (NativePointer.isNativePointer(a)) return a.toKoffiPointer();
+        if (ArrayBuffer.isView(a)) return a;
+        return a;
+      });
+      const out = raw(...mapped);
+      for (const t of tmpPointerTables) {
+        try {
+          koffi5.free(t.handle);
+        } catch {
+        }
+      }
+      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 koffi6 from "koffi";
+function loadLibrary(libPath) {
+  try {
+    return koffi6.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,
+  allocRaw,
+  freeRaw,
+  loadFfi
+};