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

package/esm/methods/connectedComponents.js

@@ -0,0 +1,147 @@
+import buildChronologicalGraphComponentsSql from "../helpers/buildChronologicalGraphComponentsSql.js";
+import buildWeakGraphComponentsSql from "../helpers/buildWeakGraphComponentsSql.js";
+import getGraphEndpointColumns from "../helpers/getGraphEndpointColumns.js";
+import prepareGraphTemporalSql, { prepareGraphTemporalOptions, } from "../helpers/prepareGraphTemporalSql.js";
+import { prepareGraphSql } from "../helpers/prepareGraphTraversal.js";
+import queueGraphResult from "../helpers/queueGraphResult.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import validateGraphTemporalEvents from "../helpers/validateGraphTemporalEvents.js";
+export default function connectedComponents(simpleTable, sourceColumn, targetColumn, options = {}) {
+    if (typeof sourceColumn !== "string") {
+        throw new TypeError("connectedComponents() sourceColumn must be a string.");
+    }
+    if (typeof targetColumn !== "string") {
+        throw new TypeError("connectedComponents() targetColumn must be a string.");
+    }
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("connectedComponents() options must be an object.");
+    }
+    if (options.mode !== undefined &&
+        !["weak", "strong"].includes(options.mode)) {
+        throw new TypeError('connectedComponents() options.mode must be "weak" or "strong".');
+    }
+    if (options.outputTable !== undefined &&
+        typeof options.outputTable !== "string" &&
+        typeof options.outputTable !== "boolean") {
+        throw new TypeError("connectedComponents() options.outputTable must be a string or boolean.");
+    }
+    const temporalOptions = prepareGraphTemporalOptions(options, undefined, "connectedComponents()");
+    if (temporalOptions !== undefined && options.mode !== "strong") {
+        throw new TypeError('connectedComponents() chronological options require options.mode to be explicitly set to "strong".');
+    }
+    options = structuredClone(options);
+    const mode = options.mode ?? "weak";
+    const parameters = { sourceColumn, targetColumn, options };
+    return queueGraphResult(simpleTable, {
+        method: "connectedComponents()",
+        parameters,
+        outputTable: options.outputTable,
+        preflight: temporalOptions === undefined
+            ? undefined
+            : (input) => validateGraphTemporalEvents(input, temporalOptions, "connectedComponents()", parameters),
+        values: (schema) => {
+            const temporal = validateInputs(schema, sourceColumn, targetColumn, temporalOptions).temporal;
+            return temporal === undefined ? [] : [temporal.gapParameter];
+        },
+        buildSelect: (input, schema) => connectedComponentsSelect(input, schema, sourceColumn, targetColumn, mode, temporalOptions),
+        outputSchema: (schema) => ({
+            componentId: "BIGINT",
+            node: validateInputs(schema, sourceColumn, targetColumn, temporalOptions).endpoints.idType,
+        }),
+    });
+}
+function validateEndpoints(schema, source, target) {
+    return getGraphEndpointColumns(schema, source, target, "connectedComponents()");
+}
+function validateInputs(schema, source, target, temporalOptions) {
+    const endpoints = validateEndpoints(schema, source, target);
+    const temporal = temporalOptions === undefined
+        ? undefined
+        : prepareGraphTemporalSql(schema, temporalOptions, "connectedComponents()");
+    return { endpoints, temporal };
+}
+function connectedComponentsSelect(input, schema, source, target, mode, temporalOptions) {
+    const prepared = prepareGraphSql(input, schema, source, target, "connectedComponents()");
+    if (temporalOptions !== undefined) {
+        return buildChronologicalGraphComponentsSql(prepared, prepareGraphTemporalSql(schema, temporalOptions, "connectedComponents()"));
+    }
+    const relationNames = mode === "weak"
+        ? [
+            "graph_edges",
+            "graph_nodes",
+            "graph_component_labels",
+            "graph_component_roots",
+        ]
+        : [
+            "graph_edges",
+            "graph_nodes",
+            "graph_reachable",
+            "graph_component_members",
+            "graph_component_roots",
+        ];
+    const relations = prepared.relationNames(relationNames);
+    const edges = relations.graph_edges;
+    const nodes = relations.graph_nodes;
+    const roots = relations.graph_component_roots;
+    const q = quoteIdentifier;
+    const common = `${edges} AS (
+      ${prepared.edges(mode === "weak" ? "both" : "outgoing")}
+    ), ${nodes} AS (
+      SELECT ${q("__from")} AS ${q("node")},
+        ${q("__from_key")} AS ${q("__key")}
+      FROM ${edges}
+      UNION
+      SELECT ${q("__to")} AS ${q("node")},
+        ${q("__to_key")} AS ${q("__key")}
+      FROM ${edges}
+    )`;
+    if (mode === "weak") {
+        const labels = relations.graph_component_labels;
+        return `WITH RECURSIVE ${common}, ${buildWeakGraphComponentsSql(edges, nodes, labels, roots)}
+    SELECT ${q("roots")}.${q("componentId")}, ${q("labels")}.${q("node")}
+    FROM ${labels} AS ${q("labels")}
+    INNER JOIN ${roots} AS ${q("roots")}
+      ON ${q("labels")}.${q("__root_key")} =
+        ${q("roots")}.${q("__root_key")}
+    ORDER BY ${q("labels")}.${q("__node_key")}`;
+    }
+    const reachable = relations.graph_reachable;
+    const members = relations.graph_component_members;
+    return `WITH RECURSIVE ${common}, ${reachable}(
+      ${q("__start_key")}, ${q("__node_key")}
+    ) AS (
+      SELECT ${q("__key")}, ${q("__key")} FROM ${nodes}
+      UNION
+      SELECT ${q("reached")}.${q("__start_key")},
+        ${q("edges")}.${q("__to_key")}
+      FROM ${reachable} AS ${q("reached")}
+      INNER JOIN ${edges} AS ${q("edges")}
+        ON ${q("reached")}.${q("__node_key")} =
+          ${q("edges")}.${q("__from_key")}
+    ), ${members} AS (
+      SELECT ${q("nodes")}.${q("node")}, ${q("nodes")}.${q("__key")},
+        MIN(${q("forward")}.${q("__start_key")}) AS ${q("__root_key")}
+      FROM ${nodes} AS ${q("nodes")}
+      INNER JOIN ${reachable} AS ${q("forward")}
+        ON ${q("nodes")}.${q("__key")} =
+          ${q("forward")}.${q("__node_key")}
+      INNER JOIN ${reachable} AS ${q("reverse")}
+        ON ${q("forward")}.${q("__start_key")} =
+          ${q("reverse")}.${q("__node_key")}
+        AND ${q("nodes")}.${q("__key")} =
+          ${q("reverse")}.${q("__start_key")}
+      GROUP BY ${q("nodes")}.${q("node")}, ${q("nodes")}.${q("__key")}
+    ), ${roots} AS (
+      SELECT ${q("__root_key")},
+        CAST(row_number() OVER (ORDER BY ${q("__root_key")}) - 1 AS BIGINT)
+          AS ${q("componentId")}
+      FROM (SELECT DISTINCT ${q("__root_key")} FROM ${members})
+        AS ${q("distinct_roots")}
+    )
+    SELECT ${q("roots")}.${q("componentId")}, ${q("members")}.${q("node")}
+    FROM ${members} AS ${q("members")}
+    INNER JOIN ${roots} AS ${q("roots")}
+      ON ${q("members")}.${q("__root_key")} =
+        ${q("roots")}.${q("__root_key")}
+    ORDER BY ${q("members")}.${q("__key")}`;
+}

package/esm/methods/degree.d.ts

@@ -0,0 +1,9 @@
+import type SimpleTable from "../class/SimpleTable.js";
+type DegreeOptions = {
+    count?: "edges" | "neighbors";
+    weight?: string;
+    outputTable?: string | boolean;
+};
+export default function degree(simpleTable: SimpleTable, sourceColumn: string, targetColumn: string, options?: DegreeOptions): SimpleTable;
+export {};
+//# sourceMappingURL=degree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"degree.d.ts","sourceRoot":"","sources":["../../src/methods/degree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAQvD,KAAK,aAAa,GAAG;IACnB,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,MAAM,CAC5B,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,aAAkB,GAC1B,WAAW,CAoEb"}

package/esm/methods/degree.js

@@ -0,0 +1,135 @@
+import getGraphEndpointColumns from "../helpers/getGraphEndpointColumns.js";
+import getGraphWeightColumn from "../helpers/getGraphWeightColumn.js";
+import { prepareGraphSql } from "../helpers/prepareGraphTraversal.js";
+import queueGraphResult from "../helpers/queueGraphResult.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+export default function degree(simpleTable, sourceColumn, targetColumn, options = {}) {
+    if (typeof sourceColumn !== "string") {
+        throw new TypeError("degree() sourceColumn must be a string.");
+    }
+    if (typeof targetColumn !== "string") {
+        throw new TypeError("degree() targetColumn must be a string.");
+    }
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("degree() options must be an object.");
+    }
+    if (options.count !== undefined &&
+        !["edges", "neighbors"].includes(options.count)) {
+        throw new TypeError('degree() options.count must be "edges" or "neighbors".');
+    }
+    if (options.weight !== undefined && typeof options.weight !== "string") {
+        throw new TypeError("degree() options.weight must be a string.");
+    }
+    if (options.outputTable !== undefined &&
+        typeof options.outputTable !== "string" &&
+        typeof options.outputTable !== "boolean") {
+        throw new TypeError("degree() options.outputTable must be a string or boolean.");
+    }
+    if (options.weight !== undefined && options.count === "neighbors") {
+        throw new TypeError('degree() options.weight cannot be combined with count: "neighbors" because weighted sums operate on edges, not distinct neighbors.');
+    }
+    options = structuredClone(options);
+    const count = options.count ?? "edges";
+    const weight = options.weight;
+    const parameters = { sourceColumn, targetColumn, options };
+    return queueGraphResult(simpleTable, {
+        method: "degree()",
+        parameters,
+        outputTable: options.outputTable,
+        values: (schema) => {
+            validateInputs(schema, sourceColumn, targetColumn, weight);
+            return [];
+        },
+        buildSelect: (input, schema) => degreeSelect(input, schema, sourceColumn, targetColumn, count, weight),
+        outputSchema: (schema) => {
+            const validated = validateInputs(schema, sourceColumn, targetColumn, weight);
+            return {
+                node: validated.idType,
+                incoming: validated.degreeType,
+                outgoing: validated.degreeType,
+                total: validated.degreeType,
+            };
+        },
+    });
+}
+function validateInputs(schema, source, target, weight) {
+    const endpoints = getGraphEndpointColumns(schema, source, target, "degree()");
+    const degreeType = weight === undefined
+        ? "BIGINT"
+        : sumType(getGraphWeightColumn(schema, weight, "degree()").distanceType);
+    return { idType: endpoints.idType, degreeType };
+}
+function sumType(type) {
+    // DuckDB SUM widens FLOAT to DOUBLE; retain that aggregate precision.
+    return type === "FLOAT" ? "DOUBLE" : type;
+}
+function degreeSelect(input, schema, source, target, count, weight) {
+    const prepared = prepareGraphSql(input, schema, source, target, "degree()");
+    const weightColumn = weight === undefined
+        ? undefined
+        : getGraphWeightColumn(schema, weight, "degree()");
+    const degreeType = sumType(weightColumn?.distanceType ?? "BIGINT");
+    const relations = prepared.relationNames([
+        "graph_edges",
+        "graph_node_candidates",
+        "graph_nodes",
+        "graph_incoming",
+        "graph_outgoing",
+    ]);
+    const edges = relations.graph_edges;
+    const candidates = relations.graph_node_candidates;
+    const nodes = relations.graph_nodes;
+    const incoming = relations.graph_incoming;
+    const outgoing = relations.graph_outgoing;
+    const q = quoteIdentifier;
+    const edgeWeight = weightColumn === undefined
+        ? undefined
+        : `CAST(${q("edges")}.${q(weightColumn.column)} AS ${degreeType}) AS ${q("__weight")}`;
+    const aggregate = (direction) => {
+        const neighborKey = direction === "incoming" ? "__from_key" : "__to_key";
+        if (edgeWeight !== undefined) {
+            return `CAST(SUM(${q("__weight")}) AS ${degreeType})`;
+        }
+        return count === "neighbors"
+            ? `COUNT(DISTINCT ${q(neighborKey)})`
+            : "COUNT(*)";
+    };
+    const zero = `CAST(0 AS ${degreeType})`;
+    const incomingDegree = `COALESCE(${q("incoming")}.${q("incoming")}, ${zero})`;
+    const outgoingDegree = `COALESCE(${q("outgoing")}.${q("outgoing")}, ${zero})`;
+    return `WITH ${edges} AS (
+      ${prepared.edges("outgoing", edgeWeight === undefined ? [] : [edgeWeight])}
+    ), ${candidates} AS (
+      SELECT ${q("__from")} AS ${q("node")},
+        ${q("__from_key")} AS ${q("__key")}
+      FROM ${edges}
+      UNION ALL
+      SELECT ${q("__to")} AS ${q("node")},
+        ${q("__to_key")} AS ${q("__key")}
+      FROM ${edges}
+    ), ${nodes} AS (
+      SELECT MIN(${q("node")}) AS ${q("node")}, ${q("__key")}
+      FROM ${candidates}
+      GROUP BY ${q("__key")}
+    ), ${incoming} AS (
+      SELECT ${q("__to_key")} AS ${q("__key")},
+        ${aggregate("incoming")} AS ${q("incoming")}
+      FROM ${edges}
+      GROUP BY ${q("__to_key")}
+    ), ${outgoing} AS (
+      SELECT ${q("__from_key")} AS ${q("__key")},
+        ${aggregate("outgoing")} AS ${q("outgoing")}
+      FROM ${edges}
+      GROUP BY ${q("__from_key")}
+    )
+    SELECT ${q("nodes")}.${q("node")},
+      ${incomingDegree} AS ${q("incoming")},
+      ${outgoingDegree} AS ${q("outgoing")},
+      CAST(${incomingDegree} + ${outgoingDegree} AS ${degreeType}) AS ${q("total")}
+    FROM ${nodes} AS ${q("nodes")}
+    LEFT JOIN ${incoming} AS ${q("incoming")}
+      ON ${q("nodes")}.${q("__key")} = ${q("incoming")}.${q("__key")}
+    LEFT JOIN ${outgoing} AS ${q("outgoing")}
+      ON ${q("nodes")}.${q("__key")} = ${q("outgoing")}.${q("__key")}
+    ORDER BY ${q("total")} DESC, ${q("nodes")}.${q("__key")}`;
+}

package/esm/methods/distances.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"distances.d.ts","sourceRoot":"","sources":["../../src/methods/distances.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAIvD,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAA2B,EACzB,KAAK,OAAO,EAEb,MAAM,kCAAkC,CAAC;AAC1C,OAA8B,EAC5B,KAAK,cAAc,EAEpB,MAAM,qCAAqC,CAAC;AAK7C,KAAK,gBAAgB,GAAG,oBAAoB,GAAG;IAC7C,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,OAAO,GAAG,OAAO,EAAE,EAC/B,OAAO,GAAE,gBAAqB,GAC7B,WAAW,CAyGb"}

package/esm/methods/distances.js

@@ -0,0 +1,164 @@
+import buildGraphTemporalCostStateSql from "../helpers/buildGraphTemporalCostStateSql.js";
+import getGraphWeightColumn from "../helpers/getGraphWeightColumn.js";
+import prepareGraphTemporalSql, { prepareGraphTemporalOptions, } from "../helpers/prepareGraphTemporalSql.js";
+import prepareGraphStarts from "../helpers/prepareGraphStarts.js";
+import prepareGraphTraversal, { validateGraphStarts, } from "../helpers/prepareGraphTraversal.js";
+import queueGraphResult from "../helpers/queueGraphResult.js";
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
+import validateGraphTemporalEvents from "../helpers/validateGraphTemporalEvents.js";
+export default function distances(simpleTable, sourceColumn, targetColumn, startNodes, options = {}) {
+    if (typeof sourceColumn !== "string") {
+        throw new TypeError("distances() sourceColumn must be a string.");
+    }
+    if (typeof targetColumn !== "string") {
+        throw new TypeError("distances() targetColumn must be a string.");
+    }
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("distances() options must be an object.");
+    }
+    if (options.direction !== undefined &&
+        !["outgoing", "incoming", "both"].includes(options.direction)) {
+        throw new TypeError('distances() options.direction must be "outgoing", "incoming", or "both".');
+    }
+    if (options.weight !== undefined && typeof options.weight !== "string") {
+        throw new TypeError("distances() options.weight must be a string.");
+    }
+    if (options.outputTable !== undefined &&
+        typeof options.outputTable !== "string" &&
+        typeof options.outputTable !== "boolean") {
+        throw new TypeError("distances() options.outputTable must be a string or boolean.");
+    }
+    const preparedStarts = prepareGraphStarts(startNodes, "distances()", "startNodes");
+    const direction = options.direction ?? "outgoing";
+    const temporalOptions = prepareGraphTemporalOptions(options, direction, "distances()");
+    options = structuredClone(options);
+    const parameters = {
+        sourceColumn,
+        targetColumn,
+        startNodes: structuredClone(startNodes),
+        options,
+    };
+    return queueGraphResult(simpleTable, {
+        method: "distances()",
+        parameters,
+        outputTable: options.outputTable,
+        preflight: temporalOptions === undefined
+            ? undefined
+            : (input) => validateGraphTemporalEvents(input, temporalOptions, "distances()", parameters),
+        values: (schema) => {
+            const { temporal } = validateDistanceInputs(schema, sourceColumn, targetColumn, preparedStarts, options.weight, temporalOptions);
+            return temporal === undefined
+                ? preparedStarts.values
+                : [temporal.gapParameter, ...preparedStarts.values];
+        },
+        buildSelect: (input, schema) => distancesSelect(input, schema, sourceColumn, targetColumn, preparedStarts, direction, options.weight, temporalOptions),
+        outputSchema: (schema) => {
+            const validated = validateDistanceInputs(schema, sourceColumn, targetColumn, preparedStarts, options.weight, temporalOptions);
+            return {
+                start: validated.idType,
+                node: validated.idType,
+                distance: validated.distanceType,
+            };
+        },
+    });
+}
+function validateDistanceInputs(schema, source, target, starts, weight, temporalOptions) {
+    const endpoints = validateGraphStarts(schema, source, target, starts, "distances()", "startNodes");
+    const distanceType = weight === undefined
+        ? "BIGINT"
+        : getGraphWeightColumn(schema, weight, "distances()").distanceType;
+    const temporal = temporalOptions === undefined
+        ? undefined
+        : prepareGraphTemporalSql(schema, temporalOptions, "distances()");
+    return { idType: endpoints.idType, distanceType, temporal };
+}
+function distancesSelect(input, schema, source, target, starts, direction, weight, temporalOptions) {
+    const prepared = prepareGraphTraversal(input, schema, source, target, starts, "distances()", "startNodes");
+    const weightColumn = weight === undefined
+        ? undefined
+        : getGraphWeightColumn(schema, weight, "distances()");
+    const distanceType = weightColumn?.distanceType ?? "BIGINT";
+    const edgeWeight = weightColumn === undefined
+        ? `CAST(1 AS ${distanceType})`
+        : `CAST(${quoteIdentifier("edges")}.${quoteIdentifier(weightColumn.column)} AS ${distanceType})`;
+    if (temporalOptions !== undefined) {
+        const temporal = prepareGraphTemporalSql(schema, temporalOptions, "distances()");
+        return temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight);
+    }
+    const relations = prepared.relationNames([
+        "graph_start_values",
+        "graph_starts",
+        "graph_edges",
+        "graph_distances",
+    ]);
+    const startValuesRelation = relations.graph_start_values;
+    const startsRelation = relations.graph_starts;
+    const edgesRelation = relations.graph_edges;
+    const distancesRelation = relations.graph_distances;
+    const start = `${quoteIdentifier("starts")}.${quoteIdentifier("start")}`;
+    const startKey = `${quoteIdentifier("starts")}.${quoteIdentifier("__key")}`;
+    const reachedStart = `${quoteIdentifier("reached")}.${quoteIdentifier("start")}`;
+    const reachedStartKey = `${quoteIdentifier("reached")}.${quoteIdentifier("__start_key")}`;
+    const reachedNodeKey = `${quoteIdentifier("reached")}.${quoteIdentifier("__node_key")}`;
+    const reachedDistance = `${quoteIdentifier("reached")}.${quoteIdentifier("distance")}`;
+    const edgeTo = `${quoteIdentifier("edges")}.${quoteIdentifier("__to")}`;
+    const edgeToKey = `${quoteIdentifier("edges")}.${quoteIdentifier("__to_key")}`;
+    const edgeFromKey = `${quoteIdentifier("edges")}.${quoteIdentifier("__from_key")}`;
+    const edgeCost = `${quoteIdentifier("edges")}.${quoteIdentifier("__weight")}`;
+    const bestDistance = `${quoteIdentifier("best")}.${quoteIdentifier("distance")}`;
+    const candidateDistance = `CAST(${reachedDistance} + ${edgeCost} AS ${distanceType})`;
+    return `WITH RECURSIVE ${startValuesRelation}(${quoteIdentifier("start")}) AS (
+      VALUES ${prepared.startValues}
+    ), ${startsRelation} AS (
+      SELECT ${quoteIdentifier("start")},
+        ${prepared.key(quoteIdentifier("start"))} AS ${quoteIdentifier("__key")}
+      FROM ${startValuesRelation}
+    ), ${edgesRelation} AS (
+      ${prepared.edges(direction, [
+        `${edgeWeight} AS ${quoteIdentifier("__weight")}`,
+    ])}
+    ), ${distancesRelation}(
+      ${quoteIdentifier("start")}, ${quoteIdentifier("node")},
+      ${quoteIdentifier("__start_key")}, ${quoteIdentifier("__node_key")},
+      ${quoteIdentifier("distance")}
+    ) USING KEY(
+      ${quoteIdentifier("__start_key")}, ${quoteIdentifier("__node_key")}
+    ) AS (
+      SELECT ${start}, ${edgeTo}, ${startKey}, ${edgeToKey},
+        MIN(${edgeCost}) AS ${quoteIdentifier("distance")}
+      FROM ${startsRelation} AS ${quoteIdentifier("starts")}
+      INNER JOIN ${edgesRelation} AS ${quoteIdentifier("edges")}
+        ON ${startKey} = ${edgeFromKey}
+      GROUP BY ${start}, ${edgeTo}, ${startKey}, ${edgeToKey}
+      UNION
+      SELECT ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
+        MIN(${candidateDistance}) AS ${quoteIdentifier("distance")}
+      FROM ${distancesRelation} AS ${quoteIdentifier("reached")}
+      INNER JOIN ${edgesRelation} AS ${quoteIdentifier("edges")}
+        ON ${reachedNodeKey} = ${edgeFromKey}
+      LEFT JOIN recurring.${distancesRelation} AS ${quoteIdentifier("best")}
+        ON ${reachedStartKey} = ${quoteIdentifier("best")}.${quoteIdentifier("__start_key")}
+        AND ${edgeToKey} = ${quoteIdentifier("best")}.${quoteIdentifier("__node_key")}
+      GROUP BY ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
+        ${bestDistance}
+      HAVING ${bestDistance} IS NULL OR MIN(${candidateDistance}) < ${bestDistance}
+    )
+    SELECT ${quoteIdentifier("start")}, ${quoteIdentifier("node")},
+      ${quoteIdentifier("distance")}
+    FROM ${distancesRelation}
+    ORDER BY ${quoteIdentifier("__start_key")}, ${quoteIdentifier("distance")}, ${quoteIdentifier("__node_key")}`;
+}
+function temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight) {
+    const q = quoteIdentifier;
+    const startsSelect = `SELECT ${q("start")},
+        ${prepared.key(q("start"))} AS ${q("__key")}
+      FROM (VALUES ${prepared.startValues}) AS ${q("start_values")}(${q("start")})`;
+    const costStates = buildGraphTemporalCostStateSql(prepared, startsSelect, direction, temporal, distanceType, edgeWeight);
+    return `${costStates.withClause}
+    SELECT ${q("start")}, ${q("node")},
+      MIN(${q("distance")}) AS ${q("distance")}
+    FROM ${costStates.costRelation}
+    GROUP BY ${q("start")}, ${q("node")}, ${q("__start_key")},
+      ${q("__node_key")}
+    ORDER BY ${q("__start_key")}, ${q("distance")}, ${q("__node_key")}`;
+}

package/esm/methods/findCycles.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"findCycles.d.ts","sourceRoot":"","sources":["../../src/methods/findCycles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAMvD,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAA2B,EACzB,KAAK,OAAO,EAEb,MAAM,kCAAkC,CAAC;AAC1C,OAA8B,EAC5B,KAAK,cAAc,EAEpB,MAAM,qCAAqC,CAAC;AAM7C,KAAK,iBAAiB,GAAG,oBAAoB,GAAG;IAC9C,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,UAAU,CAChC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,OAAO,GAAG,OAAO,EAAE,EAC/B,OAAO,GAAE,iBAAsB,GAC9B,WAAW,CAuHb"}