firebird-wasm 0.7.0 → 0.8.0

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,83 @@
+/**
+ * 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';
+/** 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: Omit<ShapeStreamOptions, 'parser' | 'transformer' | 'columnMapper' | 'offset' | 'handle'>;
+    /** 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;
+    /** For tests: the ShapeStream class to use. */
+    ShapeStream?: typeof ShapeStream;
+}
+/** A running sync.  Returned by {@link syncShapeToTable}. */
+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>;
+//# 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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,WAAW,EAAqC,MAAM,sBAAsB,CAAC;AACtF,OAAO,KAAK,EAA+B,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE5F,OAAO,KAAK,EAAE,mBAAmB,EAAY,MAAM,SAAS,CAAC;AAI7D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAClG,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/D,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,mBAAmB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACzE;AAED,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,aAAa,GAAG,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;IACjG,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,+CAA+C;IAC/C,WAAW,CAAC,EAAE,OAAO,WAAW,CAAC;CAClC;AAED,6DAA6D;AAC7D,MAAM,WAAW,SAAS;IACxB,kGAAkG;IAClG,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IAClC,2EAA2E;IAC3E,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAUD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,SAAS,CAAC,CAqKpB"}

package/dist/electric/index.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.firebirdName = exports.firebirdColumn = exports.toFirebird = exports.checkSchema = exports.tableFromSchema = void 0;
+exports.syncShapeToTable = syncShapeToTable;
+const client_1 = require("@electric-sql/client");
+const apply_1 = require("./apply");
+const values_1 = require("./values");
+var values_2 = require("./values");
+Object.defineProperty(exports, "tableFromSchema", { enumerable: true, get: function () { return values_2.tableFromSchema; } });
+Object.defineProperty(exports, "checkSchema", { enumerable: true, get: function () { return values_2.checkSchema; } });
+Object.defineProperty(exports, "toFirebird", { enumerable: true, get: function () { return values_2.toFirebird; } });
+Object.defineProperty(exports, "firebirdColumn", { enumerable: true, get: function () { return values_2.firebirdColumn; } });
+Object.defineProperty(exports, "firebirdName", { enumerable: true, get: function () { return values_2.firebirdName; } });
+const METADATA = '"ELECTRIC_SHAPES"';
+/** Electric's own parsing, turned off for the types it parses: values stay Postgres text. */
+const IDENTITY = (value) => value;
+const KEEP_TEXT = Object.fromEntries(['int2', 'int4', 'int8', 'float4', 'float8', 'bool', 'json', 'jsonb'].map((t) => [t, IDENTITY]));
+/**
+ * Keep `options.table` in step with a shape: an initial copy, then every
+ * change, until {@link ShapeSync.unsubscribe}.  The table must exist.
+ */
+async function syncShapeToTable(db, options) {
+    const table = (0, values_1.firebirdName)(options.table);
+    const column = (name) => options.columns?.[name] !== undefined ? (0, values_1.firebirdName)(options.columns[name]) : (0, apply_1.defaultColumn)(name);
+    const eventName = options.event === undefined
+        ? `electric_${options.shapeKey ?? options.table}`
+        : options.event;
+    const report = options.onError ?? ((e) => console.error('[firebird-wasm/electric] sync stopped', e));
+    // Where a previous sync stopped.
+    let position;
+    // Its own transaction: Firebird applies DDL at commit, so a table made in
+    // a transaction cannot be read in that same transaction.
+    await db.transaction((tx) => ensureMetadata(tx));
+    await db.transaction(async (tx) => {
+        if (options.shapeKey !== null) {
+            const { rows } = await tx.query(`SELECT SHAPE_HANDLE, SHAPE_OFFSET, SHAPE_SCHEMA FROM ${METADATA} WHERE SHAPE_KEY = ?`, [options.shapeKey]);
+            const row = rows[0];
+            if (row && row['SHAPE_HANDLE'] && row['SHAPE_OFFSET']) {
+                position = {
+                    handle: String(row['SHAPE_HANDLE']),
+                    offset: String(row['SHAPE_OFFSET']),
+                    schema: JSON.parse(String(row['SHAPE_SCHEMA'] ?? '{}')),
+                };
+            }
+        }
+    });
+    let schema = position?.schema;
+    let checked = false;
+    // Operations received since the last up-to-date; applied together at the next.
+    let pending = options.shapeKey === null || !position ? [{ kind: 'reset' }] : [];
+    let upToDate = false;
+    let failure;
+    let stopped = false;
+    let applying = Promise.resolve();
+    let resolveReady;
+    let rejectReady;
+    const ready = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+    });
+    ready.catch(() => undefined);
+    const abort = new AbortController();
+    const userSignal = options.shape.signal;
+    if (userSignal)
+        userSignal.addEventListener('abort', () => abort.abort(), { once: true });
+    // The schema arrives as a header, which the client does not hand on.
+    const baseFetch = options.shape.fetchClient ?? ((...args) => fetch(...args));
+    const fetchClient = async (input, init) => {
+        const response = await baseFetch(input, init);
+        const header = response.headers.get('electric-schema');
+        if (header) {
+            schema = JSON.parse(header);
+            checked = false;
+        }
+        return response;
+    };
+    const Stream = options.ShapeStream ?? client_1.ShapeStream;
+    const stream = new Stream({
+        ...options.shape,
+        signal: abort.signal,
+        fetchClient,
+        parser: KEEP_TEXT,
+        ...(position ? { handle: position.handle, offset: position.offset } : {}),
+        onError: (error) => {
+            // The client has already retried what it retries; this is final.
+            void stop(error);
+        },
+    });
+    const stop = async (error) => {
+        if (stopped)
+            return;
+        stopped = true;
+        abort.abort();
+        stream.unsubscribeAll();
+        if (error) {
+            failure = error;
+            rejectReady(error);
+            report(error);
+        }
+    };
+    const apply = async (entries) => {
+        if (!schema)
+            throw new Error('Electric sent rows before a schema; the sync cannot map them');
+        if (!checked) {
+            (0, values_1.checkSchema)(schema);
+            checked = true;
+        }
+        const target = {
+            table,
+            column,
+            schema,
+            primaryKey: options.primaryKey ?? (0, values_1.primaryKeyOf)(schema),
+        };
+        if (target.primaryKey.length === 0) {
+            throw new Error(`The shape of ${options.table} has no primary key; pass primaryKey`);
+        }
+        const handle = stream.shapeHandle;
+        const offset = String(stream.lastOffset);
+        const schemaText = JSON.stringify(schema);
+        await db.transaction(async (tx) => {
+            await (0, apply_1.applyEntries)(tx, target, entries);
+            if (options.shapeKey !== null && handle) {
+                await tx.exec(`UPDATE OR INSERT INTO ${METADATA} (SHAPE_KEY, SHAPE_HANDLE, SHAPE_OFFSET, SHAPE_SCHEMA) ` +
+                    'VALUES (?, ?, ?, ?) MATCHING (SHAPE_KEY)', [options.shapeKey, handle, offset, schemaText]);
+            }
+            if (eventName) {
+                await tx.exec('EXECUTE BLOCK (event_name VARCHAR(127) = ?) AS BEGIN POST_EVENT :event_name; END', [eventName]);
+            }
+        });
+    };
+    stream.subscribe(async (messages) => {
+        if (stopped)
+            return;
+        for (const message of messages) {
+            if ((0, client_1.isChangeMessage)(message)) {
+                pending.push({ kind: message.headers.operation, value: message.value });
+            }
+            else if ((0, client_1.isControlMessage)(message) && message.headers.control === 'must-refetch') {
+                // What came before belongs to a shape that no longer exists.
+                pending = [{ kind: 'reset' }];
+            }
+            else if ((0, client_1.isControlMessage)(message) && message.headers.control === 'up-to-date') {
+                const entries = pending;
+                pending = [];
+                applying = applying.then(() => apply(entries));
+                try {
+                    await applying;
+                }
+                catch (err) {
+                    await stop(err instanceof Error ? err : new Error(String(err)));
+                    return;
+                }
+                if (!upToDate) {
+                    upToDate = true;
+                    resolveReady();
+                }
+            }
+        }
+    });
+    return {
+        upToDate: ready,
+        get isUpToDate() {
+            return upToDate;
+        },
+        get error() {
+            return failure;
+        },
+        unsubscribe: async () => {
+            await stop();
+            await applying.catch(() => undefined);
+            rejectReady(new Error('The sync was stopped before it was up to date'));
+        },
+    };
+}
+/** The table holding each shape's position, made on first use. */
+async function ensureMetadata(tx) {
+    const { rows } = await tx.query("SELECT 1 AS X FROM RDB$RELATIONS WHERE RDB$RELATION_NAME = 'ELECTRIC_SHAPES'");
+    if (rows.length > 0)
+        return;
+    await tx.exec(`CREATE TABLE ${METADATA} (` +
+        'SHAPE_KEY VARCHAR(255) NOT NULL PRIMARY KEY, ' +
+        'SHAPE_HANDLE VARCHAR(255), SHAPE_OFFSET VARCHAR(64), SHAPE_SCHEMA BLOB SUB_TYPE TEXT)');
+}
+//# sourceMappingURL=index.js.map

package/dist/electric/index.js.map

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

package/dist/electric/values.d.ts

@@ -0,0 +1,65 @@
+/**
+ * values.ts – Postgres values, as Electric sends them, into Firebird.
+ *
+ * Electric sends every value as Postgres's text output and describes the
+ * columns once, in the `electric-schema` response header.  This turns one
+ * into a parameter Firebird converts exactly, and refuses what it does not
+ * map by name rather than storing something that looks right and is not.
+ *
+ * Observed from Electric 1.8 (not all of it in the documentation): a boolean
+ * is `"true"` in the initial snapshot and `"f"` in a live update; a
+ * `timestamptz` arrives in UTC as `2024-05-01 10:00:00+00`; arrays are marked
+ * `dims`, and the primary key `pk_index`.
+ */
+/** One column of `electric-schema`. */
+export interface ElectricColumn {
+    type: string;
+    dims?: number;
+    pk_index?: number;
+    not_null?: boolean;
+    max_length?: number;
+    length?: number;
+    precision?: number;
+    scale?: number;
+}
+/** The `electric-schema` header, parsed: Postgres column name to its type. */
+export type ElectricSchema = Record<string, ElectricColumn>;
+/**
+ * Check that every column of `schema` can be stored, before any row is.
+ * @throws naming each column and type that cannot.
+ */
+export declare function checkSchema(schema: ElectricSchema): void;
+/**
+ * One value from Electric as a Firebird parameter.
+ *
+ * `value` is Electric's text, `null`, or for an array column the array the
+ * client parsed (of texts), which is stored as JSON.
+ */
+export declare function toFirebird(value: unknown, column: string, info: ElectricColumn): unknown;
+/**
+ * The Firebird identifier for a Postgres column, quoted.
+ *
+ * Postgres folds unquoted names to lower case and Firebird to upper, so a
+ * plain lower-case Postgres name maps to the upper-case Firebird name that
+ * the same unquoted word finds (`title` → `"TITLE"`).  Anything else was
+ * quoted in Postgres to exist and stays exactly as it is (`"camelCase"`).
+ */
+export declare function firebirdColumn(postgresName: string): string;
+/**
+ * A table or column name as written in Firebird SQL, quoted: `items` and
+ * `ITEMS` are `"ITEMS"`; a name given in double quotes keeps its case.
+ */
+export declare function firebirdName(name: string): string;
+/**
+ * `CREATE TABLE` for a shape's columns, to read and adjust before running.
+ *
+ * Unbounded text becomes `BLOB SUB_TYPE TEXT`, which cannot be part of a key
+ * or an index; a text primary key gets `VARCHAR(255)` instead, and is worth
+ * a look.  Nothing here runs the statement: what types a table should have
+ * is the app's call, and a later change to the Postgres table does not
+ * migrate this one.
+ */
+export declare function tableFromSchema(table: string, schema: ElectricSchema): string;
+/** The shape's primary key, as Postgres column names in key order. */
+export declare function primaryKeyOf(schema: ElectricSchema): string[];
+//# sourceMappingURL=values.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/electric/values.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AA2G5D;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAaxD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAQxF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjD;AAwCD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAe7E;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,EAAE,CAK7D"}