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

package/esm/methods/hdbscan.js

@@ -0,0 +1,208 @@
+import { DOUBLE, INTEGER, VARCHAR } from "@duckdb/node-api";
+import appendColumnBatches from "../helpers/appendColumnBatches.js";
+import buildApproximateMutualReachabilityMst from "../helpers/buildApproximateMutualReachabilityMst.js";
+import buildExactMutualReachabilityMst from "../helpers/buildExactMutualReachabilityMst.js";
+import clusterHdbscan from "../helpers/clusterHdbscan.js";
+import foldIdentifier from "../helpers/foldIdentifier.js";
+import prepareNumericFeatures from "../helpers/prepareNumericFeatures.js";
+import publishPreparedColumns from "../helpers/publishPreparedColumns.js";
+import queueOp from "../helpers/queueOp.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+export default function hdbscan(table, columns, newColumn, options = {}) {
+    const selected = typeof columns === "string" ? columns : [...columns];
+    const settings = structuredClone(options);
+    queueOp(table, {
+        kind: "barrier",
+        method: "hdbscan()",
+        parameters: { columns: selected, newColumn, options: settings },
+        execute: () => execute(table, selected, newColumn, settings),
+    });
+}
+async function execute(table, columns, newColumn, options) {
+    const { minClusterSize = 5, metric = "euclidean", allowSingleCluster = false, approximate = false, membershipScoreColumn, outlierScoreColumn, } = options;
+    const minSamples = options.minSamples ?? minClusterSize;
+    if (typeof newColumn !== "string") {
+        throw new Error("hdbscan() newColumn must be a string.");
+    }
+    if (!Number.isSafeInteger(minClusterSize) || minClusterSize < 2) {
+        throw new Error("hdbscan() minClusterSize must be a safe integer of at least 2.");
+    }
+    if (!Number.isSafeInteger(minSamples) || minSamples < 1) {
+        throw new Error("hdbscan() minSamples must be a safe integer of at least 1.");
+    }
+    if (!["euclidean", "cosine"].includes(metric)) {
+        throw new Error('hdbscan() metric must be "euclidean" or "cosine".');
+    }
+    if (typeof allowSingleCluster !== "boolean") {
+        throw new Error("hdbscan() allowSingleCluster must be a boolean.");
+    }
+    if (typeof approximate !== "boolean") {
+        throw new Error("hdbscan() approximate must be a boolean.");
+    }
+    if (membershipScoreColumn !== undefined &&
+        typeof membershipScoreColumn !== "string") {
+        throw new Error("hdbscan() membershipScoreColumn must be a string.");
+    }
+    if (outlierScoreColumn !== undefined &&
+        typeof outlierScoreColumn !== "string") {
+        throw new Error("hdbscan() outlierScoreColumn must be a string.");
+    }
+    const sourceColumns = Object.keys(await table.getTypes());
+    const outputNames = [newColumn, membershipScoreColumn, outlierScoreColumn]
+        .filter((name) => name !== undefined);
+    validateOutputNames(sourceColumns, outputNames);
+    const prepared = await prepareNumericFeatures(table, typeof columns === "string"
+        ? { kind: "vector", column: columns }
+        : { kind: "scalars", columns }, { method: "hdbscan()" });
+    const connection = table.connection;
+    const suffix = crypto.randomUUID().replaceAll("-", "");
+    const name = (part) => `__sda_hdbscan_${suffix}_${part}`;
+    const names = {
+        rows: name("rows"),
+        neighbors: name("neighbors"),
+        search: name("search"),
+        hnsw: name("hnsw"),
+        candidates: name("candidates"),
+        coreDistances: name("core_distances"),
+        frontier: name("frontier"),
+        edges: name("edges"),
+        components: name("components"),
+        representatives: name("representatives"),
+        componentPairs: name("component_pairs"),
+        bridgeCandidates: name("bridge_candidates"),
+        mst: name("mst"),
+        result: name("result"),
+    };
+    try {
+        if (prepared.rowCount < 2) {
+            throw new Error(`hdbscan() requires at least 2 rows, but the input has ${prepared.rowCount}.`);
+        }
+        if (prepared.rowCount > 0x40000000) {
+            throw new Error("hdbscan() supports at most 1073741824 rows because its 2*n-1 hierarchy nodes use signed INTEGER identifiers.");
+        }
+        if (minSamples >= prepared.rowCount) {
+            const defaulted = options.minSamples === undefined
+                ? " (defaulted from minClusterSize)"
+                : "";
+            throw new Error(`hdbscan() minSamples is ${minSamples}${defaulted}, but ${prepared.rowCount} rows provide at most ${prepared.rowCount - 1} other point${prepared.rowCount === 2 ? "" : "s"}. Set minSamples between 1 and ${prepared.rowCount - 1}, or provide at least ${minSamples + 1} rows.`);
+        }
+        if (minClusterSize > prepared.rowCount) {
+            throw new Error(`hdbscan() minClusterSize is ${minClusterSize}, but the input has ${prepared.rowCount} rows. Set minClusterSize between 2 and ${prepared.rowCount}, or provide more rows.`);
+        }
+        const q = quoteIdentifier;
+        await connection.run(`CREATE TEMP TABLE ${q(names.rows)} AS
+       SELECT ${q(prepared.rowIdColumn)}::INTEGER AS vertex,
+         ${q(prepared.vectorColumn)} AS vec
+       FROM ${q(prepared.relation)}
+       ORDER BY ${q(prepared.rowIdColumn)}`);
+        if (approximate) {
+            await buildApproximateMutualReachabilityMst(connection, {
+                count: prepared.rowCount,
+                dimensions: prepared.dimensions,
+                minSamples,
+            }, { metric }, {
+                rows: names.rows,
+                neighbors: names.neighbors,
+                search: names.search,
+                hnsw: names.hnsw,
+                candidates: names.candidates,
+                coreDistances: names.coreDistances,
+                edges: names.edges,
+                components: names.components,
+                representatives: names.representatives,
+                componentPairs: names.componentPairs,
+                bridgeCandidates: names.bridgeCandidates,
+                mst: names.mst,
+            });
+        }
+        else {
+            await buildExactMutualReachabilityMst(connection, { count: prepared.rowCount, minSamples }, { metric }, {
+                rows: q(names.rows),
+                coreDistances: q(names.coreDistances),
+                frontier: q(names.frontier),
+                mst: q(names.mst),
+            });
+        }
+        const result = await clusterHdbscan(connection, q(names.mst), {
+            count: prepared.rowCount,
+            minClusterSize,
+            allowSingleCluster,
+        });
+        const labelColumn = "label";
+        const membershipColumn = "membership";
+        const gloshColumn = "glosh";
+        const resultColumns = [
+            "row_id INTEGER",
+            `${labelColumn} VARCHAR`,
+            membershipScoreColumn === undefined
+                ? undefined
+                : `${membershipColumn} DOUBLE`,
+            outlierScoreColumn === undefined ? undefined : `${gloshColumn} DOUBLE`,
+        ].filter((definition) => definition !== undefined);
+        await connection.run(`CREATE TEMP TABLE ${q(names.result)} (${resultColumns.join(",")})`);
+        const outputTypes = [
+            INTEGER,
+            VARCHAR,
+            ...(membershipScoreColumn === undefined ? [] : [DOUBLE]),
+            ...(outlierScoreColumn === undefined ? [] : [DOUBLE]),
+        ];
+        await appendColumnBatches(connection, names.result, outputTypes, prepared.rowCount, (column, start, end) => {
+            if (column === 0) {
+                return Array.from({ length: end - start }, (_, offset) => start + offset);
+            }
+            if (column === 1) {
+                return Array.from(result.labels.subarray(start, end), (label) => label < 0 ? "noise" : `cluster-${label}`);
+            }
+            const membershipIndex = membershipScoreColumn === undefined ? -1 : 2;
+            return Array.from(column === membershipIndex
+                ? result.probabilities.subarray(start, end)
+                : result.outlierScores.subarray(start, end));
+        });
+        const publicationOutputs = [{
+                name: newColumn,
+                expression: `r.${q(labelColumn)}`,
+            }];
+        if (membershipScoreColumn !== undefined) {
+            publicationOutputs.push({
+                name: membershipScoreColumn,
+                expression: `r.${q(membershipColumn)}`,
+            });
+        }
+        if (outlierScoreColumn !== undefined) {
+            publicationOutputs.push({
+                name: outlierScoreColumn,
+                expression: `r.${q(gloshColumn)}`,
+            });
+        }
+        await publishPreparedColumns(table, prepared, {
+            method: "hdbscan()",
+            parameters: { columns, newColumn, options },
+            result: { relation: names.result, rowIdColumn: "row_id" },
+            outputs: publicationOutputs,
+        });
+    }
+    finally {
+        for (const relation of Object.entries(names).reverse().flatMap(([key, value]) => key === "hnsw" ? [] : [value])) {
+            await connection.run(`DROP TABLE IF EXISTS ${quoteIdentifier(relation)}`);
+        }
+        await prepared.cleanup();
+    }
+}
+function validateOutputNames(sourceColumns, outputNames) {
+    const seen = new Map();
+    for (const name of outputNames) {
+        if (name.length === 0 || name.includes("\0")) {
+            throw new Error("hdbscan() output column names must be non-empty strings without null characters.");
+        }
+        const folded = foldIdentifier(name);
+        const source = sourceColumns.find((column) => foldIdentifier(column) === folded);
+        if (source !== undefined) {
+            throw new Error(`hdbscan() cannot create ${quoteIdentifier(name)} because that source column already exists. Remove it first or choose different output names.`);
+        }
+        const duplicate = seen.get(folded);
+        if (duplicate !== undefined) {
+            throw new Error(`hdbscan() output columns ${quoteIdentifier(duplicate)} and ${quoteIdentifier(name)} refer to the same column. Choose distinct output names.`);
+        }
+        seen.set(folded, name);
+    }
+}

package/esm/methods/mahalanobis.d.ts

@@ -0,0 +1,5 @@
+import type SimpleTable from "../class/SimpleTable.js";
+type Options = NonNullable<Parameters<SimpleTable["mahalanobis"]>[3]>;
+export default function mahalanobis(table: SimpleTable, columns: string | string[], referencePoint: number[], newColumn: string, options?: Options): void;
+export {};
+//# sourceMappingURL=mahalanobis.d.ts.map

package/esm/methods/mahalanobis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mahalanobis.d.ts","sourceRoot":"","sources":["../../src/methods/mahalanobis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AASvD,KAAK,OAAO,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtE,MAAM,CAAC,OAAO,UAAU,WAAW,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,EAC1B,cAAc,EAAE,MAAM,EAAE,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,OAAY,GACpB,IAAI,CAyBN"}

package/esm/methods/mahalanobis.js

@@ -0,0 +1,92 @@
+import computeCovariance from "../helpers/computeCovariance.js";
+import computeMahalanobisDistances from "../helpers/computeMahalanobisDistances.js";
+import foldIdentifier from "../helpers/foldIdentifier.js";
+import prepareNumericFeatures from "../helpers/prepareNumericFeatures.js";
+import publishPreparedColumns from "../helpers/publishPreparedColumns.js";
+import queueOp from "../helpers/queueOp.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+export default function mahalanobis(table, columns, referencePoint, newColumn, options = {}) {
+    if (!Array.isArray(referencePoint) || referencePoint.length === 0 ||
+        Array.from(referencePoint).some((value) => typeof value !== "number" || !Number.isFinite(value))) {
+        throw new Error("mahalanobis() referencePoint must be a nonempty array of finite numbers in feature-dimension order.");
+    }
+    const selected = typeof columns === "string" ? columns : [...columns];
+    const reference = [...referencePoint];
+    const settings = { ...options };
+    queueOp(table, {
+        kind: "barrier",
+        method: "mahalanobis()",
+        parameters: {
+            columns: selected,
+            referencePoint: reference,
+            newColumn,
+            options: settings,
+        },
+        execute: () => execute(table, selected, reference, newColumn, settings),
+    });
+}
+async function execute(table, columns, referencePoint, newColumn, options) {
+    const sourceColumns = Object.keys(await table.getTypes());
+    const outputNames = options.similarityScoreColumn === undefined
+        ? [newColumn]
+        : [newColumn, options.similarityScoreColumn];
+    const seen = new Set();
+    for (const name of outputNames) {
+        if (typeof name !== "string" || name.length === 0 || name.includes("\0")) {
+            throw new Error("mahalanobis() output column names must be nonempty strings without null characters.");
+        }
+        const folded = foldIdentifier(name);
+        if (seen.has(folded)) {
+            throw new Error("mahalanobis() distance and similarity score columns must have different names (case-insensitive).");
+        }
+        seen.add(folded);
+        if (sourceColumns.some((column) => foldIdentifier(column) === folded)) {
+            throw new Error(`mahalanobis() cannot create ${quoteIdentifier(name)} because that column already exists. Remove it first or choose a different name.`);
+        }
+    }
+    const prepared = await prepareNumericFeatures(table, typeof columns === "string"
+        ? { kind: "vector", column: columns }
+        : { kind: "scalars", columns }, { method: "mahalanobis()" });
+    try {
+        if (referencePoint.length !== prepared.dimensions) {
+            throw new Error(`mahalanobis() referencePoint must contain ${prepared.dimensions} values in feature-dimension order; received ${referencePoint.length}.`);
+        }
+        const model = await computeCovariance(table.connection, {
+            relation: prepared.relation,
+            rowIdColumn: prepared.rowIdColumn,
+            vectorColumn: prepared.vectorColumn,
+            observations: prepared.rowCount,
+            dimensions: prepared.dimensions,
+        });
+        const distances = await computeMahalanobisDistances(table.connection, {
+            relation: prepared.relation,
+            rowIdColumn: prepared.rowIdColumn,
+            vectorColumn: prepared.vectorColumn,
+        }, model, referencePoint);
+        try {
+            const distance = `r.${quoteIdentifier(distances.distanceColumn)}`;
+            const outputs = [{ name: newColumn, expression: distance }];
+            if (options.similarityScoreColumn !== undefined) {
+                outputs.push({
+                    name: options.similarityScoreColumn,
+                    expression: `CASE WHEN max(${distance}) OVER () = 0 THEN 1::DOUBLE ELSE 1 - ${distance} / max(${distance}) OVER () END`,
+                });
+            }
+            await publishPreparedColumns(table, prepared, {
+                method: "mahalanobis()",
+                parameters: { columns, referencePoint, newColumn, options },
+                result: {
+                    relation: distances.relation,
+                    rowIdColumn: distances.rowIdColumn,
+                },
+                outputs,
+            });
+        }
+        finally {
+            await distances.cleanup();
+        }
+    }
+    finally {
+        await prepared.cleanup();
+    }
+}

package/esm/methods/neighbors.d.ts

@@ -0,0 +1,9 @@
+import { type GraphId } from "../helpers/prepareGraphStarts.js";
+import type SimpleTable from "../class/SimpleTable.js";
+type NeighborsOptions = {
+    direction?: "outgoing" | "incoming" | "both";
+    outputTable?: string | boolean;
+};
+export default function neighbors(simpleTable: SimpleTable, sourceColumn: string, targetColumn: string, startNodes: GraphId | GraphId[], options?: NeighborsOptions): SimpleTable;
+export {};
+//# sourceMappingURL=neighbors.d.ts.map

package/esm/methods/neighbors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neighbors.d.ts","sourceRoot":"","sources":["../../src/methods/neighbors.ts"],"names":[],"mappings":"AAAA,OAA2B,EACzB,KAAK,OAAO,EAEb,MAAM,kCAAkC,CAAC;AAO1C,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAGvD,KAAK,gBAAgB,GAAG;IACtB,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,OAAO,GAAG,OAAO,EAAE,EAC/B,OAAO,GAAE,gBAAqB,GAC7B,WAAW,CAuEb"}

package/esm/methods/neighbors.js

@@ -0,0 +1,81 @@
+import prepareGraphStarts from "../helpers/prepareGraphStarts.js";
+import prepareGraphTraversal, { validateGraphStarts, } from "../helpers/prepareGraphTraversal.js";
+import queueGraphResult from "../helpers/queueGraphResult.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+export default function neighbors(simpleTable, sourceColumn, targetColumn, startNodes, options = {}) {
+    if (typeof sourceColumn !== "string") {
+        throw new TypeError("neighbors() sourceColumn must be a string.");
+    }
+    if (typeof targetColumn !== "string") {
+        throw new TypeError("neighbors() targetColumn must be a string.");
+    }
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("neighbors() options must be an object.");
+    }
+    if (options.direction !== undefined &&
+        !["outgoing", "incoming", "both"].includes(options.direction)) {
+        throw new TypeError('neighbors() options.direction must be "outgoing", "incoming", or "both".');
+    }
+    if (options.outputTable !== undefined &&
+        typeof options.outputTable !== "string" &&
+        typeof options.outputTable !== "boolean") {
+        throw new TypeError("neighbors() options.outputTable must be a string or boolean.");
+    }
+    const preparedStarts = prepareGraphStarts(startNodes, "neighbors()", "startNodes");
+    options = structuredClone(options);
+    const direction = options.direction ?? "outgoing";
+    const parameters = {
+        sourceColumn,
+        targetColumn,
+        startNodes: structuredClone(startNodes),
+        options,
+    };
+    return queueGraphResult(simpleTable, {
+        method: "neighbors()",
+        parameters,
+        outputTable: options.outputTable,
+        values: (schema) => {
+            validateStarts(schema, sourceColumn, targetColumn, preparedStarts);
+            return preparedStarts.values;
+        },
+        buildSelect: (input, schema) => neighborsSelect(input, schema, sourceColumn, targetColumn, preparedStarts, direction),
+        outputSchema: (schema) => {
+            const endpoints = validateStarts(schema, sourceColumn, targetColumn, preparedStarts);
+            return { start: endpoints.idType, node: endpoints.idType };
+        },
+    });
+}
+function validateStarts(schema, source, target, starts) {
+    return validateGraphStarts(schema, source, target, starts, "neighbors()", "startNodes");
+}
+function neighborsSelect(input, schema, source, target, starts, direction) {
+    const prepared = prepareGraphTraversal(input, schema, source, target, starts, "neighbors()", "startNodes");
+    const relations = prepared.relationNames([
+        "graph_starts",
+        "graph_edges",
+        "neighbor_matches",
+    ]);
+    const startsRelation = relations.graph_starts;
+    const edgesRelation = relations.graph_edges;
+    const matchesRelation = relations.neighbor_matches;
+    return `WITH ${startsRelation}(${quoteIdentifier("start")}) AS (
+      VALUES ${prepared.startValues}
+    ), ${edgesRelation} AS (
+      ${prepared.edges(direction)}
+    ), ${matchesRelation} AS (
+      SELECT ${quoteIdentifier("starts")}.${quoteIdentifier("start")},
+        ${quoteIdentifier("edges")}.${quoteIdentifier("__to")} AS ${quoteIdentifier("node")},
+        ${quoteIdentifier("edges")}.${quoteIdentifier("__from_key")} AS ${quoteIdentifier("__start_key")},
+        ${quoteIdentifier("edges")}.${quoteIdentifier("__to_key")} AS ${quoteIdentifier("__node_key")}
+      FROM ${edgesRelation} AS ${quoteIdentifier("edges")}
+      INNER JOIN ${startsRelation} AS ${quoteIdentifier("starts")}
+        ON ${quoteIdentifier("edges")}.${quoteIdentifier("__from_key")} =
+          ${prepared.key(`${quoteIdentifier("starts")}.${quoteIdentifier("start")}`)}
+    )
+    SELECT ${quoteIdentifier("start")}, ${quoteIdentifier("node")}
+    FROM (
+      SELECT DISTINCT ${quoteIdentifier("start")}, ${quoteIdentifier("node")}, ${quoteIdentifier("__start_key")}, ${quoteIdentifier("__node_key")}
+      FROM ${matchesRelation}
+    ) AS ${quoteIdentifier("distinct_neighbors")}
+    ORDER BY ${quoteIdentifier("__start_key")}, ${quoteIdentifier("__node_key")}`;
+}

package/esm/methods/normalizeVector.d.ts

@@ -0,0 +1,5 @@
+import type SimpleTable from "../class/SimpleTable.js";
+type Options = NonNullable<Parameters<SimpleTable["normalizeVector"]>[2]>;
+export default function normalizeVector(table: SimpleTable, column: string, newColumn: string, options?: Options): void;
+export {};
+//# sourceMappingURL=normalizeVector.d.ts.map

package/esm/methods/normalizeVector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeVector.d.ts","sourceRoot":"","sources":["../../src/methods/normalizeVector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAOvD,KAAK,OAAO,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1E,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,OAAY,GACpB,IAAI,CAiBN"}

package/esm/methods/normalizeVector.js

@@ -0,0 +1,132 @@
+import foldIdentifier from "../helpers/foldIdentifier.js";
+import prepareNumericFeatures from "../helpers/prepareNumericFeatures.js";
+import publishPreparedColumns from "../helpers/publishPreparedColumns.js";
+import queueOp from "../helpers/queueOp.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+export default function normalizeVector(table, column, newColumn, options = {}) {
+    if (options.normalization !== undefined &&
+        options.normalization !== "dimensionMinMax" &&
+        options.normalization !== "rowL2") {
+        throw new Error('normalizeVector() options.normalization must be "dimensionMinMax" or "rowL2".');
+    }
+    const settings = structuredClone(options);
+    queueOp(table, {
+        kind: "barrier",
+        method: "normalizeVector()",
+        parameters: { column, newColumn, options: settings },
+        execute: () => execute(table, column, newColumn, settings),
+    });
+}
+async function execute(table, column, newColumn, options) {
+    const normalization = options.normalization ?? "dimensionMinMax";
+    const overwrite = foldIdentifier(column) === foldIdentifier(newColumn);
+    if (!overwrite) {
+        const sourceColumns = Object.keys(await table.getTypes());
+        if (sourceColumns.some((name) => foldIdentifier(name) === foldIdentifier(newColumn))) {
+            throw new Error(`normalizeVector() cannot create ${quoteIdentifier(newColumn)} because that column already exists. Remove it first or choose a different name.`);
+        }
+    }
+    const prepared = await prepareNumericFeatures(table, { kind: "vector", column }, { method: "normalizeVector()" });
+    const connection = table.connection;
+    const q = quoteIdentifier;
+    const suffix = crypto.randomUUID().replaceAll("-", "");
+    const statsName = `__sda_normalize_vector_${suffix}_stats`;
+    const resultName = `__sda_normalize_vector_${suffix}_result`;
+    const dimension = q(`__sda_dimension_${suffix}`);
+    const minimum = q(`__sda_min_${suffix}`);
+    const maximum = q(`__sda_max_${suffix}`);
+    const normalized = `__sda_normalized_${suffix}`;
+    try {
+        if (prepared.rowCount === 0) {
+            throw new Error("normalizeVector() requires at least one row; the dataset is empty.");
+        }
+        const sourceColumn = prepared.sourceColumns.find((name) => foldIdentifier(name) === foldIdentifier(column));
+        if (normalization === "rowL2") {
+            // Scale before squaring so extreme finite magnitudes do not overflow
+            // or underflow the norm. A zero vector stays zero.
+            await connection.run(`CREATE TEMP TABLE ${q(resultName)} AS
+         WITH magnitudes AS (
+           SELECT ${q(prepared.rowIdColumn)}, ${q(prepared.vectorColumn)} AS vec,
+             list_max(list_transform(${q(prepared.vectorColumn)}, value -> abs(value))) AS magnitude
+           FROM ${q(prepared.relation)}
+         ), scaled AS (
+           SELECT *, list_transform(vec, value -> value / nullif(magnitude, 0)) AS unit_scale
+           FROM magnitudes
+         ), norms AS (
+           SELECT *, sqrt(list_sum(list_transform(unit_scale, value -> value * value))) AS norm
+           FROM scaled
+         )
+         SELECT ${q(prepared.rowIdColumn)},
+           (CASE WHEN magnitude = 0 THEN vec::DOUBLE[]
+             ELSE list_transform(unit_scale, value -> value / norm)
+           END)::DOUBLE[${prepared.dimensions}] AS ${q(normalized)}
+         FROM norms`);
+        }
+        else {
+            await connection.run(`CREATE TEMP TABLE ${q(statsName)} AS
+         SELECT ordinal::BIGINT AS ${dimension}, min(value)::DOUBLE AS ${minimum},
+           max(value)::DOUBLE AS ${maximum}
+         FROM ${q(prepared.relation)} p,
+           UNNEST(p.${q(prepared.vectorColumn)}::DOUBLE[]) WITH ORDINALITY AS values(value, ordinal)
+         GROUP BY ordinal`);
+            const invalidStats = Number((await connection.runAndReadAll(`SELECT count(*) FROM ${q(statsName)}
+           WHERE NOT isfinite(${minimum}) OR NOT isfinite(${maximum})`)).getRowsJS()[0][0]);
+            if (invalidStats > 0) {
+                throw new Error(`normalizeVector() found ${invalidStats} dimension${invalidStats === 1 ? "" : "s"} with non-finite aggregate values after conversion to DOUBLE.`);
+            }
+            const constantDimensions = (await connection.runAndReadAll(`SELECT ${dimension} FROM ${q(statsName)}
+         WHERE ${minimum} = ${maximum} ORDER BY ${dimension}`)).getRowsJS().map((row) => Number(row[0]));
+            if (constantDimensions.length > 0) {
+                throw new Error(`normalizeVector() cannot scale constant dimension${constantDimensions.length === 1 ? "" : "s"} ${constantDimensions.join(", ")} in column ${q(sourceColumn)} because the range is zero. Remove ${constantDimensions.length === 1
+                    ? "that dimension"
+                    : "those dimensions"} before normalizing. Conversion to DOUBLE can also collapse distinct large integers or decimals at its precision limit.`);
+            }
+            const value = `p.${q(prepared.vectorColumn)}[s.${dimension}]`;
+            const min = `s.${minimum}`;
+            const max = `s.${maximum}`;
+            // Dividing both sides by the larger magnitude when a range crosses zero
+            // avoids overflowing max - min for extreme finite DOUBLE values.
+            const scaled = `CASE
+        WHEN ${min} < 0 AND ${max} > 0 AND -${min} >= ${max}
+          THEN ((${value} / -${min}) + 1.0) / ((${max} / -${min}) + 1.0)
+        WHEN ${min} < 0 AND ${max} > 0
+          THEN ((${value} / ${max}) + (-${min} / ${max})) /
+            (1.0 + (-${min} / ${max}))
+        ELSE (${value} - ${min}) / (${max} - ${min})
+      END`;
+            await connection.run(`CREATE TEMP TABLE ${q(resultName)} AS
+         SELECT p.${q(prepared.rowIdColumn)},
+           list(${scaled} ORDER BY s.${dimension})::DOUBLE[${prepared.dimensions}]
+             AS ${q(normalized)}
+         FROM ${q(prepared.relation)} p CROSS JOIN ${q(statsName)} s
+         GROUP BY p.${q(prepared.rowIdColumn)}`);
+        }
+        const invalidResults = Number((await connection.runAndReadAll(`SELECT count(*) FROM ${q(resultName)}
+         WHERE ${q(normalized)} IS NULL
+           OR list_count(${q(normalized)}) != ${prepared.dimensions}
+           OR NOT list_bool_and(list_transform(${q(normalized)}, value -> isfinite(value)))
+           OR list_min(${q(normalized)}) < ${normalization === "rowL2" ? -1 : 0}
+           OR list_max(${q(normalized)}) > 1`)).getRowsJS()[0][0]);
+        if (invalidResults > 0) {
+            throw new Error(`normalizeVector() produced non-finite or out-of-range values for ${invalidResults} row${invalidResults === 1 ? "" : "s"}. Rescale the source values before normalizing.`);
+        }
+        await publishPreparedColumns(table, prepared, {
+            method: "normalizeVector()",
+            parameters: { column, newColumn, options },
+            result: {
+                relation: resultName,
+                rowIdColumn: prepared.rowIdColumn,
+            },
+            outputs: [{
+                    name: overwrite ? sourceColumn : newColumn,
+                    expression: `r.${q(normalized)}`,
+                    replace: overwrite ? sourceColumn : undefined,
+                }],
+        });
+    }
+    finally {
+        await connection.run(`DROP TABLE IF EXISTS ${q(resultName)}`);
+        await connection.run(`DROP TABLE IF EXISTS ${q(statsName)}`);
+        await prepared.cleanup();
+    }
+}

package/esm/methods/paths.d.ts

@@ -0,0 +1,12 @@
+import type SimpleTable from "../class/SimpleTable.js";
+import type { GraphId } from "../helpers/prepareGraphStarts.js";
+import { type GraphTemporalOptions } from "../helpers/prepareGraphTemporalSql.js";
+import type { GraphDirection } from "../helpers/prepareGraphTraversal.js";
+type PathsOptions = GraphTemporalOptions & {
+    direction?: GraphDirection;
+    outputTable?: string | boolean;
+    weight?: string;
+};
+export default function paths(simpleTable: SimpleTable, sourceColumn: string, targetColumn: string, edgeId: string, start: GraphId, end: GraphId, options?: PathsOptions): SimpleTable;
+export {};
+//# sourceMappingURL=paths.d.ts.map

package/esm/methods/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/methods/paths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AASvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAM1E,KAAK,YAAY,GAAG,oBAAoB,GAAG;IACzC,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,KAAK,CAC3B,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,YAAiB,GACzB,WAAW,CA+Gb"}