ZDB

The official ZDB SDK for JavaScript.

How to install

Install for Node.js

Install it with:

# using npm
npm i zdb-sdk
# or using pnpm
pnpm i zdb-sdk
# or using yarn
yarn add zdb-sdk

Next, just import it with:

const { Z } = require("zdb-sdk");

or when you use modules:

import Z from "zdb-sdk";

Install for the browser

For usage in a browser environment, when using a bundler (e.g. Rollup, Vite, or webpack) you can install it with:

# using npm
npm i zdb-sdk
# or using pnpm
pnpm i zdb-sdk
# or using yarn
yarn add zdb-sdk

Next, just import it with:

import Z from "zdb-sdk";

or when you use CommonJS:

const { Z } = require("zdb-sdk");

Install for the browser with a CDN

For fast prototyping we provide a browser-ready bundle. You can import it with:

import Z from "https://unpkg.com/zdb-sdk";
// or
import Z from "https://cdn.jsdelivr.net/npm/zdb-sdk";

NOTE: this bundle is not optimized for production! So don't use it in production!

Getting started

In the example below you can see how to connect to a remote instance of ZDB, authenticating with the database, and issuing queries for creating, updating, and selecting data from records.

This example makes use of top level await, available in modern browsers, Deno and Node.js >= 14.8.

import { Z, RecordId, Table } from "zdb-sdk";

const db = new Z();

// Connect to the database
await db.connect("http://127.0.0.1:8000/rpc");

// Select a specific namespace / database
await db.use({
    namespace: "test",
    database: "test"
});

// Signin as a namespace, database, or root user
await db.signin({
    username: "root",
    password: "root",
});

// Create a new person with a random id
let created = await db.create("person", {
    title: "SuperHeroes",
    name: {
        first: "Peter",
        last: "Parker",
    },
    superpower: true,
});

// Update a person record with a specific id
let updated = await db.merge(new RecordId('person', 'mj'), {
    superpower: false,
});

// Select all people records
let people = await db.select("person");

// Perform a custom advanced query
let groups = await db.query(
    "SELECT superpower, count() FROM $tb GROUP BY superpower",
    {
        tb: new Table("person"),
    },
);

Contributing

Local setup

This is a Bun project, not Node.js. It works across all major runtimes, however.

Supported environments

• Deno
• Node.js
• Bun
• Web Browsers

Requirements

• Bun
• ZDB (for testing)

Build for all supported environments

For Deno, no build is needed. For all other environments run

bun run build.

Code Quality Fixes

bun qa

Code Quality unsafe fixes

bun qau

Run tests for WS

bun test

Run tests for HTTP

ZDB_PROTOCOL=http bun test

PRs

Before you commit, please format and lint your code accordingly to check for errors, and ensure all tests still pass

Local setup

For local development the Bun extension and Biome extension for VSCode are helpful.

Directory structure

• ./biome.json include settings for code quality.
• ./scripts include the build scripts for NPM and JSR.
• ./src includes all source code. ./src/index.ts is the main entrypoint.
• ./dist is build by ./scripts/build.ts and includes the compiled and minified bundles for ESM, CJS and bundled ESM targets.
• ./tests includes all test files.