mta-js 1.0.0

package/src/cli.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env bun
+import { MTA } from "../index";
+import { defaultStaticGtfsUrls } from "./defaults";
+import type { StaticGtfsImportStrategy, TransitMode } from "./types";
+
+const args = Bun.argv.slice(2);
+
+const command = args.slice(0, 2).join(" ");
+if (command !== "db push" && command !== "db import") {
+  usage();
+}
+
+const options = Object.fromEntries(
+  args.slice(2).map((arg) => {
+    const [key, ...value] = arg.replace(/^--/, "").split("=");
+    return [key, value.join("=") || "true"];
+  }),
+);
+
+const databaseUrl =
+  options["database-url"] ??
+  process.env.MTA_DATABASE_URL ??
+  process.env.TURSO_DATABASE_URL ??
+  process.env.DATABASE_URL;
+const databaseAuthToken =
+  options["database-auth-token"] ??
+  process.env.MTA_DATABASE_AUTH_TOKEN ??
+  process.env.TURSO_AUTH_TOKEN;
+const databaseLocalPath = options["database-local-path"] ?? process.env.MTA_DATABASE_LOCAL_PATH;
+
+if (!databaseUrl) {
+  console.error("Missing database URL. Pass --database-url or set MTA_DATABASE_URL/TURSO_DATABASE_URL/DATABASE_URL.");
+  process.exit(1);
+}
+
+const mta = new MTA({
+  databaseUrl,
+  databaseAuthToken,
+  databaseLocalPath,
+});
+
+try {
+  if (command === "db push") {
+    const result = await mta.database.push();
+    console.log(`Pushed GTFS schema (${result.statements} statements${result.remote ? ", remote" : ", local"}).`);
+  } else {
+    const mode = parseMode(options.mode);
+    const strategy = parseStrategy(options.strategy);
+    const sourceUrl = options["source-url"] ?? defaultSourceUrl(mode);
+    if (!sourceUrl) {
+      throw new Error(`No default GTFS source URL for mode ${mode}. Pass --source-url.`);
+    }
+
+    const summary = await mta.database.importStaticData({
+      mode,
+      sourceUrl,
+      strategy,
+    });
+    if (!summary) {
+      throw new Error("Import completed but no local summary was available. Rehydrate the database and check gtfs_imports.");
+    }
+    console.log(
+      [
+        `Imported ${summary.mode} GTFS (${strategy})`,
+        `source=${summary.sourceUrl ?? "unknown"}`,
+        `stops=${summary.stopCount}`,
+        `routes=${summary.routeCount}`,
+        `trips=${summary.tripCount}`,
+        `stop_times=${summary.stopTimeCount}`,
+      ].join(" "),
+    );
+  }
+} finally {
+  mta.close();
+}
+
+function parseMode(value: string | undefined): TransitMode {
+  const mode = (value ?? "subway") as TransitMode;
+  if (!["subway", "bus", "lirr", "metro-north"].includes(mode)) {
+    throw new Error(`Unsupported mode: ${value}`);
+  }
+  return mode;
+}
+
+function parseStrategy(value: string | undefined): StaticGtfsImportStrategy {
+  const strategy = (value ?? "core") as StaticGtfsImportStrategy;
+  if (!["core", "schedule"].includes(strategy)) {
+    throw new Error(`Unsupported import strategy: ${value}`);
+  }
+  return strategy;
+}
+
+function defaultSourceUrl(mode: TransitMode) {
+  if (mode === "subway") return defaultStaticGtfsUrls.subway;
+  return undefined;
+}
+
+function usage(): never {
+  console.error(
+    [
+      "Usage:",
+      "  mta-js db push --database-url=<url> [--database-auth-token=<token>]",
+      "  mta-js db import --mode=subway [--strategy=core|schedule] [--source-url=<url>]",
+    ].join("\n"),
+  );
+  process.exit(1);
+}

package/src/database-url.ts

@@ -0,0 +1,238 @@
+import { mkdirSync } from "node:fs";
+import { createClient, type Client, type InStatement } from "@libsql/client";
+import { gtfsSchemaStatements } from "./schema";
+import type { StaticGtfsSeed, TransitMode } from "./types";
+
+export function resolveSqliteDatabaseUrl(databaseUrl: string | undefined) {
+  if (!databaseUrl) return undefined;
+  if (isRemoteDatabaseUrl(databaseUrl)) return undefined;
+  if (databaseUrl === ":memory:") return databaseUrl;
+  if (!databaseUrl.startsWith("file:")) return databaseUrl;
+
+  const url = new URL(databaseUrl);
+  return decodeURIComponent(url.pathname);
+}
+
+export async function hydrateRemoteDatabaseUrl(options: {
+  databaseUrl: string | undefined;
+  databaseAuthToken?: string;
+  databaseLocalPath?: string;
+  fetch: typeof fetch;
+  refresh?: boolean;
+}) {
+  if (!options.databaseUrl || !isRemoteDatabaseUrl(options.databaseUrl)) {
+    return options.databaseUrl;
+  }
+
+  const localPath = resolveRemoteDatabaseLocalPath(options.databaseUrl, options.databaseLocalPath);
+  const existing = Bun.file(localPath);
+  if (!options.refresh && await existing.exists()) {
+    return localPath;
+  }
+
+  if (isLibsqlDatabaseUrl(options.databaseUrl)) {
+    await hydrateLibsqlDatabase({
+      databaseUrl: options.databaseUrl,
+      databaseAuthToken: options.databaseAuthToken,
+      localPath,
+    });
+    return localPath;
+  }
+
+  const response = await options.fetch(options.databaseUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to hydrate databaseUrl ${options.databaseUrl}: ${response.status} ${response.statusText}`);
+  }
+
+  mkdirSync(localPath.slice(0, localPath.lastIndexOf("/")), { recursive: true });
+  await Bun.write(localPath, response);
+  return localPath;
+}
+
+export async function pushRemoteDatabaseSchema(options: {
+  databaseUrl: string | undefined;
+  databaseAuthToken?: string;
+}) {
+  if (!options.databaseUrl || !isLibsqlDatabaseUrl(options.databaseUrl)) {
+    return { remote: false, statements: gtfsSchemaStatements.length };
+  }
+
+  const client = createClient({
+    url: options.databaseUrl,
+    authToken: options.databaseAuthToken,
+  });
+
+  try {
+    for (const sql of gtfsSchemaStatements) {
+      await client.execute(sql);
+    }
+  } finally {
+    client.close();
+  }
+
+  return { remote: true, statements: gtfsSchemaStatements.length };
+}
+
+export async function importRemoteStaticSeed(options: {
+  databaseUrl: string | undefined;
+  databaseAuthToken?: string;
+  seed: StaticGtfsSeed;
+  mode: TransitMode;
+  sourceUrl?: string;
+}) {
+  if (!options.databaseUrl || !isLibsqlDatabaseUrl(options.databaseUrl)) {
+    return { remote: false };
+  }
+
+  const client = createClient({
+    url: options.databaseUrl,
+    authToken: options.databaseAuthToken,
+  });
+
+  try {
+    await batchChunks(client, gtfsSchemaStatements.map((sql) => ({ sql, args: [] })));
+    await batchChunks(
+      client,
+      (options.seed.stops ?? []).map((stop) => ({
+        sql: `insert or replace into stops
+          (id, name, lat, lon, parent_station, location_type, mode)
+          values (?, ?, ?, ?, ?, ?, ?)`,
+        args: [
+          stop.stop_id,
+          stop.stop_name,
+          numberOrNull(stop.stop_lat),
+          numberOrNull(stop.stop_lon),
+          stop.parent_station ?? null,
+          numberOrNull(stop.location_type),
+          options.mode,
+        ],
+      })),
+    );
+    await batchChunks(
+      client,
+      (options.seed.routes ?? []).map((route) => ({
+        sql: `insert or replace into routes
+          (id, short_name, long_name, type, color, text_color)
+          values (?, ?, ?, ?, ?, ?)`,
+        args: [
+          route.route_id,
+          route.route_short_name ?? route.route_id,
+          route.route_long_name ?? null,
+          numberOrNull(route.route_type),
+          normalizeColor(route.route_color),
+          normalizeColor(route.route_text_color),
+        ],
+      })),
+    );
+    await batchChunks(
+      client,
+      (options.seed.trips ?? []).map((trip) => ({
+        sql: `insert or replace into trips
+          (id, route_id, service_id, headsign, direction_id)
+          values (?, ?, ?, ?, ?)`,
+        args: [
+          trip.trip_id,
+          trip.route_id,
+          trip.service_id ?? null,
+          trip.trip_headsign ?? null,
+          numberOrNull(trip.direction_id),
+        ],
+      })),
+    );
+    await batchChunks(
+      client,
+      (options.seed.stopTimes ?? []).map((stopTime) => ({
+        sql: `insert or replace into stop_times
+          (trip_id, arrival_time, departure_time, stop_id, stop_sequence)
+          values (?, ?, ?, ?, ?)`,
+        args: [
+          stopTime.trip_id,
+          stopTime.arrival_time ?? null,
+          stopTime.departure_time ?? null,
+          stopTime.stop_id,
+          numberOrNull(stopTime.stop_sequence) ?? 0,
+        ],
+      })),
+    );
+    await client.batch(
+      [
+        {
+          sql: `insert or replace into gtfs_imports
+            (mode, imported_at, source_url, stop_count, route_count, trip_count, stop_time_count)
+            values (?, ?, ?, ?, ?, ?, ?)`,
+          args: [
+            options.mode,
+            new Date().toISOString(),
+            options.sourceUrl ?? null,
+            options.seed.stops?.length ?? 0,
+            options.seed.routes?.length ?? 0,
+            options.seed.trips?.length ?? 0,
+            options.seed.stopTimes?.length ?? 0,
+          ],
+        },
+      ],
+      "write",
+    );
+  } finally {
+    client.close();
+  }
+
+  return { remote: true };
+}
+
+export function isRemoteDatabaseUrl(databaseUrl: string) {
+  return isHttpDatabaseUrl(databaseUrl) || isLibsqlDatabaseUrl(databaseUrl);
+}
+
+export function resolveRemoteDatabaseLocalPath(databaseUrl: string, databaseLocalPath?: string) {
+  return databaseLocalPath ?? defaultRemoteDatabasePath(databaseUrl);
+}
+
+export function isHttpDatabaseUrl(databaseUrl: string) {
+  return databaseUrl.startsWith("https://") || databaseUrl.startsWith("http://");
+}
+
+export function isLibsqlDatabaseUrl(databaseUrl: string) {
+  return databaseUrl.startsWith("libsql://");
+}
+
+function defaultRemoteDatabasePath(databaseUrl: string) {
+  const tmp = process.env.TMPDIR ?? "/tmp";
+  const url = new URL(databaseUrl);
+  const basename = url.pathname.split("/").filter(Boolean).at(-1) ?? "gtfs.sqlite";
+  const hash = Bun.hash(databaseUrl).toString(36);
+  return `${tmp.replace(/\/$/, "")}/mta-js/${hash}-${basename}`;
+}
+
+async function hydrateLibsqlDatabase(options: {
+  databaseUrl: string;
+  databaseAuthToken?: string;
+  localPath: string;
+}) {
+  mkdirSync(options.localPath.slice(0, options.localPath.lastIndexOf("/")), { recursive: true });
+  const client = createClient({
+    url: `file:${options.localPath}`,
+    syncUrl: options.databaseUrl,
+    authToken: options.databaseAuthToken,
+  });
+  await client.sync();
+  client.close();
+}
+
+function numberOrNull(value: unknown) {
+  if (value === undefined || value === null || value === "") return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function normalizeColor(value: string | undefined) {
+  if (!value) return null;
+  return value.startsWith("#") ? value : `#${value}`;
+}
+
+async function batchChunks(client: Client, statements: InStatement[], size = 500) {
+  for (let index = 0; index < statements.length; index += size) {
+    const chunk = statements.slice(index, index + size);
+    if (chunk.length) await client.batch(chunk, "write");
+  }
+}

package/src/defaults.ts

@@ -0,0 +1,65 @@
+import type { MTAEndpoints } from "./types";
+
+const realtimeBase = "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds";
+
+export const defaultEndpoints: MTAEndpoints = {
+  subwayFeeds: {
+    "1": `${realtimeBase}/nyct%2Fgtfs`,
+    "2": `${realtimeBase}/nyct%2Fgtfs`,
+    "3": `${realtimeBase}/nyct%2Fgtfs`,
+    "4": `${realtimeBase}/nyct%2Fgtfs`,
+    "5": `${realtimeBase}/nyct%2Fgtfs`,
+    "6": `${realtimeBase}/nyct%2Fgtfs`,
+    "7": `${realtimeBase}/nyct%2Fgtfs`,
+    A: `${realtimeBase}/nyct%2Fgtfs-ace`,
+    C: `${realtimeBase}/nyct%2Fgtfs-ace`,
+    E: `${realtimeBase}/nyct%2Fgtfs-ace`,
+    B: `${realtimeBase}/nyct%2Fgtfs-bdfm`,
+    D: `${realtimeBase}/nyct%2Fgtfs-bdfm`,
+    F: `${realtimeBase}/nyct%2Fgtfs-bdfm`,
+    M: `${realtimeBase}/nyct%2Fgtfs-bdfm`,
+    G: `${realtimeBase}/nyct%2Fgtfs-g`,
+    J: `${realtimeBase}/nyct%2Fgtfs-jz`,
+    Z: `${realtimeBase}/nyct%2Fgtfs-jz`,
+    L: `${realtimeBase}/nyct%2Fgtfs-l`,
+    N: `${realtimeBase}/nyct%2Fgtfs-nqrw`,
+    Q: `${realtimeBase}/nyct%2Fgtfs-nqrw`,
+    R: `${realtimeBase}/nyct%2Fgtfs-nqrw`,
+    W: `${realtimeBase}/nyct%2Fgtfs-nqrw`,
+    SIR: `${realtimeBase}/nyct%2Fgtfs-si`,
+  },
+  alerts: `${realtimeBase}/camsys%2Fall-alerts`,
+  busVehicleMonitoring: "https://bustime.mta.info/api/siri/vehicle-monitoring.json",
+  busStopMonitoring: "https://bustime.mta.info/api/siri/stop-monitoring.json",
+};
+
+export const defaultStaticGtfsUrls = {
+  subway: "https://rrgtfsfeeds.s3.amazonaws.com/gtfs_subway.zip",
+} as const;
+
+export const subwayRouteColors: Record<string, string> = {
+  "1": "EE352E",
+  "2": "EE352E",
+  "3": "EE352E",
+  "4": "00933C",
+  "5": "00933C",
+  "6": "00933C",
+  "7": "B933AD",
+  A: "0039A6",
+  C: "0039A6",
+  E: "0039A6",
+  B: "FF6319",
+  D: "FF6319",
+  F: "FF6319",
+  M: "FF6319",
+  G: "6CBE45",
+  J: "996633",
+  Z: "996633",
+  L: "A7A9AC",
+  N: "FCCC0A",
+  Q: "FCCC0A",
+  R: "FCCC0A",
+  W: "FCCC0A",
+  S: "808183",
+  SIR: "006BB6",
+};

package/src/errors.ts

@@ -0,0 +1,43 @@
+export class MTAError extends Error {
+  override name = "MTAError";
+}
+
+export class MissingBusTimeKeyError extends MTAError {
+  override name = "MissingBusTimeKeyError";
+
+  constructor() {
+    super("MTA BusTime API calls require a busTimeKey.");
+  }
+}
+
+export class UnknownRouteError extends MTAError {
+  override name = "UnknownRouteError";
+
+  constructor(route: string) {
+    super(`Unknown MTA route: ${route}`);
+  }
+}
+
+export class UnknownStopError extends MTAError {
+  override name = "UnknownStopError";
+
+  constructor(stopId: string) {
+    super(`Unknown MTA stop: ${stopId}`);
+  }
+}
+
+export class StaticDataMissingError extends MTAError {
+  override name = "StaticDataMissingError";
+
+  constructor(mode: string) {
+    super(`Static GTFS data for ${mode} is missing. Run mta.database.importStaticData or the db import CLI before using this lookup.`);
+  }
+}
+
+export class FeedError extends MTAError {
+  override name = "FeedError";
+
+  constructor(message: string, readonly response?: Response) {
+    super(message);
+  }
+}

package/src/gtfs-realtime.ts

@@ -0,0 +1,245 @@
+import protobuf from "protobufjs";
+
+const proto = `
+syntax = "proto2";
+package transit_realtime;
+
+message FeedMessage {
+  required FeedHeader header = 1;
+  repeated FeedEntity entity = 2;
+}
+
+message FeedHeader {
+  required string gtfs_realtime_version = 1;
+  optional Incrementality incrementality = 2 [default = FULL_DATASET];
+  optional uint64 timestamp = 3;
+
+  enum Incrementality {
+    FULL_DATASET = 0;
+    DIFFERENTIAL = 1;
+  }
+}
+
+message FeedEntity {
+  required string id = 1;
+  optional bool is_deleted = 2 [default = false];
+  optional TripUpdate trip_update = 3;
+  optional VehiclePosition vehicle = 4;
+  optional Alert alert = 5;
+}
+
+message TripUpdate {
+  optional TripDescriptor trip = 1;
+  optional VehicleDescriptor vehicle = 3;
+  repeated StopTimeUpdate stop_time_update = 2;
+  optional uint64 timestamp = 4;
+  optional int32 delay = 5;
+}
+
+message StopTimeEvent {
+  optional int32 delay = 1;
+  optional int64 time = 2;
+  optional int32 uncertainty = 3;
+}
+
+message StopTimeUpdate {
+  optional uint32 stop_sequence = 1;
+  optional string stop_id = 4;
+  optional StopTimeEvent arrival = 2;
+  optional StopTimeEvent departure = 3;
+  optional ScheduleRelationship schedule_relationship = 5 [default = SCHEDULED];
+
+  enum ScheduleRelationship {
+    SCHEDULED = 0;
+    SKIPPED = 1;
+    NO_DATA = 2;
+    UNSCHEDULED = 3;
+  }
+}
+
+message VehiclePosition {
+  optional TripDescriptor trip = 1;
+  optional VehicleDescriptor vehicle = 8;
+  optional Position position = 2;
+  optional uint32 current_stop_sequence = 3;
+  optional string stop_id = 7;
+  optional VehicleStopStatus current_status = 4 [default = IN_TRANSIT_TO];
+  optional uint64 timestamp = 5;
+}
+
+message Alert {
+  repeated TimeRange active_period = 1;
+  repeated EntitySelector informed_entity = 5;
+  optional Cause cause = 6 [default = UNKNOWN_CAUSE];
+  optional Effect effect = 7 [default = UNKNOWN_EFFECT];
+  optional TranslatedString url = 8;
+  optional TranslatedString header_text = 10;
+  optional TranslatedString description_text = 11;
+
+  enum Cause {
+    UNKNOWN_CAUSE = 1;
+    OTHER_CAUSE = 2;
+    TECHNICAL_PROBLEM = 3;
+    STRIKE = 4;
+    DEMONSTRATION = 5;
+    ACCIDENT = 6;
+    HOLIDAY = 7;
+    WEATHER = 8;
+    MAINTENANCE = 9;
+    CONSTRUCTION = 10;
+    POLICE_ACTIVITY = 11;
+    MEDICAL_EMERGENCY = 12;
+  }
+
+  enum Effect {
+    NO_SERVICE = 1;
+    REDUCED_SERVICE = 2;
+    SIGNIFICANT_DELAYS = 3;
+    DETOUR = 4;
+    ADDITIONAL_SERVICE = 5;
+    MODIFIED_SERVICE = 6;
+    OTHER_EFFECT = 7;
+    UNKNOWN_EFFECT = 8;
+    STOP_MOVED = 9;
+    NO_EFFECT = 10;
+    ACCESSIBILITY_ISSUE = 11;
+  }
+}
+
+message TimeRange {
+  optional uint64 start = 1;
+  optional uint64 end = 2;
+}
+
+message Position {
+  required float latitude = 1;
+  required float longitude = 2;
+  optional float bearing = 3;
+  optional double odometer = 4;
+  optional float speed = 5;
+}
+
+message TripDescriptor {
+  optional string trip_id = 1;
+  optional string route_id = 5;
+  optional uint32 direction_id = 6;
+  optional string start_time = 2;
+  optional string start_date = 3;
+  optional ScheduleRelationship schedule_relationship = 4;
+
+  enum ScheduleRelationship {
+    SCHEDULED = 0;
+    ADDED = 1;
+    UNSCHEDULED = 2;
+    CANCELED = 3;
+    REPLACEMENT = 5;
+    DUPLICATED = 6;
+    DELETED = 7;
+  }
+}
+
+message VehicleDescriptor {
+  optional string id = 1;
+  optional string label = 2;
+  optional string license_plate = 3;
+}
+
+message EntitySelector {
+  optional string agency_id = 1;
+  optional string route_id = 2;
+  optional int32 route_type = 3;
+  optional TripDescriptor trip = 4;
+  optional string stop_id = 5;
+}
+
+message TranslatedString {
+  repeated Translation translation = 1;
+
+  message Translation {
+    required string text = 1;
+    optional string language = 2;
+  }
+}
+
+enum VehicleStopStatus {
+  INCOMING_AT = 0;
+  STOPPED_AT = 1;
+  IN_TRANSIT_TO = 2;
+}
+`;
+
+const root = protobuf.parse(proto).root;
+const FeedMessage = root.lookupType("transit_realtime.FeedMessage");
+
+export function decodeFeedMessage(bytes: ArrayBuffer | Uint8Array) {
+  const decoded = FeedMessage.decode(new Uint8Array(bytes));
+  return FeedMessage.toObject(decoded, {
+    longs: Number,
+    enums: String,
+    defaults: false,
+    arrays: true,
+  }) as GtfsRealtimeFeed;
+}
+
+export function encodeFeedMessage(feed: GtfsRealtimeFeed) {
+  const message = FeedMessage.fromObject(feed);
+  return FeedMessage.encode(message).finish();
+}
+
+export interface GtfsRealtimeFeed {
+  header?: {
+    gtfsRealtimeVersion?: string;
+    incrementality?: string;
+    timestamp?: number;
+  };
+  entity: GtfsRealtimeEntity[];
+}
+
+export interface GtfsRealtimeEntity {
+  id: string;
+  isDeleted?: boolean;
+  tripUpdate?: {
+    trip?: {
+      tripId?: string;
+      routeId?: string;
+      directionId?: number;
+      startTime?: string;
+      startDate?: string;
+      scheduleRelationship?: string;
+    };
+    vehicle?: {
+      id?: string;
+      label?: string;
+      licensePlate?: string;
+    };
+    stopTimeUpdate: {
+      stopSequence?: number;
+      stopId?: string;
+      arrival?: { delay?: number; time?: number; uncertainty?: number };
+      departure?: { delay?: number; time?: number; uncertainty?: number };
+      scheduleRelationship?: string;
+    }[];
+    timestamp?: number;
+    delay?: number;
+  };
+  vehicle?: unknown;
+  alert?: {
+    activePeriod: { start?: number; end?: number }[];
+    informedEntity: {
+      agencyId?: string;
+      routeId?: string;
+      routeType?: number;
+      stopId?: string;
+      trip?: { tripId?: string; routeId?: string };
+    }[];
+    cause?: string;
+    effect?: string;
+    url?: TranslatedString;
+    headerText?: TranslatedString;
+    descriptionText?: TranslatedString;
+  };
+}
+
+export interface TranslatedString {
+  translation: { text: string; language?: string }[];
+}