@jsondb-cloud/client

The official JavaScript/TypeScript SDK for jsondb.cloud — a hosted JSON document database.

Install

npm install @jsondb-cloud/client

Quick Start

import { JsonDB } from "@jsondb-cloud/client";

const db = new JsonDB({ apiKey: "jdb_sk_live_xxxx" });
const users = db.collection<{ name: string; email: string }>("users");

// Create
const alice = await users.create({ name: "Alice", email: "[email protected]" });

// Read
const user = await users.get(alice._id);

// List with filter
const admins = await users.list({
  filter: { role: "admin" },
  sort: "-$createdAt",
  limit: 10,
});

// Update
await users.patch(alice._id, { email: "[email protected]" });

// Delete
await users.delete(alice._id);

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | Required. API key (jdb_sk_live_... or jdb_sk_test_...) | | project | string | "v1" | Project identifier | | baseUrl | string | "https://api.jsondb.cloud" | API base URL | | timeout | number | 30000 | Request timeout in milliseconds | | retry | object | { enabled: true, maxRetries: 3 } | Retry with exponential backoff | | headers | Record<string, string> | {} | Extra headers for every request | | fetch | typeof fetch | globalThis.fetch | Custom fetch implementation |

API

Collection CRUD

• create(doc, options?) — Create a document
• get(id) — Get a document by ID
• list(options?) — List documents with filtering, sorting, pagination
• count(filter?) — Count documents matching an optional filter
• update(id, doc) — Replace a document entirely
• patch(id, partial) — Partial update (merge-patch)
• jsonPatch(id, operations) — Apply JSON Patch operations (RFC 6902)
• delete(id) — Delete a document

Query Builder

• where(field, op, value) — Start a fluent query (==, !=, >, >=, <, <=, contains, in)
• orderBy(field) — Sort results
• limit(n) / offset(n) — Paginate
• select(...fields) — Pick fields
• exec() — Execute the query

Bulk Operations

• bulk(operations) — Execute mixed bulk operations
• bulkCreate(docs) — Create multiple documents

Schema Validation

• setSchema(schema) — Set a JSON Schema for the collection
• getSchema() — Get the current schema
• removeSchema() — Remove the schema
• validate(doc) — Validate a document without storing

Version History

• listVersions(id) — List all versions of a document
• getVersion(id, version) — Get a document at a specific version
• restoreVersion(id, version) — Restore to a specific version
• diffVersions(id, from, to) — Diff two versions

Webhooks

• createWebhook(options) — Register a webhook
• listWebhooks() — List all webhooks
• getWebhook(id) — Get webhook details with recent deliveries
• updateWebhook(id, options) — Update a webhook
• deleteWebhook(id) — Delete a webhook
• testWebhook(id) — Send a test event

Import / Export

• importDocuments(docs, options?) — Import documents (fail/skip/overwrite on conflict)
• exportDocuments(options?) — Export all documents

Real-time Streaming

• stream(options?) — Subscribe to real-time changes via SSE
  • Events: created, updated, deleted, change

Error Handling

import { JsonDB, NotFoundError, ValidationError } from "@jsondb-cloud/client";

try {
  const user = await users.get("nonexistent");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log("Document not found:", err.documentId);
  }
}

All errors extend JsonDBError which has .code, .status, and .details properties.

| Error | Status | Code | |-------|--------|------| | NotFoundError | 404 | DOCUMENT_NOT_FOUND | | ValidationError | 400 | VALIDATION_FAILED | | ConflictError | 409 | CONFLICT | | UnauthorizedError | 401 | UNAUTHORIZED | | ForbiddenError | 403 | FORBIDDEN | | RateLimitError | 429 | RATE_LIMITED | | QuotaExceededError | 429 | QUOTA_EXCEEDED | | DocumentTooLargeError | 413 | DOCUMENT_TOO_LARGE | | ServerError | 500 | INTERNAL_ERROR |

Documentation

Full documentation at jsondb.cloud/docs.

Related Packages

| Package | Description | |---------|-------------| | @jsondb-cloud/client | JavaScript/TypeScript SDK | | @jsondb-cloud/mcp | MCP server for AI agents | | @jsondb-cloud/cli | CLI tool | | jsondb-cloud (PyPI) | Python SDK |

License

MIT