ScopeDB SDK for JavaScript

Query ScopeDB and write rows from server-side JavaScript and TypeScript applications.

Upgrading an existing application? See Upgrade from 0.2 to 0.3, including the move from Ingest to Append.

Install

Requires Node.js 20 or later, or a supported server runtime such as Bun, Next.js server code, or Cloudflare Workers. The package is ESM-only, includes TypeScript declarations, and has no runtime dependencies. Keep API keys in trusted server-side code, outside browser bundles and Next.js Client Components.

npm install scopedb
# or: pnpm add scopedb
# or: bun add scopedb

Run a query

Set SCOPEDB_ENDPOINT and SCOPEDB_API_KEY using the connection guide. Save this program as connect.mjs and run node connect.mjs:

import { Client } from "scopedb";

const endpoint = process.env.SCOPEDB_ENDPOINT;
const apiKey = process.env.SCOPEDB_API_KEY;
if (!endpoint || !apiKey) {
  throw new Error("Set SCOPEDB_ENDPOINT and SCOPEDB_API_KEY.");
}

const client = new Client(endpoint, { apiKey });
const result = await client.query("SELECT 1 AS ready");
console.log(result.toObjects());

query() waits for the result. toObjects() returns rows keyed by column name; integer cells default to bigint. See Read query results for JSON-safe output and timestamp precision.

Write rows

Using the client above and an existing events table with id int and name string columns:

const stream = client.table("events").appendStream().build();
await stream.send({ id: 1, name: "page_view" });

const result = await stream.shutdown();
console.log("Written rows:", result?.num_rows_inserted ?? 0);

send() queues a row; shutdown() waits for pending writes and closes the stream. Use flush() to wait while keeping it open. If you already have NDJSON, use table.append().

Find what you need

| Task | Documentation | | ---------------------------- | ----------------------------------------------------------------------- | | Read query results | Result conversion | | Track or cancel a query | Statement handles | | Read or change table schemas | Catalog | | Encode rows for Append | JSON encodings | | Tune batching and retries | Append streams | | Write logs or telemetry | Telemetry | | Set timeouts or HTTP options | Client configuration | | Inspect a failure | Errors | | Use Next.js, Workers, or Bun | Runtime templates | | Load from CommonJS | Dynamic import |

For complete programs, see the examples. For ScopeQL syntax, see the query guide and language reference. The SDK guide and changelog provide additional context.

Development

Use the pnpm version declared in package.json:

pnpm install --frozen-lockfile
pnpm test
pnpm run check

See the maintainer notes for live integration tests, package validation, and release steps. Report problems through GitHub issues.

License

Licensed under the Apache License, Version 2.0.