tfl-ts
Version:
🚇 Fully-typed TypeScript client for Transport for London (TfL) API • Zero dependencies • Auto-generated types • Real-time arrivals • Journey planning • Universal compatibility
255 lines (254 loc) • 10.2 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
exports.ROAD_DATA = exports.SeverityByMode = exports.ROAD_SEVERITY_DESCRIPTIONS = exports.ROAD_CATEGORIES = exports.Road = void 0;
const stripTypes_1 = require("./utils/stripTypes");
// Import raw data from generated meta files
const Road_1 = require("./generated/jsdoc/Road");
Object.defineProperty(exports, "ROAD_DATA", { enumerable: true, get: function () { return Road_1.ROAD_DATA; } });
const Road_2 = require("./generated/meta/Road");
Object.defineProperty(exports, "SeverityByMode", { enumerable: true, get: function () { return Road_2.SeverityByMode; } });
// Create arrays from the types for static properties
const ROAD_CATEGORIES = [
'Undefined', 'RealTime', 'PlannedWork', 'Information', 'Event', 'Crowding', 'StatusAlert'
];
exports.ROAD_CATEGORIES = ROAD_CATEGORIES;
const ROAD_SEVERITY_DESCRIPTIONS = [
'Good Service', 'Minor Delays', 'Severe Delays', 'Part Suspended', 'Suspended'
];
exports.ROAD_SEVERITY_DESCRIPTIONS = ROAD_SEVERITY_DESCRIPTIONS;
/**
* Road class for interacting with TfL Road API endpoints
* @example
* // Get all roads managed by TfL
* const allRoads = await client.road.get();
*
* // Get status for specific roads
* const status = await client.road.getStatus({ ids: ['A406', 'A2'] });
*
* // Get disruptions for roads
* const disruptions = await client.road.getDisruptions({ ids: ['A406'] });
*
* // Access static metadata (no HTTP request)
* const categories = client.road.ROAD_CATEGORIES;
* const severities = client.road.ROAD_SEVERITY_DESCRIPTIONS;
*/
class Road {
constructor(api) {
this.api = api;
/** Available API endpoints (static, no HTTP request needed) */
this.ENDPOINTS = Road_1.ROAD_DATA.endpoints;
/** Total number of available endpoints (static, no HTTP request needed) */
this.TOTAL_ENDPOINTS = Road_1.ROAD_DATA.totalEndpoints;
/** API section name (static, no HTTP request needed) */
this.SECTION = Road_1.ROAD_DATA.section;
/** Generation timestamp (static, no HTTP request needed) */
this.GENERATED_AT = Road_1.ROAD_DATA.generatedAt;
/** Available road categories (static, no HTTP request needed) */
this.ROAD_CATEGORIES = ROAD_CATEGORIES;
/** Available road severity descriptions (static, no HTTP request needed) */
this.ROAD_SEVERITY_DESCRIPTIONS = ROAD_SEVERITY_DESCRIPTIONS;
/** Road severity by mode mapping (static, no HTTP request needed) */
this.SEVERITY_BY_MODE = Road_2.SeverityByMode;
}
/**
* Gets all roads managed by TfL
*
* This method returns a comprehensive list of all roads managed by TfL,
* including major arterial routes, red routes, and other strategic roads.
*
* @param options - Options for the request
* @returns Promise resolving to an array of road corridors
* @example
* // Get all roads managed by TfL
* const allRoads = await client.road.get();
*
* // Get roads with type fields preserved
* const allRoads = await client.road.get({ keepTflTypes: true });
*
* // Process road data
* allRoads.forEach(road => {
* console.log(`${road.displayName}: ${road.statusSeverityDescription}`);
* });
*/
async get(options = {}) {
return this.api.road.roadGet()
.then(response => (0, stripTypes_1.stripTypeFields)(response.data, options.keepTflTypes));
}
/**
* Gets the road with the specified id
*
* This method returns detailed information about specific roads by their identifiers.
*
* @param ids - Array of road identifiers (e.g., ['A406', 'A2'])
* @param options - Options for the request
* @returns Promise resolving to an array of road corridors
* @example
* // Get specific roads by ID
* const roads = await client.road.getById(['A406', 'A2']);
*
* // Get single road
* const road = await client.road.getById(['A406']);
*/
async getById(ids, options = {}) {
return this.api.road.roadGet2(ids)
.then((response) => (0, stripTypes_1.stripTypeFields)(response.data, options.keepTflTypes));
}
/**
* Gets the specified roads with the status aggregated over the date range specified
*
* This method returns road status information aggregated over a specified date range,
* or from now until the end of today if no dates are provided.
*
* @param options - Query options for road status
* @returns Promise resolving to an array of road corridors with status
* @example
* // Get status for specific roads
* const status = await client.road.getStatus({
* ids: ['A406', 'A2'],
* dateRange: {
* startDate: '2023-01-01',
* endDate: '2023-01-31'
* }
* });
*
* // Get current status for all roads
* const allStatus = await client.road.getStatus({ ids: ['all'] });
*
* // Get status with type fields preserved
* const status = await client.road.getStatus({
* ids: ['A406'],
* keepTflTypes: true
* });
*/
async getStatus(options) {
const { ids, dateRange, keepTflTypes } = options;
return this.api.road.roadStatus({
ids: Array.isArray(ids) ? ids : [ids],
dateRangeNullableStartDate: dateRange?.startDate,
dateRangeNullableEndDate: dateRange?.endDate
}).then(response => (0, stripTypes_1.stripTypeFields)(response.data, keepTflTypes));
}
/**
* Get active disruptions, filtered by road ids
*
* This method returns active road disruptions with optional filtering by
* severity, category, and content stripping options.
*
* @param options - Query options for road disruptions
* @returns Promise resolving to an array of road disruptions
* @example
* // Get disruptions for specific roads
* const disruptions = await client.road.getDisruptions({
* ids: ['A406', 'A2'],
* stripContent: false,
* severities: ['Good Service', 'Minor Delays']
* });
*
* // Get all disruptions for all roads
* const allDisruptions = await client.road.getDisruptions({
* ids: ['all'],
* categories: ['RealTime', 'PlannedWork']
* });
*
* // Get minimal disruption data
* const minimalDisruptions = await client.road.getDisruptions({
* ids: ['A406'],
* stripContent: true
* });
*/
async getDisruptions(options) {
const { ids, stripContent, severities, categories, closures, keepTflTypes } = options;
return this.api.road.roadDisruption({
ids: Array.isArray(ids) ? ids : [ids],
stripContent,
severities,
categories,
closures
}).then(response => (0, stripTypes_1.stripTypeFields)(response.data, keepTflTypes));
}
/**
* Gets a list of disrupted streets
*
* This method returns a list of streets that are currently disrupted.
* If no date filters are provided, current disruptions are returned.
*
* @param options - Query options for street disruptions
* @returns Promise resolving to disrupted streets data
* @example
* // Get disrupted streets for a date range
* const streets = await client.road.getDisruptedStreets({
* startDate: '2023-01-01',
* endDate: '2023-01-31'
* });
*
* // Get current disrupted streets
* const currentStreets = await client.road.getDisruptedStreets({
* startDate: new Date().toISOString(),
* endDate: new Date().toISOString()
* });
*/
async getDisruptedStreets(options) {
const { startDate, endDate, keepTflTypes } = options;
return this.api.road.roadDisruptedStreets({
startDate,
endDate
}).then(response => (0, stripTypes_1.stripTypeFields)(response.data, keepTflTypes));
}
/**
* Gets a list of active disruptions filtered by disruption Ids
*
* This method returns specific disruptions by their identifiers,
* with optional content stripping for minimal data.
*
* @param options - Query options for disruption by ID
* @returns Promise resolving to road disruption data
* @example
* // Get specific disruptions by ID
* const disruption = await client.road.getDisruptionById({
* disruptionIds: ['12345', '67890'],
* stripContent: true
* });
*
* // Get full disruption details
* const fullDisruption = await client.road.getDisruptionById({
* disruptionIds: ['12345'],
* stripContent: false
* });
*/
async getDisruptionById(options) {
const { disruptionIds, stripContent, keepTflTypes } = options;
return this.api.road.roadDisruptionById({
disruptionIds: Array.isArray(disruptionIds) ? disruptionIds : [disruptionIds],
stripContent
}).then(response => (0, stripTypes_1.stripTypeFields)(response.data, keepTflTypes));
}
/**
* Get road metadata (makes HTTP request to TfL API)
*
* This method fetches live metadata from the TfL API. For static metadata
* that doesn't change frequently, consider using the static properties
* instead to save HTTP round trips.
*
* @param options - Options for metadata request
* @returns Promise resolving to road metadata
* @example
* // Get live metadata from TfL API
* const meta = await client.road.getMeta();
*
* // Use static metadata instead (no HTTP request)
* const categories = client.road.ROAD_CATEGORIES;
* const severities = client.road.ROAD_SEVERITY_DESCRIPTIONS;
*/
async getMeta(options = {}) {
return {
endpoints: this.ENDPOINTS,
totalEndpoints: this.TOTAL_ENDPOINTS,
section: this.SECTION,
generatedAt: this.GENERATED_AT,
categories: this.ROAD_CATEGORIES,
severities: this.ROAD_SEVERITY_DESCRIPTIONS,
severityByMode: this.SEVERITY_BY_MODE
};
}
}
exports.Road = Road;