Dexie Cloud SDK

The Dexie Cloud SDK (dexie-cloud-sdk) is a lightweight TypeScript/JavaScript client for interacting with Dexie Cloud services programmatically — without Dexie.js or IndexedDB.

Use it for:

Server-side applications (Node.js, Deno, edge functions)
CLI tools and scripts
Admin dashboards
Data migration and import/export
Any environment where you need REST API access to Dexie Cloud data

Installation

npm install dexie-cloud-sdk

Quick Start

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

// 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];

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

// Use it — no tokens to manage!
const items = await db.data.list('todoItems');
await db.data.create('todoItems', { title: 'Buy milk', done: false });

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

Configuration

const client = new DexieCloudClient({
  serviceUrl: 'https://dexie.cloud',     // Required: Dexie Cloud service URL
  blobHandling: 'auto',                   // 'auto' (default) | 'lazy'
  maxStringLength: 32768,                 // Strings longer than this offload to blobs
  timeout: 30000,                         // Request timeout (ms)
  debug: false                            // Enable debug logging
});

Blob Handling Modes

Mode	Behavior
`auto` (default)	Binary data is automatically uploaded as blobs on write, and BlobRefs are resolved to data on read
`lazy`	Write works like auto, but read returns BlobRef metadata. Call `db.blobs.download(ref)` explicitly

Authentication

The SDK uses client credentials for server-to-server access. Your client_id and client_secret come from dexie-cloud.key, created when you run:

npx dexie-cloud connect https://xxxxxxxx.dexie.cloud

Then create a database session:

const db = client.db(dbUrl, { clientId, clientSecret });

That's it. The session handles token acquisition and renewal transparently.

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 });

Each asUser() call returns a separate session with its own token cache — different impersonations never mix.

Data Operations

All data operations use TSON serialization, preserving rich types like Date, Map, Set, and binary data.

Read

// List all items in a table
const items = await db.data.list('todoItems');

// Get single item by ID
const item = await db.data.get('todoItems', 'item-123');

// Filter by realm
const realmItems = await db.data.list('todoItems', { realm: 'rlm-my-realm' });

Write

// Create
const newItem = await db.data.create('todoItems', {
  title: 'Buy milk',
  done: false,
});

// Replace (full update, PUT semantics)
await db.data.replace('todoItems', 'item-123', {
  title: 'Buy oat milk',
  done: true,
});

// Delete
await db.data.delete('todoItems', 'item-123');

// Bulk create
const items = await db.data.bulkCreate('todoItems', [
  { title: 'Task 1', done: false },
  { title: 'Task 2', done: false },
]);

Binary Data

With blobHandling: 'auto' (default), binary data is handled transparently:

// Write — binary data is uploaded to blob storage automatically
await db.data.create('photos', {
  title: 'Sunset',
  image: new Uint8Array(imageData),  // Uploaded as blob if large enough
});

// Read — BlobRefs are resolved to real data automatically
const photo = await db.data.get('photos', 'photo-123');
console.log(photo.image);  // Uint8Array with actual data

Blob Operations

Direct blob management:

// Upload
const ref = await db.blobs.upload(new Uint8Array([1, 2, 3]), 'application/octet-stream');

// Download
const { data, contentType } = await db.blobs.download(ref);

Health Check

// Quick check
const isReady = await client.isReady();

// Detailed status
const status = await client.getStatus();
console.log(status.healthy, status.ready);

// Wait for service
await client.waitForReady(30000);  // 30s timeout

TSON Support

The SDK uses TSON (Typed JSON) for all data serialization. Rich JavaScript types survive round-trips:

await db.data.create('events', {
  name: 'Meeting',
  date: new Date(),           // Date object — not a string
  attendees: new Set(['A']),  // Set — not an array
  metadata: new Map([         // Map — not an object
    ['key', 'value']
  ]),
  bigNumber: 123456789n       // BigInt
});

Error Handling

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

try {
  await db.data.get('items', 'id');
} catch (error) {
  if (error instanceof DexieCloudAuthError) {
    // Authentication failed — check your client_id/client_secret
  } else if (error instanceof DexieCloudError) {
    console.log(error.status);   // HTTP status code
    console.log(error.message);  // Error description
  }
}