Add TypeScript .d.ts files

Apparently TypeScript doesn’t like parsing JSDoc comments in imported
libraries, so this might help users who are using m3api with TypeScript,
and/or users whose IDEs use TypeScript information. I’m not sure putting
the files in a separate types/ directory is the best approach, but I
like it better than clutting the root directory with them, even though I
haven’t yet found a way to inform TypeScript about the types/ directory
(other than the "types" entrypoint in package.json which only points at
one file and makes importing 'm3api' work). I don’t want to build the
files during packaging – I think it’s a desirable characteristic that
the published m3api package is just the same files as in Git (with some
unneeded files excluded).

A new test:types script checks that the .d.ts files stay in sync with
the .js source files. The new GitHub actions job is meant to extend this
check to completely new files, which would be missed by test:types (and
I don’t want to run `git add` there).

.github/workflows/test.yaml

@@ -25,3 +25,14 @@ jobs:
           node-version: 18
       - run: npm i --package-lock-only
       - run: git diff --exit-code
+  test-types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - run: npm ci
+      - run: npx tsc
+      - run: git add types/
+      - run: git diff --cached --exit-code

CHANGES.md

@@ -7,6 +7,8 @@ but this file may sometimes contain later improvements (e.g. typo fixes).
 
 ## next (not yet released)
 
+- m3api now includes TypeScript `.d.ts` declaration files in the `types/` directory.
+  Hopefully these will be useful to some users of the library.
 - Clarified `DEFAULT_OPTIONS` conventions a bit (adding `errorHandlers` is fine).
 - Updated dependencies.
 

package.json

@@ -3,6 +3,7 @@
 	"version": "0.8.4",
 	"description": "Minimal modern MediaWiki API wrapper.",
 	"main": "node.js",
+	"types": "types/node.d.ts",
 	"type": "module",
 	"scripts": {
 		"test": "npm-run-all test:*",
@@ -11,6 +12,7 @@
 		"test:unit": "mocha test/unit/",
 		"test:node": "mocha test/integration/node.test.js",
 		"test:browser": "mocha test/integration/browser.test.js # #23",
+		"test:types": "tsc && git diff --exit-code types/",
 		"test:readme": "sed -n '/```/,/```/ { /```$/q; /```/n; p; }' README.md | node --input-type=module",
 		"doc": "jsdoc -c jsdoc/conf.json"
 	},
@@ -43,7 +45,8 @@
 		"eslint-plugin-compat": "^4.2.0",
 		"jsdoc": "^4.0.2",
 		"mocha": "^11.0.1",
-		"npm-run-all": "^4.1.5"
+		"npm-run-all": "^4.1.5",
+		"typescript": "^5.7.3"
 	},
 	"overrides": {
 		"chai": "^5.1.0"

tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"include": [ "*.js" ],
+	"compilerOptions": {
+		"allowJs": true,
+		"declaration": true,
+		"declarationDir": "types",
+		"declarationMap": true,
+		"emitDeclarationOnly": true,
+		"skipLibCheck": true
+	}
+}

types/README.md

@@ -0,0 +1,11 @@
+# m3api types
+
+These TypeScript declaration files are compiled from the JSDoc comments in the JavaScript source files.
+They are offered in the hope that some will find them useful,
+but they should not be considered an integral part of m3api.
+(They are also not a part of its stable or even internal interface.)
+
+Suggestions to improve the types are welcome,
+provided that the improvements can be implemented in the JS files
+without negatively impacting the JS code too much.
+(For instance, the way the files are currently distributed could perhaps be improved.)

types/browser.d.ts

@@ -0,0 +1,5 @@
+export default class BrowserSession extends FetchBrowserSession {
+}
+import { FetchBrowserSession } from './fetch-browser.js';
+export { ApiErrors, ApiWarnings, set } from "./core.js";
+//# sourceMappingURL=browser.d.ts.map

types/combine.d.ts

@@ -0,0 +1,2 @@
+export function mixCombiningSessionInto(otherClass: any): void;
+//# sourceMappingURL=combine.d.ts.map