Skip to content

fix(pkg): resolve conditional types for CJS and remove install-time scripts - #166

Merged
cawalch merged 1 commit into
mainfrom
fix/package-exports-and-install
Nov 1, 2026
Merged

cawalch merged 1 commit into
mainfrom
fix/package-exports-and-install

Conversation

@cawalch

@cawalch cawalch commented Nov 1, 2026

Copy link
Copy Markdown
Collaborator

A second-pass audit of the merged toolchain changes — packed artifact vs. the published 1.5.0, Node 20.19 and 26 runtimes, TypeScript 5.9 under node16/bundler, and publint/attw — found four consumer-facing problems. This fixes them.

What turned up

  1. CJS consumers got broken types. exports had a single top-level types pointing at index.d.ts. Because the package is "type": "module", TypeScript under moduleResolution: node16 treats that file as ESM, so import from a CommonJS file failed with TS1479; attw reported "Masquerading as ESM" for the root, ./stream, and ./cli.
  2. Every consumer install warned. The prepare script added in chore: replace husky and lint-staged with a Git hook #165 made npm 11.20 print install-scripts … unreviewed (prepare: node scripts/install-hooks.js) when installing the published package. The file it references is not in the tarball (files: ["dist/"]), so auto-installation was also a latent failure.
  3. Dangling declaration maps. The generated .d.ts files ended with //# sourceMappingURL=index.d.ts.map, but dts.sourcemap was disabled, so the referenced maps did not exist (the old tsup artifact had neither).
  4. Contributor Node floor was implicit. engines says >=20.19.0, but tsdown needs ^22.18, vitest@5 needs ^22.12, and the hook tooling assumes a modern Node — someone on Node 20 following engines could install and then fail at npm test.

Changes

• Per-condition types: import → .d.ts, require → .d.cts for the root, ./stream, and ./cli (browser branches included). attw is now green for node16 (CJS and ESM) and bundler.
• Emit declaration maps (dts: { sourcemap: true }); the tarball grows from 29 to 33 files, and the sourceMappingURL comments resolve.
• Remove prepare; keep npm run hooks:install. Installs no longer warn and no unpublished script is referenced. Trade-off: hooks are opt-in for contributors.
• Add devEngines (node >=22.18, onFail: warn). engines stays >=20.19.0 — the runtime artifacts still work there (verified below).
• Add publint as npm run check:pkg and run it in CI, so export-map regressions fail the build.

Verification

  • Published artifact parity: same 26 build outputs plus 4 declaration maps; CJS and ESM export keys are identical to the published 1.5.0; CJS/ESM/CLI behavior matches.
  • Node runtimes: require, import, and the CLI work on Node 20.19.0 and 26.13.0.
  • TypeScript: a consumer with TypeScript 5.9 typechecks import/require under both moduleResolution: node16 and bundler, including CompiledQuery, ValidationResult, ExpressionNode, and the ./stream subpath.
  • Install: a fresh consumer install of the packed tarball produces no install-scripts warning and no script execution.
  • Checks: lint:ci, typecheck, build, 1,380 tests, artifact tests (21), coverage thresholds, publint, npm audit (0), and osv-scanner (0) all pass.

Remaining, deliberately not changed

  • pkg.browser still points at the IIFE bundle, and exports["."].browser.require resolves to the same IIFE. publint lists this as a suggestion, not an error. Pointing it at index.esm.js/index.cjs would be more correct for bundlers but changes a long-standing public mapping; worth a separate change with a bundler test.
  • attw reports resolution failures for the ./stream and ./cli subpaths under node10 resolution. Those subpaths require exports support (TypeScript ≥4.7); Node 10 is long EOL, so this is expected rather than actionable.

…cripts

Validate the packed artifact with publint and attw; both surfaced consumer-facing problems.

• Split `exports` types per condition (`import` → `.d.ts`, `require` → `.d.cts`) for the root, `./stream`, and `./cli`. TypeScript with `moduleResolution: node16` previously reported the package as "Masquerading as ESM" for CommonJS consumers.
• Ship declaration maps (`dts.sourcemap`) so the `sourceMappingURL` comments in the emitted declarations resolve instead of pointing at missing files.
• Remove the `prepare` script: npm 11.20 warns on every consumer install about an unapproved install script, and the referenced file is not published. Hooks stay available through `npm run hooks:install`.
• Add `devEngines` requiring Node >=22.18 for contributors; the published `engines` floor stays `>=20.19.0` because the built artifacts still run there.
• Add `publint` as `check:pkg` and run it in CI.
@cawalch
cawalch merged commit 2213b8d into main Nov 1, 2026
9 checks passed
@cawalch
cawalch deleted the fix/package-exports-and-install branch November 1, 2026 17:03
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.

1 participant