unffi 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# unffi
+
+[![npm version](https://img.shields.io/npm/v/unffi?style=flat-square)](https://www.npmjs.com/package/unffi) [![license](https://img.shields.io/npm/l/unffi?style=flat-square)](./LICENSE) [![CI](https://img.shields.io/github/actions/workflow/status/rajaniraiyn/unffi/ci.yml?style=flat-square&label=CI)](https://github.com/rajaniraiyn/unffi/actions)
+
+Universal FFI for Bun, Deno, and Node.js — one schema, runtime-native performance.
+
+## Install
+
+```sh
+npm install unffi
+pnpm add unffi
+yarn add unffi
+bun add unffi
+```
+
+## Quick Start
+
+```ts
+import { dlopen, t } from 'unffi'
+
+// Compile: cc -shared -o libgreeter.dylib greeter.c
+// char* greet(const char* name);
+// void on_greet(void (*cb)(const char*), const char* name);
+
+await using lib = await dlopen('./libgreeter', {
+  greet: {
+    args: [t.cstring],
+    returns: t.cstring,
+  },
+  on_greet: {
+    args: [t.fn([t.cstring], t.void), t.cstring],
+    returns: t.void,
+  },
+})
+
+console.log(lib.symbols.greet('world'))
+// → "Hello, world!"
+
+lib.symbols.on_greet((msg) => console.log(msg), 'unffi')
+// → "Hello, unffi!"
+
+// lib.close() called automatically via await using (Symbol.asyncDispose)
+```
+
+## Runtimes
+
+| Runtime | FFI backend | Notes |
+|---------|-------------|-------|
+| Bun | `bun:ffi` | Zero overhead, native types |
+| Deno | `Deno.dlopen` | `usize`/`isize` platform types |
+| Node.js | `node:ffi` (Node 26+) → koffi | koffi is an optional peer dep, installed automatically |
+
+## How it works
+
+`unffi` ships separate adapter modules for each runtime and uses `package.json` export conditions (`"bun"`, `"deno"`, `"node"`) so the runtime loads the right adapter with no branching in your code. Each adapter translates the shared `t.xxx` type tokens into whatever representation that runtime expects — `bun:ffi` type strings, `Deno.NativeType`, or koffi signatures. On Node 26+, the native `node:ffi` module is preferred; koffi is the fallback for older Node versions.
+
+## Runtime-specific types
+
+Import from `unffi/types` to access types not in the universal core.
+
+- `t.bun.i64_fast` — i64 as `number` instead of `bigint` when Bun can fit it safely
+- `t.deno.usize` / `t.deno.isize` — pointer-width integers on the current platform
+- `t.koffi.struct(layout)` — define a C struct layout for koffi on Node.js
+
+Full API docs: [rajaniraiyn.github.io/unffi](https://rajaniraiyn.github.io/unffi)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "unffi",
+  "version": "0.1.0",
+  "description": "Universal FFI for Bun, Deno, and Node.js — one schema, runtime-native performance",
+  "workspaces": ["docs"],
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": {
+        "types": "./dist/adapters/bun.d.ts",
+        "default": "./dist/adapters/bun.js"
+      },
+      "deno": {
+        "types": "./dist/adapters/deno.d.ts",
+        "default": "./dist/adapters/deno.js"
+      },
+      "node": {
+        "types": "./dist/adapters/node.d.ts",
+        "default": "./dist/adapters/node.js"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsgo -b tsconfig.json",
+    "build:clean": "tsgo -b --clean tsconfig.json && tsgo -b tsconfig.json",
+    "typecheck": "tsgo -b tsconfig.json --dry",
+    "dev": "tsgo -b --watch tsconfig.json",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "typecheck:tests": "tsgo --project tsconfig.test.json"
+  },
+  "optionalDependencies": {
+    "koffi": "^2.9.0 || ^3.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "@types/deno": "^2.7.0",
+    "@types/node": "^18.0.0",
+    "@typescript/native-preview": "latest"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.2.0 <6"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+    "optional": true
+  }
+},
+"engines": {
+  "bun": ">=1.0.0",
+  "node": ">=18.0.0"
+},
+"keywords": [
+  "ffi",
+  "bun",
+  "deno",
+  "node",
+  "native",
+  "dylib",
+  "unjs"
+],
+"license": "MIT",
+"trustedDependencies": [
+  "koffi"
+]
+}

package/src/adapters/bun.ts

@@ -0,0 +1,183 @@
+import { dlopen as bunDlopen, FFIType, JSCallback, CString, ptr as bunPtr } from 'bun:ffi'
+import type { SymbolsSchema, InferLibrary } from '../define.js'
+import type { CCallback, CType, CTypeKind, CoreT } from '../types.js'
+import { t as coreT } from '../types.js'
+import { runtimeHint } from './hints.js'
+
+export type { InferLibrary }
+
+export interface BunT extends CoreT {
+  readonly bun: {
+    /**
+     * 64-bit signed integer that returns `number` when the value fits in a
+     * safe integer, `bigint` otherwise. Same as `FFIType.i64_fast`.
+     */
+    readonly i64_fast:   CType<number | bigint>
+    /**
+     * 64-bit unsigned integer that returns `number` when the value fits in a
+     * safe integer, `bigint` otherwise. Same as `FFIType.u64_fast`.
+     */
+    readonly u64_fast:   CType<number | bigint>
+    /** NAPI environment pointer — for interop with Node-API addons. */
+    readonly napi_env:   CType<unknown>
+    /** NAPI value — for interop with Node-API addons. */
+    readonly napi_value: CType<unknown>
+  }
+}
+
+const coreFFITypes: Record<CTypeKind, FFIType> = {
+  void:     FFIType.void,
+  bool:     FFIType.bool,
+  i8:       FFIType.int8_t,
+  i16:      FFIType.int16_t,
+  i32:      FFIType.int32_t,
+  i64:      FFIType.int64_t,
+  u8:       FFIType.uint8_t,
+  u16:      FFIType.uint16_t,
+  u32:      FFIType.uint32_t,
+  u64:      FFIType.uint64_t,
+  f32:      FFIType.float,
+  f64:      FFIType.double,
+  cstring:  FFIType.cstring,
+  pointer:  FFIType.ptr,
+  buffer:   FFIType.ptr,
+  function: FFIType.function,
+}
+
+const bunFFITypes: Record<string, FFIType> = {
+  'bun:i64_fast':   FFIType.i64_fast,
+  'bun:u64_fast':   FFIType.u64_fast,
+  'bun:napi_env':   FFIType.napi_env,
+  'bun:napi_value': FFIType.napi_value,
+}
+
+const allFFITypes: Record<string, FFIType> = { ...coreFFITypes, ...bunFFITypes }
+
+function getFFIType(kind: string): FFIType {
+  const type = allFFITypes[kind]
+  if (type !== undefined) return type
+  throw new Error(`[unffi/bun] Unsupported FFI type "${kind}". ${runtimeHint(kind, 'bun')}`)
+}
+
+const bunExtensions = {
+  i64_fast:   { kind: 'bun:i64_fast'   } as unknown as CType<number | bigint>,
+  u64_fast:   { kind: 'bun:u64_fast'   } as unknown as CType<number | bigint>,
+  napi_env:   { kind: 'bun:napi_env'   } as unknown as CType<unknown>,
+  napi_value: { kind: 'bun:napi_value' } as unknown as CType<unknown>,
+}
+
+export const t: BunT = Object.assign({}, coreT, { bun: bunExtensions })
+
+export function dlopen<const S extends SymbolsSchema>(path: string, schema: S): InferLibrary<S> {
+  const bunSymbols: Record<string, { args: FFIType[]; returns: FFIType; nonblocking?: boolean }> = {}
+
+  for (const [name, def] of Object.entries(schema)) {
+    bunSymbols[name] = {
+      args:    def.args.map((a: CType<unknown>) => getFFIType(a.kind)),
+      returns: getFFIType(def.returns.kind),
+      ...(def.async && { nonblocking: true }),
+    }
+  }
+
+  const lib = bunDlopen(path, bunSymbols)
+  // NO FinalizationRegistry around JSCallbacks. C owns the function
+  // pointer indefinitely — a library can stash a callback (logger, atexit,
+  // signal handler) and invoke it long after the JS function is unreachable.
+  // GC-driven free would race with a live C-side pointer → use-after-free.
+  // Lifetime is bound to the library and freed in close().
+  const callbacks = new Map<string, JSCallback>()
+
+  const symbols: Record<string, (...args: unknown[]) => unknown> = {}
+
+  for (const [name, def] of Object.entries(schema)) {
+    const rawFn = (lib.symbols as Record<string, (...a: unknown[]) => unknown>)[name]!
+
+    const cstringInIdx = def.args
+      .map((a: CType<unknown>, i: number) => (a.kind === 'cstring'  ? i : -1))
+      .filter((i: number) => i !== -1)
+    const bufferInIdx = def.args
+      .map((a: CType<unknown>, i: number) => (a.kind === 'buffer'   ? i : -1))
+      .filter((i: number) => i !== -1)
+    const callbackIdx = def.args
+      .map((a: CType<unknown>, i: number) => (a.kind === 'function' ? i : -1))
+      .filter((i: number) => i !== -1)
+    const returnsCstring = def.returns.kind === 'cstring'
+
+    if (
+      cstringInIdx.length === 0 &&
+      bufferInIdx.length  === 0 &&
+      callbackIdx.length  === 0 &&
+      !returnsCstring
+    ) {
+      symbols[name] = rawFn
+      continue
+    }
+
+    symbols[name] = (...args: unknown[]) => {
+      const wrapped = args.length === def.args.length ? args.slice() : [...args]
+
+      for (const i of cstringInIdx) {
+        const v = wrapped[i]
+        if (typeof v === 'string') wrapped[i] = Buffer.from(v + '\0')
+      }
+
+      for (const i of bufferInIdx) {
+        const v = wrapped[i]
+        if (v != null && typeof v === 'object' && ArrayBuffer.isView(v) && v.byteLength > 0) {
+          wrapped[i] = bunPtr(v as NodeJS.TypedArray)
+        }
+      }
+
+      for (const i of callbackIdx) {
+        const cb     = def.args[i] as CCallback<readonly CType<unknown>[], CType<unknown>>
+        const userFn = wrapped[i] as (...a: unknown[]) => unknown
+        const cbCstrIdx = cb.argTypes
+          .map((a: CType<unknown>, j: number) => (a.kind === 'cstring' ? j : -1))
+          .filter((j: number) => j !== -1)
+
+        const wrappedFn = cbCstrIdx.length === 0
+          ? userFn
+          : (...cbArgs: unknown[]) => {
+              for (const j of cbCstrIdx) {
+                const p = cbArgs[j]
+                cbArgs[j] = p == null ? null : new CString(p as number & { __pointer__: null }).toString()
+              }
+              return userFn(...cbArgs)
+            }
+
+        const jsCb = new JSCallback(wrappedFn, {
+          args:    cb.argTypes.map((a: CType<unknown>) => getFFIType(a.kind)),
+          returns: getFFIType(cb.returnType.kind),
+        })
+        callbacks.set(`${name}:${i}`, jsCb)
+        wrapped[i] = jsCb.ptr
+      }
+
+      const result = rawFn(...wrapped)
+
+      if (returnsCstring) {
+        if (result instanceof Promise) {
+          return result.then((r) => (r instanceof String ? r.toString() : r))
+        }
+        if (result instanceof String) return result.toString()
+      }
+      return result
+    }
+  }
+
+  let closed = false
+  function close() {
+    if (closed) return  // idempotent: safe to call after `using` already disposed
+    closed = true
+    for (const cb of callbacks.values()) cb.close()
+    callbacks.clear()
+    lib.close()
+  }
+
+  return {
+    symbols: symbols as InferLibrary<S>['symbols'],
+    close,
+    [Symbol.dispose]: close,
+    [Symbol.asyncDispose]() { return Promise.resolve(close()) },
+  }
+}

package/src/adapters/deno.ts

@@ -0,0 +1,259 @@
+import type { SymbolsSchema, InferLibrary } from '../define.js'
+import type { CCallback, CType, CTypeKind, CoreT } from '../types.js'
+import { t as coreT } from '../types.js'
+import { runtimeHint } from './hints.js'
+
+export type { InferLibrary }
+
+export interface DenoT extends CoreT {
+  readonly deno: {
+    /** Pointer-sized unsigned integer (64-bit on 64-bit systems) → `bigint` */
+    readonly usize: CType<bigint>
+    /** Pointer-sized signed integer (64-bit on 64-bit systems) → `bigint` */
+    readonly isize: CType<bigint>
+    /**
+     * Compose a struct C type. Passed by value to/from FFI as a
+     * BufferSource → Uint8Array. The `fields` argument is a list of
+     * unffi CType<*> tokens; their `kind`s are translated to Deno's
+     * NativeType under the hood.
+     *
+     * Example:
+     *   const Point = t.deno.struct([t.f32, t.f32])
+     */
+    struct<const Fields extends readonly CType<any>[]>(fields: Fields): CType<Uint8Array>
+
+    /**
+     * Zero-copy: return a Deno pointer to a TypedArray's memory.
+     * Pass the result to symbols typed as `t.pointer`.
+     * Equivalent to `Deno.UnsafePointer.of(view)`.
+     */
+    ptrOf(view: ArrayBufferView | ArrayBuffer): Deno.PointerValue
+
+    /**
+     * Read a UTF-8 NUL-terminated string from a pointer.
+     * Useful for symbols that return `t.pointer` instead of `t.cstring`
+     * (e.g. when you need offset arithmetic).
+     */
+    readCString(pointer: Deno.PointerValue, offset?: number): string
+
+    /**
+     * Zero-copy read of `byteLength` bytes at `pointer + offset` as an ArrayBuffer.
+     */
+    readArrayBuffer(pointer: Deno.PointerValue, byteLength: number, offset?: number): ArrayBuffer
+  }
+}
+
+const coreDenoTypes: Record<CTypeKind, Deno.NativeResultType> = {
+  void:     'void',
+  bool:     'bool',
+  i8:       'i8',  i16: 'i16', i32: 'i32', i64: 'i64',
+  u8:       'u8',  u16: 'u16', u32: 'u32', u64: 'u64',
+  f32:      'f32', f64: 'f64',
+  cstring:  'pointer',
+  pointer:  'pointer',
+  buffer:   'buffer',
+  function: 'function',
+}
+
+const denoExtraTypes: Record<string, Deno.NativeResultType> = {
+  'deno:usize': 'usize',
+  'deno:isize': 'isize',
+}
+
+const allDenoTypes: Record<string, Deno.NativeResultType> = { ...coreDenoTypes, ...denoExtraTypes }
+
+const StructDef = Symbol('unffi.deno.struct')
+type StructCType = CType<Uint8Array> & { readonly [StructDef]: Deno.NativeStructType }
+
+function isStructCType(t: CType<any>): t is StructCType {
+  return (t as StructCType)[StructDef] !== undefined
+}
+
+function getDenoType(type: CType<any>): Deno.NativeType {
+  if (isStructCType(type)) return type[StructDef]
+  const kind = type.kind
+  const mapped = allDenoTypes[kind]
+  if (mapped !== undefined && mapped !== 'void') return mapped as Deno.NativeType
+  if (mapped === 'void') return mapped as unknown as Deno.NativeType
+  throw new Error(`[unffi/deno] Unsupported FFI type "${kind}". ${runtimeHint(kind, 'deno')}`)
+}
+
+function getDenoResultType(type: CType<any>): Deno.NativeResultType {
+  if (isStructCType(type)) return type[StructDef]
+  const kind = type.kind
+  const mapped = allDenoTypes[kind]
+  if (mapped !== undefined) return mapped
+  throw new Error(`[unffi/deno] Unsupported FFI result type "${kind}".`)
+}
+
+const denoExtensions: DenoT['deno'] = {
+  usize: { kind: 'deno:usize' } as unknown as CType<bigint>,
+  isize: { kind: 'deno:isize' } as unknown as CType<bigint>,
+
+  struct<const Fields extends readonly CType<any>[]>(fields: Fields): CType<Uint8Array> {
+    const struct: Deno.NativeStructType = {
+      struct: fields.map((f) => getDenoType(f)),
+    }
+    const token = { kind: 'pointer' as CTypeKind, [StructDef]: struct }
+    return token as unknown as CType<Uint8Array>
+  },
+
+  ptrOf(view) { return Deno.UnsafePointer.of(view as ArrayBufferView) },
+  readCString(pointer, offset) {
+    if (pointer === null) throw new Error('[unffi/deno] readCString called with null pointer')
+    return Deno.UnsafePointerView.getCString(pointer, offset)
+  },
+  readArrayBuffer(pointer, byteLength, offset) {
+    if (pointer === null) throw new Error('[unffi/deno] readArrayBuffer called with null pointer')
+    return Deno.UnsafePointerView.getArrayBuffer(pointer, byteLength, offset)
+  },
+}
+
+export const t: DenoT = Object.assign({}, coreT, { deno: denoExtensions })
+
+declare const TextEncoder: { new (): { encode(input: string): Uint8Array } }
+const enc = new TextEncoder()
+
+function encodeCStringPtr(s: string): { ptr: Deno.PointerValue; bytes: Uint8Array } {
+  const bytes = enc.encode(s + '\0')
+  return { ptr: Deno.UnsafePointer.of(bytes), bytes }
+}
+
+function decodeCStringResult(ptr: Deno.PointerValue): string | null {
+  if (ptr === null) return null
+  return Deno.UnsafePointerView.getCString(ptr)
+}
+
+export function dlopen<const S extends SymbolsSchema>(path: string, schema: S): InferLibrary<S> {
+  const denoSymbols: Record<string, Deno.ForeignFunction> = {}
+
+  for (const [name, def] of Object.entries(schema)) {
+    denoSymbols[name] = {
+      parameters: def.args.map((a) => getDenoType(a)),
+      result:     getDenoResultType(def.returns),
+      ...(def.async && { nonblocking: true }),
+    }
+  }
+
+  let lib: ReturnType<typeof Deno.dlopen>
+  try {
+    lib = Deno.dlopen(path, denoSymbols)
+  } catch (e) {
+    if (e instanceof Deno.errors.PermissionDenied) {
+      throw new Error(
+        '[unffi] Deno FFI requires the --allow-ffi permission flag.\n' +
+        '  Run your script with: deno run --allow-ffi <script.ts>\n' +
+        '  Docs: https://docs.deno.com/runtime/fundamentals/ffi/',
+      )
+    }
+    throw e
+  }
+
+  // NO FinalizationRegistry on UnsafeCallbacks. C may retain the
+  // pointer after the JS function becomes unreachable (stored handler,
+  // signal/atexit hook), so GC-driven free races with a live C-side caller.
+  // Lifetime is bound to the library, freed in close().
+  const callbacks = new Set<Deno.UnsafeCallback>()
+  const wrappedSymbols: Record<string, (...args: unknown[]) => unknown> = {}
+
+  for (const [name, def] of Object.entries(schema)) {
+    const rawFn = (lib.symbols as Record<string, (...a: unknown[]) => unknown>)[name]
+
+    if (!rawFn) continue
+
+    const cstringInIdx = def.args
+      .map((a, i) => (a.kind === 'cstring' ? i : -1))
+      .filter((i) => i !== -1)
+    const callbackIdx = def.args
+      .map((a, i) => (a.kind === 'function' ? i : -1))
+      .filter((i) => i !== -1)
+    const returnsCstring = def.returns.kind === 'cstring'
+
+    if (cstringInIdx.length === 0 && callbackIdx.length === 0 && !returnsCstring) {
+      wrappedSymbols[name] = rawFn
+      continue
+    }
+
+    wrappedSymbols[name] = (...args: unknown[]) => {
+      const wrapped: unknown[] = [...args]
+      const keepAlive: Uint8Array[] = []
+
+      for (const i of cstringInIdx) {
+        const v = wrapped[i]
+        if (typeof v === 'string') {
+          const { ptr, bytes } = encodeCStringPtr(v)
+          keepAlive.push(bytes)
+          wrapped[i] = ptr
+        }
+        // If the caller already passed a Deno.PointerValue (advanced path), leave it.
+      }
+
+      for (const i of callbackIdx) {
+        const cb     = def.args[i] as CCallback<readonly CType<unknown>[], CType<unknown>>
+        const userFn = wrapped[i] as (...a: unknown[]) => unknown
+
+        const cbCstrIdx = cb.argTypes
+          .map((a, j) => (a.kind === 'cstring' ? j : -1))
+          .filter((j) => j !== -1)
+        const cbReturnsCstring = cb.returnType.kind === 'cstring'
+
+        const cbKeepAlive: Uint8Array[] = []
+
+        const inner = (cbCstrIdx.length === 0 && !cbReturnsCstring)
+          ? userFn
+          : (...cbArgs: unknown[]) => {
+            for (const j of cbCstrIdx) {
+              const p = cbArgs[j] as Deno.PointerValue
+              cbArgs[j] = p === null ? null : Deno.UnsafePointerView.getCString(p)
+            }
+            const r = userFn(...cbArgs)
+            if (cbReturnsCstring && typeof r === 'string') {
+              const bytes = enc.encode(r + '\0')
+              cbKeepAlive.push(bytes)
+              return Deno.UnsafePointer.of(bytes)
+            }
+            return r
+          }
+
+        const unsafeCb = new Deno.UnsafeCallback(
+          {
+            parameters: cb.argTypes.map((a) => getDenoType(a)),
+            result:     getDenoResultType(cb.returnType),
+          } as Deno.UnsafeCallbackDefinition,
+          inner as Deno.UnsafeCallbackFunction,
+        )
+        callbacks.add(unsafeCb)
+        wrapped[i] = unsafeCb.pointer
+      }
+
+      const result = rawFn(...wrapped)
+
+      if (returnsCstring) {
+        if (result instanceof Promise) {
+          return result.then((r) => decodeCStringResult(r as Deno.PointerValue))
+        }
+        return decodeCStringResult(result as Deno.PointerValue)
+      }
+
+      // Touch keepAlive after the call so the optimiser cannot drop it.
+      void keepAlive.length
+      return result
+    }
+  }
+
+  let closed = false
+  function close() {
+    if (closed) return  // idempotent: safe to call after `using` already disposed
+    closed = true
+    for (const cb of callbacks) cb.close()
+    callbacks.clear()
+    lib.close()
+  }
+
+  return {
+    symbols: wrappedSymbols as InferLibrary<S>['symbols'],
+    close,
+    [Symbol.dispose]: close,
+    [Symbol.asyncDispose]() { return Promise.resolve(close()) },
+  }
+}

package/src/adapters/hints.ts

@@ -0,0 +1,7 @@
+export function runtimeHint(kind: string, self: 'bun' | 'deno' | 'node'): string {
+  if (self !== 'bun'   && kind.startsWith('bun:'))   return 'This is a Bun-specific type — run with Bun. See https://bun.sh/docs/api/ffi'
+  if (self !== 'deno'  && kind.startsWith('deno:'))  return 'This is a Deno-specific type — run with Deno. See https://docs.deno.com/runtime/fundamentals/ffi/'
+  if (self !== 'node'  && kind.startsWith('node:'))  return 'This is a Node.js-specific type — run with Node.js.'
+  if (self !== 'node'  && kind.startsWith('koffi:')) return 'This is a koffi-specific type — run with Node.js and install koffi. See https://koffi.dev'
+  return 'Unknown type kind.'
+}

package/src/adapters/koffi.ts

@@ -0,0 +1,249 @@
+import koffi, { type IKoffiLib, type IKoffiCType } from 'koffi'
+import type { SymbolsSchema, InferLibrary } from '../define.js'
+import type { CCallback, CType, CTypeKind, CoreT } from '../types.js'
+import { t as coreT } from '../types.js'
+import { runtimeHint } from './hints.js'
+
+export type { InferLibrary }
+
+type KoffiTypeSpec = Parameters<IKoffiLib['symbol']>[1]
+
+type KoffiStructDef = Parameters<typeof koffi.struct>[0] extends infer P
+  ? P extends Record<string, unknown> ? P : Record<string, KoffiTypeSpec>
+  : Record<string, KoffiTypeSpec>
+
+// koffi.d.ts overlapping overloads make Parameters<typeof koffi.array>[2] resolve wrong
+type KoffiArrayHint = 'Array' | 'Typed' | 'String'
+
+const nativeKoffiType = new WeakMap<CType<unknown>, IKoffiCType>()
+
+function brand<T>(native: IKoffiCType): CType<T> {
+  const ct = { kind: 'koffi:native' as CTypeKind } as CType<T>
+  nativeKoffiType.set(ct as CType<unknown>, native)
+  return ct
+}
+
+export interface KoffiT extends CoreT {
+  readonly koffi: {
+    /** UTF-16 string — for Windows APIs that use wide strings (koffi `str16`). */
+    readonly str16:   CType<string>
+    /** Pointer-sized unsigned integer, returns `bigint` (koffi `uintptr_t`). */
+    readonly uintptr: CType<bigint>
+    /** Pointer-sized signed integer, returns `bigint`  (koffi `intptr_t`). */
+    readonly intptr:  CType<bigint>
+    /** Build a struct type from a field map.
+     *
+     * ```ts
+     * const Point = t.koffi.struct<{ x: number; y: number }>({ x: 'float64', y: 'float64' })
+     * ``` */
+    struct<T = Record<string, unknown>>(def: KoffiStructDef): CType<T>
+    struct<T = Record<string, unknown>>(name: string, def: KoffiStructDef): CType<T>
+    /** Build a fixed-length array type. */
+    array<T = unknown>(ref: CType<T> | KoffiTypeSpec, len: number, hint?: KoffiArrayHint): CType<T[]>
+    /** Build a pointer-to-type. */
+    pointer<T>(ref: CType<T> | KoffiTypeSpec): CType<T>
+    /** Mark a parameter as output-only (caller passes a 1-element array; koffi writes index 0). */
+    out<T>(ref: CType<T> | KoffiTypeSpec): CType<[T]>
+    /** Mark a parameter as input+output. */
+    inout<T>(ref: CType<T> | KoffiTypeSpec): CType<[T]>
+    /** Opaque pointer type (foreign handle). */
+    opaque(name?: string): CType<unknown>
+    /** Alias a type under a new name. */
+    alias<T>(name: string, ref: CType<T> | KoffiTypeSpec): CType<T>
+    /** Encode a JS string into an ArrayBuffer of the given type (default `str` / UTF-8). */
+    encode(value: string, type?: KoffiTypeSpec): ArrayBuffer
+    /** Decode a pointer / buffer back to a JS value. */
+    decode<T = unknown>(ref: unknown, type: CType<T> | KoffiTypeSpec): T
+    /** Free memory allocated by `koffi.alloc` or returned as `disposable`. */
+    free(ref: unknown): void
+    /** Direct access to the raw koffi module (escape hatch). */
+    readonly raw: typeof koffi
+  }
+}
+
+const coreKoffiTypes: Record<Exclude<CTypeKind, 'function'>, KoffiTypeSpec> = {
+  void:    'void',
+  bool:    'bool',
+  i8:      'int8',    i16: 'int16',   i32: 'int32',   i64: 'int64',
+  u8:      'uint8',   u16: 'uint16',  u32: 'uint32',  u64: 'uint64',
+  f32:     'float32', f64: 'float64',
+  cstring: 'str',     // koffi auto-encodes/decodes UTF-8 string ↔ char* (verified)
+  pointer: 'void *',
+  buffer:  'void *',  // TypedArrays are passed zero-copy (verified — fill_buf mutates caller's Int32Array)
+}
+
+const koffiNamedExtras: Record<string, KoffiTypeSpec> = {
+  'koffi:str16':   'str16',
+  'koffi:uintptr': 'uintptr_t',
+  'koffi:intptr':  'intptr_t',
+}
+
+export function getKoffiType(type: CType<unknown> | string): KoffiTypeSpec {
+  if (typeof type !== 'string') {
+    const native = nativeKoffiType.get(type as CType<unknown>)
+    if (native !== undefined) return native
+    return resolveKind(type.kind)
+  }
+  return resolveKind(type)
+}
+
+function resolveKind(kind: string): KoffiTypeSpec {
+  if (kind in coreKoffiTypes) return coreKoffiTypes[kind as keyof typeof coreKoffiTypes]
+  if (kind in koffiNamedExtras) return koffiNamedExtras[kind]!
+  if (kind === 'function') return 'void *'
+  if (kind === 'koffi:native') throw new Error('[unffi/koffi] Internal: koffi:native type missing IKoffiCType payload')
+  throw new Error(`[unffi/koffi] Unsupported FFI type "${kind}". ${runtimeHint(kind, 'node')}`)
+}
+
+function toSpec(ref: CType<unknown> | KoffiTypeSpec): KoffiTypeSpec {
+  if (typeof ref === 'string') return ref
+  if (ref !== null && typeof ref === 'object' && '__brand' in (ref as object)) return ref as IKoffiCType
+  return getKoffiType(ref as CType<unknown>)
+}
+
+function asPointer(ref: CType<unknown> | KoffiTypeSpec): IKoffiCType {
+  return koffi.pointer(toSpec(ref))
+}
+
+const koffiExtensions: KoffiT['koffi'] = {
+  str16:   { kind: 'koffi:str16'   } as unknown as CType<string>,
+  uintptr: { kind: 'koffi:uintptr' } as unknown as CType<bigint>,
+  intptr:  { kind: 'koffi:intptr'  } as unknown as CType<bigint>,
+
+  struct<T>(a: string | KoffiStructDef, b?: KoffiStructDef): CType<T> {
+    const native = (typeof a === 'string')
+      ? koffi.struct(a, b!)
+      : koffi.struct(a as KoffiStructDef)
+    return brand<T>(native)
+  },
+
+  array<T>(ref: CType<T> | KoffiTypeSpec, len: number, hint?: KoffiArrayHint): CType<T[]> {
+    const native = hint === undefined
+      ? koffi.array(toSpec(ref), len)
+      : koffi.array(toSpec(ref), len, hint)
+    return brand<T[]>(native)
+  },
+
+  pointer<T>(ref: CType<T> | KoffiTypeSpec): CType<T> {
+    return brand<T>(koffi.pointer(toSpec(ref)))
+  },
+
+  out<T>(ref: CType<T> | KoffiTypeSpec): CType<[T]> {
+    return brand<[T]>(koffi.out(asPointer(ref)))
+  },
+
+  inout<T>(ref: CType<T> | KoffiTypeSpec): CType<[T]> {
+    return brand<[T]>(koffi.inout(asPointer(ref)))
+  },
+
+  opaque(name?: string): CType<unknown> {
+    return brand<unknown>(name === undefined ? koffi.opaque() : koffi.opaque(name))
+  },
+
+  alias<T>(name: string, ref: CType<T> | KoffiTypeSpec): CType<T> {
+    return brand<T>(koffi.alias(name, toSpec(ref)))
+  },
+
+  encode(value: string, type: KoffiTypeSpec = 'str'): ArrayBuffer {
+    const slot = koffi.sizeof(type)
+    const size = slot > 0 ? Math.max(slot, value.length + 1) : value.length + 1
+    const buf  = new ArrayBuffer(size)
+    koffi.encode(buf, type, value)
+    return buf
+  },
+
+  decode<T>(ref: unknown, type: CType<T> | KoffiTypeSpec): T {
+    return koffi.decode(ref, toSpec(type)) as T
+  },
+
+  free: koffi.free,
+  raw: koffi,
+}
+
+export const t: KoffiT = Object.assign({}, coreT, { koffi: koffiExtensions })
+
+type CallbackDef = { i: number; cb: CCallback<readonly CType<unknown>[], CType<unknown>> }
+
+let cbCounter = 0
+
+export function dlopen<const S extends SymbolsSchema>(path: string, schema: S): InferLibrary<S> {
+  const lib = koffi.load(path)
+  const symbols: Record<string, (...args: unknown[]) => unknown> = {}
+  const registered: IKoffiCType[] = []
+
+  for (const [name, def] of Object.entries(schema)) {
+    // Per-callback proto-pointer types, indexed by arg position.
+    const callbackDefs: CallbackDef[] = []
+    const cbPointerTypes: Record<number, IKoffiCType> = {}
+
+    const argTypes: KoffiTypeSpec[] = def.args.map((a: CType<unknown>, i: number) => {
+      if (a.kind === 'function') {
+        const cb = a as CCallback<readonly CType<unknown>[], CType<unknown>>
+        callbackDefs.push({ i, cb })
+        const proto = koffi.proto(
+          `__unffi_cb_${name}_${i}_${++cbCounter}`,
+          getKoffiType(cb.returnType),
+          cb.argTypes.map((tt: CType<unknown>) => getKoffiType(tt)),
+        )
+        const ptr = koffi.pointer(proto)
+        cbPointerTypes[i] = ptr
+        return ptr
+      }
+      return getKoffiType(a)
+    })
+
+    const retType = getKoffiType(def.returns)
+    const fn = lib.func(name, retType, argTypes)
+
+    symbols[name] = def.async
+      ? (...callArgs: unknown[]) => {
+          const wrapped = wrapCallbacks(callArgs, callbackDefs, cbPointerTypes, registered)
+          return new Promise<unknown>((resolve, reject) =>
+            fn.async(...wrapped, (err: Error | null, result: unknown) =>
+              err ? reject(err) : resolve(result),
+            ),
+          )
+        }
+      : (...callArgs: unknown[]) => fn(...wrapCallbacks(callArgs, callbackDefs, cbPointerTypes, registered))
+  }
+
+  // NO FinalizationRegistry on koffi callbacks. C owns the function
+  // pointer indefinitely (stored callbacks, signal handlers, etc.); GC-driven
+  // unregister races with a live C-side caller. Lifetime is bound to the
+  // library and released in close().
+  let closed = false
+  function close() {
+    if (closed) return  // idempotent: safe to call after `using` already disposed
+    closed = true
+    for (const reg of registered) {
+      try { koffi.unregister(reg as unknown as Parameters<typeof koffi.unregister>[0]) } catch { /* already gone */ }
+    }
+    registered.length = 0
+    const maybeLib = lib as unknown as { unload?: () => void }
+    if (typeof maybeLib.unload === 'function') maybeLib.unload()
+  }
+
+  return {
+    symbols: symbols as InferLibrary<S>['symbols'],
+    close,
+    [Symbol.dispose]: close,
+    [Symbol.asyncDispose]() { return Promise.resolve(close()) },
+  }
+}
+
+function wrapCallbacks(
+  args: unknown[],
+  defs: CallbackDef[],
+  ptrTypes: Record<number, IKoffiCType>,
+  registered: IKoffiCType[],
+): unknown[] {
+  if (defs.length === 0) return args
+  const wrapped = [...args]
+  for (const { i } of defs) {
+    const userFn = args[i] as (...a: unknown[]) => unknown
+    const reg = koffi.register(userFn, ptrTypes[i]!)
+    registered.push(reg as unknown as IKoffiCType)
+    wrapped[i] = reg
+  }
+  return wrapped
+}

package/src/adapters/node.ts

@@ -0,0 +1,177 @@
+import type { SymbolsSchema, InferLibrary } from '../define.js'
+import type { CCallback, CType, CTypeKind, CoreT } from '../types.js'
+import { dlopen as koffiDlopen, t as koffiT, type KoffiT } from './koffi.js'
+import { runtimeHint } from './hints.js'
+
+export type { InferLibrary, KoffiT }
+
+// node:ffi ABI broken in Node 26.3.0 (every call reports "expected 0 arguments").
+// Bump once a release ships the fix.
+export const NODE_FFI_STABLE_VERSION = Infinity
+
+export const t: KoffiT = koffiT
+
+const nodeMajor = parseInt(process.versions.node.split('.')[0] ?? '0', 10)
+
+type FfiState = 'unavailable' | 'needs-flag' | 'available-but-incomplete' | 'available'
+
+interface NodeFFIFunctionDef {
+  parameters: readonly string[]
+  result: string
+}
+interface NodeFFIDynamicLibrary {
+  readonly functions: Record<string, (...args: unknown[]) => unknown>
+  registerCallback(def: NodeFFIFunctionDef, fn: (...args: unknown[]) => unknown): unknown
+  unregisterCallback(handle: unknown): void
+  close(): void
+}
+interface NodeFFIModule {
+  dlopen(path: string, schema: Record<string, NodeFFIFunctionDef>): {
+    lib: NodeFFIDynamicLibrary
+    functions: Record<string, (...args: unknown[]) => unknown>
+  }
+}
+
+let nodeFfi: NodeFFIModule | null = null
+
+async function detectNodeFFI(): Promise<FfiState> {
+  if (nodeMajor < 26) return 'unavailable'
+
+  try {
+    // @ts-expect-error — node:ffi has no published type definitions yet
+    const mod = (await import('node:ffi')) as { default: NodeFFIModule } & NodeFFIModule
+    nodeFfi = (mod.default ?? mod) as NodeFFIModule
+    return nodeMajor >= NODE_FFI_STABLE_VERSION ? 'available' : 'available-but-incomplete'
+  } catch (e: unknown) {
+    const code = (e as NodeJS.ErrnoException).code
+    if (code === 'ERR_EXPERIMENTAL_FEATURE_NOT_ENABLED') return 'needs-flag'
+    if (code === 'ERR_UNKNOWN_BUILTIN_MODULE' && nodeMajor >= 26) return 'needs-flag'
+    return 'unavailable'
+  }
+}
+
+const ffiState = await detectNodeFFI()
+
+if (ffiState === 'needs-flag') throw new Error(
+  '[unffi] Node.js native FFI is available in this version but requires the --experimental-ffi flag.\n' +
+  '  Run your script with: node --experimental-ffi <script.mjs>\n' +
+  '  Docs: https://nodejs.org/api/ffi.html',
+)
+
+if (ffiState === 'available-but-incomplete') {
+  process.emitWarning(
+    `node:ffi is available in Node ${process.versions.node} but its function-call ABI is not ` +
+    'yet complete (wrapped functions report "expected 0 arguments"). Falling back to koffi. ' +
+    'Upgrade to a newer Node release once node:ffi stabilises.',
+    'UnffiWarning',
+  )
+}
+
+const coreNodeFfiTypes: Record<CTypeKind, string> = {
+  void:     'void',
+  bool:     'bool',
+  i8:       'int8',    i16: 'int16',   i32: 'int32',   i64: 'int64',
+  u8:       'uint8',   u16: 'uint16',  u32: 'uint32',  u64: 'uint64',
+  f32:      'float32', f64: 'float64',
+  cstring:  'string',
+  pointer:  'pointer',
+  buffer:   'buffer',
+  function: 'function',
+}
+
+function nodeFfiTypeFor(kind: string): string {
+  const mapped = coreNodeFfiTypes[kind as CTypeKind]
+  if (mapped !== undefined) return mapped
+  throw new Error(`[unffi/node] Unsupported FFI type "${kind}". ${runtimeHint(kind, 'node')}`)
+}
+
+type CallbackDef = { i: number; cb: CCallback<readonly CType<unknown>[], CType<unknown>> }
+
+function nativeDlopen<const S extends SymbolsSchema>(path: string, schema: S): InferLibrary<S> {
+  const ffi = nodeFfi
+  if (!ffi) throw new Error('[unffi/node] node:ffi module not loaded')
+
+  const ffiSchema: Record<string, NodeFFIFunctionDef> = {}
+  const callbackDefs: Record<string, CallbackDef[]> = {}
+
+  for (const [name, def] of Object.entries(schema)) {
+    ffiSchema[name] = {
+      parameters: def.args.map((a: CType<unknown>) => nodeFfiTypeFor(a.kind)),
+      result:     nodeFfiTypeFor(def.returns.kind),
+    }
+    const cbs = def.args
+      .map((a: CType<unknown>, i: number) =>
+        a.kind === 'function' ? { i, cb: a as CCallback<readonly CType<unknown>[], CType<unknown>> } : null,
+      )
+      .filter((x): x is CallbackDef => x !== null)
+    if (cbs.length > 0) callbackDefs[name] = cbs
+  }
+
+  const handle = ffi.dlopen(path, ffiSchema)
+  const liveCallbacks: unknown[] = []
+  const symbols: Record<string, (...args: unknown[]) => unknown> = {}
+
+  for (const [name, def] of Object.entries(schema)) {
+    const rawFn = handle.functions[name]
+    if (!rawFn) throw new Error(`[unffi/node] symbol "${name}" not found in ${path}`)
+    const cbs = callbackDefs[name]
+
+    if (def.async) {
+      symbols[name] = cbs
+        ? (...callArgs: unknown[]) =>
+            Promise.resolve().then(() => rawFn(...wrapCallbacks(handle.lib, callArgs, cbs, liveCallbacks)))
+        : (...callArgs: unknown[]) => Promise.resolve().then(() => rawFn(...callArgs))
+    } else {
+      symbols[name] = cbs
+        ? (...callArgs: unknown[]) => rawFn(...wrapCallbacks(handle.lib, callArgs, cbs, liveCallbacks))
+        : (rawFn as (...a: unknown[]) => unknown)
+    }
+  }
+
+  // NO FinalizationRegistry on node:ffi callbacks. C owns the
+  // function pointer indefinitely; GC-driven unregister races with a live
+  // C-side caller. Lifetime is bound to the library, freed in close().
+  let closed = false
+  function close() {
+    if (closed) return  // idempotent: safe to call after `using` already disposed
+    closed = true
+    for (const h of liveCallbacks) handle.lib.unregisterCallback(h)
+    liveCallbacks.length = 0
+    handle.lib.close()
+  }
+
+  return {
+    symbols: symbols as InferLibrary<S>['symbols'],
+    close,
+    [Symbol.dispose]: close,
+    [Symbol.asyncDispose]() { return Promise.resolve(close()) },
+  }
+}
+
+function wrapCallbacks(
+  lib: NodeFFIDynamicLibrary,
+  args: unknown[],
+  defs: CallbackDef[],
+  liveCallbacks: unknown[],
+): unknown[] {
+  const wrapped = [...args]
+  for (const { i, cb } of defs) {
+    const handle = lib.registerCallback(
+      {
+        parameters: cb.argTypes.map((a: CType<unknown>) => nodeFfiTypeFor(a.kind)),
+        result:     nodeFfiTypeFor(cb.returnType.kind),
+      },
+      args[i] as (...a: unknown[]) => unknown,
+    )
+    liveCallbacks.push(handle)
+    wrapped[i] = handle
+  }
+  return wrapped
+}
+
+export function dlopen<const S extends SymbolsSchema>(path: string, schema: S): InferLibrary<S> {
+  if (ffiState === 'available') return nativeDlopen(path, schema)
+  return koffiDlopen(path, schema)
+}
+
+export type { CoreT }

package/src/define.ts

@@ -0,0 +1,36 @@
+import type { CType, CCallback, InferCType, InferTuple } from './types.js'
+
+export interface SymbolDef {
+  readonly args: readonly CType<any>[]
+  readonly returns: CType<any>
+  readonly async?: boolean
+}
+
+export type SymbolsSchema = Record<string, SymbolDef>
+
+type InferReturn<S extends SymbolDef> =
+  S['async'] extends true
+    ? Promise<InferCType<S['returns']>>
+    : InferCType<S['returns']>
+
+type MapArg<T extends CType<any>> =
+  T extends CCallback<infer A extends readonly CType<any>[], infer R extends CType<any>>
+    ? (...args: InferTuple<A>) => InferCType<R>
+    : InferCType<T>
+
+type MapArgs<T extends readonly CType<any>[]> =
+  T extends readonly []
+    ? []
+    : T extends readonly [infer H extends CType<any>, ...infer R extends CType<any>[]]
+      ? [MapArg<H>, ...MapArgs<R>]
+      : { [K in keyof T]: T[K] extends CType<any> ? MapArg<T[K]> : never }
+
+export type InferSymbolFn<S extends SymbolDef> =
+  (...args: MapArgs<[...S['args']]>) => InferReturn<S>
+
+export type InferLibrary<S extends SymbolsSchema> = {
+  readonly symbols: { readonly [K in keyof S]: InferSymbolFn<S[K]> }
+  close(): void
+  [Symbol.dispose](): void
+  [Symbol.asyncDispose](): Promise<void>
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// Fallback entry for environments that don't resolve export conditions.
+// Bun, Deno, and Node should get their dedicated adapters via package.json exports.
+export { t } from './types.js'
+export type { CType, CCallback, CTypeKind, Ptr, InferCType, InferTuple } from './types.js'
+export type { SymbolDef, SymbolsSchema, InferLibrary, InferSymbolFn } from './define.js'
+
+import type { SymbolsSchema, InferLibrary } from './define.js'
+
+export async function dlopen<const S extends SymbolsSchema>(
+  path: string,
+  schema: S,
+): Promise<InferLibrary<S>> {
+  if ('Bun' in globalThis) {
+    const { dlopen: bunDlopen } = await import('./adapters/bun.js')
+    return bunDlopen(path, schema)
+  }
+  if ('Deno' in globalThis) {
+    const { dlopen: denoDlopen } = await import('./adapters/deno.js')
+    return denoDlopen(path, schema)
+  }
+  // Fallback: node adapter (tries native node:ffi, then koffi) — Bun → Deno → Node → koffi
+  const { dlopen: nodeDlopen } = await import('./adapters/node.js')
+  return nodeDlopen(path, schema)
+}

package/src/types.ts

@@ -0,0 +1,83 @@
+export interface CType<T> {
+  readonly _type: T
+  readonly kind: CTypeKind
+}
+
+export type CTypeKind =
+  | 'void' | 'bool'
+  | 'i8' | 'i16' | 'i32' | 'i64'
+  | 'u8' | 'u16' | 'u32' | 'u64'
+  | 'f32' | 'f64'
+  | 'cstring' | 'pointer' | 'buffer'
+  | 'function'
+
+declare const PtrBrand: unique symbol
+export type Ptr = bigint & { readonly [PtrBrand]: true }
+
+function c<T>(kind: CTypeKind): CType<T> {
+  return { kind } as unknown as CType<T>
+}
+
+export type InferCType<T extends CType<any>> = T extends CType<infer U> ? U : never
+
+export type InferTuple<T extends readonly CType<any>[]> =
+  T extends readonly []
+    ? []
+    : T extends readonly [infer H extends CType<any>, ...infer R extends CType<any>[]]
+      ? [InferCType<H>, ...InferTuple<R>]
+      : { [K in keyof T]: T[K] extends CType<infer U> ? U : never }
+
+export interface CCallback<
+  Args extends readonly CType<any>[],
+  Ret extends CType<any>,
+> extends CType<(...args: InferTuple<Args>) => InferCType<Ret>> {
+  readonly kind: 'function'
+  readonly argTypes: Args
+  readonly returnType: Ret
+}
+
+export interface CoreT {
+  readonly void:    CType<void>
+  readonly bool:    CType<boolean>
+  readonly i8:      CType<number>
+  readonly i16:     CType<number>
+  readonly i32:     CType<number>
+  readonly i64:     CType<bigint>
+  readonly u8:      CType<number>
+  readonly u16:     CType<number>
+  readonly u32:     CType<number>
+  readonly u64:     CType<bigint>
+  readonly f32:     CType<number>
+  readonly f64:     CType<number>
+  readonly cstring: CType<string>
+  readonly pointer: CType<Ptr | null>
+  readonly buffer:  CType<ArrayBufferView>
+  fn<const Args extends readonly CType<any>[], const Ret extends CType<any>>(
+    args: Args,
+    returns: Ret,
+  ): CCallback<Args, Ret>
+}
+
+export const t: CoreT = {
+  void:    c<void>('void'),
+  bool:    c<boolean>('bool'),
+  i8:      c<number>('i8'),
+  i16:     c<number>('i16'),
+  i32:     c<number>('i32'),
+  i64:     c<bigint>('i64'),
+  u8:      c<number>('u8'),
+  u16:     c<number>('u16'),
+  u32:     c<number>('u32'),
+  u64:     c<bigint>('u64'),
+  f32:     c<number>('f32'),
+  f64:     c<number>('f64'),
+  cstring: c<string>('cstring'),
+  pointer: c<Ptr | null>('pointer'),
+  buffer:  c<ArrayBufferView>('buffer'),
+  fn<const Args extends readonly CType<any>[], const Ret extends CType<any>>(
+    args: Args,
+    returns: Ret,
+  ): CCallback<Args, Ret> {
+    return { kind: 'function', argTypes: args, returnType: returns } as unknown as CCallback<Args, Ret>
+  },
+}