Schema & types

The schema you pass to dlopen is the source of truth. TypeScript infers every argument and return type at compile time — no codegen, no decorators, no type annotations to maintain.

Hover the identifiers to see what TypeScript knows:

import { dlopen, t } from 'unffi'

const lib = await dlopen('./math.dylib', {
  add:   { args: [t.i32, t.i32], returns: t.i32 },
  greet: { args: [t.cstring],    returns: t.cstring },
})

const sum = lib.symbols.add(2, 3)
     
const sum: number

const hello = lib.symbols.greet('world')
      
const hello: string

sum is number, hello is string. TypeScript derives this from t.i32 and t.cstring in the schema alone.

What types are

Each t.* value is a CType<T> token — it carries the C type name and the JS type T as a phantom parameter. dlopen maps the whole schema through InferLibrary<S>:

import { t } from 'unffi'

const i32 = t.i32
     
const i32: CType<number>

const cstr = t.cstring
      
const cstr: CType<string>

const cb = t.fn([t.i32, t.i32], t.i32)
     
const cb: CCallback<readonly [CType<number>, CType<number>], CType<number>>

Primitives

t.cstring — decoded to a JS string on output. On input, unffi encodes the string to a temporary NUL-terminated buffer for the call's duration.

t.pointer — raw address as bigint, or null for a null pointer.

t.buffer — pass any TypedArray or DataView; unffi hands C the backing pointer directly, no copy.

Symbol definition

Each key in the schema is a SymbolDef:

import type { SymbolDef } from 'unffi'

type Sym = SymbolDef
    
type Sym = SymbolDef

async: true makes the bound function return a Promise. Supported on all backends (Bun thread pool, Deno nonblocking, koffi worker pool).

Function pointers — t.fn

t.fn(argTypes, returnType) describes a C function pointer. Pass a plain JS function at the call site — unffi wraps it automatically.

import { dlopen, t } from 'unffi'

const lib = await dlopen('./sort.dylib', {
  sort: {
    args: [t.buffer, t.i32, t.fn([t.i64, t.i64], t.i32)],
    returns: t.void,
  },
})

lib.symbols.sort(new BigInt64Array(4), 4, (a, b) => {
                                         
a: bigint
  return a < b ? -1 : a > b ? 1 : 0
})

The comparator's a and b are typed as bigint because they correspond to t.i64 — JS matches C exactly.

Async symbols

import { dlopen, t } from 'unffi'

const lib = await dlopen('./codec.dylib', {
  compress: { args: [t.buffer, t.i32], returns: t.i32, async: true },
  fast:     { args: [t.i32, t.i32],    returns: t.i32 },
})

const promise = lib.symbols.compress(new Uint8Array(0), 0)
       
const promise: Promise<number>

const value = lib.symbols.fast(1, 2)
      
const value: number

compress is async (thread-pool call). fast is synchronous.

Generated schemas

Shipped OS modules and generated bindings use the same SymbolsSchema shape. You can inspect the exported schema constants, pass them to manual dlopen, or rely on the open*() helpers.

import { coreFoundationSchema } from 'unffi/macos/CoreFoundation'
import { libcSchema } from 'unffi/linux/libc'

const cfReturn = coreFoundationSchema.CFStringGetTypeID.returns

const libcArgs = libcSchema.strlen.args

See System libraries for shipped modules and Binding generation for project-local headers.

Runtime-specific types

t.deno.ptrOf(view)                         // zero-copy pointer from TypedArray
t.deno.readCString(ptr, offset?)           // decode NUL-terminated string
t.deno.readArrayBuffer(ptr, len, offset?)  // read raw bytes