firebird-wasm 0.7.0 → 0.9.0

package/dist/browser/worker-entry.js

@@ -19,89 +19,28 @@
  * serves filesystem requests too — persistence copies the database between
  * that filesystem and IndexedDB, and only this side can read it.
  *
- * The page must be cross-origin isolated (COOP/COEP): Emscripten's pthreads
- * need SharedArrayBuffer, which browsers withhold otherwise.
+ * With the threaded build the page must be cross-origin isolated (COOP/COEP):
+ * Emscripten's pthreads need SharedArrayBuffer, which browsers withhold
+ * otherwise.  The build without threads needs no isolation.
+ *
+ * Loading this module starts serving, but only in a dedicated Worker; the
+ * library's index exports serveEngine from serve-engine.ts, which has no such
+ * side effect, so importing the library starts nothing.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.serveEngine = serveEngine;
+exports.serveEngine = void 0;
 const engine_transport_1 = require("./engine-transport");
-/**
- * Every distinct ArrayBuffer behind a Uint8Array in a query result.
- *
- * Only query results are walked, and only one level into each row: a value is
- * either a blob or it is not, and scanning arbitrary structures on every reply
- * would cost more than the transfer saves.
- *
- * De-duplicated because transferring the same buffer twice throws
- * DataCloneError, and two rows can hold views on one buffer if the same blob
- * appeared twice.
- */
-function collectBlobBuffers(result) {
-    if (typeof result !== 'object' || result === null)
-        return [];
-    const rows = result.rows;
-    if (!Array.isArray(rows))
-        return [];
-    const buffers = new Set();
-    for (const row of rows) {
-        if (typeof row !== 'object' || row === null)
-            continue;
-        // Rows are arrays in rowMode 'array' and plain objects otherwise;
-        // Object.values covers both.
-        for (const value of Object.values(row)) {
-            if (value instanceof Uint8Array)
-                buffers.add(value.buffer);
-        }
-    }
-    return [...buffers];
-}
-/**
- * Wire a transport up to a Worker scope.
- *
- * Exported so a host application can build its own Worker entry point — for
- * example to set `locateFile` before any message is handled.
- */
-function serveEngine(scope, transport) {
-    const reply = (response) => {
-        // Transfer the buffer for readFile rather than copying it: a database
-        // image is measured in megabytes and this runs on every persist.
-        //
-        // The same applies to binary BLOBs coming back from a query, which arrive
-        // as Uint8Arrays inside the rows. Structured cloning would copy every one
-        // of them across the boundary — the cost a base64 string could never avoid
-        // and the reason the side channel is worth having at all.
-        const transfer = response.result instanceof Uint8Array
-            ? [response.result.buffer]
-            : collectBlobBuffers(response.result);
-        scope.postMessage(response, transfer);
-    };
-    scope.addEventListener('message', (event) => {
-        const { id, op, args } = event.data;
-        void (async () => {
-            try {
-                // The op names are exactly the transport's method names, so this is a
-                // direct dispatch rather than a switch that has to be kept in step.
-                const fn = transport[op];
-                if (typeof fn !== 'function') {
-                    throw new Error(`unknown engine operation: ${op}`);
-                }
-                const result = (await fn.apply(transport, args)) ?? null;
-                reply({ id, ok: true, result: result });
-            }
-            catch (err) {
-                reply({
-                    id,
-                    ok: false,
-                    error: err instanceof Error ? err.message : String(err),
-                });
-            }
-        })();
-    });
-}
-// Auto-start when loaded as a Worker script.
-if (typeof self !== 'undefined' && typeof self.postMessage === 'function') {
+const serve_engine_1 = require("./serve-engine");
+var serve_engine_2 = require("./serve-engine");
+Object.defineProperty(exports, "serveEngine", { enumerable: true, get: function () { return serve_engine_2.serveEngine; } });
+// Start serving when loaded as a dedicated Worker's script, and only then.
+// `self.postMessage` alone is no test: a page's window has one too, and
+// serving there would answer every window that can message the page.
+const workerScope = globalThis.WorkerGlobalScope;
+if (typeof workerScope === 'function' && self instanceof workerScope
+    && typeof self.postMessage === 'function') {
     try {
-        serveEngine(self, new engine_transport_1.DirectTransport(self.FIREBIRD_WORKER_OPTIONS ?? {}));
+        (0, serve_engine_1.serveEngine)(self, new engine_transport_1.DirectTransport(self.FIREBIRD_WORKER_OPTIONS ?? {}));
     }
     catch (err) {
         // No request to answer yet, so report the bootstrap failure out of band;

package/dist/browser/worker-entry.js.map

@@ -1 +1 @@
-{"version":3,"file":"worker-entry.js","sourceRoot":"","sources":["../../src/browser/worker-entry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"worker-entry.js","sourceRoot":"","sources":["../../src/browser/worker-entry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;AAEH,yDAAqD;AAErD,iDAA6C;AAG7C,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AAQpB,2EAA2E;AAC3E,wEAAwE;AACxE,qEAAqE;AACrE,MAAM,WAAW,GAAI,UAA8C,CAAC,iBAAiB,CAAC;AACtF,IAAI,OAAO,WAAW,KAAK,UAAU,IAAI,IAAI,YAAa,WAAgC;OACrF,OAAO,IAAI,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;IAC5C,IAAI,CAAC;QACH,IAAA,0BAAW,EAAC,IAAI,EAAE,IAAI,kCAAe,CAAC,IAAI,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,yEAAyE;QACzE,6DAA6D;QAC7D,IAAI,CAAC,WAAW,CAAC;YACf,EAAE,EAAE,CAAC,CAAC;YACN,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/electric/apply.d.ts

@@ -0,0 +1,53 @@
+/**
+ * apply.ts – one batch of Electric's shape log, applied in one transaction.
+ *
+ * Electric's rule is to apply operations only at `up-to-date`, as a whole:
+ * the store then always matches some state Postgres was in.  The caller runs
+ * this inside a Firebird transaction that also records the sync position, so
+ * the rows and the position commit together or not at all.
+ */
+import { firebirdColumn } from './values';
+import type { ElectricSchema } from './values';
+/** What applying needs of a transaction: `FirebirdBrowserTransaction` has it. */
+export interface ElectricTransaction {
+    exec(sql: string, params?: unknown[]): Promise<{
+        affectedRows: number;
+    }>;
+    execBatch(sql: string, rows: unknown[][]): Promise<{
+        affectedRows: number;
+    }>;
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+}
+/** An operation, or the reset a `must-refetch` asks for, in log order. */
+export type LogEntry = {
+    kind: 'insert' | 'update' | 'delete';
+    value: Record<string, unknown>;
+} | {
+    kind: 'reset';
+};
+/** Where the rows go. */
+export interface ApplyTarget {
+    /** The Firebird table, quoted. */
+    table: string;
+    /** Primary key columns, Postgres names, in key order. */
+    primaryKey: string[];
+    /** The Firebird column for a Postgres column, quoted. */
+    column: (postgresName: string) => string;
+    schema: ElectricSchema;
+}
+/** The default column mapping. */
+export declare const defaultColumn: typeof firebirdColumn;
+/**
+ * Apply `entries` through `tx`.
+ *
+ * - an insert is `UPDATE OR INSERT … MATCHING (key)`, so one seen twice (a
+ *   replayed batch, a resync over rows already there) does no harm; a run of
+ *   inserts with the same columns goes through one prepared batch;
+ * - an update carries the key and the changed columns, and sets those;
+ * - a delete carries the key;
+ * - a reset empties the table, for the snapshot that follows to refill it.
+ */
+export declare function applyEntries(tx: ElectricTransaction, target: ApplyTarget, entries: LogEntry[]): Promise<void>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/electric/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/electric/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAc,MAAM,UAAU,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7E,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC,CAAC;CAC3F;AAED,0EAA0E;AAC1E,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,yBAAyB;AACzB,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,yDAAyD;IACzD,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,kCAAkC;AAClC,eAAO,MAAM,aAAa,uBAAiB,CAAC;AAE5C;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,mBAAmB,EACvB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,QAAQ,EAAE,GAClB,OAAO,CAAC,IAAI,CAAC,CAqDf"}

package/dist/electric/apply.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * apply.ts – one batch of Electric's shape log, applied in one transaction.
+ *
+ * Electric's rule is to apply operations only at `up-to-date`, as a whole:
+ * the store then always matches some state Postgres was in.  The caller runs
+ * this inside a Firebird transaction that also records the sync position, so
+ * the rows and the position commit together or not at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultColumn = void 0;
+exports.applyEntries = applyEntries;
+const values_1 = require("./values");
+/** The default column mapping. */
+exports.defaultColumn = values_1.firebirdColumn;
+/**
+ * Apply `entries` through `tx`.
+ *
+ * - an insert is `UPDATE OR INSERT … MATCHING (key)`, so one seen twice (a
+ *   replayed batch, a resync over rows already there) does no harm; a run of
+ *   inserts with the same columns goes through one prepared batch;
+ * - an update carries the key and the changed columns, and sets those;
+ * - a delete carries the key;
+ * - a reset empties the table, for the snapshot that follows to refill it.
+ */
+async function applyEntries(tx, target, entries) {
+    const key = target.primaryKey;
+    const keyWhere = key.map((c) => `${target.column(c)} = ?`).join(' AND ');
+    const keyValues = (value) => key.map((c) => {
+        if (!(c in value)) {
+            throw new Error(`A message for ${target.table} has no value for its key column ${c}`);
+        }
+        return convert(target, c, value[c]);
+    });
+    let pending = null;
+    const flush = async () => {
+        if (!pending)
+            return;
+        const { columns, rows } = pending;
+        pending = null;
+        const sql = `UPDATE OR INSERT INTO ${target.table} (${columns.map(target.column).join(', ')}) ` +
+            `VALUES (${columns.map(() => '?').join(', ')}) ` +
+            `MATCHING (${key.map(target.column).join(', ')})`;
+        if (rows.length === 1)
+            await tx.exec(sql, rows[0]);
+        else
+            await tx.execBatch(sql, rows);
+    };
+    for (const entry of entries) {
+        if (entry.kind === 'insert') {
+            const columns = Object.keys(entry.value);
+            const row = columns.map((c) => convert(target, c, entry.value[c]));
+            if (pending && sameColumns(pending.columns, columns)) {
+                pending.rows.push(row);
+            }
+            else {
+                await flush();
+                pending = { columns, rows: [row] };
+            }
+            continue;
+        }
+        await flush();
+        if (entry.kind === 'reset') {
+            await tx.exec(`DELETE FROM ${target.table}`);
+        }
+        else if (entry.kind === 'update') {
+            const changed = Object.keys(entry.value).filter((c) => !key.includes(c));
+            if (changed.length === 0)
+                continue;
+            await tx.exec(`UPDATE ${target.table} SET ${changed.map((c) => `${target.column(c)} = ?`).join(', ')} WHERE ${keyWhere}`, [...changed.map((c) => convert(target, c, entry.value[c])), ...keyValues(entry.value)]);
+        }
+        else {
+            await tx.exec(`DELETE FROM ${target.table} WHERE ${keyWhere}`, keyValues(entry.value));
+        }
+    }
+    await flush();
+}
+function convert(target, column, value) {
+    const info = target.schema[column];
+    if (!info) {
+        throw new Error(`Column ${column} is not in the shape's schema`);
+    }
+    return (0, values_1.toFirebird)(value, column, info);
+}
+function sameColumns(a, b) {
+    return a.length === b.length && a.every((c, i) => c === b[i]);
+}
+//# sourceMappingURL=apply.js.map

package/dist/electric/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/electric/apply.ts"],"names":[],"mappings":"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"}

package/dist/electric/index.d.ts

@@ -0,0 +1,133 @@
+/**
+ * firebird-wasm/electric – a Postgres table, through Electric, into Firebird.
+ *
+ * ```ts
+ * import { syncShapeToTable } from 'firebird-wasm/electric';
+ *
+ * await db.exec('CREATE TABLE items (id INTEGER PRIMARY KEY, title VARCHAR(100))');
+ * const sync = await syncShapeToTable(db, {
+ *   shape: { url: 'https://electric.example.com/v1/shape', params: { table: 'items' } },
+ *   table: 'items',
+ *   shapeKey: 'items',
+ * });
+ * await sync.upToDate;           // the first complete copy is in
+ * await sync.unsubscribe();
+ * ```
+ *
+ * Read-only: Electric streams changes out of Postgres and takes no writes,
+ * which go through the app's own API and come back down the shape.  Each
+ * batch Electric marks `up-to-date` is applied in one Firebird transaction
+ * with the sync position, so a reload resumes exactly where the database is.
+ * See docs/plans/electric-sync.md for the design and docs/integration.md for
+ * use.
+ *
+ * `@electric-sql/client` is an optional peer dependency: install it to use
+ * this module.
+ */
+import { ShapeStream } from '@electric-sql/client';
+import type { ShapeStreamOptions } from '@electric-sql/client';
+import type { ElectricTransaction } from './apply';
+export { tableFromSchema, checkSchema, toFirebird, firebirdColumn, firebirdName } from './values';
+export type { ElectricSchema, ElectricColumn } from './values';
+export type { ElectricTransaction } from './apply';
+export { createWriteQueue, WriteRejected } from './writes';
+export type { WriteQueue, WriteQueueOptions, LocalWrite, SendResult, WritesDatabase } from './writes';
+import type { WriteQueue } from './writes';
+/** What the sync needs of a database: `FirebirdBrowser` has it. */
+export interface ElectricDatabase {
+    transaction<T>(fn: (tx: ElectricTransaction) => Promise<T>): Promise<T>;
+}
+/** Options of {@link syncShapeToTable}. */
+export interface SyncShapeToTableOptions {
+    /**
+     * The shape, as `ShapeStream` takes it: `url` of Electric's `/v1/shape`
+     * (or a proxy in front of it), and `params` with at least `table`.
+     */
+    shape: ShapeOptions;
+    /** The Firebird table the rows go to, as written in Firebird SQL. */
+    table: string;
+    /**
+     * Where the sync position is kept, so that the next sync resumes rather
+     * than starting over; `null` starts over every time (and empties the
+     * table first).  One shape per key, and one shape per table.
+     */
+    shapeKey: string | null;
+    /** The primary key, as Postgres column names.  Default: the shape's own. */
+    primaryKey?: string[];
+    /** Firebird column names for Postgres columns, where the default mapping does not fit. */
+    columns?: Record<string, string>;
+    /**
+     * The event posted once per applied batch, delivered when it commits, so
+     * `useLiveQuery` and `db.live()` can follow the sync without a trigger.
+     * Default `electric_<shapeKey>`, or `electric_<table>` without a key.
+     */
+    event?: string | null;
+    /** Called when the sync stops on an error.  Default: console.error. */
+    onError?: (error: Error) => void;
+    /** Local writes to keep over what the sync applies, and to drop once confirmed: {@link createWriteQueue}. */
+    writes?: WriteQueue;
+    /** For tests: the ShapeStream class to use. */
+    ShapeStream?: typeof ShapeStream;
+}
+/** The shape options a sync passes on to `ShapeStream`. */
+export type ShapeOptions = Omit<ShapeStreamOptions, 'parser' | 'transformer' | 'columnMapper' | 'offset' | 'handle'>;
+/** One shape of {@link syncShapesToTables}. */
+export interface ShapeTableOptions {
+    /** The shape, as {@link SyncShapeToTableOptions.shape}. */
+    shape: ShapeOptions;
+    /** The Firebird table its rows go to. */
+    table: string;
+    /** The primary key, as Postgres column names.  Default: the shape's own. */
+    primaryKey?: string[];
+    /** Firebird column names for Postgres columns. */
+    columns?: Record<string, string>;
+}
+/** Options of {@link syncShapesToTables}. */
+export interface SyncShapesToTablesOptions {
+    /** The shapes, by a name of your choosing; one table each. */
+    shapes: Record<string, ShapeTableOptions>;
+    /**
+     * Where the positions are kept (one per shape, under `<key>:<name>`), so
+     * the next sync resumes; `null` starts over every time.
+     */
+    key: string | null;
+    /** The event posted once per committed batch.  Default `electric_<key>`, or none without a key. */
+    event?: string | null;
+    /** Called when the sync stops on an error.  Default: console.error. */
+    onError?: (error: Error) => void;
+    /** Local writes to keep over what the sync applies, and to drop once confirmed: {@link createWriteQueue}. */
+    writes?: WriteQueue;
+    /** For tests: the ShapeStream class to use. */
+    ShapeStream?: typeof ShapeStream;
+}
+/** A running sync.  Returned by {@link syncShapeToTable} and {@link syncShapesToTables}. */
+export interface ShapeSync {
+    /** Resolves when the first complete copy of the shape is in; rejects if the sync stops before. */
+    readonly upToDate: Promise<void>;
+    /** True once a batch marked up-to-date has been applied. */
+    readonly isUpToDate: boolean;
+    /** Why the sync stopped, if it stopped on an error. */
+    readonly error: Error | undefined;
+    /** Stop syncing.  The rows and the position stay; a later sync resumes. */
+    unsubscribe(): Promise<void>;
+}
+/**
+ * Keep `options.table` in step with a shape: an initial copy, then every
+ * change, until {@link ShapeSync.unsubscribe}.  The table must exist.
+ */
+export declare function syncShapeToTable(db: ElectricDatabase, options: SyncShapeToTableOptions): Promise<ShapeSync>;
+/**
+ * Keep several tables in step with several shapes, together: every batch is
+ * applied in one Firebird transaction with all the shapes' positions, so a
+ * Postgres transaction that wrote to two of them never shows in one table
+ * and not the other.
+ *
+ * A batch is applied once every shape has reached up-to-date after the last
+ * change it received.  Electric marks each up-to-date with the last
+ * Postgres position it has seen (`global_last_seen_lsn`); where it does, the
+ * shapes must also be at the same one, and a shape behind is asked to
+ * refresh, so the batch holds the whole of each transaction it holds any of.
+ * The tables must exist.
+ */
+export declare function syncShapesToTables(db: ElectricDatabase, options: SyncShapesToTablesOptions): Promise<ShapeSync>;
+//# sourceMappingURL=index.d.ts.map

package/dist/electric/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/electric/index.ts"],"names":[],"mappings":"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epB"}