API

Example

import {Client} from 'tinyjoin';

const db = new Client({dataDir: 'opfs://my-app-v1'});
console.log(db.ready);
// -> false

await db.waitReady;
console.log(db.ready);
// -> true
await db.close();

check

The check method reads every row and index entry of the committed database, and every page that holds them, and resolves when all of them are sound.

check(): Promise<void>

Opening a database checks only its catalog, and each page and row is checked as a statement reads it, so rows that are never read, and whether each index still matches its table, are checked only here. The check takes time in proportion to the database, and statements from every Client of the same OPFS name wait while it runs. Call it outside a transaction.

TinyJoin cannot yet repair a database that fails its check.

import {ClientError, create} from 'tinyjoin';

const db = await create('opfs://my-app-v1');
try {
  await db.check();
  console.log('Every row and index entry is sound.');
} catch (error) {
  if (!(error instanceof ClientError)) {
    throw error;
  }
  // Nothing repairs a database that fails its check, so the application
  // restores its own backup into a new OPFS name.
  console.error(error.code);
} finally {
  await db.close();
}

close

The close method detaches this Client and releases its prepared statements and Worker. Other Clients for the same OPFS name stay connected; ownership transfers automatically when necessary. Repeated calls share the same asynchronous cleanup. A closed Client cannot resume; create a new one and recreate its prepared statements and subscriptions. Closing is not a cancellation or rollback guarantee for a write already in flight.

close(): Promise<void>

import {create} from 'tinyjoin';

const db = await create('opfs://my-app-v1');
try {
  await db.exec(`
    CREATE TABLE IF NOT EXISTS tasks (id TEXT PRIMARY KEY)
  `);
} finally {
  // Releases the Worker and its hold on the storage, whatever happened.
  await db.close();
}
console.log(db.closed);
// -> true

getSchema

The getSchema method reads the database's tables, with their columns, primary keys, and indexes, as the engine's catalog holds them.

getSchema(): Promise<Schema>

Tables and each table's indexes are in name order, and columns and key columns are in the order the table declares them. Call it outside a transaction.

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, done BOOLEAN NOT NULL DEFAULT false);
  CREATE INDEX tasks_done ON tasks (done);
`);
const {tables} = await db.getSchema();
console.log(tables[0].columns[1]);
// -> {name: 'done', type: 'boolean', nullable: false, default: false}
await db.close();

setSchema

The setSchema method makes the database's tables, columns, primary keys, and indexes match a Schema, as getSchema returns one, in one change that commits whole or not at all.

setSchema(
  schema: Schema,
  options?: SetSchemaOptions,
): Promise<boolean>

It creates the tables and columns the schema has and the database lacks, renames a table or column from the name its renamedFrom gives while the database still has that name, and changes a column's default, nullability, or VARCHAR length to the schema's. Each table's indexes and foreign keys become exactly the schema's, with keys added once every table they reference exists. Tables and columns the schema leaves out stay, unless the options' drop property is true. Rows keep their values, as ALTER TABLE keeps them: a change no statement could make, to a primary key or a column's runtime type, is refused, and so is one that a row prevents, such as NOT NULL where a row holds NULL.

A schema the database already has changes nothing, so every tab of an application can call setSchema as it starts. A schema whose version is lower than the database's is refused with SCHEMA_OUTDATED, so that a tab still running an older copy of the application cannot undo a newer one's changes; a higher version is recorded. Call it outside a transaction.

import {create} from 'tinyjoin';

const db = await create();
await db.setSchema({
  version: 1,
  tables: [
    {
      name: 'tasks',
      columns: [
        {name: 'id', type: 'text', nullable: false},
        {name: 'title', type: 'text', nullable: false},
        {name: 'done', type: 'boolean', nullable: false, default: false},
      ],
      primaryKey: ['id'],
      indexes: [{name: 'tasks_done', columns: ['done'], unique: false}],
      foreignKeys: [],
    },
  ],
});
await db.close();

exec

The exec method runs one or more parameter-free statements as one implicit transaction.

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

import {create} from 'tinyjoin';

const db = await create();
const results = await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL);
  INSERT INTO tasks (id, title) VALUES ('a', 'Write docs');
  SELECT * FROM tasks;
`);
console.log(results.length);
// -> 3
console.log(results[2].rows);
// -> [{id: 'a', title: 'Write docs'}]
await db.close();

prepare

The prepare method parses and retains one reusable read or row-mutation statement in the Worker.

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

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL);
  INSERT INTO tasks (id, title) VALUES ('a', 'Write docs');
  INSERT INTO tasks (id, title) VALUES ('b', 'Ship release');
`);
const titleOf = await db.prepare<{title: string}>(
  'SELECT title FROM tasks WHERE id = $1',
);
for (const id of ['a', 'b']) {
  const {rows} = await titleOf.execute([id]);
  console.log(rows[0].title);
}
// -> 'Write docs'
// -> 'Ship release'
await titleOf.close();
await db.close();

query

The query method executes exactly one parameterized SQL statement.

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

import {create} from 'tinyjoin';

const db = await create();
await db.query(
  'CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)',
);
const inserted = await db.query(
  'INSERT INTO tasks (id, title) VALUES ($1, $2)',
  ['a', 'Write docs'],
);
console.log(inserted.affectedRows);
// -> 1

const {rows} = await db.query<{id: string; title: string}>(
  'SELECT * FROM tasks WHERE id = $1',
  ['a'],
);
console.log(rows);
// -> [{id: 'a', title: 'Write docs'}]
await db.close();

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL);
  INSERT INTO tasks (id, title) VALUES ('a', 'Write docs');
`);
// Rows come back as arrays, in the order of the fields, on request.
const {fields, rows} = await db.query('SELECT id, title FROM tasks', [], {
  rowMode: 'array',
});
console.log(fields.map(({name}) => name));
// -> ['id', 'title']
console.log(rows);
// -> [['a', 'Write docs']]
await db.close();

sql

The sql method is a parameterizing tagged-template form of query.

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

Interpolated values become $n parameters. It does not interpolate raw identifiers or SQL fragments.

import {create} from 'tinyjoin';

const db = await create();
await db.sql`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
`;

const id = 'a';
const title = 'Write docs';
await db.sql`INSERT INTO tasks (id, title) VALUES (${id}, ${title})`;

const {rows} = await db.sql<{title: string}>`
  SELECT title FROM tasks WHERE id = ${id}
`;
console.log(rows);
// -> [{title: 'Write docs'}]
await db.close();

transaction

The transaction method stages row mutations and publishes them together when the callback succeeds, unless it explicitly rolls back.

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

Transaction calls on this Client queue in order. Do not await another transaction on this Client inside the callback; pass its Transaction to helpers instead. Use that object for all SQL in the callback and prepare handles beforehand. Other Clients for the same OPFS name wait for the whole callback to finish. Do not await work on those Clients from inside this callback. An uncaught callback error before commit discards staged work. A caught statement error leaves earlier writes staged unless rollback is called.

There is no cancellation or timeout option. Promise.race only stops waiting, and queued work can still commit. Rejection during commit can leave its outcome uncertain; see the recovery guide before replaying a failed write.

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE accounts (id TEXT PRIMARY KEY, balance INTEGER NOT NULL);
  INSERT INTO accounts (id, balance) VALUES ('a', 100);
  INSERT INTO accounts (id, balance) VALUES ('b', 0);
`);
// Both updates commit together, or neither does.
const moved = await db.transaction(async (tx) => {
  await tx.query(
    'UPDATE accounts SET balance = balance - $1 WHERE id = $2',
    [30, 'a'],
  );
  await tx.query(
    'UPDATE accounts SET balance = balance + $1 WHERE id = $2',
    [30, 'b'],
  );
  return 30;
});
console.log(moved);
// -> 30

const {rows} = await db.query('SELECT * FROM accounts ORDER BY id');
console.log(rows);
// -> [{id: 'a', balance: 70}, {id: 'b', balance: 30}]
await db.close();

getRevision

The getRevision method returns the newest database revision observed by this Client.

getRevision(): number

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
`);
const before = db.getRevision();
const {revision} = await db.query(
  'INSERT INTO tasks (id, title) VALUES ($1, $2)',
  ['a', 'Write docs'],
);
console.log(revision > before);
// -> true
console.log(db.getRevision() == revision);
// -> true
await db.close();

subscribe

The subscribe method listens for committed table changes and returns an unsubscribe function. OPFS Clients receive changes from every connected tab. After handover or page restoration, reset events notify every subscriber to re-query even though tables is empty.

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

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
`);
const unsubscribe = db.subscribe({tables: ['tasks']}, async ({tables}) => {
  // The event names the tables that changed. Query again for their rows.
  const {rows} = await db.query('SELECT * FROM tasks ORDER BY id');
  console.log(tables, rows);
  // -> ['tasks'] [{id: 'a', title: 'Write docs'}]
  unsubscribe();
  await db.close();
});

await db.query('INSERT INTO tasks (id, title) VALUES ($1, $2)', [
  'a',
  'Write docs',
]);

Example

import {ClientError} from 'tinyjoin';

const error = new ClientError({
  code: 'INVALID_ARGUMENT',
  message: 'A task needs a title.',
  details: {column: 'title'},
});
console.log(error instanceof Error);
// -> true
console.log(error.code, error.details, error.retryable);
// -> 'INVALID_ARGUMENT' {column: 'title'} false

close

The close method seals the handle and releases its Worker resources after already-started executions settle.

close(): Promise<void>

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
`);
const select = await db.prepare('SELECT * FROM tasks WHERE id = $1');
await select.execute(['a']);

await select.close();
console.log(select.closed);
// -> true
await db.close();

execute

The execute method binds a complete parameter list and runs the statement.

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

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
`);
const insert = await db.prepare(
  'INSERT INTO tasks (id, title) VALUES ($1, $2)',
);
await insert.execute(['a', 'Write docs']);
await insert.execute(['b', 'Ship release']);

const {rows} = await db.query('SELECT title FROM tasks ORDER BY id');
console.log(rows);
// -> [{title: 'Write docs'}, {title: 'Ship release'}]
await insert.close();
await db.close();

Example

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
`);
await db.transaction(async (tx) => {
  const results = await tx.exec(`
    INSERT INTO tasks (id, title) VALUES ('a', 'Write docs');
    INSERT INTO tasks (id, title) VALUES ('b', 'Ship release');
    SELECT id FROM tasks ORDER BY id;
  `);
  console.log(results[2].rows);
  // -> [{id: 'a'}, {id: 'b'}]
});
await db.close();

Example

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
`);
// Prepare the statement before the transaction, and run it inside.
const insert = await db.prepare(
  'INSERT INTO tasks (id, title) VALUES ($1, $2)',
);
await db.transaction(async (tx) => {
  await tx.execute(insert, ['a', 'Write docs']);
  await tx.execute(insert, ['b', 'Ship release']);
});

const {rows} = await db.query('SELECT id FROM tasks ORDER BY id');
console.log(rows);
// -> [{id: 'a'}, {id: 'b'}]
await insert.close();
await db.close();

Example

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
`);
await db.transaction(async (tx) => {
  await tx.query('INSERT INTO tasks (id, title) VALUES ($1, $2)', [
    'a',
    'Write docs',
  ]);
  // A read inside the transaction sees the rows it has staged.
  const {rows} = await tx.query('SELECT title FROM tasks WHERE id = $1', [
    'a',
  ]);
  console.log(rows);
  // -> [{title: 'Write docs'}]
});
await db.close();

Example

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
`);
await db.transaction(async (tx) => {
  await tx.query('INSERT INTO tasks (id, title) VALUES ($1, $2)', [
    'a',
    'Write docs',
  ]);
  await tx.rollback();
  console.log(tx.closed);
  // -> true
});

const {rows} = await db.query('SELECT * FROM tasks');
console.log(rows);
// -> []
await db.close();

Example

import {create} from 'tinyjoin';

const db = await create();
await db.exec(`
  CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
`);
const tasks = [
  {id: 'a', title: 'Write docs'},
  {id: 'b', title: 'Ship release'},
];
await db.transaction(async (tx) => {
  for (const {id, title} of tasks) {
    await tx.sql`INSERT INTO tasks (id, title) VALUES (${id}, ${title})`;
  }
});

const {rows} = await db.query('SELECT id FROM tasks ORDER BY id');
console.log(rows);
// -> [{id: 'a'}, {id: 'b'}]
await db.close();

Example

import {create} from 'tinyjoin';
import type {WorkerLike} from 'tinyjoin';

const worker: WorkerLike = new Worker(
  new URL('./worker.ts', import.meta.url),
  {type: 'module'},
);

// Count the messages the Worker sends, beside the Client's own listener.
let messages = 0;
worker.addEventListener('message', () => {
  messages++;
});

const db = await create({worker});
console.log(messages > 0);
// -> true
await db.close();

Example

import {create} from 'tinyjoin';
import type {WorkerLike} from 'tinyjoin';

const worker: WorkerLike = new Worker(
  new URL('./worker.ts', import.meta.url),
  {type: 'module'},
);

// Report a message from the Worker that the page could not decode.
worker.addEventListener('messageerror', () => {
  console.error('A message from the Worker could not be decoded.');
});

const db = await create({worker});
await db.close();

Example

import {create} from 'tinyjoin';
import type {WorkerLike} from 'tinyjoin';

const worker: WorkerLike = new Worker(
  new URL('./worker.ts', import.meta.url),
  {type: 'module'},
);

// Report an error the Worker did not catch, such as a script that failed
// to load.
worker.addEventListener('error', (event) => {
  console.error('The TinyJoin Worker failed:', event.message);
});

const db = await create({worker});
await db.close();

Example

import {create} from 'tinyjoin';
import type {WorkerLike} from 'tinyjoin';

// The application's worker.ts calls startWorker() from tinyjoin/worker.
const worker: WorkerLike = new Worker(
  new URL('./worker.ts', import.meta.url),
  {type: 'module'},
);

// Count the requests the Client posts to its Worker.
let requests = 0;
const post = worker.postMessage.bind(worker);
worker.postMessage = (message) => {
  requests++;
  post(message);
};

const db = await create({worker});
console.log(requests > 0);
// -> true
await db.close();

Example

import {create} from 'tinyjoin';
import type {WorkerLike} from 'tinyjoin';

const worker: WorkerLike = new Worker(
  new URL('./worker.ts', import.meta.url),
  {type: 'module'},
);

let messages = 0;
const countMessage = (): void => {
  messages++;
};
worker.addEventListener('message', countMessage);

const db = await create({worker});
// Count only the messages it took to open the database.
worker.removeEventListener('message', countMessage);
console.log(messages > 0);
// -> true
await db.close();

Example

import {create} from 'tinyjoin';
import type {WorkerLike} from 'tinyjoin';

const worker: WorkerLike = new Worker(
  new URL('./worker.ts', import.meta.url),
  {type: 'module'},
);

const reportUndecoded = (): void => {
  console.error('A message from the Worker could not be decoded.');
};
worker.addEventListener('messageerror', reportUndecoded);

const db = await create({worker});
await db.close();
// The Worker has stopped, so there is nothing left to report.
worker.removeEventListener('messageerror', reportUndecoded);

Example

import {create} from 'tinyjoin';
import type {WorkerLike} from 'tinyjoin';

const worker: WorkerLike = new Worker(
  new URL('./worker.ts', import.meta.url),
  {type: 'module'},
);

const reportFailure = (): void => {
  console.error('The TinyJoin Worker failed.');
};
worker.addEventListener('error', reportFailure);

const db = await create({worker});
await db.close();
// The Worker has stopped, so there is nothing left to report.
worker.removeEventListener('error', reportFailure);