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

package/esm/helpers/publishPreparedColumns.js

@@ -0,0 +1,113 @@
+import foldIdentifier from "./foldIdentifier.js";
+import mergeOptions from "./mergeOptions.js";
+import queryDB from "./queryDB.js";
+import quoteIdentifier from "./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.
+ */
+export default async function publishPreparedColumns(table, prepared, options) {
+    validateOutputs(prepared.sourceColumns, options.outputs);
+    const connection = table.connection;
+    const q = quoteIdentifier;
+    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`, [foldIdentifier(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) => [foldIdentifier(output.replace), output]));
+    const select = prepared.sourceColumns.map((column) => {
+        const replacement = replacements.get(foldIdentifier(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 queryDB(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)}`, mergeOptions(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 = foldIdentifier(output.name);
+        if (outputNames.has(outputName)) {
+            throw new Error(`Internal publication received duplicate output column ${quoteIdentifier(output.name)}.`);
+        }
+        outputNames.add(outputName);
+        if (output.replace === undefined) {
+            if (sourceColumns.some((column) => foldIdentifier(column) === outputName)) {
+                throw new Error(`Internal publication cannot append existing column ${quoteIdentifier(output.name)}.`);
+            }
+            continue;
+        }
+        const replacement = foldIdentifier(output.replace);
+        if (outputName !== replacement) {
+            throw new Error(`Internal publication output ${quoteIdentifier(output.name)} must match its replacement column ${quoteIdentifier(output.replace)}.`);
+        }
+        if (!sourceColumns.some((column) => foldIdentifier(column) === replacement)) {
+            throw new Error(`Internal publication cannot replace missing column ${quoteIdentifier(output.replace)}.`);
+        }
+        if (replacements.has(replacement)) {
+            throw new Error(`Internal publication received duplicate replacement column ${quoteIdentifier(output.replace)}.`);
+        }
+        replacements.add(replacement);
+    }
+}

package/esm/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/esm/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/esm/helpers/queryDB.js

@@ -8,19 +8,6 @@ import { recordCacheTableAccess } from "./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";
@@ -35,6 +22,30 @@ import { recordCacheTableAccess } from "./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`.
  */
 export default async function queryDB(simple, query, options) {
     if (simple instanceof SimpleTable) {

package/esm/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/esm/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/esm/helpers/queueAsyncBarrier.js

@@ -15,13 +15,6 @@ import queueOp from "./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";
@@ -40,6 +33,18 @@ import queueOp from "./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.
  */
 export default function queueAsyncBarrier(simpleTable, operation) {
     queueOp(simpleTable, {

package/esm/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/esm/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/esm/helpers/queueGraphResult.js

@@ -0,0 +1,39 @@
+import queueOp from "./queueOp.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+import resolveOutputTable from "./resolveOutputTable.js";
+/** Queues a graph SELECT for overwrite or a source-preserving output table. */
+export default function queueGraphResult(simpleTable, result) {
+    const resolvedOutput = resolveOutputTable(simpleTable, result.outputTable);
+    const outputTable = typeof resolvedOutput === "string"
+        ? simpleTable.sdb.newTable(resolvedOutput)
+        : simpleTable;
+    if (outputTable !== simpleTable) {
+        queueOp(outputTable, {
+            kind: "source",
+            method: result.method,
+            parameters: result.parameters,
+            rawSQL: [quoteIdentifier(simpleTable.name)],
+            buildSelect: () => `SELECT * FROM ${quoteIdentifier(simpleTable.name)}`,
+        });
+    }
+    // A separate barrier keeps invalid-event checks observable after LIMIT 0.
+    const preflight = result.preflight;
+    if (preflight !== undefined) {
+        queueOp(outputTable, {
+            kind: "barrier",
+            method: result.method,
+            parameters: result.parameters,
+            execute: () => preflight(outputTable),
+        });
+    }
+    queueOp(outputTable, {
+        kind: "fusable",
+        method: result.method,
+        parameters: result.parameters,
+        needsSchema: true,
+        values: result.values,
+        buildSelect: result.buildSelect,
+        outputSchema: result.outputSchema,
+    });
+    return outputTable;
+}

package/esm/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/esm/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/esm/helpers/quoteIdentifier.js

@@ -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) {
     return `"${identifier.replaceAll('"', '""')}"`;

package/esm/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/esm/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/esm/helpers/quoteQualifiedIdentifier.js

@@ -5,15 +5,17 @@ import quoteIdentifier from "./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.
  */
 export default function quoteQualifiedIdentifier(relation, identifier) {
     return `${quoteIdentifier(relation)}.${quoteIdentifier(identifier)}`;

package/esm/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/esm/helpers/runQuery.js

@@ -99,9 +99,23 @@ export default 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/esm/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

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

@@ -0,0 +1 @@
+{"version":3,"file":"selectFuzzyReplacements.d.ts","sourceRoot":"","sources":["../../src/helpers/selectFuzzyReplacements.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,eAAe,GACf,gBAAgB,GAChB,aAAa,GACb,UAAU,CAAC;AAEf,wFAAwF;AACxF,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,EAAE,aAAa,GACtB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA8HrB"}

package/esm/helpers/selectFuzzyReplacements.js

@@ -0,0 +1,124 @@
+/** Groups matching values transitively and chooses each component's canonical value. */
+export default function selectFuzzyReplacements(pairs, strategy) {
+    // Build count map from the pairs — no separate query needed.
+    const countMap = new Map();
+    for (const { left_value, left_cnt, right_value, right_cnt } of pairs) {
+        countMap.set(left_value, Number(left_cnt));
+        countMap.set(right_value, Number(right_cnt));
+    }
+    // Union-Find — only over values that actually participate in a pair.
+    const parent = new Map();
+    const find = (x) => {
+        if (!parent.has(x))
+            parent.set(x, x);
+        if (parent.get(x) !== x)
+            parent.set(x, find(parent.get(x)));
+        return parent.get(x);
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent.set(ra, rb);
+    };
+    for (const v of countMap.keys())
+        find(v);
+    for (const { left_value, right_value } of pairs) {
+        union(left_value, right_value);
+    }
+    // Group values by their cluster root.
+    const clusters = new Map();
+    for (const v of countMap.keys()) {
+        const root = find(v);
+        if (!clusters.has(root))
+            clusters.set(root, []);
+        clusters.get(root).push(v);
+    }
+    // Pick the canonical value for each cluster.
+    const replacement = new Map();
+    // Every pair belongs to exactly one component. Accumulate scores globally,
+    // at most once, instead of scanning all pairs separately for each cluster.
+    // Keep this lazy: distinct counts/lengths can choose a winner without scores.
+    // Iterating in the original pair order also preserves floating-point ties.
+    let scoreSum = null;
+    const getScoreSum = () => {
+        if (scoreSum === null) {
+            scoreSum = new Map();
+            for (const { left_value, right_value, score } of pairs) {
+                scoreSum.set(left_value, (scoreSum.get(left_value) ?? 0) + score);
+                scoreSum.set(right_value, (scoreSum.get(right_value) ?? 0) + score);
+            }
+        }
+        return scoreSum;
+    };
+    let scoreMax = null;
+    const getScoreMax = () => {
+        if (scoreMax === null) {
+            scoreMax = new Map();
+            for (const { left_value, right_value, score } of pairs) {
+                scoreMax.set(left_value, Math.max(scoreMax.get(left_value) ?? 0, score));
+                scoreMax.set(right_value, Math.max(scoreMax.get(right_value) ?? 0, score));
+            }
+        }
+        return scoreMax;
+    };
+    for (const members of clusters.values()) {
+        if (members.length === 1)
+            continue;
+        // Sum-based comparator: highest total similarity, then alphabetical.
+        const byScore = (a, b) => {
+            const sum = getScoreSum();
+            const sa = sum.get(a) ?? 0;
+            const sb = sum.get(b) ?? 0;
+            if (sa !== sb)
+                return sa > sb ? a : b;
+            return a <= b ? a : b; // alphabetical tie-break
+        };
+        // Max-based comparator: highest single-pair score, then sum, then alphabetical.
+        const byMaxScore = (a, b) => {
+            const mx = getScoreMax();
+            const ma = mx.get(a) ?? 0;
+            const mb = mx.get(b) ?? 0;
+            if (ma !== mb)
+                return ma > mb ? a : b;
+            return byScore(a, b); // sum then alphabetical tie-break
+        };
+        let canonical;
+        if (strategy === "longestString") {
+            canonical = members.reduce((a, b) => {
+                if (a.length !== b.length)
+                    return a.length > b.length ? a : b;
+                return byScore(a, b);
+            });
+        }
+        else if (strategy === "shortestString") {
+            canonical = members.reduce((a, b) => {
+                if (a.length !== b.length)
+                    return a.length < b.length ? a : b;
+                return byScore(a, b);
+            });
+        }
+        else if (strategy === "mostCommon") {
+            canonical = members.reduce((a, b) => {
+                const ca = countMap.get(a) ?? 0;
+                const cb = countMap.get(b) ?? 0;
+                if (ca !== cb)
+                    return ca > cb ? a : b;
+                return byScore(a, b);
+            });
+        }
+        else if (strategy === "mostCentral") {
+            // Most central string — highest total similarity to all other cluster members.
+            canonical = members.reduce((a, b) => byScore(a, b));
+        }
+        else {
+            // "maxScore": the string participating in the single highest-scoring pair.
+            canonical = members.reduce((a, b) => byMaxScore(a, b));
+        }
+        for (const m of members) {
+            if (m !== canonical)
+                replacement.set(m, canonical);
+        }
+    }
+    return replacement;
+}

package/esm/helpers/stabilizeCosineVectors.d.ts

@@ -0,0 +1,14 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+/**
+ * Stabilizes cosine arithmetic in a caller-owned private vector relation.
+ * The already-quoted relation has unique vertex ids and a fixed-size DOUBLE
+ * vec column. Source data must be retained separately by the caller.
+ *
+ * Safe vectors keep their existing arithmetic and tie behavior. Outside the
+ * safe range, divide by the largest absolute component, then by the resulting
+ * length. This preserves direction without overflowing or underflowing norms.
+ * The bounds keep squared-norm products between 1e-300 and 1e300, with room
+ * for rounding. Only the private vec column changes; no scratch tables remain.
+ */
+export default function stabilizeCosineVectors(connection: DuckDBConnection, rows: string): Promise<void>;
+//# sourceMappingURL=stabilizeCosineVectors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stabilizeCosineVectors.d.ts","sourceRoot":"","sources":["../../src/helpers/stabilizeCosineVectors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD;;;;;;;;;;GAUG;AACH,wBAA8B,sBAAsB,CAClD,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CA4Bf"}