@osmix/gtfs 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @osmix/gtfs
+
+## 0.0.1
+
+### Added
+
+- Initial release with GTFS to OSM conversion.
+- Stops parsed as nodes with tags.
+- Routes parsed as ways with shape geometry.

package/README.md

@@ -0,0 +1,200 @@
+# @osmix/gtfs
+
+Convert GTFS (General Transit Feed Specification) transit feeds to OSM format.
+
+**Lazy parsing**: Files are only parsed when accessed, not upfront.
+
+## Installation
+
+```bash
+npm install @osmix/gtfs
+# or
+bun add @osmix/gtfs
+```
+
+## Usage
+
+```ts
+import { fromGtfs } from "@osmix/gtfs"
+
+// Fetch a GTFS zip file
+const response = await fetch("https://example.com/gtfs.zip")
+const zipData = await response.arrayBuffer()
+
+// Convert to OSM format
+const osm = await fromGtfs(zipData, { id: "transit" })
+
+console.log(`Imported ${osm.nodes.size} stops and ${osm.ways.size} routes`)
+```
+
+### Using GtfsArchive for Custom Processing
+
+For more control, use `GtfsArchive` directly. Files are only parsed when you access them:
+
+```ts
+import { GtfsArchive } from "@osmix/gtfs"
+
+const archive = GtfsArchive.fromZip(zipData)
+
+// Only stops.txt is parsed - other files remain unread
+for await (const stop of archive.iterStops()) {
+  console.log(stop.stop_name, stop.stop_lat, stop.stop_lon)
+}
+
+// Access routes later - now routes.txt is parsed
+const routes = await archive.routes()
+```
+
+## GTFS to OSM Mapping
+
+### Stops → Nodes
+
+GTFS stops are converted to OSM nodes with the following tags:
+
+| GTFS Field           | OSM Tag              |
+| -------------------- | -------------------- |
+| `stop_name`          | `name`               |
+| `stop_id`            | `ref`                |
+| `stop_code`          | `ref:gtfs:stop_code` |
+| `stop_desc`          | `description`        |
+| `stop_url`           | `website`            |
+| `platform_code`      | `ref:platform`       |
+| `wheelchair_boarding`| `wheelchair`         |
+| `location_type`      | `public_transport`   |
+
+Location types are mapped as:
+- `0` (stop) → `public_transport=platform`
+- `1` (station) → `public_transport=station`
+- `2` (entrance) → `railway=subway_entrance`
+- `4` (boarding area) → `public_transport=platform`
+
+### Routes → Ways
+
+GTFS routes are converted to OSM ways with the following tags:
+
+| GTFS Field         | OSM Tag              |
+| ------------------ | -------------------- |
+| `route_long_name`  | `name`               |
+| `route_short_name` | `ref`                |
+| `route_id`         | `ref:gtfs:route_id`  |
+| `route_desc`       | `description`        |
+| `route_url`        | `website`            |
+| `route_color`      | `color`              |
+| `route_text_color` | `text_color`         |
+| `route_type`       | `route`, `gtfs:route_type` |
+
+Route types are mapped to OSM route values:
+- `0` → `tram`
+- `1` → `subway`
+- `2` → `train`
+- `3` → `bus`
+- `4` → `ferry`
+- `5` → `tram` (cable tram)
+- `6` → `aerialway`
+- `7` → `funicular`
+- `11` → `trolleybus`
+- `12` → `train` (monorail)
+
+### Geometry
+
+Route geometry is derived from:
+1. **shapes.txt** (preferred) - Uses shape points to create accurate route paths
+2. **stop_times.txt** (fallback) - Uses stop sequence when shapes are unavailable
+
+Files are only parsed when needed for the conversion.
+
+## Options
+
+```ts
+interface GtfsConversionOptions {
+  /** Whether to include stops as nodes. Default: true */
+  includeStops?: boolean
+  /** Filter stops by location_type. Default: include all types. */
+  stopTypes?: number[]
+  /** Whether to include routes as ways. Default: true */
+  includeRoutes?: boolean
+  /** Filter routes by route_type. Default: include all types. */
+  routeTypes?: number[]
+  /** Whether to include shape geometry for routes. Default: true */
+  includeShapes?: boolean
+}
+```
+
+### Example with Options
+
+```ts
+import { fromGtfs } from "@osmix/gtfs"
+
+// Only bus routes, with stops and stations
+const osm = await fromGtfs(zipData, { id: "buses-only" }, {
+  routeTypes: [3], // Only bus routes
+  stopTypes: [0, 1], // Only stops and stations
+})
+
+// Routes only (no stops) - useful for just getting route shapes
+const routesOnly = await fromGtfs(zipData, { id: "routes" }, {
+  includeStops: false,
+})
+
+// Stops only (no routes)
+const stopsOnly = await fromGtfs(zipData, { id: "stops" }, {
+  includeRoutes: false,
+})
+```
+
+## API
+
+### `fromGtfs(zipData, options?, gtfsOptions?, onProgress?)`
+
+Main function to convert a GTFS zip file to an Osm index.
+
+### `GtfsArchive`
+
+Lazy GTFS archive class. Files are parsed on-demand:
+
+```ts
+const archive = GtfsArchive.fromZip(zipData)
+
+// Check what files exist
+archive.listFiles()      // ['agency.txt', 'stops.txt', ...]
+archive.hasFile('shapes.txt')
+
+// Lazy accessors (parse on first call, cache result)
+await archive.agencies()
+await archive.stops()
+await archive.routes()
+await archive.trips()
+await archive.stopTimes()
+await archive.shapes()
+
+// Streaming iterator with automatic type inference
+for await (const stop of archive.iter("stops.txt")) {
+  console.log(stop.stop_name) // TypeScript knows this is GtfsStop
+}
+
+for await (const route of archive.iter("routes.txt")) {
+  console.log(route.route_type) // TypeScript knows this is GtfsRoute
+}
+
+for await (const shape of archive.iter("shapes.txt")) {
+  console.log(shape.shape_pt_lat) // TypeScript knows this is GtfsShapePoint
+}
+```
+
+The `iter(filename)` method automatically infers the return type based on the filename:
+- `"agency.txt"` → `AsyncGenerator<GtfsAgency>`
+- `"stops.txt"` → `AsyncGenerator<GtfsStop>`
+- `"routes.txt"` → `AsyncGenerator<GtfsRoute>`
+- `"trips.txt"` → `AsyncGenerator<GtfsTrip>`
+- `"stop_times.txt"` → `AsyncGenerator<GtfsStopTime>`
+- `"shapes.txt"` → `AsyncGenerator<GtfsShapePoint>`
+
+### `GtfsOsmBuilder`
+
+Class for more fine-grained control over the conversion process.
+
+## Dependencies
+
+- [but-unzip](https://github.com/nicolo-ribaudo/but-unzip) - ZIP file parsing
+- [@std/csv](https://jsr.io/@std/csv) - Streaming CSV parsing (from Deno standard library)
+- [@osmix/core](../core) - OSM data structures

package/dist/from-gtfs.d.ts

@@ -0,0 +1,76 @@
+/**
+ * GTFS to OSM conversion utilities.
+ *
+ * Imports GTFS transit feeds into Osm indexes, mapping:
+ * - Stops → Nodes with transit tags
+ * - Routes → Ways with shape geometry
+ *
+ * Uses lazy, on-demand parsing - files are only parsed when needed.
+ *
+ * @module
+ */
+import { Osm, type OsmOptions } from "@osmix/core";
+import { type ProgressEvent } from "@osmix/shared/progress";
+import { GtfsArchive } from "./gtfs-archive";
+import type { GtfsConversionOptions } from "./types";
+/**
+ * Create an Osm index from a zipped GTFS file.
+ *
+ * Parses the GTFS zip lazily - only reading files when needed.
+ * Converts stops and routes to OSM entities:
+ * - Stops become nodes with transit-related tags
+ * - Routes become ways with shape geometry (if available) or stop sequence
+ *
+ * @param zipData - The GTFS zip file as ArrayBuffer or Uint8Array
+ * @param options - Osm index options (id, header)
+ * @param gtfsOptions - GTFS conversion options
+ * @param onProgress - Progress callback for UI feedback
+ * @returns Populated Osm index with built indexes
+ *
+ * @example
+ * ```ts
+ * import { fromGtfs } from "@osmix/gtfs"
+ *
+ * const response = await fetch("https://example.com/gtfs.zip")
+ * const zipData = await response.arrayBuffer()
+ * const osm = await fromGtfs(zipData, { id: "transit" })
+ *
+ * console.log(`Imported ${osm.nodes.size} stops`)
+ * ```
+ */
+export declare function fromGtfs(zipData: ArrayBuffer | Uint8Array, options?: Partial<OsmOptions>, gtfsOptions?: GtfsConversionOptions, onProgress?: (progress: ProgressEvent) => void): Promise<Osm>;
+/**
+ * Builder class for converting GTFS data to OSM entities.
+ *
+ * Uses lazy parsing - only reads GTFS files when needed.
+ */
+export declare class GtfsOsmBuilder {
+    private osm;
+    private onProgress;
+    private nextNodeId;
+    private nextWayId;
+    private stopIdToNodeId;
+    constructor(osmOptions?: Partial<OsmOptions>, onProgress?: (progress: ProgressEvent) => void);
+    /**
+     * Process GTFS stops into OSM nodes.
+     * Uses streaming iteration to avoid loading all stops at once.
+     */
+    processStops(archive: GtfsArchive): Promise<void>;
+    /**
+     * Process GTFS routes into OSM ways.
+     * Creates one way per unique (shape_id, route_id) pair, so each route gets
+     * its own way with correct metadata even when routes share the same shape.
+     *
+     * @param archive - The GTFS archive
+     */
+    processRoutes(archive: GtfsArchive): Promise<void>;
+    /**
+     * Create a way from shape points.
+     */
+    private createWayFromShape;
+    /**
+     * Build the OSM index with all entities.
+     */
+    buildOsm(): Osm;
+}
+//# sourceMappingURL=from-gtfs.d.ts.map

package/dist/from-gtfs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-gtfs.d.ts","sourceRoot":"","sources":["../src/from-gtfs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,GAAG,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAEN,KAAK,aAAa,EAElB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,qBAAqB,EAAkB,MAAM,SAAS,CAAA;AAGpE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,QAAQ,CAC7B,OAAO,EAAE,WAAW,GAAG,UAAU,EACjC,OAAO,GAAE,OAAO,CAAC,UAAU,CAAM,EACjC,WAAW,GAAE,qBAA0B,EACvC,UAAU,GAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAkB,GACzD,OAAO,CAAC,GAAG,CAAC,CAad;AAED;;;;GAIG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,UAAU,CAAmC;IAErD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,SAAS,CAAK;IAGtB,OAAO,CAAC,cAAc,CAA4B;gBAGjD,UAAU,GAAE,OAAO,CAAC,UAAU,CAAM,EACpC,UAAU,GAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAkB;IAM5D;;;OAGG;IACG,YAAY,CAAC,OAAO,EAAE,WAAW;IAgCvC;;;;;;OAMG;IACG,aAAa,CAAC,OAAO,EAAE,WAAW;IAmFxC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;OAEG;IACH,QAAQ,IAAI,GAAG;CAMf"}

package/dist/from-gtfs.js

@@ -0,0 +1,211 @@
+/**
+ * GTFS to OSM conversion utilities.
+ *
+ * Imports GTFS transit feeds into Osm indexes, mapping:
+ * - Stops → Nodes with transit tags
+ * - Routes → Ways with shape geometry
+ *
+ * Uses lazy, on-demand parsing - files are only parsed when needed.
+ *
+ * @module
+ */
+import { Osm } from "@osmix/core";
+import { logProgress, progressEvent, } from "@osmix/shared/progress";
+import { GtfsArchive } from "./gtfs-archive";
+import { routeToTags, stopToTags } from "./utils";
+/**
+ * Create an Osm index from a zipped GTFS file.
+ *
+ * Parses the GTFS zip lazily - only reading files when needed.
+ * Converts stops and routes to OSM entities:
+ * - Stops become nodes with transit-related tags
+ * - Routes become ways with shape geometry (if available) or stop sequence
+ *
+ * @param zipData - The GTFS zip file as ArrayBuffer or Uint8Array
+ * @param options - Osm index options (id, header)
+ * @param gtfsOptions - GTFS conversion options
+ * @param onProgress - Progress callback for UI feedback
+ * @returns Populated Osm index with built indexes
+ *
+ * @example
+ * ```ts
+ * import { fromGtfs } from "@osmix/gtfs"
+ *
+ * const response = await fetch("https://example.com/gtfs.zip")
+ * const zipData = await response.arrayBuffer()
+ * const osm = await fromGtfs(zipData, { id: "transit" })
+ *
+ * console.log(`Imported ${osm.nodes.size} stops`)
+ * ```
+ */
+export async function fromGtfs(zipData, options = {}, gtfsOptions = {}, onProgress = logProgress) {
+    onProgress(progressEvent("Opening GTFS archive..."));
+    const archive = GtfsArchive.fromZip(zipData);
+    const builder = new GtfsOsmBuilder(options, onProgress);
+    if (gtfsOptions.includeStops ?? true) {
+        await builder.processStops(archive);
+    }
+    if (gtfsOptions.includeRoutes ?? true) {
+        await builder.processRoutes(archive);
+    }
+    return builder.buildOsm();
+}
+/**
+ * Builder class for converting GTFS data to OSM entities.
+ *
+ * Uses lazy parsing - only reads GTFS files when needed.
+ */
+export class GtfsOsmBuilder {
+    osm;
+    onProgress;
+    nextNodeId = -1;
+    nextWayId = -1;
+    // Map GTFS stop_id to OSM node ID
+    stopIdToNodeId = new Map();
+    constructor(osmOptions = {}, onProgress = logProgress) {
+        this.osm = new Osm(osmOptions);
+        this.onProgress = onProgress;
+    }
+    /**
+     * Process GTFS stops into OSM nodes.
+     * Uses streaming iteration to avoid loading all stops at once.
+     */
+    async processStops(archive) {
+        let count = 0;
+        this.onProgress(progressEvent("Processing stops..."));
+        for await (const stop of archive.iter("stops.txt")) {
+            const lat = Number.parseFloat(stop.stop_lat);
+            const lon = Number.parseFloat(stop.stop_lon);
+            if (Number.isNaN(lat) || Number.isNaN(lon))
+                continue;
+            const tags = stopToTags(stop);
+            const nodeId = this.nextNodeId--;
+            this.osm.nodes.addNode({
+                id: nodeId,
+                lat,
+                lon,
+                tags,
+            });
+            this.stopIdToNodeId.set(stop.stop_id, nodeId);
+            count++;
+            if (count % 1000 === 0) {
+                this.onProgress(progressEvent(`Processed ${count} stops...`));
+            }
+        }
+        this.onProgress(progressEvent(`Added ${count} stops as nodes`));
+    }
+    /**
+     * Process GTFS routes into OSM ways.
+     * Creates one way per unique (shape_id, route_id) pair, so each route gets
+     * its own way with correct metadata even when routes share the same shape.
+     *
+     * @param archive - The GTFS archive
+     */
+    async processRoutes(archive) {
+        this.onProgress(progressEvent("Processing routes..."));
+        // Build shape lookup if shapes exist
+        const shapeMap = new Map();
+        if (archive.hasFile("shapes.txt")) {
+            this.onProgress(progressEvent("Loading shape data..."));
+            for await (const point of archive.iter("shapes.txt")) {
+                const points = shapeMap.get(point.shape_id) ?? [];
+                points.push(point);
+                shapeMap.set(point.shape_id, points);
+            }
+            // Sort each shape by sequence
+            for (const points of shapeMap.values()) {
+                points.sort((a, b) => Number.parseInt(a.shape_pt_sequence, 10) -
+                    Number.parseInt(b.shape_pt_sequence, 10));
+            }
+        }
+        else {
+            throw Error("No shape data found. Cannot process routes.");
+        }
+        // Group trips by (shape_id, route_id) to ensure each route gets its own way
+        // even when multiple routes share the same shape geometry
+        const shapeRouteToTrips = new Map();
+        this.onProgress(progressEvent("Loading trip data..."));
+        for await (const trip of archive.iter("trips.txt")) {
+            if (!trip.shape_id)
+                continue;
+            const key = `${trip.shape_id}:${trip.route_id}`;
+            const existing = shapeRouteToTrips.get(key);
+            if (existing) {
+                existing.tripIds.push(trip.trip_id);
+            }
+            else {
+                shapeRouteToTrips.set(key, { tripIds: [trip.trip_id] });
+            }
+        }
+        // Load routes into a map for lookup
+        const routeMap = new Map();
+        for await (const route of archive.iter("routes.txt")) {
+            routeMap.set(route.route_id, routeToTags(route));
+        }
+        // Process unique (shape, route) pairs - one way per combination
+        let count = 0;
+        for (const [key, { tripIds }] of shapeRouteToTrips) {
+            const [shapeId, routeId] = key.split(":");
+            const routeTags = routeMap.get(routeId);
+            if (!routeTags)
+                continue;
+            const shapePoints = shapeMap.get(shapeId);
+            if (!shapePoints || shapePoints.length < 2) {
+                this.onProgress(progressEvent(`No shape data found for shape ${shapeId}`, "error"));
+                continue;
+            }
+            // Build tags with route info and all trip IDs for this route
+            const tags = {
+                ...routeTags,
+                "gtfs:shape_id": shapeId,
+                "gtfs:trip_ids": tripIds.join(";"),
+                "gtfs:trip_count": tripIds.length,
+            };
+            // Create way from shape points
+            this.createWayFromShape(tags, shapePoints);
+            count++;
+            if (count % 100 === 0) {
+                this.onProgress(progressEvent(`Processed ${count} shape-route pairs...`));
+            }
+        }
+        this.onProgress(progressEvent(`Added ${count} shape-route pairs as ways`));
+    }
+    /**
+     * Create a way from shape points.
+     */
+    createWayFromShape(tags, shapePoints) {
+        const nodeRefs = [];
+        for (const point of shapePoints) {
+            const lat = Number.parseFloat(point.shape_pt_lat);
+            const lon = Number.parseFloat(point.shape_pt_lon);
+            if (Number.isNaN(lat) || Number.isNaN(lon))
+                continue;
+            // Create a node for this shape point
+            const nodeId = this.nextNodeId--;
+            this.osm.nodes.addNode({
+                id: nodeId,
+                lat,
+                lon,
+            });
+            nodeRefs.push(nodeId);
+        }
+        if (nodeRefs.length >= 2) {
+            const wayId = this.nextWayId--;
+            this.osm.ways.addWay({
+                id: wayId,
+                refs: nodeRefs,
+                tags,
+            });
+        }
+    }
+    /**
+     * Build the OSM index with all entities.
+     */
+    buildOsm() {
+        this.onProgress(progressEvent("Building indexes..."));
+        this.osm.buildIndexes();
+        this.osm.buildSpatialIndexes();
+        return this.osm;
+    }
+}
+//# sourceMappingURL=from-gtfs.js.map

package/dist/from-gtfs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-gtfs.js","sourceRoot":"","sources":["../src/from-gtfs.ts"],"names":[],"mappings":"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"}

package/dist/gtfs-archive.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Lazy GTFS archive parser with streaming CSV support.
+ *
+ * Only parses CSV files when they are accessed, not upfront.
+ * Uses @std/csv CsvParseStream for true line-by-line streaming.
+ *
+ * @module
+ */
+import type { GtfsAgency, GtfsRoute, GtfsShapePoint, GtfsStop, GtfsStopTime, GtfsTrip } from "./types";
+/**
+ * Map of GTFS filenames to their record types.
+ */
+export interface GtfsFileTypeMap {
+    "agency.txt": GtfsAgency;
+    "stops.txt": GtfsStop;
+    "routes.txt": GtfsRoute;
+    "trips.txt": GtfsTrip;
+    "stop_times.txt": GtfsStopTime;
+    "shapes.txt": GtfsShapePoint;
+}
+/** Valid GTFS filenames that can be parsed. */
+export type GtfsFileName = keyof GtfsFileTypeMap;
+/**
+ * Lazy GTFS archive that only parses files on demand.
+ *
+ * Files are read from the zip and parsed only when their
+ * corresponding getter is called for the first time.
+ * Streaming iterators parse CSV line-by-line without loading
+ * the entire file into memory.
+ */
+export declare class GtfsArchive {
+    private entries;
+    private constructor();
+    /**
+     * Create a GtfsArchive from zip data.
+     */
+    static fromZip(zipData: ArrayBuffer | Uint8Array): GtfsArchive;
+    /**
+     * Check if a file exists in the archive.
+     */
+    hasFile(filename: string): boolean;
+    /**
+     * List all files in the archive.
+     */
+    listFiles(): string[];
+    /**
+     * Get a readable stream of bytes for a file.
+     */
+    private getFileBytes;
+    /**
+     * Stream parse a CSV file, yielding typed records one at a time.
+     *
+     * The return type is automatically inferred based on the filename:
+     * - `"stops.txt"` → `AsyncGenerator<GtfsStop>`
+     * - `"routes.txt"` → `AsyncGenerator<GtfsRoute>`
+     * - `"shapes.txt"` → `AsyncGenerator<GtfsShapePoint>`
+     * - etc.
+     *
+     * @param filename - The GTFS filename to parse (e.g., "stops.txt")
+     * @returns An async generator yielding typed records
+     *
+     * @example
+     * ```ts
+     * for await (const stop of archive.iter("stops.txt")) {
+     *   console.log(stop.stop_name) // TypeScript knows this is GtfsStop
+     * }
+     * ```
+     */
+    iter<F extends GtfsFileName>(filename: F): AsyncGenerator<GtfsFileTypeMap[F], void, unknown>;
+}
+//# sourceMappingURL=gtfs-archive.d.ts.map

package/dist/gtfs-archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gtfs-archive.d.ts","sourceRoot":"","sources":["../src/gtfs-archive.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACX,UAAU,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,QAAQ,EACR,MAAM,SAAS,CAAA;AAGhB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,YAAY,EAAE,UAAU,CAAA;IACxB,WAAW,EAAE,QAAQ,CAAA;IACrB,YAAY,EAAE,SAAS,CAAA;IACvB,WAAW,EAAE,QAAQ,CAAA;IACrB,gBAAgB,EAAE,YAAY,CAAA;IAC9B,YAAY,EAAE,cAAc,CAAA;CAC5B;AAED,+CAA+C;AAC/C,MAAM,MAAM,YAAY,GAAG,MAAM,eAAe,CAAA;AAEhD;;;;;;;GAOG;AACH,qBAAa,WAAW;IACvB,OAAO,CAAC,OAAO,CAAsB;IAErC,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,GAAG,WAAW;IAiB9D;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,SAAS,IAAI,MAAM,EAAE;IAIrB;;OAEG;YACW,YAAY;IAQ1B;;;;;;;;;;;;;;;;;;OAkBG;IACI,IAAI,CAAC,CAAC,SAAS,YAAY,EACjC,QAAQ,EAAE,CAAC,GACT,cAAc,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC;CAoBpD"}

package/dist/gtfs-archive.js

@@ -0,0 +1,102 @@
+/**
+ * Lazy GTFS archive parser with streaming CSV support.
+ *
+ * Only parses CSV files when they are accessed, not upfront.
+ * Uses @std/csv CsvParseStream for true line-by-line streaming.
+ *
+ * @module
+ */
+import { CsvParseStream } from "@std/csv/parse-stream";
+import { unzip } from "but-unzip";
+import { bytesToTextStream } from "./utils";
+/**
+ * Lazy GTFS archive that only parses files on demand.
+ *
+ * Files are read from the zip and parsed only when their
+ * corresponding getter is called for the first time.
+ * Streaming iterators parse CSV line-by-line without loading
+ * the entire file into memory.
+ */
+export class GtfsArchive {
+    entries;
+    constructor(entries) {
+        this.entries = entries;
+    }
+    /**
+     * Create a GtfsArchive from zip data.
+     */
+    static fromZip(zipData) {
+        const bytes = zipData instanceof Uint8Array ? zipData : new Uint8Array(zipData);
+        const items = unzip(bytes);
+        const entries = new Map();
+        for (const item of items) {
+            // Remove directory prefix and store by filename
+            const name = item.filename.replace(/^.*\//, "");
+            if (name.endsWith(".txt")) {
+                entries.set(name, item);
+            }
+        }
+        return new GtfsArchive(entries);
+    }
+    /**
+     * Check if a file exists in the archive.
+     */
+    hasFile(filename) {
+        return this.entries.has(filename);
+    }
+    /**
+     * List all files in the archive.
+     */
+    listFiles() {
+        return Array.from(this.entries.keys());
+    }
+    /**
+     * Get a readable stream of bytes for a file.
+     */
+    async getFileBytes(filename) {
+        const entry = this.entries.get(filename);
+        if (!entry)
+            return null;
+        const data = entry.read();
+        return data instanceof Promise ? await data : data;
+    }
+    /**
+     * Stream parse a CSV file, yielding typed records one at a time.
+     *
+     * The return type is automatically inferred based on the filename:
+     * - `"stops.txt"` → `AsyncGenerator<GtfsStop>`
+     * - `"routes.txt"` → `AsyncGenerator<GtfsRoute>`
+     * - `"shapes.txt"` → `AsyncGenerator<GtfsShapePoint>`
+     * - etc.
+     *
+     * @param filename - The GTFS filename to parse (e.g., "stops.txt")
+     * @returns An async generator yielding typed records
+     *
+     * @example
+     * ```ts
+     * for await (const stop of archive.iter("stops.txt")) {
+     *   console.log(stop.stop_name) // TypeScript knows this is GtfsStop
+     * }
+     * ```
+     */
+    async *iter(filename) {
+        const bytes = await this.getFileBytes(filename);
+        if (!bytes)
+            return;
+        const textStream = bytesToTextStream(bytes);
+        const csvStream = textStream.pipeThrough(new CsvParseStream({ skipFirstRow: true }));
+        const reader = csvStream.getReader();
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                yield value;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}
+//# sourceMappingURL=gtfs-archive.js.map