@nshiab/simple-data-analysis-core 2.1.7 → 2.1.9

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

@@ -1 +1 @@
-{"version":3,"file":"prepareGraphMetricOptions.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareGraphMetricOptions.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,QAAQ,GAAG,aAAa,GAAG,aAAa,CAAC;CACpD,CAAC;AAEF,qFAAqF;AACrF,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAC/C,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,GAChB,0BAA0B,CAwD5B"}
+{"version":3,"file":"prepareGraphMetricOptions.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareGraphMetricOptions.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,aAAa,CAAC;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,aAAa,CAAC;CAC9C,CAAC;AAEF,qFAAqF;AACrF,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAC/C,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,GAChB,0BAA0B,CA2D5B"}

package/esm/helpers/prepareGraphMetricOptions.js

@@ -14,8 +14,9 @@ export default function prepareGraphMetricOptions(options, method, optimize) {
         if (!optimize) {
             throw new TypeError(`${method} options.minimize is not supported because this method returns all routes.`);
         }
-        if (options.minimize !== "weight" && options.minimize !== "elapsedTime") {
-            throw new TypeError(`${method} options.minimize must be "weight" or "elapsedTime".`);
+        if (options.minimize !== "steps" && options.minimize !== "weight" &&
+            options.minimize !== "elapsedTime") {
+            throw new TypeError(`${method} options.minimize must be "steps", "weight", or "elapsedTime".`);
         }
         if (options.minimize === "weight" && options.weight === undefined) {
             throw new TypeError(`${method} options.minimize: "weight" requires options.weight.`);
@@ -26,7 +27,7 @@ export default function prepareGraphMetricOptions(options, method, optimize) {
     }
     if (optimize && elapsedTime && options.weight !== undefined &&
         options.minimize === undefined) {
-        throw new TypeError(`${method} when weight and elapsedTime are both enabled, specify options.minimize: "weight" or "elapsedTime".`);
+        throw new TypeError(`${method} when weight and elapsedTime are both enabled, specify options.minimize: "steps", "weight", or "elapsedTime".`);
     }
     return {
         elapsedTime,
@@ -35,6 +36,6 @@ export default function prepareGraphMetricOptions(options, method, optimize) {
                 ? "weight"
                 : elapsedTime
                     ? "elapsedTime"
-                    : "connections"),
+                    : "steps"),
     };
 }

package/esm/helpers/prepareGraphRouteSql.d.ts

@@ -8,13 +8,13 @@ export type PreparedGraphRouteEndpoints = {
 /** 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): {
+export declare function validateGraphRouteInputs(schema: TableSchema, source: string, target: string, edgeId: string, endpoints: PreparedGraphRouteEndpoints, weight: string | undefined, method: string, includeTotal?: boolean): {
     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): {
+export declare function prepareGraphRouteSql(input: string, schema: TableSchema, source: string, target: string, edgeId: string, endpoints: PreparedGraphRouteEndpoints, weight: string | undefined, method: string, includeTotal?: boolean): {
     distanceType: string;
     edgeIdColumn: import("./getGraphEdgeIdColumn.js").GraphEdgeIdColumn;
     edgeKey: string;

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

@@ -1 +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"}
+{"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,EACd,YAAY,UAAO;;;;EAmBpB;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,EACd,YAAY,UAAO;;;;;;;;;;;;;EAkDpB"}

package/esm/helpers/prepareGraphRouteSql.js

@@ -34,13 +34,13 @@ export function prepareGraphRouteEndpoints(start, end, method) {
     };
 }
 /** Validates the columns shared by edge-route methods from queued schema data. */
-export function validateGraphRouteInputs(schema, source, target, edgeId, endpoints, weight, method) {
+export function validateGraphRouteInputs(schema, source, target, edgeId, endpoints, weight, method, includeTotal = true) {
     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);
+    validateGraphRouteResultSchema(schema, method, [], includeTotal);
     return {
         distanceType: weightColumn?.distanceType ?? "BIGINT",
         edgeIdType: edges.idType,
@@ -48,8 +48,8 @@ export function validateGraphRouteInputs(schema, source, target, edgeId, endpoin
     };
 }
 /** Prepares the typed SQL expressions shared by edge-route enumeration. */
-export function prepareGraphRouteSql(input, schema, source, target, edgeId, endpoints, weight, method) {
-    validateGraphRouteResultSchema(schema, method);
+export function prepareGraphRouteSql(input, schema, source, target, edgeId, endpoints, weight, method, includeTotal = true) {
+    validateGraphRouteResultSchema(schema, method, [], includeTotal);
     const traversal = prepareGraphTraversal(input, schema, source, target, endpoints.values, method);
     const edgeIdColumn = getGraphEdgeIdColumn(schema, edgeId, method);
     const weightColumn = weight === undefined

package/esm/helpers/validateGraphRouteResultSchema.d.ts

@@ -1,4 +1,4 @@
 import type { TableSchema } from "./pendingOps.js";
 /** Validates that route result columns do not replace original input columns. */
-export default function validateGraphRouteResultSchema(schema: TableSchema, method: string, additionalResultColumns?: readonly string[]): void;
+export default function validateGraphRouteResultSchema(schema: TableSchema, method: string, additionalResultColumns?: readonly string[], includeTotal?: boolean): void;
 //# sourceMappingURL=validateGraphRouteResultSchema.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validateGraphRouteResultSchema.d.ts","sourceRoot":"","sources":["../../src/helpers/validateGraphRouteResultSchema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,iFAAiF;AACjF,MAAM,CAAC,OAAO,UAAU,8BAA8B,CACpD,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,uBAAuB,GAAE,SAAS,MAAM,EAAO,GAC9C,IAAI,CAkBN"}
+{"version":3,"file":"validateGraphRouteResultSchema.d.ts","sourceRoot":"","sources":["../../src/helpers/validateGraphRouteResultSchema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,iFAAiF;AACjF,MAAM,CAAC,OAAO,UAAU,8BAA8B,CACpD,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,uBAAuB,GAAE,SAAS,MAAM,EAAO,EAC/C,YAAY,UAAO,GAClB,IAAI,CAmBN"}

package/esm/helpers/validateGraphRouteResultSchema.js

@@ -2,8 +2,10 @@ import foldIdentifier from "./foldIdentifier.js";
 import quoteIdentifier from "./quoteIdentifier.js";
 const resultColumns = ["pathId", "step", "weight", "total"];
 /** Validates that route result columns do not replace original input columns. */
-export default function validateGraphRouteResultSchema(schema, method, additionalResultColumns = []) {
+export default function validateGraphRouteResultSchema(schema, method, additionalResultColumns = [], includeTotal = true) {
     for (const resultColumn of [...resultColumns, ...additionalResultColumns]) {
+        if (resultColumn === "total" && !includeTotal)
+            continue;
         const folded = foldIdentifier(resultColumn);
         const inputColumn = Object.keys(schema).find((column) => foldIdentifier(column) === folded);
         if (inputColumn !== undefined) {

package/esm/methods/distances.d.ts

@@ -7,7 +7,7 @@ type DistancesOptions = GraphTemporalOptions & {
     outputTable?: string | boolean;
     weight?: string;
     elapsedTime?: boolean;
-    minimize?: "weight" | "elapsedTime";
+    minimize?: "steps" | "weight" | "elapsedTime";
 };
 export default function distances(simpleTable: SimpleTable, sourceColumn: string, targetColumn: string, startNodes: GraphId | GraphId[], options?: DistancesOptions): SimpleTable;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"distances.d.ts","sourceRoot":"","sources":["../../src/methods/distances.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAOvD,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;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;CACrC,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,CA4Gb"}
+{"version":3,"file":"distances.d.ts","sourceRoot":"","sources":["../../src/methods/distances.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAOvD,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;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,aAAa,CAAC;CAC/C,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,CA+Gb"}

package/esm/methods/distances.js

@@ -59,7 +59,10 @@ export default function distances(simpleTable, sourceColumn, targetColumn, start
             return {
                 start: validated.idType,
                 node: validated.idType,
-                total: validated.distanceType,
+                steps: "BIGINT",
+                ...(options.weight === undefined
+                    ? {}
+                    : { total: validated.distanceType }),
                 ...(metrics.elapsedTime ? { elapsedTimeMs: "DOUBLE" } : {}),
             };
         },
@@ -84,12 +87,14 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
     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()");
-        if (metrics.elapsedTime) {
-            return elapsedDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, metrics.minimize);
-        }
-        return temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight);
+    const temporal = temporalOptions === undefined
+        ? undefined
+        : prepareGraphTemporalSql(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",
@@ -113,6 +118,14 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
     const edgeCost = `${quoteIdentifier("edges")}.${quoteIdentifier("__weight")}`;
     const bestDistance = `${quoteIdentifier("best")}.${quoteIdentifier("distance")}`;
     const candidateDistance = `CAST(${reachedDistance} + ${edgeCost} AS ${distanceType})`;
+    const candidateSteps = `${quoteIdentifier("reached")}.${quoteIdentifier("steps")} + 1`;
+    const bestSteps = `${quoteIdentifier("best")}.${quoteIdentifier("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}(${quoteIdentifier("start")}) AS (
       VALUES ${prepared.startValues}
     ), ${startsRelation} AS (
@@ -126,19 +139,20 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
     ), ${distancesRelation}(
       ${quoteIdentifier("start")}, ${quoteIdentifier("node")},
       ${quoteIdentifier("__start_key")}, ${quoteIdentifier("__node_key")},
-      ${quoteIdentifier("distance")}
+      ${quoteIdentifier("distance")}, ${quoteIdentifier("steps")}
     ) USING KEY(
       ${quoteIdentifier("__start_key")}, ${quoteIdentifier("__node_key")}
     ) AS (
       SELECT ${start}, ${edgeTo}, ${startKey}, ${edgeToKey},
-        MIN(${edgeCost}) AS ${quoteIdentifier("distance")}
+        MIN(${edgeCost}) AS ${quoteIdentifier("distance")}, CAST(1 AS BIGINT)
       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")}
+        ${selectedDistance} AS ${quoteIdentifier("distance")},
+        ${selectedSteps} AS ${quoteIdentifier("steps")}
       FROM ${distancesRelation} AS ${quoteIdentifier("reached")}
       INNER JOIN ${edgesRelation} AS ${quoteIdentifier("edges")}
         ON ${reachedNodeKey} = ${edgeFromKey}
@@ -146,111 +160,259 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
         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}
+        ${bestDistance}, ${bestSteps}
+      HAVING ${bestDistance} IS NULL OR
+        ${order(selectedDistance, selectedSteps)} < ${order(bestDistance, bestSteps)}
     )
     SELECT ${quoteIdentifier("start")}, ${quoteIdentifier("node")},
-      ${quoteIdentifier("distance")} AS ${quoteIdentifier("total")}
+      ${quoteIdentifier("steps")}${weight === undefined
+        ? ""
+        : `, ${quoteIdentifier("distance")} AS ${quoteIdentifier("total")}`}
     FROM ${distancesRelation}
-    ORDER BY ${quoteIdentifier("__start_key")}, ${quoteIdentifier("distance")}, ${quoteIdentifier("__node_key")}`;
+    ORDER BY ${quoteIdentifier("__start_key")}, ${quoteIdentifier(metrics.minimize === "steps" ? "steps" : "distance")}, ${quoteIdentifier("__node_key")}`;
 }
-function temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight) {
+function temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, minimize, includeTotal) {
     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);
+    const costStates = buildGraphTemporalCostStateSql(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("total")}
+    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("total")}, ${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")}`;
 }
-function elapsedDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, minimize) {
+// 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;
     const relations = prepared.relationNames([
         "graph_starts",
         "graph_temporal_settings",
         "graph_event_rows",
         "graph_edges",
-        "graph_elapsed_states",
-        "graph_elapsed_results",
+        "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 states = relations.graph_elapsed_states;
-    const results = relations.graph_elapsed_results;
+    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 anchor = temporal.journeyAnchor("edges", direction);
-    const reachedAnchor = ref("reached", "__anchor");
-    const candidateDistance = `CAST(${ref("reached", "distance")} + ${ref("edges", "__weight")} AS ${distanceType})`;
-    const order = minimize === "elapsedTime"
-        ? `${q("__elapsed")}, ${q("distance")}`
-        : `${q("distance")}, ${q("__elapsed")}`;
-    // A physical event and the first departure (last arrival for incoming
-    // traversal) fix elapsed time. Keep the cheapest cost for each such state;
-    // merging different anchors would lose later-departing, faster journeys.
-    // The state space is finite, and strict improvements terminate zero cycles.
-    return `WITH RECURSIVE ${settings} AS MATERIALIZED (
-      SELECT CAST(? AS HUGEINT) AS ${q("__gap")}
+    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"),
+        ...(temporal?.eventSelections("edges") ?? []),
     ])}
     ), ${edges} AS MATERIALIZED (
-      SELECT * FROM ${events} AS ${q("events")}
-      WHERE ${temporal.eventValidity("events")}
-    ), ${starts} 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")})
-    ), ${states}(
+    ), ${bounds.ctes}, ${summaries}(
       ${q("start")}, ${q("node")}, ${q("__start_key")}, ${q("__node_key")},
-      ${q("__event_id")}, ${q("__event_start")}, ${q("__event_end")},
-      ${q("__anchor")}, ${q("distance")}
-    ) USING KEY(${q("__start_key")}, ${q("__event_id")}, ${q("__anchor")}) AS (
+      ${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")},
-        ${ref("edges", "__event_id")}, ${ref("edges", "__event_start")},
-        ${ref("edges", "__event_end")}, ${anchor}, ${ref("edges", "__weight")}
+        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")},
-        ${ref("edges", "__event_id")}, ${ref("edges", "__event_start")},
-        ${ref("edges", "__event_end")}, ${reachedAnchor},
-        MIN(${candidateDistance}) AS ${q("distance")}
-      FROM ${states} AS ${q("reached")}
+        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")}
-      LEFT JOIN recurring.${states} AS ${q("best")}
-        ON ${ref("reached", "__start_key")} = ${ref("best", "__start_key")}
-        AND ${ref("edges", "__event_id")} = ${ref("best", "__event_id")}
-        AND ${reachedAnchor} = ${ref("best", "__anchor")}
-      WHERE ${temporal.transition("reached", "edges", direction, ref("settings", "__gap"))}
-      GROUP BY ${ref("reached", "start")}, ${ref("edges", "__to")},
-        ${ref("reached", "__start_key")}, ${ref("edges", "__to_key")},
-        ${ref("edges", "__event_id")}, ${ref("edges", "__event_start")},
-        ${ref("edges", "__event_end")}, ${reachedAnchor}, ${ref("best", "distance")}
-      HAVING ${ref("best", "distance")} IS NULL OR
-        MIN(${candidateDistance}) < ${ref("best", "distance")}
+      ${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 *, ${temporal.journeyElapsed("states", ref("states", "__anchor"), direction)} AS ${q("__elapsed")}
-      FROM ${states} AS ${q("states")}
+      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("distance")} AS ${q("total")},
-      ${temporal.elapsedMilliseconds(q("__elapsed"))} AS ${q("elapsedTimeMs")}
-    FROM ${results}
-    QUALIFY row_number() OVER (
-      PARTITION BY ${q("__start_key")}, ${q("__node_key")}
-      ORDER BY ${order}, ${q("__event_id")}, ${q("__anchor")}
-    ) = 1
-    ORDER BY ${q("__start_key")}, ${order}, ${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;
+    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/esm/methods/shortestPath.d.ts

@@ -7,7 +7,7 @@ type ShortestPathOptions = GraphTemporalOptions & {
     outputTable?: string | boolean;
     weight?: string;
     elapsedTime?: boolean;
-    minimize?: "weight" | "elapsedTime";
+    minimize?: "steps" | "weight" | "elapsedTime";
 };
 export default function shortestPath(simpleTable: SimpleTable, sourceColumn: string, targetColumn: string, edgeId: string, start: GraphId, end: GraphId, options?: ShortestPathOptions): SimpleTable;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"shortestPath.d.ts","sourceRoot":"","sources":["../../src/methods/shortestPath.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAMvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAShE,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAK1E,KAAK,mBAAmB,GAAG,oBAAoB,GAAG;IAChD,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;CACrC,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,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,mBAAwB,GAChC,WAAW,CAsHb"}
+{"version":3,"file":"shortestPath.d.ts","sourceRoot":"","sources":["../../src/methods/shortestPath.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAMvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAShE,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAK1E,KAAK,mBAAmB,GAAG,oBAAoB,GAAG;IAChD,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,aAAa,CAAC;CAC/C,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,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,mBAAwB,GAChC,WAAW,CAyHb"}