@loro-dev/unisqlite

UniSQLite

Universal SQLite adapter for Node.js, Cloudflare Workers, and browsers.

Features

• Cross-platform: Works in Node.js, Cloudflare Workers, and browsers
• Type-safe: Full TypeScript support with strong typing
• Transaction support: Both synchronous and asynchronous transactions
• Connection type detection: Identify and enforce proper transaction usage
• Leader election: Browser adapter uses leader election for multi-tab coordination
• Cloudflare DO Support: Native adapter for Cloudflare Durable Objects' SQLite persistence API

Usage

Standard Usage

import { openStore } from "@loro-dev/unisqlite";

const store = await openStore({ path: "my-database.db" });

// Basic operations
await store.run("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");
await store.run("INSERT INTO users (name) VALUES (?)", ["Alice"]);
const users = await store.query("SELECT * FROM users");

// Transactions
await store.transaction(async (txn) => {
  await txn.run("INSERT INTO users (name) VALUES (?)", ["Bob"]);
  await txn.run("INSERT INTO users (name) VALUES (?)", ["Charlie"]);
});

await store.close();

Cloudflare Durable Objects

For Cloudflare Durable Objects with the new SQLite persistence API:

import { CloudflareDOAdapter, createCloudflareDOAdapter } from "@loro-dev/unisqlite";

export class MyDurableObject extends DurableObject {
  private db: CloudflareDOAdapter;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    // Use the factory function for easy setup
    this.db = createCloudflareDOAdapter(ctx.storage.sql);
  }

  async fetch(request: Request) {
    // Use the adapter like any other UniSQLite connection
    await this.db.run("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)");
    await this.db.run("INSERT INTO users (name) VALUES (?)", ["Alice"]);
    const users = await this.db.query("SELECT * FROM users");

    return Response.json({ users });
  }
}

Connection Types

UniSQLite provides three types of connections with different transaction capabilities:

Direct Connection ("direct")

• Primary database connections
• Can execute both transaction() and asyncTransaction()
• Entry point for all database operations

const store = await openStore({ path: "database.db" });
console.log(store.getConnectionType()); // "direct"

// Both transaction types are supported
await store.transaction(async (txn) => {
  /* sync transaction */
});
await store.asyncTransaction(async (txn) => {
  /* async transaction */
});

Sync Transaction Connection ("syncTxn")

• Created within transaction() calls
• Can call transaction() using itself (for nested operations)
• Cannot call asyncTransaction() - will throw an error

await store.transaction(async (txn) => {
  console.log(txn.getConnectionType()); // "syncTxn"

  // ✅ Allowed: nested transaction using same connection
  await txn.transaction(async (nested) => {
    // nested === txn (same connection)
    await nested.run("INSERT INTO users (name) VALUES (?)", ["user"]);
  });

  // ❌ Not allowed: will throw error
  await txn.asyncTransaction(async (nested) => {
    // Error: "asyncTransaction is not supported in syncTxn connections"
  });
});

Async Transaction Connection ("asyncTxn")

• Created within asyncTransaction() calls
• Can call both transaction() and asyncTransaction() using itself
• Supports timeout configuration and async operations

await store.asyncTransaction(
  async (txn) => {
    console.log(txn.getConnectionType()); // "asyncTxn"

    // ✅ Both transaction types are supported
    await txn.transaction(async (nested) => {
      // nested === txn (same connection)
    });

    await txn.asyncTransaction(async (nested) => {
      // nested === txn (same connection)
    });
  },
  { timeoutMs: 30000 }
);

Browser Storage Backends

The browser adapter supports multiple storage backends for persistence. By default, it uses 'auto' mode which tries each backend in order until one succeeds.

Storage Backend Options

Backend	Description	Requirements
'opfs'	Origin Private File System - best for persistent storage with custom database names	Secure context (HTTPS/localhost), modern browser
'localStorage'	localStorage-backed storage	Path must be 'local' or 'session' only
'memory'	In-memory storage (no persistence)	None
'auto'	Try OPFS → localStorage → memory (default)	None

If you set storageBackend: 'opfs', UniSQLite will not silently fall back — openStore() will throw if OPFS cannot be opened. Use storageBackend: 'auto' if you want automatic fallback.

Using OPFS for Custom Database Names

OPFS is ideal for multi-workspace applications that need separate persistent databases:

import { openStore } from "@loro-dev/unisqlite";

// Each workspace gets its own persistent database
const db = await openStore({
  path: `workspace-${workspaceId}.db`,
  sqlite: {
    loadStrategy: 'cdn',
    storageBackend: 'opfs'  // Use OPFS for custom database names
  }
});

// Check which storage backend is active
const info = db.getSQLiteInfo();
console.log('Storage backend:', info.activeStorageBackend); // 'opfs'

// Or use the dedicated method
console.log('Storage backend:', db.getStorageBackend()); // 'opfs'

Auto Mode (Default)

In 'auto' mode, the adapter tries backends in order and falls back gracefully:

const db = await openStore({
  path: 'my-database.db',
  sqlite: {
    storageBackend: 'auto'  // Default - tries OPFS first
  }
});

// Will use OPFS if available, otherwise falls back
console.log('Using:', db.getStorageBackend()); // 'opfs', 'localStorage', or 'memory'

OPFS VFS Types

SQLite WASM supports multiple OPFS-backed VFS implementations. Configure via sqlite.opfsVfsType:

const db = await openStore({
  path: 'my-database.db',
  sqlite: {
    storageBackend: 'opfs',
    opfsVfsType: 'auto', // 'auto' (default) | 'opfs' | 'sahpool'
  }
});

Note: SQLite WASM OPFS backends are worker-only. When UniSQLite is used from the main thread with storageBackend: 'opfs', it will transparently use SQLite WASM's wrapped-worker API under the hood (i.e. it will start a Worker). There is currently no separate "allow worker" option — requesting OPFS implies Worker usage.

OPFS Requirements

• Secure context: HTTPS or localhost
• Browser support: Chrome 86+, Firefox 111+, Safari 15.2+
• Worker requirement: SQLite WASM OPFS backends are only available in Worker contexts. When running on the main thread, UniSQLite will automatically run SQLite in a Worker (wrapped-worker). Your sqlite.loadStrategy must be able to load sqlite3Worker1Promiser (use 'npm' or 'cdn', or provide it globally).
• For VFS 'opfs': Requires COOP/COEP headers (window.crossOriginIsolated === true) so SharedArrayBuffer is available.
• Benefits over localStorage:
  • No 5MB size limit
  • Binary storage (better performance)
  • Custom database filenames
  • Better suited for large datasets

localStorage Limitations

The localStorage backend only accepts 'local' or 'session' as database paths:

// ✅ Works with localStorage
const db = await openStore({
  path: 'local',  // or 'session'
  sqlite: { storageBackend: 'localStorage' }
});

// ❌ Throws error - invalid path for localStorage
const db = await openStore({
  path: 'my-custom-db.db',
  sqlite: { storageBackend: 'localStorage' }
});
// Error: localStorage storage backend requires path to be 'local' or 'session'

Platform-specific entrypoints

The default unisqlite export stays minimal and uses dynamic imports so optional peers are only loaded when their platform adapter is actually needed. To make bundling and installations more intentional, use platform-specific entrypoints:

• Node (requires peer better-sqlite3): import { openNodeStore, NodeAdapter } from "unisqlite/node";
• Browser (needs broadcast-channel, and @sqlite.org/sqlite-wasm if you load SQLite from npm): import { openStore } from "unisqlite/browser";
• Cloudflare Durable Objects: import { openCloudflareStore, CloudflareDOAdapter, createCloudflareDOAdapter } from "unisqlite/cloudflare";

These entrypoints avoid pulling in other platform adapters, keeping browser bundles slim and Node installs free from WASM/downloaded assets.

API Reference

Connection Type Detection

interface UniStoreConnection {
  getConnectionType(): "direct" | "syncTxn" | "asyncTxn";
  // ... other methods
}

Transaction Method Signatures

// Synchronous transaction - function cannot return Promise
transaction<T>(fn: (tx: UniStoreConnection) => T extends Promise<unknown> ? never : T): T extends Promise<unknown> ? never : T;

// Asynchronous transaction - function can return Promise
asyncTransaction<T>(fn: (tx: UniStoreConnection) => Promise<T>, options?: { timeoutMs?: number }): Promise<T>;

Transaction Enforcement Rules

Connection Type	transaction()	asyncTransaction()
"direct"	✅ Supported	✅ Supported
"syncTxn"	✅ Supported	❌ Throws Error
"asyncTxn"	✅ Supported	✅ Supported

TypeScript Constraints

The transaction() method enforces synchronous functions at compile time:

// ✅ Valid - returns non-Promise value
const result = store.transaction((txn) => {
  return "sync-result";
});

// ❌ TypeScript Error - returns Promise
const invalid = store.transaction((txn) => {
  return Promise.resolve("async-result"); // Type error!
});

// ❌ TypeScript Error - async function
const invalid2 = store.transaction(async (txn) => {
  return "result"; // Type error!
});

This design ensures:

• Type safety at the connection level
• Prevention of async operations in sync-only contexts
• Clear error messages for invalid usage patterns
• Consistent behavior across all adapter implementations
• Compile-time enforcement of synchronous transaction functions