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

package/script/helpers/graphRouteResultSelect.d.ts

@@ -0,0 +1,4 @@
+import type { GraphEdgeIdColumn } from "./getGraphEdgeIdColumn.js";
+/** Joins ranked route steps to their original input rows for final output. */
+export default function graphRouteResultSelect(rankedRelation: string, input: string, edgeIdColumn: GraphEdgeIdColumn, includeStart?: boolean): string;
+//# sourceMappingURL=graphRouteResultSelect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graphRouteResultSelect.d.ts","sourceRoot":"","sources":["../../src/helpers/graphRouteResultSelect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,8EAA8E;AAC9E,MAAM,CAAC,OAAO,UAAU,sBAAsB,CAC5C,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,iBAAiB,EAC/B,YAAY,UAAQ,GACnB,MAAM,CAyBR"}

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

package/script/helpers/prepareGraphStarts.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = prepareGraphStarts;
+/** Validates and snapshots scalar-or-array graph starting IDs. */
+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/script/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/script/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"}