Skip to content

Commit 92aa51c

Browse files
ljharbljharb
committed
add types
1 parent ecfb546 commit 92aa51c

14 files changed

+603
-48
lines changed

‎.github/workflows/node-aught.yml

+1
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

+1
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

+2
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ var hasImport = require('has-dynamic-import');
9595

9696
var tape = require('../');
9797

98+
/** @type {(hasSupport: boolean) => Promise<void> | void} */
9899
function importFiles(hasSupport) {
99100
if (!hasSupport) {
100101
return files.forEach(function (x) { require(x); });
@@ -104,6 +105,7 @@ function importFiles(hasSupport) {
104105

105106
tape.wait();
106107

108+
/** @type {null | undefined | Promise<unknown>} */
107109
var filesPromise = files.reduce(function (promise, file) {
108110
return promise ? promise.then(function () {
109111
return importOrRequire(file);

‎index.d.ts

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
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: ThisType<Test>, name: string, opts: tape.TestOptions, cb: Test.Callback): Test;
7+
declare function harnessFunction(this: ThisType<Test>, name: string, opts: tape.TestOptions): Test;
8+
declare function harnessFunction(this: ThisType<Test>, name: string, cb: Test.Callback): Test;
9+
declare function harnessFunction(this: ThisType<Test>, name: string): Test;
10+
declare function harnessFunction(this: ThisType<Test>, opts: tape.TestOptions, cb: Test.Callback): Test;
11+
declare function harnessFunction(this: ThisType<Test>, opts: tape.TestOptions): Test;
12+
declare function harnessFunction(this: ThisType<Test>, cb: Test.Callback): Test;
13+
14+
declare namespace tape {
15+
export type TestOptions = {
16+
objectPrintDepth?: number | undefined;
17+
skip?: boolean | undefined;
18+
timeout?: number | undefined;
19+
todo?: boolean | undefined;
20+
};
21+
22+
export interface AssertOptions {
23+
skip?: boolean | string | undefined;
24+
todo?: boolean | string | undefined;
25+
message?: string | undefined;
26+
actual?: unknown;
27+
expected?: unknown;
28+
exiting?: boolean;
29+
}
30+
31+
export interface StreamOptions {
32+
objectMode?: boolean | undefined;
33+
}
34+
35+
function createStream(opts?: StreamOptions): ThroughStream;
36+
37+
export type CreateStream = typeof createStream;
38+
39+
export type HarnessEventHandler = (cb: Test.SyncCallback, ...rest: unknown[]) => void;
40+
41+
function only(name: string, cb: Test.Callback): void;
42+
function only(name: string, opts: tape.TestOptions, cb: Test.Callback): void;
43+
function only(cb: Test.Callback): void;
44+
function only(opts: tape.TestOptions, cb: Test.Callback): void;
45+
46+
export type HarnessCallSignatures = typeof harnessFunction;
47+
48+
export interface Harness extends HarnessCallSignatures {
49+
run?: () => void;
50+
only: typeof only;
51+
_exitCode: number;
52+
_results: Results;
53+
_tests: Test[];
54+
close: () => void;
55+
createStream: CreateStream;
56+
onFailure: HarnessEventHandler;
57+
onFinish: HarnessEventHandler;
58+
}
59+
60+
export type HarnessConfig = {
61+
autoclose?: boolean;
62+
noOnly?: boolean;
63+
stream?: NodeJS.WritableStream | ThroughStream;
64+
exit?: boolean;
65+
} & StreamOptions;
66+
67+
function createHarness(conf_?: HarnessConfig): Harness;
68+
const Test: Test;
69+
const test: typeof tape;
70+
const skip: Test['skip'];
71+
}
72+
73+
declare function tape(this: tape.Harness, name: string, opts: tape.TestOptions, cb: Test.Callback): Test;
74+
declare function tape(this: tape.Harness, name: string, cb: Test.Callback): Test;
75+
declare function tape(this: tape.Harness, opts?: tape.TestOptions): Test;
76+
declare function tape(this: tape.Harness, opts: tape.TestOptions, cb: Test.Callback): Test;
77+
78+
export = tape;

‎index.js

+37-10
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,35 @@
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+
// eslint-disable-next-line no-extra-parens
12+
&& typeof process.on === 'function' && /** @type {{ browser?: boolean }} */ (process).browser !== true;
1113
var canExit = typeof process !== 'undefined' && process
1214
&& typeof process.exit === 'function';
1315

16+
/** @typedef {import('.')} Tape */
17+
/** @typedef {import('.').Harness} Harness */
18+
/** @typedef {import('.').HarnessConfig} HarnessConfig */
19+
/** @typedef {import('.').HarnessCallSignatures} HarnessCallSignatures */
20+
/** @typedef {import('.').TestOptions} TestOptions */
21+
/** @typedef {import('.').HarnessEventHandler} HarnessEventHandler */
22+
/** @typedef {import('.').CreateStream} CreateStream */
23+
/** @typedef {import('.').createHarness} CreateHarness */
24+
/** @typedef {import('./lib/results').Result} Result */
25+
/** @typedef {import('stream').Writable} WritableStream */
26+
1427
module.exports = (function () {
1528
var wait = false;
29+
/** @type {undefined | Harness} */
1630
var harness;
1731

32+
/** @type {(opts?: HarnessConfig) => Harness} */
1833
function getHarness(opts) {
1934
// this override is here since tests fail via nyc if createHarness is moved upwards
2035
if (!harness) {
@@ -24,6 +39,7 @@ module.exports = (function () {
2439
return harness;
2540
}
2641

42+
/** @type {(this: Harness, ...args: Parameters<Tape>) => ReturnType<Tape>} */
2743
function lazyLoad() {
2844
// eslint-disable-next-line no-invalid-this
2945
return getHarness().apply(this, arguments);
@@ -43,6 +59,7 @@ module.exports = (function () {
4359
return getHarness().only.apply(this, arguments);
4460
};
4561

62+
/** @type {CreateStream} */
4663
lazyLoad.createStream = function (opts) {
4764
var options = opts || {};
4865
if (!harness) {
@@ -66,21 +83,23 @@ module.exports = (function () {
6683
return lazyLoad;
6784
}());
6885

86+
/** @type {CreateHarness} */
6987
function createHarness(conf_) {
7088
var results = new Results({ todoIsOK: !!(process.env.TODO_IS_OK === '1') });
7189
if (!conf_ || conf_.autoclose !== false) {
7290
results.once('done', function () { results.close(); });
7391
}
7492

93+
/** @type {(name: string, conf: TestOptions, cb: Test.Callback) => Test} */
7594
function test(name, conf, cb) {
7695
var t = new Test(name, conf, cb);
7796
test._tests.push(t);
7897

7998
(function inspectCode(st) {
80-
st.on('test', function sub(st_) {
99+
st.on('test', /** @type {(st: Test) => void} */ function sub(st_) {
81100
inspectCode(st_);
82101
});
83-
st.on('result', function (r) {
102+
st.on('result', /** @type {(r: Result) => void} */ function (r) {
84103
if (!r.todo && !r.ok && typeof r !== 'string') { test._exitCode = 1; }
85104
});
86105
}(t));
@@ -90,21 +109,25 @@ function createHarness(conf_) {
90109
}
91110
test._results = results;
92111

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

114+
/** @type {CreateStream} */
95115
test.createStream = function (opts) {
96116
return results.createStream(opts);
97117
};
98118

119+
/** @type {HarnessEventHandler} */
99120
test.onFinish = function (cb) {
100121
results.on('done', cb);
101122
};
102123

124+
/** @type {HarnessEventHandler} */
103125
test.onFailure = function (cb) {
104126
results.on('fail', cb);
105127
};
106128

107129
var only = false;
130+
/** @type {() => Test} */
108131
test.only = function () {
109132
if (only) { throw new Error('there can only be one only test'); }
110133
if (conf_ && conf_.noOnly) { throw new Error('`only` tests are prohibited'); }
@@ -117,9 +140,11 @@ function createHarness(conf_) {
117140

118141
test.close = function () { results.close(); };
119142

143+
// @ts-expect-error TODO FIXME: why is `test` not assignable to `Harness`???
120144
return test;
121145
}
122146

147+
/** @type {(conf: Omit<HarnessConfig, 'autoclose'>, wait?: boolean) => Harness} */
123148
function createExitHarness(config, wait) {
124149
var noOnly = config.noOnly;
125150
var objectMode = config.objectMode;
@@ -137,11 +162,12 @@ function createExitHarness(config, wait) {
137162
if (running) { return; }
138163
running = true;
139164
var stream = harness.createStream({ objectMode: objectMode });
140-
var es = stream.pipe(cStream || createDefaultStream());
165+
// eslint-disable-next-line no-extra-parens
166+
var es = stream.pipe(/** @type {WritableStream} */ (cStream || createDefaultStream()));
141167
if (canEmitExit && es) { // in node v0.4, `es` is `undefined`
142168
// TODO: use `err` arg?
143169
// eslint-disable-next-line no-unused-vars
144-
es.on('error', function (err) { harness._exitCode = 1; });
170+
es.on('error', function (_) { harness._exitCode = 1; });
145171
}
146172
stream.on('end', function () { ended = true; });
147173
}
@@ -180,6 +206,7 @@ function createExitHarness(config, wait) {
180206
}
181207

182208
module.exports.createHarness = createHarness;
183-
module.exports.Test = Test;
184-
module.exports.test = module.exports; // tap compat
185-
module.exports.test.skip = Test.skip;
209+
var moduleExports = module.exports; // this hack is needed because TS has a bug with seemingly circular exports
210+
moduleExports.Test = Test;
211+
moduleExports.test = module.exports; // tap compat
212+
moduleExports.skip = Test.skip;

‎lib/default_stream.d.ts

+5
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;

‎lib/default_stream.js

+7-4
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,13 @@
33
var through = require('@ljharb/through');
44
var fs = require('fs');
55

6+
/** @type {import('./default_stream')} */
67
module.exports = function () {
78
var line = '';
89
var stream = through(write, flush);
910
return stream;
1011

12+
/** @type {(buf: unknown) => void} */
1113
function write(buf) {
1214
if (
1315
buf == null // eslint-disable-line eqeqeq
@@ -16,10 +18,11 @@ module.exports = function () {
1618
flush();
1719
return;
1820
}
19-
for (var i = 0; i < buf.length; i++) {
20-
var c = typeof buf === 'string'
21-
? buf.charAt(i)
22-
: String.fromCharCode(buf[i]);
21+
var b = /** @type {string | ArrayLike<number>} */ (buf); // eslint-disable-line no-extra-parens
22+
for (var i = 0; i < b.length; i++) {
23+
var c = typeof b === 'string'
24+
? b.charAt(i)
25+
: String.fromCharCode(b[i]);
2326
if (c === '\n') {
2427
flush();
2528
} else {

‎lib/results.d.ts

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
import through from '@ljharb/through';
2+
import type { EventEmitter } from 'events';
3+
4+
import type { StreamOptions } from '../';
5+
import Test = require('./test');
6+
7+
declare class Results extends EventEmitter {
8+
constructor(options?: { todoIsOK?: boolean });
9+
10+
count: number;
11+
fail: number;
12+
pass: number;
13+
tests: Test[];
14+
todo: number;
15+
todoIsOK: boolean;
16+
closed?: boolean;
17+
18+
_isRunning: boolean;
19+
_only: Test | null;
20+
_stream: through.ThroughStream;
21+
22+
close(this: Results): void;
23+
createStream(this: Results, opts?: StreamOptions): through.ThroughStream;
24+
only(this: Results, t: Test): void;
25+
push(this: Results, t: Test): void;
26+
27+
_watch(this: Results, t: Test): void;
28+
}
29+
30+
declare namespace Results {
31+
export type Operator = string;
32+
33+
export type Result = {
34+
id: number;
35+
ok: boolean;
36+
skip: unknown;
37+
todo: unknown;
38+
name?: string;
39+
operator: undefined | Operator;
40+
objectPrintDepth?: number;
41+
actual?: unknown;
42+
expected?: unknown;
43+
error?: unknown;
44+
functionName?: string;
45+
file?: string;
46+
line?: number;
47+
column?: number;
48+
at?: string;
49+
};
50+
}
51+
52+
export = Results;

0 commit comments

Comments
 (0)