@nshiab/simple-data-analysis-core 2.0.9 → 2.1.1

package/script/helpers/printTable.d.ts

@@ -4,19 +4,6 @@
  * handles multi-line content, making it ideal for displaying data with long
  * column names and text values.
  *
- * @param data - An array of objects representing the rows of the table. Each
- *   object should have string keys.
- * @param options - Optional configuration for table rendering.
- * @param options.maxColumnWidth - The maximum width for any column (default:
- *   `75`). Headers and values exceeding this width will be wrapped at word
- *   boundaries.
- * @param options.minColumnWidth - The minimum width for any column (default:
- *   `3`).
- * @param options.typesRowIndex - The index of a row that contains type
- *   annotations (e.g. `"VARCHAR/string"`). This row will be rendered in grey.
- *   If omitted, no row is treated as a types row.
- * @returns void - The table is printed directly to the console.
- *
  * @example
  * ```typescript
  * const data = [
@@ -37,6 +24,24 @@
  * ];
  * printTable([types, ...data], { typesRowIndex: 0 });
  * ```
+ *
+ * @param data - An array of objects representing the rows of the table. Each
+ *   object should have string keys.
+ *
+ * @param options - Optional configuration for table rendering.
+ *
+ * @param options.maxColumnWidth - The maximum width for any column (default:
+ *   `75`). Headers and values exceeding this width will be wrapped at word
+ *   boundaries.
+ *
+ * @param options.minColumnWidth - The minimum width for any column (default:
+ *   `3`).
+ *
+ * @param options.typesRowIndex - The index of a row that contains type
+ *   annotations (e.g. `"VARCHAR/string"`). This row will be rendered in grey.
+ *   If omitted, no row is treated as a types row.
+ *
+ * @returns void - The table is printed directly to the console.
  */
 export default function printTable(data: {
     [key: string]: unknown;

package/script/helpers/printTable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"printTable.d.ts","sourceRoot":"","sources":["../../src/helpers/printTable.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAChC,IAAI,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,EAClC,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACA,IAAI,CAgNN"}
+{"version":3,"file":"printTable.d.ts","sourceRoot":"","sources":["../../src/helpers/printTable.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAChC,IAAI,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,EAClC,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACA,IAAI,CAgNN"}

package/script/helpers/printTable.js

@@ -12,19 +12,6 @@ const wrapString_js_1 = __importDefault(require("./wrapString.js"));
  * handles multi-line content, making it ideal for displaying data with long
  * column names and text values.
  *
- * @param data - An array of objects representing the rows of the table. Each
- *   object should have string keys.
- * @param options - Optional configuration for table rendering.
- * @param options.maxColumnWidth - The maximum width for any column (default:
- *   `75`). Headers and values exceeding this width will be wrapped at word
- *   boundaries.
- * @param options.minColumnWidth - The minimum width for any column (default:
- *   `3`).
- * @param options.typesRowIndex - The index of a row that contains type
- *   annotations (e.g. `"VARCHAR/string"`). This row will be rendered in grey.
- *   If omitted, no row is treated as a types row.
- * @returns void - The table is printed directly to the console.
- *
  * @example
  * ```typescript
  * const data = [
@@ -45,6 +32,24 @@ const wrapString_js_1 = __importDefault(require("./wrapString.js"));
  * ];
  * printTable([types, ...data], { typesRowIndex: 0 });
  * ```
+ *
+ * @param data - An array of objects representing the rows of the table. Each
+ *   object should have string keys.
+ *
+ * @param options - Optional configuration for table rendering.
+ *
+ * @param options.maxColumnWidth - The maximum width for any column (default:
+ *   `75`). Headers and values exceeding this width will be wrapped at word
+ *   boundaries.
+ *
+ * @param options.minColumnWidth - The minimum width for any column (default:
+ *   `3`).
+ *
+ * @param options.typesRowIndex - The index of a row that contains type
+ *   annotations (e.g. `"VARCHAR/string"`). This row will be rendered in grey.
+ *   If omitted, no row is treated as a types row.
+ *
+ * @returns void - The table is printed directly to the console.
  */
 function printTable(data, options) {
     if (!data || data.length === 0) {

package/script/helpers/publishPreparedColumns.d.ts

@@ -0,0 +1,37 @@
+import type SimpleTable from "../class/SimpleTable.js";
+import type { PreparedNumericFeatures } from "./prepareNumericFeatures.js";
+type PublicationOutput = {
+    /** Raw output-column name. */
+    name: string;
+    /** Trusted internal SQL evaluated with the prepared relation aliased as p. */
+    expression: string;
+    /** Raw source-column name to replace in its original position. */
+    replace?: string;
+};
+type PublicationResult = {
+    /** Raw relation name joined to the prepared rows. */
+    relation: string;
+    /** Raw row-identity column in the result relation. */
+    rowIdColumn: string;
+};
+/**
+ * Atomically publishes validated algorithm outputs from a prepared numeric
+ * feature snapshot. New outputs are appended, while replacements retain the
+ * source column's position. Existing native DuckDB indexes are recreated in
+ * the same transaction because CREATE OR REPLACE drops them.
+ *
+ * Output expressions are trusted internal SQL. They may reference `p`, the
+ * prepared relation alias, and `r` when a result relation is supplied. The
+ * consumer must fully compute and validate one result row per prepared row
+ * before calling this helper, and remains responsible for scratch cleanup.
+ */
+export default function publishPreparedColumns(table: SimpleTable, prepared: Pick<PreparedNumericFeatures, "relation" | "rowIdColumn" | "sourceColumns" | "sourceTemporary">, options: {
+    method: string;
+    parameters: {
+        [key: string]: unknown;
+    } | null;
+    outputs: PublicationOutput[];
+    result?: PublicationResult;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=publishPreparedColumns.d.ts.map

package/script/helpers/publishPreparedColumns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishPreparedColumns.d.ts","sourceRoot":"","sources":["../../src/helpers/publishPreparedColumns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAM3E,KAAK,iBAAiB,GAAG;IACvB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAA8B,sBAAsB,CAClD,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,IAAI,CACZ,uBAAuB,EACrB,UAAU,GACV,aAAa,GACb,eAAe,GACf,iBAAiB,CACpB,EACD,OAAO,EAAE;IACP,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B,GACA,OAAO,CAAC,IAAI,CAAC,CAwFf"}

package/script/helpers/publishPreparedColumns.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = publishPreparedColumns;
+const foldIdentifier_js_1 = __importDefault(require("./foldIdentifier.js"));
+const mergeOptions_js_1 = __importDefault(require("./mergeOptions.js"));
+const queryDB_js_1 = __importDefault(require("./queryDB.js"));
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+/**
+ * Atomically publishes validated algorithm outputs from a prepared numeric
+ * feature snapshot. New outputs are appended, while replacements retain the
+ * source column's position. Existing native DuckDB indexes are recreated in
+ * the same transaction because CREATE OR REPLACE drops them.
+ *
+ * Output expressions are trusted internal SQL. They may reference `p`, the
+ * prepared relation alias, and `r` when a result relation is supplied. The
+ * consumer must fully compute and validate one result row per prepared row
+ * before calling this helper, and remains responsible for scratch cleanup.
+ */
+async function publishPreparedColumns(table, prepared, options) {
+    validateOutputs(prepared.sourceColumns, options.outputs);
+    const connection = table.connection;
+    const q = quoteIdentifier_js_1.default;
+    const source = q(table.name);
+    const tableDetails = (await connection.runAndReadAll(`SELECT table_oid FROM duckdb_tables()
+     WHERE translate(table_name, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') = $1
+       AND schema_name = current_schema()
+       AND database_name IN (current_database(), 'temp')
+       AND temporary = $2
+     LIMIT 1`, [(0, foldIdentifier_js_1.default)(table.name), prepared.sourceTemporary])).getRowsJS()[0];
+    if (tableDetails === undefined) {
+        throw new Error(`${options.method} requires a materialized source table.`);
+    }
+    const tableOid = tableDetails[0];
+    if (typeof tableOid !== "number" && typeof tableOid !== "bigint") {
+        throw new Error(`${options.method} could not identify the source table.`);
+    }
+    const indexes = (await connection.runAndReadAll("SELECT sql FROM duckdb_indexes() WHERE table_oid = $1 ORDER BY index_name", [tableOid])).getRowsJS().map((row) => String(row[0]));
+    const replacements = new Map(options.outputs.filter((output) => output.replace !== undefined).map((output) => [(0, foldIdentifier_js_1.default)(output.replace), output]));
+    const select = prepared.sourceColumns.map((column) => {
+        const replacement = replacements.get((0, foldIdentifier_js_1.default)(column));
+        return replacement === undefined
+            ? `p.${q(column)}`
+            : `${replacement.expression} AS ${q(column)}`;
+    });
+    for (const output of options.outputs) {
+        if (output.replace === undefined) {
+            select.push(`${output.expression} AS ${q(output.name)}`);
+        }
+    }
+    const resultJoin = options.result === undefined
+        ? ""
+        : ` JOIN ${q(options.result.relation)} r
+      ON p.${q(prepared.rowIdColumn)} = r.${q(options.result.rowIdColumn)}`;
+    await connection.run("BEGIN TRANSACTION");
+    try {
+        await (0, queryDB_js_1.default)(table, `CREATE OR REPLACE ${prepared.sourceTemporary ? "TEMP " : ""}TABLE ${source} AS
+       SELECT ${select.join(", ")}
+       FROM ${q(prepared.relation)} p${resultJoin}
+       ORDER BY p.${q(prepared.rowIdColumn)}`, (0, mergeOptions_js_1.default)(table, {
+            table: table.name,
+            method: options.method,
+            parameters: options.parameters,
+            noClean: true,
+        }));
+        for (const sql of indexes) {
+            try {
+                await connection.run(sql);
+            }
+            catch (error) {
+                const detail = error instanceof Error ? ` ${error.message}` : "";
+                throw new Error(`${options.method} could not restore an existing DuckDB index while publishing its output. Remove or rebuild indexes that do not support the output column types.${detail}`, { cause: error });
+            }
+        }
+        await connection.run("COMMIT");
+    }
+    catch (error) {
+        try {
+            await connection.run("ROLLBACK");
+        }
+        catch {
+            // DuckDB may already abort the transaction after an index-build error.
+            // Preserve the publication error that explains why the operation failed.
+        }
+        // UNIQUE violations can be deferred until COMMIT, which may also fail for
+        // unrelated reasons. Preserve that diagnostic instead of blaming indexes.
+        throw error;
+    }
+}
+function validateOutputs(sourceColumns, outputs) {
+    const outputNames = new Set();
+    const replacements = new Set();
+    for (const output of outputs) {
+        const outputName = (0, foldIdentifier_js_1.default)(output.name);
+        if (outputNames.has(outputName)) {
+            throw new Error(`Internal publication received duplicate output column ${(0, quoteIdentifier_js_1.default)(output.name)}.`);
+        }
+        outputNames.add(outputName);
+        if (output.replace === undefined) {
+            if (sourceColumns.some((column) => (0, foldIdentifier_js_1.default)(column) === outputName)) {
+                throw new Error(`Internal publication cannot append existing column ${(0, quoteIdentifier_js_1.default)(output.name)}.`);
+            }
+            continue;
+        }
+        const replacement = (0, foldIdentifier_js_1.default)(output.replace);
+        if (outputName !== replacement) {
+            throw new Error(`Internal publication output ${(0, quoteIdentifier_js_1.default)(output.name)} must match its replacement column ${(0, quoteIdentifier_js_1.default)(output.replace)}.`);
+        }
+        if (!sourceColumns.some((column) => (0, foldIdentifier_js_1.default)(column) === replacement)) {
+            throw new Error(`Internal publication cannot replace missing column ${(0, quoteIdentifier_js_1.default)(output.replace)}.`);
+        }
+        if (replacements.has(replacement)) {
+            throw new Error(`Internal publication received duplicate replacement column ${(0, quoteIdentifier_js_1.default)(output.replace)}.`);
+        }
+        replacements.add(replacement);
+    }
+}

package/script/helpers/queryDB.d.ts

@@ -8,19 +8,6 @@ type DuckDBValue = NativeDuckDBValue;
  * 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";
@@ -35,6 +22,30 @@ type DuckDBValue = NativeDuckDBValue;
  * }));
  * await table.log();
  * ```
+ *
+ * @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`.
  */
 export default function queryDB(simple: SimpleTable | SimpleDB, query: string, options: {
     table: string | null;

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

@@ -1 +1 @@
-{"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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;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/script/helpers/queryDB.js

@@ -14,19 +14,6 @@ const cacheTableDependencies_js_1 = require("./cacheTableDependencies.js");
  * 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";
@@ -41,6 +28,30 @@ const cacheTableDependencies_js_1 = require("./cacheTableDependencies.js");
  * }));
  * await table.log();
  * ```
+ *
+ * @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`.
  */
 async function queryDB(simple, query, options) {
     if (simple instanceof SimpleTable_js_1.default) {

package/script/helpers/queueAsyncBarrier.d.ts

@@ -15,13 +15,6 @@ import type SimpleTable from "../class/SimpleTable.js";
  * the failing table's remaining chain is aborted, but unexecuted work for other
  * tables is requeued for their next observation.
  *
- * @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";
@@ -40,6 +33,18 @@ import type SimpleTable from "../class/SimpleTable.js";
  *   return table;
  * }
  * ```
+ *
+ * @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.
  */
 export default function queueAsyncBarrier(simpleTable: SimpleTable, operation: {
     method: string;

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

@@ -1 +1 @@
-{"version":3,"file":"queueAsyncBarrier.d.ts","sourceRoot":"","sources":["../../src/helpers/queueAsyncBarrier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;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"}
+{"version":3,"file":"queueAsyncBarrier.d.ts","sourceRoot":"","sources":["../../src/helpers/queueAsyncBarrier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;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/script/helpers/queueAsyncBarrier.js

@@ -21,13 +21,6 @@ const queueOp_js_1 = __importDefault(require("./queueOp.js"));
  * the failing table's remaining chain is aborted, but unexecuted work for other
  * tables is requeued for their next observation.
  *
- * @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";
@@ -46,6 +39,18 @@ const queueOp_js_1 = __importDefault(require("./queueOp.js"));
  *   return table;
  * }
  * ```
+ *
+ * @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.
  */
 function queueAsyncBarrier(simpleTable, operation) {
     (0, queueOp_js_1.default)(simpleTable, {

package/script/helpers/queueGraphResult.d.ts

@@ -0,0 +1,18 @@
+import type { DuckDBValue } from "@duckdb/node-api";
+import type SimpleTable from "../class/SimpleTable.js";
+import type { TableSchema } from "./pendingOps.js";
+type GraphResult = {
+    buildSelect: (input: string, schema: TableSchema) => string;
+    method: string;
+    outputSchema: (schema: TableSchema) => TableSchema;
+    outputTable?: string | boolean;
+    parameters: {
+        [key: string]: unknown;
+    };
+    preflight?: (input: SimpleTable) => Promise<void>;
+    values: (schema: TableSchema) => DuckDBValue[];
+};
+/** Queues a graph SELECT for overwrite or a source-preserving output table. */
+export default function queueGraphResult(simpleTable: SimpleTable, result: GraphResult): SimpleTable;
+export {};
+//# sourceMappingURL=queueGraphResult.d.ts.map

package/script/helpers/queueGraphResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queueGraphResult.d.ts","sourceRoot":"","sources":["../../src/helpers/queueGraphResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,KAAK,WAAW,GAAG;IACjB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,MAAM,CAAC;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,WAAW,CAAC;IACnD,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACvC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,WAAW,EAAE,CAAC;CAChD,CAAC;AAEF,+EAA+E;AAC/E,MAAM,CAAC,OAAO,UAAU,gBAAgB,CACtC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,WAAW,GAClB,WAAW,CAqCb"}

package/script/helpers/queueGraphResult.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = queueGraphResult;
+const queueOp_js_1 = __importDefault(require("./queueOp.js"));
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+const resolveOutputTable_js_1 = __importDefault(require("./resolveOutputTable.js"));
+/** Queues a graph SELECT for overwrite or a source-preserving output table. */
+function queueGraphResult(simpleTable, result) {
+    const resolvedOutput = (0, resolveOutputTable_js_1.default)(simpleTable, result.outputTable);
+    const outputTable = typeof resolvedOutput === "string"
+        ? simpleTable.sdb.newTable(resolvedOutput)
+        : simpleTable;
+    if (outputTable !== simpleTable) {
+        (0, queueOp_js_1.default)(outputTable, {
+            kind: "source",
+            method: result.method,
+            parameters: result.parameters,
+            rawSQL: [(0, quoteIdentifier_js_1.default)(simpleTable.name)],
+            buildSelect: () => `SELECT * FROM ${(0, quoteIdentifier_js_1.default)(simpleTable.name)}`,
+        });
+    }
+    // A separate barrier keeps invalid-event checks observable after LIMIT 0.
+    const preflight = result.preflight;
+    if (preflight !== undefined) {
+        (0, queueOp_js_1.default)(outputTable, {
+            kind: "barrier",
+            method: result.method,
+            parameters: result.parameters,
+            execute: () => preflight(outputTable),
+        });
+    }
+    (0, queueOp_js_1.default)(outputTable, {
+        kind: "fusable",
+        method: result.method,
+        parameters: result.parameters,
+        needsSchema: true,
+        values: result.values,
+        buildSelect: result.buildSelect,
+        outputSchema: result.outputSchema,
+    });
+    return outputTable;
+}

package/script/helpers/quoteIdentifier.d.ts

@@ -3,14 +3,15 @@
  * 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"""'
  * ```
+ *
+ * @param identifier - The identifier to quote.
+ *
+ * @returns The identifier wrapped in double quotes with embedded quotes doubled.
  */
 export default function quoteIdentifier(identifier: string): string;
 //# sourceMappingURL=quoteIdentifier.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"quoteIdentifier.d.ts","sourceRoot":"","sources":["../../src/helpers/quoteIdentifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAElE"}

package/script/helpers/quoteIdentifier.js

@@ -6,14 +6,15 @@ exports.default = quoteIdentifier;
  * 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"""'
  * ```
+ *
+ * @param identifier - The identifier to quote.
+ *
+ * @returns The identifier wrapped in double quotes with embedded quotes doubled.
  */
 function quoteIdentifier(identifier) {
     return `"${identifier.replaceAll('"', '""')}"`;

package/script/helpers/quoteQualifiedIdentifier.d.ts

@@ -4,15 +4,17 @@
  * Qualifying column references prevents DuckDB from resolving a relation name
  * as its row struct when a missing column has the same name as the relation.
  *
- * @param relation - The table or relation containing the identifier.
- * @param identifier - The identifier to qualify.
- * @returns The separately quoted relation and identifier joined by a period.
- *
  * @example
  * ```ts
  * quoteQualifiedIdentifier("people", "full name");
  * // '"people"."full name"'
  * ```
+ *
+ * @param relation - The table or relation containing the identifier.
+ *
+ * @param identifier - The identifier to qualify.
+ *
+ * @returns The separately quoted relation and identifier joined by a period.
  */
 export default function quoteQualifiedIdentifier(relation: string, identifier: string): string;
 //# sourceMappingURL=quoteQualifiedIdentifier.d.ts.map

package/script/helpers/quoteQualifiedIdentifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quoteQualifiedIdentifier.d.ts","sourceRoot":"","sources":["../../src/helpers/quoteQualifiedIdentifier.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAC9C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER"}
+{"version":3,"file":"quoteQualifiedIdentifier.d.ts","sourceRoot":"","sources":["../../src/helpers/quoteQualifiedIdentifier.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAC9C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER"}

package/script/helpers/quoteQualifiedIdentifier.js

@@ -11,15 +11,17 @@ const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
  * Qualifying column references prevents DuckDB from resolving a relation name
  * as its row struct when a missing column has the same name as the relation.
  *
- * @param relation - The table or relation containing the identifier.
- * @param identifier - The identifier to qualify.
- * @returns The separately quoted relation and identifier joined by a period.
- *
  * @example
  * ```ts
  * quoteQualifiedIdentifier("people", "full name");
  * // '"people"."full name"'
  * ```
+ *
+ * @param relation - The table or relation containing the identifier.
+ *
+ * @param identifier - The identifier to qualify.
+ *
+ * @returns The separately quoted relation and identifier joined by a period.
  */
 function quoteQualifiedIdentifier(relation, identifier) {
     return `${(0, quoteIdentifier_js_1.default)(relation)}.${(0, quoteIdentifier_js_1.default)(identifier)}`;

package/script/helpers/runQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runQuery.d.ts","sourceRoot":"","sources":["../../src/helpers/runQuery.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,gBAAgB,EAIrB,KAAK,UAAU,EAEf,KAAK,WAAW,EAIjB,MAAM,kBAAkB,CAAC;AAI1B,KAAK,eAAe,GAAG;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AA8CF,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAM,GAAG,IAAW,GAC9B,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAoCjC;AAED,wBAA8B,QAAQ,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CACN;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,EAAE,GACD,IAAI,CACP,CAoEA"}
+{"version":3,"file":"runQuery.d.ts","sourceRoot":"","sources":["../../src/helpers/runQuery.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,gBAAgB,EAIrB,KAAK,UAAU,EAEf,KAAK,WAAW,EAIjB,MAAM,kBAAkB,CAAC;AAI1B,KAAK,eAAe,GAAG;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AA8CF,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAM,GAAG,IAAW,GAC9B,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAoCjC;AAED,wBAA8B,QAAQ,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CACN;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,EAAE,GACD,IAAI,CACP,CAiFA"}

package/script/helpers/runQuery.js

@@ -106,9 +106,23 @@ async function runQuery(query, connection, returnData, options) {
                 for (let j = 0; j < columnCount; j++) {
                     const columnName = columnNames[j];
                     const converter = converters[j];
-                    chunk.visitColumnValues(j, (value, rowIndex) => {
-                        rows[base + rowIndex][columnName] = converter(value);
-                    });
+                    if (columnName === "__proto__") {
+                        // This valid SQL identifier must define data, not invoke Node's
+                        // legacy Object.prototype setter. Keep ordinary columns fast.
+                        chunk.visitColumnValues(j, (value, rowIndex) => {
+                            Object.defineProperty(rows[base + rowIndex], columnName, {
+                                value: converter(value),
+                                enumerable: true,
+                                configurable: true,
+                                writable: true,
+                            });
+                        });
+                    }
+                    else {
+                        chunk.visitColumnValues(j, (value, rowIndex) => {
+                            rows[base + rowIndex][columnName] = converter(value);
+                        });
+                    }
                 }
             }
             return rows;

package/script/helpers/selectFuzzyReplacements.d.ts

@@ -0,0 +1,11 @@
+export type FuzzyPair = {
+    left_value: string;
+    right_value: string;
+    left_cnt: number;
+    right_cnt: number;
+    score: number;
+};
+export type FuzzyStrategy = "mostCommon" | "longestString" | "shortestString" | "mostCentral" | "maxScore";
+/** Groups matching values transitively and chooses each component's canonical value. */
+export default function selectFuzzyReplacements(pairs: FuzzyPair[], strategy: FuzzyStrategy): Map<string, string>;
+//# sourceMappingURL=selectFuzzyReplacements.d.ts.map