Release v0.7.0

Add buildGraph() for building a directed stop-to-stop graph from a set of
trips. Edges are deduplicated; each edge carries the originating trips with
route_id and direction_id. Uses LEAD() so non-contiguous stop_sequence
values are handled correctly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: chtitux

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Upcoming release
 
+## 0.7.0
+
+- Add `buildGraph(tripIds)` method and `Graph` / `EdgeTrip` / `EdgeData` types. Builds a directed stop-to-stop graph from the given trips, with each deduplicated edge carrying the list of originating trips (plus `route_id` and `direction_id`). Handles non-contiguous `stop_sequence` values via `LEAD()`. Helpers `edgeCount()` and `edges()` are also exported.
+
 ## 0.6.0
 
 ### Breaking changes — pluggable database adapter

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gtfs-sqljs",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Load GTFS data into a SQLite database (sql.js / better-sqlite3 / op-sqlite / expo-sqlite) via a pluggable adapter",
   "type": "module",
   "main": "./dist/index.js",

src/gtfs-sqljs.ts

@@ -28,6 +28,7 @@ import {
 } from './queries/calendar';
 import { getTrips, type TripFilters, type TripWithRealtime } from './queries/trips';
 import { getStopTimes, buildOrderedStopList, type StopTimeFilters, type StopTimeWithRealtime } from './queries/stop-times';
+import { buildGraph, type Graph } from './queries/graph';
 import { getShapes, getShapesToGeojson, type ShapeFilters, type GeoJsonFeatureCollection } from './queries/shapes';
 import { getAlerts as getAlertsQuery, getAllAlerts, type AlertFilters } from './queries/rt-alerts';
 import { getVehiclePositions as getVehiclePositionsQuery, getAllVehiclePositions, type VehiclePositionFilters } from './queries/rt-vehicle-positions';
@@ -766,6 +767,18 @@ export class GtfsSqlJs {
     return buildOrderedStopList(this.db, tripIds);
   }
 
+  /**
+   * Build a directed stop-to-stop graph for the given trips.
+   *
+   * Edges connect consecutive stops in a trip (paired via `stop_sequence`,
+   * whose values need not be contiguous). Each edge carries the list of
+   * trips traversing it, with route_id and direction_id attached.
+   */
+  async buildGraph(tripIds: string[]): Promise<Graph> {
+    if (!this.db) throw new Error('Database not initialized');
+    return buildGraph(this.db, tripIds);
+  }
+
   // ==================== Realtime Methods ====================
 
   /**

src/index.ts

@@ -36,6 +36,14 @@ export type {
 } from './adapters/types';
 export { ExportNotSupportedError } from './adapters/types';
 
+// Export graph types
+export type {
+  EdgeTrip,
+  EdgeData,
+  Graph,
+} from './queries/graph';
+export { edgeCount, edges } from './queries/graph';
+
 // Export GTFS types
 export type {
   Agency,

src/queries/graph.ts

@@ -0,0 +1,113 @@
+/**
+ * Graph query methods
+ *
+ * Build a directed graph from GTFS trips: nodes are stops, edges connect
+ * consecutive stops within a trip (ordered by `stop_sequence`, which is only
+ * guaranteed monotonic — gaps are allowed). Edges are deduplicated; each
+ * edge carries the list of trips that traverse it, so callers can recover
+ * frequency, route, and direction information without a second query.
+ */
+
+import type { GtfsDatabase } from '../adapters/types';
+
+export interface EdgeTrip {
+  tripId: string;
+  routeId: string;
+  directionId: number | null;
+}
+
+export interface EdgeData {
+  trips: EdgeTrip[];
+}
+
+/** Directed graph: from stop_id -> to stop_id -> edge data. */
+export type Graph = Map<string, Map<string, EdgeData>>;
+
+/**
+ * Build a directed stop-to-stop graph for the given trips.
+ *
+ * - Uses `LEAD()` to pair each stop with its successor in `stop_sequence`
+ *   order, so non-contiguous sequences (e.g. 1, 5, 10) are handled correctly.
+ * - Edges are deduplicated on `(from, to)`; per-edge `trips[]` preserves the
+ *   originating trip/route/direction.
+ * - A trip that traverses the same edge twice (e.g. a loop) contributes two
+ *   entries in `trips[]`.
+ * - An empty `tripIds` array returns an empty graph without touching the DB.
+ */
+export async function buildGraph(
+  db: GtfsDatabase,
+  tripIds: string[]
+): Promise<Graph> {
+  const graph: Graph = new Map();
+  if (tripIds.length === 0) return graph;
+
+  const placeholders = tripIds.map(() => '?').join(', ');
+  const sql = `
+    WITH ordered AS (
+      SELECT st.trip_id,
+             st.stop_id,
+             LEAD(st.stop_id) OVER (
+               PARTITION BY st.trip_id ORDER BY st.stop_sequence
+             ) AS next_stop,
+             t.route_id,
+             t.direction_id
+      FROM stop_times st
+      INNER JOIN trips t ON st.trip_id = t.trip_id
+      WHERE st.trip_id IN (${placeholders})
+    )
+    SELECT stop_id AS from_stop,
+           next_stop AS to_stop,
+           trip_id,
+           route_id,
+           direction_id
+    FROM ordered
+    WHERE next_stop IS NOT NULL
+  `;
+
+  const stmt = await db.prepare(sql);
+  await stmt.bind(tripIds);
+
+  while (await stmt.step()) {
+    const row = await stmt.getAsObject();
+    const from = String(row.from_stop);
+    const to = String(row.to_stop);
+    const edgeTrip: EdgeTrip = {
+      tripId: String(row.trip_id),
+      routeId: String(row.route_id),
+      directionId: row.direction_id !== null ? Number(row.direction_id) : null,
+    };
+
+    let inner = graph.get(from);
+    if (!inner) {
+      inner = new Map();
+      graph.set(from, inner);
+    }
+    let edge = inner.get(to);
+    if (!edge) {
+      edge = { trips: [] };
+      inner.set(to, edge);
+    }
+    edge.trips.push(edgeTrip);
+  }
+
+  await stmt.free();
+  return graph;
+}
+
+/** Number of distinct directed edges in the graph. */
+export function edgeCount(graph: Graph): number {
+  let n = 0;
+  for (const inner of graph.values()) n += inner.size;
+  return n;
+}
+
+/** Iterate all edges as `{ from, to, data }` tuples. */
+export function* edges(
+  graph: Graph
+): Generator<{ from: string; to: string; data: EdgeData }> {
+  for (const [from, inner] of graph) {
+    for (const [to, data] of inner) {
+      yield { from, to, data };
+    }
+  }
+}