Bun Adapter

Use Zinc from Bun with bun:ffi

The Bun adapter uses Bun’s built-in bun:ffi module to call the Zinc C ABI directly. No native addon compilation is needed. Bun loads libzinc_core at runtime through its FFI layer.

Installation

Build the core from a source checkout, then set up the adapter:

# From your repository root, import ./adapters/bun/src/index.ts

SharedRegion

import { SharedRegion } from "./adapters/bun/src/index.ts";

create

const region = SharedRegion.create("my-data", 16384);

Creates a new region. Throws on failure.

open

const region = SharedRegion.open("my-data");

Opens an existing region.

buffer

Returns a Buffer backed by the shared memory mapping. Uses bun:ffi’s toBuffer function for zero-copy access.

const buf = region.buffer();
buf.writeFloatLE(3.14, 0);

notify

region.notify();

wait

const ok = region.wait(1000);

Returns true on notification, false on timeout.

close

region.close();

The region also supports Symbol.dispose for using statements:

{
    using region = SharedRegion.open("my-data");
    const buf = region.buffer();
    // region is automatically closed when the block exits
}

Complete example

import { SharedRegion } from "./adapters/bun/src/index.ts";

// Writer
const w = SharedRegion.create("bun-channel", 16384);
const buf = w.buffer();
buf.writeBigInt64LE(42n, 0);
w.notify();

setTimeout(() => w.close(), 5000);

// Reader (separate process)
const r = SharedRegion.open("bun-channel");
if (r.wait(3000)) {
    const data = r.buffer();
    console.log(data.readBigInt64LE(0)); // 42n
}
r.close();

FFI details

Handles are numeric pointers in Bun’s FFI API. zinc_ptr returns the data pointer and toBuffer wraps it without copying. The loader resolves target/release/libzinc_core.{so,dylib} relative to the source checkout.

Keep the region open while any returned buffer is in use. close() is idempotent and later operations on the region throw. tryWait() consumes a pending notification without blocking. Timeouts must be integers between 0 and 2^32 - 1 milliseconds.