toondb

Official JavaScript SDK for communicating with a TOONDB instance.

Overview

toondb provides a clean client for:

• service health checks
• collection management
• CRUD operations
• schema updates
• TOON dumps
• bridge-compatible action execution

TOONDB Instance Setup

To create and run a TOONDB database instance, use the main TOONDB project:

• github.com/lythelab/toondb

This SDK assumes you already have a running TOONDB service URL and credentials.

Requirements

• Node.js >=18

Installation

npm install toondb

Quick Start

import { ToonDBClient } from "toondb";

const client = new ToonDBClient({
  baseUrl: "https://your-toondb-service-url",
  username: "your-username",
  password: "your-password",
});

const health = await client.health();
console.log(health);

Configuration

Explicit configuration

const client = new ToonDBClient({
  baseUrl: "https://example.toondb.io",
  username: "amit",
  password: "amit098",
  timeoutMs: 30000, // optional
});

Environment fallback

If omitted in constructor options, SDK auto-loads values from env vars:

• TOONDB_URL
• TOONDB_USER or TOONDB_USERNAME
• TOONDB_PASS or TOONDB_PASSWORD

// works if env vars are set
const client = new ToonDBClient();

API Reference

Health

• health()

Collection operations

• createCollection(collection, schema)
• updateCollectionSchema(collection, schema)
• dump(collection) -> returns TOON string

Document operations

• insert(collection, doc)
• find(collection, filter?)
• update(collection, filter, patch)
• delete(collection, filter)

Bridge-compatible operations

• bridge(request)
• execute(action, payload?)
• shutdown()

Supported bridge actions:

• create_collection
• insert
• update
• update_schema
• find
• delete
• dump
• shutdown

Usage Example (CRUD)

await client.createCollection("users", {
  fields: { name: "string", age: "number", active: "boolean" },
  indexed_fields: ["name"],
});

await client.insert("users", { name: "milo", age: 7, active: true });

const found = await client.find("users", {
  conditions: [{ field: "name", op: "eq", value: "milo" }],
});

await client.update(
  "users",
  { conditions: [{ field: "name", op: "eq", value: "milo" }] },
  { age: 8 }
);

const toonDump = await client.dump("users");
console.log(toonDump);

Error Handling

The SDK throws typed errors:

• ToonDBAuthError for auth failures
• ToonDBResponseError for API/server response failures
• ToonDBNetworkError for transport/network failures

import { ToonDBAuthError, ToonDBNetworkError } from "toondb";

try {
  await client.health();
} catch (err) {
  if (err instanceof ToonDBAuthError) {
    console.error("Invalid credentials");
  } else if (err instanceof ToonDBNetworkError) {
    console.error("Network issue");
  } else {
    console.error(err);
  }
}

Development

Run tests:

npm test

Run smoke example:

TOONDB_URL=http://127.0.0.1:6767 TOONDB_USER=amit TOONDB_PASS=amit098 npm run smoke

Smoke script location:

• examples/smoke.js

Contributing

Please see:

• CONTRIBUTING.md