Are the Types Wrong

Are the Types Wrong is a tool designed to analyze npm packages for TypeScript type issues, specifically focusing on ESM-related module resolution problems. It detects issues across node10, node16, and bundler module resolution modes.

Key problems detected include:

• Resolution failed: The module cannot be resolved.
• No types: The resolution succeeds but no type definitions are found.
• Masquerading as CJS/ESM: The package claims to be one module type but behaves like another.
• ESM (dynamic import only): The package can only be loaded via dynamic import.
• Used fallback condition: The package relies on problematic exports fallback conditions.
• CJS default export issues: Problems with how default exports are handled in CommonJS.
• Incorrect/False default exports: Mismatches in how default exports are declared vs. how they behave.
• Missing export =: Missing the standard CommonJS export pattern.
• Unexpected module syntax: Syntax that violates the expected module type.
• Internal resolution error: Errors occurring during the internal resolution process.
• Named exports: Issues specifically related to named export availability.

To resolve this error, ensure that your package.json exports map provides specific type declarations for both ESM and CJS entry points. A single .d.ts file cannot represent two different module formats.

Recommended Fix: Explicit Condition Mapping

Map the import condition to a .d.mts file and the require condition to a .d.ts file:

{
  "name": "pkg",
  "exports": {
    ".": {
      "import": {
        "types": "./index.d.mts",
        "default": "./index.mjs"
      },
      "require": {
        "types": "./index.d.ts",
        "default": "./index.js"
      }
    }
  }
}

Alternative Fix: Extension Substitution

If your files follow standard naming conventions, you can simplify the exports map and let TypeScript find the correct types via extension substitution:

{
  "name": "pkg",
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.js"
    }
  }
}

In this setup, TypeScript will automatically look for ./index.d.mts for imports and ./index.d.ts for requires.

When a CommonJS (CJS) module simulates a default export using exports.default and exports.__esModule = true without also assigning to module.exports, it creates a divergence in behavior between Node.js and bundlers (like Webpack or esbuild).

The Problem

If a module is structured like this:

Object.defineProperty(exports, "__esModule", { value: true });
exports.default = function f() {
  /* ... */
};

A default import import mod from "pkg"; will result in:

• In Node.js: mod is the object { default: [Function: f] }.
• In most bundlers: mod is the function [Function: f].

This makes it difficult to write code that works consistently across both environments.

Mitigation for Library Authors

To ensure a default import correctly resolves to the intended function in both Node.js and bundlers, use a circular assignment pattern. Assign the intended export to module.exports, and then assign module.exports.default back to itself:

Object.defineProperty(exports, "__esModule", { value: true });
function f() {
  /* ... */
}
module.exports = f;
module.exports.default = f;

Consumer Workaround

If you are consuming a package that has this issue and you are running in Node.js, you may need to access the export via the .default property on the imported module:

import mod from "pkg";
const actualExport = mod.default;

The @arethetypeswrong/history package provides historical @arethetypeswrong/core analysis for every npm-high-impact package. It tracks the latest version available on the first of every month from January 2022 onwards.

The data is provided as a large dataset (compressed for npm) and can be accessed programmatically in Node.js using two primary functions:

1. getVersionsByDate(): Returns a mapping of dates to the packages and versions available on that date.
2. getAllDataAsObject(): Returns the full analysis dataset as a JavaScript object, where keys are formatted as ${packageName}@${packageVersion}.

Note: If a package does not contain types, its entry in the data object will be undefined.

import { getAllDataAsObject, getVersionsByDate } from "@arethetypeswrong/history";

const dates = await getVersionsByDate();
const data = await getAllDataAsObject();

// Example: Finding packages with specific problems on a specific date
function getPackagesWithFalseCJSProblems(date) {
  const packages = dates[date];
  const result = [];
  for (const { packageName, packageVersion } of packages) {
    const analysis = data[`${packageName}@${packageVersion}`];
    // `analysis` is undefined if the package doesn't contain types
    if (analysis?.problems.some((p) => p.kind === "FalseESM")) {
      result.push(analysis);
    }
  }
  return result;
}

const mayFalseESMProblems = getPackagesWithFalseCJSProblems("2023-05-01").length;
const juneFalseESMProblems = getPackagesWithFalseCJSProblems("2023-06-01").length;
console.log({ mayFalseESMProblems, juneFalseESMProblems });