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

package/llm.md

@@ -1,7 +1,7 @@
 # The Simple Data Analysis (Core) Library
 
 - Package: `@nshiab/simple-data-analysis-core`
-- Version: `2.1.6`
+- Version: `2.1.8`
 
 To install the library with Deno, use:
 
@@ -3796,40 +3796,24 @@ await table
 
 #### `distances`
 
-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.
-
-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.
+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.
 
-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"`.
+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:
 
@@ -3845,7 +3829,7 @@ many connections are needed:
 ##### Signature
 
 ```typescript
-distances(sourceColumn: string, targetColumn: string, startNodes: string | number | bigint | (string | number | bigint)[], options?: { direction?: "outgoing" | "incoming" | "both"; endTimeColumn?: string; minGapMs?: number; outputTable?: string | boolean; startTimeColumn?: string; strictOrdering?: boolean; weight?: string }): SimpleTable;
+distances(sourceColumn: string, targetColumn: string, startNodes: string | number | bigint | (string | number | bigint)[], options?: { direction?: "outgoing" | "incoming" | "both"; elapsedTime?: boolean; endTimeColumn?: string; minGapMs?: number; minimize?: "steps" | "weight" | "elapsedTime"; outputTable?: string | boolean; startTimeColumn?: string; strictOrdering?: boolean; weight?: string }): SimpleTable;
 ```
 
 ##### Parameters
@@ -3854,12 +3838,14 @@ distances(sourceColumn: string, targetColumn: string, startNodes: string | numbe
   node ID.
 - **`targetColumn`**: The name of the column containing each connection's target
   node ID.
-- **`startNodes`**: One starting node ID or an array of distinct starting node
-  IDs.
+- **`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.
 - **`options`**: An optional object with direction, time, and result
   configuration.
 - **`options.direction`**: The direction in which to follow connections.
-  Defaults to `"outgoing"`.
+  Defaults to `"outgoing"`. Chronological traversal supports only `"outgoing"`
+  and `"incoming"`.
 - **`options.startTimeColumn`**: The name of the column containing each
   connection's start time. Use this or `endTimeColumn` to follow connections in
   chronological order.
@@ -3867,20 +3853,35 @@ distances(sourceColumn: string, targetColumn: string, startNodes: string | numbe
   connection's end time. Use this or `startTimeColumn` to follow connections in
   chronological order.
 - **`options.minGapMs`**: The minimum gap between consecutive connections, in
-  milliseconds. Must be a non-negative integer. Defaults to `0`. Requires a time
-  column.
+  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.
 - **`options.strictOrdering`**: Whether to reject zero-duration gaps between
   consecutive connections (equal timestamps). Defaults to `true`. Requires a
   time column.
 - **`options.weight`**: The name of the numeric column used as the cost of each
-  connection. If omitted, each connection costs one.
+  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.
+- **`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.
+- **`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.
 - **`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.
+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.
 
 ##### Examples
 
@@ -3890,12 +3891,12 @@ await connections
   .log();
 ```
 
-| start | node | distance |
-| ----- | ---- | -------: |
-| A     | B    |        1 |
-| A     | C    |        2 |
+| 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:
 
 ```ts
 await connections
@@ -3903,10 +3904,10 @@ await connections
   .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:
@@ -3917,11 +3918,11 @@ await connections
   .log();
 ```
 
-| start | node | distance |
-| ----- | ---- | -------: |
-| C     | B    |        1 |
-| C     | A    |        2 |
-| C     | D    |        2 |
+| start | node | steps |
+| ----- | ---- | ----: |
+| C     | B    |     1 |
+| C     | A    |     2 |
+| C     | D    |     2 |
 
 With `direction: "both"`, connections can be followed in either direction:
 
@@ -3931,14 +3932,14 @@ await connections
   .log();
 ```
 
-| start | node | distance |
-| ----- | ---- | -------: |
-| A     | B    |        1 |
-| A     | A    |        2 |
-| A     | C    |        2 |
-| A     | D    |        2 |
+| 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 and back.
+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:
 
@@ -3950,12 +3951,12 @@ await connections
   .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:
@@ -3975,14 +3976,14 @@ await connections
   .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 one-hour
-minimum exactly:
+Here, B → C leaves before A → B arrives, while B → D meets the one-hour minimum
+exactly:
 
 | origin | destination | departureTime    | arrivalTime      | minutes |
 | ------ | ----------- | ---------------- | ---------------- | ------: |
@@ -4001,10 +4002,127 @@ await scheduledFlights
   .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:
+
+```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:
+
+```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:
+
+```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:
+
+```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:
+
+```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 |
 
 #### `shortestPath`
 
@@ -4022,15 +4140,17 @@ Each connection needs a unique, non-null ID. Pass the name of the column
 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.
 
@@ -4045,6 +4165,16 @@ column, between their timestamps. The `strictOrdering` option defaults to
 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`.
 
@@ -4071,7 +4201,7 @@ connections. Two routes from A to E tie at three connections each:
 ##### Signature
 
 ```typescript
-shortestPath(sourceColumn: string, targetColumn: string, edgeId: string, start: string | number | bigint, end: string | number | bigint, options?: { direction?: "outgoing" | "incoming" | "both"; endTimeColumn?: string; minGapMs?: number; outputTable?: string | boolean; startTimeColumn?: string; strictOrdering?: boolean; weight?: string }): SimpleTable;
+shortestPath(sourceColumn: string, targetColumn: string, edgeId: string, start: string | number | bigint, end: string | number | bigint, options?: { direction?: "outgoing" | "incoming" | "both"; elapsedTime?: boolean; endTimeColumn?: string; minGapMs?: number; minimize?: "steps" | "weight" | "elapsedTime"; outputTable?: string | boolean; startTimeColumn?: string; strictOrdering?: boolean; weight?: string }): SimpleTable;
 ```
 
 ##### Parameters
@@ -4101,14 +4231,24 @@ shortestPath(sourceColumn: string, targetColumn: string, edgeId: string, start:
   consecutive connections (equal timestamps). Defaults to `true`. Requires a
   time column.
 - **`options.weight`**: The name of the numeric column used as the cost of each
-  connection. If omitted, each connection costs one.
+  connection. Adds `total`, the cumulative sum of those costs. If omitted, no
+  `total` column is generated.
+- **`options.elapsedTime`**: Whether to add cumulative `elapsedTimeMs` in
+  milliseconds, including connection gaps. Defaults to `false`. Requires both
+  time columns.
+- **`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.
 - **`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.
+The table of route connections with optional cumulative `total` and
+`elapsedTimeMs` metrics, so methods can be chained.
 
 ##### Examples
 
@@ -4118,14 +4258,14 @@ await connections
   .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:
 
@@ -4143,10 +4283,10 @@ await unnumberedConnections
   .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:
@@ -4183,9 +4323,9 @@ await flights
   .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 gap:
@@ -4228,9 +4368,84 @@ await reverseExample
   .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:
+
+```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:
+
+```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:
+
+```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 |
 
 #### `paths`
 
@@ -4292,7 +4507,7 @@ to D are returned:
 ##### Signature
 
 ```typescript
-paths(sourceColumn: string, targetColumn: string, edgeId: string, start: string | number | bigint, end: string | number | bigint, options?: { direction?: "outgoing" | "incoming" | "both"; endTimeColumn?: string; minGapMs?: number; outputTable?: string | boolean; startTimeColumn?: string; strictOrdering?: boolean; weight?: string }): SimpleTable;
+paths(sourceColumn: string, targetColumn: string, edgeId: string, start: string | number | bigint, end: string | number | bigint, options?: { direction?: "outgoing" | "incoming" | "both"; elapsedTime?: boolean; endTimeColumn?: string; minGapMs?: number; outputTable?: string | boolean; startTimeColumn?: string; strictOrdering?: boolean; weight?: string }): SimpleTable;
 ```
 
 ##### Parameters
@@ -4323,6 +4538,9 @@ paths(sourceColumn: string, targetColumn: string, edgeId: string, start: string
   time column.
 - **`options.weight`**: The name of the numeric column used as the cost of each
   connection. If omitted, each connection costs one.
+- **`options.elapsedTime`**: Whether to add cumulative `elapsedTimeMs` in
+  milliseconds, including connection gaps. Defaults to `false`. Requires both
+  time columns.
 - **`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`.
@@ -4473,6 +4691,57 @@ await scheduledFlights
 |      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:
+
+```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:
+
+```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 |
+
 #### `findCycles`
 
 Finds all cycles starting and ending at each node in `startNodes`. Pass one node
@@ -4546,7 +4815,7 @@ By default, connections are followed from source to target:
 ##### Signature
 
 ```typescript
-findCycles(sourceColumn: string, targetColumn: string, edgeId: string, startNodes: string | number | bigint | (string | number | bigint)[], options?: { direction?: "outgoing" | "incoming" | "both"; endTimeColumn?: string; minGapMs?: number; outputTable?: string | boolean; startTimeColumn?: string; strictOrdering?: boolean; weight?: string }): SimpleTable;
+findCycles(sourceColumn: string, targetColumn: string, edgeId: string, startNodes: string | number | bigint | (string | number | bigint)[], options?: { direction?: "outgoing" | "incoming" | "both"; elapsedTime?: boolean; endTimeColumn?: string; minGapMs?: number; outputTable?: string | boolean; startTimeColumn?: string; strictOrdering?: boolean; weight?: string }): SimpleTable;
 ```
 
 ##### Parameters
@@ -4577,6 +4846,9 @@ findCycles(sourceColumn: string, targetColumn: string, edgeId: string, startNode
   time column.
 - **`options.weight`**: The name of the numeric column used as the cost of each
   connection. If omitted, each connection costs one.
+- **`options.elapsedTime`**: Whether to add cumulative `elapsedTimeMs` in
+  milliseconds, including connection gaps. Defaults to `false`. Requires both
+  time columns.
 - **`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`.
@@ -4755,6 +5027,54 @@ await timedFlights
 | 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:
+
+```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:
+
+```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 |
+
 #### `extractDatePart`
 
 Extracts one or more components from a temporal column into new columns. Pass a