@nshiab/simple-data-analysis-core 1.0.1 → 2.0.0

package/esm/helpers/pendingOps.d.ts

@@ -0,0 +1,151 @@
+import type { DuckDBValue } from "@duckdb/node-api";
+/**
+ * The types of a table's schema, as returned by DESCRIBE: column names mapped
+ * to DuckDB types (e.g., { name: "VARCHAR", salary: "BIGINT" }).
+ */
+export type TableSchema = {
+    [column: string]: string;
+};
+/**
+ * A queued operation that can be expressed as a single SELECT over its input.
+ * At flush time, consecutive fusable operations on the same table are
+ * composed as CTEs into one statement.
+ */
+export type FusableOp = {
+    kind: "fusable";
+    /** The SDA method that queued the operation (e.g., "filter()"). */
+    method: string;
+    /** The parameters passed to the method, for error reporting. */
+    parameters: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * The operation's position in program order across all tables of the
+     * database, stamped by queueOp.
+     */
+    sequence: number;
+    /**
+     * Whether buildSelect needs the schema of its input relation. When `false`,
+     * the flush compiler skips the DESCRIBE round-trip and passes an empty
+     * schema.
+     */
+    needsSchema: boolean;
+    /**
+     * Whether the SELECT uses spatial functions. The flush compiler loads the
+     * spatial extension once per connection before executing such operations.
+     */
+    needsSpatial?: boolean;
+    /**
+     * The user-supplied SQL fragments embedded verbatim in the SELECT (e.g.,
+     * filter conditions, addColumn definitions). Such SQL can reference tables
+     * by name, and names don't follow a fused chain: a subquery on the
+     * operation's own table would read the pre-chain state instead of the
+     * previous step's output. The flush compiler scans these fragments and
+     * executes the operation against materialized tables when they reference
+     * one.
+     */
+    rawSQL?: string[];
+    /**
+     * Whether the operation's fused segment must be rooted in a materialized
+     * table rather than an external source. Used when DuckDB's source execution
+     * shape affects an observable result such as deterministic sampled-row
+     * order.
+     */
+    requiresMaterializedInput?: boolean;
+    /** Data values bound to placeholders in this operation's SELECT. */
+    values?: DuckDBValue[] | ((schema: TableSchema) => DuckDBValue[]);
+    /**
+     * Whether the SELECT returns exactly the schema of its input (same columns,
+     * same types), like `SELECT * REPLACE` with type-preserving expressions.
+     * The flush compiler reuses the schema across consecutive
+     * schema-preserving operations instead of running a DESCRIBE per step.
+     */
+    preservesSchema?: boolean;
+    /**
+     * Derives the output schema from a known input schema without another
+     * DESCRIBE query. Used by projections and explicit casts whose output types
+     * are fully determined by their arguments.
+     */
+    outputSchema?: (input: TableSchema) => TableSchema;
+    /**
+     * Returns a single SELECT statement over `input`, which is either the
+     * quoted table name or the alias of the previous CTE in the fused chain.
+     */
+    buildSelect: (input: string, schema: TableSchema) => string;
+};
+/**
+ * A queued operation that starts a fused segment from an external relational
+ * source instead of consuming the target table's current contents.
+ */
+export type SourceOp = {
+    kind: "source";
+    /** The SDA method that queued the source (e.g., "loadData()"). */
+    method: string;
+    /** The parameters passed to the method, for error reporting. */
+    parameters: {
+        [key: string]: unknown;
+    } | null;
+    /** The operation's position in database-wide program order. */
+    sequence: number;
+    /**
+     * User-supplied SQL fragments or table names read by the source. They close
+     * pending segments for those tables before the source executes.
+     */
+    rawSQL?: string[];
+    /** A schema known from explicit source options, when inference is unnecessary. */
+    schema?: TableSchema;
+    /** Returns the source as a single composable SELECT statement. */
+    buildSelect: () => string;
+};
+/** A relational operation that can participate in a fused segment. */
+export type RelationalOp = SourceOp | FusableOp;
+/**
+ * A queued operation that is multi-statement by nature (or otherwise cannot
+ * be expressed as a single SELECT). Barriers execute in order between fused
+ * segments.
+ */
+export type BarrierOp = {
+    kind: "barrier";
+    /** The SDA method that queued the operation (e.g., "loadData()"). */
+    method: string;
+    /** The parameters passed to the method, for error reporting. */
+    parameters: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * The operation's position in program order across all tables of the
+     * database, stamped by queueOp.
+     */
+    sequence: number;
+    /** Executes the operation. */
+    execute: () => Promise<void>;
+};
+/**
+ * An asynchronous extension barrier whose callback can queue builder methods.
+ * Nested operations drain before the callback observes the database and before
+ * the original chain continues.
+ */
+export type AsyncBarrierOp = {
+    kind: "asyncBarrier";
+    /** The extension method that queued the operation. */
+    method: string;
+    /** The parameters passed to the extension method, for error reporting. */
+    parameters: {
+        [key: string]: unknown;
+    } | null;
+    /** The operation's position in database-wide program order. */
+    sequence: number;
+    /** Executes the asynchronous extension operation. */
+    execute: () => Promise<void>;
+};
+/**
+ * An operation queued by a sync builder or extension method, executed when
+ * the pending chains are flushed at an observation point.
+ */
+export type PendingOp = RelationalOp | BarrierOp | AsyncBarrierOp;
+/**
+ * A pending operation as built by a sync builder or extension method, before
+ * queueOp stamps it with its program-order sequence.
+ */
+export type PendingOpInput = Omit<FusableOp, "sequence"> | Omit<SourceOp, "sequence"> | Omit<BarrierOp, "sequence"> | Omit<AsyncBarrierOp, "sequence">;
+//# sourceMappingURL=pendingOps.d.ts.map

package/esm/helpers/pendingOps.d.ts.map

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

package/esm/helpers/pendingOps.js

@@ -0,0 +1 @@
+export {};

package/esm/helpers/prepareDbExtensions.d.ts

@@ -0,0 +1,4 @@
+import type SimpleDB from "../class/SimpleDB.js";
+import type { IndexDefinition } from "./indexDefinitions.js";
+export default function prepareDbExtensions(sdb: SimpleDB, database: string, indexes: Record<string, IndexDefinition[]>): Promise<void>;
+//# sourceMappingURL=prepareDbExtensions.d.ts.map

package/esm/helpers/prepareDbExtensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareDbExtensions.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareDbExtensions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,wBAA8B,mBAAmB,CAC/C,GAAG,EAAE,QAAQ,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,GACzC,OAAO,CAAC,IAAI,CAAC,CAiDf"}

package/esm/helpers/prepareDbExtensions.js

@@ -0,0 +1,22 @@
+import queryDbFile from "./queryDbFile.js";
+import parseValue from "./parseValue.js";
+export default async function prepareDbExtensions(sdb, database, indexes) {
+    const definitions = Object.values(indexes).flat();
+    const physicalIndexes = await queryDbFile(sdb, `SELECT sql FROM duckdb_indexes() WHERE database_name = ${parseValue(database)};`, { returnData: true });
+    if (definitions.some((index) => index.kind === "vss") ||
+        physicalIndexes.some((index) => /\bUSING\s+HNSW\b/i.test(String(index.sql)))) {
+        await queryDbFile(sdb, "INSTALL vss; LOAD vss; SET hnsw_enable_experimental_persistence = true;");
+    }
+    const ftsSchemas = await queryDbFile(sdb, `SELECT schema_name FROM duckdb_schemas() WHERE database_name = ${parseValue(database)} AND starts_with(schema_name, 'fts_');`, { returnData: true });
+    if (definitions.some((index) => index.kind === "fts") || ftsSchemas.length > 0) {
+        await queryDbFile(sdb, "INSTALL fts; LOAD fts;");
+    }
+    if (!sdb.spatialLoaded) {
+        const geometryColumns = await queryDbFile(sdb, `SELECT column_name FROM duckdb_columns()
+       WHERE database_name = ${parseValue(database)} AND data_type ILIKE '%GEOMETRY%' LIMIT 1;`, { returnData: true });
+        if (geometryColumns.length > 0) {
+            await queryDbFile(sdb, "INSTALL spatial; LOAD spatial; SET geometry_always_xy = true;");
+            sdb.spatialLoaded = true;
+        }
+    }
+}

package/esm/helpers/prepareValueFilters.d.ts

@@ -0,0 +1,11 @@
+import type { DuckDBValue } from "@duckdb/node-api";
+export type ValueFilter = {
+    column: string;
+    values: DuckDBValue[];
+    includesNull: boolean;
+};
+/** Converts column filter values to bindable values while tracking nulls. */
+export default function prepareValueFilters(columnsAndValues: {
+    [key: string]: unknown;
+}): ValueFilter[];
+//# sourceMappingURL=prepareValueFilters.d.ts.map

package/esm/helpers/prepareValueFilters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareValueFilters.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareValueFilters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,OAAO,UAAU,mBAAmB,CACzC,gBAAgB,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAC3C,WAAW,EAAE,CAWf"}

package/esm/helpers/prepareValueFilters.js

@@ -0,0 +1,12 @@
+import toDuckDBValue from "./toDuckDBValue.js";
+/** Converts column filter values to bindable values while tracking nulls. */
+export default function prepareValueFilters(columnsAndValues) {
+    return Object.entries(columnsAndValues).map(([column, value]) => {
+        const boundValues = (Array.isArray(value) ? value : [value]).map(toDuckDBValue);
+        return {
+            column,
+            values: boundValues.filter((boundValue) => boundValue !== null),
+            includesNull: boundValues.some((boundValue) => boundValue === null),
+        };
+    });
+}

package/esm/helpers/queryDB.d.ts

@@ -1,19 +1,54 @@
+import type { DuckDBValue as NativeDuckDBValue } from "@duckdb/node-api";
 import SimpleTable from "../class/SimpleTable.js";
 import SimpleDB from "../class/SimpleDB.js";
+/** @internal DuckDB owns this type; retain its exact binding contract without re-exporting it. */
+type DuckDBValue = NativeDuckDBValue;
+/**
+ * Executes SQL for a table or database after flushing all queued operations.
+ * Starts the database on first use and applies its SQL logging settings.
+ * Extension authors can construct `options` with `mergeOptions()`.
+ *
+ * @param simple - The table or database that owns the query.
+ * @param query - The SQL statement to execute.
+ * @param options - Query execution and diagnostic settings.
+ * @param options.table - The table name used for diagnostics, or `null`.
+ * @param options.method - The calling method used for diagnostics, or `null`.
+ * @param options.parameters - Arguments included in error diagnostics, or `null`.
+ * @param options.rowsToLog - The caller's row-display limit, retained for compatibility.
+ * @param options.charsToLog - The caller's per-cell display limit, retained for compatibility.
+ * @param options.returnData - Whether to convert and return the result rows.
+ * @param options.values - DuckDB-native values bound to SQL placeholders, in order.
+ * @param options.noClean - Whether to preserve the SQL text without cleaning it.
+ * @returns Converted rows when `returnData` is true, otherwise `null`.
+ *
+ * @example
+ * ```ts
+ * import { mergeOptions, queryDB, quoteIdentifier } from "@nshiab/simple-data-analysis-core/helpers";
+ *
+ * await table.loadArray([{ answer: 0 }]).run();
+ * const query = `UPDATE ${quoteIdentifier(table.name)} SET answer = ?`;
+ * await queryDB(table, query, mergeOptions(table, {
+ *   table: table.name,
+ *   method: "example()",
+ *   parameters: null,
+ *   values: [42],
+ * }));
+ * await table.log();
+ * ```
+ */
 export default function queryDB(simple: SimpleTable | SimpleDB, query: string, options: {
     table: string | null;
     method: string | null;
     parameters: {
         [key: string]: unknown;
     } | null;
-    nbRowsToLog: number;
-    nbCharactersToLog: number | undefined;
-    returnDataFrom: "query" | "none";
-    debug: boolean;
-    types?: {
-        [key: string]: string;
-    };
+    rowsToLog: number;
+    charsToLog: number | undefined;
+    returnData: boolean;
+    values?: DuckDBValue[];
+    noClean?: boolean;
 }): Promise<{
-    [key: string]: string | number | boolean | Date | null;
+    [key: string]: unknown;
 }[] | null>;
+export {};
 //# sourceMappingURL=queryDB.d.ts.map

package/esm/helpers/queryDB.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queryDB.d.ts","sourceRoot":"","sources":["../../src/helpers/queryDB.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,yBAAyB,CAAC;AAClD,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAG5C,wBAA8B,OAAO,CACnC,MAAM,EAAE,WAAW,GAAG,QAAQ,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,cAAc,EAAE,OAAO,GAAG,MAAM,CAAC;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACnC,GACA,OAAO,CACN;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC;CACxD,EAAE,GACD,IAAI,CACP,CA+DA"}
+{"version":3,"file":"queryDB.d.ts","sourceRoot":"","sources":["../../src/helpers/queryDB.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,WAAW,MAAM,yBAAyB,CAAC;AAClD,OAAO,QAAQ,MAAM,sBAAsB,CAAC;AAK5C,kGAAkG;AAClG,KAAK,WAAW,GAAG,iBAAiB,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAA8B,OAAO,CACnC,MAAM,EAAE,WAAW,GAAG,QAAQ,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA,OAAO,CACN;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,EAAE,GACD,IAAI,CACP,CAuDA"}

package/esm/helpers/queryDB.js

@@ -1,7 +1,49 @@
 import SimpleTable from "../class/SimpleTable.js";
 import SimpleDB from "../class/SimpleDB.js";
 import cleanSQL from "./cleanSQL.js";
+import flushAllTables from "./flushAllTables.js";
+import { recordCacheTableAccess } from "./cacheTableDependencies.js";
+/**
+ * Executes SQL for a table or database after flushing all queued operations.
+ * Starts the database on first use and applies its SQL logging settings.
+ * Extension authors can construct `options` with `mergeOptions()`.
+ *
+ * @param simple - The table or database that owns the query.
+ * @param query - The SQL statement to execute.
+ * @param options - Query execution and diagnostic settings.
+ * @param options.table - The table name used for diagnostics, or `null`.
+ * @param options.method - The calling method used for diagnostics, or `null`.
+ * @param options.parameters - Arguments included in error diagnostics, or `null`.
+ * @param options.rowsToLog - The caller's row-display limit, retained for compatibility.
+ * @param options.charsToLog - The caller's per-cell display limit, retained for compatibility.
+ * @param options.returnData - Whether to convert and return the result rows.
+ * @param options.values - DuckDB-native values bound to SQL placeholders, in order.
+ * @param options.noClean - Whether to preserve the SQL text without cleaning it.
+ * @returns Converted rows when `returnData` is true, otherwise `null`.
+ *
+ * @example
+ * ```ts
+ * import { mergeOptions, queryDB, quoteIdentifier } from "@nshiab/simple-data-analysis-core/helpers";
+ *
+ * await table.loadArray([{ answer: 0 }]).run();
+ * const query = `UPDATE ${quoteIdentifier(table.name)} SET answer = ?`;
+ * await queryDB(table, query, mergeOptions(table, {
+ *   table: table.name,
+ *   method: "example()",
+ *   parameters: null,
+ *   values: [42],
+ * }));
+ * await table.log();
+ * ```
+ */
 export default async function queryDB(simple, query, options) {
+    if (simple instanceof SimpleTable) {
+        recordCacheTableAccess(simple);
+    }
+    const sdb = simple instanceof SimpleTable ? simple.sdb : simple;
+    if (sdb.lifecycleState === "closed") {
+        throw new Error(`${options.method ?? "The query"} cannot run because its SimpleDB is closed.`);
+    }
     if (simple instanceof SimpleDB && simple.connection === undefined) {
         await simple.start();
     }
@@ -14,49 +56,26 @@ export default async function queryDB(simple, query, options) {
     if (simple.connection === undefined) {
         throw new Error("simple.connection is undefined");
     }
-    query = cleanSQL(query);
-    if (options.debug) {
-        // We beautify it a little bit
-        if (query.at(-1) !== ";") {
-            query += ";";
-        }
-        if (query.includes("\n")) {
-            query = query
-                .trim()
-                .split("\n")
-                .map((line) => line.trim())
-                .filter((line) => line !== "" && line !== ";")
-                .join("\n");
-        }
-        console.log(query);
-    }
-    let data = null;
-    if (options.returnDataFrom === "none") {
-        await simple.runQuery(query, simple.connection, false, options);
-    }
-    else if (options.returnDataFrom === "query") {
-        data = await simple.runQuery(query, simple.connection, true, {
-            ...options,
-            // To convert dates and bigInts to numbers
-            types: options.method !== "getTypes()"
-                ? options.types
-                    ? options.types
-                    : simple instanceof SimpleTable
-                        ? await simple.getTypes()
-                        : undefined
-                : undefined,
-        });
-    }
-    else {
-        throw new Error(`Unknown ${options.returnDataFrom} options.returnDataFrom`);
+    // Observing executes: any query touching the database first flushes the
+    // operations queued by sync builder methods, preserving program order.
+    await flushAllTables(simple instanceof SimpleTable ? simple.sdb : simple);
+    if (options.noClean !== true) {
+        query = cleanSQL(query);
     }
-    if (options.returnDataFrom === "query") {
+    const executionOptions = {
+        ...options,
+        logSQL: sdb.logSQL,
+        explainSQL: sdb.explainSQL,
+    };
+    if (options.returnData) {
+        const data = await simple.runQuery(query, simple.connection, true, executionOptions);
         if (data === null) {
             throw new Error("data is null");
         }
         return data;
     }
     else {
+        await simple.runQuery(query, simple.connection, false, executionOptions);
         return null;
     }
 }

package/esm/helpers/queryDbFile.d.ts

@@ -0,0 +1,8 @@
+import type SimpleDB from "../class/SimpleDB.js";
+/** Executes generated database-file SQL without rewriting paths or metadata. */
+export default function queryDbFile(sdb: SimpleDB, sql: string, options?: {
+    returnData?: boolean;
+}): Promise<{
+    [key: string]: unknown;
+}[] | null>;
+//# sourceMappingURL=queryDbFile.d.ts.map

package/esm/helpers/queryDbFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryDbFile.d.ts","sourceRoot":"","sources":["../../src/helpers/queryDbFile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AAIjD,gFAAgF;AAChF,MAAM,CAAC,OAAO,UAAU,WAAW,CACjC,GAAG,EAAE,QAAQ,EACb,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO;;YAavC"}

package/esm/helpers/queryDbFile.js

@@ -0,0 +1,12 @@
+import queryDB from "./queryDB.js";
+import mergeOptions from "./mergeOptions.js";
+/** Executes generated database-file SQL without rewriting paths or metadata. */
+export default function queryDbFile(sdb, sql, options = {}) {
+    return queryDB(sdb, sql, mergeOptions(sdb, {
+        table: null,
+        method: "database file operation",
+        parameters: null,
+        returnData: options.returnData,
+        noClean: true,
+    }));
+}

package/esm/helpers/queueAsyncBarrier.d.ts

@@ -0,0 +1,47 @@
+import type SimpleTable from "../class/SimpleTable.js";
+/**
+ * Queues asynchronous extension work as one ordered table-builder step.
+ * Builder operations queued by `execute` are scoped to the barrier and drain
+ * before its observer queries and before later chained operations.
+ *
+ * `execute` must await all asynchronous work that can queue table operations.
+ * Detached work is outside the barrier's program-order scope.
+ *
+ * If `execute` rejects, captured builder operations that have not already
+ * drained are discarded. Operations drained by an observer inside `execute`
+ * remain applied; an asynchronous barrier does not provide database rollback.
+ *
+ * @param simpleTable - The table whose chain owns the asynchronous work.
+ * @param operation - The asynchronous extension operation to queue.
+ * @param operation.method - The public method name used for diagnostics.
+ * @param operation.parameters - A snapshot of the public method parameters used for diagnostics.
+ * @param operation.execute - The asynchronous work to run at the barrier's position in the chain.
+ * @returns Nothing. The public builder should return its target table.
+ *
+ * @example
+ * ```ts
+ * import type { SimpleTable } from "@nshiab/simple-data-analysis-core";
+ * import { queueAsyncBarrier } from "@nshiab/simple-data-analysis-core/helpers";
+ *
+ * function loadRemote(table: SimpleTable, url: string): SimpleTable {
+ *   queueAsyncBarrier(table, {
+ *     method: "loadRemote()",
+ *     parameters: { url },
+ *     execute: async () => {
+ *       const rows = await fetch(url).then((response) => response.json()) as
+ *         { [key: string]: unknown }[];
+ *       table.loadArray(rows);
+ *     },
+ *   });
+ *   return table;
+ * }
+ * ```
+ */
+export default function queueAsyncBarrier(simpleTable: SimpleTable, operation: {
+    method: string;
+    parameters: {
+        [key: string]: unknown;
+    } | null;
+    execute: () => Promise<void>;
+}): void;
+//# sourceMappingURL=queueAsyncBarrier.d.ts.map

package/esm/helpers/queueAsyncBarrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queueAsyncBarrier.d.ts","sourceRoot":"","sources":["../../src/helpers/queueAsyncBarrier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACvC,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE;IACT,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,GACA,IAAI,CAKN"}

package/esm/helpers/queueAsyncBarrier.js

@@ -0,0 +1,45 @@
+import queueOp from "./queueOp.js";
+/**
+ * Queues asynchronous extension work as one ordered table-builder step.
+ * Builder operations queued by `execute` are scoped to the barrier and drain
+ * before its observer queries and before later chained operations.
+ *
+ * `execute` must await all asynchronous work that can queue table operations.
+ * Detached work is outside the barrier's program-order scope.
+ *
+ * If `execute` rejects, captured builder operations that have not already
+ * drained are discarded. Operations drained by an observer inside `execute`
+ * remain applied; an asynchronous barrier does not provide database rollback.
+ *
+ * @param simpleTable - The table whose chain owns the asynchronous work.
+ * @param operation - The asynchronous extension operation to queue.
+ * @param operation.method - The public method name used for diagnostics.
+ * @param operation.parameters - A snapshot of the public method parameters used for diagnostics.
+ * @param operation.execute - The asynchronous work to run at the barrier's position in the chain.
+ * @returns Nothing. The public builder should return its target table.
+ *
+ * @example
+ * ```ts
+ * import type { SimpleTable } from "@nshiab/simple-data-analysis-core";
+ * import { queueAsyncBarrier } from "@nshiab/simple-data-analysis-core/helpers";
+ *
+ * function loadRemote(table: SimpleTable, url: string): SimpleTable {
+ *   queueAsyncBarrier(table, {
+ *     method: "loadRemote()",
+ *     parameters: { url },
+ *     execute: async () => {
+ *       const rows = await fetch(url).then((response) => response.json()) as
+ *         { [key: string]: unknown }[];
+ *       table.loadArray(rows);
+ *     },
+ *   });
+ *   return table;
+ * }
+ * ```
+ */
+export default function queueAsyncBarrier(simpleTable, operation) {
+    queueOp(simpleTable, {
+        kind: "asyncBarrier",
+        ...operation,
+    });
+}

package/esm/helpers/queueOp.d.ts

@@ -0,0 +1,18 @@
+import type SimpleDB from "../class/SimpleDB.js";
+import type SimpleTable from "../class/SimpleTable.js";
+import type { PendingOpInput } from "./pendingOps.js";
+/**
+ * Queues an internal relational operation, barrier, or asynchronous barrier.
+ *
+ * @internal
+ */
+export default function queueOp(simpleTable: SimpleTable, op: PendingOpInput): void;
+/**
+ * Empties every table's pending queue without executing it and returns what
+ * was dropped, so close() can report forgotten work after cleaning up.
+ */
+export declare function discardAllPending(sdb: SimpleDB): {
+    table: SimpleTable;
+    methods: string[];
+}[];
+//# sourceMappingURL=queueOp.d.ts.map

package/esm/helpers/queueOp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queueOp.d.ts","sourceRoot":"","sources":["../../src/helpers/queueOp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAMtD;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,WAAW,EAAE,WAAW,EACxB,EAAE,EAAE,cAAc,GACjB,IAAI,CA8CN;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,QAAQ,GACZ;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,CAa7C"}

package/esm/helpers/queueOp.js

@@ -0,0 +1,70 @@
+import { ensureTableRegistered, getRegisteredTables } from "./tableRegistry.js";
+import { markTableChanged } from "./tableGeneration.js";
+import { recordCacheTableReferences } from "./cacheTableDependencies.js";
+import { captureAsyncOperation } from "./asyncOperationContext.js";
+/**
+ * Queues an internal relational operation, barrier, or asynchronous barrier.
+ *
+ * @internal
+ */
+export default function queueOp(simpleTable, op) {
+    const sdb = simpleTable.sdb;
+    if (sdb.lifecycleState !== "open") {
+        throw new Error(`${op.method} cannot queue work because its SimpleDB is ${sdb.lifecycleState}.`);
+    }
+    let capturedOp = {
+        ...op,
+        parameters: op.parameters === null ? null : structuredClone(op.parameters),
+    };
+    if (capturedOp.kind === "fusable" || capturedOp.kind === "source") {
+        capturedOp = {
+            ...capturedOp,
+            rawSQL: capturedOp.rawSQL === undefined
+                ? undefined
+                : [...capturedOp.rawSQL],
+        };
+        if (capturedOp.rawSQL !== undefined) {
+            recordCacheTableReferences(simpleTable, capturedOp.rawSQL);
+        }
+    }
+    if (capturedOp.kind === "fusable" &&
+        capturedOp.values !== undefined &&
+        typeof capturedOp.values !== "function") {
+        capturedOp = {
+            ...capturedOp,
+            values: [...capturedOp.values],
+        };
+    }
+    // A table de-registered by removeTable()/removeTables()/selectTables() that
+    // queues new work comes back under the flush's responsibility, like v1
+    // methods recreating a removed table.
+    ensureTableRegistered(sdb, simpleTable);
+    markTableChanged(simpleTable);
+    const queuedOp = {
+        ...capturedOp,
+        sequence: sdb.opSequence++,
+    };
+    if (captureAsyncOperation(sdb, { table: simpleTable, op: queuedOp })) {
+        return;
+    }
+    simpleTable.pendingOps.push(queuedOp);
+    sdb.pendingCount++;
+}
+/**
+ * Empties every table's pending queue without executing it and returns what
+ * was dropped, so close() can report forgotten work after cleaning up.
+ */
+export function discardAllPending(sdb) {
+    const discarded = [];
+    for (const table of getRegisteredTables(sdb)) {
+        if (table.pendingOps.length > 0) {
+            discarded.push({
+                table,
+                methods: table.pendingOps.map((op) => op.method),
+            });
+            sdb.pendingCount -= table.pendingOps.length;
+            table.pendingOps.length = 0;
+        }
+    }
+    return discarded;
+}

package/esm/helpers/quoteIdentifier.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Quotes one SQL identifier and escapes embedded double quotes.
+ * Use this for library-generated table, column, schema, database, and alias
+ * names. User-authored SQL expressions must remain unmodified.
+ *
+ * @param identifier - The identifier to quote.
+ * @returns The identifier wrapped in double quotes with embedded quotes doubled.
+ *
+ * @example
+ * ```ts
+ * quoteIdentifier('people "archive"');
+ * // '"people ""archive"""'
+ * ```
+ */
+export default function quoteIdentifier(identifier: string): string;
+//# sourceMappingURL=quoteIdentifier.d.ts.map

package/esm/helpers/quoteIdentifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quoteIdentifier.d.ts","sourceRoot":"","sources":["../../src/helpers/quoteIdentifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAElE"}