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

package/esm/class/SimpleTable.js

@@ -2770,42 +2770,24 @@ class SimpleTable extends Simple {
         return topologicalSort(this, sourceColumn, targetColumn, options);
     }
     /**
-     * Finds the shortest distance from each starting node to every node it can
-     * reach by following one or more connections. By default, distance is the
-     * number of connections along the shortest route. Use the `weight` option
-     * to find the smallest sum of values from a numeric column, such as travel
-     * time.
+     * Finds the shortest routes from each starting node to every reachable
+     * 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 `distance` columns, sorted by `start`, then by increasing
-     * `distance`, then by `node` to break ties. The closest nodes appear first
-     * for each start.
-     *
-     * Each row gives the shortest distance 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.
+     * 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.
      *
-     * A starting node appears in its own results only when a self-connection
-     * or a route leads back to it. Its distance is the shortest actual return
-     * route, using at least one connection. With `direction: "both"`, this
-     * can mean following the same connection out and back.
+     * 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.
      *
-     * 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.
-     *
-     * 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"`.
-     *
-     * 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:
      *
@@ -2825,12 +2807,12 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
+     * | start | node | steps |
      * | --- | --- | ---: |
      * | A | B | 1 |
      * | A | C | 2 |
      *
-     * With `weight: "minutes"`, distance is the shortest total travel time:
+     * With `weight: "minutes"`, `total` is the sum of travel times:
      *
      * @example
      * ```ts
@@ -2839,10 +2821,10 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
-     * | --- | --- | ---: |
-     * | 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:
@@ -2854,7 +2836,7 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
+     * | start | node | steps |
      * | --- | --- | ---: |
      * | C | B | 1 |
      * | C | A | 2 |
@@ -2870,14 +2852,14 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
+     * | start | node | steps |
      * | --- | --- | ---: |
      * | A | B | 1 |
      * | A | A | 2 |
      * | A | C | 2 |
      * | A | D | 2 |
      *
-     * A appears at distance 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:
@@ -2891,12 +2873,12 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
-     * | --- | --- | ---: |
-     * | 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:
@@ -2917,13 +2899,13 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
-     * | --- | --- | ---: |
-     * | 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 |
@@ -2944,23 +2926,147 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
-     * | --- | --- | ---: |
-     * | A | B | 2 |
-     * | A | D | 5 |
+     * | start | node | steps | total |
+     * | --- | --- | ---: | ---: |
+     * | A | B | 1 | 2 |
+     * | A | D | 2 | 5 |
+     *
+     * 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 |
+     * | --- | --- | --- | --- | --- | ---: |
+     * | F1 | A | B | 2025-01-01 09:00 | 2025-01-01 10:00 | 40 |
+     * | F2 | B | C | 2025-01-01 12:00 | 2025-01-01 13:00 | 40 |
+     * | F3 | A | C | 2025-01-01 09:00 | 2025-01-01 12:00 | 120 |
+     *
+     * Find the fastest journey from A to each reachable destination, including
+     * layovers:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .distances("origin", "destination", "A", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *   })
+     *   .log();
+     * ```
+     *
+     * | start | node | steps | elapsedTimeMs |
+     * | --- | --- | ---: | ---: |
+     * | A | B | 1 | 3600000 |
+     * | A | C | 1 | 10800000 |
+     *
+     * The direct flight to C takes three hours (10,800,000 milliseconds).
+     * The route through B takes four hours including its layover.
+     *
+     * Find the fastest journeys from A while also adding up their prices:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .distances("origin", "destination", "A", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *     weight: "price",
+     *     minimize: "elapsedTime",
+     *   })
+     *   .log();
+     * ```
+     *
+     * | start | node | steps | total | elapsedTimeMs |
+     * | --- | --- | ---: | ---: | ---: |
+     * | A | B | 1 | 40 | 3600000 |
+     * | A | C | 1 | 120 | 10800000 |
+     *
+     * 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.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 = {}) {
@@ -2981,15 +3087,17 @@ class SimpleTable extends Simple {
      * 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.
      *
@@ -3004,6 +3112,16 @@ class SimpleTable extends Simple {
      * 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`.
      *
@@ -3034,14 +3152,14 @@ class SimpleTable extends Simple {
      *   .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:
      *
@@ -3060,10 +3178,10 @@ class SimpleTable extends Simple {
      *   .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:
@@ -3103,9 +3221,9 @@ class SimpleTable extends Simple {
      *   .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
@@ -3152,9 +3270,87 @@ class SimpleTable extends Simple {
      *   .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 three examples, `flights` contains these rows, with departure
+     * and arrival stored as timestamps on the same day:
+     *
+     * | flightId | origin | destination | departure | arrival | price |
+     * | --- | --- | --- | --- | --- | ---: |
+     * | F1 | A | B | 2025-01-01 09:00 | 2025-01-01 10:00 | 40 |
+     * | F2 | B | C | 2025-01-01 12:00 | 2025-01-01 13:00 | 40 |
+     * | F3 | A | C | 2025-01-01 09:00 | 2025-01-01 12:00 | 120 |
+     * | F4 | A | D | 2025-01-01 09:00 | 2025-01-01 09:30 | 60 |
+     * | F5 | D | C | 2025-01-01 10:30 | 2025-01-01 11:00 | 80 |
+     *
+     * Find the fastest journey from A to C, including layovers:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .shortestPath("origin", "destination", "flightId", "A", "C", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *   })
+     *   .log();
+     * ```
+     *
+     * | 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.
+     *
+     * Find the fastest journey while also adding up its price:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .shortestPath("origin", "destination", "flightId", "A", "C", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *     weight: "price",
+     *     minimize: "elapsedTime",
+     *   })
+     *   .log();
+     * ```
+     *
+     * | pathId | step | weight | total | elapsedTimeMs | flightId | origin | destination | departure | arrival | price |
+     * | ---: | ---: | ---: | ---: | ---: | --- | --- | --- | --- | --- | ---: |
+     * | 0 | 1 | 60 | 60 | 1800000 | F4 | A | D | 2025-01-01 09:00:00 | 2025-01-01 09:30:00 | 60 |
+     * | 0 | 2 | 80 | 140 | 7200000 | F5 | D | C | 2025-01-01 10:30:00 | 2025-01-01 11:00:00 | 80 |
+     *
+     * 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.
@@ -3167,9 +3363,11 @@ class SimpleTable extends Simple {
      * @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: `"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 = {}) {
@@ -3381,6 +3579,59 @@ class SimpleTable extends Simple {
      * | 0 | 1 | 3 | 3 | F3 | B | D | 2025-01-01 11:00:00 | 2025-01-01 12:00:00 | 3 |
      * | 0 | 2 | 2 | 5 | F1 | A | B | 2025-01-01 08:00:00 | 2025-01-01 10:00:00 | 2 |
      *
+     * For the next two examples, `flights` contains these rows, with departure
+     * and arrival stored as timestamps on the same day:
+     *
+     * | flightId | origin | destination | departure | arrival | price |
+     * | --- | --- | --- | --- | --- | ---: |
+     * | F1 | A | B | 2025-01-01 09:00 | 2025-01-01 10:00 | 40 |
+     * | F2 | B | C | 2025-01-01 12:00 | 2025-01-01 13:00 | 40 |
+     * | F3 | A | C | 2025-01-01 09:00 | 2025-01-01 12:00 | 120 |
+     *
+     * Report elapsed time for every path, including layovers:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .paths("origin", "destination", "flightId", "A", "C", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *   })
+     *   .log();
+     * ```
+     *
+     * | pathId | step | weight | total | elapsedTimeMs | flightId | origin | destination | departure | arrival | price |
+     * | ---: | ---: | ---: | ---: | ---: | --- | --- | --- | --- | --- | ---: |
+     * | 0 | 1 | 1 | 1 | 3600000 | F1 | A | B | 2025-01-01 09:00:00 | 2025-01-01 10:00:00 | 40 |
+     * | 0 | 2 | 1 | 2 | 14400000 | F2 | B | C | 2025-01-01 12:00:00 | 2025-01-01 13:00:00 | 40 |
+     * | 1 | 1 | 1 | 1 | 10800000 | F3 | A | C | 2025-01-01 09:00:00 | 2025-01-01 12:00:00 | 120 |
+     *
+     * The route through B takes four hours (14,400,000 milliseconds),
+     * including its two-hour layover. The direct flight takes three hours.
+     *
+     * Add up prices while continuing to report elapsed time for every path:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .paths("origin", "destination", "flightId", "A", "C", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *     weight: "price",
+     *   })
+     *   .log();
+     * ```
+     *
+     * | pathId | step | weight | total | elapsedTimeMs | flightId | origin | destination | departure | arrival | price |
+     * | ---: | ---: | ---: | ---: | ---: | --- | --- | --- | --- | --- | ---: |
+     * | 0 | 1 | 40 | 40 | 3600000 | F1 | A | B | 2025-01-01 09:00:00 | 2025-01-01 10:00:00 | 40 |
+     * | 0 | 2 | 40 | 80 | 14400000 | F2 | B | C | 2025-01-01 12:00:00 | 2025-01-01 13:00:00 | 40 |
+     * | 1 | 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).
@@ -3393,6 +3644,7 @@ class SimpleTable extends Simple {
      * @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.elapsedTime - Whether to add cumulative `elapsedTimeMs` in milliseconds, including connection gaps. Defaults to `false`. Requires both time columns.
      * @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.
      * @category Graph Operations
@@ -3648,6 +3900,56 @@ class SimpleTable extends Simple {
      * | B | 0 | 2 | 1 | 2 | F2 | C | A | 2025-01-01 10:00:00 |
      * | B | 0 | 3 | 1 | 3 | F1 | B | C | 2025-01-01 09:00:00 |
      *
+     * For the next two examples, `flights` contains these rows, with departure
+     * and arrival stored as timestamps on the same day:
+     *
+     * | flightId | origin | destination | departure | arrival | price |
+     * | --- | --- | --- | --- | --- | ---: |
+     * | F1 | A | B | 2025-01-01 09:00 | 2025-01-01 10:00 | 40 |
+     * | F2 | B | A | 2025-01-01 12:00 | 2025-01-01 13:00 | 60 |
+     *
+     * Report elapsed time for every cycle, including layovers:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .findCycles("origin", "destination", "flightId", "A", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *   })
+     *   .log();
+     * ```
+     *
+     * | start | pathId | step | weight | total | elapsedTimeMs | flightId | origin | destination | departure | arrival | price |
+     * | --- | ---: | ---: | ---: | ---: | ---: | --- | --- | --- | --- | --- | ---: |
+     * | A | 0 | 1 | 1 | 1 | 3600000 | F1 | A | B | 2025-01-01 09:00:00 | 2025-01-01 10:00:00 | 40 |
+     * | A | 0 | 2 | 1 | 2 | 14400000 | F2 | B | A | 2025-01-01 12:00:00 | 2025-01-01 13:00:00 | 60 |
+     *
+     * The return journey takes four hours (14,400,000 milliseconds),
+     * including the two-hour layover at B.
+     *
+     * Add up prices while continuing to report elapsed time for every cycle:
+     *
+     * @example
+     * ```ts
+     * await flights
+     *   .findCycles("origin", "destination", "flightId", "A", {
+     *     startTimeColumn: "departure",
+     *     endTimeColumn: "arrival",
+     *     minGapMs: 60 * 60 * 1000,
+     *     elapsedTime: true,
+     *     weight: "price",
+     *   })
+     *   .log();
+     * ```
+     *
+     * | start | pathId | step | weight | total | elapsedTimeMs | flightId | origin | destination | departure | arrival | price |
+     * | --- | ---: | ---: | ---: | ---: | ---: | --- | --- | --- | --- | --- | ---: |
+     * | A | 0 | 1 | 40 | 40 | 3600000 | F1 | A | B | 2025-01-01 09:00:00 | 2025-01-01 10:00:00 | 40 |
+     * | A | 0 | 2 | 60 | 100 | 14400000 | F2 | B | A | 2025-01-01 12:00:00 | 2025-01-01 13:00:00 | 60 |
+     *
      * @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).
@@ -3659,6 +3961,7 @@ class SimpleTable extends Simple {
      * @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.elapsedTime - Whether to add cumulative `elapsedTimeMs` in milliseconds, including connection gaps. Defaults to `false`. Requires both time columns.
      * @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.
      * @category Graph Operations

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