Node.js Adapter

Use Zinc from Node.js with native N-API bindings

The Node.js adapter uses napi-rs, which compiles a Rust crate into a .node native addon. The addon links directly to zinc-core and exposes a JavaScript class backed by the Rust core.

Installation

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

cd adapters/node
npm ci
npm run build

ZincRegion

import { ZincRegion } from './adapters/node/index.js';

create

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

Creates a new region. Throws if the name already exists or the size is invalid.

open

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

Opens an existing region. Throws if the region does not exist.

asBuffer

Returns a Node.js Buffer backed by the shared memory mapping. No copying occurs.

const buf = region.asBuffer();
buf.writeFloatLE(3.14, 0);
const val = buf.readFloatLE(0);

The buffer points directly into the mmap. Writing to the buffer modifies shared memory immediately.

notify

region.notify();

wait

const ok = region.wait(1000); // returns boolean

Returns true if data was available, false on timeout.

Complete example

import { ZincRegion } from './adapters/node/index.js';

// Writer
const writer = ZincRegion.create("channel", 16384);
const buf = writer.asBuffer();
const view = new Float64Array(buf.buffer, buf.byteOffset, buf.length / 8);

view[0] = 42.0;
writer.notify();

// Keep writer and its buffer alive until readers finish.

// Reader (separate process)
const reader = ZincRegion.open("channel");
const buf2 = reader.asBuffer();
const view2 = new Float64Array(buf2.buffer, buf2.byteOffset, buf2.length / 8);

if (reader.wait(3000)) {
    console.log(view2[0]); // 42.0
}

TypeScript

The package includes TypeScript declarations. The ZincRegion class and all its methods are fully typed.

napi-rs internals

asBuffer() uses napi-rs to wrap the mapping without copying. Its finalizer retains an Arc<SharedRegion> until the buffer is collected. A buffer remains valid after its region object is collected. Node has no explicit close() method; the creator unlinks when both its region object and retained buffers have been released.

tryWait() consumes a pending notification without blocking. wait() returns false on timeout and throws on other failures. Capacities and timeouts must be unsigned 32-bit integers; fractional, negative, and out-of-range values are rejected.