📝 Document the TypeScript 5.0 type floor
Consumers need TypeScript >= 5.0: the emitted declarations use const type parameters and keep relative .ts specifiers, both of which resolve only on TS >= 5.0. That also makes the emitted .ts specifiers a non-issue, so the backlog item is closed without a .d.ts post-step: TS <= 4.9 cannot parse the declarations anyway. The README/CONTRIBUTING wording now says the rewrite applies to the JavaScript output, not to the declarations.
This commit is contained in:
1 parent
e7a058d608
commit
a0dd187042
3 files changed
+8
-6
No files matched your search
@@ -39,7 +39,7 @@ Each tool's configuration trade-off is recorded in [Tooling decisions](#tooling-
|
||||
The choice and configuration of each tool above is the result of deliberate trade-offs, not defaults. The non-obvious ones:
|
||||
|
||||
- **`tsconfig.json` extends `@tsconfig/strictest` + `@tsconfig/node26`**; `tsconfig.build.json` extends it to add the emit-only options (`declaration`, `sourceMap`, `inlineSources`, `outDir`, `target: es2024`, `rewriteRelativeImportExtensions: true`) and to exclude test files. `inlineSources` embeds the original TypeScript in `dist/*.js.map`, so debuggers can map into `src/` without it being shipped; `declarationMap` is intentionally off because a `.d.ts.map` cannot embed source and would dangle. This separation lets the editor and CI type-check from one config while the build emits from the other.
|
||||
- **Source imports use `.ts` extensions** so `node --strip-types` resolves them at test time. `rewriteRelativeImportExtensions: true` in `tsconfig.build.json` rewrites them to `.js` in the emitted `dist/*` output, so consumers see conventional ESM imports.
|
||||
- **Source imports use `.ts` extensions** so `node --strip-types` resolves them at test time. `rewriteRelativeImportExtensions: true` in `tsconfig.build.json` rewrites them to `.js` in the emitted JavaScript; the emitted `.d.ts` keep the `.ts` specifier, which TypeScript >= 5.0 resolves (see [Requirements](#requirements)), so no post-processing step is needed.
|
||||
- **Type-aware oxlint is enabled declaratively** via `options.typeAware: true` in `.oxlintrc.json` (powered by `oxlint-tsgolint`). The script commands stay clean — no CLI flag — and type-aware mode is a property of the config, not the invocation.
|
||||
- **Source-level `oxlint-disable` directives** are used for known type-aware false positives (see `src/pattern.ts`, `src/match.ts`, `src/index.test.ts`). The disable lives next to the code it silences, not in `.oxlintrc.json`, so the trade-off is visible to anyone reading the source.
|
||||
- **`knip --include dependencies,exports,files`** intentionally omits the `types` category, which produces systematic false positives for libraries whose exported types are part of the public API. The targeted scope keeps the signal high without config-file boilerplate.
|
||||
@@ -52,6 +52,7 @@ The choice and configuration of each tool above is the result of deliberate trad
|
||||
### Requirements
|
||||
|
||||
- Node.js >= 26 (engines field; pinned via `.node-version`).
|
||||
- TypeScript >= 5.0 to consume the published declarations. The emitted `.d.ts` use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers; both resolve on TS >= 5.0 in `node10`/`node16`/`nodenext`/`bundler`.
|
||||
|
||||
## VSCode integration
|
||||
|
||||
|
||||
Reference in new issue
Block a user