@nshiab/simple-data-analysis-core 2.1.11 → 2.1.13

package/esm/helpers/prepareGraphTemporalSql.js

@@ -1,161 +0,0 @@
-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,
-        journeyAnchor: (alias, direction) => direction === "outgoing"
-            ? temporalUnits(eventReference(alias, "__event_start"), startType, gapUnit)
-            : temporalUnits(eventReference(alias, "__event_end"), endType, gapUnit),
-        journeyElapsed: (alias, anchor, direction) => direction === "outgoing"
-            ? `(${temporalUnits(eventReference(alias, "__event_end"), endType, gapUnit)} - (${anchor}))`
-            : `((${anchor}) - ${temporalUnits(eventReference(alias, "__event_start"), startType, gapUnit)})`,
-        elapsedMilliseconds: (elapsed) => `(CAST(${elapsed} AS DOUBLE) / ${gapUnit === "nanosecond" ? 1000000 : 1000})`,
-        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

@@ -1,19 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,79 +0,0 @@
-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/prepareJSON.d.ts

@@ -1,3 +0,0 @@
-/** Validates and snapshots a JavaScript JSON value without dropping information. */
-export default function prepareJSON(value: unknown, column: string, row: number): string | null;
-//# sourceMappingURL=prepareJSON.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"prepareJSON.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareJSON.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,CAAC,OAAO,UAAU,WAAW,CACjC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAmEf"}

package/esm/helpers/prepareJSON.js

@@ -1,50 +0,0 @@
-/** Validates and snapshots a JavaScript JSON value without dropping information. */
-export default function prepareJSON(value, column, row) {
-    if (value === null || value === undefined)
-        return null;
-    const active = new Set();
-    const fail = (path, message) => {
-        throw new Error(`Column ${JSON.stringify(column)}, row ${row}, ${path}: ${message}`);
-    };
-    function serialize(value, path) {
-        if (value === null)
-            return "null";
-        if (typeof value === "string" || typeof value === "boolean") {
-            return JSON.stringify(value);
-        }
-        if (typeof value === "number" && Number.isFinite(value)) {
-            return Object.is(value, -0) ? "-0.0" : JSON.stringify(value);
-        }
-        if (typeof value !== "object") {
-            return fail(path, "Expected a JSON value: finite numbers, strings, booleans, null, arrays, or plain objects.");
-        }
-        if (active.has(value)) {
-            return fail(path, "Cyclic JSON values are unsupported.");
-        }
-        if (active.size >= 100) {
-            return fail(path, "JSON values may nest at most 100 levels.");
-        }
-        const array = Array.isArray(value);
-        if (!array && Object.getPrototypeOf(value) !== Object.prototype &&
-            Object.getPrototypeOf(value) !== null) {
-            return fail(path, "Expected a plain JSON object; convert class instances to JSON values first.");
-        }
-        if (Object.getOwnPropertySymbols(value).length) {
-            return fail(path, "JSON cannot represent symbol keys.");
-        }
-        active.add(value);
-        try {
-            if (array) {
-                if (Object.keys(value).length !== value.length) {
-                    return fail(path, "JSON arrays must be dense and have no extra properties.");
-                }
-                return `[${Array.from(value, (item, i) => serialize(item, `${path}[${i}]`)).join(",")}]`;
-            }
-            return `{${Object.entries(value).map(([key, item]) => `${JSON.stringify(key)}:${serialize(item, `${path}[${JSON.stringify(key)}]`)}`).join(",")}}`;
-        }
-        finally {
-            active.delete(value);
-        }
-    }
-    return serialize(value, "$");
-}

package/esm/helpers/prepareNumericFeatures.d.ts

@@ -1,41 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,210 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,23 +0,0 @@
-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/prepareValueFilters.d.ts

@@ -1,11 +0,0 @@
-import type { DuckDBValue } from "@duckdb/node-api";
-export type ValueFilter = {
-    column: string;
-    values: DuckDBValue[];
-    includesNull: boolean;
-};
-/** Converts column filter values to bindable values while tracking nulls. */
-export default function prepareValueFilters(columnsAndValues: {
-    [key: string]: unknown;
-}): ValueFilter[];
-//# sourceMappingURL=prepareValueFilters.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"prepareValueFilters.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareValueFilters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,OAAO,UAAU,mBAAmB,CACzC,gBAAgB,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAC3C,WAAW,EAAE,CAWf"}

package/esm/helpers/prepareValueFilters.js

@@ -1,12 +0,0 @@
-import toDuckDBValue from "./toDuckDBValue.js";
-/** Converts column filter values to bindable values while tracking nulls. */
-export default function prepareValueFilters(columnsAndValues) {
-    return Object.entries(columnsAndValues).map(([column, value]) => {
-        const boundValues = (Array.isArray(value) ? value : [value]).map(toDuckDBValue);
-        return {
-            column,
-            values: boundValues.filter((boundValue) => boundValue !== null),
-            includesNull: boundValues.some((boundValue) => boundValue === null),
-        };
-    });
-}