Skip to content

fix: ship type declarations for the CommonJS require entry - #1011

Open
pcriadoperez wants to merge 4 commits into
ccxt:masterfrom
pcriadoperez:claude/quirky-franklin-bu2uhh
Open

pcriadoperez wants to merge 4 commits into
ccxt:masterfrom
pcriadoperez:claude/quirky-franklin-bu2uhh

Conversation

@pcriadoperez

@pcriadoperez pcriadoperez commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Fixes #1010

Problem

Under --module node16/nodenext, TypeScript resolves types through exports and ignores the top-level typings field. exports["."].require pointed only at dist/cjs/node-binance-api.cjs, with no declarations next to it. CommonJS consumers (a .cts file, or a .ts file in a package without "type": "module") therefore got TS7016 and an implicit any.

Fix

  • package.json: import and require each get a types condition.
  • New scripts/generate-cjs-types.mjs, run as bundle-cjs-types in npm run build:
    1. Copies dist/*.d.ts to dist/cjs/types/*.d.cts.
      • Relative imports are rewritten to the .cjs copies.
      • Package default imports (import WebSocket from 'ws') become import WebSocket = require('ws').
      • Without these copies, a CommonJS declaration would import an ES module declaration. TypeScript rejects that under node16/node18, and under nodenext before 5.8 (TS1541/TS1479).
    2. Writes dist/cjs/node-binance-api.d.cts, which uses export = because the rollup CJS bundle does module.exports = Binance.
      • Reusing the ESM export default declaration would type the module as require(...).default, which is undefined at runtime.
      • The other ESM type exports (Order, Interval, Dictionary<T>, …) are re-exposed through a namespace merged with the class, so both Binance.Order and import type { Order } from 'node-binance-api' work.
      • The list is read from the emitted ESM .d.ts with the TypeScript compiler API, so new types in src/ are picked up without edits.
    3. Type-checks its own output with skipLibCheck off under node16 and nodenext, with esModuleInterop on and off. If the output doesn't check, the build fails rather than shipping broken types.
  • It also fails the build if a non-default value export is added, because the CJS bundle wouldn't expose it. Type-only re-exports are fine.

Generated entry (excerpt):

import type * as ESM from './types/node-binance-api.cjs';
declare const Binance: typeof ESM.default;
type Binance = ESM.default;
declare namespace Binance {
    export type Account = ESM.Account;
    export type Dictionary<T> = ESM.Dictionary<T>;
    // ... 52 types in total
}
export = Binance;

Tests (TDD)

Each fix commit comes after a commit that adds the failing test for it.

  • tests/package-types.sh (npm run package-types-test, run in CI right after Build):
    • packs the package, installs the tarball into a fresh temp project, and runs strict tsc with skipLibCheck off;
    • runs under node16 and nodenext, with esModuleInterop both on and off;
    • consumer files:
      • cjs-require.cts: import Binance = require('node-binance-api'), plus namespaced types
      • cjs-default-import.cts: default import and import type { Interval } from a CJS file
      • esm-import.mts: regression guard for the ESM entry
    • @ts-expect-error guards in each file make the test fail if the module silently resolves to any.
  • On master the test fails with TS7016.
  • An independent review then found that the first version of this PR still failed under node16 (TS1541) and with esModuleInterop: false (TS1259). The test now covers both, and both pass.
  • Manual matrix against the packed tarball, with node16 and nodenext and errors from @types/* ignored:
    • TS 5.4.5, 5.7.3, 5.8.3, 5.9.3: OK with esModuleInterop on and off.
    • TS 7.0.2: OK. esModuleInterop can't be turned off in TS 7.
    • The issue's exact repro passes on TS 5.9.3 and 7.0.2.
    • TS 5.0 only shows a lib.dom vs @types/node conflict, which doesn't involve this package.
  • At runtime, require() returns the class and the ESM default import is the class, matching the types.
  • CI on this branch ran the live suites (REST, package test with live calls from the CJS and ESM consumers, and WebSocket), and they passed.

Notes

  • The top-level typings field is unchanged. Under node10 resolution, import X = require('node-binance-api') still sees the ESM export default types, as on master. That is out of scope here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XpTLXUxpfhtzV8YPuQiJAh

Adds tests/package-types.sh, which packs the package, installs it into a
fresh consumer project and runs tsc under --module nodenext against a
CommonJS (.cts) and an ES module (.mts) consumer. The CJS cases currently
fail with TS7016 because the `require` export has no declarations (ccxt#1010).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpTLXUxpfhtzV8YPuQiJAh
Under --module node16/nodenext TypeScript resolves types through
`exports` and ignores the top-level `typings` field, so CommonJS consumers
got TS7016 because `exports["."].require` had no declarations.

- Add `types` conditions to both the `import` and `require` exports.
- Generate dist/cjs/node-binance-api.d.cts at build time. The CJS bundle
  does `module.exports = Binance`, so the declaration uses `export =` and
  re-exposes the ESM type exports via a merged namespace (Binance.Order,
  or `import type { Order } from 'node-binance-api'`). The type list is
  read from the emitted ESM declarations so it stays in sync with src/.
- Add `bundle-cjs-types` to the build and a `package-types-test` script.

Fixes ccxt#1010

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpTLXUxpfhtzV8YPuQiJAh
…Interop

The package types test only ran under --module nodenext with the locked
TypeScript 5.8, where a CommonJS declaration may import an ES module
declaration. Run it under node16 as well, and add a pass with
esModuleInterop disabled. Both currently fail (TS1541 and TS1259).

Also make the script fail fast (set -euo pipefail) and stop hiding npm
install errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpTLXUxpfhtzV8YPuQiJAh
The generated dist/cjs/node-binance-api.d.cts imported the ESM
declarations, which TypeScript rejects from a CommonJS file under
--module node16/node18, and under nodenext before 5.8 (TS1541/TS1479)
when skipLibCheck is off.

- Copy dist/*.d.ts to dist/cjs/types/*.d.cts, rewriting relative
  imports to the .cjs copies and package default imports
  (`import WebSocket from 'ws'`) to `import X = require(...)` so they
  also work with esModuleInterop disabled.
- Type-check the generated declarations at the end of the generator
  (node16 and nodenext, esModuleInterop on and off, skipLibCheck off),
  so the build fails instead of shipping broken types.
- Don't treat type-only re-exports of classes as value exports.
- Run the package types test right after the build in CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpTLXUxpfhtzV8YPuQiJAh
@pcriadoperez
pcriadoperez marked this pull request as ready for review November 16, 2026 13:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Missing type declarations for the require entry under node16/nodenext

2 participants