Automate creating index.d.ts

Author: keeganwitt

.gitignore

@@ -9,3 +9,4 @@ coverage
 .vscode
 package-lock.json
 *tsbuildinfo
+/types/index.d.ts

package.json

@@ -3,24 +3,27 @@
   "version": "5.0.3",
   "description": "Additional Jest matchers",
   "main": "dist/index.js",
-  "types": "types/index.d.ts",
   "files": [
     "dist",
     "types/index.d.ts",
     "all.js"
   ],
   "scripts": {
-    "clean": "node clean.js",
+    "clean": "node scripts/clean.js",
     "prebuild": "yarn clean",
     "build": "tsc && tsc-alias",
+    "postbuild": "yarn generate-types",
+    "generate-types": "ts-node scripts/generate-types.ts",
     "lint": "eslint .",
     "lint:fix": "yarn lint --fix",
     "prepare": "husky",
     "prepublishOnly": "yarn build",
     "precommit": "lint-staged",
+    "pretest": "yarn generate-types",
     "test": "jest --color=true",
     "test:clearCache": "yarn test --clearCache",
     "test:updateSnapshot": "yarn test --updateSnapshot",
+    "pretest:coverage": "yarn generate-types",
     "test:coverage": "yarn test --coverage",
     "test:watch": "yarn test --watch",
     "typecheck": "tsc --noEmit",
@@ -61,6 +64,7 @@
     "lint-staged": "~15.5.0",
     "prettier": "^3.0.0",
     "ts-jest": "^29.0.0",
+    "ts-node": "^10.9.2",
     "tsc-alias": "^1.8.0",
     "typescript": "^5.0.0"
   },

clean.js renamed to scripts/clean.js

@@ -1,6 +1,6 @@
 const fs = require('fs');
 const path = require('path');
-const distPath = path.join(__dirname, 'dist');
+const distPath = path.join(__dirname, '..', 'dist');
 if (fs.existsSync(distPath)) {
   fs.rmSync(distPath, { recursive: true, force: true });
 }

scripts/generate-types.ts

@@ -0,0 +1,141 @@
+import * as ts from 'typescript';
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface MatcherInfo {
+  name: string;
+  docComment: string;
+  parameters: {
+    name: string;
+    type: string;
+    optional?: boolean;
+    rest?: boolean;
+  }[];
+  returnType: string;
+}
+
+function extractMatcherInfo(sourceFile: ts.SourceFile): MatcherInfo[] {
+  const matchers: MatcherInfo[] = [];
+  ts.forEachChild(sourceFile, node => {
+    if (ts.isFunctionDeclaration(node) && node.name) {
+      const matcherName = node.name.text;
+      // Extract the full JSDoc block (not just tags)
+      let docComment = '';
+      const jsDocs = (node as any).jsDoc;
+      if (jsDocs && jsDocs.length > 0 && jsDocs[0].comment) {
+        docComment = jsDocs[0].comment;
+        // If there are tags, add them as well
+        if (jsDocs[0].tags && jsDocs[0].tags.length > 0) {
+          const tags = jsDocs[0].tags.map((tag: any) => {
+            let tagLine = `@${tag.tagName.escapedText}`;
+            if (tag.typeExpression && tag.typeExpression.type) {
+              tagLine += ` {${tag.typeExpression.type.getText()}}`;
+            }
+            if (tag.name) tagLine += ` ${tag.name.escapedText}`;
+            if (tag.comment) tagLine += ` ${tag.comment}`;
+            return tagLine;
+          });
+          docComment += '\n' + tags.join('\n');
+        }
+      }
+      // Skip the first parameter (actual) as it's implicit in Jest matchers
+      const parameters = node.parameters.slice(1).map(param => {
+        const paramName = param.name.getText(sourceFile);
+        const paramType = param.type ? param.type.getText(sourceFile) : 'unknown';
+        // Check if parameter is optional (has default value or is marked with ?)
+        const isOptional = param.initializer !== undefined || param.questionToken !== undefined;
+        // Check if parameter is a rest parameter
+        const isRest = param.dotDotDotToken !== undefined;
+        return { 
+          name: paramName, 
+          type: paramType, 
+          optional: isOptional,
+          rest: isRest 
+        };
+      });
+      const returnType = node.type ? node.type.getText(sourceFile) : 'unknown';
+      matchers.push({ name: matcherName, docComment, parameters, returnType });
+    }
+  });
+  return matchers;
+}
+
+function generateTypeDefinition(matcher: MatcherInfo): string {
+  // Split docComment into lines, trim, and wrap in JSDoc
+  let docBlock = '';
+  if (matcher.docComment && matcher.docComment.trim().length > 0) {
+    const lines = matcher.docComment.split('\n').map(line => `   * ${line.trim()}`);
+    docBlock = ['  /**', ...lines, '   */'].join('\n');
+  }
+  const params = matcher.parameters.map(p => {
+    const prefix = p.rest ? '...' : '';
+    const suffix = p.optional ? '?' : '';
+    return `${prefix}${p.name}${suffix}: ${p.type}`;
+  }).join(', ');
+  
+  // Check if the function uses the E type parameter
+  const needsGenericE = matcher.parameters.some(p => p.type.includes('E')) || 
+                       matcher.returnType.includes('E');
+  
+  // Add generic type parameter if needed
+  const genericParams = needsGenericE ? '<E>' : '';
+  
+  // Add two newlines after each method for clarity
+  return `\n${docBlock}\n  ${matcher.name}${genericParams}(${params}): R;\n`;
+}
+
+function generateTypeFile(matchers: MatcherInfo[]): string {
+  return `interface CustomMatchers<R> extends Record<string, any> {${matchers
+    .map(generateTypeDefinition)
+    .join('')}
+}
+
+declare namespace jest {
+  interface Matchers<R> {${matchers
+    .map(generateTypeDefinition)
+    .join('')}
+  }
+
+  interface Expect extends CustomMatchers<any> {}
+  interface InverseAsymmetricMatchers extends Expect {}
+}
+
+declare module 'jest-extended' {
+  const matchers: CustomMatchers<any>;
+  export = matchers;
+}`;
+}
+
+function main() {
+  const matchersDir = path.join(__dirname, '../src/matchers');
+  const typesDir = path.join(__dirname, '../types');
+  const outputFile = path.join(typesDir, 'index.d.ts');
+
+  // Read all matcher files
+  const matcherFiles = fs.readdirSync(matchersDir)
+    .filter(file => file.endsWith('.ts') && file !== 'index.ts');
+
+  const matchers: MatcherInfo[] = [];
+
+  // Process each matcher file
+  for (const file of matcherFiles) {
+    const filePath = path.join(matchersDir, file);
+    const sourceFile = ts.createSourceFile(
+      filePath,
+      fs.readFileSync(filePath, 'utf8').replace(/\r/g, ''),
+      ts.ScriptTarget.Latest,
+      true
+    );
+
+    const matcherInfos = extractMatcherInfo(sourceFile);
+    matchers.push(...matcherInfos);
+  }
+
+  // Generate and write type definitions
+  const typeDefinitions = generateTypeFile(matchers);
+  fs.mkdirSync(typesDir, { recursive: true });
+  fs.writeFileSync(outputFile, typeDefinitions);
+  console.log(`Generated type definitions in ${outputFile}`);
+}
+
+main(); 

src/matchers/fail.ts

@@ -1,3 +1,9 @@
+/**
+ * Note: Currently unimplemented
+ * Failing assertion
+ *
+ * @param {String} message
+ */
 export function fail(_: unknown, message: string) {
   return {
     pass: false,

src/matchers/pass.ts

@@ -1,3 +1,9 @@
+/**
+ * Note: Currently unimplemented
+ * Passing assertion
+ *
+ * @param {String} message
+ */
 export function pass(_: unknown, message: string) {
   return {
     pass: true,

src/matchers/toBeAfter.ts

@@ -1,3 +1,7 @@
+/**
+ * Use `.toBeAfter` when checking if a date occurs after `date`.
+ * @param {Date} after
+ */
 export function toBeAfter(actual: unknown, after: Date) {
   // @ts-expect-error OK to have implicit any for this.utils
   const { printReceived, matcherHint } = this.utils;

src/matchers/toBeAfterOrEqualTo.ts

@@ -1,3 +1,7 @@
+/**
+ * Use `.toBeAfterOrEqualTo` when checking if a date equals to or occurs after `date`.
+ * @param {Date} date
+ */
 export function toBeAfterOrEqualTo(actual: unknown, expected: Date) {
   // @ts-expect-error OK to have implicit any for this.utils
   const { printReceived, matcherHint } = this.utils;

src/matchers/toBeArray.ts

@@ -1,8 +1,11 @@
-export function toBeArray(expected: unknown) {
+/**
+ * Use `.toBeArray` when checking if a value is an `Array`.
+ */
+export function toBeArray(actual: unknown) {
   // @ts-expect-error OK to have implicit any for this.utils
   const { matcherHint, printReceived } = this.utils;
 
-  const pass = Array.isArray(expected);
+  const pass = Array.isArray(actual);
 
   return {
     pass,
@@ -11,10 +14,10 @@ export function toBeArray(expected: unknown) {
         ? matcherHint('.not.toBeArray', 'received', '') +
           '\n\n' +
           'Expected value to not be an array received:\n' +
-          `  ${printReceived(expected)}`
+          `  ${printReceived(actual)}`
         : matcherHint('.toBeArray', 'received', '') +
           '\n\n' +
           'Expected value to be an array received:\n' +
-          `  ${printReceived(expected)}`,
+          `  ${printReceived(actual)}`,
   };
 }

src/matchers/toBeArrayOfSize.ts

@@ -1,5 +1,9 @@
 import { determinePropertyMessage } from 'src/utils';
 
+/**
+ * Use `.toBeArrayOfSize` when checking if a value is an `Array` of size x.
+ * @param {Number} expected
+ */
 export function toBeArrayOfSize(actual: unknown, expected: number) {
   // @ts-expect-error OK to have implicit any for this.utils
   const { printExpected, printReceived, matcherHint } = this.utils;