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

package/script/class/SimpleTable.js

@@ -2776,38 +2776,23 @@ class SimpleTable extends Simple_js_1.default {
     }
     /**
      * Finds the shortest routes from each starting node to every reachable
-     * node and reports their total costs. By default, each connection costs
-     * one. Use the `weight` option to sum values from a numeric column, such
-     * as travel time or price.
+     * node. Without options, shortest means the fewest connections. Use `weight`
+     * to report total cost and `elapsedTime` to report duration including waiting
+     * between connections. Use `minimize` to choose which metric defines shortest.
      *
-     * The `direction` option lets you follow connections from source to target,
-     * from target to source, or in either direction. The result has `start`,
-     * `node`, and `total` columns.
-     *
-     * Each row gives the selected route's total cost from `start` to `node`.
-     * Intermediate steps along the route are not returned. To get the steps
-     * between two different nodes, use `shortestPath()` for the shortest routes
-     * or `paths()` for all routes without repeated nodes.
-     *
-     * A starting node appears in its own results only when a self-connection
-     * or a route leads back to it. Its total is the cost of the shortest actual
-     * return route, using at least one connection. With `direction: "both"`, this
-     * can mean following the same connection out and back.
-     *
-     * Unknown starting IDs and starts with no connections to follow produce
-     * no rows. Empty start arrays and duplicate starting IDs throw an error.
-     * Weights must be non-null, finite, and non-negative.
+     * Each row contains `start`, `node`, and `steps`, plus `total` when `weight`
+     * is supplied and `elapsedTimeMs` when enabled. Routes tied on the chosen
+     * metric produce separate rows only when their reported summaries differ;
+     * identical summaries appear once.
      *
-     * Use the `startTimeColumn` or `endTimeColumn` options to follow connections
-     * in chronological order. The `minGapMs` option sets the minimum gap between
-     * consecutive connections, in milliseconds. With both time columns, gaps are
-     * measured from one connection's end to the next connection's start; with one
-     * column, between their timestamps. The `strictOrdering` option defaults to
-     * `true`, rejecting zero-duration gaps. These options only work with
-     * `direction: "outgoing"` or `direction: "incoming"`.
+     * Routes cannot repeat nodes except for a final return to the start. A start
+     * appears in its own results only through an actual return or self-connection,
+     * never with zero steps. With `direction: "both"`, a return can follow the
+     * same connection out and back. Use `shortestPath()` to inspect individual
+     * connections between two different nodes.
      *
-     * The minimum gap applies only between consecutive connections, not before
-     * the first connection.
+     * Reporting weight or elapsed time can require substantial time and memory
+     * on dense networks because many routes may need to be explored.
      *
      * The next five examples each start with this data:
      *
@@ -2827,7 +2812,7 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | start | node | total |
+     * | start | node | steps |
      * | --- | --- | ---: |
      * | A | B | 1 |
      * | A | C | 2 |
@@ -2841,10 +2826,10 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | start | node | total |
-     * | --- | --- | ---: |
-     * | A | B | 4 |
-     * | A | C | 5 |
+     * | start | node | steps | total |
+     * | --- | --- | ---: | ---: |
+     * | A | B | 1 | 4 |
+     * | A | C | 2 | 5 |
      *
      * With `direction: "incoming"`, connections are followed from target to
      * source. Starting at C:
@@ -2856,7 +2841,7 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | start | node | total |
+     * | start | node | steps |
      * | --- | --- | ---: |
      * | C | B | 1 |
      * | C | A | 2 |
@@ -2872,14 +2857,14 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | start | node | total |
+     * | start | node | steps |
      * | --- | --- | ---: |
      * | A | B | 1 |
      * | A | A | 2 |
      * | A | C | 2 |
      * | A | D | 2 |
      *
-     * A appears with a total of 2 because A → B → A follows a connection out
+     * A appears with 2 steps because A → B → A follows a connection out
      * and back.
      *
      * An array of starting nodes gives separate distances for each start:
@@ -2893,12 +2878,12 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | start | node | total |
-     * | --- | --- | ---: |
-     * | A | B | 4 |
-     * | A | C | 5 |
-     * | D | B | 2 |
-     * | D | C | 3 |
+     * | start | node | steps | total |
+     * | --- | --- | ---: | ---: |
+     * | A | B | 1 | 4 |
+     * | A | C | 2 | 5 |
+     * | D | B | 1 | 2 |
+     * | D | C | 2 | 3 |
      *
      * A direct self-connection and a longer return route can both lead back
      * to the start. This example uses different data:
@@ -2919,13 +2904,13 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | start | node | total |
-     * | --- | --- | ---: |
-     * | A | B | 2 |
-     * | A | A | 5 |
+     * | start | node | steps | total |
+     * | --- | --- | ---: | ---: |
+     * | A | B | 1 | 2 |
+     * | A | A | 2 | 5 |
      *
      * Chronological options can rule out a cheaper sequence that departs too
-     * early. For this example, F2 leaves before F1 arrives, while F3 meets the
+     * early. Here, B → C leaves before A → B arrives, while B → D meets the
      * one-hour minimum exactly:
      *
      * | origin | destination | departureTime | arrivalTime | minutes |
@@ -2946,12 +2931,12 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | start | node | total |
-     * | --- | --- | ---: |
-     * | A | B | 2 |
-     * | A | D | 5 |
+     * | start | node | steps | total |
+     * | --- | --- | ---: | ---: |
+     * | A | B | 1 | 2 |
+     * | A | D | 2 | 5 |
      *
-     * For the next two examples, `flights` contains these rows, with departure
+     * For the next four examples, `flights` contains these rows, with departure
      * and arrival stored as timestamps on the same day:
      *
      * | flightId | origin | destination | departure | arrival | price |
@@ -2975,7 +2960,7 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | start | node | total | elapsedTimeMs |
+     * | start | node | steps | elapsedTimeMs |
      * | --- | --- | ---: | ---: |
      * | A | B | 1 | 3600000 |
      * | A | C | 1 | 10800000 |
@@ -2999,29 +2984,94 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | start | node | total | elapsedTimeMs |
-     * | --- | --- | ---: | ---: |
-     * | A | B | 40 | 3600000 |
-     * | A | C | 120 | 10800000 |
+     * | start | node | steps | total | elapsedTimeMs |
+     * | --- | --- | ---: | ---: | ---: |
+     * | A | B | 1 | 40 | 3600000 |
+     * | A | C | 1 | 120 | 10800000 |
      *
-     * Use `minimize: "weight"` to find the cheapest journeys instead.
-     * Equally fast journeys are ranked by price; equally cheap journeys
-     * are ranked by elapsed time.
+     * Use `minimize: "weight"` to find the cheapest journeys instead. The
+     * selected route to C now takes two steps through B and costs 80:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .distances("origin", "destination", "A", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *     weight: "price",
+     *     minimize: "weight",
+     *   })
+     *   .log();
+     * ```
+     *
+     * | start | node | steps | total | elapsedTimeMs |
+     * | --- | --- | ---: | ---: | ---: |
+     * | A | B | 1 | 40 | 3600000 |
+     * | A | C | 2 | 80 | 14400000 |
+     *
+     * Choose the fewest connections while still reporting price and elapsed
+     * time. The direct flight to C has one step, even though it costs more:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .distances("origin", "destination", "A", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *     weight: "price",
+     *     minimize: "steps",
+     *   })
+     *   .log();
+     * ```
+     *
+     * | start | node | steps | total | elapsedTimeMs |
+     * | --- | --- | ---: | ---: | ---: |
+     * | A | B | 1 | 40 | 3600000 |
+     * | A | C | 1 | 120 | 10800000 |
+     *
+     * When two routes to C both take two steps but have different prices,
+     * minimizing steps while reporting price returns both summaries:
+     *
+     * @example
+     * ```ts
+     * await connections
+     *   .loadArray([
+     *     { origin: "A", destination: "B", price: 20 },
+     *     { origin: "B", destination: "C", price: 30 },
+     *     { origin: "A", destination: "D", price: 40 },
+     *     { origin: "D", destination: "C", price: 40 },
+     *   ])
+     *   .distances("origin", "destination", "A", {
+     *     weight: "price",
+     *     minimize: "steps",
+     *   })
+     *   .filter("node = 'C'")
+     *   .log();
+     * ```
+     *
+     * | start | node | steps | total |
+     * | --- | --- | ---: | ---: |
+     * | A | C | 2 | 50 |
+     * | A | C | 2 | 80 |
      *
      * @param sourceColumn - The name of the column containing each connection's source node ID.
      * @param targetColumn - The name of the column containing each connection's target node ID.
-     * @param startNodes - One starting node ID or an array of distinct starting node IDs.
+     * @param startNodes - One starting node ID or a non-empty array of distinct IDs. Unknown IDs and starts with no connections to follow produce no rows. Empty arrays and duplicate IDs throw an error.
      * @param options - An optional object with direction, time, and result configuration.
-     * @param options.direction - The direction in which to follow connections. Defaults to `"outgoing"`.
+     * @param options.direction - The direction in which to follow connections. Defaults to `"outgoing"`. Chronological traversal supports only `"outgoing"` and `"incoming"`.
      * @param options.startTimeColumn - The name of the column containing each connection's start time. Use this or `endTimeColumn` to follow connections in chronological order.
      * @param options.endTimeColumn - The name of the column containing each connection's end time. Use this or `startTimeColumn` to follow connections in chronological order.
-     * @param options.minGapMs - The minimum gap between consecutive connections, in milliseconds. Must be a non-negative integer. Defaults to `0`. Requires a time column.
+     * @param options.minGapMs - The minimum gap between consecutive connections, in milliseconds; does not apply before the first connection. With both time columns, measured from one connection's end to the next's start; with one column, between timestamps. Must be a non-negative integer. Defaults to `0`. Requires a time column.
      * @param options.strictOrdering - Whether to reject zero-duration gaps between consecutive connections (equal timestamps). Defaults to `true`. Requires a time column.
-     * @param options.weight - The name of the numeric column used as the cost of each connection. If omitted, each connection costs one.
-     * @param options.elapsedTime - Whether to add cumulative `elapsedTimeMs` in milliseconds, including connection gaps. Defaults to `false`. Requires both time columns.
-     * @param options.minimize - The metric used to select optimal routes. Required when both `weight` and `elapsedTime` are enabled; otherwise inferred. The corresponding metric must be enabled.
+     * @param options.weight - The name of the numeric column used as the cost of each connection. Values must be non-null, finite, and non-negative. Adds `total`, the cumulative sum of those costs. If omitted, no `total` column is generated.
+     * @param options.elapsedTime - Whether to add cumulative `elapsedTimeMs` in milliseconds, including connection gaps. Defaults to `false`. Requires both time columns. Optimization compares native timestamp precision before conversion to milliseconds.
+     * @param options.minimize - The metric used to select optimal routes: `"steps"`, `"weight"`, or `"elapsedTime"`. Defaults to `"weight"` when only `weight` is enabled, `"elapsedTime"` when only elapsed-time reporting is enabled, and `"steps"` when neither is enabled. Required when both are enabled. `"steps"` is always available; the other metrics require their corresponding options.
      * @param options.outputTable - If `true`, stores the result in a new table with a generated name. If a string, uses it as the new table's name. If `false` or omitted, overwrites the current table. Defaults to `false`.
-     * @returns The result table, so methods can be chained.
+     * @returns The table of distinct optimal summaries with `start`, `node`, and `steps`, plus `total` when `weight` is supplied and `elapsedTimeMs` when enabled, so methods can be chained. Sorted by start, the chosen metric, node, then remaining metrics in the order steps, total, elapsed time.
      * @category Graph Operations
      */
     distances(sourceColumn, targetColumn, startNodes, options = {}) {
@@ -3042,15 +3092,17 @@ class SimpleTable extends Simple_js_1.default {
      * containing these IDs as the `edgeId` argument. If your table is missing
      * an ID column, you can easily create one with `addId()`.
      *
-     * The result starts with the `pathId`, `step`, `weight`, and `total`
-     * columns, followed by all original columns. Steps start at one and follow
-     * the search direction. The `weight` column is the connection cost, and
-     * `total` is the sum of those costs up to and including the current step.
-     * Without the `weight` option, each connection costs one.
+     * The result starts with `pathId`, `step`, and `weight`, followed by the
+     * optional metric columns and all original columns. Steps start at one and
+     * follow the search direction. The `weight` column is the connection cost,
+     * or one when no `weight` option is supplied. Supplying `weight` also adds
+     * `total`, the sum of those costs up to and including the current step.
+     * Enabling `elapsedTime` adds cumulative `elapsedTimeMs`, including gaps.
      *
-     * If an input column is already named `pathId`, `step`, `weight`, or `total`
-     * (regardless of capitalization), the method throws an error. Rename it
-     * with `renameColumns()` first.
+     * If an input column conflicts with a generated result column (regardless
+     * of capitalization), the method throws an error. Rename it with
+     * `renameColumns()` first. `total` is reserved only when `weight` is supplied,
+     * and `elapsedTimeMs` only when elapsed-time reporting is enabled.
      *
      * Each row is one connection along a route.
      *
@@ -3065,6 +3117,16 @@ class SimpleTable extends Simple_js_1.default {
      * The minimum gap applies only between consecutive connections, not before
      * the first connection.
      *
+     * Use `minimize: "steps"` to choose the fewest connections even when weight
+     * or elapsed-time reporting is enabled. Without an explicit `minimize`, the
+     * method minimizes weight when only `weight` is enabled, elapsed time when
+     * only `elapsedTime` is enabled, and steps when neither is enabled. With
+     * both enabled, specify `"steps"`, `"weight"`, or `"elapsedTime"` explicitly.
+     * Elapsed-time reporting requires both time columns.
+     *
+     * All routes tied on the selected metric are returned, even if their other
+     * metrics differ. Each route reports its own weights and elapsed times.
+     *
      * Routes are numbered from zero by comparing their sequences of connection
      * IDs, element by element. Rows are sorted by `pathId`, then `step`.
      *
@@ -3095,14 +3157,14 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | pathId | step | weight | total | edgeId | source | target |
-     * | ---: | ---: | ---: | ---: | --- | --- | --- |
-     * | 0 | 1 | 1 | 1 | E1 | A | B |
-     * | 0 | 2 | 1 | 2 | E3 | B | D |
-     * | 0 | 3 | 1 | 3 | E5 | D | E |
-     * | 1 | 1 | 1 | 1 | E2 | A | C |
-     * | 1 | 2 | 1 | 2 | E4 | C | D |
-     * | 1 | 3 | 1 | 3 | E5 | D | E |
+     * | pathId | step | weight | edgeId | source | target |
+     * | ---: | ---: | ---: | --- | --- | --- |
+     * | 0 | 1 | 1 | E1 | A | B |
+     * | 0 | 2 | 1 | E3 | B | D |
+     * | 0 | 3 | 1 | E5 | D | E |
+     * | 1 | 1 | 1 | E2 | A | C |
+     * | 1 | 2 | 1 | E4 | C | D |
+     * | 1 | 3 | 1 | E5 | D | E |
      *
      * For an input without connection IDs, use `addId()` first:
      *
@@ -3121,10 +3183,10 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | pathId | step | weight | total | source | target | edgeId |
-     * | ---: | ---: | ---: | ---: | --- | --- | --- |
-     * | 0 | 1 | 1 | 1 | A | B | edge-0 |
-     * | 0 | 2 | 1 | 2 | B | E | edge-1 |
+     * | pathId | step | weight | source | target | edgeId |
+     * | ---: | ---: | ---: | --- | --- | --- |
+     * | 0 | 1 | 1 | A | B | edge-0 |
+     * | 0 | 2 | 1 | B | E | edge-1 |
      *
      * The next two examples each start with these flights. The direct flight
      * takes ten minutes; the route through B and D takes three:
@@ -3164,9 +3226,9 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | pathId | step | weight | total | flightId | origin | destination | minutes |
-     * | ---: | ---: | ---: | ---: | --- | --- | --- | ---: |
-     * | 0 | 1 | 1 | 1 | F1 | A | E | 10 |
+     * | pathId | step | weight | flightId | origin | destination | minutes |
+     * | ---: | ---: | ---: | --- | --- | --- | ---: |
+     * | 0 | 1 | 1 | F1 | A | E | 10 |
      *
      * With time options, the cheaper route through B is ruled out because F2
      * leaves before F1 arrives. The route through C meets the one-hour minimum
@@ -3213,11 +3275,11 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | pathId | step | weight | total | edgeId | source | target |
-     * | ---: | ---: | ---: | ---: | --- | --- | --- |
-     * | 0 | 1 | 1 | 1 | F1 | A | B |
+     * | pathId | step | weight | edgeId | source | target |
+     * | ---: | ---: | ---: | --- | --- | --- |
+     * | 0 | 1 | 1 | F1 | A | B |
      *
-     * For the next two examples, `flights` contains these rows, with departure
+     * For the next three examples, `flights` contains these rows, with departure
      * and arrival stored as timestamps on the same day:
      *
      * | flightId | origin | destination | departure | arrival | price |
@@ -3242,10 +3304,10 @@ class SimpleTable extends Simple_js_1.default {
      *   .log();
      * ```
      *
-     * | pathId | step | weight | total | elapsedTimeMs | flightId | origin | destination | departure | arrival | price |
-     * | ---: | ---: | ---: | ---: | ---: | --- | --- | --- | --- | --- | ---: |
-     * | 0 | 1 | 1 | 1 | 1800000 | F4 | A | D | 2025-01-01 09:00:00 | 2025-01-01 09:30:00 | 60 |
-     * | 0 | 2 | 1 | 2 | 7200000 | F5 | D | C | 2025-01-01 10:30:00 | 2025-01-01 11:00:00 | 80 |
+     * | pathId | step | weight | elapsedTimeMs | flightId | origin | destination | departure | arrival | price |
+     * | ---: | ---: | ---: | ---: | --- | --- | --- | --- | --- | ---: |
+     * | 0 | 1 | 1 | 1800000 | F4 | A | D | 2025-01-01 09:00:00 | 2025-01-01 09:30:00 | 60 |
+     * | 0 | 2 | 1 | 7200000 | F5 | D | C | 2025-01-01 10:30:00 | 2025-01-01 11:00:00 | 80 |
      *
      * The route through D takes two hours (7,200,000 milliseconds), including
      * a one-hour layover. The direct flight takes three hours.
@@ -3274,6 +3336,27 @@ class SimpleTable extends Simple_js_1.default {
      * Use `minimize: "weight"` to find the cheapest journey instead.
      * All ties on the chosen metric are returned.
      *
+     * Choose the fewest flights while still reporting price and elapsed time.
+     * The direct flight takes one step, although the route through D is faster:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .shortestPath("origin", "destination", "flightId", "A", "C", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *     weight: "price",
+     *     minimize: "steps",
+     *   })
+     *   .log();
+     * ```
+     *
+     * | pathId | step | weight | total | elapsedTimeMs | flightId | origin | destination | departure | arrival | price |
+     * | ---: | ---: | ---: | ---: | ---: | --- | --- | --- | --- | --- | ---: |
+     * | 0 | 1 | 120 | 120 | 10800000 | F3 | A | C | 2025-01-01 09:00:00 | 2025-01-01 12:00:00 | 120 |
+     *
      * @param sourceColumn - The name of the column containing each connection's source node ID.
      * @param targetColumn - The name of the column containing each connection's target node ID.
      * @param edgeId - The name of the column uniquely identifying each connection (edge).
@@ -3285,11 +3368,11 @@ class SimpleTable extends Simple_js_1.default {
      * @param options.endTimeColumn - The name of the column containing each connection's end time. Use this or `startTimeColumn` to follow connections in chronological order.
      * @param options.minGapMs - The minimum gap between consecutive connections, in milliseconds. Must be a non-negative integer. Defaults to `0`. Requires a time column.
      * @param options.strictOrdering - Whether to reject zero-duration gaps between consecutive connections (equal timestamps). Defaults to `true`. Requires a time column.
-     * @param options.weight - The name of the numeric column used as the cost of each connection. If omitted, each connection costs one.
+     * @param options.weight - The name of the numeric column used as the cost of each connection. Adds `total`, the cumulative sum of those costs. If omitted, no `total` column is generated.
      * @param options.elapsedTime - Whether to add cumulative `elapsedTimeMs` in milliseconds, including connection gaps. Defaults to `false`. Requires both time columns.
-     * @param options.minimize - The metric used to select optimal routes. Required when both `weight` and `elapsedTime` are enabled; otherwise inferred. The corresponding metric must be enabled.
+     * @param options.minimize - The metric used to select optimal routes: `"steps"`, `"weight"`, or `"elapsedTime"`. Defaults to `"weight"` when only `weight` is enabled, `"elapsedTime"` when only elapsed-time reporting is enabled, and `"steps"` when neither is enabled. Required when both are enabled. `"steps"` is always available; the other metrics require their corresponding options.
      * @param options.outputTable - If `true`, stores the result in a new table with a generated name. If a string, uses it as the new table's name. If `false` or omitted, overwrites the current table. Defaults to `false`.
-     * @returns The result table, so methods can be chained.
+     * @returns The table of route connections with optional cumulative `total` and `elapsedTimeMs` metrics, so methods can be chained.
      * @category Graph Operations
      */
     shortestPath(sourceColumn, targetColumn, edgeId, start, end, options = {}) {
@@ -4646,7 +4729,7 @@ class SimpleTable extends Simple_js_1.default {
      * // Compare feature vectors and add a dataset-relative similarity score.
      * await table
      *   .similarityMahalanobis("features", [175, 70], "distance", {
-     *     similarityScoreColumn: "similarity",
+     *     similarityColumn: "similarity",
      *   })
      *   .log();
      * ```
@@ -4657,7 +4740,7 @@ class SimpleTable extends Simple_js_1.default {
      * const reference = await table.getRow("name === 'Alex'");
      * await table
      *   .similarityMahalanobis(["height", "weight"], reference, "distance", {
-     *     similarityScoreColumn: true,
+     *     similarityColumn: true,
      *   })
      *   .log();
      * ```
@@ -4665,7 +4748,7 @@ class SimpleTable extends Simple_js_1.default {
      * @param referencePoint - An array of finite numbers in feature order, or an object with an own finite numeric value for each scalar feature column; may be outside the dataset.
      * @param newColumn - The name of the new DOUBLE distance column.
      * @param options - Optional output settings.
-     * @param options.similarityScoreColumn - A custom name, or true for a new DOUBLE column named "similarity"; false or omitted adds no score. The dataset-relative
+     * @param options.similarityColumn - A custom name, or true for a new DOUBLE column named "similarity"; false or omitted adds no score. The dataset-relative
      * score is `1 - distance / maxDistance`. Exact matches score 1 and the farthest
      * rows score 0; if all distances are zero, every score is 1.
      * @returns The table, so methods can be chained.

package/script/helpers/buildGraphTemporalCostStateSql.d.ts

@@ -8,5 +8,5 @@ export type GraphTemporalCostStateSql = {
     withClause: string;
 };
 /** Builds keyed best-cost chronological states from an arbitrary start relation. */
-export default function buildGraphTemporalCostStateSql(prepared: PreparedGraphSql, startsSelect: string | ((validEdgesRelation: string) => string), direction: Exclude<GraphDirection, "both">, temporal: PreparedGraphTemporalSql, distanceType: string, edgeWeight: string, eventSelections?: string[]): GraphTemporalCostStateSql;
+export default function buildGraphTemporalCostStateSql(prepared: PreparedGraphSql, startsSelect: string | ((validEdgesRelation: string) => string), direction: Exclude<GraphDirection, "both">, temporal: PreparedGraphTemporalSql, distanceType: string, edgeWeight: string, eventSelections?: string[], minimize?: "weight" | "steps"): GraphTemporalCostStateSql;
 //# sourceMappingURL=buildGraphTemporalCostStateSql.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"buildGraphTemporalCostStateSql.d.ts","sourceRoot":"","sources":["../../src/helpers/buildGraphTemporalCostStateSql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EACjB,MAAM,4BAA4B,CAAC;AAGpC,MAAM,MAAM,yBAAyB,GAAG;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,oFAAoF;AACpF,MAAM,CAAC,OAAO,UAAU,8BAA8B,CACpD,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,MAAM,GAAG,CAAC,CAAC,kBAAkB,EAAE,MAAM,KAAK,MAAM,CAAC,EAC/D,SAAS,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,EAC1C,QAAQ,EAAE,wBAAwB,EAClC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,eAAe,GAAE,MAAM,EAAO,GAC7B,yBAAyB,CAuF3B"}
+{"version":3,"file":"buildGraphTemporalCostStateSql.d.ts","sourceRoot":"","sources":["../../src/helpers/buildGraphTemporalCostStateSql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EACjB,MAAM,4BAA4B,CAAC;AAGpC,MAAM,MAAM,yBAAyB,GAAG;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,oFAAoF;AACpF,MAAM,CAAC,OAAO,UAAU,8BAA8B,CACpD,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,MAAM,GAAG,CAAC,CAAC,kBAAkB,EAAE,MAAM,KAAK,MAAM,CAAC,EAC/D,SAAS,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,EAC1C,QAAQ,EAAE,wBAAwB,EAClC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,eAAe,GAAE,MAAM,EAAO,EAC9B,QAAQ,GAAE,QAAQ,GAAG,OAAkB,GACtC,yBAAyB,CAyG3B"}

package/script/helpers/buildGraphTemporalCostStateSql.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = buildGraphTemporalCostStateSql;
 const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
 /** Builds keyed best-cost chronological states from an arbitrary start relation. */
-function buildGraphTemporalCostStateSql(prepared, startsSelect, direction, temporal, distanceType, edgeWeight, eventSelections = []) {
+function buildGraphTemporalCostStateSql(prepared, startsSelect, direction, temporal, distanceType, edgeWeight, eventSelections = [], minimize = "weight") {
     const q = quoteIdentifier_js_1.default;
     const relations = prepared.relationNames([
         "graph_starts",
@@ -35,12 +35,26 @@ function buildGraphTemporalCostStateSql(prepared, startsSelect, direction, tempo
     const edgeCost = `${q("edges")}.${q("__weight")}`;
     const bestDistance = `${q("best")}.${q("distance")}`;
     const gap = `${q("settings")}.${q("__gap")}`;
-    const candidateDistance = `CAST(${reachedDistance} + ${edgeCost} AS ${distanceType})`;
+    const candidateSteps = `${q("reached")}.${q("steps")} + 1`;
+    // A steps-only bound must not sum reported weights: discarded routes can
+    // overflow even when every optimal route's reported total is representable.
+    const firstDistance = minimize === "steps" ? "CAST(1 AS BIGINT)" : edgeCost;
+    const candidateDistance = minimize === "steps"
+        ? candidateSteps
+        : `CAST(${reachedDistance} + ${edgeCost} AS ${distanceType})`;
+    const bestSteps = `${q("best")}.${q("steps")}`;
+    const order = (distance, steps) => 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})`;
     const resolvedStartsSelect = typeof startsSelect === "string"
         ? startsSelect
         : startsSelect(edgesRelation);
-    // Only costs for the same start and physical event can dominate each other.
-    // Strict improvements and non-negative weights terminate even zero-cost cycles.
+    // Only states for the same start and physical event can dominate each other.
+    // Weight optimization orders by cost then steps; step optimization counts
+    // only connections. Strict improvements terminate even zero-cost cycles.
     return {
         costRelation,
         edgesRelation,
@@ -64,17 +78,17 @@ function buildGraphTemporalCostStateSql(prepared, startsSelect, direction, tempo
       ${q("start")}, ${q("node")},
       ${q("__start_key")}, ${q("__node_key")},
       ${q("__event_id")}, ${q("__event_start")}, ${q("__event_end")},
-      ${q("distance")}
+      ${q("distance")}, ${q("steps")}
     ) USING KEY(${q("__start_key")}, ${q("__event_id")}) AS (
       SELECT ${start}, ${edgeTo}, ${startKey}, ${edgeToKey},
-        ${eventId}, ${eventStart}, ${eventEnd}, ${edgeCost}
+        ${eventId}, ${eventStart}, ${eventEnd}, ${firstDistance}, CAST(1 AS BIGINT)
       FROM ${startsRelation} AS ${q("starts")}
       INNER JOIN ${edgesRelation} AS ${q("edges")}
         ON ${startKey} = ${edgeFromKey}
       UNION
       SELECT ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
         ${eventId}, ${eventStart}, ${eventEnd},
-        MIN(${candidateDistance}) AS ${q("distance")}
+        ${selectedDistance} AS ${q("distance")}, ${selectedSteps} AS ${q("steps")}
       FROM ${costRelation} AS ${q("reached")}
       INNER JOIN ${edgesRelation} AS ${q("edges")}
         ON ${reachedNodeKey} = ${edgeFromKey}
@@ -84,9 +98,9 @@ function buildGraphTemporalCostStateSql(prepared, startsSelect, direction, tempo
         AND ${eventId} = ${q("best")}.${q("__event_id")}
       WHERE ${temporal.transition("reached", "edges", direction, gap)}
       GROUP BY ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
-        ${eventId}, ${eventStart}, ${eventEnd}, ${bestDistance}
+        ${eventId}, ${eventStart}, ${eventEnd}, ${bestDistance}, ${bestSteps}
       HAVING ${bestDistance} IS NULL OR
-        MIN(${candidateDistance}) < ${bestDistance}
+        ${order(selectedDistance, selectedSteps)} < ${order(bestDistance, bestSteps)}
     )`,
     };
 }

package/script/helpers/graphRouteResultSchema.d.ts

@@ -1,4 +1,4 @@
 import type { TableSchema } from "./pendingOps.js";
 /** Derives the route result schema while preserving input columns and types. */
-export default function graphRouteResultSchema(schema: TableSchema, distanceType: string, method: string, elapsedTime?: boolean): TableSchema;
+export default function graphRouteResultSchema(schema: TableSchema, distanceType: string, method: string, elapsedTime?: boolean, includeTotal?: boolean): TableSchema;
 //# sourceMappingURL=graphRouteResultSchema.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"graphRouteResultSchema.d.ts","sourceRoot":"","sources":["../../src/helpers/graphRouteResultSchema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,gFAAgF;AAChF,MAAM,CAAC,OAAO,UAAU,sBAAsB,CAC5C,MAAM,EAAE,WAAW,EACnB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,WAAW,UAAQ,GAClB,WAAW,CAcb"}
+{"version":3,"file":"graphRouteResultSchema.d.ts","sourceRoot":"","sources":["../../src/helpers/graphRouteResultSchema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,gFAAgF;AAChF,MAAM,CAAC,OAAO,UAAU,sBAAsB,CAC5C,MAAM,EAAE,WAAW,EACnB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,WAAW,UAAQ,EACnB,YAAY,UAAO,GAClB,WAAW,CAeb"}

package/script/helpers/graphRouteResultSchema.js

@@ -6,13 +6,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = graphRouteResultSchema;
 const validateGraphRouteResultSchema_js_1 = __importDefault(require("./validateGraphRouteResultSchema.js"));
 /** Derives the route result schema while preserving input columns and types. */
-function graphRouteResultSchema(schema, distanceType, method, elapsedTime = false) {
-    (0, validateGraphRouteResultSchema_js_1.default)(schema, method, elapsedTime ? ["elapsedTimeMs"] : []);
+function graphRouteResultSchema(schema, distanceType, method, elapsedTime = false, includeTotal = true) {
+    (0, validateGraphRouteResultSchema_js_1.default)(schema, method, elapsedTime ? ["elapsedTimeMs"] : [], includeTotal);
     return {
         pathId: "BIGINT",
         step: "BIGINT",
         weight: distanceType,
-        total: distanceType,
+        ...(includeTotal ? { total: distanceType } : {}),
         ...(elapsedTime ? { elapsedTimeMs: "DOUBLE" } : {}),
         ...schema,
     };

package/script/helpers/graphRouteResultSelect.d.ts

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

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

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

package/script/helpers/graphRouteResultSelect.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = graphRouteResultSelect;
 const quoteIdentifier_js_1 = __importDefault(require("./quoteIdentifier.js"));
 /** Joins ranked route steps to their original input rows for final output. */
-function graphRouteResultSelect(rankedRelation, input, edgeIdColumn, includeStart = false, elapsedTime = false) {
+function graphRouteResultSelect(rankedRelation, input, edgeIdColumn, includeStart = false, elapsedTime = false, includeTotal = true) {
     const q = quoteIdentifier_js_1.default;
     const routeStep = `${q("unnested")}.${q("route_step")}`;
     const originalEdgeId = `${q("original")}.${q(edgeIdColumn.column)}`;
@@ -18,7 +18,7 @@ function graphRouteResultSelect(rankedRelation, input, edgeIdColumn, includeStar
     return `SELECT ${includeStart ? `${q("ranked")}.${q("start")},\n      ` : ""}${q("ranked")}.${q("pathId")},
       CAST(${q("unnested")}.${q("step")} AS BIGINT) AS ${q("step")},
       ${routeStep}.${q("weight")} AS ${q("weight")},
-      ${routeStep}.${q("distance")} AS ${q("total")},
+      ${includeTotal ? `${routeStep}.${q("distance")} AS ${q("total")},` : ""}
       ${elapsedTime
         ? `${routeStep}.${q("elapsedTimeMs")} AS ${q("elapsedTimeMs")},`
         : ""}

package/script/helpers/prepareGraphMetricOptions.d.ts

@@ -1,13 +1,13 @@
 export type GraphMetricOptions = {
     elapsedTime?: boolean;
-    minimize?: "weight" | "elapsedTime";
+    minimize?: "steps" | "weight" | "elapsedTime";
     weight?: string;
     startTimeColumn?: string;
     endTimeColumn?: string;
 };
 export type PreparedGraphMetricOptions = {
     elapsedTime: boolean;
-    minimize: "weight" | "elapsedTime" | "connections";
+    minimize: "steps" | "weight" | "elapsedTime";
 };
 /** Resolves graph cost selection separately from optional elapsed-time reporting. */
 export default function prepareGraphMetricOptions(options: GraphMetricOptions, method: string, optimize: boolean): PreparedGraphMetricOptions;