Skip to content

Commit 4e56161

Browse files
ljharbljharb
committed
[New] add types
1 parent d8d42b6 commit 4e56161

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+980
-160
lines changed

‎.eslintrc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@
2323
"no-underscore-dangle": "warn",
2424
"object-curly-newline": "off",
2525
"sort-keys": "off",
26+
27+
"no-extra-parens": "off",
2628
},
2729
"ignorePatterns": ["syntax-error.*"],
2830
"overrides": [

‎.github/workflows/node-aught.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ jobs:
99
range: '< 10'
1010
type: minors
1111
command: npm run tests-only
12+
skip-ls-check: true

‎bin/import-or-require.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ const { extname: extnamePath } = require('path');
44
const { pathToFileURL } = require('url');
55
const getPackageType = require('get-package-type');
66

7+
/** @type {(file: string) => undefined | Promise<unknown>} */
78
// eslint-disable-next-line consistent-return
89
module.exports = function importOrRequire(file) {
910
const ext = extnamePath(file);

‎bin/tape

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,9 +100,11 @@ var hasImport = require('has-dynamic-import');
100100

101101
var tape = require('../');
102102

103+
/** @type {(hasSupport: boolean) => Promise<void> | void} */
103104
function importFiles(hasSupport) {
104105
tape.wait();
105106

107+
/** @type {null | undefined | Promise<unknown>} */
106108
var filesPromise;
107109
if (hasSupport) {
108110
var importOrRequire = require('./import-or-require');

‎example/array.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,11 @@ test('array', function (t) {
2626
];
2727

2828
Function('fn', 'g', String(output))(
29-
function (xs) {
29+
/** @param {number[]} xs */ function (xs) {
3030
t.same(arrays.shift(), xs);
3131
return xs;
3232
},
33-
function (xs) {
33+
/** @param {number[]} xs */ function (xs) {
3434
t.same(xs, [[1, 2, [3, 4]], [5, 6]]);
3535
}
3636
);

‎example/fail.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,11 @@ test('array', function (t) {
2626
];
2727

2828
Function('fn', 'g', String(output))(
29-
function (xs) {
29+
/** @param {number[]} xs */ function (xs) {
3030
t.same(arrays.shift(), xs);
3131
return xs;
3232
},
33-
function (xs) {
33+
/** @param {number[]} xs */ function (xs) {
3434
t.same(xs, [[1, 2, [3, 4444]], [5, 6]]);
3535
}
3636
);

‎example/nested.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,11 @@ test('nested array test', function (t) {
3535
];
3636

3737
Function('fn', 'g', String(output))(
38-
function (xs) {
38+
/** @param {number[]} xs */ function (xs) {
3939
t.same(arrays.shift(), xs);
4040
return xs;
4141
},
42-
function (xs) {
42+
/** @param {number[]} xs */ function (xs) {
4343
t.same(xs, [[1, 2, [3, 4]], [5, 6]]);
4444
}
4545
);

‎example/nested_fail.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,11 @@ test('nested array test', function (t) {
3535
];
3636

3737
Function('fn', 'g', String(output))(
38-
function (xs) {
38+
/** @param {number[]} xs */ function (xs) {
3939
t.same(arrays.shift(), xs);
4040
return xs;
4141
},
42-
function (xs) {
42+
/** @param {number[]} xs */ function (xs) {
4343
t.same(xs, [[1, 2, [3, 4]], [5, 6]]);
4444
}
4545
);

‎example/not_enough_fail.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,11 @@ test('array', function (t) {
2626
];
2727

2828
Function('fn', 'g', String(output))(
29-
function (xs) {
29+
/** @param {number[]} xs */ function (xs) {
3030
t.same(arrays.shift(), xs);
3131
return xs;
3232
},
33-
function (xs) {
33+
/** @param {number[]} xs */ function (xs) {
3434
t.same(xs, [[1, 2, [3, 4]], [5, 6]]);
3535
}
3636
);

‎example/too_many_fail.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,11 @@ test('array', function (t) {
2626
];
2727

2828
Function('fn', 'g', String(output))(
29-
function (xs) {
29+
/** @param {number[]} xs */ function (xs) {
3030
t.same(arrays.shift(), xs);
3131
return xs;
3232
},
33-
function (xs) {
33+
/** @param {number[]} xs */ function (xs) {
3434
t.same(xs, [[1, 2, [3, 4]], [5, 6]]);
3535
}
3636
);

‎index.d.ts

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
import type { ThroughStream } from '@ljharb/through';
2+
3+
import type Test from './lib/test';
4+
import type Results from './lib/results';
5+
6+
declare function harnessFunction(this: Test, name: string, opts: tape.TestOptions, cb: Test.TestCase): Test;
7+
declare function harnessFunction(this: Test, name: string, opts: tape.TestOptions): Test;
8+
declare function harnessFunction(this: Test, name: string, cb: Test.TestCase): Test;
9+
declare function harnessFunction(this: Test, name: string): Test;
10+
declare function harnessFunction(this: Test, opts: tape.TestOptions, cb: Test.TestCase): Test;
11+
declare function harnessFunction(this: Test, opts: tape.TestOptions): Test;
12+
declare function harnessFunction(this: Test, cb: Test.TestCase): Test;
13+
14+
declare function harnessFunction(this: void, name: string, opts: tape.TestOptions, cb: Test.TestCase): Test;
15+
declare function harnessFunction(this: void, name: string, opts: tape.TestOptions): Test;
16+
declare function harnessFunction(this: void, name: string, cb: Test.TestCase): Test;
17+
declare function harnessFunction(this: void, name: string): Test;
18+
declare function harnessFunction(this: void, opts: tape.TestOptions, cb: Test.TestCase): Test;
19+
declare function harnessFunction(this: void, opts: tape.TestOptions): Test;
20+
declare function harnessFunction(this: void, cb: Test.TestCase): Test;
21+
22+
declare namespace tape {
23+
export type TestOptions = {
24+
objectPrintDepth?: number | undefined;
25+
skip?: boolean | string | undefined;
26+
timeout?: number | undefined;
27+
todo?: boolean | string | undefined;
28+
};
29+
30+
export interface AssertOptions {
31+
skip?: boolean | string | undefined;
32+
todo?: boolean | string | undefined;
33+
message?: string | undefined;
34+
actual?: unknown;
35+
expected?: unknown;
36+
exiting?: boolean;
37+
}
38+
39+
export interface StreamOptions {
40+
objectMode?: boolean | undefined;
41+
}
42+
43+
function createStream(opts?: StreamOptions): ThroughStream;
44+
45+
export type CreateStream = typeof createStream;
46+
47+
export type HarnessEventHandler = (cb: Test.SyncCallback, ...rest: unknown[]) => void;
48+
49+
function only(name: string, cb: Test.TestCase): void;
50+
function only(name: string, opts: tape.TestOptions, cb: Test.TestCase): void;
51+
function only(cb: Test.TestCase): void;
52+
function only(opts: tape.TestOptions, cb?: Test.TestCase): void;
53+
54+
export type Harness = typeof harnessFunction & {
55+
run?: () => void;
56+
only: typeof only;
57+
_exitCode: number;
58+
_results: Results;
59+
_tests: Test[];
60+
close: () => void;
61+
createStream: CreateStream;
62+
onFailure: HarnessEventHandler;
63+
onFinish: HarnessEventHandler;
64+
}
65+
66+
export type HarnessConfig = {
67+
autoclose?: boolean;
68+
noOnly?: boolean;
69+
stream?: NodeJS.WritableStream | ThroughStream;
70+
exit?: boolean;
71+
} & StreamOptions;
72+
73+
function createHarness(conf_?: HarnessConfig): Harness;
74+
const Test: Test;
75+
const test: typeof tape;
76+
const skip: Test['skip'];
77+
78+
function getHarness(opts?: HarnessConfig): Harness;
79+
function run(): void;
80+
function onFailure(cb: Test.SyncCallback, ...rest: unknown[]): void;
81+
function onFinish(cb: Test.SyncCallback, ...rest: unknown[]): void
82+
function wait(): void;
83+
}
84+
85+
declare function tape(this: tape.Harness, name: string, opts: tape.TestOptions, cb: Test.TestCase): Test;
86+
declare function tape(this: tape.Harness, name: string, cb: Test.TestCase): Test;
87+
declare function tape(this: tape.Harness, opts?: tape.TestOptions): Test;
88+
declare function tape(this: tape.Harness, opts: tape.TestOptions, cb: Test.TestCase): Test;
89+
declare function tape(this: tape.Harness, cb: Test.TestCase): Test;
90+
91+
declare function tape(this: void, name: string, opts: tape.TestOptions, cb: Test.TestCase): Test;
92+
declare function tape(this: void, name: string, cb: Test.TestCase): Test;
93+
declare function tape(this: void, opts?: tape.TestOptions): Test;
94+
declare function tape(this: void, opts: tape.TestOptions, cb: Test.TestCase): Test;
95+
declare function tape(this: void, cb: Test.TestCase): Test;
96+
97+
export = tape;

‎index.js

Lines changed: 50 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,33 @@
11
'use strict';
22

33
var defined = require('defined');
4+
var through = require('@ljharb/through');
5+
46
var createDefaultStream = require('./lib/default_stream');
57
var Test = require('./lib/test');
68
var Results = require('./lib/results');
7-
var through = require('@ljharb/through');
89

910
var canEmitExit = typeof process !== 'undefined' && process
10-
&& typeof process.on === 'function' && process.browser !== true;
11+
&& typeof process.on === 'function' && /** @type {{ browser?: boolean }} */ (process).browser !== true;
1112
var canExit = typeof process !== 'undefined' && process
1213
&& typeof process.exit === 'function';
1314

14-
module.exports = (function () {
15+
/** @typedef {import('.')} Tape */
16+
/** @typedef {import('.').Harness} Harness */
17+
/** @typedef {import('.').HarnessConfig} HarnessConfig */
18+
/** @typedef {import('.').TestOptions} TestOptions */
19+
/** @typedef {import('.').HarnessEventHandler} HarnessEventHandler */
20+
/** @typedef {import('.').CreateStream} CreateStream */
21+
/** @typedef {import('.').createHarness} CreateHarness */
22+
/** @typedef {import('./lib/results').Result} Result */
23+
/** @typedef {import('stream').Writable} WritableStream */
24+
25+
var tape = (function () {
1526
var wait = false;
27+
/** @type {undefined | Harness} */
1628
var harness;
1729

30+
/** @type {(opts?: HarnessConfig) => Harness} */
1831
function getHarness(opts) {
1932
// this override is here since tests fail via nyc if createHarness is moved upwards
2033
if (!harness) {
@@ -24,6 +37,7 @@ module.exports = (function () {
2437
return harness;
2538
}
2639

40+
/** @type {(this: Harness, ...args: Parameters<Tape>) => ReturnType<Tape>} */
2741
function lazyLoad() {
2842
// eslint-disable-next-line no-invalid-this
2943
return getHarness().apply(this, arguments);
@@ -43,6 +57,7 @@ module.exports = (function () {
4357
return getHarness().only.apply(this, arguments);
4458
};
4559

60+
/** @type {CreateStream} */
4661
lazyLoad.createStream = function (opts) {
4762
var options = opts || {};
4863
if (!harness) {
@@ -66,21 +81,23 @@ module.exports = (function () {
6681
return lazyLoad;
6782
}());
6883

84+
/** @type {CreateHarness} */
6985
function createHarness(conf_) {
7086
var results = new Results({ todoIsOK: !!(process.env.TODO_IS_OK === '1') });
7187
if (!conf_ || conf_.autoclose !== false) {
7288
results.once('done', function () { results.close(); });
7389
}
7490

91+
/** @type {(name: string, conf: TestOptions, cb: Test.TestCase) => Test} */
7592
function test(name, conf, cb) {
7693
var t = new Test(name, conf, cb);
7794
test._tests.push(t);
7895

7996
(function inspectCode(st) {
80-
st.on('test', function sub(st_) {
97+
st.on('test', /** @type {(st: Test) => void} */ function sub(st_) {
8198
inspectCode(st_);
8299
});
83-
st.on('result', function (r) {
100+
st.on('result', /** @type {(r: Result) => void} */ function (r) {
84101
if (!r.todo && !r.ok && typeof r !== 'string') { test._exitCode = 1; }
85102
});
86103
}(t));
@@ -90,21 +107,25 @@ function createHarness(conf_) {
90107
}
91108
test._results = results;
92109

93-
test._tests = [];
110+
/** @type {Test[]} */ test._tests = [];
94111

112+
/** @type {CreateStream} */
95113
test.createStream = function (opts) {
96114
return results.createStream(opts);
97115
};
98116

117+
/** @type {HarnessEventHandler} */
99118
test.onFinish = function (cb) {
100119
results.on('done', cb);
101120
};
102121

122+
/** @type {HarnessEventHandler} */
103123
test.onFailure = function (cb) {
104124
results.on('fail', cb);
105125
};
106126

107127
var only = false;
128+
/** @type {() => Test} */
108129
test.only = function () {
109130
if (only) { throw new Error('there can only be one only test'); }
110131
if (conf_ && conf_.noOnly) { throw new Error('`only` tests are prohibited'); }
@@ -117,9 +138,11 @@ function createHarness(conf_) {
117138

118139
test.close = function () { results.close(); };
119140

141+
// @ts-expect-error TODO FIXME: why is `test` not assignable to `Harness`???
120142
return test;
121143
}
122144

145+
/** @type {(conf: Omit<HarnessConfig, 'autoclose'>, wait?: boolean) => Harness} */
123146
function createExitHarness(config, wait) {
124147
var noOnly = config.noOnly;
125148
var objectMode = config.objectMode;
@@ -139,9 +162,8 @@ function createExitHarness(config, wait) {
139162
var stream = harness.createStream({ objectMode: objectMode });
140163
var es = stream.pipe(cStream || createDefaultStream());
141164
if (canEmitExit && es) { // in node v0.4, `es` is `undefined`
142-
// TODO: use `err` arg?
143165
// eslint-disable-next-line no-unused-vars
144-
es.on('error', function (err) { harness._exitCode = 1; });
166+
es.on('error', function (_) { harness._exitCode = 1; });
145167
}
146168
stream.on('end', function () { ended = true; });
147169
}
@@ -155,7 +177,7 @@ function createExitHarness(config, wait) {
155177
if (exit === false) { return harness; }
156178
if (!canEmitExit || !canExit) { return harness; }
157179

158-
process.on('exit', function (code) {
180+
process.on('exit', /** @param {number | undefined} code */ function (code) {
159181
// let the process exit cleanly.
160182
if (typeof code === 'number' && code !== 0) {
161183
return;
@@ -179,7 +201,24 @@ function createExitHarness(config, wait) {
179201
return harness;
180202
}
181203

204+
module.exports = tape;
205+
182206
module.exports.createHarness = createHarness;
183207
module.exports.Test = Test;
184-
module.exports.test = module.exports; // tap compat
185-
module.exports.test.skip = Test.skip;
208+
module.exports.test = tape; // tap compat
209+
module.exports.skip = Test.skip;
210+
211+
// @ts-expect-error TODO FIXME: attw errors without this line
212+
module.exports.createStream = tape.createStream;
213+
// @ts-expect-error TODO FIXME: attw errors without this line
214+
module.exports.only = tape.only;
215+
// @ts-expect-error TODO FIXME: attw errors without this line
216+
module.exports.getHarness = tape.getHarness;
217+
// @ts-expect-error TODO FIXME: attw errors without this line
218+
module.exports.run = tape.run;
219+
// @ts-expect-error TODO FIXME: attw errors without this line
220+
module.exports.wait = tape.wait;
221+
// @ts-expect-error TODO FIXME: attw errors without this line
222+
module.exports.onFinish = tape.onFinish;
223+
// @ts-expect-error TODO FIXME: attw errors without this line
224+
module.exports.onFailure = tape.onFailure;

‎lib/default_stream.d.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
import type { ThroughStream } from "@ljharb/through";
2+
3+
declare function defaultStream(): ThroughStream;
4+
5+
export = defaultStream;

0 commit comments

Comments
 (0)