gtfs 4.17.7 → 4.18.0

package/dist/index.d.ts

@@ -3,36 +3,132 @@ import Database$1, { Database } from 'better-sqlite3';
 import { FeatureCollection } from 'geojson';
 
 type UnixTimestamp = number;
-interface ConfigAgency {
-    exclude?: string[];
-    url?: string;
-    path?: string;
+type TableNames = 'agency' | 'stops' | 'routes' | 'trips' | 'stop_times' | 'calendar' | 'calendar_dates' | 'fare_attributes' | 'fare_rules' | 'timeframes' | 'rider_categories' | 'fare_media' | 'fare_products' | 'fare_leg_rules' | 'fare_leg_join_rules' | 'fare_transfer_rules' | 'areas' | 'stop_areas' | 'networks' | 'route_networks' | 'shapes' | 'frequencies' | 'transfers' | 'pathways' | 'levels' | 'location_groups' | 'location_group_stops' | 'locations' | 'booking_rules' | 'translations' | 'feed_info' | 'attributions';
+interface BaseConfigAgency {
+    /**
+     * An array of GTFS file names (without .txt) to exclude when importing
+     */
+    exclude?: TableNames[];
+    /**
+     * An object of HTTP headers in key:value format to use when fetching GTFS from the url specified
+     */
     headers?: Record<string, string>;
+    /**
+     * Settings for fetching GTFS-Realtime alerts
+     */
     realtimeAlerts?: {
+        /**
+         * URL for fetching GTFS-Realtime alerts
+         */
         url: string;
+        /**
+         * Headers to use when fetching GTFS-Realtime alerts
+         */
         headers?: Record<string, string>;
     };
+    /**
+     * Settings for fetching GTFS-Realtime trip updates
+     */
     realtimeTripUpdates?: {
+        /**
+         * URL for fetching GTFS-Realtime trip updates
+         */
         url: string;
+        /**
+         * Headers to use when fetching GTFS-Realtime trip updates
+         */
         headers?: Record<string, string>;
     };
+    /**
+     * Settings for fetching GTFS-Realtime vehicle positions
+     */
     realtimeVehiclePositions?: {
+        /**
+         * URL for fetching GTFS-Realtime vehicle positions
+         */
         url: string;
+        /**
+         * Headers to use when fetching GTFS-Realtime vehicle positions
+         */
         headers?: Record<string, string>;
     };
+    /**
+     * A prefix to be added to every ID field maintain uniqueness when importing multiple GTFS from multiple agencies
+     */
     prefix?: string;
 }
+type ConfigAgency = BaseConfigAgency & ({
+    /**
+     * The URL to a zipped GTFS file. Required if path not present
+     */
+    url: string;
+} | {
+    /**
+     * A path to a zipped GTFS file or a directory of unzipped .txt files. Required if url is not present
+     */
+    path: string;
+});
 interface Config {
+    /**
+     * An existing database instance to use instead of relying on node-gtfs to connect.
+     */
     db?: Database;
+    /**
+     * A path to an SQLite database. Defaults to using an in-memory database.
+     */
     sqlitePath?: string;
+    /**
+     * Amount of time in seconds to allow GTFS-Realtime data to be stored in database before allowing to be deleted.
+     *
+     * Note: is an integer
+     *
+     * @defaultValue 0
+     */
     gtfsRealtimeExpirationSeconds?: number;
+    /**
+     * The number of milliseconds to wait before throwing an error when downloading GTFS.
+     *
+     * Note: is an integer
+     */
     downloadTimeout?: number;
+    /**
+     * Options passed to `csv-parse` for parsing GTFS CSV files.
+     */
     csvOptions?: Options;
+    /**
+     * A path to a directory to put exported GTFS files.
+     *
+     * @defaultValue `gtfs-export/<agency_name>`
+     */
     exportPath?: string;
+    /**
+     * Whether or not to ignore unique constraints on ids when importing GTFS, such as `trip_id`, `calendar_id`.
+     *
+     * @defaultValue false
+     */
     ignoreDuplicates?: boolean;
+    /**
+     * Whether or not to ignore errors during the import process. If true, failed files will be skipped while the rest are processed.
+     *
+     * @defaultValue false
+     */
     ignoreErrors?: boolean;
+    /**
+     * An array of GTFS files to be imported, and which files to exclude.
+     */
     agencies: ConfigAgency[];
+    /**
+     * Whether or not to print output to the console.
+     *
+     * @defaulValue true
+     */
     verbose?: boolean;
+    /**
+     * An optional custom logger instead of the build in console.log
+     *
+     * @param message
+     * @returns
+     */
     logFunction?: (message: string) => void;
 }
 interface ModelColumn {
@@ -49,7 +145,7 @@ interface ModelColumn {
     prefix?: boolean;
 }
 interface Model {
-    filenameBase: string;
+    filenameBase: TableNames;
     filenameExtension?: string;
     extension?: string;
     nonstandard?: boolean;
@@ -623,8 +719,16 @@ interface StopAttribute {
     stop_city?: string;
 }
 
+/**
+ * Function to import GTFS files into the database
+ *
+ * @param initialConfig
+ */
 declare function importGtfs(initialConfig: Config): Promise<void>;
 
+/**
+ * Main function to update GTFS Realtime data
+ */
 declare function updateGtfsRealtime(initialConfig: Config): Promise<void>;
 
 declare const exportGtfs: (initialConfig: Config) => Promise<void>;
@@ -643,7 +747,41 @@ declare function advancedQuery(table: string, advancedQueryOptions: {
     orderBy?: SqlOrderBy;
     join?: JoinOptions[];
     options?: QueryOptions;
-}): Array<Record<string, any>>;
+}): Array<Record<string, SqlValue>>;
+
+/**
+ * Prepares a directory for saving files by clearing its contents
+ * @param {string} exportPath - Path to the directory to prepare
+ * @returns {Promise<void>}
+ * @example
+ * await prepDirectory('./output');
+ */
+declare function prepDirectory(exportPath: string): Promise<void>;
+/**
+ * Extracts contents of a zip file to specified directory
+ * @param {string} zipfilePath - Path to the zip file
+ * @param {string} exportPath - Directory to extract contents to
+ * @returns {Promise<void>}
+ * @throws {Error} If zip file cannot be opened or extracted
+ * @example
+ * await unzip('./data.zip', './extracted');
+ */
+declare function unzip(zipfilePath: string, exportPath: string): Promise<void>;
+/**
+ * Generates a safe folder name from input string
+ * Converts to snake_case and removes unsafe characters
+ * @param {string} folderName - Input string to convert to folder name
+ * @returns {string} Sanitized folder name
+ * @example
+ * generateFolderName('My Folder!') // returns 'my_folder'
+ */
+declare function generateFolderName(folderName: string): string;
+/**
+ * Converts a tilde path to a full path
+ * @param pathWithTilde The path to convert
+ * @returns The full path
+ */
+declare function untildify(pathWithTilde: string): string;
 
 declare function getAgencies<Fields extends keyof Agency>(query?: SqlWhere, fields?: Fields[], orderBy?: SqlOrderBy, options?: QueryOptions): QueryResult<Agency, Fields>[];
 
@@ -758,4 +896,4 @@ declare function getRunEvents<Fields extends keyof RunEvent>(query?: SqlWhere, f
 
 declare function getRunsPieces<Fields extends keyof RunPiece>(query?: SqlWhere, fields?: Fields[], orderBy?: SqlOrderBy, options?: QueryOptions): QueryResult<RunPiece, Fields>[];
 
-export { type Agency, type Area, type Attribution, type BoardAlight, type BookingRule, type Calendar, type CalendarAttribute, type CalendarDate, type Config, type ConfigAgency, type Deadhead, type DeadheadTime, type Direction, type FareAttribute, type FareLegRule, type FareMedia, type FareProduct, type FareRule, type FareTransferRule, type FeedInfo, type Frequency, type JoinOptions, type Level, type Location, type LocationGroup, type LocationGroupStop, type Model, type ModelColumn, type Network, type OpsLocation, type Pathway, type QueryOptions, type QueryResult, type RideFeedInfo, type RiderCategory, type RiderTrip, type Ridership, type Route, type RouteAttribute, type RouteNetwork, type RunEvent, type RunPiece, type ServiceAlert, type Shape, type SqlOrderBy, type SqlValue, type SqlWhere, type Stop, type StopArea, type StopAttribute, type StopTime, type StopTimeUpdate, type Timeframe, type Timetable, type TimetableNote, type TimetableNotesReference, type TimetablePage, type TimetableStopOrder, type Transfer, type Translation, type Trip, type TripCapacity, type TripUpdate, type TripsDatedVehicleJourney, type UnixTimestamp, type VehiclePosition, advancedQuery, closeDb, deleteDb, exportGtfs, getAgencies, getAreas, getAttributions, getBoardAlights, getBookingRules, getCalendarAttributes, getCalendarDates, getCalendars, getDeadheadTimes, getDeadheads, getDirections, getFareAttributes, getFareLegRules, getFareMedia, getFareProducts, getFareRules, getFareTransferRules, getFeedInfo, getFrequencies, getLevels, getLocationGroupStops, getLocationGroups, getLocations, getNetworks, getOpsLocations, getPathways, getRideFeedInfo, getRiderCategories, getRiderTrips, getRidership, getRouteAttributes, getRouteNetworks, getRoutes, getRunEvents, getRunsPieces, getServiceAlerts, getServiceIdsByDate, getShapes, getShapesAsGeoJSON, getStopAreas, getStopAttributes, getStopTimeUpdates, getStops, getStopsAsGeoJSON, getStoptimes, getTimeframes, getTimetableNotes, getTimetableNotesReferences, getTimetablePages, getTimetableStopOrders, getTimetables, getTransfers, getTranslations, getTripCapacities, getTripUpdates, getTrips, getTripsDatedVehicleJourneys, getVehiclePositions, importGtfs, openDb, updateGtfsRealtime };
+export { type Agency, type Area, type Attribution, type BoardAlight, type BookingRule, type Calendar, type CalendarAttribute, type CalendarDate, type Config, type ConfigAgency, type Deadhead, type DeadheadTime, type Direction, type FareAttribute, type FareLegRule, type FareMedia, type FareProduct, type FareRule, type FareTransferRule, type FeedInfo, type Frequency, type JoinOptions, type Level, type Location, type LocationGroup, type LocationGroupStop, type Model, type ModelColumn, type Network, type OpsLocation, type Pathway, type QueryOptions, type QueryResult, type RideFeedInfo, type RiderCategory, type RiderTrip, type Ridership, type Route, type RouteAttribute, type RouteNetwork, type RunEvent, type RunPiece, type ServiceAlert, type Shape, type SqlOrderBy, type SqlValue, type SqlWhere, type Stop, type StopArea, type StopAttribute, type StopTime, type StopTimeUpdate, type TableNames, type Timeframe, type Timetable, type TimetableNote, type TimetableNotesReference, type TimetablePage, type TimetableStopOrder, type Transfer, type Translation, type Trip, type TripCapacity, type TripUpdate, type TripsDatedVehicleJourney, type UnixTimestamp, type VehiclePosition, advancedQuery, closeDb, deleteDb, exportGtfs, generateFolderName, getAgencies, getAreas, getAttributions, getBoardAlights, getBookingRules, getCalendarAttributes, getCalendarDates, getCalendars, getDeadheadTimes, getDeadheads, getDirections, getFareAttributes, getFareLegRules, getFareMedia, getFareProducts, getFareRules, getFareTransferRules, getFeedInfo, getFrequencies, getLevels, getLocationGroupStops, getLocationGroups, getLocations, getNetworks, getOpsLocations, getPathways, getRideFeedInfo, getRiderCategories, getRiderTrips, getRidership, getRouteAttributes, getRouteNetworks, getRoutes, getRunEvents, getRunsPieces, getServiceAlerts, getServiceIdsByDate, getShapes, getShapesAsGeoJSON, getStopAreas, getStopAttributes, getStopTimeUpdates, getStops, getStopsAsGeoJSON, getStoptimes, getTimeframes, getTimetableNotes, getTimetableNotesReferences, getTimetablePages, getTimetableStopOrders, getTimetables, getTransfers, getTranslations, getTripCapacities, getTripUpdates, getTrips, getTripsDatedVehicleJourneys, getVehiclePositions, importGtfs, openDb, prepDirectory, untildify, unzip, updateGtfsRealtime };