add types

.dprint.json

@@ -0,0 +1,24 @@
+{
+  "typescript": {
+  },
+  "json": {
+  },
+  "markdown": {
+  },
+  "toml": {
+  },
+  "excludes": [
+    "**/node_modules",
+    "**/*.js",
+    "**/*.md",
+    "**/*.json"
+  ],
+  "indentWidth": 4,
+  "lineWidth": 120,
+  "plugins": [
+    "https://plugins.dprint.dev/typescript-0.89.0.wasm",
+    "https://plugins.dprint.dev/json-0.19.1.wasm",
+    "https://plugins.dprint.dev/markdown-0.16.3.wasm",
+    "https://plugins.dprint.dev/toml-0.6.0.wasm"
+  ]
+}

.eslintrc.json

@@ -29,9 +29,11 @@
         "@stylistic/function-paren-newline": "off",
         "@stylistic/indent": ["error", "tab"],
         "@stylistic/indent-binary-ops": ["error", "tab"],
+        "@stylistic/lines-around-comment": ["error", { "ignorePattern": "Bergmann" }],
         "@stylistic/max-len": "off",
         "@stylistic/multiline-ternary": ["error", "always-multiline"],
         "@stylistic/newline-per-chained-call": ["error", { "ignoreChainWithDepth": 1 }],
+        "@stylistic/no-extra-parens": "off", /* J.B. tsc doc typing needs parens */
         "@stylistic/no-mixed-operators": "off",
         "@stylistic/no-tabs": "off",
         "@stylistic/object-property-newline": "off",

.github/workflows/test-types.yml

@@ -0,0 +1,29 @@
+name: test types
+
+on: 
+  push:
+    branches: [ add-types-in-jsdoc ]
+
+jobs:
+
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          ref: add-types-in-jsdoc 
+
+      - name: setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+
+      - run: npm install
+
+      - run: npm run tsc
+      - run: npm run lint
+      - run: npm run test-unit

.gitignore

@@ -8,3 +8,4 @@ npm-debug.log
 package-lock.json
 
 /.tap
+/build

.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Launch Program",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/test/index.js",
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+	"editor.insertSpaces": false
+}

.vscode/settings.template.json

@@ -0,0 +1,6 @@
+{
+    "[typescript]": {
+        "editor.defaultFormatter": "dprint.dprint",
+        "editor.formatOnSave": true
+    }
+}

changed-files.txt

@@ -0,0 +1 @@
+.gitignore create-declaration-file.sh export-defaultProfile.js format/ index.d.ts index.js lib/ p/ package.json parse/ tsconfig.json types-private.ts types.ts typescript-readme.md

create-declaration-file.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# create a TypeScript declaration file for DefinitelyTyped ./build/index.d.ts are included
+
+if [ ! -f "./tsconfig.json" ]; then
+    echo "please run from project directory"
+    exit 1
+fi
+
+npx tsc --emitDeclarationOnly true --noEmit false
+
+if [ $? -ne 0 ]
+then
+  exit 1
+fi
+
+VERSION=$(grep "version" package.json | sed -E 's/.*([0-9]+\.[0-9]+)\..*/\1/')
+
+cat ./build/types.d.ts > ./index.d.ts
+
+cat >> ./index.d.ts << EOF
+
+export function createClient(commonProfile: Profile, userAgent: string, opt?: any): HafasClient;
+EOF
+
+sed -i 's/export declare type/export type/' index.d.ts
+
+dprint fmt index.d.ts

create-types-test-file.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# create a TypeScript file from test fixture js and json files and tools/debug-cli/cli.js results
+
+if [ ! -f "./tsconfig.json" ]; then
+    echo "please run from project directory"
+    exit 1
+fi
+
+DATE=$(date)
+OUTFILE="types-test-generated.ts"
+
+echo "// created with script './create-types-test-file.sh' at ${DATE}" > ${OUTFILE}
+echo "" >> ${OUTFILE}
+echo "import { Journeys, Journey, Alternative, Station, Stop, Location, Departures, Arrivals } from './types'" >> ${OUTFILE}
+echo "import { RawResult, RawResponse } from './types-raw-api'" >> ${OUTFILE}
+
+echo "const r1 : RawResult = " >> ${OUTFILE}
+cat test/fixtures/db-journey.json >> ${OUTFILE}
+
+echo "const r2 : RawResult = " >> ${OUTFILE}
+cat test/fixtures/db-journey-2.json >> ${OUTFILE}
+
+echo "const r3 : RawResult = " >> ${OUTFILE}
+cat test/fixtures/db-journey-polyline.json >> ${OUTFILE}
+
+sed -e '/use strict/d' -e 's/const dbJourney/const dbJourney: Journey/' test/fixtures/db-journey.js >> ${OUTFILE}
+
+sed -e '/use strict/d' -e 's/const dbJourneyPolyline/const dbJourneyPolyline: Journey/' test/fixtures/db-journey-polyline.js >> ${OUTFILE}
+
+sed -e '/use strict/d' -e 's/const dbArrivals/const dbArrivals: Alternative[]/' test/fixtures/db-arrivals.js >> ${OUTFILE}
+
+sed -e '/use strict/d' -e 's/const bvgRadar/const bvgRadar: Alternative[]/' test/fixtures/bvg-radar.js >> ${OUTFILE}
+
+echo "const journeys : Journeys = " >> ${OUTFILE}
+DEBUG=hafas-client node tools/debug-cli/cli.js db journeys 8000149 8000152 '{"results": 10, "transfers": 0, "stopovers": true}' >> ${OUTFILE} 2>x.txt
+
+echo "const rawResponse : RawResponse = " >> ${OUTFILE}
+tail -1 x.txt >> ${OUTFILE}
+rm x.txt
+
+echo "const locations : (Station | Stop | Location)[] = " >> ${OUTFILE}
+node tools/debug-cli/cli.js db locations Hannover >> ${OUTFILE}
+
+echo "const departures : Departures = " >> ${OUTFILE}
+node tools/debug-cli/cli.js db departures 8000152 >> ${OUTFILE}
+
+echo "const arrivals : Arrivals = " >> ${OUTFILE}
+node tools/debug-cli/cli.js db arrivals 8000152 >> ${OUTFILE}

format/lines-req.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatLinesReq"]} */
 const formatLinesReq = (ctx, query) => {
 	return {
 		meth: 'LineMatch',

format/location.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatLocation"]} */
 const formatLocation = (profile, l, name = 'location') => {
 	if ('string' === typeof l) {
 		return profile.formatStation(l);

format/locations-req.js

@@ -1,3 +1,9 @@
+/**
+ * @typedef {import("../types-private").ProfileEx} ProfileEx
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatLocationsReq"]} */
 const formatLocationsReq = (ctx, query) => {
 	const {profile, opt} = ctx;
 

format/nearby-req.js

@@ -1,3 +1,9 @@
+/**
+ * @typedef {import("../types-private").ProfileEx} ProfileEx
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatNearbyReq"]} */
 const formatNearbyReq = (ctx, location) => {
 	const {profile, opt} = ctx;
 

format/products-filter.js

@@ -1,7 +1,13 @@
 import isObj from 'lodash/isObject.js';
 
+/**
+ * @typedef {import("../types-private").ProfileEx} ProfileEx
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
 const hasProp = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
 
+/** @type {DefaultProfile["formatProductsFilter"]} */
 const formatProductsFilter = (ctx, filter) => {
 	if (!isObj(filter)) {
 		throw new TypeError('products filter must be an object');

format/radar-req.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatRadarReq"]} */
 const formatRadarReq = (ctx, north, west, south, east) => {
 	const {profile, opt} = ctx;
 

format/reachable-from-req.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatReachableFromReq"]} */
 const formatReachableFromReq = (ctx, address) => {
 	const {profile, opt} = ctx;
 

format/rectangle.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatRectangle"]} */
 const formatRectangle = (profile, north, west, south, east) => {
 	return {
 		llCrd: {

format/refresh-journey-req.js

@@ -1,6 +1,12 @@
+/**
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatRefreshJourneyReq"]} */
 const formatRefreshJourneyReq = (ctx, refreshToken) => {
 	const {profile, opt} = ctx;
 
+	/** @type {import("../types-raw-api").ReconstructionRequest} */
 	const req = {
 		getIST: true, // todo: make an option
 		getPasslist: Boolean(opt.stopovers),

format/remarks-req.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatRemarksReq"]} */
 const formatRemarksReq = (ctx) => {
 	const {profile, opt} = ctx;
 
@@ -7,6 +12,7 @@ const formatRemarksReq = (ctx) => {
 		himFltrL.push(profile.formatProductsFilter(ctx, opt.products));
 	}
 
+	/** @type {import("../types-raw-api").HimSearchRequest} */
 	const req = {
 		himFltrL,
 	};

format/station-board-req.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatStationBoardReq"]} */
 const formatStationBoardReq = (ctx, station, type) => {
 	const {profile, opt} = ctx;
 
@@ -8,6 +13,7 @@ const formatStationBoardReq = (ctx, station, type) => {
 		jnyFltrL.push({type: 'LINEID', mode: 'INC', value: opt.line});
 	}
 
+	/** @type {import("../types-raw-api").StationBoardRequest} */
 	const req = {
 		type,
 		date: profile.formatDate(profile, opt.when),

format/stop-req.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatStopReq"]} */
 const formatStopReq = (ctx, stopRef) => {
 	return {
 		// todo: there's also `StationDetails`, are there differences?

format/trip-req.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import("../types-private").DefaultProfile} DefaultProfile
+ */
+
+/** @type {DefaultProfile["formatTripReq"]} */
 const formatTripReq = ({opt}, id) => {
 	return {
 		cfg: {polyEnc: 'GPA'},