JavaScript / TypeScript SDK

npm install @jsondb-cloud/client

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

const db = new JsonDB({ apiKey: 'jdb_sk_live_...' });

interface User {
  name: string;
  email: string;
  age: number;
}

const users = db.collection<User>('users');

// Create
const alice = await users.create({
  name: 'Alice',
  email: '[email protected]',
  age: 30,
});
console.log(alice._id); // "use_a1b2c3d4e5f6"

// Read
const user = await users.get(alice._id);
console.log(user.name); // "Alice" (typed as string)

// List
const { data, meta } = await users.list({
  filter: { age: { $gte: 18 } },
  sort: '-createdAt',
  limit: 10,
});

// Auto-generated ID
const doc = await users.create({ name: 'Bob', email: '[email protected]', age: 25 });

// Explicit ID
const doc2 = await users.create(
  { name: 'Charlie', email: '[email protected]', age: 28 },
  { id: 'custom-id' },
);

// Full replace (PUT)
await users.update('use_abc123', {
  name: 'Alice Updated',
  email: '[email protected]',
  age: 31,
});

// Merge patch (PATCH) — only send changed fields
await users.patch('use_abc123', { age: 31 });

// JSON Patch (RFC 6902)
await users.jsonPatch('use_abc123', [
  { op: 'replace', path: '/age', value: 31 },
  { op: 'add', path: '/verified', value: true },
]);

await users.delete('use_abc123');

const admins = await users.list({
  filter: {
    role: 'admin',              // exact match
    age: { $gte: 21 },          // operators
    status: { $in: ['active', 'pending'] },
  },
  sort: '-createdAt',            // prefix with - for descending
  limit: 10,
  offset: 0,
  select: ['name', 'email'],    // only return these fields
});

const count = await users.count({ role: 'admin' });
console.log(count); // 42

// Bulk create
const result = await users.bulkCreate([
  { name: 'Charlie', email: '[email protected]', age: 28 },
  { name: 'Dana', email: '[email protected]', age: 35 },
]);
console.log(result.summary); // { total: 2, succeeded: 2, failed: 0 }

// Mixed bulk operations
const result2 = await users.bulk([
  { method: 'POST', body: { name: 'Eve', email: '[email protected]', age: 22 } },
  { method: 'PATCH', id: 'use_abc123', body: { role: 'admin' } },
  { method: 'DELETE', id: 'use_old456' },
]);

// Set a schema
await users.setSchema({
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1 },
    email: { type: 'string', format: 'email' },
  },
  required: ['name', 'email'],
});

// Dry-run validate
const result = await users.validate({ name: '', email: 'not-email' });
console.log(result.valid);  // false
console.log(result.errors); // [{ path: '/name', ... }, { path: '/email', ... }]

// Remove schema
await users.removeSchema();

import {
  JsonDB,
  NotFoundError,
  ValidationError,
  QuotaExceededError,
  RateLimitError,
  JsonDBError,
} from '@jsondb-cloud/client';

try {
  const user = await users.get('nonexistent');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Not found');
  } else if (error instanceof ValidationError) {
    console.log('Validation errors:', error.errors);
  } else if (error instanceof QuotaExceededError) {
    console.log('Quota exceeded');
  } else if (error instanceof RateLimitError) {
    console.log('Rate limited — retry later');
  } else if (error instanceof JsonDBError) {
    console.log('API error:', error.code, error.message);
  }
}

const db = new JsonDB({
  apiKey: 'jdb_sk_live_...',
  namespace: 'default',           // optional, default: 'default'
  baseUrl: 'https://api.jsondb.cloud', // optional

  retry: {
    enabled: true,                // auto-retry on 429/5xx (default: true)
    maxRetries: 3,                // default: 3
    baseDelay: 1000,              // default: 1000ms
    maxDelay: 10000,              // default: 10000ms
  },

  timeout: 30000,                 // default: 30000ms

  headers: {
    'X-Custom-Header': 'value',   // extra headers on every request
  },
});