♻️ Keep the public API to the four factories
The builder types are already the inferred return types and travel into the emitted .d.ts, so exporting them only made them nameable while pinning the internal Strict/Widening split as API. Revert the type exports and the public renames, drop the type-surface test, and document only the factories in README and development/library.md.
This commit is contained in:
1 parent
9c9468fa3c
commit
5ddbbdc183
7 files changed
+37
-145
No files matched your search
+13
-15
@@ -12,32 +12,30 @@ is implementation detail.
|
||||
|
||||
#### Decision (2026-09)
|
||||
|
||||
`src/index.ts` exports the four factories and the builder types they return:
|
||||
`PrimitiveUnionMatcher` / `PrimitiveUnionMatcherW`, `TaggedUnionMatcher` /
|
||||
`TaggedUnionMatcherW`, and `TaggedUnionMatcherFactory` /
|
||||
`TaggedUnionMatcherWFactory`. Every exported symbol carries TSDoc. The
|
||||
universe-agnostic pieces in `matcher-shared.ts` stay internal.
|
||||
`src/index.ts` exports the four factories and nothing else. Every exported
|
||||
function carries TSDoc; the builder types and the `matcher-shared.ts`
|
||||
vocabulary stay internal.
|
||||
|
||||
#### Why
|
||||
|
||||
- The builder interfaces are already the inferred return types (they appear in
|
||||
the emitted `.d.ts`), so exporting them only makes them nameable — a consumer
|
||||
can annotate a factory result without restating its structure.
|
||||
- The `Strict` / `Widening` suffixes were dropped for the public names because
|
||||
the factory names already carry the `W` axis; the type and function names line
|
||||
up (`getPrimitiveUnionMatcher` → `PrimitiveUnionMatcher`).
|
||||
- The factories are the whole contract: a consumer calls one and never needs to
|
||||
name the builder type it returns.
|
||||
- The builder interfaces are already the inferred return types, so they travel
|
||||
into the emitted `.d.ts` regardless. Exporting them would only make them
|
||||
nameable while freezing the internal `Strict` / `Widening` overload split as
|
||||
API.
|
||||
- TSDoc travels into the emitted declarations, so editor hovers and the
|
||||
published package document the API without a hand-written `.d.ts`.
|
||||
- `matcher-shared.ts` stays internal: its types are plumbing (`Handlers`,
|
||||
`Fallback`, `UniverseGate`, …) whose shape follows the implementation, and the
|
||||
matchers are the stable contract.
|
||||
|
||||
#### Rejected
|
||||
|
||||
- **Exporting the builder types** (`PrimitiveUnionMatcher`, …). Nameable, but it
|
||||
grows the surface for no call-site benefit and pins the `Strict` / `Widening`
|
||||
split.
|
||||
- **Exporting the `matcher-shared.ts` vocabulary** (`Matchable`, `UnaryFn`,
|
||||
`PatternKey`, `Member`, `PatternReturns`, …). They appear in the public
|
||||
signatures, but a consumer never needs to name them; exporting them would
|
||||
freeze internals as API.
|
||||
freeze plumbing as API.
|
||||
- **A hand-written `.d.ts` or a separate API document.** It would drift from the
|
||||
implementation; TSDoc is generated from the source.
|
||||
|
||||
|
||||
Reference in new issue
Block a user