[New] add types

.eslintrc

@@ -23,6 +23,8 @@
         "no-underscore-dangle": "warn",
         "object-curly-newline": "off",
         "sort-keys": "off",
+
+		"no-extra-parens": "off",
     },
     "ignorePatterns": ["syntax-error.*"],
     "overrides": [

.github/workflows/node-aught.yml

@@ -9,3 +9,4 @@ jobs:
       range: '< 10'
       type: minors
       command: npm run tests-only
+      skip-ls-check: true

bin/import-or-require.js

@@ -4,6 +4,7 @@ const { extname: extnamePath } = require('path');
 const { pathToFileURL } = require('url');
 const getPackageType = require('get-package-type');
 
+/** @type {(file: string) => undefined | Promise<unknown>} */
 // eslint-disable-next-line consistent-return
 module.exports = function importOrRequire(file) {
 	const ext = extnamePath(file);

bin/tape

@@ -100,9 +100,11 @@ var hasImport = require('has-dynamic-import');
 
 var tape = require('../');
 
+/** @type {(hasSupport: boolean) => Promise<void> | void} */
 function importFiles(hasSupport) {
 	tape.wait();
 
+	/** @type {null | undefined | Promise<unknown>} */
 	var filesPromise;
 	if (hasSupport) {
 		var importOrRequire = require('./import-or-require');

example/array.js

@@ -26,11 +26,11 @@ test('array', function (t) {
 	];
 
 	Function('fn', 'g', String(output))(
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(arrays.shift(), xs);
 			return xs;
 		},
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(xs, [[1, 2, [3, 4]], [5, 6]]);
 		}
 	);

example/fail.js

@@ -26,11 +26,11 @@ test('array', function (t) {
 	];
 
 	Function('fn', 'g', String(output))(
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(arrays.shift(), xs);
 			return xs;
 		},
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(xs, [[1, 2, [3, 4444]], [5, 6]]);
 		}
 	);

example/nested.js

@@ -35,11 +35,11 @@ test('nested array test', function (t) {
 	];
 
 	Function('fn', 'g', String(output))(
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(arrays.shift(), xs);
 			return xs;
 		},
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(xs, [[1, 2, [3, 4]], [5, 6]]);
 		}
 	);

example/nested_fail.js

@@ -35,11 +35,11 @@ test('nested array test', function (t) {
 	];
 
 	Function('fn', 'g', String(output))(
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(arrays.shift(), xs);
 			return xs;
 		},
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(xs, [[1, 2, [3, 4]], [5, 6]]);
 		}
 	);

example/not_enough_fail.js

@@ -26,11 +26,11 @@ test('array', function (t) {
 	];
 
 	Function('fn', 'g', String(output))(
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(arrays.shift(), xs);
 			return xs;
 		},
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(xs, [[1, 2, [3, 4]], [5, 6]]);
 		}
 	);

example/too_many_fail.js

@@ -26,11 +26,11 @@ test('array', function (t) {
 	];
 
 	Function('fn', 'g', String(output))(
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(arrays.shift(), xs);
 			return xs;
 		},
-		function (xs) {
+		/** @param {number[]} xs */ function (xs) {
 			t.same(xs, [[1, 2, [3, 4]], [5, 6]]);
 		}
 	);

index.d.ts

@@ -0,0 +1,97 @@
+import type { ThroughStream } from '@ljharb/through';
+
+import type Test from './lib/test';
+import type Results from './lib/results';
+
+declare function harnessFunction(this: Test, name: string, opts: tape.TestOptions, cb: Test.TestCase): Test;
+declare function harnessFunction(this: Test, name: string, opts: tape.TestOptions): Test;
+declare function harnessFunction(this: Test, name: string, cb: Test.TestCase): Test;
+declare function harnessFunction(this: Test, name: string): Test;
+declare function harnessFunction(this: Test, opts: tape.TestOptions, cb: Test.TestCase): Test;
+declare function harnessFunction(this: Test, opts: tape.TestOptions): Test;
+declare function harnessFunction(this: Test, cb: Test.TestCase): Test;
+
+declare function harnessFunction(this: void, name: string, opts: tape.TestOptions, cb: Test.TestCase): Test;
+declare function harnessFunction(this: void, name: string, opts: tape.TestOptions): Test;
+declare function harnessFunction(this: void, name: string, cb: Test.TestCase): Test;
+declare function harnessFunction(this: void, name: string): Test;
+declare function harnessFunction(this: void, opts: tape.TestOptions, cb: Test.TestCase): Test;
+declare function harnessFunction(this: void, opts: tape.TestOptions): Test;
+declare function harnessFunction(this: void, cb: Test.TestCase): Test;
+
+declare namespace tape {
+    export type TestOptions = {
+        objectPrintDepth?: number | undefined;
+        skip?: boolean | string | undefined;
+        timeout?: number | undefined;
+        todo?: boolean | string | undefined;
+    };
+
+    export interface AssertOptions {
+        skip?: boolean | string | undefined;
+        todo?: boolean | string | undefined;
+        message?: string | undefined;
+        actual?: unknown;
+        expected?: unknown;
+        exiting?: boolean;
+    }
+
+    export interface StreamOptions {
+        objectMode?: boolean | undefined;
+    }
+
+    function createStream(opts?: StreamOptions): ThroughStream;
+
+    export type CreateStream = typeof createStream;
+
+    export type HarnessEventHandler = (cb: Test.SyncCallback, ...rest: unknown[]) => void;
+
+    function only(name: string, cb: Test.TestCase): void;
+    function only(name: string, opts: tape.TestOptions, cb: Test.TestCase): void;
+    function only(cb: Test.TestCase): void;
+    function only(opts: tape.TestOptions, cb?: Test.TestCase): void;
+
+    export type Harness = typeof harnessFunction & {
+        run?: () => void;
+        only: typeof only;
+        _exitCode: number;
+        _results: Results;
+        _tests: Test[];
+        close: () => void;
+        createStream: CreateStream;
+        onFailure: HarnessEventHandler;
+        onFinish: HarnessEventHandler;
+    }
+
+    export type HarnessConfig = {
+        autoclose?: boolean;
+        noOnly?: boolean;
+        stream?: NodeJS.WritableStream | ThroughStream;
+        exit?: boolean;
+    } & StreamOptions;
+
+    function createHarness(conf_?: HarnessConfig): Harness;
+    const Test: Test;
+    const test: typeof tape;
+    const skip: Test['skip'];
+
+	function getHarness(opts?: HarnessConfig): Harness;
+	function run(): void;
+	function onFailure(cb: Test.SyncCallback, ...rest: unknown[]): void;
+	function onFinish(cb: Test.SyncCallback, ...rest: unknown[]): void
+	function wait(): void;
+}
+
+declare function tape(this: tape.Harness, name: string, opts: tape.TestOptions, cb: Test.TestCase): Test;
+declare function tape(this: tape.Harness, name: string, cb: Test.TestCase): Test;
+declare function tape(this: tape.Harness, opts?: tape.TestOptions): Test;
+declare function tape(this: tape.Harness, opts: tape.TestOptions, cb: Test.TestCase): Test;
+declare function tape(this: tape.Harness, cb: Test.TestCase): Test;
+
+declare function tape(this: void, name: string, opts: tape.TestOptions, cb: Test.TestCase): Test;
+declare function tape(this: void, name: string, cb: Test.TestCase): Test;
+declare function tape(this: void, opts?: tape.TestOptions): Test;
+declare function tape(this: void, opts: tape.TestOptions, cb: Test.TestCase): Test;
+declare function tape(this: void, cb: Test.TestCase): Test;
+
+export = tape;

index.js

@@ -1,20 +1,33 @@
 'use strict';
 
 var defined = require('defined');
+var through = require('@ljharb/through');
+
 var createDefaultStream = require('./lib/default_stream');
 var Test = require('./lib/test');
 var Results = require('./lib/results');
-var through = require('@ljharb/through');
 
 var canEmitExit = typeof process !== 'undefined' && process
-	&& typeof process.on === 'function' && process.browser !== true;
+	&& typeof process.on === 'function' && /** @type {{ browser?: boolean }} */ (process).browser !== true;
 var canExit = typeof process !== 'undefined' && process
 	&& typeof process.exit === 'function';
 
-module.exports = (function () {
+/** @typedef {import('.')} Tape */
+/** @typedef {import('.').Harness} Harness */
+/** @typedef {import('.').HarnessConfig} HarnessConfig */
+/** @typedef {import('.').TestOptions} TestOptions */
+/** @typedef {import('.').HarnessEventHandler} HarnessEventHandler */
+/** @typedef {import('.').CreateStream} CreateStream */
+/** @typedef {import('.').createHarness} CreateHarness */
+/** @typedef {import('./lib/results').Result} Result */
+/** @typedef {import('stream').Writable} WritableStream */
+
+var tape = (function () {
 	var wait = false;
+	/** @type {undefined | Harness} */
 	var harness;
 
+	/** @type {(opts?: HarnessConfig) => Harness} */
 	function getHarness(opts) {
 		// this override is here since tests fail via nyc if createHarness is moved upwards
 		if (!harness) {
@@ -24,6 +37,7 @@ module.exports = (function () {
 		return harness;
 	}
 
+	/** @type {(this: Harness, ...args: Parameters<Tape>) => ReturnType<Tape>} */
 	function lazyLoad() {
 		// eslint-disable-next-line no-invalid-this
 		return getHarness().apply(this, arguments);
@@ -43,6 +57,7 @@ module.exports = (function () {
 		return getHarness().only.apply(this, arguments);
 	};
 
+	/** @type {CreateStream} */
 	lazyLoad.createStream = function (opts) {
 		var options = opts || {};
 		if (!harness) {
@@ -66,21 +81,23 @@ module.exports = (function () {
 	return lazyLoad;
 }());
 
+/** @type {CreateHarness} */
 function createHarness(conf_) {
 	var results = new Results({ todoIsOK: !!(process.env.TODO_IS_OK === '1') });
 	if (!conf_ || conf_.autoclose !== false) {
 		results.once('done', function () { results.close(); });
 	}
 
+	/** @type {(name: string, conf: TestOptions, cb: Test.TestCase) => Test} */
 	function test(name, conf, cb) {
 		var t = new Test(name, conf, cb);
 		test._tests.push(t);
 
 		(function inspectCode(st) {
-			st.on('test', function sub(st_) {
+			st.on('test', /** @type {(st: Test) => void} */ function sub(st_) {
 				inspectCode(st_);
 			});
-			st.on('result', function (r) {
+			st.on('result', /** @type {(r: Result) => void} */ function (r) {
 				if (!r.todo && !r.ok && typeof r !== 'string') { test._exitCode = 1; }
 			});
 		}(t));
@@ -90,21 +107,25 @@ function createHarness(conf_) {
 	}
 	test._results = results;
 
-	test._tests = [];
+	/** @type {Test[]} */ test._tests = [];
 
+	/** @type {CreateStream} */
 	test.createStream = function (opts) {
 		return results.createStream(opts);
 	};
 
+	/** @type {HarnessEventHandler} */
 	test.onFinish = function (cb) {
 		results.on('done', cb);
 	};
 
+	/** @type {HarnessEventHandler} */
 	test.onFailure = function (cb) {
 		results.on('fail', cb);
 	};
 
 	var only = false;
+	/** @type {() => Test} */
 	test.only = function () {
 		if (only) { throw new Error('there can only be one only test'); }
 		if (conf_ && conf_.noOnly) { throw new Error('`only` tests are prohibited'); }
@@ -117,9 +138,11 @@ function createHarness(conf_) {
 
 	test.close = function () { results.close(); };
 
+	// @ts-expect-error TODO FIXME: why is `test` not assignable to `Harness`???
 	return test;
 }
 
+/** @type {(conf: Omit<HarnessConfig, 'autoclose'>, wait?: boolean) => Harness} */
 function createExitHarness(config, wait) {
 	var noOnly = config.noOnly;
 	var objectMode = config.objectMode;
@@ -139,9 +162,8 @@ function createExitHarness(config, wait) {
 		var stream = harness.createStream({ objectMode: objectMode });
 		var es = stream.pipe(cStream || createDefaultStream());
 		if (canEmitExit && es) { // in node v0.4, `es` is `undefined`
-			// TODO: use `err` arg?
 			// eslint-disable-next-line no-unused-vars
-			es.on('error', function (err) { harness._exitCode = 1; });
+			es.on('error', function (_) { harness._exitCode = 1; });
 		}
 		stream.on('end', function () { ended = true; });
 	}
@@ -155,7 +177,7 @@ function createExitHarness(config, wait) {
 	if (exit === false) { return harness; }
 	if (!canEmitExit || !canExit) { return harness; }
 
-	process.on('exit', function (code) {
+	process.on('exit', /** @param {number | undefined} code */ function (code) {
 		// let the process exit cleanly.
 		if (typeof code === 'number' && code !== 0) {
 			return;
@@ -179,7 +201,24 @@ function createExitHarness(config, wait) {
 	return harness;
 }
 
+module.exports = tape;
+
 module.exports.createHarness = createHarness;
 module.exports.Test = Test;
-module.exports.test = module.exports; // tap compat
-module.exports.test.skip = Test.skip;
+module.exports.test = tape; // tap compat
+module.exports.skip = Test.skip;
+
+// @ts-expect-error TODO FIXME: attw errors without this line
+module.exports.createStream = tape.createStream;
+// @ts-expect-error TODO FIXME: attw errors without this line
+module.exports.only = tape.only;
+// @ts-expect-error TODO FIXME: attw errors without this line
+module.exports.getHarness = tape.getHarness;
+// @ts-expect-error TODO FIXME: attw errors without this line
+module.exports.run = tape.run;
+// @ts-expect-error TODO FIXME: attw errors without this line
+module.exports.wait = tape.wait;
+// @ts-expect-error TODO FIXME: attw errors without this line
+module.exports.onFinish = tape.onFinish;
+// @ts-expect-error TODO FIXME: attw errors without this line
+module.exports.onFailure = tape.onFailure;

lib/default_stream.d.ts

@@ -0,0 +1,5 @@
+import type { ThroughStream } from "@ljharb/through";
+
+declare function defaultStream(): ThroughStream;
+
+export = defaultStream;