bun-ffi-structs

bun-ffi-structs

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

• Type-safe struct definitions with primitives (u8, u16, u32, u64, i16, i32, i64, f32, f64, bool_u8, bool_u32, pointer)
• Enums with custom base types and bidirectional mapping
• Nested structs (inline or as pointers)
• Arrays of primitives, enums, structs, and object pointers
• Fixed little-endian layout with size-based alignment tested on x64 and arm64
• Field options: optional, defaults, validation, transforms (packTransform, unpackTransform)
• Conditional fields for platform-specific layouts
• mapValue/reduceValue transformations for input/output type conversions
• Object pointers for referencing external objects with .ptr property
• Allocation utilities with pre-allocated sub-buffers for arrays
• C strings (null-terminated) and raw string pointers
• Reusable decoding into caller-owned objects and DataView storage
• Reusable primitive lists with packListInto

Installation

bun install bun-ffi-structs

Pure primitive layouts work on Node.js without FFI flags. Pointer-backed operations require Node.js 26.1 or newer with --experimental-ffi; when using Node's Permission Model, also pass --permission --allow-ffi.

For local development, run bun run build, then use scripts/link-dev.sh <target-project-root> to symlink this package into another project's node_modules.

Usage

See examples/README.md for runnable examples demonstrating various features.

import { defineStruct, defineEnum, allocStruct, objectPtr } from "bun-ffi-structs"

const ColorEnum = defineEnum({ RED: 0, GREEN: 1, BLUE: 2 })

const PositionStruct = defineStruct([
  ["x", "f32"],
  ["y", "f32"],
  ["z", "f32"],
])

const ObjectStruct = defineStruct([
  ["id", "u32"],
  ["position", PositionStruct],
  ["color", ColorEnum],
  ["count", "u32", { lengthOf: "items" }],
  ["items", ["u32"]],
])

const buffer: ArrayBuffer = ObjectStruct.pack({
  id: 42,
  position: { x: 1.0, y: 2.0, z: 3.0 },
  color: "BLUE",
  items: [10, 20, 30],
})

const unpacked = ObjectStruct.unpack(buffer)
// -> resolves to type {
//   id: number
//   position: { x: number, y: number, z: number }
//   color: "RED" | "GREEN" | "BLUE"
//   items: Iterable<number>
//   count?: number | null | undefined
// }

Reusable Storage

Definitions without a top-level reduceValue expose unpackInto(view, target, offset = 0). The offset is relative to the supplied DataView, the complete struct must fit before any target mutation occurs, and the same target is returned. Struct defaults are reapplied before decoding, mapValue is not called, and unrelated target properties remain unless overwritten by a struct default. Nested values, strings, and arrays can still allocate.

const CursorStruct = defineStruct([
  ["row", "u32"],
  ["col", "u32"],
])

const packed = CursorStruct.pack({ row: 4, col: 8 })
const cursor = {}
CursorStruct.unpackInto(new DataView(packed), cursor)

Option-free definitions containing only required, non-pointer primitive fields expose packListInto(objects, view, offset, options?):

const buffer = new ArrayBuffer(CursorStruct.size * 2)
CursorStruct.packListInto(
  [
    { row: 1, col: 2 },
    { row: 3, col: 4 },
  ],
  new DataView(buffer),
  0,
)

packListInto deliberately excludes enums, pointers, strings, arrays, defaults, transforms, validation, mapping, reducers, and nested structs. Those definitions require stronger dirty-buffer or pointer-owner semantics than reusable primitive storage.

Hot required-primitive pack, packInto, packList, packListInto, unpack, and unpackInto paths are generated after a measured warmup threshold. Primitive unpackList definitions with reduceValue receive equivalent specialization while preserving the reducer callback. Environments that disable string code generation automatically continue on the generic implementations.