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

package/script/helpers/graphRouteResultSelect.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = graphRouteResultSelect;
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+/** Joins ranked route steps to their original input rows for final output. */
+function graphRouteResultSelect(rankedRelation, input, edgeIdColumn, includeStart = false) {
+    const q = quoteIdentifier_js_1.default;
+    const routeStep = `${q("unnested")}.${q("route_step")}`;
+    const originalEdgeId = `${q("original")}.${q(edgeIdColumn.column)}`;
+    const edgeMatch = edgeIdColumn.family === "string"
+        ? `ENCODE(CAST(${originalEdgeId} AS VARCHAR)) =
+        ENCODE(${routeStep}.${q("edgeId")})`
+        : `CAST(${originalEdgeId} AS ${edgeIdColumn.idType}) =
+        ${routeStep}.${q("edgeId")}`;
+    return `SELECT ${includeStart ? `${q("ranked")}.${q("start")},\n      ` : ""}${q("ranked")}.${q("pathId")},
+      CAST(${q("unnested")}.${q("step")} AS BIGINT) AS ${q("step")},
+      ${routeStep}.${q("weight")} AS ${q("weight")},
+      ${routeStep}.${q("distance")} AS ${q("total")},
+      ${q("original")}.*
+    FROM ${rankedRelation} AS ${q("ranked")},
+      UNNEST(${q("ranked")}.${q("steps")}) WITH ORDINALITY AS ${q("unnested")}(${q("route_step")}, ${q("step")})
+    INNER JOIN ${input} AS ${q("original")}
+      ON ${edgeMatch}
+    ORDER BY ${includeStart ? `${q("ranked")}.${q("__start_key")}, ` : ""}${q("ranked")}.${q("pathId")}, ${q("unnested")}.${q("step")}`;
+}

package/script/helpers/hasGeometryColumn.d.ts

@@ -5,9 +5,6 @@ import type SimpleTable from "../class/SimpleTable.js";
  * Uses `getTypes()` to inspect column types and checks for any column
  * whose type normalizes to `"geometry"`.
  *
- * @param table - The SimpleTable instance to inspect.
- * @returns `true` if at least one geometry column exists, `false` otherwise.
- *
  * @example
  * ```ts
  * const hasGeo = await hasGeometryColumn(table);
@@ -15,6 +12,10 @@ import type SimpleTable from "../class/SimpleTable.js";
  *   console.log("This table contains geometry columns");
  * }
  * ```
+ *
+ * @param table - The SimpleTable instance to inspect.
+ *
+ * @returns `true` if at least one geometry column exists, `false` otherwise.
  */
 export default function hasGeometryColumn(table: SimpleTable): Promise<boolean>;
 //# sourceMappingURL=hasGeometryColumn.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"hasGeometryColumn.d.ts","sourceRoot":"","sources":["../../src/helpers/hasGeometryColumn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAA8B,iBAAiB,CAC7C,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,OAAO,CAAC,CAGlB"}
+{"version":3,"file":"hasGeometryColumn.d.ts","sourceRoot":"","sources":["../../src/helpers/hasGeometryColumn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAA8B,iBAAiB,CAC7C,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/script/helpers/hasGeometryColumn.js

@@ -7,9 +7,6 @@ exports.default = hasGeometryColumn;
  * Uses `getTypes()` to inspect column types and checks for any column
  * whose type normalizes to `"geometry"`.
  *
- * @param table - The SimpleTable instance to inspect.
- * @returns `true` if at least one geometry column exists, `false` otherwise.
- *
  * @example
  * ```ts
  * const hasGeo = await hasGeometryColumn(table);
@@ -17,6 +14,10 @@ exports.default = hasGeometryColumn;
  *   console.log("This table contains geometry columns");
  * }
  * ```
+ *
+ * @param table - The SimpleTable instance to inspect.
+ *
+ * @returns `true` if at least one geometry column exists, `false` otherwise.
  */
 async function hasGeometryColumn(table) {
     const types = await table.getTypes();

package/script/helpers/initialUmapCoordinates.d.ts

@@ -0,0 +1,2 @@
+export default function initialUmapCoordinates(count: number, seed: number): Float64Array<ArrayBuffer>;
+//# sourceMappingURL=initialUmapCoordinates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"initialUmapCoordinates.d.ts","sourceRoot":"","sources":["../../src/helpers/initialUmapCoordinates.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,UAAU,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,6BAGzE"}

package/script/helpers/initialUmapCoordinates.js

@@ -0,0 +1,11 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = initialUmapCoordinates;
+const umapRandom_js_1 = __importDefault(require("./umapRandom.js"));
+function initialUmapCoordinates(count, seed) {
+    const random = (0, umapRandom_js_1.default)(seed);
+    return Float64Array.from({ length: count * 2 }, () => random() * 20 - 10);
+}

package/script/helpers/inspectGraphConnectivity.d.ts

@@ -0,0 +1,10 @@
+import type { DuckDBConnection } from "@duckdb/node-api";
+/**
+ * Inspect connectivity of an edge relation while transferring ids, not vectors.
+ * Isolated vertices count as one-point components. Invalid ids fail closed.
+ */
+export default function inspectGraphConnectivity(connection: DuckDBConnection, edges: string, vertexCount: number): Promise<{
+    componentCount: number;
+    sizes: number[];
+}>;
+//# sourceMappingURL=inspectGraphConnectivity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inspectGraphConnectivity.d.ts","sourceRoot":"","sources":["../../src/helpers/inspectGraphConnectivity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;GAGG;AACH,wBAA8B,wBAAwB,CACpD,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAoDtD"}

package/script/helpers/inspectGraphConnectivity.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = inspectGraphConnectivity;
+/**
+ * Inspect connectivity of an edge relation while transferring ids, not vectors.
+ * Isolated vertices count as one-point components. Invalid ids fail closed.
+ */
+async function inspectGraphConnectivity(connection, edges, vertexCount) {
+    if (!Number.isSafeInteger(vertexCount) || vertexCount < 1 ||
+        vertexCount > 2147483647) {
+        throw new Error("Graph vertex count must fit a positive INTEGER vertex count.");
+    }
+    const parent = new Int32Array(vertexCount);
+    const sizes = new Int32Array(vertexCount).fill(1);
+    for (let vertex = 0; vertex < vertexCount; vertex++)
+        parent[vertex] = vertex;
+    const root = (vertex) => {
+        while (parent[vertex] !== vertex) {
+            parent[vertex] = parent[parent[vertex]];
+            vertex = parent[vertex];
+        }
+        return vertex;
+    };
+    const rows = await connection.stream(`SELECT source,target FROM ${edges}`);
+    while (true) {
+        const chunk = await rows.fetchChunk();
+        if (!chunk || chunk.rowCount === 0)
+            break;
+        const sources = chunk.getColumnVector(0);
+        const targets = chunk.getColumnVector(1);
+        for (let row = 0; row < chunk.rowCount; row++) {
+            const sourceValue = sources.getItem(row);
+            const targetValue = targets.getItem(row);
+            const source = Number(sourceValue);
+            const target = Number(targetValue);
+            if (sourceValue === null || targetValue === null ||
+                !Number.isSafeInteger(source) || source < 0 || source >= vertexCount ||
+                !Number.isSafeInteger(target) || target < 0 || target >= vertexCount) {
+                throw new Error("Graph edge contains an invalid vertex id.");
+            }
+            let sourceRoot = root(source), targetRoot = root(target);
+            if (sourceRoot === targetRoot)
+                continue;
+            if (sizes[sourceRoot] < sizes[targetRoot]) {
+                [sourceRoot, targetRoot] = [targetRoot, sourceRoot];
+            }
+            parent[targetRoot] = sourceRoot;
+            sizes[sourceRoot] += sizes[targetRoot];
+        }
+    }
+    const componentSizes = [];
+    for (let vertex = 0; vertex < vertexCount; vertex++) {
+        if (root(vertex) === vertex)
+            componentSizes.push(sizes[vertex]);
+    }
+    componentSizes.sort((a, b) => b - a);
+    return { componentCount: componentSizes.length, sizes: componentSizes };
+}

package/script/helpers/mergeOptions.d.ts

@@ -5,19 +5,6 @@ type DuckDBValue = NativeDuckDBValue;
  * Combines a table or database's logging defaults with query-specific options.
  * Use this helper with `queryDB()` when implementing an extension.
  *
- * @param simple - The logging defaults from a table or database.
- * @param simple.rowsToLog - The default number of rows to display.
- * @param simple.charsToLog - The default maximum characters to display per cell.
- * @param options - Query-specific settings, which take precedence over defaults.
- * @param options.table - The table name used for diagnostics, or `null`.
- * @param options.method - The calling method used for diagnostics, or `null`.
- * @param options.parameters - Arguments included in error diagnostics, or `null`.
- * @param options.rowsToLog - Overrides the default number of displayed rows.
- * @param options.returnData - Whether to return converted rows. Defaults to false.
- * @param options.values - DuckDB-native values bound to SQL placeholders, in order.
- * @param options.noClean - Whether to preserve the SQL text without cleaning it.
- * @returns The merged query options without modifying either argument.
- *
  * @example
  * ```ts
  * import { mergeOptions } from "@nshiab/simple-data-analysis-core/helpers";
@@ -30,6 +17,30 @@ type DuckDBValue = NativeDuckDBValue;
  * });
  * console.log(options.rowsToLog, options.returnData);
  * ```
+ *
+ * @param simple - The logging defaults from a table or database.
+ *
+ * @param simple.rowsToLog - The default number of rows to display.
+ *
+ * @param simple.charsToLog - The default maximum characters to display per cell.
+ *
+ * @param options - Query-specific settings, which take precedence over defaults.
+ *
+ * @param options.table - The table name used for diagnostics, or `null`.
+ *
+ * @param options.method - The calling method used for diagnostics, or `null`.
+ *
+ * @param options.parameters - Arguments included in error diagnostics, or `null`.
+ *
+ * @param options.rowsToLog - Overrides the default number of displayed rows.
+ *
+ * @param options.returnData - Whether to return converted rows. Defaults to false.
+ *
+ * @param options.values - DuckDB-native values bound to SQL placeholders, in order.
+ *
+ * @param options.noClean - Whether to preserve the SQL text without cleaning it.
+ *
+ * @returns The merged query options without modifying either argument.
  */
 export default function mergeOptions(simple: {
     rowsToLog: number;

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

@@ -1 +1 @@
-{"version":3,"file":"mergeOptions.d.ts","sourceRoot":"","sources":["../../src/helpers/mergeOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEzE,kGAAkG;AAClG,KAAK,WAAW,GAAG,iBAAiB,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAC7D,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAWA"}
+{"version":3,"file":"mergeOptions.d.ts","sourceRoot":"","sources":["../../src/helpers/mergeOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEzE,kGAAkG;AAClG,KAAK,WAAW,GAAG,iBAAiB,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAC7D,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACA;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAWA"}

package/script/helpers/mergeOptions.js

@@ -5,19 +5,6 @@ exports.default = mergeOptions;
  * Combines a table or database's logging defaults with query-specific options.
  * Use this helper with `queryDB()` when implementing an extension.
  *
- * @param simple - The logging defaults from a table or database.
- * @param simple.rowsToLog - The default number of rows to display.
- * @param simple.charsToLog - The default maximum characters to display per cell.
- * @param options - Query-specific settings, which take precedence over defaults.
- * @param options.table - The table name used for diagnostics, or `null`.
- * @param options.method - The calling method used for diagnostics, or `null`.
- * @param options.parameters - Arguments included in error diagnostics, or `null`.
- * @param options.rowsToLog - Overrides the default number of displayed rows.
- * @param options.returnData - Whether to return converted rows. Defaults to false.
- * @param options.values - DuckDB-native values bound to SQL placeholders, in order.
- * @param options.noClean - Whether to preserve the SQL text without cleaning it.
- * @returns The merged query options without modifying either argument.
- *
  * @example
  * ```ts
  * import { mergeOptions } from "@nshiab/simple-data-analysis-core/helpers";
@@ -30,6 +17,30 @@ exports.default = mergeOptions;
  * });
  * console.log(options.rowsToLog, options.returnData);
  * ```
+ *
+ * @param simple - The logging defaults from a table or database.
+ *
+ * @param simple.rowsToLog - The default number of rows to display.
+ *
+ * @param simple.charsToLog - The default maximum characters to display per cell.
+ *
+ * @param options - Query-specific settings, which take precedence over defaults.
+ *
+ * @param options.table - The table name used for diagnostics, or `null`.
+ *
+ * @param options.method - The calling method used for diagnostics, or `null`.
+ *
+ * @param options.parameters - Arguments included in error diagnostics, or `null`.
+ *
+ * @param options.rowsToLog - Overrides the default number of displayed rows.
+ *
+ * @param options.returnData - Whether to return converted rows. Defaults to false.
+ *
+ * @param options.values - DuckDB-native values bound to SQL placeholders, in order.
+ *
+ * @param options.noClean - Whether to preserve the SQL text without cleaning it.
+ *
+ * @returns The merged query options without modifying either argument.
  */
 function mergeOptions(simple, options) {
     return {

package/script/helpers/optimizeUmapLayout.d.ts

@@ -0,0 +1,7 @@
+import type prepareUmapLayoutOptions from "./prepareUmapLayoutOptions.js";
+export default function optimizeUmapLayout(graph: {
+    source: Uint32Array;
+    target: Uint32Array;
+    weight: Float64Array;
+}, initial: Float64Array, options: ReturnType<typeof prepareUmapLayoutOptions>): Float64Array;
+//# sourceMappingURL=optimizeUmapLayout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"optimizeUmapLayout.d.ts","sourceRoot":"","sources":["../../src/helpers/optimizeUmapLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,wBAAwB,MAAM,+BAA+B,CAAC;AAS1E,MAAM,CAAC,OAAO,UAAU,kBAAkB,CACxC,KAAK,EAAE;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,EACzE,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,GACnD,YAAY,CA2Fd"}

package/script/helpers/optimizeUmapLayout.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = optimizeUmapLayout;
+const umapRandom_js_1 = __importDefault(require("./umapRandom.js"));
+// Internal interface. Graph entries are directed, in a stable order; the fuzzy
+// union graph supplies both orientations. Coordinates are interleaved x,y.
+// Inputs are borrowed read-only. State is O(edges + vertices), never O(n²).
+// Implements reference Euclidean UMAP SGD: scheduled attractive edges, sampled
+// repulsion, clipped gradients, symmetric attractive updates, linear decay.
+// Algorithm: https://umap-learn.readthedocs.io/en/latest/how_umap_works.html
+function optimizeUmapLayout(graph, initial, options) {
+    const { epochs, seed, learningRate, negativeSamples, curve: [a, b] } = options;
+    const count = initial.length / 2;
+    if (!Number.isInteger(count) || count < 3 || count > 0xffffffff) {
+        throw new Error("Expected interleaved coordinates for at least three vertices.");
+    }
+    for (const value of initial) {
+        if (!Number.isFinite(value)) {
+            throw new Error("Initial coordinates must be finite.");
+        }
+    }
+    const { source, target, weight } = graph;
+    if (!weight.length || source.length !== weight.length ||
+        target.length !== weight.length)
+        throw new Error("Invalid graph column lengths.");
+    let maximum = 0;
+    for (let edge = 0; edge < weight.length; edge++) {
+        if (source[edge] >= count || target[edge] >= count ||
+            source[edge] === target[edge])
+            throw new Error("Graph contains an invalid vertex or self edge.");
+        if (!Number.isFinite(weight[edge]) || weight[edge] < 0 || weight[edge] > 1)
+            throw new Error("Graph weights must be between zero and one.");
+        maximum = Math.max(maximum, weight[edge]);
+    }
+    if (!maximum)
+        throw new Error("Graph must contain a positive edge.");
+    const period = new Float64Array(weight.length);
+    const nextPositive = new Float64Array(weight.length);
+    const nextNegative = new Float64Array(weight.length);
+    // Reference pruning uses 500 when explicitly requesting at most ten epochs.
+    const threshold = maximum / (epochs > 10 ? epochs : 500);
+    for (let edge = 0; edge < weight.length; edge++) {
+        period[edge] = weight[edge] > 0 && weight[edge] >= threshold
+            ? epochs / ((weight[edge] / maximum) * epochs)
+            : Infinity;
+        nextPositive[edge] = period[edge];
+        nextNegative[edge] = period[edge] / negativeSamples;
+    }
+    const coordinates = initial.slice();
+    const random = (0, umapRandom_js_1.default)(seed ^ 0x7f4a7c15);
+    const clip = (gradient) => Math.max(-4, Math.min(4, gradient));
+    let alpha = learningRate;
+    for (let epoch = 0; epoch < epochs; epoch++) {
+        for (let edge = 0; edge < weight.length; edge++) {
+            if (nextPositive[edge] > epoch)
+                continue;
+            const u = source[edge] * 2, v = target[edge] * 2;
+            let dx = coordinates[u] - coordinates[v], dy = coordinates[u + 1] - coordinates[v + 1];
+            let squared = dx * dx + dy * dy;
+            if (squared > 0) {
+                const attraction = -2 * a * b * Math.pow(squared, b - 1) /
+                    (1 + a * Math.pow(squared, b));
+                const gx = clip(attraction * dx) * alpha, gy = clip(attraction * dy) * alpha;
+                coordinates[u] += gx;
+                coordinates[u + 1] += gy;
+                coordinates[v] -= gx;
+                coordinates[v + 1] -= gy;
+            }
+            nextPositive[edge] += period[edge];
+            const negativePeriod = period[edge] / negativeSamples;
+            const draws = Math.floor((epoch - nextNegative[edge]) / negativePeriod);
+            for (let draw = 0; draw < draws; draw++) {
+                const other = Math.floor(random() * count) * 2;
+                dx = coordinates[u] - coordinates[other];
+                dy = coordinates[u + 1] - coordinates[other + 1];
+                squared = dx * dx + dy * dy;
+                // Coincident points get zero repulsive gradient, as in current Python
+                // UMAP; this intentionally differs from UMAP-JS's constant +4 fallback.
+                if (squared > 0) {
+                    const repulsion = 2 * b /
+                        ((0.001 + squared) * (1 + a * Math.pow(squared, b)));
+                    coordinates[u] += clip(repulsion * dx) * alpha;
+                    coordinates[u + 1] += clip(repulsion * dy) * alpha;
+                }
+            }
+            nextNegative[edge] += draws * negativePeriod;
+        }
+        alpha = learningRate * (1 - epoch / epochs);
+    }
+    for (const value of coordinates) {
+        if (!Number.isFinite(value)) {
+            throw new Error("UMAP optimization produced a non-finite coordinate.");
+        }
+    }
+    return coordinates;
+}

package/script/helpers/parseValue.d.ts

@@ -3,16 +3,18 @@
  * quotes escaped, dates become quoted ISO strings, and null, undefined, or NaN
  * become `"NULL"`. Numbers and booleans are returned unchanged.
  *
- * @param value - A string, number, boolean, Date, null, or undefined.
- * @returns A SQL literal, or the original number or boolean.
- * @throws If the value has an unsupported type.
- *
  * @example
  * ```ts
  * import { parseValue } from "@nshiab/simple-data-analysis-core/helpers";
  * console.log(parseValue("O'Brien")); // "'O''Brien'"
  * console.log(parseValue(null)); // "NULL"
  * ```
+ *
+ * @param value - A string, number, boolean, Date, null, or undefined.
+ *
+ * @returns A SQL literal, or the original number or boolean.
+ *
+ * @throws If the value has an unsupported type.
  */
 export default function parseValue(value: unknown): string | boolean | number;
 //# sourceMappingURL=parseValue.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"parseValue.d.ts","sourceRoot":"","sources":["../../src/helpers/parseValue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAc5E"}
+{"version":3,"file":"parseValue.d.ts","sourceRoot":"","sources":["../../src/helpers/parseValue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAc5E"}

package/script/helpers/parseValue.js

@@ -6,16 +6,18 @@ exports.default = parseValue;
  * quotes escaped, dates become quoted ISO strings, and null, undefined, or NaN
  * become `"NULL"`. Numbers and booleans are returned unchanged.
  *
- * @param value - A string, number, boolean, Date, null, or undefined.
- * @returns A SQL literal, or the original number or boolean.
- * @throws If the value has an unsupported type.
- *
  * @example
  * ```ts
  * import { parseValue } from "@nshiab/simple-data-analysis-core/helpers";
  * console.log(parseValue("O'Brien")); // "'O''Brien'"
  * console.log(parseValue(null)); // "NULL"
  * ```
+ *
+ * @param value - A string, number, boolean, Date, null, or undefined.
+ *
+ * @returns A SQL literal, or the original number or boolean.
+ *
+ * @throws If the value has an unsupported type.
  */
 function parseValue(value) {
     if (Number.isNaN(value) || value === undefined || value === null) {

package/script/helpers/prepareGraphRouteSql.d.ts

@@ -0,0 +1,31 @@
+import type { TableSchema } from "./pendingOps.js";
+import { type GraphId, type PreparedGraphStarts } from "./prepareGraphStarts.js";
+export type PreparedGraphRouteEndpoints = {
+    end: PreparedGraphStarts;
+    start: PreparedGraphStarts;
+    values: PreparedGraphStarts;
+};
+/** Prepares and validates the two scalar endpoints shared by route methods. */
+export declare function prepareGraphRouteEndpoints(start: GraphId, end: GraphId, method: string): PreparedGraphRouteEndpoints;
+/** Validates the columns shared by edge-route methods from queued schema data. */
+export declare function validateGraphRouteInputs(schema: TableSchema, source: string, target: string, edgeId: string, endpoints: PreparedGraphRouteEndpoints, weight: string | undefined, method: string): {
+    distanceType: string;
+    edgeIdType: string;
+    nodeIdType: string;
+};
+/** Prepares the typed SQL expressions shared by edge-route enumeration. */
+export declare function prepareGraphRouteSql(input: string, schema: TableSchema, source: string, target: string, edgeId: string, endpoints: PreparedGraphRouteEndpoints, weight: string | undefined, method: string): {
+    distanceType: string;
+    edgeIdColumn: import("./getGraphEdgeIdColumn.js").GraphEdgeIdColumn;
+    edgeKey: string;
+    edgeWeight: string;
+    endpointValue: string;
+    keyType: string;
+    stepType: string;
+    input: string;
+    schema: TableSchema;
+    traversal: import("./prepareGraphTraversal.js").PreparedGraphTraversal;
+    typedEdgeId: string;
+    weightType: string | undefined;
+};
+//# sourceMappingURL=prepareGraphRouteSql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepareGraphRouteSql.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareGraphRouteSql.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAA2B,EACzB,KAAK,OAAO,EACZ,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AAMjC,MAAM,MAAM,2BAA2B,GAAG;IACxC,GAAG,EAAE,mBAAmB,CAAC;IACzB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,MAAM,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAEF,+EAA+E;AAC/E,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,GACb,2BAA2B,CA+B7B;AAED,kFAAkF;AAClF,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,2BAA2B,EACtC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM;;;;EAmBf;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,2BAA2B,EACtC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM;;;;;;;;;;;;;EAkDf"}

package/script/helpers/prepareGraphRouteSql.js

@@ -0,0 +1,127 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareGraphRouteEndpoints = prepareGraphRouteEndpoints;
+exports.validateGraphRouteInputs = validateGraphRouteInputs;
+exports.prepareGraphRouteSql = prepareGraphRouteSql;
+const getGraphEdgeIdColumn_js_1 = __importDefault(require("./getGraphEdgeIdColumn.js"));
+const getGraphWeightColumn_js_1 = __importDefault(require("./getGraphWeightColumn.js"));
+const validateGraphRouteResultSchema_js_1 = __importDefault(require("./validateGraphRouteResultSchema.js"));
+const prepareGraphStarts_js_1 = __importDefault(require("./prepareGraphStarts.js"));
+const prepareGraphTraversal_js_1 = __importStar(require("./prepareGraphTraversal.js"));
+const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
+/** Prepares and validates the two scalar endpoints shared by route methods. */
+function prepareGraphRouteEndpoints(start, end, method) {
+    if (Array.isArray(start)) {
+        throw new TypeError(`${method} start must be one node ID.`);
+    }
+    if (Array.isArray(end)) {
+        throw new TypeError(`${method} end must be one node ID.`);
+    }
+    const preparedStart = (0, prepareGraphStarts_js_1.default)(start, method);
+    const preparedEnd = (0, prepareGraphStarts_js_1.default)(end, method);
+    if (preparedStart.family !== preparedEnd.family) {
+        throw new TypeError(`${method} start and end must both be string IDs or both be numeric IDs.`);
+    }
+    if (preparedStart.values[0] === preparedEnd.values[0]) {
+        throw new TypeError(`${method} start and end must be different. Use distances() to measure return routes or findCycles() to find loops.`);
+    }
+    return {
+        start: preparedStart,
+        end: preparedEnd,
+        values: {
+            family: preparedStart.family,
+            numericValues: [
+                ...preparedStart.numericValues,
+                ...preparedEnd.numericValues,
+            ],
+            values: [preparedStart.values[0], preparedEnd.values[0]],
+        },
+    };
+}
+/** Validates the columns shared by edge-route methods from queued schema data. */
+function validateGraphRouteInputs(schema, source, target, edgeId, endpoints, weight, method) {
+    const nodes = (0, prepareGraphTraversal_js_1.validateGraphStarts)(schema, source, target, endpoints.values, method);
+    const edges = (0, getGraphEdgeIdColumn_js_1.default)(schema, edgeId, method);
+    const weightColumn = weight === undefined
+        ? undefined
+        : (0, getGraphWeightColumn_js_1.default)(schema, weight, method);
+    (0, validateGraphRouteResultSchema_js_1.default)(schema, method);
+    return {
+        distanceType: weightColumn?.distanceType ?? "BIGINT",
+        edgeIdType: edges.idType,
+        nodeIdType: nodes.idType,
+    };
+}
+/** Prepares the typed SQL expressions shared by edge-route enumeration. */
+function prepareGraphRouteSql(input, schema, source, target, edgeId, endpoints, weight, method) {
+    (0, validateGraphRouteResultSchema_js_1.default)(schema, method);
+    const traversal = (0, prepareGraphTraversal_js_1.default)(input, schema, source, target, endpoints.values, method);
+    const edgeIdColumn = (0, getGraphEdgeIdColumn_js_1.default)(schema, edgeId, method);
+    const weightColumn = weight === undefined
+        ? undefined
+        : (0, getGraphWeightColumn_js_1.default)(schema, weight, method);
+    const distanceType = weightColumn?.distanceType ?? "BIGINT";
+    const q = quoteIdentifier_js_1.default;
+    const edgeIdReference = `${q("edges")}.${q(edgeIdColumn.column)}`;
+    const typedEdgeId = `CAST(${edgeIdReference} AS ${edgeIdColumn.idType})`;
+    const edgeKey = edgeIdColumn.family === "string"
+        ? `ENCODE(${typedEdgeId})`
+        : typedEdgeId;
+    const edgeWeight = weightColumn === undefined
+        ? `CAST(1 AS ${distanceType})`
+        : `CAST(${q("edges")}.${q(weightColumn.column)} AS ${distanceType})`;
+    const keyType = edgeIdColumn.family === "string"
+        ? "BLOB"
+        : edgeIdColumn.idType;
+    const stepType = `STRUCT(${q("edgeId")} ${edgeIdColumn.idType}, ${q("source")} ${traversal.endpoints.idType}, ${q("target")} ${traversal.endpoints.idType}, ${q("weight")} ${distanceType}, ${q("distance")} ${distanceType})`;
+    return {
+        distanceType,
+        edgeIdColumn,
+        edgeKey,
+        edgeWeight,
+        endpointValue: `TRY_CAST(? AS ${traversal.endpoints.idType})`,
+        keyType,
+        stepType,
+        input,
+        schema,
+        traversal,
+        typedEdgeId,
+        weightType: weightColumn?.type,
+    };
+}

package/script/helpers/prepareGraphStarts.d.ts

@@ -0,0 +1,9 @@
+export type GraphId = string | number | bigint;
+export type PreparedGraphStarts = {
+    family: "string" | "numeric";
+    numericValues: bigint[];
+    values: string[];
+};
+/** Validates and snapshots scalar-or-array graph starting IDs. */
+export default function prepareGraphStarts(start: GraphId | GraphId[], method: string, argument?: string, scalar?: boolean): PreparedGraphStarts;
+//# sourceMappingURL=prepareGraphStarts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepareGraphStarts.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareGraphStarts.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/C,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,kEAAkE;AAClE,MAAM,CAAC,OAAO,UAAU,kBAAkB,CACxC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,EAC1B,MAAM,EAAE,MAAM,EACd,QAAQ,SAAU,EAClB,MAAM,UAAQ,GACb,mBAAmB,CAoErB"}