firebird-wasm 0.6.1 → 0.8.0

package/dist/frameworks/query-store.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * query-store.ts – a query's rows as a value a UI framework can watch.
+ *
+ * The React and Vue bindings are thin: each wraps a {@link QueryStore}, which
+ * runs a statement once (`query()`) or keeps it running (`live()`), and holds
+ * the latest `{ rows, error, loading }` for whoever subscribed.  What both
+ * frameworks get wrong in the same way without it lives here once: a result
+ * that arrives after the component moved on to another query, a live query
+ * that resolves after it was stopped, and a stop and restart of the same store
+ * (React's StrictMode does exactly that on every mount).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryStore = void 0;
+exports.resolveStatement = resolveStatement;
+exports.queryKey = queryKey;
+const sql_tag_1 = require("../sql-tag");
+/**
+ * One statement with its parameters, run against one database.
+ *
+ * Immutable in what it runs: other SQL or parameters make a new store, which
+ * is how a stale result can never land in the wrong one.
+ */
+class QueryStore {
+    constructor(db, sql, params, options = {}, placeholder) {
+        this.db = db;
+        this.sql = sql;
+        this.params = params;
+        this.options = options;
+        this.listeners = new Set();
+        /** Bumped by every start() and stop(); a result from an older run is dropped. */
+        this.generation = 0;
+        this.running = false;
+        /** The one-off run in flight, settled once its result or error is applied. */
+        this.pending = Promise.resolve();
+        /** For `useSyncExternalStore`: register a listener, get its removal. */
+        this.subscribe = (listener) => {
+            this.listeners.add(listener);
+            return () => {
+                this.listeners.delete(listener);
+            };
+        };
+        /** The current state; the same object until something changes. */
+        this.getSnapshot = () => this.state;
+        /** Run the statement again now, without waiting for an event. */
+        this.refresh = async () => {
+            if (!this.running)
+                return;
+            if (this.live === undefined) {
+                // A one-off query: run it again, and settle when its result is in.
+                this.stop();
+                this.start();
+                await this.pending;
+                return;
+            }
+            const live = await this.live;
+            if (live && this.running) {
+                await live.refresh();
+            }
+            else if (this.running) {
+                // The live query failed to start: try again.
+                this.stop();
+                this.start();
+            }
+        };
+        this.state = { rows: placeholder, error: undefined, loading: true };
+    }
+    /** Run the statement, and with events keep running it.  Idempotent. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        const generation = ++this.generation;
+        const current = () => generation === this.generation;
+        const events = this.options.events ?? [];
+        if (events.length === 0) {
+            this.pending = this.db.query(this.sql, this.params).then((result) => {
+                if (current())
+                    this.set({ rows: result.rows, error: undefined, loading: false });
+            }, (error) => {
+                if (current())
+                    this.fail(error);
+            });
+            return;
+        }
+        this.live = this.db
+            .live(this.sql, {
+            events: [...events],
+            params: this.params,
+            pollIntervalMs: this.options.pollIntervalMs,
+            onError: (error) => {
+                if (current())
+                    this.fail(error);
+            },
+        }, (rows) => {
+            if (current())
+                this.set({ rows, error: undefined, loading: false });
+        })
+            .then((live) => {
+            // Stopped while it was starting: nobody else will release it.
+            if (!current()) {
+                void live.unsubscribe();
+                return undefined;
+            }
+            return live;
+        }, (error) => {
+            if (current())
+                this.fail(error);
+            return undefined;
+        });
+    }
+    /** Stop watching; results still in flight are dropped.  start() may follow. */
+    stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        this.generation++;
+        const live = this.live;
+        this.live = undefined;
+        void live?.then((running) => running?.unsubscribe());
+    }
+    fail(error) {
+        this.set({
+            rows: this.state.rows,
+            error: error instanceof Error ? error : new Error(String(error)),
+            loading: false,
+        });
+    }
+    set(next) {
+        this.state = next;
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}
+exports.QueryStore = QueryStore;
+/**
+ * The statement a hook was given, resolved: SQL text and parameters from a
+ * string with parameters, or from an `sql` tagged template.
+ */
+function resolveStatement(query, params) {
+    const statement = (0, sql_tag_1.toStatement)(query, params ?? []);
+    return { sql: statement.sql, params: statement.params };
+}
+/**
+ * A string that is equal exactly when two calls would run the same thing.
+ *
+ * Components pass a fresh parameter array on every render; comparing by
+ * identity would restart the query each time.  Types JSON would merge are
+ * kept apart: a Date and its ISO string, a bigint and a number, bytes and an
+ * array of numbers.
+ */
+function queryKey(sql, params, options = {}) {
+    return JSON.stringify([sql, params, options.events ?? [], options.pollIntervalMs ?? null], function (key, value) {
+        const raw = this[key];
+        if (typeof raw === 'bigint')
+            return { $bigint: raw.toString() };
+        if (raw instanceof Date)
+            return { $date: raw.getTime() };
+        if (raw instanceof Uint8Array)
+            return { $bytes: Array.from(raw) };
+        if (raw === undefined && Array.isArray(this))
+            return { $undefined: true };
+        return value;
+    });
+}
+//# sourceMappingURL=query-store.js.map

package/dist/frameworks/query-store.js.map

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

package/dist/index.d.ts

@@ -20,6 +20,8 @@ export { sql, SqlFragment, RawSql, isSqlFragment, toStatement } from './sql-tag'
 export { statementKind } from './statement-types';
 export type { SqlTag, Statement } from './sql-tag';
 export type { FirebirdLiteOptions, QueryResult, QueryParams, Row, FieldInfo, QueryOptions, QueryDescription, StatementKind, RowMode, ArrayRow, TransactionOptions, IsolationLevel, } from './types';
-export { loadFirebirdWasm, allocString } from './wasm-loader';
+export { loadFirebirdWasm, allocString, wasmGlueFile, hasSharedHeap, cdnArtifacts } from './wasm-loader';
+export type { CdnOptions, CdnArtifacts } from './wasm-loader';
+export { VERSION } from './version';
 export type { FirebirdWasmModule, WasmLoadOptions, EmscriptenFS, FbHandle, } from './wasm-loader';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE/D,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEnD,YAAY,EACV,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,GAAG,EACH,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,OAAO,EACP,QAAQ,EACR,kBAAkB,EAClB,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,QAAQ,GACT,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE/D,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEnD,YAAY,EACV,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,GAAG,EACH,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,OAAO,EACP,QAAQ,EACR,kBAAkB,EAClB,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACzG,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,QAAQ,GACT,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -17,7 +17,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.allocString = exports.loadFirebirdWasm = exports.statementKind = exports.toStatement = exports.isSqlFragment = exports.RawSql = exports.SqlFragment = exports.sql = exports.FirebirdTransaction = exports.FirebirdLite = void 0;
+exports.VERSION = exports.cdnArtifacts = exports.hasSharedHeap = exports.wasmGlueFile = exports.allocString = exports.loadFirebirdWasm = exports.statementKind = exports.toStatement = exports.isSqlFragment = exports.RawSql = exports.SqlFragment = exports.sql = exports.FirebirdTransaction = exports.FirebirdLite = void 0;
 var firebird_1 = require("./firebird");
 Object.defineProperty(exports, "FirebirdLite", { enumerable: true, get: function () { return firebird_1.FirebirdLite; } });
 Object.defineProperty(exports, "FirebirdTransaction", { enumerable: true, get: function () { return firebird_1.FirebirdTransaction; } });
@@ -33,4 +33,9 @@ Object.defineProperty(exports, "statementKind", { enumerable: true, get: functio
 var wasm_loader_1 = require("./wasm-loader");
 Object.defineProperty(exports, "loadFirebirdWasm", { enumerable: true, get: function () { return wasm_loader_1.loadFirebirdWasm; } });
 Object.defineProperty(exports, "allocString", { enumerable: true, get: function () { return wasm_loader_1.allocString; } });
+Object.defineProperty(exports, "wasmGlueFile", { enumerable: true, get: function () { return wasm_loader_1.wasmGlueFile; } });
+Object.defineProperty(exports, "hasSharedHeap", { enumerable: true, get: function () { return wasm_loader_1.hasSharedHeap; } });
+Object.defineProperty(exports, "cdnArtifacts", { enumerable: true, get: function () { return wasm_loader_1.cdnArtifacts; } });
+var version_1 = require("./version");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_1.VERSION; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAEH,uCAA+D;AAAtD,wGAAA,YAAY,OAAA;AAAE,+GAAA,mBAAmB,OAAA;AAE1C,qCAAiF;AAAxE,8FAAA,GAAG,OAAA;AAAE,sGAAA,WAAW,OAAA;AAAE,iGAAA,MAAM,OAAA;AAAE,wGAAA,aAAa,OAAA;AAAE,sGAAA,WAAW,OAAA;AAC7D,qDAAkD;AAAzC,gHAAA,aAAa,OAAA;AAkBtB,2CAA2C;AAC3C,6CAA8D;AAArD,+GAAA,gBAAgB,OAAA;AAAE,0GAAA,WAAW,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAEH,uCAA+D;AAAtD,wGAAA,YAAY,OAAA;AAAE,+GAAA,mBAAmB,OAAA;AAE1C,qCAAiF;AAAxE,8FAAA,GAAG,OAAA;AAAE,sGAAA,WAAW,OAAA;AAAE,iGAAA,MAAM,OAAA;AAAE,wGAAA,aAAa,OAAA;AAAE,sGAAA,WAAW,OAAA;AAC7D,qDAAkD;AAAzC,gHAAA,aAAa,OAAA;AAkBtB,2CAA2C;AAC3C,6CAAyG;AAAhG,+GAAA,gBAAgB,OAAA;AAAE,0GAAA,WAAW,OAAA;AAAE,2GAAA,YAAY,OAAA;AAAE,4GAAA,aAAa,OAAA;AAAE,2GAAA,YAAY,OAAA;AAEjF,qCAAoC;AAA3B,kGAAA,OAAO,OAAA"}

package/dist/react/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * firebird-wasm/react – hooks that keep a component in step with a query.
+ *
+ * ```tsx
+ * import { FirebirdProvider, useLiveQuery } from 'firebird-wasm/react';
+ *
+ * <FirebirdProvider db={db}><Todos /></FirebirdProvider>
+ *
+ * function Todos() {
+ *   const { rows, error } = useLiveQuery<{ ID: number; TITLE: string }>(
+ *     'SELECT id, title FROM todos ORDER BY id', { events: ['todos'] });
+ *   if (error) return <p>{error.message}</p>;
+ *   return <ul>{rows?.map((r) => <li key={r.ID}>{r.TITLE}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * React 18 or later (`useSyncExternalStore`), a peer dependency the package
+ * does not install for you.
+ */
+import type { ReactNode } from 'react';
+import type { QueryableDatabase, QueryState } from '../frameworks/query-store';
+import type { SqlFragment } from '../sql-tag';
+import type { QueryParams, Row } from '../types';
+export type { QueryableDatabase, QueryState } from '../frameworks/query-store';
+/** Makes `db` the database of every hook below it. */
+export declare function FirebirdProvider(props: {
+    db: QueryableDatabase;
+    children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<QueryableDatabase | null>>;
+/** The database a `FirebirdProvider` above this component provides. */
+export declare function useFirebird<D extends QueryableDatabase = QueryableDatabase>(): D;
+/** What `useQuery` and `useLiveQuery` return. */
+export interface QueryHookResult<T> extends QueryState<T> {
+    /** Run the statement again now. */
+    refresh(): Promise<void>;
+}
+/** Options of {@link useQuery}. */
+export interface UseQueryOptions {
+    /** A database other than the provider's. */
+    db?: QueryableDatabase;
+}
+/** Options of {@link useLiveQuery}. */
+export interface UseLiveQueryOptions extends UseQueryOptions {
+    /** Event names whose firing re-runs the statement (`POST_EVENT`). */
+    events: readonly string[];
+    /** Parameters, when the statement is a string with `?` placeholders. */
+    params?: QueryParams;
+    /** How often to poll for events, in milliseconds.  @default 250 */
+    pollIntervalMs?: number;
+}
+/**
+ * Run a statement and render its rows.  It runs again when the SQL or the
+ * parameters change (by value: a new array with the same values does not).
+ *
+ * ```tsx
+ * const { rows, loading } = useQuery('SELECT * FROM todos WHERE done = ?', [false]);
+ * const { rows } = useQuery(sql`SELECT * FROM todos WHERE id = ${id}`);
+ * ```
+ */
+export declare function useQuery<T extends Row = Row>(query: string | SqlFragment, params?: QueryParams, options?: UseQueryOptions): QueryHookResult<T>;
+/**
+ * Like {@link useQuery}, and the statement runs again each time one of
+ * `events` fires: `FirebirdBrowser.live()` under a hook.  A trigger posts
+ * the events (`POST_EVENT 'todos'` after insert, update and delete), or the
+ * code that wrote calls `db.notify()`.
+ */
+export declare function useLiveQuery<T extends Row = Row>(query: string | SqlFragment, options: UseLiveQueryOptions): QueryHookResult<T>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAWH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAqB,MAAM,2BAA2B,CAAC;AAClG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEjD,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAI/E,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IAAE,EAAE,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,qGAEtF;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,KAAK,CAAC,CAShF;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACvD,mCAAmC;IACnC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,EAAE,CAAC,EAAE,iBAAiB,CAAC;CACxB;AAED,uCAAuC;AACvC,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,qEAAqE;IACrE,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG,EAC1C,KAAK,EAAE,MAAM,GAAG,WAAW,EAC3B,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,GAAE,eAAoB,GAC5B,eAAe,CAAC,CAAC,CAAC,CAEpB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG,EAC9C,KAAK,EAAE,MAAM,GAAG,WAAW,EAC3B,OAAO,EAAE,mBAAmB,GAC3B,eAAe,CAAC,CAAC,CAAC,CAQpB"}

package/dist/react/index.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * firebird-wasm/react – hooks that keep a component in step with a query.
+ *
+ * ```tsx
+ * import { FirebirdProvider, useLiveQuery } from 'firebird-wasm/react';
+ *
+ * <FirebirdProvider db={db}><Todos /></FirebirdProvider>
+ *
+ * function Todos() {
+ *   const { rows, error } = useLiveQuery<{ ID: number; TITLE: string }>(
+ *     'SELECT id, title FROM todos ORDER BY id', { events: ['todos'] });
+ *   if (error) return <p>{error.message}</p>;
+ *   return <ul>{rows?.map((r) => <li key={r.ID}>{r.TITLE}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * React 18 or later (`useSyncExternalStore`), a peer dependency the package
+ * does not install for you.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirebirdProvider = FirebirdProvider;
+exports.useFirebird = useFirebird;
+exports.useQuery = useQuery;
+exports.useLiveQuery = useLiveQuery;
+const react_1 = require("react");
+const query_store_1 = require("../frameworks/query-store");
+const FirebirdContext = (0, react_1.createContext)(null);
+/** Makes `db` the database of every hook below it. */
+function FirebirdProvider(props) {
+    return (0, react_1.createElement)(FirebirdContext.Provider, { value: props.db }, props.children);
+}
+/** The database a `FirebirdProvider` above this component provides. */
+function useFirebird() {
+    const db = (0, react_1.useContext)(FirebirdContext);
+    if (db === null) {
+        throw new Error('useFirebird() found no database: wrap the component in <FirebirdProvider db={…}>, ' +
+            'or pass { db } to the hook');
+    }
+    return db;
+}
+/**
+ * Run a statement and render its rows.  It runs again when the SQL or the
+ * parameters change (by value: a new array with the same values does not).
+ *
+ * ```tsx
+ * const { rows, loading } = useQuery('SELECT * FROM todos WHERE done = ?', [false]);
+ * const { rows } = useQuery(sql`SELECT * FROM todos WHERE id = ${id}`);
+ * ```
+ */
+function useQuery(query, params, options = {}) {
+    return useStore(options.db, query, params, {});
+}
+/**
+ * Like {@link useQuery}, and the statement runs again each time one of
+ * `events` fires: `FirebirdBrowser.live()` under a hook.  A trigger posts
+ * the events (`POST_EVENT 'todos'` after insert, update and delete), or the
+ * code that wrote calls `db.notify()`.
+ */
+function useLiveQuery(query, options) {
+    if (options.events.length === 0) {
+        throw new RangeError('useLiveQuery() needs at least one event name; useQuery() runs a statement once');
+    }
+    return useStore(options.db, query, options.params, {
+        events: options.events,
+        pollIntervalMs: options.pollIntervalMs,
+    });
+}
+function useStore(explicitDb, query, params, storeOptions) {
+    const provided = (0, react_1.useContext)(FirebirdContext);
+    const db = explicitDb ?? provided;
+    if (db === null) {
+        throw new Error('No database for this query: wrap the component in <FirebirdProvider db={…}>, ' +
+            'or pass { db } to the hook');
+    }
+    const statement = (0, query_store_1.resolveStatement)(query, params);
+    const key = (0, query_store_1.queryKey)(statement.sql, statement.params, storeOptions);
+    // The last store this component ran, for its rows while the next one loads.
+    const previous = (0, react_1.useRef)(null);
+    const store = (0, react_1.useMemo)(() => new query_store_1.QueryStore(db, statement.sql, statement.params, storeOptions, previous.current?.getSnapshot().rows), 
+    // `key` stands for the statement, its parameters and the options, which
+    // are new objects on every render.
+    [db, key]);
+    (0, react_1.useEffect)(() => {
+        previous.current = store;
+        store.start();
+        return () => store.stop();
+    }, [store]);
+    const state = (0, react_1.useSyncExternalStore)(store.subscribe, store.getSnapshot, store.getSnapshot);
+    return (0, react_1.useMemo)(() => ({ ...state, refresh: store.refresh }), [state, store]);
+}
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

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

package/dist/repl/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * firebird-wasm/repl – an interactive SQL console as a custom element.
+ *
+ * ```js
+ * import { defineFirebirdRepl } from 'firebird-wasm/repl';
+ *
+ * defineFirebirdRepl();                       // registers <firebird-repl>
+ * document.querySelector('firebird-repl').db = db;
+ * ```
+ *
+ * A custom element, so it works the same in plain pages, React and Vue: give
+ * it a database through its `db` property.  Type SQL, run it with
+ * Ctrl+Enter (⌘+Enter on a Mac) or the Run button; a script runs statement by
+ * statement (`SET TERM` included) and stops at the first error.  ArrowUp on
+ * the first line and ArrowDown on the last walk the history.
+ *
+ * Every value is written as text, never as HTML, so a row cannot inject
+ * markup into the page.  The element draws in its own shadow root; colours
+ * follow `color-scheme` and can be set with `--firebird-repl-*` properties.
+ *
+ * Nothing runs on import: the class is made by {@link defineFirebirdRepl},
+ * so importing this module where there is no DOM (Node, server rendering) is
+ * harmless.
+ */
+import type { ArrayRow, FieldInfo, QueryResult } from '../types';
+/** What the console needs of a database: `FirebirdBrowser` has it. */
+export interface ReplDatabase {
+    query(sql: string, params: unknown[], options: {
+        rowMode: 'array';
+    }): Promise<QueryResult<ArrayRow>>;
+    /** Whether a statement yields rows, before running it. */
+    describeQuery(sql: string): Promise<{
+        hasResultSet: boolean;
+    }>;
+    /**
+     * For a statement without rows: a transaction's `exec()` runs exactly one
+     * statement and reports what it changed.  (`FirebirdBrowser.exec()` would
+     * split the statement again, cutting a PSQL body at its semicolons.)
+     */
+    transaction<T>(fn: (tx: {
+        exec(sql: string): Promise<{
+            affectedRows: number;
+        }>;
+    }) => Promise<T>): Promise<T>;
+}
+/** One statement the console ran, as it reports it in `firebird-repl-run`. */
+export interface ReplEntry {
+    sql: string;
+    /** 1-based line of the statement in what was run. */
+    line: number;
+    /** Milliseconds the statement took. */
+    ms: number;
+    fields?: FieldInfo[];
+    rows?: ArrayRow[];
+    affectedRows?: number;
+    error?: Error;
+}
+/** The element's own API, beyond HTMLElement's. */
+export interface FirebirdReplElement extends HTMLElement {
+    /** The database statements run against. */
+    db: ReplDatabase | null;
+    /** The editor's text. */
+    value: string;
+    /** Run `script` (default: the editor's text); resolves with what each statement did. */
+    run(script?: string): Promise<ReplEntry[]>;
+    /** Empty the output. */
+    clear(): void;
+}
+/**
+ * Register the element under `tag` (default `firebird-repl`) and return its
+ * class.  Calling it again returns the class already registered.
+ */
+export declare function defineFirebirdRepl(tag?: string): {
+    new (): FirebirdReplElement;
+};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/repl/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEjE,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrG,0DAA0D;IAC1D,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC/D;;;;OAIG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9G;AAED,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,2CAA2C;IAC3C,EAAE,EAAE,YAAY,GAAG,IAAI,CAAC;IACxB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC3C,wBAAwB;IACxB,KAAK,IAAI,IAAI,CAAC;CACf;AAiDD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,SAAkB,GAAG;IAAE,QAAQ,mBAAmB,CAAA;CAAE,CAsLzF"}