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

package/esm/class/SimpleTable.js

@@ -2770,26 +2770,23 @@ 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 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.
      *
      * 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.
+     * `node`, and `total` columns.
      *
-     * 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 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 distance is the shortest actual return
-     * route, using at least one connection. With `direction: "both"`, this
+     * 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
@@ -2825,12 +2822,12 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
+     * | start | node | total |
      * | --- | --- | ---: |
      * | 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,7 +2836,7 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
+     * | start | node | total |
      * | --- | --- | ---: |
      * | A | B | 4 |
      * | A | C | 5 |
@@ -2854,7 +2851,7 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
+     * | start | node | total |
      * | --- | --- | ---: |
      * | C | B | 1 |
      * | C | A | 2 |
@@ -2870,14 +2867,14 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
+     * | start | node | total |
      * | --- | --- | ---: |
      * | 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 a total of 2 because A → B → A follows a connection out
      * and back.
      *
      * An array of starting nodes gives separate distances for each start:
@@ -2891,7 +2888,7 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
+     * | start | node | total |
      * | --- | --- | ---: |
      * | A | B | 4 |
      * | A | C | 5 |
@@ -2917,7 +2914,7 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
+     * | start | node | total |
      * | --- | --- | ---: |
      * | A | B | 2 |
      * | A | A | 5 |
@@ -2944,11 +2941,68 @@ class SimpleTable extends Simple {
      *   .log();
      * ```
      *
-     * | start | node | distance |
+     * | start | node | total |
      * | --- | --- | ---: |
      * | A | B | 2 |
      * | A | D | 5 |
      *
+     * 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 |
+     *
+     * 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 | total | 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 | total | elapsedTimeMs |
+     * | --- | --- | ---: | ---: |
+     * | A | B | 40 | 3600000 |
+     * | A | C | 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.
+     *
      * @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.
@@ -2959,6 +3013,8 @@ 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.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.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
@@ -3156,6 +3212,63 @@ class SimpleTable extends Simple {
      * | ---: | ---: | ---: | ---: | --- | --- | --- |
      * | 0 | 1 | 1 | 1 | F1 | A | B |
      *
+     * 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 |
+     * | 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 | 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 |
+     *
+     * 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.
+     *
      * @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).
@@ -3168,6 +3281,8 @@ 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.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.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
@@ -3381,6 +3496,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 +3561,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 +3817,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 +3878,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
@@ -7096,23 +7316,24 @@ class SimpleTable extends Simple {
      * @example
      * ```ts
      * // Get GeoJSON data from a specific geometry column named 'myGeometries'
-     * const myGeomJson = await table.getGeoData("myGeometries");
+     * const myGeomJson = await table.getGeoData({ column: "myGeometries" });
      * console.log(myGeomJson);
      * ```
      *
      * @example
      * ```ts
      * // Get GeoJSON data and rewind polygon coordinates for D3.js compatibility
-     * const rewoundGeojson = await table.getGeoData(undefined, { rewind: true });
+     * const rewoundGeojson = await table.getGeoData({ rewind: true });
      * console.log(rewoundGeojson);
      * ```
-     * @param column - The name of the column storing the geometries. If omitted, the method will automatically attempt to find a geometry column.
      * @param options - An optional object with configuration options:
+     * @param options.column - The name of the column storing the geometries. If omitted, the table must have exactly one geometry column, which will be selected automatically.
      * @param options.rewind - If `true`, rewinds the coordinates of polygons to follow the spherical winding order (important for D3.js). Defaults to `false`.
      * @returns A promise that resolves to a GeoJSON object representing the table's geospatial data.
      * @category Getting Data
      */
-    async getGeoData(column, options = {}) {
+    async getGeoData(options = {}) {
+        let column = options.column;
         if (column === undefined) {
             column = await findGeoColumn(this, "getGeoData()");
         }

package/esm/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): TableSchema;
+export default function graphRouteResultSchema(schema: TableSchema, distanceType: string, method: string, elapsedTime?: boolean): TableSchema;
 //# sourceMappingURL=graphRouteResultSchema.d.ts.map

package/esm/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,GACb,WAAW,CASb"}
+{"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"}

package/esm/helpers/graphRouteResultSchema.js

@@ -1,12 +1,13 @@
 import validateGraphRouteResultSchema from "./validateGraphRouteResultSchema.js";
 /** Derives the route result schema while preserving input columns and types. */
-export default function graphRouteResultSchema(schema, distanceType, method) {
-    validateGraphRouteResultSchema(schema, method);
+export default function graphRouteResultSchema(schema, distanceType, method, elapsedTime = false) {
+    validateGraphRouteResultSchema(schema, method, elapsedTime ? ["elapsedTimeMs"] : []);
     return {
         pathId: "BIGINT",
         step: "BIGINT",
         weight: distanceType,
         total: distanceType,
+        ...(elapsedTime ? { elapsedTimeMs: "DOUBLE" } : {}),
         ...schema,
     };
 }

package/esm/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): string;
+export default function graphRouteResultSelect(rankedRelation: string, input: string, edgeIdColumn: GraphEdgeIdColumn, includeStart?: boolean, elapsedTime?: boolean): string;
 //# sourceMappingURL=graphRouteResultSelect.d.ts.map

package/esm/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,GACnB,MAAM,CAyBR"}
+{"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"}

package/esm/helpers/graphRouteResultSelect.js

@@ -1,6 +1,6 @@
 import quoteIdentifier from "./quoteIdentifier.js";
 /** Joins ranked route steps to their original input rows for final output. */
-export default function graphRouteResultSelect(rankedRelation, input, edgeIdColumn, includeStart = false) {
+export default function graphRouteResultSelect(rankedRelation, input, edgeIdColumn, includeStart = false, elapsedTime = false) {
     const q = quoteIdentifier;
     const routeStep = `${q("unnested")}.${q("route_step")}`;
     const originalEdgeId = `${q("original")}.${q(edgeIdColumn.column)}`;
@@ -13,6 +13,9 @@ export default function graphRouteResultSelect(rankedRelation, input, edgeIdColu
       CAST(${q("unnested")}.${q("step")} AS BIGINT) AS ${q("step")},
       ${routeStep}.${q("weight")} AS ${q("weight")},
       ${routeStep}.${q("distance")} AS ${q("total")},
+      ${elapsedTime
+        ? `${routeStep}.${q("elapsedTimeMs")} AS ${q("elapsedTimeMs")},`
+        : ""}
       ${q("original")}.*
     FROM ${rankedRelation} AS ${q("ranked")},
       UNNEST(${q("ranked")}.${q("steps")}) WITH ORDINALITY AS ${q("unnested")}(${q("route_step")}, ${q("step")})

package/esm/helpers/prepareGraphMetricOptions.d.ts

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

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

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

package/esm/helpers/prepareGraphMetricOptions.js

@@ -0,0 +1,40 @@
+/** Resolves graph cost selection separately from optional elapsed-time reporting. */
+export default function prepareGraphMetricOptions(options, method, optimize) {
+    if (options.elapsedTime !== undefined &&
+        typeof options.elapsedTime !== "boolean") {
+        throw new TypeError(`${method} options.elapsedTime must be a boolean.`);
+    }
+    const elapsedTime = options.elapsedTime === true;
+    if (elapsedTime &&
+        (options.startTimeColumn === undefined ||
+            options.endTimeColumn === undefined)) {
+        throw new TypeError(`${method} options.elapsedTime requires both options.startTimeColumn and options.endTimeColumn.`);
+    }
+    if (options.minimize !== undefined) {
+        if (!optimize) {
+            throw new TypeError(`${method} options.minimize is not supported because this method returns all routes.`);
+        }
+        if (options.minimize !== "weight" && options.minimize !== "elapsedTime") {
+            throw new TypeError(`${method} options.minimize must be "weight" or "elapsedTime".`);
+        }
+        if (options.minimize === "weight" && options.weight === undefined) {
+            throw new TypeError(`${method} options.minimize: "weight" requires options.weight.`);
+        }
+        if (options.minimize === "elapsedTime" && !elapsedTime) {
+            throw new TypeError(`${method} options.minimize: "elapsedTime" requires options.elapsedTime: true.`);
+        }
+    }
+    if (optimize && elapsedTime && options.weight !== undefined &&
+        options.minimize === undefined) {
+        throw new TypeError(`${method} when weight and elapsedTime are both enabled, specify options.minimize: "weight" or "elapsedTime".`);
+    }
+    return {
+        elapsedTime,
+        minimize: options.minimize ??
+            (options.weight !== undefined
+                ? "weight"
+                : elapsedTime
+                    ? "elapsedTime"
+                    : "connections"),
+    };
+}

package/esm/helpers/prepareGraphTemporalSql.d.ts

@@ -18,6 +18,9 @@ export type PreparedGraphTemporalSql = {
     eventValidity: (tableAlias?: string) => string;
     gapParameter: string;
     gapUnit: "microsecond" | "nanosecond";
+    journeyAnchor: (alias: string, direction: Exclude<GraphDirection, "both">) => string;
+    journeyElapsed: (alias: string, anchor: string, direction: Exclude<GraphDirection, "both">) => string;
+    elapsedMilliseconds: (elapsed: string) => string;
     startTimeColumn?: string;
     transition: (currentAlias: string, candidateAlias: string, direction: Exclude<GraphDirection, "both">, gapExpression: string) => string;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"prepareGraphTemporalSql.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareGraphTemporalSql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGjE,MAAM,MAAM,oBAAoB,GAAG;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IACnD,aAAa,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,aAAa,GAAG,YAAY,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,CACV,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,EAC1C,aAAa,EAAE,MAAM,KAClB,MAAM,CAAC;CACb,CAAC;AAWF,0EAA0E;AAC1E,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,cAAc,GAAG,SAAS,EACrC,MAAM,EAAE,MAAM,GACb,4BAA4B,GAAG,SAAS,CAkE1C;AAED,+EAA+E;AAC/E,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,4BAA4B,EACrC,MAAM,EAAE,MAAM,GACb,wBAAwB,CAwE1B"}
+{"version":3,"file":"prepareGraphTemporalSql.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareGraphTemporalSql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGjE,MAAM,MAAM,oBAAoB,GAAG;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IACnD,aAAa,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,aAAa,GAAG,YAAY,CAAC;IACtC,aAAa,EAAE,CACb,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,KACvC,MAAM,CAAC;IACZ,cAAc,EAAE,CACd,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,KACvC,MAAM,CAAC;IACZ,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,CACV,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,EAC1C,aAAa,EAAE,MAAM,KAClB,MAAM,CAAC;CACb,CAAC;AAWF,0EAA0E;AAC1E,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,cAAc,GAAG,SAAS,EACrC,MAAM,EAAE,MAAM,GACb,4BAA4B,GAAG,SAAS,CAkE1C;AAED,+EAA+E;AAC/E,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,4BAA4B,EACrC,MAAM,EAAE,MAAM,GACb,wBAAwB,CAgG1B"}

package/esm/helpers/prepareGraphTemporalSql.js

@@ -85,6 +85,13 @@ export default function prepareGraphTemporalSql(schema, options, method) {
         endTimeColumn: end?.column,
         gapParameter: gap.toString(),
         gapUnit,
+        journeyAnchor: (alias, direction) => direction === "outgoing"
+            ? temporalUnits(eventReference(alias, "__event_start"), startType, gapUnit)
+            : temporalUnits(eventReference(alias, "__event_end"), endType, gapUnit),
+        journeyElapsed: (alias, anchor, direction) => direction === "outgoing"
+            ? `(${temporalUnits(eventReference(alias, "__event_end"), endType, gapUnit)} - (${anchor}))`
+            : `((${anchor}) - ${temporalUnits(eventReference(alias, "__event_start"), startType, gapUnit)})`,
+        elapsedMilliseconds: (elapsed) => `(CAST(${elapsed} AS DOUBLE) / ${gapUnit === "nanosecond" ? 1000000 : 1000})`,
         eventSelections: (alias) => [
             `row_number() OVER () AS ${q("__event_id")}`,
             `${reference(alias, startColumn)} AS ${q("__event_start")}`,

package/esm/methods/distances.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"distances.d.ts","sourceRoot":"","sources":["../../src/methods/distances.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAIvD,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAA2B,EACzB,KAAK,OAAO,EAEb,MAAM,kCAAkC,CAAC;AAC1C,OAA8B,EAC5B,KAAK,cAAc,EAEpB,MAAM,qCAAqC,CAAC;AAK7C,KAAK,gBAAgB,GAAG,oBAAoB,GAAG;IAC7C,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,OAAO,GAAG,OAAO,EAAE,EAC/B,OAAO,GAAE,gBAAqB,GAC7B,WAAW,CAyGb"}
+{"version":3,"file":"distances.d.ts","sourceRoot":"","sources":["../../src/methods/distances.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAOvD,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAA2B,EACzB,KAAK,OAAO,EAEb,MAAM,kCAAkC,CAAC;AAC1C,OAA8B,EAC5B,KAAK,cAAc,EAEpB,MAAM,qCAAqC,CAAC;AAK7C,KAAK,gBAAgB,GAAG,oBAAoB,GAAG;IAC7C,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;CACrC,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,OAAO,GAAG,OAAO,EAAE,EAC/B,OAAO,GAAE,gBAAqB,GAC7B,WAAW,CA4Gb"}