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>

getSchema(): Promise<Schema>

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(
  schema: Schema,
  options?: SetSchemaOptions,
): Promise<boolean>

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(
  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

ColumnSchema

The ColumnSchema interface describes one column of a table.

JsonValue

number

string

boolean

string

ColumnType

ForeignKeySchema

The ForeignKeySchema interface describes one foreign key of a table: columns whose values, unless one is NULL, must be those of a row of the table it references.

string[]

string

ForeignKeyAction

ForeignKeyAction

string[]

string

IndexSchema

The IndexSchema interface describes one secondary index on a table.

A primary key is not listed as an index; TableSchema's primaryKey holds it.

string[]

string

boolean

Schema

The Schema interface is returned by the getSchema method, and describes every table in the database. The setSchema method takes one to make the database's.

TableSchema[]

number

SetSchemaOptions

The SetSchemaOptions interface configures the setSchema method.

boolean

TableSchema

The TableSchema interface describes one table, its columns, its primary key, its indexes, and its foreign keys.

ColumnSchema[]

ForeignKeySchema[]

IndexSchema[]

string

string[]

string

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"

An object row holds one value for each name, so a SELECT whose output names repeat is rejected unless its rows are arrays.

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.

ColumnType

The ColumnType type names one of the five runtime types a column holds.

"boolean" | "integer" | "float" | "text" | "json"

Each SQL type name maps to one of them: INTEGER and BIGINT to integer, REAL and DOUBLE PRECISION to float, TEXT and VARCHAR to text, and JSON and JSONB to json. The schema keeps the runtime type, not the name the table was declared with, and the length of a VARCHAR(n) as its column's maxLength.

ForeignKeyAction

The ForeignKeyAction type names what deleting or updating a referenced row does to the rows that reference it: no action and restrict refuse it, cascade deletes or updates them too, and set null and set default change their referencing columns to NULL or to the columns' defaults.

"no action" | "restrict" | "cascade" | "set null" | "set default"

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

MigrationConfig

The MigrationConfig interface describes the migrations that the migrate function applies.

MigrationJournal

Record<string, string>

string

MigrationJournal

The MigrationJournal interface is the journal that drizzle-kit generate writes beside its migrations, as meta/_journal.json, of which the migrate function reads each entry's tag and time.

{
  tag: string;
  when: number;
}[]

PushOptions

The PushOptions interface configures the push function.

boolean

Record<string, string>

number

drizzle

The drizzle function creates a Drizzle database over a TinyJoin Client.

drizzle<TSchema>(
  client: Client,
  config?: DrizzleConfig<TSchema>,
): TinyJoinDatabase<TSchema>

Queries run on the Client as array rows, which Drizzle maps to its own result shapes. Drizzle's db.transaction runs on the Client's callback transaction, so it holds the database as any TinyJoin transaction does, tx.rollback discards its work, and a transaction cannot nest, since there are no savepoints, or take an isolation level.

A value Drizzle encodes for a json or jsonb column is bound as the JSON value it is, rather than as the JSON text Drizzle makes of it, which TinyJoin would store as a string.

Close the Client yourself when the database is no longer needed.

import {create} from 'tinyjoin';
import {drizzle} from 'tinyjoin/drizzle';
import {eq} from 'drizzle-orm';
import {boolean, pgTable, text} from 'drizzle-orm/pg-core';

const tasks = pgTable('tasks', {
  id: text('id').primaryKey(),
  title: text('title').notNull(),
  done: boolean('done').notNull().default(false),
});

const client = await create('opfs://my-app-v1');
const db = drizzle(client, {schema: {tasks}});
await db.insert(tasks).values({id: crypto.randomUUID(), title: 'Try Drizzle'});
const open = await db.select().from(tasks).where(eq(tasks.done, false));

migrate

The migrate function applies the migrations that drizzle-kit generate wrote, which the database has not yet recorded, in the journal's order.

migrate<TSchema>(
  db: TinyJoinDatabase<TSchema>,
  config: MigrationConfig,
): Promise<void>

Each migration runs as one script together with the row that records it, so it commits whole or not at all, and a migration that fails leaves the database as the previous one left it, and rejects with its error. A migration another Client of the same database applied first is skipped, so every tab of an application can call migrate as it starts.

A migration is recorded by its tag and applied once: a file changed after it was applied is not applied again, and a migration that joins the journal before others already applied is still applied. The migrations need no file system, so a browser application bundles them.

import {create} from 'tinyjoin';
import {drizzle, migrate} from 'tinyjoin/drizzle';
import journal from './drizzle/meta/_journal.json';

const db = drizzle(await create('opfs://my-app-v1'));
await migrate(db, {
  journal,
  migrations: import.meta.glob<string>('./drizzle/*.sql', {
    query: '?raw',
    import: 'default',
    eager: true,
  }),
});

push

The push function makes the database hold the tables of a Drizzle schema, as Drizzle Kit's push would for PostgreSQL, but from the application and as one change that commits whole or not at all.

push<TSchema>(
  db: TinyJoinDatabase<TSchema>,
  schema: Record<string, unknown>,
  options?: PushOptions,
): Promise<boolean>

It reads each table's columns, primary key, unique constraints, and indexes from Drizzle, and passes them to the Client's setSchema, which creates what the database lacks and changes what differs. A schema the database already holds changes nothing, so every tab of an application can call push as it starts, in place of migrations.

A table that declares what TinyJoin does not have, such as a foreign key, a timestamp column, an SQL default, or an index on an expression, is refused before anything changes. A default Drizzle works out in JavaScript, with $defaultFn, is Drizzle's, not the database's.

import {create} from 'tinyjoin';
import {drizzle, push} from 'tinyjoin/drizzle';
import * as schema from './schema';

const db = drizzle(await create('opfs://my-app-v1'), {schema});
await push(db, schema, {version: 2, renames: {'tasks.name': 'title'}});

Since

v0.5.0

Example

import {create} from 'tinyjoin';
import {TinyJoinDialect} from 'tinyjoin/kysely';
import {Kysely} from 'kysely';

interface Database {
  tasks: {id: string; title: string; done: boolean};
}

const client = await create('opfs://my-app-v1');
const db = new Kysely<Database>({dialect: new TinyJoinDialect({client})});
const open = await db
  .selectFrom('tasks')
  .select(['id', 'title'])
  .where('done', '=', false)
  .execute();

Since

v0.5.0

Constructors

new TinyJoinDialect(config: TinyJoinDialectConfig): TinyJoinDialect

Methods

createAdapter(): DialectAdapter

createDriver(): Driver

createIntrospector(): DatabaseIntrospector

createQueryCompiler(): QueryCompiler

Since

v0.5.0

client

The client property is the TinyJoin Client, from create(), on which Kysely runs its queries. The application closes it: Kysely's destroy leaves it open.

Client

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