@thetransportlab/tsopenldb v2.0.3

TSOpenLDB

A typescript library for interacting with the UK National Rail OpenLDBSV (staff) web service

API Registration: http://openldbsv.nationalrail.co.uk/

API Documentation: https://lite.realtime.nationalrail.co.uk/OpenLDBSVWS/

Library documentation: https://thetransportlab.github.io/TSOpenLDB/

Library documentation also found in the /docs folder

Install

To install version 2.0 (the version that these docs relate to):

yarn add @thetransportlab/tsopenldb@next

To install the current stable/prod version:

yarn add @thetransportlab/tsopenldb@latest

New in version 2

• Test suite
• Complete interfaces for arguments and responses
• Functional and class approaches
• Significantly reduced number of libraries

Basic Usage Example

The library provides class and functional approaches for usage. The class approach allows you to specify your API key only once, while the functional approach requires you to provide your API key with each call.

Important: We provide a function to get the current valid timestamp - getLondonTimeViaTemporal(). This accepts 1 optional parameter to specify the number of minutes to offset by. In the class-based approach, you can set this during new (see example below), or by calling timeOffsetInMinutes(<offset in minutes as number>) on an instance of the class.

This example will retrieve the arrival and departure board for Leeds (station CRS is LDS) for 10 minutes in the past.

Class approach

    const apiKey = "ADD_YOUR_API_KEY";
    import { TSOpenLDBSV } from "@thetransportlab/tsopenldb";

    const RunFn = async () => {
        const LDB = new TSOpenLDBSV({ apiKey });
        const data = await LDB.GetArrivalDepartureBoardByCRS({
            crs: "LDS",
        });
        console.log({ data });
    };

    RunFn();

Functional approach

    const apiKey = "ADD_YOUR_API_KEY";
    import { GetArrivalDepartureBoardByCRS } from "@thetransportlab/tsopenldb";

    const RunFn = async () => {
        const data = await GetArrivalDepartureBoardByCRS({
            apiKey,
            args: {
                crs: "LDS",
            },
        });
        console.log({ data });
    };

    RunFn();

Notes

Version 2 of this library is a complete rewrite from the ground up and is NOT compatible with previous versions. All functions which were working (based upon available documentation) at time of development have interfaces generated for responses and required arguments.

All functions which take arguments apply sensible default values where appropriate. This is because the API will often return an error if fields are missing. You can override the defaults inside the args object of a call.

Version 2 of this library makes use of the @js-temporal/polyfill in order to generate valid timestamps used by several calls. Although the temporal feature is still in stage 3 proposal, I felt it worthwhile to bring in the functionality in order to better improve the reliability of timestamps. This also allowed me to remove a number of different libraries that were being used to achieve this functionality in version 1.

Limitations

At present, version 2 of this library uses the 2017-10-01 WSDL (included). Attempts have been made to use the current 2021-11-01, but as of writing, this has not been successful.

Development

The development of this library is semi-automated.

API request interfaces (i.e. args and name) are manually generated at the moment:

• Run yarn viewendpoints
• This will generate nonreferenceEndpoints.json and referenceEndpoints.json in the src/devtools/ directory
• In these files, you'll fine a portTypes object.
• In that object, you'll fine an LDBSVServiceSoap object.
• In that object, you'll find a methods object.
• Each child includes the name of the endpoint as the key, and the value will be an object describing the endpoint

As of writing, I haven't had time to dig into these objects and put together an automated solution to generate these requests, so each request interface is manually written at this time. It's clunky, but it does the job.

API response interfaces are generated by running actual API calls. These API call details are stored in src/constants.ts (as referenceEndpoints and nonReferenceEndpoints). Calling yarn generateinterfaces will call each of these endpoints with the arguments defined in the above files and generate TS interfaces from the responses.

It's a clunky way of doing things and I'd love to have an automated solution which doesn't require me to call the endpoints, but I've not gotten around to writing that. This way brings the benefit of actually testing a function works as I'm developing the library.

Why not automate entirely using existing tools?

There's a few tools out there that generate typescript classes and interfaces from WSDL, but the ones I tried didn't seem to be able to generate code that was easy to work with. Since the purpose of this library is to make working with OpenLDBSV as easy as possible, I've opted to manually perform some parts with intentions to write an automated solution later.

Testing

First, obtain a valid RID for a train service - this will look something like 202207217636931. It can be obtained by running a request to the GetDepartureBoardByCRS endpoint and using a popular station CRS (e.g. LDS usually has trains 24/7 on most days).

Drop this RID into src/functions/nonreference/GetServiceDetailsByRID.test.ts, replacing the existing const serviceRid that's in there.

Next, create a .env file which includes your key in the format: OPENLDBSV_API_KEY="<Your OpenLDBSV API Key>"

Run yarn test.

You may be able to automate a way to grab a valid RID and test against that. I've not had chance to look into a solution for that as of writing.

Why?

Over the years, there have been a few libraries which implement support for the OpenLDB service, but not many of them correctly supported the staff service (OpenLDBSV).

This library provides a nice wrapper around the API calls and is designed to provide a super-flexible approach and ease of implementation. It doesn't modify the results that the API returns, so reading the documentation linked at the top of this readme is advised.