Dexie Cloud SDK

Official server-side JavaScript/TypeScript SDK for Dexie Cloud — local-first database with sync.

Features

• Transparent auth — configure credentials once, tokens are managed automatically
• Impersonation — act as any user with db.asUser()
• Blob handling — automatic offloading of large strings and binaries
• TSON support — Date, Map, Set, BigInt serialized out of the box
• Multi-environment — Node.js, Deno, Cloudflare Workers

Installation

npm install dexie-cloud-sdk

Quick Start

import { DexieCloudClient } from 'dexie-cloud-sdk';
import { readFileSync } from 'fs';

// 1. Read credentials from dexie-cloud.key (generated by `npx dexie-cloud connect`)
const keys = JSON.parse(readFileSync('dexie-cloud.key', 'utf-8'));
const dbUrl = Object.keys(keys)[0];
const { clientId, clientSecret } = keys[dbUrl];

// 2. Create client and database session
const client = new DexieCloudClient('https://dexie.cloud');
const db = client.db(dbUrl, { clientId, clientSecret });

// 3. Use it — no tokens to manage!
const items = await db.data.list('todoItems');
console.log(items);

await db.data.create('todoItems', {
  title: 'Buy milk',
  done: false,
});

Impersonation

Act as a specific user (requires IMPERSONATE scope on the client):

const userDb = db.asUser({
  sub: 'user@example.com',
  email: 'user@example.com',
});

// All operations run as that user
const items = await userDb.data.list('todoItems');
await userDb.data.create('todoItems', { title: 'User task', done: false });

API

client.db(dbUrl, credentials)

Creates a DatabaseSession with automatic token management.

const db = client.db('https://xxxxxxxx.dexie.cloud', {
  clientId: '...',
  clientSecret: '...',
});

Tokens are cached in-memory and refreshed automatically when within 5 minutes of expiry.

db.data

CRUD operations on database tables:

await db.data.list('table');                          // List all
await db.data.list('table', { realm: 'realmId' });   // Filter by realm
await db.data.get('table', 'id');                     // Get one
await db.data.create('table', { ... });               // Create
await db.data.replace('table', 'id', { ... });        // Full replace (PUT)
await db.data.delete('table', 'id');                   // Delete
await db.data.bulkCreate('table', [{ ... }, ...]);    // Bulk create

db.blobs

Binary blob operations:

const ref = await db.blobs.upload(uint8Array, 'image/png');
const { data, contentType } = await db.blobs.download(ref);

db.asUser(claims)

Returns a new DatabaseSession impersonating a user:

const userDb = db.asUser({ sub: 'user@example.com', email: 'user@example.com' });

Client Initialization

// Simple
const client = new DexieCloudClient('https://dexie.cloud');

// Full config
const client = new DexieCloudClient({
  serviceUrl: 'https://dexie.cloud',
  dbUrl: 'https://xxxxxxxx.dexie.cloud',
  blobHandling: 'auto',      // 'auto' | 'lazy'
  maxStringLength: 32768,     // Strings longer than this are offloaded to blobs
  timeout: 30000,
  debug: true,
});

Health Monitoring

await client.waitForReady(60000);
const status = await client.getStatus();
const isReady = await client.isReady();

Error Handling

import {
  DexieCloudError,
  DexieCloudAuthError,
  DexieCloudNetworkError,
} from 'dexie-cloud-sdk';

try {
  await db.data.list('todoItems');
} catch (error) {
  if (error instanceof DexieCloudAuthError) {
    console.log('Auth failed:', error.message);
  } else if (error instanceof DexieCloudError) {
    console.log('API error:', error.status, error.message);
  }
}

E2E Testing

The repo includes a Docker-based test stack:

# Start stack
docker compose -f docker-compose.test.yml up -d

# Run E2E tests
pnpm run test:e2e

# Stop
docker compose -f docker-compose.test.yml down -v

License

MIT — see LICENSE for details.

Links

• Dexie.js — IndexedDB wrapper
• Dexie Cloud — Sync service
• SDK Documentation — Full docs
• GitHub — Source code