JavaScript and TypeScript

The zova-js package provides synchronous and queued asynchronous Node-API bindings with bundled TypeScript declarations. It uses the same native Zova engine and file format as the other bindings.

Install

bun add zova-js
# or
npm install zova-js

Prebuilt packages support Node.js 22 and 24 and Bun on:

• macOS arm64 and x86_64;
• glibc Linux arm64 and x86_64; and
• Windows x86_64 with MSVC.

Electron, Deno, browsers, musl Linux, Windows arm64, and WASM are not claimed in v0.26.1. A supported prebuilt installation does not need Zig, Rust, a C compiler, or an install-time native download.

Synchronous database

Database exposes SQL statements, transactions, savepoints, backup and restore, objects, typed vectors, public graph operations, and bundled extension lifecycle.

import { Database, Step } from "zova-js";

const db = Database.create("app.zova");
db.exec("create table notes(id integer primary key, body text not null)");

const insert = db.prepare("insert into notes(body) values (?1)");
insert.bindText(1, "hello");
if (insert.step() !== Step.Done) {
  throw new Error("insert did not finish");
}
insert.close();

db.transaction((transaction) => {
  transaction.exec("insert into notes(body) values ('committed')");
});

db.close();

Transaction and savepoint callbacks are synchronous. Returning a Promise is rejected before commit, and throwing rolls the scope back.

Queued asynchronous database

AsyncDatabase runs native work on the Node worker pool while preserving FIFO order for each database. It rejects new work after closing begins, waits for already queued work, and closes once.

import { AsyncDatabase } from "zova-js";

const db = AsyncDatabase.create("app.zova");
await db.exec("create table notes(body text)");
const objectId = await db.putObject(
  new TextEncoder().encode("large bytes"),
);
const bytes = await db.getObject(objectId);
console.log(bytes.byteLength);
await db.close();

Queued operations include backup, compact, restore, vector batches and searches, and graph batches and walks. Async transaction callbacks and prepared statement handles are not exposed.

Data mappings

Zova value	JavaScript value
SQL integer, count, or identity	bigint
blob or object bytes	Uint8Array
f32 vector	Float32Array
raw f16 elements	Uint16Array
i8 vector	Int8Array
nullable SQL data	null
absent option	undefined

Ownership and errors

Close Statement, ObjectWriter, and Database values explicitly. Node-API finalizers are fallback cleanup, not the primary lifecycle.

Native failures are exposed as ZovaError with the Zova status name, numeric status, and native message.

import { Database, ZovaError } from "zova-js";

const db = Database.create("app.zova");

try {
  db.exec("select * from missing");
} catch (error) {
  if (error instanceof ZovaError) {
    console.error(error.code, error.status, error.message);
  }
}

db.close();

Advanced opaque graph keys, topology scans, edge payloads, and fresh-build sessions remain C ABI and raw zova-sys capabilities in v0.26.1.