ffi

type NativeTypeName = | 'void' | 'bool' | 'u8' | 'i8' | 'u16' | 'i16' | 'u32' | 'i32' | 'u64' | 'i64' | 'usize' | 'isize' | 'usizeBig' | 'isizeBig' | 'f32' | 'f64' | 'pointer' | 'ignoredPointer' | 'buffer'

String descriptor for a scalar or pointer-shaped C ABI type.

Integer descriptors use the matching C width. usize and isize marshal results as JavaScript number; use usizeBig or isizeBig when the full pointer-sized range must round-trip as bigint.

pointer represents an opaque void* and crosses JS as NativePointer. buffer passes an ArrayBuffer or typed-array backing-store address as a void* parameter. ignoredPointer is for callbacks that receive a pointer parameter but intentionally do not materialize it in JavaScript.

type NativeTypeDescriptor = NativeTypeName | StructType

Native type descriptor accepted in parameter and result positions.

structType() values may be used by dlopen() for by-value struct parameters and return values. FfiCallback does not currently support struct parameters or struct returns.

type NativeSymbolMap = Record<string, NativeSymbolSpec>

Map of C symbol names to native call signatures.

type NativeBindings<TSymbols extends NativeSymbolMap> = { [K in keyof TSymbols]: (...args: any[]) => any; }

Callable JavaScript wrappers for symbols loaded from a dynamic library.

The runtime validates and marshals arguments according to the symbol's descriptor on each call. Synchronous symbols return their native result directly; symbols marked async: true return a Promise.

type NativeSymbolPointers<TSymbols extends NativeSymbolMap> = { [K in keyof TSymbols]: ArrayBuffer; }

Raw native code pointers for symbols loaded from a dynamic library.

These pointers are useful when a C API needs another function pointer, but they should not be called or dereferenced manually.

type NativePointer = ArrayBuffer | ArrayBufferView | null

A native pointer value: an 8-byte ArrayBuffer holding the address as a little-endian u64, or null for the C null pointer.

ArrayBufferView values may be passed where a pointer to the view's first byte is required. The view's byteOffset is included in the address.

type StructFieldTuple = readonly [name: string, type: NativeTypeDescriptor]

Tuple-form field descriptor accepted by structType().

type StructField = StructFieldTuple | StructFieldDescriptor

Field descriptor accepted by structType().

interface NativeSymbolSpec {

Native function signature metadata passed to dlopen().

A symbol descriptor maps the JavaScript call boundary to the native ABI. parameters defaults to an empty list only when an empty array is supplied; each entry must be a native type descriptor. result describes the return type and should be 'void' for functions that do not return a value.

Properties

interface DynamicLibrary<TSymbols extends NativeSymbolMap = NativeSymbolMap> {

Handle returned by dlopen().

The handle keeps the native library open for as long as any bound function may be called. symbols contains callable wrappers, while pointers contains raw pointer-sized buffers for the resolved symbol addresses.

Properties

interface StructFieldInfo {

Metadata for one field in a StructType.

Properties

interface StructType {

By-value C struct descriptor returned by structType().

Struct values are represented as ArrayBuffers containing the native byte layout. The descriptor can allocate a correctly sized buffer, read and write fields, report offsets, and be used as a dlopen() parameter or result descriptor.

Readonly Properties

Methods

interface StructFieldDescriptor {

Object-form field descriptor accepted by structType().

Properties

interface FfiCallbackHandle {

Callback object returned by new FfiCallback().

Readonly Properties

Methods

interface PointerApi {

Pointer and raw-memory helper API exposed as Pointer.

Pointer helpers dereference raw addresses. They do not validate that the address is allocated, correctly aligned, or large enough for the requested access.

Methods

const Pointer: PointerApi

Namespace of pointer and raw-memory helpers.

const FfiCallback: { new ( spec: Pick<NativeSymbolSpec, 'parameters' | 'result'>, callback: (...args: any[]) => unknown, ): FfiCallbackHandle; }

Native callback constructor.

Constructed callbacks expose a native function pointer and must be retained for as long as native code may call them. The callback may be closed explicitly or with a using declaration.

import { FfiCallback } from 'fino:ffi';

using cmp = new FfiCallback(
  { parameters: ['pointer', 'pointer'], result: 'i32' },
  (left, right) => 0,
);

nativeApi.symbols.registerComparator(cmp.pointer);

function structType( fields: readonly StructField[], options?: { size?: number; align?: number }, ): StructType

Build a by-value struct descriptor from field layout metadata.

Fields may be declared as [name, type] tuples or as objects with explicit offset and size metadata. Normal fields are naturally aligned by default. Object fields with type: 'bytes' add explicit padding and require size.

import { structType } from 'fino:ffi';

const Point = structType([
  ['x', 'i32'],
  ['y', 'i32'],
]);

const point = Point.alloc();
Point.set(point, 'x', 12);
Point.set(point, 'y', -3);

function dlopen<TSymbols extends NativeSymbolMap = NativeSymbolMap>( path: string | null, symbols: TSymbols, ): DynamicLibrary<TSymbols>

Open a dynamic library and bind the requested symbols.

path may be null to resolve symbols from the current process. The returned handle exposes callable wrappers in symbols and raw symbol addresses in pointers.

import { dlopen } from 'fino:ffi';

const libc = dlopen('/usr/lib/libSystem.B.dylib', {
  strlen: { parameters: ['buffer'], result: 'usize' },
});

const input = new TextEncoder().encode('hello\0');
console.log(libc.symbols.strlen(input));

function ffiFunction( pointer: NativePointer | bigint, definition: NativeSymbolSpec, ): (...args: any[]) => any

Bind a function pointer obtained at runtime.

dlopen() can only reach symbols by name. Function pointers handed back by native code have no name to look up: vkGetInstanceProcAddr results, callback fields read out of a C struct, and FfiCallback.pointer all need this instead.

pointer accepts a pointer buffer, an ArrayBufferView over one, or a BigInt address. The definition is the same shape dlopen() takes for a single symbol, including async, fast, and variadic.

The returned function keeps nothing alive. Whatever provides the code — a DynamicLibrary handle, an FfiCallback — must be retained for as long as the function may be called, or the call will jump into freed memory.

import { dlopen, ffiFunction } from 'fino:ffi';

const libc = dlopen('/usr/lib/libSystem.B.dylib', {
  strlen: { parameters: ['buffer'], result: 'usize' },
});

const strlen = ffiFunction(libc.pointers.strlen, {
  parameters: ['buffer'],
  result: 'usizeBig',
});

console.log(strlen(new TextEncoder().encode('hello\0')));