chore: move callback and object typedefs to a new types.d.ts #5351

JoshuaKGoldberg · 2025-05-01T19:59:24Z

PR Checklist

Addresses an existing open issue: fixes 🛠 Repo: Split type declarations into standalone .d.ts files #5347
That issue was marked as status: accepting prs
Steps in CONTRIBUTING.md were taken

Overview

Creates a new lib/types.d.ts and moves every @callback and @typedef {Object} to it. A new tsconfig.json & tsc script can be run to verify that the types in that file can be type checked.

Does not yet validate types in .js files (#4154, #4228). You can preview those by switching tsconfig.json's allowJs to checkJs. I made sure there are no more "Cannot find name ..." errors but fixing the rest of the ~650+ will be a lot more work. Much of the code will be much easier to get type-safe when it's ported from manual function prototypes to classes (#5025). I also held off porting all the info from @types/mocha there to keep the changes minimal.

Does not yet try to pull in types or descriptions from @types/mocha. That would be a bigger change too.

Moves error constants from errors.js to error-constants.js to avoid circular dependency errors.

voxpelli · 2025-05-05T20:47:02Z

Why everything in one large .d.ts?

Also: You can try to use (still sometimes buggy) the @import to import instead of using typedef, eg:

/** @import { Foo } from './bar.js' */

JoshuaKGoldberg · 2025-05-06T00:42:43Z

Why everything in one large .d.ts?

I don't have preferences on where to organize types, since this feels like a transient "we'll clean things up over time anyway" kind of situation to me 😄. Do you have a preference for where things should go?

JoshuaKGoldberg · 2025-05-19T13:48:11Z

ping @voxpelli did you mean for #5351 (comment) to be a full review? I'm not clear on whether you're requesting changes and waiting on me, or just posting thoughts pending a full review?

voxpelli · 2025-05-19T13:49:39Z

@JoshuaKGoldberg Posting thoughts pending a full review, thanks for pinging and asking 🙏

mark-wiemer

Pretty good, requested a few changes :)

mark-wiemer · 2025-06-11T22:13:49Z

lib/types.d.ts

+  /** Disable syntax highlighting? */
+  noHighlighting?: boolean;
+
+  /** - Reporter name or constructor. */


Suggested change

/** - Reporter name or constructor. */

/** Reporter name or constructor. */

mark-wiemer · 2025-06-11T22:14:12Z

lib/types.d.ts

+  /** Number of times to retry failed tests. */
+  retries?: number;
+
+  /** Slow threshold value. */


Suggested change

/** Slow threshold value. */

/** Slow threshold value, in milliseconds. */

mark-wiemer · 2025-06-11T22:14:38Z

lib/types.d.ts

+  /** Slow threshold value. */
+  slow?: number;
+
+  /** Timeout threshold value. */


Suggested change

/** Timeout threshold value. */

/** Timeout threshold value, in milliseconds. */

mark-wiemer · 2025-06-11T22:15:43Z

lib/types.d.ts

+ * @private
+ * @param failures - Number of failures that occurred.
+ */
+export type DoneCB = (failures: number) => void;


I know in JS all params are implicitly optional, but I think we should be explicit for clarity

Suggested change

export type DoneCB = (failures: number) => void;

export type DoneCB = (failures?: number) => void;

mark-wiemer · 2025-06-11T22:17:36Z

lib/types.d.ts

+ * Diagnostic object containing unmatched files
+ */
+export interface UnmatchedFile {
+  /** A list of unmatched files derived from the file arguments passed in */


List? How are entries separated? Or should this be an array? Same for next entry

I think the comments for this UnmatchedFile type were copy-pasted wrong :)

mark-wiemer · 2025-06-11T22:21:13Z

package.json

@@ -163,6 +168,7 @@
    "rollup-plugin-polyfill-node": "^0.8.0",
    "rollup-plugin-visualizer": "^5.6.0",
    "sinon": "^9.0.3",
+    "typescript": "^5.8.3",


TS famously doesn't follow semantic versioning, but I believe they only introducing breaking changes in minor versions, never in patches

Suggested change

"typescript": "^5.8.3",

"typescript": "~5.8.3",

mark-wiemer · 2025-06-11T22:22:19Z

test/unit/errors.spec.js

@@ -1,6 +1,7 @@
 'use strict';

 var errors = require('../../lib/errors');
+var constants = require('../../lib/error-constants');


If we are adding a reference to error-constants, can we remove the references to errors?

Copilot

Pull Request Overview

This PR centralizes JSDoc type definitions into a new lib/types.d.ts, moves error constants to lib/error-constants.js, and updates module files to import those typedefs. It also adds a tsconfig.json and GitHub Actions job to run tsc for type checking.

Consolidated all @callback/@typedef declarations into types.d.ts
Extracted error constants into lib/error-constants.js and updated imports
Added a tsc script and workflow step for validating the new types

Reviewed Changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
lib/reporters/base.js	Removed inline `FullErrorStack` typedef and added import from `types.d.ts`
lib/plugin-loader.js	Removed inline `PluginDefinition` and `PluginLoaderOptions` typedefs, added imports
lib/nodejs/worker.js	Removed inline `BufferedEvent`/`MochaOptions` typedefs, added imports and updated `@param`
lib/nodejs/serializer.js	Removed inline `SerializedEvent`/`SerializedWorkerResult` typedefs, added imports
lib/nodejs/reporters/parallel-buffered.js	Removed inline `BufferedEvent` typedef and added import
lib/nodejs/parallel-buffered-runner.js	Removed inline `SigIntListener`/`FileRunner` typedefs, added imports
lib/nodejs/buffered-worker-pool.js	Removed inline typedefs, added imports for `WorkerPoolOptions`, `MochaOptions`, results
lib/mocha.js	Removed many inline typedefs, added imports for `DoneCB`, fixtures, options, reporter types
lib/interfaces/tdd.js	Added `Suite` typedef import
lib/interfaces/qunit.js	Added `Suite` typedef import
lib/interfaces/common.js	Added `Context` and `Mocha` typedef imports
lib/interfaces/bdd.js	Added `Suite` typedef import
lib/errors.js	Removed inline constants, imported from `error-constants.js`, no longer exports `constants`
lib/error-constants.js	New file exporting all Mocha error constants
lib/context.js	Added `Runnable` typedef import
lib/cli/watch-run.js	Added typedef imports for `FSWatcher`, `Mocha`, `BeforeWatchRun`, `FileCollectionOptions`, etc.
lib/cli/run-option-metadata.js	Updated JSDoc `{{string:string[]}}` to `Record<string,string[]>`
lib/cli/run-helpers.js	Added imports for `Mocha`, `MochaOptions`, `UnmatchedFile`, `Runner`
lib/cli/collect-files.js	Switched error import to `error-constants`, added `FileCollectionOptions`/`Response` imports
.github/workflows/mocha.yml	Added `tsc` job to run the TypeScript compiler for validation

Comments suppressed due to low confidence (2)

lib/errors.js:418

The constants object was removed from this module’s exports but is still documented under module:lib/errors. If backward compatibility is required, re-export constants here or update documentation to reflect the new location.

module.exports = {

lib/error-constants.js:4

The @memberof module:lib/errors tag is misleading in this standalone file. Consider changing it to module:lib/error-constants or removing the @memberof directive.

* @memberof module:lib/errors

JoshuaKGoldberg added 4 commits May 1, 2025 15:56

chore: move callback and object typedefs to a new types.d.ts

992f02e

fix: correct constants import path for options.spec.js

88bba73

Correct another require

856c674

Fix another require

e33f7f0

JoshuaKGoldberg marked this pull request as ready for review May 2, 2025 13:26

JoshuaKGoldberg requested a review from a team May 2, 2025 13:39

mark-wiemer self-requested a review May 11, 2025 19:22

mark-wiemer requested changes Jun 11, 2025

View reviewed changes

voxpelli requested a review from Copilot June 12, 2025 07:45

Copilot AI reviewed Jun 12, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

chore: move callback and object typedefs to a new types.d.ts #5351

chore: move callback and object typedefs to a new types.d.ts #5351

Uh oh!

JoshuaKGoldberg commented May 1, 2025 •

edited

Loading

Uh oh!

voxpelli commented May 5, 2025

Uh oh!

JoshuaKGoldberg commented May 6, 2025 •

edited

Loading

Uh oh!

JoshuaKGoldberg commented May 19, 2025

Uh oh!

voxpelli commented May 19, 2025

Uh oh!

mark-wiemer left a comment

Uh oh!

mark-wiemer Jun 11, 2025

Uh oh!

mark-wiemer Jun 11, 2025

Uh oh!

mark-wiemer Jun 11, 2025

Uh oh!

mark-wiemer Jun 11, 2025

Uh oh!

mark-wiemer Jun 11, 2025

Uh oh!

mark-wiemer Jun 11, 2025

Uh oh!

mark-wiemer Jun 11, 2025

Uh oh!

mark-wiemer Jun 11, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

	/** - Reporter name or constructor. */
	/** Reporter name or constructor. */

	/** Slow threshold value. */
	/** Slow threshold value, in milliseconds. */

	/** Timeout threshold value. */
	/** Timeout threshold value, in milliseconds. */

	export type DoneCB = (failures: number) => void;
	export type DoneCB = (failures?: number) => void;

Uh oh!

chore: move callback and object typedefs to a new types.d.ts #5351

Are you sure you want to change the base?

chore: move callback and object typedefs to a new types.d.ts #5351

Uh oh!

Conversation

JoshuaKGoldberg commented May 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Checklist

Overview

Uh oh!

voxpelli commented May 5, 2025

Uh oh!

JoshuaKGoldberg commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JoshuaKGoldberg commented May 19, 2025

Uh oh!

voxpelli commented May 19, 2025

Uh oh!

mark-wiemer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

JoshuaKGoldberg commented May 1, 2025 •

edited

Loading

JoshuaKGoldberg commented May 6, 2025 •

edited

Loading