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

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

package/esm/helpers/prepareGraphTemporalSql.js

@@ -0,0 +1,154 @@
+import foldIdentifier from "./foldIdentifier.js";
+import quoteIdentifier from "./quoteIdentifier.js";
+const temporalTypes = new Set([
+    "DATE",
+    "TIMESTAMP",
+    "TIMESTAMP_S",
+    "TIMESTAMP_MS",
+    "TIMESTAMP_NS",
+    "TIMESTAMP WITH TIME ZONE",
+]);
+/** Validates chronological options before a graph operation is queued. */
+export function prepareGraphTemporalOptions(options, direction, method) {
+    const startTimeColumn = options.startTimeColumn;
+    const endTimeColumn = options.endTimeColumn;
+    if (startTimeColumn !== undefined && typeof startTimeColumn !== "string") {
+        throw new TypeError(`${method} options.startTimeColumn must be a string.`);
+    }
+    if (endTimeColumn !== undefined && typeof endTimeColumn !== "string") {
+        throw new TypeError(`${method} options.endTimeColumn must be a string.`);
+    }
+    if (options.strictOrdering !== undefined &&
+        typeof options.strictOrdering !== "boolean") {
+        throw new TypeError(`${method} options.strictOrdering must be a boolean.`);
+    }
+    if (options.minGapMs !== undefined && typeof options.minGapMs !== "number") {
+        throw new TypeError(`${method} options.minGapMs must be a number.`);
+    }
+    const hasTimeColumn = startTimeColumn !== undefined ||
+        endTimeColumn !== undefined;
+    const hasTemporalSetting = options.minGapMs !== undefined ||
+        options.strictOrdering !== undefined;
+    if (!hasTimeColumn) {
+        if (hasTemporalSetting) {
+            throw new TypeError(`${method} options.minGapMs and options.strictOrdering require options.startTimeColumn or options.endTimeColumn.`);
+        }
+        return undefined;
+    }
+    if (direction === "both") {
+        throw new TypeError(`${method} options.direction cannot be "both" when chronological options are supplied.`);
+    }
+    const minGapMs = options.minGapMs ?? 0;
+    if (!Number.isFinite(minGapMs) || minGapMs < 0 || !Number.isInteger(minGapMs)) {
+        throw new TypeError(`${method} options.minGapMs must be a finite, non-negative integer.`);
+    }
+    if (minGapMs > Number.MAX_SAFE_INTEGER) {
+        throw new TypeError(`${method} options.minGapMs must not exceed Number.MAX_SAFE_INTEGER.`);
+    }
+    const gapMicroseconds = BigInt(minGapMs) * 1000n;
+    return {
+        endTimeColumn,
+        gapMicroseconds,
+        startTimeColumn,
+        strictOrdering: options.strictOrdering ?? true,
+    };
+}
+/** Prepares native-precision event and transition SQL from a queued schema. */
+export default function prepareGraphTemporalSql(schema, options, method) {
+    const start = options.startTimeColumn === undefined
+        ? undefined
+        : getTemporalColumn(schema, options.startTimeColumn, method);
+    const end = options.endTimeColumn === undefined
+        ? undefined
+        : getTemporalColumn(schema, options.endTimeColumn, method);
+    if (start?.zoned !== undefined && end?.zoned !== undefined) {
+        if (start.zoned !== end.zoned) {
+            throw new TypeError(`${method} cannot mix time-zone-aware and time-zone-naive chronological columns. Convert both columns to the same timestamp domain first.`);
+        }
+    }
+    const startColumn = start?.column ?? end.column;
+    const endColumn = end?.column ?? start.column;
+    const startType = start?.type ?? end.type;
+    const endType = end?.type ?? start.type;
+    const gapUnit = start?.type === "TIMESTAMP_NS" ||
+        end?.type === "TIMESTAMP_NS"
+        ? "nanosecond"
+        : "microsecond";
+    const gap = gapUnit === "nanosecond"
+        ? options.gapMicroseconds * 1000n
+        : options.gapMicroseconds;
+    const q = quoteIdentifier;
+    const reference = (alias, column) => `${alias === undefined ? "" : `${q(alias)}.`}${q(column)}`;
+    const eventReference = (alias, name) => `${alias === undefined ? "" : `${q(alias)}.`}${q(name)}`;
+    return {
+        startTimeColumn: start?.column,
+        endTimeColumn: end?.column,
+        gapParameter: gap.toString(),
+        gapUnit,
+        eventSelections: (alias) => [
+            `row_number() OVER () AS ${q("__event_id")}`,
+            `${reference(alias, startColumn)} AS ${q("__event_start")}`,
+            `${reference(alias, endColumn)} AS ${q("__event_end")}`,
+        ],
+        eventValidity: (alias) => {
+            const eventStart = eventReference(alias, "__event_start");
+            const eventEnd = eventReference(alias, "__event_end");
+            return `CASE
+        WHEN ${eventStart} IS NULL OR ${eventEnd} IS NULL THEN false
+        WHEN NOT isfinite(${eventStart}) OR NOT isfinite(${eventEnd}) THEN false
+        ELSE ${temporalUnits(eventEnd, endType, gapUnit)} >= ${temporalUnits(eventStart, startType, gapUnit)}
+      END`;
+        },
+        transition: (currentAlias, candidateAlias, direction, gapExpression) => {
+            const currentStart = eventReference(currentAlias, "__event_start");
+            const currentEnd = eventReference(currentAlias, "__event_end");
+            const candidateStart = eventReference(candidateAlias, "__event_start");
+            const candidateEnd = eventReference(candidateAlias, "__event_end");
+            const earlierEnd = direction === "outgoing" ? currentEnd : candidateEnd;
+            const laterStart = direction === "outgoing"
+                ? candidateStart
+                : currentStart;
+            const elapsed = `${temporalUnits(laterStart, startType, gapUnit)} - ${temporalUnits(earlierEnd, endType, gapUnit)}`;
+            const ordering = options.strictOrdering
+                ? `
+        AND ${elapsed} > 0`
+                : "";
+            return `${elapsed} >= ${gapExpression}${ordering}`;
+        },
+    };
+}
+function temporalUnits(expression, type, unit) {
+    // Widen before scaling/subtraction to preserve precision and the DATE range.
+    const scale = unit === "nanosecond" ? 1000n : 1n;
+    if (type === "DATE") {
+        return `(CAST(date_diff('day', DATE '1970-01-01', ${expression}) AS HUGEINT) * ${86400000000n * scale})`;
+    }
+    if (type === "TIMESTAMP_NS") {
+        return `CAST(epoch_ns(${expression}) AS HUGEINT)`;
+    }
+    return `(CAST(epoch_us(${expression}) AS HUGEINT) * ${scale})`;
+}
+function getTemporalColumn(schema, requested, method) {
+    const folded = foldIdentifier(requested);
+    const column = Object.keys(schema).find((name) => foldIdentifier(name) === folded);
+    if (column === undefined) {
+        throw new Error(`${method} the column ${quoteIdentifier(requested)} does not exist. Check for typos, or load the data first.`);
+    }
+    const type = normalizeTemporalType(schema[column]);
+    if (!temporalTypes.has(type)) {
+        throw new TypeError(`${method} requires DATE or TIMESTAMP chronological columns, but column ${quoteIdentifier(column)} has type ${schema[column].toUpperCase()}.`);
+    }
+    return {
+        column,
+        type,
+        zoned: type === "TIMESTAMP WITH TIME ZONE",
+    };
+}
+function normalizeTemporalType(type) {
+    const normalized = type.toUpperCase();
+    if (normalized === "TIMESTAMPTZ")
+        return "TIMESTAMP WITH TIME ZONE";
+    if (normalized === "TIMESTAMP WITHOUT TIME ZONE")
+        return "TIMESTAMP";
+    return normalized;
+}

package/esm/helpers/prepareGraphTraversal.d.ts

@@ -0,0 +1,19 @@
+import { type GraphEndpointColumns } from "./getGraphEndpointColumns.js";
+import type { TableSchema } from "./pendingOps.js";
+import type { PreparedGraphStarts } from "./prepareGraphStarts.js";
+export type GraphDirection = "outgoing" | "incoming" | "both";
+export type PreparedGraphTraversal = {
+    edges: (direction: GraphDirection, selections?: string[]) => string;
+    endpoints: GraphEndpointColumns;
+    key: (expression: string) => string;
+    relationNames: (names: string[]) => Record<string, string>;
+    startValues: string;
+};
+export type PreparedGraphSql = Omit<PreparedGraphTraversal, "startValues">;
+/** Prepares exact-ID SQL shared by graph traversal methods. */
+export default function prepareGraphTraversal(input: string, schema: TableSchema, source: string, target: string, starts: PreparedGraphStarts, method: string, argument?: string): PreparedGraphTraversal;
+/** Prepares exact-ID edge SQL for graph methods without starting nodes. */
+export declare function prepareGraphSql(input: string, schema: TableSchema, source: string, target: string, method: string): PreparedGraphSql;
+/** Validates supplied starts against resolved endpoint ID types. */
+export declare function validateGraphStarts(schema: TableSchema, source: string, target: string, starts: PreparedGraphStarts, method: string, argument?: string): GraphEndpointColumns;
+//# sourceMappingURL=prepareGraphTraversal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prepareGraphTraversal.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareGraphTraversal.ts"],"names":[],"mappings":"AACA,OAAgC,EAC9B,KAAK,oBAAoB,EAC1B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGnE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAE9D,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,EAAE,CAAC,SAAS,EAAE,cAAc,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;IACpE,SAAS,EAAE,oBAAoB,CAAC;IAChC,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,sBAAsB,EAAE,aAAa,CAAC,CAAC;AAE3E,+DAA+D;AAC/D,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAC3C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,SAAU,GACjB,sBAAsB,CAcxB;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,gBAAgB,CAKlB;AAwCD,oEAAoE;AACpE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,SAAU,GACjB,oBAAoB,CAyBtB"}