ffi: support Bun and Node.js backends (#6)

Load bun:ffi or node:ffi at startup so the same packed structs work
under both runtimes. Pointers flow through a Pointer = number |
bigint type so callers stay agnostic to the runtime: Bun returns
number, Node returns bigint.

Retain every packed pointer target in a WeakMap keyed by the owning
buffer. Otherwise the GC may free strings, nested buffers, and
array storage while the parent struct still holds raw pointers,
producing use-after-free when the struct is passed to native code.

Author: simonklee

README.md

@@ -1,6 +1,6 @@
 # bun-ffi-structs
 
-TypeScript FFI struct library for Bun. Define and pack/unpack C-style structs with memory layout control for FFI calls.
+TypeScript struct-packing library for Bun and Node.js `node:ffi` workflows. Define and pack/unpack C-style structs with memory layout control for FFI calls.
 
 ## Features
 
@@ -22,6 +22,8 @@ TypeScript FFI struct library for Bun. Define and pack/unpack C-style structs wi
 bun install bun-ffi-structs
 ```
 
+Using the package on Node.js currently requires `node:ffi` support to be enabled, for example with `--experimental-ffi --allow-ffi` on supported builds.
+
 For local development, use `scripts/link-dev.sh <target-project-root>` to symlink this package into another project's node_modules.
 
 ## Usage

src/ffi.ts

@@ -0,0 +1,77 @@
+import type { Pointer } from "./types.js"
+
+interface FfiBackend {
+  ptr(value: ArrayBufferLike | ArrayBufferView): Pointer
+  toArrayBuffer(pointer: Pointer, offset: number | undefined, length: number): ArrayBuffer
+}
+
+interface BunFfiModule {
+  ptr(value: ArrayBufferLike | ArrayBufferView): number
+  toArrayBuffer(pointer: number, offset: number | undefined, length: number): ArrayBuffer
+}
+
+interface NodeFfiModule {
+  getRawPointer(source: ArrayBuffer): bigint
+  toArrayBuffer(pointer: bigint, length: number, copy?: boolean): ArrayBuffer
+}
+
+const FFI_LOAD_ERROR = "bun-ffi-structs requires Bun or Node.js with node:ffi enabled (--experimental-ffi --allow-ffi)."
+
+const backend = await loadBackend()
+
+async function loadBackend(): Promise<FfiBackend> {
+  if (typeof process !== "undefined" && "bun" in process.versions) {
+    return createBunBackend(await importModule<BunFfiModule>("bun:ffi"))
+  }
+
+  try {
+    return createNodeBackend(await importModule<NodeFfiModule>("node:ffi"))
+  } catch (error) {
+    throw new Error(FFI_LOAD_ERROR, {
+      cause: error instanceof Error ? error : undefined,
+    })
+  }
+}
+
+function importModule<T>(specifier: string): Promise<T> {
+  return import(specifier).then((module) => (module as { default?: T }).default ?? (module as T))
+}
+
+function createBunBackend(bun: BunFfiModule): FfiBackend {
+  return {
+    ptr: bun.ptr,
+    toArrayBuffer(pointer, offset, length) {
+      return bun.toArrayBuffer(toBunPointer(pointer), offset, length)
+    },
+  }
+}
+
+function createNodeBackend(nodeFfi: NodeFfiModule): FfiBackend {
+  return {
+    ptr(value) {
+      if (ArrayBuffer.isView(value)) {
+        return nodeFfi.getRawPointer(value.buffer as ArrayBuffer) + BigInt(value.byteOffset)
+      }
+
+      if (value instanceof ArrayBuffer) {
+        return nodeFfi.getRawPointer(value)
+      }
+
+      throw new TypeError("node:ffi ptr() only supports ArrayBuffer and ArrayBufferView values.")
+    },
+    toArrayBuffer(pointer, offset, length) {
+      return nodeFfi.toArrayBuffer(toBigIntPointer(pointer) + BigInt(offset ?? 0), length, false)
+    },
+  }
+}
+
+function toBigIntPointer(pointer: Pointer): bigint {
+  return typeof pointer === "bigint" ? pointer : BigInt(pointer)
+}
+
+function toBunPointer(pointer: Pointer): number {
+  return typeof pointer === "bigint" ? Number(pointer) : pointer
+}
+
+export const ptr = backend.ptr
+export const toArrayBuffer = backend.toArrayBuffer

src/structs_ffi.ts

@@ -1,5 +1,6 @@
-import { ptr, toArrayBuffer } from "bun:ffi"
+import { ptr, toArrayBuffer } from "./ffi.js"
 import type {
+  Pointer,
   PrimitiveType,
   PointyObject,
   ObjectPointerDef,
@@ -24,6 +25,7 @@ function fatalError(...args: any[]): never {
 }
 
 export const pointerSize = process.arch === "x64" || process.arch === "arm64" ? 8 : 4
+const isBun = typeof process !== "undefined" && "bun" in process.versions
 
 const typeSizes: Record<PrimitiveType, number> = {
   u8: 1,
@@ -95,6 +97,7 @@ export function allocStruct(structDef: StructDef<any, any>, options?: AllocStruc
 
       const pointer = length > 0 ? ptr(subBuffer) : null
       pointerPacker(view, arrayMeta.arrayOffset, pointer)
+      retainPointerTarget(buffer, subBuffer)
       arrayMeta.lengthPack(view, arrayMeta.lengthOffset, length)
     }
 
@@ -228,14 +231,18 @@ function primitivePackers(type: PrimitiveType) {
       unpack = (view: DataView, off: number) => view.getFloat64(off, true)
       break
     case "pointer":
-      pack = (view: DataView, off: number, val: bigint | number) => {
+      pack = (view: DataView, off: number, val: Pointer) => {
         pointerSize === 8
           ? view.setBigUint64(off, val ? BigInt(val) : 0n, true)
           : view.setUint32(off, val ? Number(val) : 0, true)
       }
-      unpack = (view: DataView, off: number): number => {
-        const bint = pointerSize === 8 ? view.getBigUint64(off, true) : BigInt(view.getUint32(off, true))
-        return Number(bint)
+      unpack = (view: DataView, off: number): Pointer => {
+        if (pointerSize === 8) {
+          const value = view.getBigUint64(off, true)
+          return isBun ? Number(value) : value
+        }
+
+        return view.getUint32(off, true)
       }
       break
     default:
@@ -248,6 +255,31 @@ function primitivePackers(type: PrimitiveType) {
 
 const { pack: pointerPacker, unpack: pointerUnpacker } = primitivePackers("pointer")
 
+const retainedPointerTargets = new WeakMap<ArrayBufferLike, unknown[]>()
+
+function retainPointerTarget(owner: ArrayBufferLike, target: unknown) {
+  const retained = retainedPointerTargets.get(owner)
+  if (retained) {
+    retained.push(target)
+  } else {
+    retainedPointerTargets.set(owner, [target])
+  }
+}
+
+function retainIfPointerTargets(owner: ArrayBufferLike, target: ArrayBufferLike) {
+  if (retainedPointerTargets.has(target)) {
+    retainPointerTarget(owner, target)
+  }
+}
+
+function isNullPointer(pointer: Pointer | null | undefined): boolean {
+  return pointer == null || pointer === 0 || pointer === 0n
+}
+
+function toItemCount(length: number | bigint): number {
+  return typeof length === "bigint" ? Number(length) : length
+}
+
 export function packObjectArray(val: (PointyObject | null)[]) {
   const buffer = new ArrayBuffer(val.length * pointerSize)
   const bufferView = new DataView(buffer)
@@ -299,8 +331,15 @@ export function defineStruct<const Fields extends readonly StructField[], const
       size = pointerSize
       align = pointerSize
       pack = (view: DataView, off: number, val: string | null) => {
-        const bufPtr = val ? ptr(encoder.encode(val + "\0")) : null
+        if (!val) {
+          pointerPacker(view, off, null)
+          return
+        }
+
+        const bytes = encoder.encode(val + "\0")
+        const bufPtr = ptr(bytes)
         pointerPacker(view, off, bufPtr)
+        retainPointerTarget(view.buffer, bytes)
       }
       unpack = (view: DataView, off: number) => {
         // TODO: Unpack CString from pointer
@@ -312,8 +351,15 @@ export function defineStruct<const Fields extends readonly StructField[], const
       size = pointerSize
       align = pointerSize
       pack = (view: DataView, off: number, val: string | null) => {
-        const bufPtr = val ? ptr(encoder.encode(val)) : null // No null terminator
+        if (!val) {
+          pointerPacker(view, off, null)
+          return
+        }
+
+        const bytes = encoder.encode(val) // No null terminator
+        const bufPtr = ptr(bytes)
         pointerPacker(view, off, bufPtr)
+        retainPointerTarget(view.buffer, bytes)
       }
       // Initial unpack returns pointer; will be replaced if lengthOf field exists
       unpack = (view: DataView, off: number) => {
@@ -347,6 +393,7 @@ export function defineStruct<const Fields extends readonly StructField[], const
           }
           const nestedBuf = typeOrStruct.pack(val, options)
           pointerPacker(view, off, ptr(nestedBuf))
+          retainPointerTarget(view.buffer, nestedBuf)
         }
         unpack = (view, off) => {
           throw new Error("Not implemented yet")
@@ -360,6 +407,7 @@ export function defineStruct<const Fields extends readonly StructField[], const
           const nestedView = new Uint8Array(nestedBuf)
           const dView = new Uint8Array(view.buffer)
           dView.set(nestedView, off)
+          retainIfPointerTargets(view.buffer, nestedBuf)
         }
         unpack = (view, off) => {
           const slice = view.buffer.slice(off, off + size)
@@ -412,6 +460,7 @@ export function defineStruct<const Fields extends readonly StructField[], const
             bufferView.setUint32(i * arrayElementSize, num, true)
           }
           pointerPacker(view, off, ptr(buffer))
+          retainPointerTarget(view.buffer, buffer)
         }
         unpack = null!
         needsLengthOf = true
@@ -430,6 +479,7 @@ export function defineStruct<const Fields extends readonly StructField[], const
             def.packInto(val[i], bufferView, i * arrayElementSize, options)
           }
           pointerPacker(view, off, ptr(buffer))
+          retainPointerTarget(view.buffer, buffer)
         }
         unpack = (view, off) => {
           throw new Error("Not implemented yet")
@@ -450,6 +500,7 @@ export function defineStruct<const Fields extends readonly StructField[], const
             primitivePack(bufferView, i * arrayElementSize, val[i])
           }
           pointerPacker(view, off, ptr(buffer))
+          retainPointerTarget(view.buffer, buffer)
         }
         unpack = null!
         needsLengthOf = true
@@ -464,6 +515,7 @@ export function defineStruct<const Fields extends readonly StructField[], const
 
           const packedView = packObjectArray(val)
           pointerPacker(view, off, ptr(packedView.buffer))
+          retainPointerTarget(view.buffer, packedView.buffer)
         }
         unpack = () => {
           // TODO: implement unpack for class pointers
@@ -583,11 +635,11 @@ export function defineStruct<const Fields extends readonly StructField[], const
         const ptrAddress = pointerUnpacker(view, off)
         const length = lengthOfField.unpack(view, off + relativeOffset)
 
-        if (ptrAddress === 0) {
+        if (isNullPointer(ptrAddress)) {
           return null
         }
 
-        const byteLength = typeof length === "bigint" ? Number(length) : length
+        const byteLength = toItemCount(length)
 
         if (byteLength === 0) {
           return ""
@@ -604,19 +656,20 @@ export function defineStruct<const Fields extends readonly StructField[], const
       requester.unpack = (view, off) => {
         const result = []
         const length = lengthOfField.unpack(view, off + relativeOffset)
+        const itemCount = toItemCount(length)
         const ptrAddress = pointerUnpacker(view, off)
 
-        if (ptrAddress === 0n && length > 0) {
+        if (isNullPointer(ptrAddress) && itemCount > 0) {
           throw new Error(`Array field ${requester.name} has null pointer but length ${length}.`)
         }
-        if (ptrAddress === 0n || length === 0) {
+        if (isNullPointer(ptrAddress) || itemCount === 0) {
           return []
         }
 
-        const buffer = toArrayBuffer(ptrAddress, 0, length * elemSize)
+        const buffer = toArrayBuffer(ptrAddress, 0, itemCount * elemSize)
         const bufferView = new DataView(buffer)
 
-        for (let i = 0; i < length; i++) {
+        for (let i = 0; i < itemCount; i++) {
           result.push(primitiveUnpack(bufferView, i * elemSize))
         }
         return result
@@ -628,19 +681,20 @@ export function defineStruct<const Fields extends readonly StructField[], const
       requester.unpack = (view, off) => {
         const result = []
         const length = lengthOfField.unpack(view, off + relativeOffset)
+        const itemCount = toItemCount(length)
         const ptrAddress = pointerUnpacker(view, off)
 
-        if (ptrAddress === 0n && length > 0) {
+        if (isNullPointer(ptrAddress) && itemCount > 0) {
           throw new Error(`Array field ${requester.name} has null pointer but length ${length}.`)
         }
-        if (ptrAddress === 0n || length === 0) {
+        if (isNullPointer(ptrAddress) || itemCount === 0) {
           return []
         }
 
-        const buffer = toArrayBuffer(ptrAddress, 0, length * elemSize)
+        const buffer = toArrayBuffer(ptrAddress, 0, itemCount * elemSize)
         const bufferView = new DataView(buffer)
 
-        for (let i = 0; i < length; i++) {
+        for (let i = 0; i < itemCount; i++) {
           result.push(def.from(bufferView.getUint32(i * elemSize, true)))
         }
         return result

src/tests/char-star-unpacking.test.ts

@@ -1,6 +1,6 @@
 import { expect, describe, it } from "bun:test"
+import { ptr } from "../ffi.js"
 import { defineStruct } from "../structs_ffi.js"
-import { ptr } from "bun:ffi"
 
 describe("char* automatic unpacking", () => {
   it("should automatically unpack char* to string when lengthOf field exists", () => {
@@ -164,9 +164,13 @@ describe("char* automatic unpacking", () => {
     })
     const unpacked = PointerStruct.unpack(packed)
 
-    // Without lengthOf, should return the pointer value (number)
-    expect(typeof unpacked.data).toBe("number")
-    expect(unpacked.data).toBeGreaterThan(0)
+    // Without lengthOf, should return the raw pointer value.
+    expect(["number", "bigint"]).toContain(typeof unpacked.data)
+    if (typeof unpacked.data === "bigint") {
+      expect(unpacked.data).toBeGreaterThan(0n)
+    } else {
+      expect(unpacked.data).toBeGreaterThan(0)
+    }
     expect(unpacked.someOtherField).toBe(42)
   })
 

src/tests/field-validation.test.ts

@@ -1,5 +1,5 @@
 import { expect, describe, it } from "bun:test"
-import { toArrayBuffer } from "bun:ffi"
+import { toArrayBuffer } from "../ffi.js"
 import { defineEnum, defineStruct } from "../structs_ffi.js"
 
 describe("field validation", () => {

src/tests/graphemes.test.ts

@@ -1,6 +1,7 @@
 import { expect, describe, it } from "bun:test"
-import { toArrayBuffer } from "bun:ffi"
+import { toArrayBuffer } from "../ffi.js"
 import { defineStruct } from "../structs_ffi.js"
+import type { Pointer } from "../types.js"
 
 describe("string packing with graphemes and emojis", () => {
   it("should pack and unpack char* with byte length (not character count) for ASCII", () => {
@@ -113,11 +114,10 @@ describe("string packing with graphemes and emojis", () => {
           data: v,
           length: Buffer.byteLength(v),
         }),
-        reduceValue: (v: { data: number; length: bigint }) => {
-          if (v.data === 0 || v.length === 0n) {
+        reduceValue: (v: { data: Pointer; length: bigint }) => {
+          if (v.data === 0 || v.data === 0n || v.length === 0n) {
             return ""
           }
-          // @ts-ignore - toArrayBuffer pointer type issue
           const buffer = toArrayBuffer(v.data, 0, Number(v.length))
           return new TextDecoder().decode(buffer)
         },
@@ -143,11 +143,10 @@ describe("string packing with graphemes and emojis", () => {
           data: v,
           length: Buffer.byteLength(v),
         }),
-        reduceValue: (v: { data: number; length: bigint }) => {
-          if (v.data === 0 || v.length === 0n) {
+        reduceValue: (v: { data: Pointer; length: bigint }) => {
+          if (v.data === 0 || v.data === 0n || v.length === 0n) {
             return ""
           }
-          // @ts-ignore - toArrayBuffer pointer type issue
           const buffer = toArrayBuffer(v.data, 0, Number(v.length))
           return new TextDecoder().decode(buffer)
         },