♻️ 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:
tmu committed 2026-09-23 22:19:02 +00:00
1 parent 9c9468fa3c
commit 5ddbbdc183
7 files changed
+37 -145

No files matched your search

+13 -15
View File
@@ -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.