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

package/esm/helpers/prepareGraphTraversal.js

@@ -0,0 +1,79 @@
+import foldIdentifier from "./foldIdentifier.js";
+import getGraphEndpointColumns from "./getGraphEndpointColumns.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+/** Prepares exact-ID SQL shared by graph traversal methods. */
+export default function prepareGraphTraversal(input, schema, source, target, starts, method, argument = "start") {
+    const endpoints = validateGraphStarts(schema, source, target, starts, method, argument);
+    return {
+        ...prepareGraphSqlFromEndpoints(input, endpoints),
+        startValues: starts.values.map(() => `(TRY_CAST(? AS ${endpoints.idType}))`)
+            .join(", "),
+    };
+}
+/** Prepares exact-ID edge SQL for graph methods without starting nodes. */
+export function prepareGraphSql(input, schema, source, target, method) {
+    return prepareGraphSqlFromEndpoints(input, getGraphEndpointColumns(schema, source, target, method));
+}
+function prepareGraphSqlFromEndpoints(input, endpoints) {
+    const sourceColumn = quoteIdentifier(endpoints.source);
+    const targetColumn = quoteIdentifier(endpoints.target);
+    const idType = endpoints.idType;
+    const cast = (expression) => `CAST(${expression} AS ${idType})`;
+    const key = endpoints.family === "string"
+        ? (expression) => `ENCODE(${cast(expression)})`
+        : cast;
+    const edge = (from, to, selections) => `SELECT ${cast(from)} AS ${quoteIdentifier("__from")},
+        ${cast(to)} AS ${quoteIdentifier("__to")},
+        ${key(from)} AS ${quoteIdentifier("__from_key")},
+        ${key(to)} AS ${quoteIdentifier("__to_key")}${selections.length === 0
+        ? ""
+        : `,\n        ${selections.join(",\n        ")}`}
+      FROM ${input} AS ${quoteIdentifier("edges")}`;
+    const sourceReference = `${quoteIdentifier("edges")}.${sourceColumn}`;
+    const targetReference = `${quoteIdentifier("edges")}.${targetColumn}`;
+    return {
+        endpoints,
+        key,
+        edges: (direction, selections = []) => direction === "outgoing"
+            ? edge(sourceReference, targetReference, selections)
+            : direction === "incoming"
+                ? edge(targetReference, sourceReference, selections)
+                : `${edge(sourceReference, targetReference, selections)}\nUNION ALL\n${edge(targetReference, sourceReference, selections)}`,
+        relationNames: (names) => uniqueRelationNames(input, names),
+    };
+}
+/** Validates supplied starts against resolved endpoint ID types. */
+export function validateGraphStarts(schema, source, target, starts, method, argument = "start") {
+    const endpoints = getGraphEndpointColumns(schema, source, target, method);
+    const verb = argument === "start" ? "contains" : "contain";
+    if (endpoints.family !== starts.family) {
+        throw new TypeError(`${method} ${argument} ${verb} ${starts.family} IDs, but endpoint columns ${quoteIdentifier(endpoints.source)} and ${quoteIdentifier(endpoints.target)} contain ${endpoints.family} IDs.`);
+    }
+    if (endpoints.floating) {
+        for (const value of starts.numericValues) {
+            const converted = endpoints.idType === "FLOAT"
+                ? Math.fround(Number(value))
+                : Number(value);
+            if (!Number.isFinite(converted) || BigInt(converted) !== value) {
+                throw new TypeError(`${method} ${argument} ${verb} ${value}n, which ${endpoints.idType} cannot represent exactly.`);
+            }
+        }
+    }
+    return endpoints;
+}
+function uniqueRelationNames(input, requestedNames) {
+    const used = new Set([foldIdentifier(input)]);
+    const names = {};
+    for (const requested of requestedNames) {
+        let candidate = requested;
+        let suffix = 1;
+        while (used.has(foldIdentifier(quoteIdentifier(candidate)))) {
+            candidate = `${requested}_${suffix}`;
+            suffix++;
+        }
+        const quoted = quoteIdentifier(candidate);
+        used.add(foldIdentifier(quoted));
+        names[requested] = quoted;
+    }
+    return names;
+}

package/esm/helpers/prepareNumericFeatures.d.ts

@@ -0,0 +1,41 @@
+import type SimpleTable from "../class/SimpleTable.js";
+/** Returns whether a DuckDB type is a scalar numeric type. */
+export declare function isNumericScalarType(type: string): boolean;
+export type NumericFeatureInput = {
+    kind: "scalars";
+    columns: string[];
+} | {
+    kind: "vector";
+    column: string;
+};
+export type PreparedNumericFeatures = {
+    /** Raw temporary-relation name. Quote it before embedding it in SQL. */
+    relation: string;
+    /** Raw private row-identity column name. */
+    rowIdColumn: string;
+    /** Raw private `DOUBLE[d]` feature column name. */
+    vectorColumn: string;
+    dimensions: number;
+    rowCount: number;
+    /** Source column names in their original order and spelling. */
+    sourceColumns: string[];
+    sourceTemporary: boolean;
+    /** Drops all scratch state owned by this preparation. Safe to call twice. */
+    cleanup: () => Promise<void>;
+};
+/**
+ * Prepares scalar columns or a vector column as a private `DOUBLE[d]` feature
+ * vector while retaining every source column in DuckDB. Converting large
+ * integers or exact decimals to DOUBLE can lose precision. The source columns
+ * remain unchanged, so callers can publish results from the returned snapshot.
+ *
+ * The private row identity is positional and distinguishes duplicate rows. A
+ * caller owns the returned relation and must invoke `cleanup()` in `finally`.
+ * Preparation failures clean up their own scratch state.
+ */
+export default function prepareNumericFeatures(table: SimpleTable, input: NumericFeatureInput, options: {
+    method: string;
+    rejectNulls?: boolean;
+    rejectNonFinite?: boolean;
+}): Promise<PreparedNumericFeatures>;
+//# sourceMappingURL=prepareNumericFeatures.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepareNumericFeatures.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareNumericFeatures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAOvD,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,MAAM,MAAM,uBAAuB,GAAG;IACpC,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAA8B,sBAAsB,CAClD,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE;IACP,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GACA,OAAO,CAAC,uBAAuB,CAAC,CA2MlC"}

package/esm/helpers/prepareNumericFeatures.js

@@ -0,0 +1,210 @@
+import foldIdentifier from "./foldIdentifier.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+const NUMERIC_SCALAR_TYPE = /^(?:TINYINT|SMALLINT|INTEGER|BIGINT|HUGEINT|UTINYINT|USMALLINT|UINTEGER|UBIGINT|UHUGEINT|BIGNUM|FLOAT|REAL|DOUBLE|DECIMAL\(\d+,\d+\))$/;
+/** Returns whether a DuckDB type is a scalar numeric type. */
+export function isNumericScalarType(type) {
+    return NUMERIC_SCALAR_TYPE.test(type);
+}
+/**
+ * Prepares scalar columns or a vector column as a private `DOUBLE[d]` feature
+ * vector while retaining every source column in DuckDB. Converting large
+ * integers or exact decimals to DOUBLE can lose precision. The source columns
+ * remain unchanged, so callers can publish results from the returned snapshot.
+ *
+ * The private row identity is positional and distinguishes duplicate rows. A
+ * caller owns the returned relation and must invoke `cleanup()` in `finally`.
+ * Preparation failures clean up their own scratch state.
+ */
+export default async function prepareNumericFeatures(table, input, options) {
+    const rejectNulls = options.rejectNulls ?? true;
+    const rejectNonFinite = options.rejectNonFinite ?? true;
+    const types = await table.getTypes();
+    // Object.keys(types) sorts integer-like identifiers, which would reorder
+    // source columns when algorithms publish from this snapshot.
+    const sourceColumns = await table.getColumns();
+    const resolveColumn = (requested) => {
+        const resolved = sourceColumns.find((column) => foldIdentifier(column) === foldIdentifier(requested));
+        if (resolved === undefined) {
+            throw new Error(`${options.method} could not find column ${quoteIdentifier(requested)}. Available columns: ${sourceColumns.map(quoteIdentifier).join(", ")}.`);
+        }
+        return resolved;
+    };
+    let selectedColumns;
+    let vectorType;
+    if (input.kind === "scalars") {
+        if (input.columns.length === 0) {
+            throw new Error(`${options.method} requires at least one numeric scalar column.`);
+        }
+        const duplicate = findDuplicate(input.columns);
+        if (duplicate !== undefined) {
+            throw new Error(`${options.method} received duplicate input column ${quoteIdentifier(duplicate)}. Each numeric feature column must be listed once.`);
+        }
+        selectedColumns = input.columns.map(resolveColumn);
+        const nonNumeric = selectedColumns.filter((column) => !isNumericScalarType(types[column]));
+        if (nonNumeric.length > 0) {
+            throw new Error(`${options.method} requires numeric scalar columns. The following input columns are not numeric scalars: ${nonNumeric.map((column) => `${quoteIdentifier(column)} (${types[column]})`).join(", ")}. Convert them to numeric scalar types first.`);
+        }
+    }
+    else {
+        const column = resolveColumn(input.column);
+        selectedColumns = [column];
+        vectorType = parseNumericVectorType(types[column]);
+        if (vectorType === undefined) {
+            throw new Error(`${options.method} requires a one-dimensional numeric LIST or ARRAY column, but ${quoteIdentifier(column)} has type ${types[column]}.`);
+        }
+    }
+    const connection = table.connection;
+    const source = quoteIdentifier(table.name);
+    const suffix = crypto.randomUUID().replaceAll("-", "");
+    const relation = `__sda_features_${suffix}`;
+    const rowIdColumn = `__sda_row_${suffix}`;
+    const vectorColumn = `__sda_vector_${suffix}`;
+    const preparedRelation = quoteIdentifier(relation);
+    let cleaned = false;
+    const cleanup = async () => {
+        if (cleaned)
+            return;
+        await connection.run(`DROP TABLE IF EXISTS ${preparedRelation}`);
+        cleaned = true;
+    };
+    try {
+        const tableDetails = (await connection.runAndReadAll(`SELECT table_oid, temporary FROM duckdb_tables()
+       WHERE translate(table_name, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz') = $1
+         AND schema_name = current_schema()
+         AND database_name IN (current_database(), 'temp')
+       ORDER BY temporary DESC LIMIT 1`, [foldIdentifier(table.name)])).getRowsJS()[0];
+        if (tableDetails === undefined) {
+            throw new Error(`${options.method} requires a materialized source table.`);
+        }
+        const sourceTemporary = Boolean(tableDetails[1]);
+        const rowCount = Number((await connection.runAndReadAll(`SELECT count(*) FROM ${source}`))
+            .getRowsJS()[0][0]);
+        let dimensions;
+        let vectorExpression;
+        if (input.kind === "scalars") {
+            dimensions = selectedColumns.length;
+            await rejectInvalidScalarRows(connection, source, selectedColumns, types, options.method, { rejectNulls, rejectNonFinite });
+            vectorExpression = `[${selectedColumns.map((column) => castToDouble(quoteIdentifier(column), types[column]))
+                .join(", ")}]::DOUBLE[${dimensions}]`;
+        }
+        else {
+            const column = selectedColumns[0];
+            const quotedColumn = quoteIdentifier(column);
+            const emptyRows = Number((await connection.runAndReadAll(`SELECT count(*) FROM ${source}
+           WHERE ${quotedColumn} IS NOT NULL AND len(${quotedColumn}) = 0`)).getRowsJS()[0][0]);
+            if (emptyRows > 0) {
+                throw new Error(`${options.method} found ${emptyRows} row${emptyRows === 1 ? "" : "s"} with an empty vector in column ${quoteIdentifier(column)}. Vectors must have a nonzero dimension.`);
+            }
+            await rejectInvalidVectorRows(connection, source, column, vectorType.elementType, options.method, { rejectNulls, rejectNonFinite });
+            if (vectorType?.fixedDimensions !== undefined) {
+                dimensions = vectorType.fixedDimensions;
+            }
+            else {
+                const dimensionRows = (await connection.runAndReadAll(`SELECT len(${quotedColumn}) AS dimensions
+           FROM ${source} WHERE ${quotedColumn} IS NOT NULL LIMIT 1`)).getRowsJS();
+                if (dimensionRows.length === 0) {
+                    throw new Error(`${options.method} could not determine a vector dimension for ${quoteIdentifier(column)}. Provide at least one non-null, nonempty vector.`);
+                }
+                dimensions = Number(dimensionRows[0][0]);
+            }
+            const distinctDimensions = Number((await connection.runAndReadAll(`SELECT count(DISTINCT len(${quotedColumn})) FROM ${source}
+           WHERE ${quotedColumn} IS NOT NULL`)).getRowsJS()[0][0]);
+            if (distinctDimensions > 1) {
+                throw new Error(`${options.method} requires vectors with equal dimensions, but column ${quoteIdentifier(column)} contains ${distinctDimensions} different lengths.`);
+            }
+            vectorExpression = vectorType.elementType === "BIGNUM"
+                ? `list_transform(${quotedColumn}, value -> ${castToDouble("value", "BIGNUM")})::DOUBLE[${dimensions}]`
+                : `${quotedColumn}::DOUBLE[${dimensions}]`;
+        }
+        await connection.run(`CREATE TEMP TABLE ${preparedRelation} AS
+       SELECT *, row_number() OVER () - 1 AS ${quoteIdentifier(rowIdColumn)}, ${vectorExpression} AS ${quoteIdentifier(vectorColumn)}
+       FROM ${source}`);
+        return {
+            relation,
+            rowIdColumn,
+            vectorColumn,
+            dimensions,
+            rowCount,
+            sourceColumns,
+            sourceTemporary,
+            cleanup,
+        };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+function parseNumericVectorType(type) {
+    const match = /^(.+)\[(\d*)\]$/.exec(type);
+    if (match === null || !isNumericScalarType(match[1]))
+        return undefined;
+    const elementType = match[1];
+    if (match[2] === "")
+        return { elementType };
+    const fixedDimensions = Number(match[2]);
+    return fixedDimensions > 0 ? { elementType, fixedDimensions } : undefined;
+}
+function findDuplicate(columns) {
+    const seen = new Set();
+    for (const column of columns) {
+        const folded = foldIdentifier(column);
+        if (seen.has(folded))
+            return column;
+        seen.add(folded);
+    }
+    return undefined;
+}
+async function rejectInvalidScalarRows(connection, source, columns, types, method, validation) {
+    const predicates = columns.map((column) => {
+        const value = quoteIdentifier(column);
+        const converted = castToDouble(value, types[column], true);
+        const checks = [];
+        if (validation.rejectNulls)
+            checks.push(`${value} IS NULL`);
+        if (validation.rejectNonFinite) {
+            checks.push(`(${value} IS NOT NULL AND (${converted} IS NULL OR NOT isfinite(${converted})))`);
+        }
+        return checks.length === 0 ? "FALSE" : `(${checks.join(" OR ")})`;
+    });
+    if (predicates.every((predicate) => predicate === "FALSE"))
+        return;
+    const aliases = columns.map((_, index) => `invalid_${index}`);
+    const query = `SELECT
+    count(*) FILTER (WHERE ${predicates.join(" OR ")}) AS invalid_rows,
+    ${predicates.map((predicate, index) => `count(*) FILTER (WHERE ${predicate}) AS ${aliases[index]}`).join(", ")}
+    FROM ${source}`;
+    const row = (await connection.runAndReadAll(query)).getRowsJS()[0];
+    const invalidRows = Number(row[0]);
+    if (invalidRows === 0)
+        return;
+    const affected = columns.flatMap((column, index) => {
+        const count = Number(row[index + 1]);
+        return count === 0
+            ? []
+            : [`${quoteIdentifier(column)} (${count} row${count === 1 ? "" : "s"})`];
+    });
+    throw new Error(`${method} requires finite, non-null numeric features. Found ${invalidRows} invalid row${invalidRows === 1 ? "" : "s"}. Affected columns: ${affected.join(", ")}.`);
+}
+async function rejectInvalidVectorRows(connection, source, column, elementType, method, validation) {
+    const vector = quoteIdentifier(column);
+    const checks = [];
+    if (validation.rejectNulls) {
+        checks.push(`${vector} IS NULL`);
+        checks.push(`(${vector} IS NOT NULL AND list_count(${vector}) != len(${vector}))`);
+    }
+    if (validation.rejectNonFinite) {
+        checks.push(`(${vector} IS NOT NULL AND COALESCE(NOT list_bool_and(list_transform(${vector}, value -> value IS NULL OR COALESCE(isfinite(${castToDouble("value", elementType, true)}), FALSE))), FALSE))`);
+    }
+    if (checks.length === 0)
+        return;
+    const invalidRows = Number((await connection.runAndReadAll(`SELECT count(*) FROM ${source} WHERE ${checks.join(" OR ")}`)).getRowsJS()[0][0]);
+    if (invalidRows === 0)
+        return;
+    throw new Error(`${method} requires finite, non-null vector values. Column ${quoteIdentifier(column)} has ${invalidRows} invalid row${invalidRows === 1 ? "" : "s"}.`);
+}
+/** BIGNUM's direct DOUBLE conversion can throw even inside DuckDB TRY_CAST. */
+function castToDouble(value, type, tryCast = false) {
+    const convertible = type === "BIGNUM" ? `CAST(${value} AS VARCHAR)` : value;
+    return `${tryCast ? "TRY_CAST" : "CAST"}(${convertible} AS DOUBLE)`;
+}

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

@@ -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, options = {}) {

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

@@ -6,19 +6,6 @@ import wrapString from "./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 = [
@@ -39,6 +26,24 @@ import wrapString from "./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.
  */
 export default function printTable(data, options) {
     if (!data || data.length === 0) {

package/esm/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/esm/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"}