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

package/script/helpers/prepareUmapLayoutOptions.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = prepareUmapLayoutOptions;
+const fitUmapCurve_js_1 = __importDefault(require("./fitUmapCurve.js"));
+// Resolve and validate settings before database work, fitting the curve once.
+function prepareUmapLayoutOptions(options = {}) {
+    const { epochs = 200, seed = 42, minDistance = 0.1, learningRate = 1, negativeSamples = 5, } = options;
+    for (const [key, value] of Object.entries({ epochs, negativeSamples })) {
+        if (!Number.isSafeInteger(value) || value < 1) {
+            throw new Error(`${key} must be a positive safe integer.`);
+        }
+    }
+    if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff) {
+        throw new Error("seed must be an integer between 0 and 4294967295.");
+    }
+    if (!Number.isFinite(learningRate) || learningRate <= 0) {
+        throw new Error("learningRate must be finite and positive.");
+    }
+    return {
+        epochs,
+        seed,
+        learningRate,
+        negativeSamples,
+        curve: (0, fitUmapCurve_js_1.default)(minDistance),
+    };
+}

package/script/helpers/prettyDuration.d.ts

@@ -3,14 +3,6 @@
  *
  * The function can calculate the duration from a given start time to the current time, or between a specified start and end time. It provides options for logging the output directly to the console and adding custom prefixes or suffixes to the formatted string. Note that for simplicity, months are approximated as 30 days and years as 365 days.
  *
- * @param start - The starting point of the duration. This can be a `Date` object or a Unix timestamp (number of milliseconds since epoch).
- * @param options - Optional settings to customize the duration formatting and output.
- *   @param options.log - If `true`, the formatted duration string will be logged to the console. Defaults to `false`.
- *   @param options.end - The ending point of the duration. This can be a `Date` object or a Unix timestamp. If omitted, the current time (`Date.now()`) will be used as the end point.
- *   @param options.prefix - A string to prepend to the formatted duration string (e.g., "Elapsed time: ").
- *   @param options.suffix - A string to append to the formatted duration string (e.g., " (Task completed)").
- * @returns A human-readable string representing the duration.
- *
  * @example
  * ```ts
  * // A starting Date somewhere in your code.
@@ -20,6 +12,7 @@
  * const duration = prettyDuration(startDate);
  * console.log(duration); // Returns something like "22 days, 6 h, 3 min, 15 sec, 3 ms"
  * ```
+ *
  * @example
  * ```ts
  * // If you want to console.log it directly, set the `log` option to `true`.
@@ -28,6 +21,7 @@
  * // ... some operations ...
  * prettyDuration(startDateForLog, { log: true });
  * ```
+ *
  * @example
  * ```ts
  * // You can also use a prefix and/or suffix for the output string.
@@ -36,6 +30,7 @@
  * prettyDuration(startDateWithPrefixSuffix, { log: true, prefix: "Elapsed time: ", suffix: " (Main function)" });
  * // Returns and logs something like "Total duration: 3 min, 15 sec, 3 ms (Main function)"
  * ```
+ *
  * @example
  * ```ts
  * // If you want to format the duration between two specific dates, use the `end` option.
@@ -44,6 +39,17 @@
  * const specificDuration = prettyDuration(start, { end });
  * console.log(specificDuration); // Returns "22 days, 6 h, 3 min, 15 sec, 0 ms"
  * ```
+ *
+ * @param start - The starting point of the duration. This can be a `Date` object or a Unix timestamp (number of milliseconds since epoch).
+ *
+ * @param options - Optional settings to customize the duration formatting and output.
+ *   @param options.log - If `true`, the formatted duration string will be logged to the console. Defaults to `false`.
+ *   @param options.end - The ending point of the duration. This can be a `Date` object or a Unix timestamp. If omitted, the current time (`Date.now()`) will be used as the end point.
+ *   @param options.prefix - A string to prepend to the formatted duration string (e.g., "Elapsed time: ").
+ *   @param options.suffix - A string to append to the formatted duration string (e.g., " (Task completed)").
+ *
+ * @returns A human-readable string representing the duration.
+ *
  * @category Formatting
  */
 export default function prettyDuration(start: Date | number, options?: {

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

@@ -1 +1 @@
-{"version":3,"file":"prettyDuration.d.ts","sourceRoot":"","sources":["../../src/helpers/prettyDuration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,KAAK,EAAE,IAAI,GAAG,MAAM,EACpB,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,GACL,MAAM,CAuGR"}
+{"version":3,"file":"prettyDuration.d.ts","sourceRoot":"","sources":["../../src/helpers/prettyDuration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,KAAK,EAAE,IAAI,GAAG,MAAM,EACpB,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,GACL,MAAM,CAuGR"}

package/script/helpers/prettyDuration.js

@@ -6,14 +6,6 @@ exports.default = prettyDuration;
  *
  * The function can calculate the duration from a given start time to the current time, or between a specified start and end time. It provides options for logging the output directly to the console and adding custom prefixes or suffixes to the formatted string. Note that for simplicity, months are approximated as 30 days and years as 365 days.
  *
- * @param start - The starting point of the duration. This can be a `Date` object or a Unix timestamp (number of milliseconds since epoch).
- * @param options - Optional settings to customize the duration formatting and output.
- *   @param options.log - If `true`, the formatted duration string will be logged to the console. Defaults to `false`.
- *   @param options.end - The ending point of the duration. This can be a `Date` object or a Unix timestamp. If omitted, the current time (`Date.now()`) will be used as the end point.
- *   @param options.prefix - A string to prepend to the formatted duration string (e.g., "Elapsed time: ").
- *   @param options.suffix - A string to append to the formatted duration string (e.g., " (Task completed)").
- * @returns A human-readable string representing the duration.
- *
  * @example
  * ```ts
  * // A starting Date somewhere in your code.
@@ -23,6 +15,7 @@ exports.default = prettyDuration;
  * const duration = prettyDuration(startDate);
  * console.log(duration); // Returns something like "22 days, 6 h, 3 min, 15 sec, 3 ms"
  * ```
+ *
  * @example
  * ```ts
  * // If you want to console.log it directly, set the `log` option to `true`.
@@ -31,6 +24,7 @@ exports.default = prettyDuration;
  * // ... some operations ...
  * prettyDuration(startDateForLog, { log: true });
  * ```
+ *
  * @example
  * ```ts
  * // You can also use a prefix and/or suffix for the output string.
@@ -39,6 +33,7 @@ exports.default = prettyDuration;
  * prettyDuration(startDateWithPrefixSuffix, { log: true, prefix: "Elapsed time: ", suffix: " (Main function)" });
  * // Returns and logs something like "Total duration: 3 min, 15 sec, 3 ms (Main function)"
  * ```
+ *
  * @example
  * ```ts
  * // If you want to format the duration between two specific dates, use the `end` option.
@@ -47,6 +42,17 @@ exports.default = prettyDuration;
  * const specificDuration = prettyDuration(start, { end });
  * console.log(specificDuration); // Returns "22 days, 6 h, 3 min, 15 sec, 0 ms"
  * ```
+ *
+ * @param start - The starting point of the duration. This can be a `Date` object or a Unix timestamp (number of milliseconds since epoch).
+ *
+ * @param options - Optional settings to customize the duration formatting and output.
+ *   @param options.log - If `true`, the formatted duration string will be logged to the console. Defaults to `false`.
+ *   @param options.end - The ending point of the duration. This can be a `Date` object or a Unix timestamp. If omitted, the current time (`Date.now()`) will be used as the end point.
+ *   @param options.prefix - A string to prepend to the formatted duration string (e.g., "Elapsed time: ").
+ *   @param options.suffix - A string to append to the formatted duration string (e.g., " (Task completed)").
+ *
+ * @returns A human-readable string representing the duration.
+ *
  * @category Formatting
  */
 function prettyDuration(start, options = {}) {

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;
+}