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"
+  ]
+}

.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: 20
+
+      - 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,25 @@
+#!/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
+
+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

format/lines-req.js

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

format/location.js

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

format/locations-req.js

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

format/nearby-req.js

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

format/products-filter.js

@@ -1,7 +1,12 @@
 import isObj from 'lodash/isObject.js';
 
+/**
+ * @import {DefaultProfile} from "../types-private"
+ */
+
 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 @@
+/**
+ * @import {DefaultProfile} from "../types-private"
+ */
+
+/** @type {DefaultProfile["formatRadarReq"]} */
 const formatRadarReq = (ctx, north, west, south, east) => {
 	const {profile, opt} = ctx;
 

format/reachable-from-req.js

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

format/rectangle.js

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

format/refresh-journey-req.js

@@ -1,6 +1,12 @@
+/**
+ * @import {DefaultProfile} from "../types-private"
+ */
+
+/** @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 @@
+/**
+ * @import {DefaultProfile} from "../types-private"
+ */
+
+/** @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 @@
+/**
+ * @import {DefaultProfile} from "../types-private"
+ */
+
+/** @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 @@
+/**
+ * @import {DefaultProfile} from "../types-private"
+ */
+
+/** @type {DefaultProfile["formatStopReq"]} */
 const formatStopReq = (ctx, stopRef) => {
 	return {
 		// todo: there's also `StationDetails`, are there differences?

format/trip-req.js

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