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

package/esm/helpers/prepareGraphTemporalSql.js

@@ -0,0 +1,154 @@
+import foldIdentifier from "./foldIdentifier.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+const temporalTypes = new Set([
+    "DATE",
+    "TIMESTAMP",
+    "TIMESTAMP_S",
+    "TIMESTAMP_MS",
+    "TIMESTAMP_NS",
+    "TIMESTAMP WITH TIME ZONE",
+]);
+/** Validates chronological options before a graph operation is queued. */
+export function prepareGraphTemporalOptions(options, direction, method) {
+    const startTimeColumn = options.startTimeColumn;
+    const endTimeColumn = options.endTimeColumn;
+    if (startTimeColumn !== undefined && typeof startTimeColumn !== "string") {
+        throw new TypeError(`${method} options.startTimeColumn must be a string.`);
+    }
+    if (endTimeColumn !== undefined && typeof endTimeColumn !== "string") {
+        throw new TypeError(`${method} options.endTimeColumn must be a string.`);
+    }
+    if (options.strictOrdering !== undefined &&
+        typeof options.strictOrdering !== "boolean") {
+        throw new TypeError(`${method} options.strictOrdering must be a boolean.`);
+    }
+    if (options.minGapMs !== undefined && typeof options.minGapMs !== "number") {
+        throw new TypeError(`${method} options.minGapMs must be a number.`);
+    }
+    const hasTimeColumn = startTimeColumn !== undefined ||
+        endTimeColumn !== undefined;
+    const hasTemporalSetting = options.minGapMs !== undefined ||
+        options.strictOrdering !== undefined;
+    if (!hasTimeColumn) {
+        if (hasTemporalSetting) {
+            throw new TypeError(`${method} options.minGapMs and options.strictOrdering require options.startTimeColumn or options.endTimeColumn.`);
+        }
+        return undefined;
+    }
+    if (direction === "both") {
+        throw new TypeError(`${method} options.direction cannot be "both" when chronological options are supplied.`);
+    }
+    const minGapMs = options.minGapMs ?? 0;
+    if (!Number.isFinite(minGapMs) || minGapMs < 0 || !Number.isInteger(minGapMs)) {
+        throw new TypeError(`${method} options.minGapMs must be a finite, non-negative integer.`);
+    }
+    if (minGapMs > Number.MAX_SAFE_INTEGER) {
+        throw new TypeError(`${method} options.minGapMs must not exceed Number.MAX_SAFE_INTEGER.`);
+    }
+    const gapMicroseconds = BigInt(minGapMs) * 1000n;
+    return {
+        endTimeColumn,
+        gapMicroseconds,
+        startTimeColumn,
+        strictOrdering: options.strictOrdering ?? true,
+    };
+}
+/** Prepares native-precision event and transition SQL from a queued schema. */
+export default function prepareGraphTemporalSql(schema, options, method) {
+    const start = options.startTimeColumn === undefined
+        ? undefined
+        : getTemporalColumn(schema, options.startTimeColumn, method);
+    const end = options.endTimeColumn === undefined
+        ? undefined
+        : getTemporalColumn(schema, options.endTimeColumn, method);
+    if (start?.zoned !== undefined && end?.zoned !== undefined) {
+        if (start.zoned !== end.zoned) {
+            throw new TypeError(`${method} cannot mix time-zone-aware and time-zone-naive chronological columns. Convert both columns to the same timestamp domain first.`);
+        }
+    }
+    const startColumn = start?.column ?? end.column;
+    const endColumn = end?.column ?? start.column;
+    const startType = start?.type ?? end.type;
+    const endType = end?.type ?? start.type;
+    const gapUnit = start?.type === "TIMESTAMP_NS" ||
+        end?.type === "TIMESTAMP_NS"
+        ? "nanosecond"
+        : "microsecond";
+    const gap = gapUnit === "nanosecond"
+        ? options.gapMicroseconds * 1000n
+        : options.gapMicroseconds;
+    const q = quoteIdentifier;
+    const reference = (alias, column) => `${alias === undefined ? "" : `${q(alias)}.`}${q(column)}`;
+    const eventReference = (alias, name) => `${alias === undefined ? "" : `${q(alias)}.`}${q(name)}`;
+    return {
+        startTimeColumn: start?.column,
+        endTimeColumn: end?.column,
+        gapParameter: gap.toString(),
+        gapUnit,
+        eventSelections: (alias) => [
+            `row_number() OVER () AS ${q("__event_id")}`,
+            `${reference(alias, startColumn)} AS ${q("__event_start")}`,
+            `${reference(alias, endColumn)} AS ${q("__event_end")}`,
+        ],
+        eventValidity: (alias) => {
+            const eventStart = eventReference(alias, "__event_start");
+            const eventEnd = eventReference(alias, "__event_end");
+            return `CASE
+        WHEN ${eventStart} IS NULL OR ${eventEnd} IS NULL THEN false
+        WHEN NOT isfinite(${eventStart}) OR NOT isfinite(${eventEnd}) THEN false
+        ELSE ${temporalUnits(eventEnd, endType, gapUnit)} >= ${temporalUnits(eventStart, startType, gapUnit)}
+      END`;
+        },
+        transition: (currentAlias, candidateAlias, direction, gapExpression) => {
+            const currentStart = eventReference(currentAlias, "__event_start");
+            const currentEnd = eventReference(currentAlias, "__event_end");
+            const candidateStart = eventReference(candidateAlias, "__event_start");
+            const candidateEnd = eventReference(candidateAlias, "__event_end");
+            const earlierEnd = direction === "outgoing" ? currentEnd : candidateEnd;
+            const laterStart = direction === "outgoing"
+                ? candidateStart
+                : currentStart;
+            const elapsed = `${temporalUnits(laterStart, startType, gapUnit)} - ${temporalUnits(earlierEnd, endType, gapUnit)}`;
+            const ordering = options.strictOrdering
+                ? `
+        AND ${elapsed} > 0`
+                : "";
+            return `${elapsed} >= ${gapExpression}${ordering}`;
+        },
+    };
+}
+function temporalUnits(expression, type, unit) {
+    // Widen before scaling/subtraction to preserve precision and the DATE range.
+    const scale = unit === "nanosecond" ? 1000n : 1n;
+    if (type === "DATE") {
+        return `(CAST(date_diff('day', DATE '1970-01-01', ${expression}) AS HUGEINT) * ${86400000000n * scale})`;
+    }
+    if (type === "TIMESTAMP_NS") {
+        return `CAST(epoch_ns(${expression}) AS HUGEINT)`;
+    }
+    return `(CAST(epoch_us(${expression}) AS HUGEINT) * ${scale})`;
+}
+function getTemporalColumn(schema, requested, method) {
+    const folded = foldIdentifier(requested);
+    const column = Object.keys(schema).find((name) => foldIdentifier(name) === folded);
+    if (column === undefined) {
+        throw new Error(`${method} the column ${quoteIdentifier(requested)} does not exist. Check for typos, or load the data first.`);
+    }
+    const type = normalizeTemporalType(schema[column]);
+    if (!temporalTypes.has(type)) {
+        throw new TypeError(`${method} requires DATE or TIMESTAMP chronological columns, but column ${quoteIdentifier(column)} has type ${schema[column].toUpperCase()}.`);
+    }
+    return {
+        column,
+        type,
+        zoned: type === "TIMESTAMP WITH TIME ZONE",
+    };
+}
+function normalizeTemporalType(type) {
+    const normalized = type.toUpperCase();
+    if (normalized === "TIMESTAMPTZ")
+        return "TIMESTAMP WITH TIME ZONE";
+    if (normalized === "TIMESTAMP WITHOUT TIME ZONE")
+        return "TIMESTAMP";
+    return normalized;
+}

package/esm/helpers/prepareGraphTraversal.d.ts

@@ -0,0 +1,19 @@
+import { type GraphEndpointColumns } from "./getGraphEndpointColumns.js";
+import type { TableSchema } from "./pendingOps.js";
+import type { PreparedGraphStarts } from "./prepareGraphStarts.js";
+export type GraphDirection = "outgoing" | "incoming" | "both";
+export type PreparedGraphTraversal = {
+    edges: (direction: GraphDirection, selections?: string[]) => string;
+    endpoints: GraphEndpointColumns;
+    key: (expression: string) => string;
+    relationNames: (names: string[]) => Record<string, string>;
+    startValues: string;
+};
+export type PreparedGraphSql = Omit<PreparedGraphTraversal, "startValues">;
+/** Prepares exact-ID SQL shared by graph traversal methods. */
+export default function prepareGraphTraversal(input: string, schema: TableSchema, source: string, target: string, starts: PreparedGraphStarts, method: string, argument?: string): PreparedGraphTraversal;
+/** Prepares exact-ID edge SQL for graph methods without starting nodes. */
+export declare function prepareGraphSql(input: string, schema: TableSchema, source: string, target: string, method: string): PreparedGraphSql;
+/** Validates supplied starts against resolved endpoint ID types. */
+export declare function validateGraphStarts(schema: TableSchema, source: string, target: string, starts: PreparedGraphStarts, method: string, argument?: string): GraphEndpointColumns;
+//# sourceMappingURL=prepareGraphTraversal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepareGraphTraversal.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareGraphTraversal.ts"],"names":[],"mappings":"AACA,OAAgC,EAC9B,KAAK,oBAAoB,EAC1B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGnE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAE9D,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,EAAE,CAAC,SAAS,EAAE,cAAc,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;IACpE,SAAS,EAAE,oBAAoB,CAAC;IAChC,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,sBAAsB,EAAE,aAAa,CAAC,CAAC;AAE3E,+DAA+D;AAC/D,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAC3C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,SAAU,GACjB,sBAAsB,CAcxB;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,gBAAgB,CAKlB;AAwCD,oEAAoE;AACpE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,SAAU,GACjB,oBAAoB,CAyBtB"}

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/prepareUmapLayoutOptions.d.ts

@@ -0,0 +1,14 @@
+export default function prepareUmapLayoutOptions(options?: {
+    epochs?: number;
+    seed?: number;
+    minDistance?: number;
+    learningRate?: number;
+    negativeSamples?: number;
+}): {
+    epochs: number;
+    seed: number;
+    learningRate: number;
+    negativeSamples: number;
+    curve: [number, number];
+};
+//# sourceMappingURL=prepareUmapLayoutOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepareUmapLayoutOptions.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareUmapLayoutOptions.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAC9C,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;CACrB;;;;;;EA2BP"}

package/esm/helpers/prepareUmapLayoutOptions.js

@@ -0,0 +1,23 @@
+import fitUmapCurve from "./fitUmapCurve.js";
+// Resolve and validate settings before database work, fitting the curve once.
+export default 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: fitUmapCurve(minDistance),
+    };
+}

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"}