@nshiab/simple-data-analysis-core 2.1.6 → 2.1.8

package/script/methods/distances.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = distances;
 const buildGraphTemporalCostStateSql_js_1 = __importDefault(require("../helpers/buildGraphTemporalCostStateSql.js"));
 const getGraphWeightColumn_js_1 = __importDefault(require("../helpers/getGraphWeightColumn.js"));
+const prepareGraphMetricOptions_js_1 = __importDefault(require("../helpers/prepareGraphMetricOptions.js"));
 const prepareGraphTemporalSql_js_1 = __importStar(require("../helpers/prepareGraphTemporalSql.js"));
 const prepareGraphStarts_js_1 = __importDefault(require("../helpers/prepareGraphStarts.js"));
 const prepareGraphTraversal_js_1 = __importStar(require("../helpers/prepareGraphTraversal.js"));
@@ -67,6 +68,7 @@ function distances(simpleTable, sourceColumn, targetColumn, startNodes, options
         typeof options.outputTable !== "boolean") {
         throw new TypeError("distances() options.outputTable must be a string or boolean.");
     }
+    const metrics = (0, prepareGraphMetricOptions_js_1.default)(options, "distances()", true);
     const preparedStarts = (0, prepareGraphStarts_js_1.default)(startNodes, "distances()", "startNodes");
     const direction = options.direction ?? "outgoing";
     const temporalOptions = (0, prepareGraphTemporalSql_js_1.prepareGraphTemporalOptions)(options, direction, "distances()");
@@ -90,13 +92,17 @@ function distances(simpleTable, sourceColumn, targetColumn, startNodes, options
                 ? preparedStarts.values
                 : [temporal.gapParameter, ...preparedStarts.values];
         },
-        buildSelect: (input, schema) => distancesSelect(input, schema, sourceColumn, targetColumn, preparedStarts, direction, options.weight, temporalOptions),
+        buildSelect: (input, schema) => distancesSelect(input, schema, sourceColumn, targetColumn, preparedStarts, direction, options.weight, temporalOptions, metrics),
         outputSchema: (schema) => {
             const validated = validateDistanceInputs(schema, sourceColumn, targetColumn, preparedStarts, options.weight, temporalOptions);
             return {
                 start: validated.idType,
                 node: validated.idType,
-                distance: validated.distanceType,
+                steps: "BIGINT",
+                ...(options.weight === undefined
+                    ? {}
+                    : { total: validated.distanceType }),
+                ...(metrics.elapsedTime ? { elapsedTimeMs: "DOUBLE" } : {}),
             };
         },
     });
@@ -111,7 +117,7 @@ function validateDistanceInputs(schema, source, target, starts, weight, temporal
         : (0, prepareGraphTemporalSql_js_1.default)(schema, temporalOptions, "distances()");
     return { idType: endpoints.idType, distanceType, temporal };
 }
-function distancesSelect(input, schema, source, target, starts, direction, weight, temporalOptions) {
+function distancesSelect(input, schema, source, target, starts, direction, weight, temporalOptions, metrics) {
     const prepared = (0, prepareGraphTraversal_js_1.default)(input, schema, source, target, starts, "distances()", "startNodes");
     const weightColumn = weight === undefined
         ? undefined
@@ -120,9 +126,14 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
     const edgeWeight = weightColumn === undefined
         ? `CAST(1 AS ${distanceType})`
         : `CAST(${(0, quoteIdentifier_js_1.default)("edges")}.${(0, quoteIdentifier_js_1.default)(weightColumn.column)} AS ${distanceType})`;
-    if (temporalOptions !== undefined) {
-        const temporal = (0, prepareGraphTemporalSql_js_1.default)(schema, temporalOptions, "distances()");
-        return temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight);
+    const temporal = temporalOptions === undefined
+        ? undefined
+        : (0, prepareGraphTemporalSql_js_1.default)(schema, temporalOptions, "distances()");
+    if (weight !== undefined || metrics.elapsedTime) {
+        return summaryDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, metrics, weight !== undefined, weightColumn?.type === "FLOAT" || weightColumn?.type === "DOUBLE");
+    }
+    if (temporal !== undefined) {
+        return temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, "steps", false);
     }
     const relations = prepared.relationNames([
         "graph_start_values",
@@ -146,6 +157,14 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
     const edgeCost = `${(0, quoteIdentifier_js_1.default)("edges")}.${(0, quoteIdentifier_js_1.default)("__weight")}`;
     const bestDistance = `${(0, quoteIdentifier_js_1.default)("best")}.${(0, quoteIdentifier_js_1.default)("distance")}`;
     const candidateDistance = `CAST(${reachedDistance} + ${edgeCost} AS ${distanceType})`;
+    const candidateSteps = `${(0, quoteIdentifier_js_1.default)("reached")}.${(0, quoteIdentifier_js_1.default)("steps")} + 1`;
+    const bestSteps = `${(0, quoteIdentifier_js_1.default)("best")}.${(0, quoteIdentifier_js_1.default)("steps")}`;
+    const order = (distance, steps) => metrics.minimize === "steps"
+        ? `ROW(${steps}, ${distance})`
+        : `ROW(${distance}, ${steps})`;
+    const candidateOrder = order(candidateDistance, candidateSteps);
+    const selectedDistance = `arg_min(${candidateDistance}, ${candidateOrder})`;
+    const selectedSteps = `arg_min(${candidateSteps}, ${candidateOrder})`;
     return `WITH RECURSIVE ${startValuesRelation}(${(0, quoteIdentifier_js_1.default)("start")}) AS (
       VALUES ${prepared.startValues}
     ), ${startsRelation} AS (
@@ -159,19 +178,20 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
     ), ${distancesRelation}(
       ${(0, quoteIdentifier_js_1.default)("start")}, ${(0, quoteIdentifier_js_1.default)("node")},
       ${(0, quoteIdentifier_js_1.default)("__start_key")}, ${(0, quoteIdentifier_js_1.default)("__node_key")},
-      ${(0, quoteIdentifier_js_1.default)("distance")}
+      ${(0, quoteIdentifier_js_1.default)("distance")}, ${(0, quoteIdentifier_js_1.default)("steps")}
     ) USING KEY(
       ${(0, quoteIdentifier_js_1.default)("__start_key")}, ${(0, quoteIdentifier_js_1.default)("__node_key")}
     ) AS (
       SELECT ${start}, ${edgeTo}, ${startKey}, ${edgeToKey},
-        MIN(${edgeCost}) AS ${(0, quoteIdentifier_js_1.default)("distance")}
+        MIN(${edgeCost}) AS ${(0, quoteIdentifier_js_1.default)("distance")}, CAST(1 AS BIGINT)
       FROM ${startsRelation} AS ${(0, quoteIdentifier_js_1.default)("starts")}
       INNER JOIN ${edgesRelation} AS ${(0, quoteIdentifier_js_1.default)("edges")}
         ON ${startKey} = ${edgeFromKey}
       GROUP BY ${start}, ${edgeTo}, ${startKey}, ${edgeToKey}
       UNION
       SELECT ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
-        MIN(${candidateDistance}) AS ${(0, quoteIdentifier_js_1.default)("distance")}
+        ${selectedDistance} AS ${(0, quoteIdentifier_js_1.default)("distance")},
+        ${selectedSteps} AS ${(0, quoteIdentifier_js_1.default)("steps")}
       FROM ${distancesRelation} AS ${(0, quoteIdentifier_js_1.default)("reached")}
       INNER JOIN ${edgesRelation} AS ${(0, quoteIdentifier_js_1.default)("edges")}
         ON ${reachedNodeKey} = ${edgeFromKey}
@@ -179,25 +199,259 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
         ON ${reachedStartKey} = ${(0, quoteIdentifier_js_1.default)("best")}.${(0, quoteIdentifier_js_1.default)("__start_key")}
         AND ${edgeToKey} = ${(0, quoteIdentifier_js_1.default)("best")}.${(0, quoteIdentifier_js_1.default)("__node_key")}
       GROUP BY ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
-        ${bestDistance}
-      HAVING ${bestDistance} IS NULL OR MIN(${candidateDistance}) < ${bestDistance}
+        ${bestDistance}, ${bestSteps}
+      HAVING ${bestDistance} IS NULL OR
+        ${order(selectedDistance, selectedSteps)} < ${order(bestDistance, bestSteps)}
     )
     SELECT ${(0, quoteIdentifier_js_1.default)("start")}, ${(0, quoteIdentifier_js_1.default)("node")},
-      ${(0, quoteIdentifier_js_1.default)("distance")}
+      ${(0, quoteIdentifier_js_1.default)("steps")}${weight === undefined
+        ? ""
+        : `, ${(0, quoteIdentifier_js_1.default)("distance")} AS ${(0, quoteIdentifier_js_1.default)("total")}`}
     FROM ${distancesRelation}
-    ORDER BY ${(0, quoteIdentifier_js_1.default)("__start_key")}, ${(0, quoteIdentifier_js_1.default)("distance")}, ${(0, quoteIdentifier_js_1.default)("__node_key")}`;
+    ORDER BY ${(0, quoteIdentifier_js_1.default)("__start_key")}, ${(0, quoteIdentifier_js_1.default)(metrics.minimize === "steps" ? "steps" : "distance")}, ${(0, quoteIdentifier_js_1.default)("__node_key")}`;
 }
-function temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight) {
+function temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, minimize, includeTotal) {
     const q = quoteIdentifier_js_1.default;
     const startsSelect = `SELECT ${q("start")},
         ${prepared.key(q("start"))} AS ${q("__key")}
       FROM (VALUES ${prepared.startValues}) AS ${q("start_values")}(${q("start")})`;
-    const costStates = (0, buildGraphTemporalCostStateSql_js_1.default)(prepared, startsSelect, direction, temporal, distanceType, edgeWeight);
+    const costStates = (0, buildGraphTemporalCostStateSql_js_1.default)(prepared, startsSelect, direction, temporal, distanceType, edgeWeight, [], minimize);
+    const order = minimize === "steps"
+        ? `${q("steps")}, ${q("distance")}`
+        : `${q("distance")}, ${q("steps")}`;
     return `${costStates.withClause}
-    SELECT ${q("start")}, ${q("node")},
-      MIN(${q("distance")}) AS ${q("distance")}
+    SELECT ${q("start")}, ${q("node")}, ${q("steps")}${includeTotal ? `, ${q("distance")} AS ${q("total")}` : ""}
     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")}`;
+    QUALIFY row_number() OVER (
+      PARTITION BY ${q("__start_key")}, ${q("__node_key")}
+      ORDER BY ${order}
+    ) = 1
+    ORDER BY ${q("__start_key")}, ${q(minimize === "steps" ? "steps" : "distance")}, ${q("__node_key")}`;
+}
+// Distinct visited sets, metrics, and temporal boundaries are enough to extend
+// summaries. No edge IDs or full connection sequences are needed. Keeping the
+// visited set is necessary: equal summaries can have different legal extensions.
+function summaryDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, metrics, includeTotal, floatingWeight) {
+    const q = quoteIdentifier_js_1.default;
+    const relations = prepared.relationNames([
+        "graph_starts",
+        "graph_temporal_settings",
+        "graph_event_rows",
+        "graph_edges",
+        "graph_summaries",
+        "graph_metric_results",
+        "graph_tied_summaries",
+        "graph_best_metrics",
+        "graph_metric_bounds",
+    ]);
+    const starts = relations.graph_starts;
+    const settings = relations.graph_temporal_settings;
+    const events = relations.graph_event_rows;
+    const edges = relations.graph_edges;
+    const summaries = relations.graph_summaries;
+    const results = relations.graph_metric_results;
+    const tied = relations.graph_tied_summaries;
+    const ref = (alias, column) => `${q(alias)}.${q(column)}`;
+    const searchDirection = direction;
+    const firstAnchor = temporal?.journeyAnchor("edges", searchDirection);
+    const sum = `CAST(${ref("reached", "distance")} + ${ref("edges", "__weight")} AS ${distanceType})`;
+    // Reported costs must not reject routes before the primary objective has
+    // selected its results. NULL marks overflow and propagates through sums;
+    // non-negative weights cannot bring an overflowing total back into range.
+    const nextDistance = metrics.minimize === "weight" ? sum : `TRY(${sum})`;
+    const temporalColumns = temporal === undefined
+        ? ""
+        : `, ${q("__event_start")}, ${q("__event_end")}`;
+    const eventValues = temporal === undefined
+        ? ""
+        : `, ${ref("edges", "__event_start")}, ${ref("edges", "__event_end")}`;
+    const metric = metrics.minimize === "steps"
+        ? q("steps")
+        : metrics.minimize === "weight"
+            ? q("distance")
+            : q("__elapsed");
+    // Use native time precision for selection. Collapse equal reported values
+    // after conversion to milliseconds, since these are summary rows.
+    const reportedElapsed = metrics.elapsedTime
+        ? `, ${temporal.elapsedMilliseconds(q("__elapsed"))} AS ${q("elapsedTimeMs")}`
+        : "";
+    const order = metrics.minimize === "steps"
+        ? [
+            q("steps"),
+            q("__node_key"),
+            ...(includeTotal ? [q("total")] : []),
+            ...(metrics.elapsedTime ? [q("elapsedTimeMs")] : []),
+        ]
+        : metrics.minimize === "weight"
+            ? [
+                q("total"),
+                q("__node_key"),
+                q("steps"),
+                ...(metrics.elapsedTime ? [q("elapsedTimeMs")] : []),
+            ]
+            : [
+                q("elapsedTimeMs"),
+                q("__node_key"),
+                q("steps"),
+                ...(includeTotal ? [q("total")] : []),
+            ];
+    const bounds = summaryBoundsSql(relations.graph_best_metrics, relations.graph_metric_bounds, starts, edges, settings, temporal, searchDirection, metrics.minimize, distanceType, floatingWeight);
+    return `WITH RECURSIVE ${settings} AS (
+      ${temporal === undefined
+        ? `SELECT 0 AS ${q("__gap")}`
+        : `SELECT CAST(? AS HUGEINT) AS ${q("__gap")}`}
+    ), ${events} AS MATERIALIZED (
+      ${prepared.edges(direction, [
+        `${edgeWeight} AS ${q("__weight")}`,
+        ...(temporal?.eventSelections("edges") ?? []),
+    ])}
+    ), ${edges} AS MATERIALIZED (
+      SELECT DISTINCT ${q("__from")}, ${q("__to")}, ${q("__from_key")},
+        ${q("__to_key")}, ${q("__weight")}${temporalColumns}
+      FROM ${events} AS ${q("events")}
+      ${temporal === undefined ? "" : `WHERE ${temporal.eventValidity("events")}`}
+    ), ${starts} AS (
+      SELECT ${q("start")}, ${prepared.key(q("start"))} AS ${q("__key")}
+      FROM (VALUES ${prepared.startValues}) AS ${q("start_values")}(${q("start")})
+    ), ${bounds.ctes}, ${summaries}(
+      ${q("start")}, ${q("node")}, ${q("__start_key")}, ${q("__node_key")},
+      ${q("__visited")}, ${q("steps")}, ${q("distance")}${temporalColumns}${metrics.elapsedTime ? `, ${q("__anchor")}` : ""}
+    ) AS (
+      SELECT ${ref("starts", "start")}, ${ref("edges", "__to")},
+        ${ref("starts", "__key")}, ${ref("edges", "__to_key")},
+        list_sort(list_distinct([${ref("starts", "__key")}, ${ref("edges", "__to_key")}])),
+        CAST(1 AS BIGINT), ${ref("edges", "__weight")}${eventValues}${metrics.elapsedTime ? `, ${firstAnchor}` : ""}
+      FROM ${starts} AS ${q("starts")}
+      INNER JOIN ${edges} AS ${q("edges")}
+        ON ${ref("starts", "__key")} = ${ref("edges", "__from_key")}
+      ${bounds.join(ref("starts", "__key"))}
+      WHERE ${bounds.test("CAST(1 AS BIGINT)", ref("edges", "__weight"), firstAnchor)}
+      UNION
+      SELECT ${ref("reached", "start")}, ${ref("edges", "__to")},
+        ${ref("reached", "__start_key")}, ${ref("edges", "__to_key")},
+        list_sort(list_distinct(list_append(${ref("reached", "__visited")}, ${ref("edges", "__to_key")}))),
+        ${ref("reached", "steps")} + 1, ${nextDistance}${eventValues}${metrics.elapsedTime ? `, ${ref("reached", "__anchor")}` : ""}
+      FROM ${summaries} AS ${q("reached")}
+      INNER JOIN ${edges} AS ${q("edges")}
+        ON ${ref("reached", "__node_key")} = ${ref("edges", "__from_key")}
+      CROSS JOIN ${settings} AS ${q("settings")}
+      ${bounds.join(ref("reached", "__start_key"))}
+      WHERE ${bounds.test(`${ref("reached", "steps")} + 1`, nextDistance, ref("reached", "__anchor"))}
+        AND ${ref("reached", "__node_key")} <> ${ref("reached", "__start_key")}
+        AND (NOT list_contains(${ref("reached", "__visited")}, ${ref("edges", "__to_key")})
+          OR ${ref("edges", "__to_key")} = ${ref("reached", "__start_key")})
+        ${temporal === undefined ? "" : `AND ${temporal.transition("reached", "edges", searchDirection, ref("settings", "__gap"))}`}
+    ), ${results} AS (
+      SELECT *${metrics.elapsedTime
+        ? `, ${temporal.journeyElapsed("summaries", ref("summaries", "__anchor"), searchDirection)} AS ${q("__elapsed")}`
+        : ""}
+      FROM ${summaries} AS ${q("summaries")}
+    ), ${tied} AS MATERIALIZED (
+      SELECT DISTINCT ${q("start")}, ${q("node")}, ${q("__start_key")}, ${q("__node_key")},
+        ${q("steps")}${includeTotal ? `, ${q("distance")} AS ${q("total")}` : ""}${reportedElapsed}
+      FROM ${results}
+      QUALIFY ${metric} = MIN(${metric}) OVER (
+        PARTITION BY ${q("__start_key")}, ${q("__node_key")}
+      )
+    )
+    SELECT ${q("start")}, ${q("node")}, ${q("steps")}${includeTotal
+        ? `, CASE WHEN ${q("total")} IS NULL
+          THEN error('distances() total exceeds the supported ${distanceType} range for an optimal route.')
+          ELSE ${q("total")} END AS ${q("total")}`
+        : ""}${metrics.elapsedTime ? `, ${q("elapsedTimeMs")}` : ""}
+    FROM ${tied}
+    ORDER BY ${q("__start_key")}, ${order.join(", ")}`;
+}
+// Compute primary optima without enumerating visited sets. Exact additive
+// objectives have optimal prefixes (at the same event boundary in temporal
+// traversal). Floating addition can erase prefix differences, and elapsed
+// optima can depend on a later departure, so those use a per-start upper bound.
+function summaryBoundsSql(best, limits, starts, edges, settings, temporal, direction, minimize, distanceType, floatingWeight) {
+    const q = quoteIdentifier_js_1.default;
+    const ref = (alias, column) => `${q(alias)}.${q(column)}`;
+    const elapsed = minimize === "elapsedTime";
+    const globalBound = elapsed || (minimize === "weight" && floatingWeight);
+    const boundaries = temporal === undefined
+        ? []
+        : ["__event_start", "__event_end"];
+    const keys = [
+        "__start_key",
+        "__node_key",
+        ...boundaries,
+        ...(elapsed ? ["__anchor"] : []),
+    ];
+    const firstAnchor = elapsed
+        ? temporal.journeyAnchor("edges", direction)
+        : undefined;
+    const firstKeys = [
+        ref("starts", "__key"),
+        ref("edges", "__to_key"),
+        ...boundaries.map((key) => ref("edges", key)),
+        ...(elapsed ? [firstAnchor] : []),
+    ];
+    const nextKeys = [
+        ref("reached", "__start_key"),
+        ref("edges", "__to_key"),
+        ...boundaries.map((key) => ref("edges", key)),
+        ...(elapsed ? [ref("reached", "__anchor")] : []),
+    ];
+    const firstMetric = minimize === "steps"
+        ? "CAST(1 AS BIGINT)"
+        : elapsed
+            ? temporal.journeyElapsed("edges", firstAnchor, direction)
+            : ref("edges", "__weight");
+    const nextMetric = minimize === "steps"
+        ? `${ref("reached", "__metric")} + 1`
+        : elapsed
+            ? temporal.journeyElapsed("edges", ref("reached", "__anchor"), direction)
+            : `CAST(${ref("reached", "__metric")} + ${ref("edges", "__weight")} AS ${distanceType})`;
+    const minimum = `MIN(${nextMetric})`;
+    const bestMetric = ref("best", "__metric");
+    const ctes = `${best}(${keys.map(q).join(", ")}, ${q("__metric")})
+    USING KEY(${keys.map(q).join(", ")}) AS (
+      SELECT ${firstKeys.join(", ")}, MIN(${firstMetric})
+      FROM ${starts} AS ${q("starts")}
+      INNER JOIN ${edges} AS ${q("edges")}
+        ON ${ref("starts", "__key")} = ${ref("edges", "__from_key")}
+      GROUP BY ${firstKeys.join(", ")}
+      UNION
+      SELECT ${nextKeys.join(", ")}, ${minimum}
+      FROM ${best} AS ${q("reached")}
+      INNER JOIN ${edges} AS ${q("edges")}
+        ON ${ref("reached", "__node_key")} = ${ref("edges", "__from_key")}
+      CROSS JOIN ${settings} AS ${q("settings")}
+      LEFT JOIN recurring.${best} AS ${q("best")}
+        ON ${keys.map((key, i) => `${ref("best", key)} = ${nextKeys[i]}`).join(" AND ")}
+      WHERE ${ref("reached", "__node_key")} <> ${ref("reached", "__start_key")}
+        ${temporal === undefined ? "" : `AND ${temporal.transition("reached", "edges", direction, ref("settings", "__gap"))}`}
+      GROUP BY ${nextKeys.join(", ")}, ${bestMetric}
+      HAVING ${bestMetric} IS NULL OR ${minimum} < ${bestMetric}
+    )${globalBound
+        ? `, ${limits} AS (
+      SELECT ${q("__start_key")}, MAX(${q("__minimum")}) AS ${q("__metric")}
+      FROM (
+        SELECT ${q("__start_key")}, ${q("__node_key")}, MIN(${q("__metric")}) AS ${q("__minimum")}
+        FROM ${best}
+        GROUP BY ${q("__start_key")}, ${q("__node_key")}
+      ) AS ${q("minima")}
+      GROUP BY ${q("__start_key")}
+    )`
+        : ""}`;
+    return {
+        ctes,
+        join: (startKey) => `INNER JOIN ${globalBound ? limits : best} AS ${q("bounds")}
+      ON ${ref("bounds", "__start_key")} = ${startKey}
+      ${globalBound
+            ? ""
+            : `AND ${ref("bounds", "__node_key")} = ${ref("edges", "__to_key")}
+        ${boundaries.map((key) => `AND ${ref("bounds", key)} = ${ref("edges", key)}`).join(" ")}`}`,
+        test: (steps, distance, anchor) => {
+            const metric = minimize === "steps"
+                ? steps
+                : elapsed
+                    ? temporal.journeyElapsed("edges", anchor, direction)
+                    : distance;
+            return `${metric} ${globalBound ? "<=" : "="} ${ref("bounds", "__metric")}`;
+        },
+    };
 }

package/script/methods/findCycles.d.ts

@@ -3,6 +3,7 @@ import { type GraphTemporalOptions } from "../helpers/prepareGraphTemporalSql.js
 import { type GraphId } from "../helpers/prepareGraphStarts.js";
 import { type GraphDirection } from "../helpers/prepareGraphTraversal.js";
 type FindCyclesOptions = GraphTemporalOptions & {
+    elapsedTime?: boolean;
     direction?: GraphDirection;
     outputTable?: string | boolean;
     weight?: string;

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

@@ -1 +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"}
+{"version":3,"file":"findCycles.d.ts","sourceRoot":"","sources":["../../src/methods/findCycles.ts"],"names":[],"mappings":"AACA,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,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,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,CAgIb"}

package/script/methods/findCycles.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = findCycles;
+const prepareGraphMetricOptions_js_1 = __importDefault(require("../helpers/prepareGraphMetricOptions.js"));
 const getGraphEdgeIdColumn_js_1 = __importDefault(require("../helpers/getGraphEdgeIdColumn.js"));
 const getGraphWeightColumn_js_1 = __importDefault(require("../helpers/getGraphWeightColumn.js"));
 const graphRouteResultSchema_js_1 = __importDefault(require("../helpers/graphRouteResultSchema.js"));
@@ -74,6 +75,7 @@ function findCycles(simpleTable, sourceColumn, targetColumn, edgeId, startNodes,
         typeof options.outputTable !== "boolean") {
         throw new TypeError("findCycles() options.outputTable must be a string or boolean.");
     }
+    const metric = (0, prepareGraphMetricOptions_js_1.default)(options, "findCycles()", false);
     const direction = options.direction ?? "outgoing";
     const temporalOptions = (0, prepareGraphTemporalSql_js_1.prepareGraphTemporalOptions)(options, direction, "findCycles()");
     options = structuredClone(options);
@@ -92,7 +94,8 @@ function findCycles(simpleTable, sourceColumn, targetColumn, edgeId, startNodes,
             ? undefined
             : (input) => (0, validateGraphTemporalEvents_js_1.default)(input, temporalOptions, "findCycles()", parameters),
         values: (schema) => {
-            validateFindCyclesInputs(schema, sourceColumn, targetColumn, edgeId, preparedStarts, options.weight);
+            const validated = validateFindCyclesInputs(schema, sourceColumn, targetColumn, edgeId, preparedStarts, options.weight);
+            (0, graphRouteResultSchema_js_1.default)(schema, validated.distanceType, "findCycles()", metric.elapsedTime);
             const temporal = temporalOptions === undefined
                 ? undefined
                 : (0, prepareGraphTemporalSql_js_1.default)(schema, temporalOptions, "findCycles()");
@@ -100,7 +103,7 @@ function findCycles(simpleTable, sourceColumn, targetColumn, edgeId, startNodes,
                 ? preparedStarts.values
                 : [temporal.gapParameter, ...preparedStarts.values];
         },
-        buildSelect: (input, schema) => findCyclesSelect(input, schema, sourceColumn, targetColumn, edgeId, preparedStarts, direction, options.weight, temporalOptions),
+        buildSelect: (input, schema) => findCyclesSelect(input, schema, sourceColumn, targetColumn, edgeId, preparedStarts, direction, options.weight, temporalOptions, metric.elapsedTime),
         outputSchema: (schema) => {
             const validated = validateFindCyclesInputs(schema, sourceColumn, targetColumn, edgeId, preparedStarts, options.weight);
             if (temporalOptions !== undefined) {
@@ -108,7 +111,7 @@ function findCycles(simpleTable, sourceColumn, targetColumn, edgeId, startNodes,
             }
             return {
                 start: validated.nodeIdType,
-                ...(0, graphRouteResultSchema_js_1.default)(schema, validated.distanceType, "findCycles()"),
+                ...(0, graphRouteResultSchema_js_1.default)(schema, validated.distanceType, "findCycles()", metric.elapsedTime),
             };
         },
     });
@@ -126,7 +129,7 @@ function validateFindCyclesInputs(schema, source, target, edgeId, starts, weight
         nodeIdType: endpoints.idType,
     };
 }
-function findCyclesSelect(input, schema, source, target, edgeId, starts, direction, weight, temporalOptions) {
+function findCyclesSelect(input, schema, source, target, edgeId, starts, direction, weight, temporalOptions, elapsedTime) {
     const prepared = (0, prepareGraphTraversal_js_1.default)(input, schema, source, target, starts, "findCycles()", "startNodes");
     const edgeIdColumn = (0, getGraphEdgeIdColumn_js_1.default)(schema, edgeId, "findCycles()");
     const weightColumn = weight === undefined
@@ -142,10 +145,10 @@ function findCyclesSelect(input, schema, source, target, edgeId, starts, directi
     const edgeWeight = weightColumn === undefined
         ? `CAST(1 AS ${distanceType})`
         : `CAST(${q("edges")}.${q(weightColumn.column)} AS ${distanceType})`;
-    const stepType = `STRUCT(${q("edgeId")} ${edgeIdColumn.idType}, ${q("source")} ${prepared.endpoints.idType}, ${q("target")} ${prepared.endpoints.idType}, ${q("weight")} ${distanceType}, ${q("distance")} ${distanceType})`;
+    const stepType = `STRUCT(${q("edgeId")} ${edgeIdColumn.idType}, ${q("source")} ${prepared.endpoints.idType}, ${q("target")} ${prepared.endpoints.idType}, ${q("weight")} ${distanceType}, ${q("distance")} ${distanceType}${elapsedTime ? `, ${q("elapsedTimeMs")} DOUBLE` : ""})`;
     if (temporalOptions !== undefined) {
         const temporal = (0, prepareGraphTemporalSql_js_1.default)(schema, temporalOptions, "findCycles()");
-        return temporalFindCyclesSelect(prepared, direction, temporal, typedEdgeId, edgeKey, edgeWeight, distanceType, stepType, input, edgeIdColumn);
+        return temporalFindCyclesSelect(prepared, direction, temporal, typedEdgeId, edgeKey, edgeWeight, distanceType, stepType, input, edgeIdColumn, elapsedTime);
     }
     const relations = prepared.relationNames([
         "graph_start_values",
@@ -249,7 +252,7 @@ function findCyclesSelect(input, schema, source, target, edgeId, starts, directi
     )
     ${(0, graphRouteResultSelect_js_1.default)(rankedRelation, input, edgeIdColumn, true)}`;
 }
-function temporalFindCyclesSelect(prepared, direction, temporal, typedEdgeId, edgeKey, edgeWeight, distanceType, stepType, input, edgeIdColumn) {
+function temporalFindCyclesSelect(prepared, direction, temporal, typedEdgeId, edgeKey, edgeWeight, distanceType, stepType, input, edgeIdColumn, elapsedTime) {
     const q = quoteIdentifier_js_1.default;
     const relations = prepared.relationNames([
         "graph_start_values",
@@ -279,12 +282,16 @@ function temporalFindCyclesSelect(prepared, direction, temporal, typedEdgeId, ed
     const walkDistance = `${q("walks")}.${q("distance")}`;
     const candidateDistance = `CAST(${walkDistance} + ${edgeCost} AS ${distanceType})`;
     const gap = `${q("settings")}.${q("__gap")}`;
-    const step = (distance) => `struct_pack(
+    const firstAnchor = temporal.journeyAnchor("edges", direction);
+    const anchor = `${q("walks")}.${q("__journey_anchor")}`;
+    const step = (distance, journeyAnchor) => `struct_pack(
           ${q("edgeId")} := ${edgeIdentity},
           ${q("source")} := ${edgeFrom},
           ${q("target")} := ${edgeTo},
           ${q("weight")} := ${edgeCost},
-          ${q("distance")} := ${distance}
+          ${q("distance")} := ${distance}${elapsedTime
+        ? `, ${q("elapsedTimeMs")} := ${temporal.elapsedMilliseconds(temporal.journeyElapsed("edges", journeyAnchor, direction))}`
+        : ""}
         )`;
     return `WITH RECURSIVE ${settingsRelation} AS MATERIALIZED (
       SELECT CAST(? AS HUGEINT) AS ${q("__gap")}
@@ -310,7 +317,7 @@ function temporalFindCyclesSelect(prepared, direction, temporal, typedEdgeId, ed
       ${q("__node_key")}, ${q("__visited")}, ${q("__event_ids")},
       ${q("__edge_keys")}, ${q("steps")}, ${q("distance")},
       ${q("closed")}, ${q("__event_id")}, ${q("__event_start")},
-      ${q("__event_end")}
+      ${q("__event_end")}${elapsedTime ? `, ${q("__journey_anchor")}` : ""}
     ) AS (
       SELECT ${q("starts")}.${q("start")},
         ${q("starts")}.${q("__start_key")}, ${edgeTo}, ${edgeToKey},
@@ -319,11 +326,11 @@ function temporalFindCyclesSelect(prepared, direction, temporal, typedEdgeId, ed
           ELSE [${edgeFromKey}, ${edgeToKey}]
         END,
         [${q("edges")}.${q("__event_id")}], [${edgeIdentityKey}],
-        [${step(edgeCost)}]::${stepType}[], ${edgeCost},
+        [${step(edgeCost, firstAnchor)}]::${stepType}[], ${edgeCost},
         ${edgeFromKey} = ${edgeToKey},
         ${q("edges")}.${q("__event_id")},
         ${q("edges")}.${q("__event_start")},
-        ${q("edges")}.${q("__event_end")}
+        ${q("edges")}.${q("__event_end")}${elapsedTime ? `, ${firstAnchor}` : ""}
       FROM ${edgesRelation} AS ${q("edges")}
       INNER JOIN ${startsRelation} AS ${q("starts")}
         ON ${q("starts")}.${q("__start_key")} = ${edgeFromKey}
@@ -334,12 +341,12 @@ function temporalFindCyclesSelect(prepared, direction, temporal, typedEdgeId, ed
         list_append(${q("walks")}.${q("__event_ids")},
           ${q("edges")}.${q("__event_id")}),
         list_append(${q("walks")}.${q("__edge_keys")}, ${edgeIdentityKey}),
-        list_append(${q("walks")}.${q("steps")}, ${step(candidateDistance)}),
+        list_append(${q("walks")}.${q("steps")}, ${step(candidateDistance, anchor)}),
         ${candidateDistance},
         ${edgeToKey} = ${q("walks")}.${q("__start_key")},
         ${q("edges")}.${q("__event_id")},
         ${q("edges")}.${q("__event_start")},
-        ${q("edges")}.${q("__event_end")}
+        ${q("edges")}.${q("__event_end")}${elapsedTime ? `, ${anchor}` : ""}
       FROM ${walksRelation} AS ${q("walks")}
       INNER JOIN ${edgesRelation} AS ${q("edges")}
         ON ${q("walks")}.${q("__node_key")} = ${edgeFromKey}
@@ -365,5 +372,5 @@ function temporalFindCyclesSelect(prepared, direction, temporal, typedEdgeId, ed
           AS BIGINT) AS ${q("pathId")}, ${q("steps")}
       FROM ${completeRelation}
     )
-    ${(0, graphRouteResultSelect_js_1.default)(rankedRelation, input, edgeIdColumn, true)}`;
+    ${(0, graphRouteResultSelect_js_1.default)(rankedRelation, input, edgeIdColumn, true, elapsedTime)}`;
 }

package/script/methods/paths.d.ts

@@ -3,6 +3,7 @@ import type { GraphId } from "../helpers/prepareGraphStarts.js";
 import { type GraphTemporalOptions } from "../helpers/prepareGraphTemporalSql.js";
 import type { GraphDirection } from "../helpers/prepareGraphTraversal.js";
 type PathsOptions = GraphTemporalOptions & {
+    elapsedTime?: boolean;
     direction?: GraphDirection;
     outputTable?: string | boolean;
     weight?: string;

package/script/methods/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/methods/paths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AASvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAM1E,KAAK,YAAY,GAAG,oBAAoB,GAAG;IACzC,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,KAAK,CAC3B,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,YAAiB,GACzB,WAAW,CA+Gb"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/methods/paths.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AASvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAM1E,KAAK,YAAY,GAAG,oBAAoB,GAAG;IACzC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,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,KAAK,CAC3B,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,YAAiB,GACzB,WAAW,CA4Hb"}