API

Client

The Client class represents one open TinyJoin database and its dedicated Worker.

Prefer the async create function so initialization failures are reported before the Client is returned.

new Client(options?: ClientOptions): Client

check(): Promise<void>

close(): Promise<void>

exec(
  sql: string,
  options?: QueryOptions,
): Promise<Results<Row>[]>

prepare<RowType>(sql: string): Promise<PreparedStatement<RowType>>

query<RowType>(
  sql: string,
  params?: JsonValue[],
  options?: QueryOptions,
): Promise<Results<RowType>>

sql<RowType>(
  strings: TemplateStringsArray,
  ...params: JsonValue[],
): Promise<Results<RowType>>

transaction<Result>(callback: (transaction: Transaction) => Result | Promise<Result>): Promise<Result>

getRevision(): number

subscribe(
  options: SubscriptionOptions,
  listener: (event: TablesChangedEvent) => void,
): () => void

boolean

boolean

Promise<void>

ClientError

The ClientError class extends JavaScript Error with a validated error returned by the TinyJoin Worker.

RECOVERY_REQUIRED, STORAGE_COMMIT_OUTCOME_UNKNOWN, and STORAGE_ENGINE_POISONED mean the engine must no longer be used. Stop work, close the Client, reopen the same OPFS name, and reconcile stored state using stable operation identifiers before replaying a write. A rejected operation may already have committed. See the recovery guide.

new ClientError(error: SerializedError): ClientError

string

JsonValue | undefined

boolean

PreparedStatement

The PreparedStatement interface represents one parsed SELECT, INSERT, UPDATE, or DELETE statement retained by an open Client.

close(): Promise<void>

execute(
  params?: JsonValue[],
  options?: QueryOptions,
): Promise<Results<RowType>>

boolean

Transaction

The Transaction interface runs reads and row mutations against one isolated staged database inside a Client.transaction callback.

Do not retain this object after its callback completes. Run schema DDL in a standalone Client.query call or Client.exec script. Pass this object to helpers instead of awaiting another transaction on the same Client, which would queue behind the active callback and deadlock.

exec(
  sql: string,
  options?: QueryOptions,
): Promise<Results<Row>[]>

execute<RowType>(
  statement: PreparedStatement<RowType>,
  params?: JsonValue[],
  options?: QueryOptions,
): Promise<Results<RowType>>

query<RowType>(
  sql: string,
  params?: JsonValue[],
  options?: QueryOptions,
): Promise<Results<RowType>>

rollback(): Promise<void>

sql<RowType>(
  strings: TemplateStringsArray,
  ...params: JsonValue[],
): Promise<Results<RowType>>

boolean

QueryOptions

The QueryOptions interface configures the shape of query results.

Only rowMode is supported. There is no AbortSignal or timeout option; Promise.race with a timer does not cancel database work.

RowMode

ResultField

The ResultField interface describes one projected result column.

number

string

Results

The Results interface is returned by queries, prepared statements, and scripts.

It follows the familiar PGlite result shape and adds the observed database revision and the names of changed tables.

number

string

ResultField[]

ChangedKeys

number

number

RowType[]

string[]

SubscriptionOptions

The SubscriptionOptions interface filters invalidations by table name.

string[]

TablesChangedEvent

The TablesChangedEvent interface describes one committed table-level invalidation or a request to refresh after database-owner handover.

ChangedKeys

boolean

number

string[]

ClientOptions

The ClientOptions interface configures storage or an application-owned Worker.

The zero-boilerplate default constructs TinyJoin's packaged module Worker. Provide at most one of worker, workerFactory, or workerUrl.

WorkerLike

string

() => WorkerLike

string | URL

SerializedError

The SerializedError interface is the stable error envelope sent by the Worker.

string

JsonValue

string

boolean

WorkerLike

The WorkerLike interface is the minimal Worker surface accepted by a custom Client configuration.

Most applications should let create construct the packaged Worker instead.

addEventListener(
  type: "message",
  listener: (event: (
    Omit<MessageEvent<any>, "data"> &
    {data: unknown}
  )) => void,
): void

addEventListener(
  type: "messageerror",
  listener: (event: (
    Omit<MessageEvent<any>, "data"> &
    {data: unknown}
  )) => void,
): void

addEventListener(
  type: "error",
  listener: (event: ErrorEvent) => void,
): void

postMessage(message: unknown): void

removeEventListener(
  type: "message",
  listener: (event: (
    Omit<MessageEvent<any>, "data"> &
    {data: unknown}
  )) => void,
): void

removeEventListener(
  type: "messageerror",
  listener: (event: (
    Omit<MessageEvent<any>, "data"> &
    {data: unknown}
  )) => void,
): void

removeEventListener(
  type: "error",
  listener: (event: ErrorEvent) => void,
): void

() => void

Example

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE IF NOT EXISTS tasks (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL
  )
`);
const {rows} = await db.query('SELECT * FROM tasks ORDER BY id');
await db.close();

Since

v0.0.5

Example

import {create} from 'tinyjoin';

const db = await create({dataDir: 'memory://'});
await db.close();

Since

v0.0.5

Example

import {create} from 'tinyjoin';

const db = await create('opfs://my-app');
await db.close();

Since

v0.0.5

ChangedKeys

The ChangedKeys type maps a table name to the primary keys that changed in it.

{[table: string]: Row[]}

Each key is an object holding only that table's primary-key columns, so a composite key arrives as one object with one property per column.

RowMode

The RowMode type selects object rows or positional array rows.

"array" | "object"

JsonPrimitive

The JsonPrimitive type represents a scalar value accepted by TinyJoin.

null | boolean | number | string

JsonValue

The JsonValue type represents a parameter or result value accepted by the TinyJoin JavaScript API.

JsonPrimitive | JsonValue[] | {[key: string]: JsonValue}

Row

The Row type represents the default object form of a result row.

Record<string, JsonValue>

DataDir

The DataDir type identifies the database storage mode.

string

Use memory:// for an ephemeral database, or opfs://name for a persistent database. Calling create without a data directory also uses memory. Clients using the same OPFS name automatically share an elected database owner, including across tabs. Pending operations interrupted by owner loss reject without replay; subsequent operations reconnect automatically. Different names have independent data and do not synchronize.

Example

import {type Client, create} from 'tinyjoin/node';

const db: Client = await create();
try {
  await db.exec('CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)');
  await db.query('INSERT INTO notes VALUES ($1, $2)', [1, 'Hello from Node']);
  console.log((await db.query('SELECT * FROM notes ORDER BY id')).rows);
} finally {
  await db.close();
}

Since

v0.1.0

Since

v0.1.0

mode

The mode property selects automatic service-worker registration or integration with an existing service worker. The default is service-worker.

"service-worker" | "manifest"

The manifest mode emits tinyjoin-precache.json and tinyjoin-precache.js without registering or replacing a service worker.

navigationFallback

The navigationFallback property names the emitted HTML file served for otherwise unmatched navigation requests within the application scope. It defaults to index.html; use false to disable SPA navigation fallback.

string | false

Example

import {defineConfig} from 'vite';
import {tinyjoinOffline} from 'tinyjoin/vite';

export default defineConfig({plugins: [tinyjoinOffline()]});

Since

v0.1.0