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

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

@@ -4,9 +4,6 @@
  * 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);
@@ -14,6 +11,10 @@
  *   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 async function hasGeometryColumn(table) {
     const types = await table.getTypes();

package/esm/helpers/initialUmapCoordinates.d.ts

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

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

@@ -0,0 +1,5 @@
+import umapRandom from "./umapRandom.js";
+export default function initialUmapCoordinates(count, seed) {
+    const random = umapRandom(seed);
+    return Float64Array.from({ length: count * 2 }, () => random() * 20 - 10);
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Inspect connectivity of an edge relation while transferring ids, not vectors.
+ * Isolated vertices count as one-point components. Invalid ids fail closed.
+ */
+export default 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/esm/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/esm/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/esm/helpers/mergeOptions.js

@@ -2,19 +2,6 @@
  * 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";
@@ -27,6 +14,30 @@
  * });
  * 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, options) {
     return {

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

@@ -0,0 +1,93 @@
+import umapRandom from "./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
+export default 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 = umapRandom(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/esm/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/esm/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/esm/helpers/parseValue.js

@@ -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) {
     if (Number.isNaN(value) || value === undefined || value === null) {

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

@@ -0,0 +1,86 @@
+import getGraphEdgeIdColumn from "./getGraphEdgeIdColumn.js";
+import getGraphWeightColumn from "./getGraphWeightColumn.js";
+import validateGraphRouteResultSchema from "./validateGraphRouteResultSchema.js";
+import prepareGraphStarts from "./prepareGraphStarts.js";
+import prepareGraphTraversal, { validateGraphStarts, } from "./prepareGraphTraversal.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+/** Prepares and validates the two scalar endpoints shared by route methods. */
+export 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 = prepareGraphStarts(start, method);
+    const preparedEnd = prepareGraphStarts(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. */
+export function validateGraphRouteInputs(schema, source, target, edgeId, endpoints, weight, method) {
+    const nodes = validateGraphStarts(schema, source, target, endpoints.values, method);
+    const edges = getGraphEdgeIdColumn(schema, edgeId, method);
+    const weightColumn = weight === undefined
+        ? undefined
+        : getGraphWeightColumn(schema, weight, method);
+    validateGraphRouteResultSchema(schema, method);
+    return {
+        distanceType: weightColumn?.distanceType ?? "BIGINT",
+        edgeIdType: edges.idType,
+        nodeIdType: nodes.idType,
+    };
+}
+/** Prepares the typed SQL expressions shared by edge-route enumeration. */
+export function prepareGraphRouteSql(input, schema, source, target, edgeId, endpoints, weight, method) {
+    validateGraphRouteResultSchema(schema, method);
+    const traversal = prepareGraphTraversal(input, schema, source, target, endpoints.values, method);
+    const edgeIdColumn = getGraphEdgeIdColumn(schema, edgeId, method);
+    const weightColumn = weight === undefined
+        ? undefined
+        : getGraphWeightColumn(schema, weight, method);
+    const distanceType = weightColumn?.distanceType ?? "BIGINT";
+    const q = quoteIdentifier;
+    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/esm/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/esm/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"}

package/esm/helpers/prepareGraphStarts.js

@@ -0,0 +1,68 @@
+/** Validates and snapshots scalar-or-array graph starting IDs. */
+export default function prepareGraphStarts(start, method, argument = "start", scalar = false) {
+    const starts = Array.isArray(start) ? [...start] : [start];
+    if (starts.length === 0) {
+        throw new TypeError(`${method} ${argument} must not be an empty array.`);
+    }
+    let family;
+    const values = [];
+    const numericValues = [];
+    const seen = new Set();
+    const duplicates = [];
+    for (const value of starts) {
+        const valueFamily = typeof value === "string"
+            ? "string"
+            : typeof value === "number" || typeof value === "bigint"
+                ? "numeric"
+                : undefined;
+        if (valueFamily === undefined) {
+            throw new TypeError(scalar
+                ? `${method} ${argument} must be a string or a whole number.`
+                : `${method} ${argument} must be a string, a whole number, or an array of those values.`);
+        }
+        if (family !== undefined && family !== valueFamily) {
+            throw new TypeError(`${method} ${argument} must not mix string and numeric IDs.`);
+        }
+        family = valueFamily;
+        let encoded;
+        if (typeof value === "number") {
+            if (!Number.isSafeInteger(value)) {
+                throw new TypeError(`${method} ${argument} contains ${value}, which is not a safe whole number. Use a bigint for exact integer IDs outside JavaScript's safe integer range.`);
+            }
+            encoded = BigInt(value).toString();
+            numericValues.push(BigInt(value));
+        }
+        else if (typeof value === "bigint") {
+            encoded = value.toString();
+            numericValues.push(value);
+        }
+        else {
+            encoded = value;
+        }
+        const key = `${valueFamily}:${encoded}`;
+        if (seen.has(key)) {
+            if (!duplicates.some((duplicate) => graphIdsEqual(duplicate, value))) {
+                duplicates.push(value);
+            }
+        }
+        else {
+            seen.add(key);
+            values.push(encoded);
+        }
+    }
+    if (duplicates.length > 0) {
+        throw new TypeError(`${method} ${argument} contains duplicate IDs: ${duplicates.map(formatGraphId).join(", ")}.`);
+    }
+    return { family: family, numericValues, values };
+}
+function graphIdsEqual(left, right) {
+    if (typeof left === "string" || typeof right === "string") {
+        return left === right;
+    }
+    return BigInt(left) === BigInt(right);
+}
+function formatGraphId(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    return typeof value === "bigint" ? `${value}n` : String(value);
+}

package/esm/helpers/prepareGraphTemporalSql.d.ts

@@ -0,0 +1,28 @@
+import type { TableSchema } from "./pendingOps.js";
+import type { GraphDirection } from "./prepareGraphTraversal.js";
+export type GraphTemporalOptions = {
+    endTimeColumn?: string;
+    minGapMs?: number;
+    startTimeColumn?: string;
+    strictOrdering?: boolean;
+};
+export type PreparedGraphTemporalOptions = {
+    endTimeColumn?: string;
+    gapMicroseconds: bigint;
+    startTimeColumn?: string;
+    strictOrdering: boolean;
+};
+export type PreparedGraphTemporalSql = {
+    endTimeColumn?: string;
+    eventSelections: (tableAlias?: string) => string[];
+    eventValidity: (tableAlias?: string) => string;
+    gapParameter: string;
+    gapUnit: "microsecond" | "nanosecond";
+    startTimeColumn?: string;
+    transition: (currentAlias: string, candidateAlias: string, direction: Exclude<GraphDirection, "both">, gapExpression: string) => string;
+};
+/** Validates chronological options before a graph operation is queued. */
+export declare function prepareGraphTemporalOptions(options: GraphTemporalOptions, direction: GraphDirection | undefined, method: string): PreparedGraphTemporalOptions | undefined;
+/** Prepares native-precision event and transition SQL from a queued schema. */
+export default function prepareGraphTemporalSql(schema: TableSchema, options: PreparedGraphTemporalOptions, method: string): PreparedGraphTemporalSql;
+//# sourceMappingURL=prepareGraphTemporalSql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepareGraphTemporalSql.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareGraphTemporalSql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGjE,MAAM,MAAM,oBAAoB,GAAG;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IACnD,aAAa,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,aAAa,GAAG,YAAY,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,CACV,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,EAC1C,aAAa,EAAE,MAAM,KAClB,MAAM,CAAC;CACb,CAAC;AAWF,0EAA0E;AAC1E,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,cAAc,GAAG,SAAS,EACrC,MAAM,EAAE,MAAM,GACb,4BAA4B,GAAG,SAAS,CAkE1C;AAED,+EAA+E;AAC/E,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,4BAA4B,EACrC,MAAM,EAAE,MAAM,GACb,wBAAwB,CAwE1B"}