tmu/tiny-pattern-ts
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 16 Wiki Activity

Compare commits

base: tmu/tiny-pattern-ts:0.1.6
tmu/tiny-pattern-ts:main
tmu/tiny-pattern-ts:0.9.0 tmu/tiny-pattern-ts:0.8.3 tmu/tiny-pattern-ts:0.8.2 tmu/tiny-pattern-ts:0.8.1 tmu/tiny-pattern-ts:0.8.0 tmu/tiny-pattern-ts:0.7.1 tmu/tiny-pattern-ts:0.7.0 tmu/tiny-pattern-ts:0.6.0 tmu/tiny-pattern-ts:0.5.0 tmu/tiny-pattern-ts:0.4.0 tmu/tiny-pattern-ts:0.3.0 tmu/tiny-pattern-ts:0.2.0 tmu/tiny-pattern-ts:0.1.8 tmu/tiny-pattern-ts:0.1.7 tmu/tiny-pattern-ts:0.1.6 tmu/tiny-pattern-ts:0.1.5 tmu/tiny-pattern-ts:0.1.4 tmu/tiny-pattern-ts:0.1.3 tmu/tiny-pattern-ts:0.1.2 tmu/tiny-pattern-ts:0.1.1 tmu/tiny-pattern-ts:0.1.0
..
compare: tmu/tiny-pattern-ts:1723419e69f47b1944cc4b51f26b044e70105f19
tmu/tiny-pattern-ts:main
tmu/tiny-pattern-ts:0.9.0 tmu/tiny-pattern-ts:0.8.3 tmu/tiny-pattern-ts:0.8.2 tmu/tiny-pattern-ts:0.8.1 tmu/tiny-pattern-ts:0.8.0 tmu/tiny-pattern-ts:0.7.1 tmu/tiny-pattern-ts:0.7.0 tmu/tiny-pattern-ts:0.6.0 tmu/tiny-pattern-ts:0.5.0 tmu/tiny-pattern-ts:0.4.0 tmu/tiny-pattern-ts:0.3.0 tmu/tiny-pattern-ts:0.2.0 tmu/tiny-pattern-ts:0.1.8 tmu/tiny-pattern-ts:0.1.7 tmu/tiny-pattern-ts:0.1.6 tmu/tiny-pattern-ts:0.1.5 tmu/tiny-pattern-ts:0.1.4 tmu/tiny-pattern-ts:0.1.3 tmu/tiny-pattern-ts:0.1.2 tmu/tiny-pattern-ts:0.1.1 tmu/tiny-pattern-ts:0.1.0
103 Commits
0.1.6 .. 1723419e69
Author SHA1 Message Date
tmu 1723419e69 🚀 Release 0.6.0
CI / release-gate (push) Successful in 3s
Details
CI / build (push) Successful in 33s
Details
CI / maintain (push) Failing after 13s
Details
CI / publish (push) Failing after 16s
Details
2026-09-22 11:10:34 +00:00
tmu dcd5f8d1c4 🔀 Merge feature/tagged-union-boolean-nullish-tags into main 2026-09-22 11:09:21 +00:00
tmu 4ebe18adb1 ♻️ Align primitive-union matcher names and drop stale lint disables 
Rename `MatcherStrict` / `MatcherWidening` to
`PrimitiveUnionMatcherStrict` / `PrimitiveUnionMatcherWidening`, matching
the exported `getPrimitiveUnionMatcher(W)` names and the
`TaggedUnionMatcher*` pair.

Folds in the working-tree lint cleanups: drop the now-unneeded
`typescript/unified-signatures` disables and turn the tagged-union
factory interfaces into type aliases.
 2026-09-22 11:05:16 +00:00
tmu 09e1c12270 ♻️ Return dispatch tacitly from the tagged-union factory 2026-09-22 10:57:03 +00:00
tmu 6228b4922d ♻️ Share the Matchable universe between both matchers 2026-09-22 10:54:27 +00:00
tmu d88a4eeb45 📝 Track optional discriminants under the union-property task 2026-09-22 10:45:54 +00:00
tmu fcec637f01 ✅ Check the runtime member in every boolean/nullish handler 2026-09-22 10:36:03 +00:00
tmu f7b7a06f1a ✅ Assert the fallback receives real boolean/nullish tags 2026-09-22 10:33:26 +00:00
tmu c06538d6c1 📝 Check off the tagged-union non-key tags task 2026-09-22 10:23:06 +00:00
tmu e96ca12149 ✨ Allow boolean and nullish tags in tagged unions 
A `boolean` / `null` / `undefined` discriminant cannot key a handler
map, so the tagged-union matcher now routes it through the
`PatternKey` / `PatternParam` projection the primitive-union matcher
already used. Both matchers share the projection from
`matcher-shared.ts`; `MapTaggedUnion`, `Handlers`, `HandledMembers`
and `MustBePartial` key off the projected form and invert it to
recover the real member.

Covers exhaustive and fallback dispatch, the redundant-fallback
guard, and the LSP popup offering the tags by name.
 2026-09-22 10:22:59 +00:00
tmu b81a8149d9 🔀 Merge chore/rename-primitive-union into main 2026-09-22 09:58:28 +00:00
tmu a88d49ffe2 📝 Check off the primitive-union rename 2026-09-22 09:47:05 +00:00
tmu 02f736507c ♻️ Rename primitive to primitive-union 
`getMatcher` / `getMatcherW` become `getPrimitiveUnionMatcher` /
`getPrimitiveUnionMatcherW`; `src/primitive.ts` and its test move to
`src/primitive-union.*`. The `Union` suffix mirrors `getTaggedUnionMatcher`.
 2026-09-22 09:46:59 +00:00
tmu 0727117afb 🔀 Merge chore/lsp-symbol-search-rule into main 2026-09-22 09:43:56 +00:00
tmu b293e611b2 📝 Prefer LSP for symbol lookup in AGENTS 2026-09-22 09:43:08 +00:00
tmu 63b020338e 🔀 Merge chore/backlog-notes into main 2026-09-22 09:15:04 +00:00
tmu 32b9ce0987 📝 Note two matcher gaps in the backlog 
Record the non-exhaustive broad-type hole in the primitive matcher and the
never-typed handler parameters the tagged-union matcher produces when a
property is a union, so both can be picked up as their own work units.
 2026-09-22 09:14:58 +00:00
tmu 434c3a2222 🔀 Merge feature/tagged-union-matcher into main
CI / release-gate (push) Successful in 2s
Details
CI / build (push) Successful in 27s
Details
CI / publish (push) Skipped
Details
CI / maintain (push) Failing after 15s
Details
2026-09-21 23:29:48 +00:00
tmu 6280061737 📝 Note the primitive-union rename in the backlog 2026-09-21 23:24:06 +00:00
tmu 23a2776d55 📝 Note the widened-string-union matcher test 2026-09-21 23:21:19 +00:00
tmu 937d84ea48 ♻️ Share matcher internals 2026-09-21 23:15:09 +00:00
tmu 6f4f509b69 ⚡ Inline the tag read into dispatch 2026-09-21 23:02:56 +00:00
tmu 3f22e5ca01 🔥 Drop unused unified-signature disables 2026-09-21 22:53:42 +00:00
tmu 78e9af600d ✅ Cover the discriminant-key popup 2026-09-21 22:36:30 +00:00
tmu 8ab3c6dbc6 📝 Document the tagged-union matcher 2026-09-21 22:14:22 +00:00
tmu c0fc090ee4 ✨ Add a matcher for tagged unions 2026-09-21 22:14:10 +00:00
tmu a4b4618c9f 🚀 Release 0.5.0
CI / release-gate (push) Successful in 2s
Details
CI / build (push) Successful in 30s
Details
CI / maintain (push) Failing after 14s
Details
CI / publish (push) Failing after 17s
Details
2026-09-21 13:11:27 +00:00
tmu bf711cf9fc 🔀 Merge chore/test-handler-runtime-arguments into main 2026-09-21 13:09:10 +00:00
tmu 9e03c52473 ✅ Assert the shape each handler receives 
A handler's `expectTypeOf(shape)` only proved the type the compiler inferred;
nothing observed the argument `dispatch` passed. Passing `String(shape)` at the
call site therefore kept the whole suite green while breaking every key whose
property name differs from its value (`true`, `null`, `1`).

Pair each handler expectation with a runtime assertion: `assert.equal` where a
handler runs for one shape, the disjunction over the set a `_` fallback accepts
where it runs for several. Where the exact value matters the fallback returns
its shape verbatim and the call site asserts it; a widening pattern absorbs the
remainder type into the return union, so the claim stays strict-free. The
mutation above now fails 10 of the 33 tests.

Rule: CONTRIBUTING.md, rationale: development/testing.md § Handler arguments.
 2026-09-21 12:52:58 +00:00
tmu aa6d71076c 🔀 Merge feature/boolean-null-undefined-patterns into main 2026-09-21 11:27:29 +00:00
tmu 80d498e4f4 ⚡ Index dispatch with the raw shape key 
String(shape) defeats V8's numeric-key fast path (measured ~2x on
number-keyed dispatch). JS already coerces boolean/null/undefined to the
same property key, so assert shape to string | number and index directly.
The assertion is TS2538-only; the facade keeps it sound. Needs a source
no-unsafe-type-assertion disable, next to the existing one.
 2026-09-21 11:23:14 +00:00
tmu 1ad19ba308 📝 Document matcher caveats in the README 
State the end-user limits once, in README § Caveats: a member colliding
with its stringification, the unsupported symbol/bigint, and NaN/-0. Drop
the duplicated known-issue prose from development/library.md and the
source comment; link to the README instead.
 2026-09-21 10:33:36 +00:00
tmu 16904440cf 📝 Place test-wide suppressions in the config 
Drop the fixed no-floating-promises header exception from CONTRIBUTING.md
and AGENTS.md; agents must not add a source disable or edit .oxlintrc.json.
Record the split in tooling.md and testing.md: a one-site false positive is a
source disable, a file-class one lives in the test override.
 2026-09-21 10:01:30 +00:00
tmu 9b7dec96e0 🔧 Move test lint disables to oxlint config 
The no-floating-promises header was repeated at the top of every test
file. Centralize it, and the no-null suppression the new null/undefined
cases need, in the **/*.test.ts override.
 2026-09-21 09:56:39 +00:00
tmu 45495fe2a8 ✨ Match boolean, null and undefined 
Extend the matcher universe beyond string | number so a union can carry
boolean, null and undefined members. true|false, null and undefined are
not property keys, so handler keys are their stringification while the
callback still receives the real member. Symbols are rejected (a brand
is compile-time only) and bigint is not a property key.
 2026-09-21 09:44:44 +00:00
tmu c32fe08c73 🔀 Merge chore/spike-redundant-fallback into main
CI / release-gate (push) Successful in 3s
Details
CI / build (push) Successful in 24s
Details
CI / publish (push) Skipped
Details
CI / maintain (push) Failing after 16s
Details
2026-09-20 22:08:35 +00:00
tmu f27966e803 ✨ Reject a fallback for an exhaustive map 
A fallback paired with a handler map that already covers `T` was still
accepted, even though its remainder is empty. Fold the guard into
`Handled`'s own (F-bounded) constraint so it is checked after inference;
a conditional in the fallback parameter is evaluated while `Handled` is
still its constraint and rejects every partial map whose handler callbacks
need contextual typing.
 2026-09-20 22:05:40 +00:00
tmu 7e7f716424 🚀 Release 0.4.0
CI / release-gate (push) Successful in 2s
Details
CI / build (push) Successful in 30s
Details
CI / maintain (push) Failing after 14s
Details
CI / publish (push) Failing after 16s
Details
2026-09-20 21:46:32 +00:00
tmu 62db7de537 🔀 Merge chore/unify-task-branching into main 2026-09-20 21:44:21 +00:00
tmu ff823b3cba 📝 Route every task through the full branching model 
Drop the leaf-task exception in AGENTS.md: a task without subtasks was implemented on the current branch, bypassing create:branch / create:finish. Every task now opens and closes a branch, so the clean-tree / current-main / green-baseline preconditions and the post-merge verify always apply.
 2026-09-20 21:43:46 +00:00
tmu eeb831b717 🔀 Merge feature/fallback-remainder into main
CI / release-gate (push) Successful in 3s
Details
CI / build (push) Successful in 24s
Details
CI / publish (push) Skipped
Details
CI / maintain (push) Failing after 15s
Details
2026-09-19 00:02:23 +00:00
tmu ae7ffb6fa2 📝 Document the two-argument fallback 
Rewrite development/library.md around the new shape: the fallback is a second
argument (so it can receive the remainder), `R` needs an inference site in the
handler map, `Exact` restores the excess-property check, and the overload order
is load-bearing. Record this branch's rejected alternatives (single-object `_`,
currying, `this`/HKT, variance/`const`/`NoInfer`/brands) and the redundant-
fallback known issue. Add the changelog note and check off the backlog task.
 2026-09-18 23:52:47 +00:00
tmu 0d6a3f1b9b ✅ Cover the dispatch throw 
An open universe (`getMatcher<string>()`) types its handler map as an index
signature, so a runtime map with fewer keys still satisfies the exhaustive
overload. Calling the matcher with a missing shape reaches the dispatch guard
and throws — no cast needed.
 2026-09-18 23:48:59 +00:00
tmu 8615723c64 ✅ Cover fallback autocompletes 
When a fallback argument is present, the second overload supplies the
contextual type, so the handler map popup offers optional keys (`a? b? c?`)
and handled keys stay optional (`b? c?`). The exhaustive one-argument popup
is unchanged. Covered for both factories.
 2026-09-18 23:44:51 +00:00
tmu 935e82d205 ✅ Reject a mismatched strict fallback 
The factory-contract test now also covers a fallback whose return does not
fit the common return of the handler map — a `number` handler with a
`string` fallback — which `getMatcherW` accepts as `number | string`.
 2026-09-18 23:37:44 +00:00
tmu c7223dbe69 🐛 Infer strict return from the handler map 
The fallback overload could not infer `R` from the handlers: `R` appeared
only inside the `Exact` constraint, which is not an inference site, so with
inferred handler params it collapsed to `unknown` and the matcher silently
returned `UnaryFn<T, unknown>`. Adding `Partial<Handlers<T, R>>` to the
handler parameter gives `R` an inference site, so the common return is
inferred from the handlers and the fallback alike.

Tests drop their explicit handler return annotations: real handlers are short
and unannotated, and the common type is now inferred from them.
 2026-09-18 23:33:34 +00:00
tmu 2d3577716d ✨ Narrow the fallback to unhandled keys 
The fallback is now the second factory argument — `(handlers, (s) => …)` —
so its parameter is `Exclude<T, keyof handlers>`. A property's contextual
type is fixed before TypeScript infers its sibling keys, so the remainder is
not expressible while the fallback sits in the handler map; a later argument
is contextually typed from inference on an earlier one.

Both factories take the new shape; the tests and autocomplete probes follow.
The generic overloads guard excess keys with type-fest's `Exact`, so the
error lands on the offending property. A redundant fallback (a full handler
map plus one) is still accepted — the guard for it does not survive inference
and is left to its backlog task.
 2026-09-18 23:08:16 +00:00
tmu cc88c07961 🚀 Release 0.3.0
CI / release-gate (push) Successful in 2s
Details
CI / build (push) Successful in 29s
Details
CI / maintain (push) Failing after 15s
Details
CI / publish (push) Failing after 18s
Details
2026-09-18 07:51:16 +00:00
tmu 62c37e6d89 🔀 Merge chore/protocol-backed-lsp-helper into main
CI / release-gate (push) Successful in 3s
Details
CI / build (push) Successful in 24s
Details
CI / publish (push) Skipped
Details
CI / maintain (push) Failing after 14s
Details
2026-09-18 07:45:22 +00:00
tmu 947eac8089 ⏪ Revert the LSP notes in testing.md 
The protocol cross-link and the TS-internal shutdown-race explanation were
too detailed for the category doc. The helper comment keeps a short,
self-contained note on the stdin-EOF workaround.
 2026-09-18 07:43:36 +00:00
tmu eea2fbb17d 🚨 Silence helper oxlint warnings 
The completion helper is test-only (excluded from dist/), so the
style-only no-magic-numbers and unicorn/no-null warnings are tolerable
here. A file-level disable keeps them out of check:oxlint without touching
the project config.
 2026-09-18 07:38:13 +00:00
tmu b278a153d3 📝 Check off the LSP shutdown bug 
Record the cause (Session.updateWatches raced against exit) and the
stdin-EOF fix now that npm run verify is green with no context-canceled
output.
 2026-09-18 07:31:10 +00:00
tmu 8b73143740 🐛 Stop the LSP shutdown context-canceled log 
The TS 7 Go server races Session.updateWatches against the exit
notification; handleExit returns io.EOF, the background context is
cancelled, and the bare error is flushed to stderr once the outgoing
queue closes (server.go / logger.go). Send shutdown and close stdin
instead: EOF makes the server exit cleanly (code 0, no output), with the
kill kept as a fallback. testing.md records the cause.
 2026-09-18 07:31:04 +00:00
tmu 13497d1df8 📝 Check off the LSP helper task 
npm run verify is green: 23 tests pass, check:tsc, check:oxlint, check:oxfmt
and check:cspell clean with the protocol-backed helper.
 2026-09-18 07:17:19 +00:00
tmu 998c4bfd80 📝 Document the protocol-backed LSP helper 
Note that the autocomplete helper drives the server through
vscode-languageserver-protocol, cross-link the tooling decision, and replace
the obsolete string-id known issue with the benign context-canceled stderr
the Go server emits on shutdown.
 2026-09-18 07:16:45 +00:00
tmu 9f56d7ae8e ♻️ Back LSP helper with protocol library 
Replace the hand-rolled JSON-RPC client (framing, pending map, reply
dispatch) with createMessageConnection and typed requests from
vscode-languageserver-protocol. A catch-all onRequest answers the server
requests the old client replied to, and CompletionList/CompletionItem
replace the ad-hoc shape guards. Public LspSession API is unchanged.
 2026-09-18 07:16:25 +00:00
tmu 94ccc16963 ➕ Add the LSP protocol dependency 
The autocomplete helper drives tsc --lsp --stdio; vscode-languageserver-protocol
supplies the transport (re-exported vscode-jsonrpc/node) and the typed LSP
requests, replacing the hand-rolled JSON-RPC client. Record the choice and
the rejected alternatives in tooling.md.
 2026-09-18 07:14:45 +00:00
tmu 0b97632a7c 📝 Track protocol-backed LSP helper 
The autocomplete helper still carries a hand-rolled JSON-RPC client
(Content-Length framing, a pending-request map, server-request replies).
vscode-languageserver-protocol provides all of it plus typed requests, so
track the move as a task with subtasks.
 2026-09-18 07:14:18 +00:00
tmu 6f87c2f3b5 🔀 Merge chore/adopt-three-overload-matcher into main 2026-09-17 21:56:41 +00:00
tmu 88159296d4 📝 Drop the stale scripts test glob from testing.md 
No tests live under scripts/, and every test script (test, test:unit, test:ci,
watch:test) globs only src/**/*.test.ts, so state that. The scripts/**
oxlint scope it was confused with still exists and carries the same
import/no-nodejs-modules exception as the test-helper scope.
 2026-09-17 21:55:41 +00:00
tmu 800c11139d ♻️ Name the matcher factories getMatcher / getMatcherW 
Drop the strict/widened aliases from src/index.ts so the factories are
exported under their own names, and align the type tests, the autocomplete
probe (which now imports the public surface from ./index.ts) and library.md
with them.

Also correct the widened-overload comment: the excess-property check does not
apply to a generic P, so MatcherWidening's keyof guard — not the closed
constraint — is what rejects keys outside T/_, as library.md already
documented.
 2026-09-17 21:48:54 +00:00
tmu 05fad0fcd6 📝 Record the autocomplete and matcher-design decisions 
The matcher is now two three-overload factories; library.md documents why
the union merge, inferred universe, conditional RequireKeys and cases-first
paths were rejected, and lists the two open issues (the fallback sees all of
T; a redundant _ is still accepted). testing.md records the language server
as the autocomplete oracle, and CONTRIBUTING points the exception at the
matcher's own test file.

The backlog marks the design-doc and autocomplete groundwork done alongside
the adoption.
 2026-09-17 20:59:28 +00:00
tmu 58d127da4e ✅ Test the LSP completion helper against the server 
The helper's own contract — marker handling, requested position, label
extraction and the rejection when the marker is absent — is asserted against
in-memory documents whose contextual types are written inline, so the helper
is tested without coupling to the library's code.
 2026-09-17 20:59:19 +00:00
tmu 165bd9e3df ♻️ Adopt the three-overload matcher 
strict/widened each take the exhaustive/fallback pattern shape in three
overloads ordered ExhaustiveLoose -> Fallback -> Handlers. TypeScript reads
the first overload for the object-literal popup (_?, a, b) and the last for
the missing-key error, so autocomplete and the error message are tuned
independently. The fallback is a pattern shape, not a factory, so the four
getPrimitiveUnionMatcher* factories collapse to two.

src/index.ts re-exports the two factories; the prototype scratch files that
explored the alternatives are removed.
 2026-09-17 20:59:09 +00:00
tmu 02634f41de 🔀 Merge chore/test-util-home into main 2026-09-17 13:33:41 +00:00
tmu 9da5b5dbf2 📝 Note the test-helper home in the changelog 2026-09-17 13:23:36 +00:00
tmu dc57529f0f 📝 Correct the upstream claim in branch.sh 
`main` tracks `origin` (ssh); the comment claiming it tracked an
https companion remote was stale.
 2026-09-17 13:23:34 +00:00
tmu 484e5c8ca5 📝 Allow the floating-promise header in test files 
Agents may add the fixed file-level typescript/no-floating-promises
oxlint-disable header at the top of a `*.test.ts` file — the
expectTypeOf() misidentification is a documented false positive
(development/testing.md § Known issues) and the await/void workarounds
collide with eslint/no-void. Every other suppression stays the human
last resort it was.
 2026-09-17 13:23:32 +00:00
tmu c51e32d6a6 📝 Record the test-helper home decision 
development/testing.md § Test helpers: why name beats path under
import/no-relative-parent-imports, why the key needs `#`, why the
`__tests__` folder name, and what was rejected (flat placement, tsconfig
paths, rule exemptions).
 2026-09-17 13:23:29 +00:00
tmu 9e5522c131 🚚 Home test helpers behind #test-utils/* 
src/util/__tests__/ holds shared test helpers, reached from anywhere
in the source tree as `#test-utils/<name>.ts` through
package.json#imports. A bare `~/…` is not a valid imports key — Node
requires `#` — and a direction-free specifier keeps
import/no-relative-parent-imports from ever firing. The `__tests__`
folder name is the pattern tsconfig.build.json already excludes, so
helpers can never ship. Lint scoping: import/no-nodejs-modules off for
the folder (the probe spawns a language server) and
typescript/promise-function-async off to match its promise-returning
style. The LSP probe moves in from scripts/; a smoke test pins the
specifier's resolution and typing without starting a server.
 2026-09-17 13:23:27 +00:00
tmu ee146ce350 🚀 Release 0.2.0
CI / release-gate (push) Successful in 3s
Details
CI / build (push) Successful in 24s
Details
CI / maintain (push) Failing after 15s
Details
CI / publish (push) Failing after 17s
Details
2026-09-16 22:07:16 +00:00
tmu 33c6d9dc8d 🔀 Merge chore/remove-example-code into main 2026-09-16 22:06:17 +00:00
tmu 65e885989b 📝 Backlog the README walkthrough restoration 
The example-code removal stripped the synopsis and examples with the
template modules; track bringing them back around the real API, with the
previous section order recorded so its placement is not re-guessed.
 2026-09-16 22:05:05 +00:00
tmu 16092350b8 📝 Check off example-code removal in backlog 
Note the finished work under [Unreleased] and mark the task and its
subtasks done; retarget the v1.0 coverage tasks at the surviving
primitive module.
 2026-09-16 21:58:14 +00:00
tmu a3eb6183af 🔥 Remove the match and pattern example modules 
They were the template's demo API, not the library's real surface. Drop
them, their README walkthrough, and the tooling note that cited their
disable directives, and point index.ts at the primitive matchers that
remain.
 2026-09-16 21:57:55 +00:00
tmu ce3d618757 🔥 Remove the example index spec 
The spec only exercised the template's match/P example API. Removing it
first lets the modules and exports it imports go next without leaving a
dangling reference.
 2026-09-16 21:57:42 +00:00
tmu 73e5bc0093 🔀 Merge chore/straighten-oxc-rules into main
CI / release-gate (push) Successful in 3s
Details
CI / build (push) Successful in 23s
Details
CI / publish (push) Skipped
Details
CI / maintain (push) Failing after 14s
Details
2026-09-16 21:50:14 +00:00
tmu 08513b36a9 📝 Check off straighten-oxc-rules in backlog 
Note the finished work under [Unreleased] and mark the task and its
subtasks done.
 2026-09-16 21:46:04 +00:00
tmu 068d6b4998 ♻️ Use line comments in primitive matchers 
Replace the three `/* */` prose blocks with `//` line comments, matching
the rest of the codebase and the comment style the oxlint config now
allows.
 2026-09-16 21:46:00 +00:00
tmu fa0b7f2e84 🔧 Allow ternaries and lowercase comments 
Turn off `eslint/no-ternary` and `eslint/capitalized-comments` in the
project config: both encode a style the project rejects, so they belong in
the config's rule map rather than a per-site disable.

Scope the adjacent `oxlint-disable` decision to false positives and
record why a rejected stylistic rule is turned off project-wide.
 2026-09-16 21:45:54 +00:00
tmu 71ecd508b7 🔀 Merge feature/primitve-pattern-matching into main 2026-09-16 21:40:57 +00:00
tmu c13bc2f408 📝 Document why any is retained in primitive matchers 
Rewriting without any was evaluated; the alternatives were more
complex than the current solution. Record the rationale next to the
two oxlint-disable sites so the suppression is not re-litigated.
 2026-09-16 21:39:46 +00:00
tmu 8e2691e6aa 📝 Will add backlog items found while working 2026-09-16 20:43:01 +00:00
tmu 16650b07e3 📝 Backlog primitive literal coverage questions 2026-09-16 20:01:20 +00:00
tmu a0f0894339 ✅ Spec mixed string and numeric union keys 2026-09-16 20:01:12 +00:00
tmu ed71929365 ✅ Check matcher handler params 
The primitive union matchers invoke every handler with the matched
literal, but the specs wrote their handlers with zero parameters, so
the passed value and its inferred key-literal type went untested.

Declare the parameter on each such handler and pin it with
expectTypeOf, matching the style the two already-correct handlers used.
The `_` fallbacks assert the whole union rather than a single literal.
Return-type expectations are unchanged, so the W / non-W widening
distinctions are still covered.
 2026-09-16 19:29:04 +00:00
tmu cce030b8e5 🐛 Type partial W matcher without an any cast 
getPrimitiveUnionMatcherPartialW was declared with the intended
P-inferring signature but assigned via `as any`, hiding that the
declared parameter was not assignable to the implementation's. The
union in PatternPrimitiveUnionPartial makes the `_` arm demand
`_ ∈ keyof P`, which the exhaustive arm cannot prove.

Intersect the inference hook Simplify<P> with the implementation's
parameter shape, R pinned to PatternReturns<P>, so the assignment
type-checks while callers keep inferring P from the argument.

Add a spec for the exhaustive (no `_`) pattern.
 2026-09-16 19:10:40 +00:00
tmu 2ff67801e0 ✨ Add VS Code node:test debugging and runner config 
launch.json: 'Debug current test file' F5 config running
node --test --strip-types on the active file.

settings.json: register .ts with the connor4312.nodejs-testing
extension via nodejs-testing.extensions, using --strip-types (the
repo pins node >=26 with native type stripping) instead of tsx, so
the extension discovers src/*.test.ts and shows Run/Debug lenses
above test() calls in the native Testing UI.

extensions.json: recommend connor4312.nodejs-testing; cspell.json:
allow 'connor' for the extension id.

.gitignore: un-ignore .vscode/launch.json so the config is shared.
 2026-09-16 17:34:53 +00:00
tmu 62a5599ab3 📝 Require labeled AAA blocks in tests 
Rule in CONTRIBUTING.md; decision, why and rejected unlabeled
ordering in development/testing.md.
 2026-09-16 16:00:43 +00:00
tmu 34567856a5 ♻️ Label arrange-act-assert blocks in specs 
Rework every test body into // Arrange / // Act / // Assert blocks
separated by blank lines: the factory is arranged once, the matcher is
built from it in a single act, and all type/runtime checks sink to the
end. index.test.ts adopts the same shape.

Also migrate off expect-type's deprecated toMatchTypeOf: the checks
are assignability tests, so toExtend is the faithful replacement.
 2026-09-16 16:00:41 +00:00
tmu a25ac6d1e2 ✅ Spec primitive union matchers 
Type-driven tests: every expectTypeOf pairs an assert, covering the
header matrix (exhaustive vs partial patterns, strict R vs widened
returns, string and numeric keys, _ fallback wiring).

Negative cases use Parameters<typeof factory>[0] assignability because
expect-type's .not.toBeCallableWith collapses to never on these generic
Simplify<>-wrapped signatures.

Same documented expectTypeOf floating-promise false positive as
index.test.ts, so the same file-level disable applies; testing.md
known-issue updated to list both files.
 2026-09-16 14:52:30 +00:00
tmu 40bf652b97 ✨ Add primitive union pattern matchers 
Curried matchers over string|number literal unions in four variants
(exhaustive/partial x strict/widened return inference), per the header
matrix in src/primitive.ts.

- Adds type-fest for Simplify/ValueOf.
- Deliberate oxlint escape hatches (as any dispatch) until a cast-free
  formulation lands; see the file comments.
 2026-09-16 14:52:21 +00:00
tmu 1e13917cbe 🚀 Release 0.1.8
CI / release-gate (push) Successful in 2s
Details
CI / build (push) Successful in 25s
Details
CI / maintain (push) Successful in 15s
Details
CI / publish (push) Failing after 15s
Details
2026-09-16 09:01:49 +00:00
tmu 42281a0f10 🔀 Merge chore/upgrade-deps into main 2026-09-16 08:56:32 +00:00
tmu c15bc0153e 📝 Require concise prose in development/ 
Actionable sentence in CONTRIBUTING.md § Rules the tools don't enforce;
the why — humans skim, agents imitate the dominant style, so verbosity
compounds — in development/README.md § Decision blocks. Both sides in
one commit per the write-each-fact-once rule.
 2026-09-16 08:00:36 +00:00
tmu ae319f6547 🔧 Ignore @types/node in maintain:outdated 
DefinitelyTyped keeps the @types/node latest dist-tag on the LTS line,
so check-outdated compared the current-line types against a lower
version: a permanent "reverted" flag, scan exit 1, zero signal. Ignored
by package name; --types filtering and a version-scoped pin rejected
(rationale in development/tooling.md).
 2026-09-16 07:55:25 +00:00
tmu 63e8edce79 ⬆️ Upgrade dependencies 
@types/node to ^26.6.1 and cspell to ^10.3.2 — the only packages
check-outdated found behind the registry, both bumps within the existing
semver ranges. cspell 10.3.2 drops its transitive
fast-json-stable-stringify. npm run verify is green with no rule or
format fallout. maintain:outdated still flags @types/node as "reverted"
because DefinitelyTyped's latest dist-tag stays on the 22.x LTS series;
known false positive, advisory scan only.
 2026-09-16 07:31:49 +00:00
tmu b456a430a7 🚀 Release 0.1.7
CI / release-gate (push) Successful in 2s
Details
CI / build (push) Successful in 22s
Details
CI / maintain (push) Failing after 14s
Details
CI / publish (push) Failing after 15s
Details
2026-09-16 07:23:24 +00:00
tmu 36d8c4feae 🔀 Merge chore/resolve-finish-push-tension into main 2026-09-16 07:21:55 +00:00
tmu d646fd1ec4 ♻️ Let create:branch start from an ahead main 
`create:finish` leaves the merge local until `create:release` pushes it, so
`main` is routinely ahead of its upstream between a merge and a release. The
branch front door demanded an exact match and refused until it was pushed,
forcing a manual `git push` that the model deliberately keeps out of it.

Reject only a `main` that is behind its upstream — matching `create:finish`,
which already tolerates being ahead — and record why pushing from `finish` was
rejected instead. The push stays with `create:release`, so the merge remains
reviewable locally, and the known issue about the deadlock is gone.

Resolves: backlog task "Resolve the finish/push tension".
 2026-09-15 22:14:51 +00:00
tmu 177d63fa95 🔀 Merge chore/prune-backlog-and-changelog-rule into main
CI / release-gate (push) Successful in 2s
Details
CI / build (push) Successful in 20s
Details
CI / publish (push) Skipped
Details
CI / maintain (push) Failing after 14s
Details
2026-09-15 22:09:21 +00:00
tmu f6f820a648 📝 Require a changelog note before finishing a branch 
A merged branch must carry a final commit adding a short summary of the
work under [Unreleased] in CHANGELOG.md. create:release derives the bump
heuristic from that body, so notes have to exist before release day;
rationale in development/workflow.md.
 2026-09-15 22:08:08 +00:00
tmu c5cc903221 📝 Prune the backlog of closed tasks 
All completed and cancelled entries are implemented and reflected in the
docs, CI and changelog; only still-open tasks remain.
 2026-09-15 21:58:44 +00:00
30 changed files with 3024 additions and 607 deletions
Expand all files Collapse all files

No files matched your search

.gitignore
+2 -1
View File
@@ -10,5 +10,6 @@ coverage
!.vscode/extensions.json !.vscode/extensions.json
!.vscode/settings.json !.vscode/settings.json
!.vscode/tasks.json !.vscode/tasks.json
!.vscode/launch.json
.idea .idea
.DS_Store .DS_Store
.oxlintrc.json
+13 -2
View File
@@ -13,6 +13,8 @@
"eslint/no-undefined": "off", "eslint/no-undefined": "off",
"eslint/sort-keys": "off", "eslint/sort-keys": "off",
"eslint/id-length": "off", "eslint/id-length": "off",
"eslint/capitalized-comments": "off",
"eslint/no-ternary": "off",
"import/no-named-export": "off", "import/no-named-export": "off",
"eslint/one-var": "off", "eslint/one-var": "off",
"import/group-exports": "off", "import/group-exports": "off",
@@ -20,7 +22,8 @@
"eslint/sort-imports": "off", "eslint/sort-imports": "off",
"import/consistent-type-specifier-style": "off", "import/consistent-type-specifier-style": "off",
"unicorn/prefer-export-from": "off", "unicorn/prefer-export-from": "off",
"typescript/method-signature-style": "off" "typescript/method-signature-style": "off",
"typescript/promise-function-async": "off"
}, },
"options": { "typeAware": true }, "options": { "typeAware": true },
"env": { "builtin": true, "es2024": true, "node": true }, "env": { "builtin": true, "es2024": true, "node": true },
@@ -31,7 +34,9 @@
"no-unused-expressions": "off", "no-unused-expressions": "off",
"no-empty-file": "off", "no-empty-file": "off",
"import/no-nodejs-modules": "off", "import/no-nodejs-modules": "off",
"eslint/no-magic-numbers": "off" "eslint/no-magic-numbers": "off",
"unicorn/no-null": "off",
"typescript/no-floating-promises": "off"
} }
}, },
{ {
@@ -39,6 +44,12 @@
"rules": { "rules": {
"import/no-nodejs-modules": "off" "import/no-nodejs-modules": "off"
} }
},
{
"files": ["src/util/__tests__/**"],
"rules": {
"import/no-nodejs-modules": "off"
}
} }
], ],
"ignorePatterns": ["dist", "node_modules", "coverage"] "ignorePatterns": ["dist", "node_modules", "coverage"]
.vscode/extensions.json
Vendored
+1
View File
@@ -1,5 +1,6 @@
{ {
"recommendations": [ "recommendations": [
"connor4312.nodejs-testing",
"oxc.oxc-vscode", "oxc.oxc-vscode",
"streetsidesoftware.code-spell-checker", "streetsidesoftware.code-spell-checker",
"typescriptteam.native-preview", "typescriptteam.native-preview",
.vscode/launch.json
Vendored
+15
View File
@@ -0,0 +1,15 @@
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Debug current test file",
"runtimeExecutable": "node",
"runtimeArgs": ["--test", "--strip-types"],
"args": ["${file}"],
"cwd": "${workspaceFolder}",
"console": "integratedTerminal"
}
]
}
.vscode/settings.json
Vendored
+10
View File
@@ -1,4 +1,14 @@
{ {
"nodejs-testing.extensions": [
{
"extensions": ["mjs", "cjs", "js"],
"parameters": []
},
{
"extensions": ["ts"],
"parameters": ["--strip-types"]
}
],
"[typescript]": { "[typescript]": {
"editor.defaultFormatter": "oxc.oxc-vscode", "editor.defaultFormatter": "oxc.oxc-vscode",
"editor.formatOnSave": true "editor.formatOnSave": true
AGENTS.md
+7 -6
View File
@@ -9,7 +9,7 @@ first-action facts. Do not restate evolving prose here — it will drift.
- Project: F#-style pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim). - Project: F#-style pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim).
- **While iterating:** `npm run test` (`check:tsc` + the unit suite) for fast feedback on the files you changed. - **While iterating:** `npm run test` (`check:tsc` + the unit suite) for fast feedback on the files you changed.
- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong. - **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. **When you are looking for a symbol, reach for the LSP before `rg`/`grep`** — `lsp_references` / `lsp_find_symbol` / `lsp_definition` / `lsp_document_symbols` are semantic and cross-file, so they see shadowing, imports and overloads that a text search cannot; use `lsp_hover` to read inferred types on generic-heavy code. Use `rg` for what the LSP cannot see — doc prose, string literals, config, task lists, file discovery — and reconcile the two sets before editing (symbols from the LSP, strings and prose from `rg`). It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong.
- **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run. - **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run.
- **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit. - **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit.
- **Document decisions where the next maintainer will look:** rationale, rejected alternatives and known issues go in `development/<category>.md` (see [development/README.md](./development/README.md)); the actionable rule stays in [CONTRIBUTING.md](./CONTRIBUTING.md) and links to it. Write each fact once — never copy the rule into `development/` or the reason into `CONTRIBUTING.md` — and change both in the same commit when a rule changes. - **Document decisions where the next maintainer will look:** rationale, rejected alternatives and known issues go in `development/<category>.md` (see [development/README.md](./development/README.md)); the actionable rule stays in [CONTRIBUTING.md](./CONTRIBUTING.md) and links to it. Write each fact once — never copy the rule into `development/` or the reason into `CONTRIBUTING.md` — and change both in the same commit when a rule changes.
@@ -26,9 +26,10 @@ Don't silence the type system to force a green run. As an agent these are forbid
- `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error` - `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error`
- `// oxlint-disable` / `// oxlint-disable-next-line` - `// oxlint-disable` / `// oxlint-disable-next-line`
- editing `.oxlintrc.json` to silence a finding (e.g. turning `typescript/no-floating-promises` off)
- `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions) - `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions)
Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it. Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. Suppressions — a source `oxlint-disable` **or** a `.oxlintrc.json` entry — are a **human** last resort, not a tool for you. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it.
The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C <skipped-sha>`. The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C <skipped-sha>`.
@@ -42,7 +43,9 @@ Never start a long-lived / blocking process such as `npm run watch`. It runs unt
### Working on tasks ### Working on tasks
- **Task with subtasks** (a task that has indented children): create the branch with `npm run create:branch -- <prefix>/<desc>`, inferring the prefix from the task content (`feature/…` / `fix/…` / `chore/…`) — do not hand-write `git switch -c`, the command enforces the clean-tree / current-`main` / green-baseline precondition. Work on each subtask with commits, then present a concise handover for the user to review. Use this fixed shape: Every task — with or without subtasks — goes through the complete branching model:
- Create the branch with `npm run create:branch -- <prefix>/<desc>`, inferring the prefix from the task content (`feature/…` / `fix/…` / `chore/…`) — do not hand-write `git switch -c`, the command enforces the clean-tree / current-`main` / green-baseline precondition. Work with commits (each subtask gets one or more), then present a concise handover for the user to review. Use this fixed shape:
```md ```md
## Handover — <branch> ## Handover — <branch>
@@ -54,9 +57,7 @@ Never start a long-lived / blocking process such as `npm run watch`. It runs unt
Once the user has no further objections, merge back: `npm run create:finish` (on the branch — it merges `--no-ff`, runs `npm run verify`, and deletes the branch). The branching model is documented in [CONTRIBUTING.md § Branching model](./CONTRIBUTING.md#branching-model). Once the user has no further objections, merge back: `npm run create:finish` (on the branch — it merges `--no-ff`, runs `npm run verify`, and deletes the branch). The branching model is documented in [CONTRIBUTING.md § Branching model](./CONTRIBUTING.md#branching-model).
- **Leaf task** (no indented children): implement on the current branch and commit. Follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven) throughout.
In both cases, follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven). Each subtask gets one or more commits.
## Read these ## Read these
CHANGELOG.md
+46 -1
View File
@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased] ## [Unreleased]
## [0.6.0] - 2026-09-22
- add `getTaggedUnionMatcher` / `getTaggedUnionMatcherW` for discriminated unions
- rename the primitive matcher to primitive-union: `getMatcher` /
`getMatcherW` → `getPrimitiveUnionMatcher` / `getPrimitiveUnionMatcherW`, and
`src/primitive.ts` / `src/primitive.test.ts` → `src/primitive-union.*`
## [0.5.0] - 2026-09-21
- reject a fallback when the handler map already covers the universe
- allow boolean, null and undefined in the matcher universe
## [0.4.0] - 2026-09-20
- move the `_` fallback out of handlers
## [0.3.0] - 2026-09-18
- condensed primitive matcher factories down to 2 from formerly 4
- house shared test helpers under `src/util/__tests__/`
## [0.2.0] - 2026-09-16
- allow ternaries and lowercase comments in oxlint
- switch `src/primitive.ts` prose from block comments to line comments
- remove the template's `match`/`P` example modules and their documentation, and point `src/index.ts` at the primitive matchers
## [0.1.8] - 2026-09-16
- upgrade dependencies
- ignore `@types/node` in `maintain:outdated` (misleading `latest` dist-tag)
- require extremely concise prose in `development/`
## [0.1.7] - 2026-09-16
- require a short summary under `[Unreleased]` in the changelog before a branch is finished
- let `create:branch` start from a `main` that is ahead of its upstream, so a finished merge no longer blocks the next branch until it is pushed
## [0.1.6] - 2026-09-15 ## [0.1.6] - 2026-09-15
- restructure the documentation: README.md for users, CONTRIBUTING.md for contributors, and development/ for the decisions, rejected alternatives and known issues - restructure the documentation: README.md for users, CONTRIBUTING.md for contributors, and development/ for the decisions, rejected alternatives and known issues
@@ -37,7 +75,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- basic setup - basic setup
[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.6...main [Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.6.0...main
[0.6.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.5.0...0.6.0
[0.5.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.4.0...0.5.0
[0.4.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.3.0...0.4.0
[0.3.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.2.0...0.3.0
[0.2.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.8...0.2.0
[0.1.8]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.7...0.1.8
[0.1.7]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.6...0.1.7
[0.1.6]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.5...0.1.6 [0.1.6]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.5...0.1.6
[0.1.5]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.4...0.1.5 [0.1.5]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.4...0.1.5
[0.1.4]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.3...0.1.4 [0.1.4]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.3...0.1.4
CONTRIBUTING.md
+33 -9
View File
@@ -66,7 +66,21 @@ before the implementation. The loop is **type → red → green → refactor**:
4. **Refactor** — with the type system and the tests as the safety net, then 4. **Refactor** — with the type system and the tests as the safety net, then
`npm run verify` as the definition-of-done gate. `npm run verify` as the definition-of-done gate.
Every test pairs an `expectTypeOf(...)` with an `assert.*`; keep them together. Every test pairs an `expectTypeOf(...)` with an `assert.*`; keep them together
— including the expectations inside handler bodies, which pair with an
assertion on the value dispatch passed, not only the type it inferred (see
[development/testing.md § Handler arguments](./development/testing.md#handler-arguments)).
The autocomplete tests (`src/util/__tests__/lsp-completion.test.ts` for the
helper, `src/primitive-union.test.ts` for the matcher's popup) are the
exception —
the language server, not the type system, is the oracle (see
[development/testing.md § Autocomplete](./development/testing.md#autocomplete)).
Each test body follows **AAA (Arrange–Act–Assert)** with labeled blocks
separated by a blank line: `// Arrange` sets up the inputs (e.g. the matcher
factory), `// Act` exercises the subject once from them (not a second
throwaway call), `// Assert` holds every check — type expectations first,
runtime assertions last; an empty block drops its label (see
[development/testing.md § AAA ordering](./development/testing.md#aaa-ordering)).
Type-first is enforced structurally: `npm test` runs `check:tsc` before the Type-first is enforced structurally: `npm test` runs `check:tsc` before the
test runner, so a wrong type can never be papered over by a passing assertion. test runner, so a wrong type can never be papered over by a passing assertion.
Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the
@@ -144,7 +158,8 @@ reaches for by default:
[Script prefix convention](#script-prefix-convention). [Script prefix convention](#script-prefix-convention).
- **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The - **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The
trade-off must sit next to the code it silences. This is a _human_ last-resort trade-off must sit next to the code it silences. This is a _human_ last-resort
convention; agents must not add these — see convention; agents must not add one, nor edit `.oxlintrc.json` to silence a
finding (e.g. `typescript/no-floating-promises`) — see
[AGENTS.md § Never do](./AGENTS.md#never-do). (why: [AGENTS.md § Never do](./AGENTS.md#never-do). (why:
[development/tooling.md](./development/tooling.md#oxlint-disable-directives-live-next-to-the-code)) [development/tooling.md](./development/tooling.md#oxlint-disable-directives-live-next-to-the-code))
- **Don't put slow / network / whole-project scans in `check` or pre-commit.** - **Don't put slow / network / whole-project scans in `check` or pre-commit.**
@@ -164,11 +179,18 @@ reaches for by default:
- **There is no local `npm run publish`, and `publish:publint` / `publish:attw` - **There is no local `npm run publish`, and `publish:publint` / `publish:attw`
don't go in `check`.** (why: don't go in `check`.** (why:
[development/publishing.md](./development/publishing.md#ci-only-publishing)) [development/publishing.md](./development/publishing.md#ci-only-publishing))
- **A branch ends with a changelog note:** before `npm run create:finish`,
summarize the work under `[Unreleased]` in [CHANGELOG.md](./CHANGELOG.md).
(why:
[development/workflow.md](./development/workflow.md#changelog-notes))
- **A decision or its rationale belongs in `development/`, not here.** This file - **A decision or its rationale belongs in `development/`, not here.** This file
holds the actionable rule; `development/<category>.md` holds why, the rejected holds the actionable rule; `development/<category>.md` holds why, the rejected
alternatives and the known issues. When you change a rule, update its category alternatives and the known issues. When you change a rule, update its category
file in the same commit and cross-link the two. (why: file in the same commit and cross-link the two. (why:
[development/README.md](./development/README.md)) [development/README.md](./development/README.md))
- **Prose in `development/` is extremely concise.** When adding or changing a
decision, write fragments if needed — sacrifice grammar for concision. (why:
[development/README.md § Decision blocks](./development/README.md#decision-blocks))
## Branching model ## Branching model
@@ -180,9 +202,10 @@ request workflow on Gitea yet.
- **Branch naming:** `feature/<desc>` / `fix/<desc>` / `chore/<desc>` - **Branch naming:** `feature/<desc>` / `fix/<desc>` / `chore/<desc>`
- **Starting work:** `npm run create:branch -- <prefix>/<desc>`. It refuses, - **Starting work:** `npm run create:branch -- <prefix>/<desc>`. It refuses,
without changing anything, unless the working tree is clean, no without changing anything, unless the working tree is clean, no
merge/rebase/cherry-pick is in progress, `main` matches its upstream, and merge/rebase/cherry-pick is in progress, `main` is not behind its upstream
`npm run test` is green on `main`. The prefix is _your_ call, inferred from the (a local merge not yet pushed is fine — the push belongs to `create:release`),
task; the script validates it rather than guessing it. and `npm run test` is green on `main`. The prefix is _your_ call, inferred from
the task; the script validates it rather than guessing it.
- **Merging:** `npm run create:finish` (on the branch). It re-asserts the same - **Merging:** `npm run create:finish` (on the branch). It re-asserts the same
preconditions, merges `--no-ff`, runs `npm run verify`, and deletes the branch preconditions, merges `--no-ff`, runs `npm run verify`, and deletes the branch
only after the merge is green. The push is left to `create:release`, so the only after the merge is green. The push is left to `create:release`, so the
@@ -192,8 +215,7 @@ request workflow on Gitea yet.
- **Releases are NOT triggered by pushes.** Only the maintainer triggers a - **Releases are NOT triggered by pushes.** Only the maintainer triggers a
release; see [Publishing](#publishing). release; see [Publishing](#publishing).
Full rationale, including the front-door decisions and a known issue about Full rationale, including the front-door decisions:
`main` being ahead of its upstream between a merge and the next push:
[development/workflow.md § Branching model](./development/workflow.md#branching-model). [development/workflow.md § Branching model](./development/workflow.md#branching-model).
## Submitting changes ## Submitting changes
@@ -204,9 +226,11 @@ as a branch that is merged locally:
1. `npm run create:branch -- <prefix>/<desc>`. 1. `npm run create:branch -- <prefix>/<desc>`.
2. Commit your work (one or more commits, per the tests and style rules above). 2. Commit your work (one or more commits, per the tests and style rules above).
3. `npm run verify` — the definition of done. 3. `npm run verify` — the definition of done.
4. `npm run create:finish` to merge the branch into `main` and verify the 4. Add a changelog note under `[Unreleased]` (see
[Rules the tools don't enforce](#rules-the-tools-dont-enforce)).
5. `npm run create:finish` to merge the branch into `main` and verify the
result. result.
5. Present a handover for review. Once there are no further objections, the 6. Present a handover for review. Once there are no further objections, the
maintainer pushes. maintainer pushes.
When the project is promoted to GitHub, this step becomes a normal pull request When the project is promoted to GitHub, this step becomes a normal pull request
README.md
+18 -144
View File
@@ -2,34 +2,14 @@
Pattern matching for TypeScript/ESM environments (F#-style, not regex). Pattern matching for TypeScript/ESM environments (F#-style, not regex).
## Synopsis
```ts
import { match, P } from "tiny-pattern-ts";
const reply = (answer: "yes" | "no") =>
match(answer)
.with(P.literal("yes"), (): "agreed" => "agreed")
.with(P.literal("no"), (): "declined" => "declined")
.exhaustive();
reply("yes"); // "agreed"
```
## Description ## Description
`tiny-pattern-ts` gives TypeScript the shape of F#-style pattern matching: `tiny-pattern-ts` brings F#-style pattern matching to TypeScript. Patterns are
a value flows through a chain of patterns, the first one that matches runs its ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
handler, and the handler receives the value narrowed to that pattern's type. The composes the way any other guard does. It is deliberately not a regex engine and
"patterns" are ordinary objects whose `matches` method is a TypeScript type not a macro: there is no transpiler and no DSL to learn, and the type-level
guard, so narrowing composes the way any other guard does. contract is the feature — see [development/library.md](./development/library.md)
for the design decisions and [Caveats](#caveats) for the limits.
It is deliberately not a regex engine and not a macro. There is no transpiler
and no DSL to learn: `match(value)` returns a builder, `.with(pattern, handler)`
adds a case, and the chain ends in either `.exhaustive()` or `.otherwise(...)`.
The type-level contract is the feature — see
[development/library.md](./development/library.md) for the design decisions and
the known limitations.
## Requirements ## Requirements
@@ -39,128 +19,22 @@ the known limitations.
both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`. both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
- The package is **ESM-only** (no CommonJS shim). - The package is **ESM-only** (no CommonJS shim).
## Examples
### Literal matching and `exhaustive()`
`.exhaustive()` returns the union of the handler return types and throws if no
case matched. Annotate handler returns when you want literal types rather than
`string`:
```ts
type Answer = "yes" | "no";
const reply = (answer: Answer): "agreed" | "declined" =>
match(answer)
.with(P.literal("yes"), (): "agreed" => "agreed")
.with(P.literal("no"), (): "declined" => "declined")
.exhaustive();
reply("yes"); // "agreed"
```
`exhaustive()` checks at runtime, not at compile time — TypeScript does not force
every union member to have a case (see
[development/library.md](./development/library.md#exhaustive-is-a-runtime-check)).
Use `.otherwise(...)` when a fallback is wanted:
```ts
const label = (answer: Answer): string =>
match(answer)
.with(P.literal("yes"), () => "agreed")
.otherwise(() => "not agreed");
```
### Matching by `typeof`
`P.type<T>(name)` pairs an explicit type `T` with the runtime `typeof` name it
should test for:
```ts
const describe = (value: unknown): string =>
match(value)
.with(P.type<string>("string"), (s) => `string of length ${s.length}`)
.with(P.type<number>("number"), (n) => `number ${n.toFixed(2)}`)
.otherwise(() => "something else");
```
The supported names are `string`, `number`, `boolean`, `bigint`, `symbol`,
`undefined`, `object`, and `function`. `"object"` matches non-null objects and
functions; `"undefined"` compares against `undefined` directly.
### Structural matching and discriminated unions
`P.shape(shape, refine?)` checks that every key in `shape` exists on the value.
A value that is itself a matcher is applied, otherwise it is compared with
strict equality. To narrow to a concrete type, pass a `refine` type guard:
```ts
interface Circle {
readonly kind: "circle";
readonly radius: number;
}
interface Square {
readonly kind: "square";
readonly side: number;
}
type Shape = Circle | Square;
const area = (shape: Shape): number =>
match(shape)
.with(
P.shape({ kind: "circle" }, (v): v is Circle => "radius" in v),
(c) => Math.PI * c.radius ** 2,
)
.with(
P.shape({ kind: "square" }, (v): v is Square => "side" in v),
(s) => s.side ** 2,
)
.exhaustive();
```
Without `refine`, `P.shape` returns a matcher for the shape's own type, not the
narrowed one. Nested matchers can be used in the shape object, for example
`P.shape({ name: P.type<string>("string") })`.
### Custom guards with `when`
`P.when` takes a type guard and infers the narrowed type from it:
```ts
const toNumber = (value: unknown): number =>
match(value)
.with(
P.when((v): v is string => typeof v === "string"),
(s) => Number.parseInt(s, 10),
)
.otherwise(() => 0);
```
### Widening with `any`
`P.any<T>(predicate)` takes a plain boolean predicate and a declared type `T`,
for cases where the predicate cannot be written as a type guard:
```ts
const firstNumber = (items: readonly unknown[]): number | undefined =>
match(items)
.with(
P.any<readonly number[]>(
(v) =>
Array.isArray(v) &&
v.every((item) => typeof item === "number"),
),
(xs) => xs[0],
)
.otherwise(() => undefined);
```
## API ## API
Yet to be implemented Yet to be implemented
## Caveats
- **A value and its stringification collide.** Object keys stringify, so a
universe that mixes a member with the string it stringifies to — `1 | "1"`,
`true | "true"`, `null | "null"` — collapses to a single handler key and both
members are routed to it. Use one form or the other.
- **`symbol` and `bigint` are not supported.** A `symbol` brand is a
compile-time phantom with nothing to match at runtime, and a `bigint` is not a
valid property key; neither satisfies the matcher's universe constraint.
- **`NaN` and `-0` cannot be matched specifically.** They have no literal type,
so both stay part of `number`.
## License ## License
MIT © 2025 tmu. See [LICENSE](./LICENSE). MIT © 2025 tmu. See [LICENSE](./LICENSE).
backlog.tasks
+64 -55
View File
@@ -5,9 +5,18 @@ Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.
--- ---
Setup: Setup:
✔ Add gitea release page in CI @high @done ☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @low
✔ Manually verify the Gitea release page on a real tag push (needs main) @high @done (9/15/2026, 1:18:15 PM) ✔ straighten oxc rules @done
☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @high ✔ oxc forbids ternary => remove oxc rule @done
✔ oxc wants comments to start comments with a capital letter => remove oxc rule @done
✔ there already exists a /* */ block comment in primitive.ts, => change to multi-line comment @done
✔ Remove example code files and its documentation and its exports from index.ts @high @done
✔ remove src/match.ts and its documentation @high @done
✔ remove src/pattern.ts and its documentation @high @done
✔ remove src/index.test.ts and its documentation @high @done
✔ exports from `src/index.ts` should only be the public API surface @done
v1.0: v1.0:
☐ API surface is stable and fully typed ☐ API surface is stable and fully typed
@@ -15,59 +24,75 @@ v1.0:
☐ Document all exported types and functions ☐ Document all exported types and functions
☐ Add JSDoc for public APIs ☐ Add JSDoc for public APIs
☐ Test coverage meets threshold ☐ Test coverage meets threshold
☐ Achieve 100% branch coverage on `src/pattern.ts` ☐ Achieve 100% branch coverage on `src/primitive-union.ts`
☐ Achieve 100% branch coverage on `src/match.ts`
☐ Achieve 100% branch coverage on `src/index.ts` ☐ Achieve 100% branch coverage on `src/index.ts`
Bugs: Testing:
✔ Cover autocomplete with real completion test cases in the suite @medium @done
→ `src/util/__tests__/lsp-completion.ts` (`#test-utils/…`) is the helper; the suite asserts its labels (see development/testing.md § Autocomplete)
→ wire it into `node --test` so a test asserts the offered labels
→ note: `Parameters<typeof factory>[0]` resolves only the *last* overload; use `@ts-expect-error` call sites for factory negatives, not `not.toExtend<Parameters<…>>`
✔ Drive the LSP completion helper through the LSP protocol library instead of a hand-rolled JSON-RPC client @medium @done
✔ Add `vscode-languageserver-protocol` and record the tooling decision @done
✔ Rewrite `src/util/__tests__/lsp-completion.ts` onto `createMessageConnection` and typed requests @done
✔ Update `development/testing.md § Autocomplete` for the new client @done
✔ Run `npm run verify` and check the task off @done
☐ Test a literal union widened with `(string & {})` — `"red" | "green" | "yellow" | (string & {})` @medium
→ autocomplete should still offer the literals; arbitrary strings stay assignable and fall through to the fallback
☐ Type hole when using broad types like string as a universe @high
☐ handlers cannot be exhaustive, yet it is possible to not have a fallback
☐ one test even exploits this, I think for a negative test
☐ does the same type hole exist for tagged-union matchers or primitive-union matchers only?
Matcher:
✔ Clean up: adopt the 3-overload matcher (`src/prototype-ac2.ts`) and delete the prototypes @high @done
→ `getMatcher` / `getMatcherW`, each with overloads `ExhaustiveLoose` → `Fallback` → `Handlers` (order is load-bearing)
→ fold into `src/primitive.ts` / the public API; drop `src/prototype*.ts`
✔ `_` should receive only the unhandled `T` keys, not all of `T` @medium @done
→ the fallback is now a second argument: `(handlers, (s) => …)`, `s: Exclude<T, keyof handlers>`
✔ A fallback for an already-exhaustive handler map must be a compile error @medium @done
→ rejected by an F-bounded constraint on `Handled` (checked *after* inference); a conditional in the fallback parameter is evaluated too early and breaks contextual typing
✔ Implement matcher with similar API like matcher from primitive.ts @high @done
→ `getTaggedUnionMatcher` / `getTaggedUnionMatcherW`, curried on the discriminant key
→ fallback is the second argument; `_` removed
✔ Rename `primitive` to `primitive-union` and `getMatcher` to `getPrimitiveMatcher` @medium @done
→ `src/primitive.ts` / `src/primitive.test.ts` → `primitive-union.*`
→ `getMatcherW` → `getPrimitiveMatcherW` for symmetry with the tagged-union pair
→ update `src/index.ts`, `development/library.md` and any README references
→ shipped as `getPrimitiveUnionMatcher` / `getPrimitiveUnionMatcherW`; kept `Union` for symmetry with the tagged-union pair
☐ when using a union type as a property, the current behavior of tagged union matcher is
to pass never to handler parameters
→ new matcher function needed or can be fixed in tagged union matcher
☐ optional discriminant (`{ type?: "x" }`) is the same hole: the boolean/nullish change now admits the `undefined` tag, so the factory accepts the key, but `Extract<T, Record<K, V>>` still passes `never` to both the `x` and `undefined` handlers
Bugs:
✔ TS 7 LSP server logs `context canceled` on stderr at shutdown @done
→ `handleExit` returns `io.EOF`, cancelling the background context while `Session.updateWatches` is still in flight; the bare error is flushed to stderr and the server exits 1
→ close stdin after `shutdown` instead of sending `exit`; the server exits cleanly (code 0, no output), kill kept as a fallback
Enhancements: Enhancements:
✔ Allow boolean literals in primitive union patterns (e.g. `true: () => "yes"`) @medium @done
✔ Are there other primitive types that should be supported in union patterns? (e.g. `bigint`, `symbol`) @medium @done
→ added boolean, null and undefined; rejected `symbol` (compile-time brand, nothing at runtime) and `bigint` (not a property key)
✔ Allow boolean, null and undefined discriminant values in tagged-union patterns @medium @done
→ moved the `PatternKey` / `PatternParam` projection to `matcher-shared.ts` and keyed the tagged-union handler map through it; see development/library.md § Tagged-union matcher
Documentation: Documentation:
✔ Clean up CONTRIBUTING.md and README.md, create docs @done ☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
✔ Review existing documentation for accuracy and completeness @done → previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
✔ README.md should be the main entry point for users, and CONTRIBUTING.md should be the main entry point for contributors @done → previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
✔ Move the decisions, shortcomings and known issues out of README.md and CONTRIBUTING.md @done
✔ Decided: category files under development/ (one per area), not ADRs. Each decision is a block with #### Decision (YYYY-MM) / #### Why / #### Rejected / #### Known issue; rationale in development/README.md @done
✔ have a look at other well known repositories for inspiration on how to structure the docs @done
✔ often times a docs folder is used, but this usually contains further user of the library documentation, that is deployed to a website. Deployment is out of scope for now @done
✔ make sure to preserve that information in the new docs @done
✔ development/README.md - index and decision-block convention @done
✔ development/workflow.md - branching, script prefixes, feedback tiers, commits @done
✔ development/tooling.md - toolchain decisions and editor setup @done
✔ development/testing.md - type-driven testing @done
✔ development/ci.md - pipeline, runner image, coverage serving @done
✔ development/publishing.md - release and npm publishing @done
✔ development/library.md - public API design and its limitations @done
✔ README.md @done
✔ I really like the order perl documentation does it: name with a single line description, version, Synopsis, Description, examples, API reference, license @done
(example: https://metacpan.org/pod/Scalar::Util)
✔ should include a clear description of the library, its purpose, and how to use it @done
✔ Add usage examples to README.md @done
✔ version needs to be kept in sync with package.json in release.sh @done
✔ Not every section in current README fits in the above order, so put them in another file @done
✔ CONTRIBUTING.md @done
✔ should include instructions for how to contribute to the project, including how to set up a development environment, run tests, and submit pull requests @done
✔ should include guidelines for code style and formatting and a hint, that vscode extensions are suggested from .vscode/extensions.json @done
✔ Not every section in current CONTRIBUTING.md fits in, so put them in another file @done
☐ Create `examples/` directory with runnable snippets ☐ Create `examples/` directory with runnable snippets
☐ Add comparison section vs. other TS pattern-matching libs in Readme.md ☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
☐ Write migration guide for users coming from discriminated unions ☐ Write migration guide for users coming from discriminated unions
☐ Create backlog tasks for implementation ☐ Create backlog tasks for implementation
✔ Document the matcher design paths in `development/` — union vs overload merge, inferred universe (`NoInfer`), conditional `RequireKeys`, cases-first — and why each was abandoned @done
☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API ☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API
Workflow: Workflow:
☐ Resolve the finish/push tension: `create:finish` leaves `main` ahead of its upstream while `create:branch` refuses until `main` matches upstream — decide whether `finish` should push or `branch` should compare only `BEHIND` (see development/workflow.md) ✔ Resolve the finish/push tension: `create:finish` leaves `main` ahead of its upstream while `create:branch` refuses until `main` matches upstream — decide whether `finish` should push or `branch` should compare only `BEHIND` (see development/workflow.md) @done
Maintenance: Maintenance:
☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low ☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low
✔ Add a minimal dir-listing webserver to the gitea docker setup (e.g. caddy `file_server browse` reusing the existing reverse proxy, or any single-binary static server, lipanski/docker-static-website) @done (9/13/2026, 9:02:37 PM)
✔ drop the `actions/upload-artifact` coverage step in favour of the shared-dir layout @done (9/13/2026, 10:37:22 PM)
☐ Explore serving coverage for non-tag pushes (e.g. `main/coverage`, PR previews) @low ☐ Explore serving coverage for non-tag pushes (e.g. `main/coverage`, PR previews) @low
✔ Manually verify the coverage was created on a real tag push (needs main) @low @done (9/14/2026, 1:55:03 PM)
→ design: no deploy step in CI; the webserver just exposes the shared directory (decided over Gitea Pages / Codecov — neither confirmed available/ wanted) → design: no deploy step in CI; the webserver just exposes the shared directory (decided over Gitea Pages / Codecov — neither confirmed available/ wanted)
☐ serve docs over self hosted server @low ☐ serve docs over self hosted server @low
☐ Add a minimal dir-listing webserver to the gitea docker setup for serving docs (reuse existing reverse proxy) ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving docs (reuse existing reverse proxy)
@@ -77,19 +102,3 @@ Maintenance:
☐ Add a minimal dir-listing webserver to the gitea docker setup for serving landing page (reuse existing reverse proxy) ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving landing page (reuse existing reverse proxy)
☐ CI writes landing page to a shared volume keyed by project + tag (e.g. `/landing/tiny-pattern-ts/<tag>/`) ☐ CI writes landing page to a shared volume keyed by project + tag (e.g. `/landing/tiny-pattern-ts/<tag>/`)
☐ Browse to `…/tiny-pattern-ts/index.html` in the browser ☐ Browse to `…/tiny-pattern-ts/index.html` in the browser
✔ Stop Gitea CI re-downloading Node on every job @done
✔ Share the warm npm cache with the publish job @done
✔ Bake Node into the CI job image (docker/Dockerfile, container.image in ci.yml) @done
✔ Build/push gitea.e1nsnull.de/tmu/act-ci:26.8.2 and confirm setup-node skips the download @done
✔ Write the `<version>/x64.complete` marker — actions/tool-cache ignores a bare directory, so the probe missed and the download continued @done
✔ Log tool-cache state from the job container to find it (temporary, removed once understood) @done
✔ Guard the invariant in CI (`Assert the baked tool cache is present`) @done
✘ Enable force-pull for the runner so a changed act-ci image is never missed @low @cancelled
→ decided against: it is acceptable to miss a runner-side image change, and the image is only rebuilt on a Node bump, which changes the tag anyway. A Dockerfile-only change re-pushed under an unchanged tag is a known issue with a manual `docker rmi` workaround (see development/ci.md).
✔ Improve CI publish @done
✔ Check whether publish job is only run on tags, if not, guard it @done
✔ Gate only single steps @done
✔ Do not publish to npm, if NPM_TOKEN is not set (e.g. PRs from forks) @done
✔ Do not publish to Gitea — uses the run's automatic `github.token`, so no secret gate is needed @done
✔ Otherwise run the steps @done
✔ Fail the job unless both the Gitea release and npm publish succeeded @done
cspell.json
+2 -1
View File
@@ -42,7 +42,8 @@
"bestikk", "bestikk",
"silverwind", "silverwind",
"idris", "idris",
"todotasks" "todotasks",
"connor"
], ],
"ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"] "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
} }
development/README.md
+3
View File
@@ -66,6 +66,9 @@ of downloading per job.
goes under a `## Known issues` section at the end of the file. goes under a `## Known issues` section at the end of the file.
- Replace a superseded decision in place rather than archiving it; git history - Replace a superseded decision in place rather than archiving it; git history
is the archive. is the archive.
- Terse is the point: humans skim and agents imitate the style already in the
file, so verbosity compounds edit over edit. Grammar loses to density here on
purpose.
## Adding to these docs ## Adding to these docs
development/library.md
+193 -1
View File
@@ -3,4 +3,196 @@
The type-level design of the public API and the limitations it carries. The The type-level design of the public API and the limitations it carries. The
user-facing reference is [README § API](../README.md#api). user-facing reference is [README § API](../README.md#api).
Currently the library is placeholder code. The matchers are implemented in `src/primitive-union.ts` (`getPrimitiveUnionMatcher` /
`getPrimitiveUnionMatcherW`) and `src/tagged-union.ts` (`getTaggedUnionMatcher` /
`getTaggedUnionMatcherW`), re-exported from `src/index.ts`; the rest of the
library is placeholder code.
## Matcher shape
#### Decision (2026-09)
A factory takes the universe and returns a builder; the builder takes a handler
map and an optional fallback:
```ts
const matcher = getPrimitiveUnionMatcher<"a" | "b">()({ a: (s) => …, b: (s) => … });
const fallback = getPrimitiveUnionMatcher<"a" | "b" | "c">()({ a: (s) => … }, (s) => …);
```
Exhaustive or fallback is decided **at the call site**, by whether the second
argument is present. The fallback's parameter is the remainder
`Exclude<T, keyof Handled>`. Only the return-strictness axis remains, so there
are two factories:
- `getPrimitiveUnionMatcher` — one common `R`; the fallback must fit it;
- `getPrimitiveUnionMatcherW` — the union `PatternReturns<Handled> | R`.
Each factory is two overloads whose order is load-bearing:
1. `Handlers<T, R>` — the exhaustive form, and the contextual type of the
handler-map popup;
2. `Handled extends Exact<Partial<Handlers<T, R>>, Handled>` intersected with
`MustBePartial<T, Handled>`, plus `Fallback<T, Handled, R>` — a partial
handler map plus the fallback, rejected when the map already covers `T`.
#### Why
- **The fallback is an argument, not a property.** TypeScript fixes a property's
contextual type before it infers its sibling keys, so `_: (s) => …` in the
handler map can only see all of `T`, never `Exclude<T, keyof Handled>`. A later
argument is contextually typed from inference on an earlier one, so the split
is what makes the remainder expressible.
- **The redundant-fallback guard is an F-bounded constraint.** A map that
already covers `T` plus a fallback is rejected by folding
`MustBePartial<T, Handled>` into `Handled`'s own constraint. The guard is
checked _after_ `Handled` is inferred, so the contextual pass that types the
handler callbacks survives. The obvious conditional
`Exclude<T, keyof Handled> extends never ? …` in the fallback's parameter
type is evaluated while `Handled` is still its constraint and rejects every
partial map whose callbacks are context-sensitive.
- **Overload order keeps both messages.** #1 supplies the contextual type
(`a, b, c`); #2 accepts a partial map once a fallback is present, so its popup
is optional (`a?, b?, c?`). A gap without a fallback is reported against #1.
- **`R` needs an inference site.** `R` inside the `Exact<…>` constraint is not
one, so `handlers: Handled & Partial<Handlers<T, R>>` re-adds it; without that
`R` collapses to `unknown` when the handler params are inferred.
- **`Exact` restores the excess-property check.** TypeScript skips it for a
generic constraint, so without `Exact` the handler map accepts keys outside
`T`.
- Two factories, not four: the fallback is an argument, not a separate API.
#### Rejected
- **Single-object `_`** (the former shape). `_` sees only all of `T`; the
remainder is not expressible there, and an exhaustive map plus `_` was
accepted.
- **Curried handlers-first** — `(handlers)(fallback)`. Rejected: two calls for
the common case. It is not needed for the redundant-fallback guard, which the
F-bounded constraint already provides (see Why).
- **`this` / HKT self-reference.** `this` is post-construction (method bodies,
return positions); a parameter's contextual type is pre-construction.
`keyof this` in an interface method is the interface, not the literal.
- **Variance / `const` type parameters / `NoInfer` / `unique symbol` brands /
defaulted type-param guards.** None change inference or evaluation order;
`in`/`out` on the handler map broke contextual typing outright. `NoInfer`
specifically leaks into the emitted `.d.ts`, raising the consumer floor to
TypeScript 5.4 (README promises `>= 5.0`).
- **Union merge**, **overload merge with only the exhaustive arm last**,
**inferred universe**, **conditional `RequireKeys`**, **cases-first curried** —
decided against while the API was single-object; their reasons (reported
near-miss member, no `_` in the exhaustive popup, `NoInfer`/floor, `keyof P`
counts optional keys, not pipe-friendly) hold where they still apply.
#### Known issue
- `PatternReturns` must be
`ReturnType<Extract<ValueOf<P>, (...args: never[]) => unknown>>` so it survives
the closed, partly-optional `P` constraints.
- `Parameters<typeof factory>[0]` resolves only the **last** overload, so it is
not a sound "rejected" oracle for a factory. Factory-negative tests use
`@ts-expect-error` call sites (the test file only — the general ban stands).
## Shared internals
#### Decision (2026-09)
`src/matcher-shared.ts` holds the seven universe-agnostic pieces both matchers
use: `UnaryFn`, `PatternReturns`, `RedundantFallback`, `HandlerMap`, the shared
`Matchable` universe, and the `PatternKey` / `PatternParam` key projection.
#### Why
- `RedundantFallback`'s property name is the diagnostic, so one definition
keeps the two matchers' message from drifting; the other pieces appear
verbatim in both public signatures or are the same projection over each
matcher's universe.
- **`Matchable` is one definition, not two.** The primitive-union matcher's
universe and the tagged-union matcher's allowed `Tag` values are the same set,
so aliasing them keeps the two matchers from drifting apart on what they
accept (`symbol`/`bigint` rejected once).
#### Rejected
- **A generic `Matcher<Universe>` over the interface pair, `Handlers`,
`Fallback` and `MustBePartial`.** Each is built from its own universe
(`Tags`/`MapTaggedUnion` vs the primitive values); abstracting over the
F-bounded `Handled` constraint that makes the remainder work risks the
contextual typing it exists to preserve. `Matchable` and the `PatternKey` /
`PatternParam` projection are the pieces both universes genuinely share.
## Tagged-union matcher
#### Decision (2026-09)
`getTaggedUnionMatcher` / `getTaggedUnionMatcherW` mirror the primitive-union pair
with one extra curried step for the discriminant key:
```ts
type Shape =
| { kind: "circle"; radius: number }
| { kind: "square"; side: number };
const area = getTaggedUnionMatcher<Shape>()("kind")({
circle: (s) => Math.PI * s.radius ** 2,
square: (s) => s.side ** 2,
});
const fallback = getTaggedUnionMatcher<Shape>()("kind")(
{ circle: (s) => … },
(s) => …, // s: { kind: "square"; side: number }
);
```
The key is a separate call because `K` is inferred from its literal argument and
`T` is fixed by the first factory; one call could not infer both.
`Discriminated<T>` restricts the key to properties whose values are tags.
#### Why
- **Same fallback/remainder machinery as the primitive-union matcher.** `HandledMembers`
maps the handled tags to their members and `Exclude<T, …>` is the fallback's
parameter; the redundant-fallback guard is the same F-bounded constraint. Only
the "universe" changes — `T`'s members instead of primitive values.
- **`T extends object`, not `Record<PropertyKey, unknown>`.** An `interface` has
no implicit index signature, so the `Record` constraint would reject
interface-based unions. The runtime reads the tag off `object` with one
assertion, the tagged twin of the primitive-union dispatch's `shape as string | number`.
- **`MapTaggedUnion` distributes with `Extract`.** A duplicated tag yields a
union of members instead of dropping one.
- **A `boolean` / `null` / `undefined` tag goes through the shared
`PatternKey` / `PatternParam` projection.** `Discriminated` admits those tags
(they are in `Tag`), but they cannot key a mapped type, so the handler map is
keyed by the stringified form (`true` → `"true"`) and `PatternParam` inverts
it to recover the member. This is the same projection the primitive-union
matcher uses over its universe, which is why it lives in `matcher-shared.ts`.
#### Known issue
- A member's tag must be unique across the union; two members with the same tag
collapse to a union under one handler. The same holds for a tag colliding with
its stringification (`true | "true"`) — see [README § Caveats](../README.md#caveats).
## Primitive universe
#### Decision (2026-09)
The universe (`Matchable`) is `string | number | boolean | null | undefined`,
with `boolean` admitted as `true | false`.
`boolean`/`null`/`undefined` are not property keys, so handler-map keys are a
projection (`PatternKey`: each member stringified) and `PatternParam` inverts
it, so callbacks receive the real member (`true`, not `"true"`). The popup
offers `true`, `false`, `null`, `undefined` by name (verified over LSP). The
same projection is shared with the tagged-union matcher; see
§ Tagged-union matcher.
#### Why
- Runtime dispatch indexes with the raw `shape`; `handlers[true]` coerces to
`"true"` at runtime exactly as `String` would. The `shape as string | number`
assertion only placates `TS2538` and buys the number fast path (an explicit
`String()` defeats V8's numeric-key path: measured ~2× on number-keyed
dispatch).
- `symbol`/`bigint`/`NaN`/`-0` are rejected, and a member colliding with its
stringification is unguarded: user-facing, stated once in
[README § Caveats](../README.md#caveats).
development/testing.md
+170 -7
View File
@@ -27,19 +27,182 @@ before the implementation.
- Runtime-first (classic red/green): it verifies the value, not the contract, - Runtime-first (classic red/green): it verifies the value, not the contract,
and the contract is the product. and the contract is the product.
- Testing the type only: it would not catch handler wiring, `exhaustive()` - Testing the type only: it would not catch handler dispatch or the `_`
throwing, or the `otherwise` fallback (see `src/index.test.ts`). fallback (see `src/primitive-union.test.ts`).
The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are in The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are
in
[CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands). [CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
`c8` uses V8 coverage, so the `--strip-types` source is instrumented without a `c8` uses V8 coverage, so the `--strip-types` source is instrumented without a
build step, and the runner relies on the `.ts` import-extension convention (see build step, and the runner relies on the `.ts` import-extension convention (see
[tooling.md](./tooling.md#source-imports-use-ts-extensions)). [tooling.md](./tooling.md#source-imports-use-ts-extensions)).
## Handler arguments
#### Decision (2026-09)
A handler's `expectTypeOf(shape)` is always paired with an assertion on the
argument `dispatch` actually passed: `assert.equal` where the handler runs for
one shape, `assert.ok(s === … || s === …)` over the set a `_` fallback accepts
(`assert` is imported as `strict`, so each comparison is `Object.is`). Where a
test should also prove that the _exact_ value reached the handler unchanged,
the fallback returns the shape verbatim and the call site asserts it.
#### Why
- The parameter's type is what the compiler inferred from the pattern; the
argument is what the runtime passed. Only the second can drift, and the keys
whose property name differs from their value (`true`, `null`, `1`) are
exactly where it can — see [library.md](./library.md).
- `String(shape)` at the call site keeps every type expectation and every
return-value assertion green; the argument assertions fail (10 of the 33
tests). Without them the suite never looks at the passed argument.
- Returning the shape verbatim costs a widening pattern nothing: the remainder
type joins the union of handler returns in place of a marker literal, so the
test still shows the widening it is named for.
#### Rejected
- A recorded `unknown[]` of every fallback call compared with `deepEqual`:
strong, but it couples the assertion to call order, and the sink sits three
blocks away from the value it observes.
- `typeof` checks: they cannot separate `2` from its key text `"2"`, which is
the drift a fallback with a numeric remainder can hit.
- One expected value asserted inline in a fallback: its argument is a _set_ of
shapes, so only the disjunction holds on every call.
## AAA ordering
The rule is in
[CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
#### Decision (2026-09)
Test bodies read arrange → act → assert: inputs (the factory) set up first, the
subject exercised once from them, all checks last — types then runtime. The
blocks are labeled with `// Arrange` / `// Act` / `// Assert` comments and
separated by a blank line; an empty block drops its label.
#### Why
- Interleaved setup/checks hide what runs vs. what is observed; the eye
re-reads the block to find the seams.
- A factory built mid-test invites a second throwaway call of the subject;
arranging it once makes the positive construction and the negative
`Parameters<…>` check share one source of truth.
- Labels make the seams explicit, not inferred — grep-able and reviewable
without reading the statements.
#### Rejected
- Unlabeled ordering (bare blank lines): the seams still have to be found by
reading; the labels cost nothing.
## Test helpers
The rule is enforced by `import/no-relative-parent-imports`; this section records
why the mechanism is shaped like this.
#### Decision (2026-09)
A shared test helper — code that scattered `*.test.ts` files import to do their
testing — lives under `src/util/__tests__/` and is addressed by the
`#test-utils/…` self-reference (`package.json#imports`:
`"#test-utils/*": "./src/util/__tests__/*"`), never by a relative path:
```ts
import { LspSession } from "#test-utils/lsp-completion.ts";
```
#### Why
- The lint rule bans upward (`../`) imports, and a cross-cutting helper can
always be placed above _some_ scattered consumer, wherever it goes. Name
beats path: a `#test-utils/…` specifier has no direction, so the rule never
fires and file moves only touch the one mapping in `package.json`.
- `#…` is Node's reserved prefix for _private_ subpath imports: publishing
`package.json` leaks nothing and resolves nothing for consumers.
- `__tests__` as the folder name is not about tests living there; it is the
directory pattern `tsconfig.build.json` already excludes, so a helper can
never be emitted into `dist/` and shipped by accident.
- Node's own resolver handles `#…` under `--strip-types`, and `tsc` resolves it
via the same `imports` field — one mechanism for runtime and type gate, no
loader needed.
- The helper uses `node:` builtins (it drives a language server), so
`import/no-nodejs-modules` is off for `src/util/__tests__/**` in
`.oxlintrc.json` — the same exception the `scripts/**` scope carries.
- Helpers carry no library coupling: their tests probe in-memory documents
whose contextual types are written inline, so only the helper's own contract
(marker handling, position, label extraction) is under test. A test that
asserts a _matcher's_ popup belongs with the matcher.
#### Rejected
- A helper beside the tests (`src/util/test.ts`, flat `src/`): composes only
while `src/` stays flat; the first nested test reaching it reintroduces the
banned upward import.
- Bare `~/…` specifier: not valid in `imports` (keys must start with `#`) —
resolution fails at runtime with `ERR_MODULE_NOT_FOUND`. A `#~/…` “home”
shorthand was dropped in review; `#test-utils/…` states what it is.
- tsconfig `paths` alias: resolves for `tsc` but not for plain
`node --test --strip-types` (no loader hook), breaking the fast tier.
- Turning `import/no-relative-parent-imports` off for test files: the rule
still guards non-test helpers importing each other, and the exemption is
only needed for the one specifier the mapping already solves cleanly.
## Autocomplete
#### Decision (2026-09)
Completion is verified by driving the repo's own language server
(`tsc --lsp --stdio`, the same server pi's LSP extension talks to) through
the test helper `#test-utils/lsp-completion.ts`
(`src/util/__tests__/lsp-completion.ts`), not through the type system:
```sh
node --strip-types src/util/__tests__/lsp-completion.ts <file> [<marker>]
```
The script prints the labels the server offers at a `/*COMPLETE*/` marker inside
`<file>` (the marker is stripped before the document is sent). Its `LspSession`
is imported by `src/util/__tests__/lsp-completion.test.ts` — which tests the
helper itself against inline documents, never the library's code — and by
`src/primitive-union.test.ts`, where the same probe asserts the matcher's popup;
the CLI is for manual inspection.
#### Why
- Completion is a contextual-type property: it depends on which overload
signature TypeScript picks for the object literal, and no type-level assertion
observes that.
- `Parameters<typeof factory>[0]` resolves only the _last_ overload, so it is
not the popup's contextual type either — see
[library.md § Matcher shape](./library.md#matcher-shape).
- The server is the only ground truth; the script reproduces what the editor
shows.
#### Rejected
- **`expect-type` would not work**: there is no operator for “the popup offers
these labels”. `toExtend` / `toEqualTypeOf` test assignability and cannot say
which overload supplied the contextual type.
- **Checking by hand in the editor**: not reproducible in review or by an agent.
- **`@ts-expect-error` at a completion position**: it asserts the absence of a
compile error, not the presence of specific labels.
#### Known issue
- Each test spawns its own `tsc` server so the tests share no state and pass in
any order; the file is an integration test (~1.6 s) that needs `node_modules`.
`didOpen` is handled in order before the completion request, so no settle
delay is needed.
- The server answers some requests with a string id (`client/registerCapability`);
the client must tolerate `string | number` ids or the server stalls.
## Known issues ## Known issues
- The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so - The type-aware linter misidentifies `expectTypeOf()` as a floating promise.
`src/index.test.ts` carries a file-level `oxlint-disable It is a known false positive, so `typescript/no-floating-promises` is off for
typescript/no-floating-promises` with an explanatory comment. It is a known `**/*.test.ts` in the `.oxlintrc.json` override rather than repeated as a
false positive, not a rule worth disabling project-wide (see file-level header (see
[tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)). [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).
development/tooling.md
+96 -9
View File
@@ -24,6 +24,8 @@ in [package.json](../package.json).
- **@spences10/pi-lsp** — read-only LSP code intelligence for AI agents - **@spences10/pi-lsp** — read-only LSP code intelligence for AI agents
(project-local `.pi/settings.json`); talks to this repo's TypeScript 7 via (project-local `.pi/settings.json`); talks to this repo's TypeScript 7 via
`tsc --lsp --stdio`. `tsc --lsp --stdio`.
- **vscode-languageserver-protocol** — LSP client and protocol types for the
autocomplete test helper (`src/util/__tests__/lsp-completion.ts`).
When each runs is in When each runs is in
[CONTRIBUTING.md § Feedback tiers](../CONTRIBUTING.md#feedback-tiers). [CONTRIBUTING.md § Feedback tiers](../CONTRIBUTING.md#feedback-tiers).
@@ -104,24 +106,55 @@ Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
#### Decision (2026-09) #### Decision (2026-09)
Known type-aware false positives are silenced with source-level `oxlint-disable` A type-aware rule that false-positives **at one site** is silenced with a
directives (see `src/pattern.ts`, `src/match.ts`, `src/index.test.ts`), not with source-level `oxlint-disable` directive (see `src/primitive-union.ts`). A rule that is
rules disabled in `.oxlintrc.json`. wrong for a whole **file class** is turned off in a `.oxlintrc.json` `overrides`
entry instead — e.g. `typescript/no-floating-promises` (synchronous
`expectTypeOf` reads as an unhandled promise) and `unicorn/no-null` (intentional
`null` inputs) for `**/*.test.ts`. The same exemption is not repeated as a
file-level header in every affected file.
#### Why #### Why
- The disable sits next to the code it silences, visible to anyone reading the - A one-site disable sits next to the code it silences, visible to anyone
source. reading the source, and the rule stays on everywhere else.
- A file-class rule is a property of the file class, not of one line; the
override states it once, where the rest of the file-class config lives.
#### Rejected #### Rejected
- A project-wide disable in `.oxlintrc.json`: it hides the suppression from the - A project-wide disable in `.oxlintrc.json` for a one-site false positive: it
reader of the affected code. hides the exemption from the reader of the affected code and switches the rule
off repo-wide for a one-site problem.
- A repeated file-level `oxlint-disable` header for a file-class false positive:
the copies drift and scatter one config decision across the tree.
#### Known issue #### Known issue
- A source-level disable is a _human_ last resort. AI agents must not add one; - Both placements are _human_ last resorts. AI agents must neither add a source
they fix the type at its root (see [AGENTS.md § Never do](../AGENTS.md#never-do)). disable nor edit `.oxlintrc.json`; they fix the type at its root (see
[AGENTS.md § Never do](../AGENTS.md#never-do)).
### Unwanted stylistic rules are turned off in the config
#### Decision (2026-09)
A stylistic rule the project rejects is `"off"` in the `.oxlintrc.json` `rules`
map, not silenced at a use site. Current entries: `eslint/capitalized-comments`
(comments may start lowercase) and `eslint/no-ternary` (ternaries are allowed),
joining the oxfmt-superseded rules already off.
#### Why
- The rule is wrong for the whole project, not mis-firing at one site, so there
is no line to annotate.
- Keeping the two mechanisms separate keeps a source-level `oxlint-disable`
meaningful: it marks a lone exception.
#### Rejected
- A source-level `oxlint-disable` per use: the same exemption repeated at every
site, and oxfmt can move the site.
### `check:tsc` runs first ### `check:tsc` runs first
@@ -163,6 +196,28 @@ rules disabled in `.oxlintrc.json`.
are part of the public API. are part of the public API.
- The narrower scope keeps the signal high without config-file boilerplate. - The narrower scope keeps the signal high without config-file boilerplate.
### `maintain:outdated` ignores `@types/node`
#### Decision (2026-09)
Pass `--ignore-packages @types/node`.
#### Why
- DT pins `@types/node`'s `latest` dist-tag to LTS (22.x); current-line types
ride other tags. Scan sees latest < installed — permanent "reverted", exit
1, zero signal. `--ignore-pre-releases` no help: 22.20.3 is stable.
#### Rejected
- `--types major,minor,patch`: hides real reverted reports elsewhere.
- `@types/node@26.*`: tag stays wrong across majors; un-pin per bump = ritual.
#### Known issue
- A genuinely behind `@types/node` goes unreported; match it to
`.node-version` by hand.
### `attw` targets ESM-only ### `attw` targets ESM-only
#### Decision (2026-09) #### Decision (2026-09)
@@ -202,6 +257,38 @@ project.
- The same script works by hand (whole project) and staged (scoped), so there is - The same script works by hand (whole project) and staged (scoped), so there is
no second command to maintain. no second command to maintain.
## Language server tooling
### `vscode-languageserver-protocol` backs the autocomplete helper
#### Decision (2026-09)
The autocomplete helper (`src/util/__tests__/lsp-completion.ts`) drives
`tsc --lsp --stdio` through `vscode-languageserver-protocol`'s
`createMessageConnection` and its typed request / notification objects, instead
of a hand-rolled JSON-RPC client.
#### Why
- Framing, `Content-Length` parsing, the pending-request map and server-request
dispatch are protocol plumbing the helper only reimplemented; the official
client owns them and tolerates the server's `string | number` ids.
- `InitializeRequest`, `CompletionRequest`, `DidOpenTextDocumentNotification`,
… carry their parameter and result types, so `CompletionList` / `CompletionItem`
replace the helper's ad-hoc shape guards.
- The `./node` entry re-exports `vscode-jsonrpc/node`, so one devDependency
supplies both the transport and the protocol types. It is test-only and never
ships (`files` publishes `dist/` only).
#### Rejected
- `vscode-languageclient`: the editor-side client with a full feature registry
— far more than a test helper needs.
- Generic JSON-RPC (`jsonrpc-lite`, `jayson`): still no LSP types, so they
replace framing only and leave the typed protocol surface unimplemented.
- Keeping the hand-rolled client: the low-level shape is the maintenance cost
the helper exists to remove, and it must be re-audited against the server.
## Editor and agent tooling ## Editor and agent tooling
### VSCode integration ### VSCode integration
development/workflow.md
+35 -5
View File
@@ -26,7 +26,10 @@ plus hand-written `git`.
gate is not paid on an ineligible tree. gate is not paid on an ineligible tree.
- The merge half owns the post-merge `npm run verify`, so a merge cannot land - The merge half owns the post-merge `npm run verify`, so a merge cannot land
unverified. The push stays with `create:release` so the merge is reviewed unverified. The push stays with `create:release` so the merge is reviewed
locally first. locally first; `main` is therefore routinely ahead of its upstream between a
merge and the release that ships it. `create:branch` requires only that `main`
is not _behind_ — matching `create:finish`, which tolerates the local merge and
fast-forwards over a remote one — rather than an exact match.
- Every failure is non-mutating except the baseline test, which runs on `main` - Every failure is non-mutating except the baseline test, which runs on `main`
after switching there: a red `main` restores the branch you started on, and a after switching there: a red `main` restores the branch you started on, and a
merge conflict aborts back to the feature branch rather than stranding a merge conflict aborts back to the feature branch rather than stranding a
@@ -42,12 +45,39 @@ plus hand-written `git`.
can run from a dirty tree. can run from a dirty tree.
- Fast-forward instead of `--no-ff`: `--no-ff` keeps each unit of work visible - Fast-forward instead of `--no-ff`: `--no-ff` keeps each unit of work visible
in `git log`. in `git log`.
- Pushing from `create:finish` to keep `main` level with its upstream: it would
trade the local review the push waits for for a network side effect, and a
failed push would leave the merge landed but unpublished.
#### Known issue ## Changelog notes
- `create:finish` does not push, so `main` is ahead of `origin/main` between a The rule is in
merge and the next push. `create:branch` requires `main` to match its upstream [CONTRIBUTING.md § Rules the tools don't enforce](../CONTRIBUTING.md#rules-the-tools-dont-enforce).
and refuses until it is pushed; push `main` before starting the next branch.
#### Decision (2026-09)
A merged branch carries its own summary under `[Unreleased]` in
[CHANGELOG.md](../CHANGELOG.md), added before `create:finish`;
`create:release` graduates it into the tagged section (see
[publishing.md](./publishing.md)).
#### Why
- `create:release` derives the bump heuristic from the `[Unreleased]` body, so
the notes must exist before release day.
- The contributor has fresh context; at release day the intent of a branch is
only its diff.
- Gitmoji subjects are signposts, not semantic keys, so notes cannot be derived
from the history.
#### Rejected
- Generating notes from subjects at release time: subjects carry no parseable
type/scope (see § Commit messages).
- The maintainer writing one summary during `create:release`: reconstruction
after the fact.
- Enforcing it in `create:finish`: the front doors assert git state, not
content — and _notable_ is exactly the judgment a tool cannot make.
## Script prefix convention ## Script prefix convention
package-lock.json
Generated
+179 -128
View File
@@ -1,22 +1,25 @@
{ {
"name": "tiny-pattern-ts", "name": "tiny-pattern-ts",
"version": "0.1.6", "version": "0.6.0",
"lockfileVersion": 3, "lockfileVersion": 3,
"requires": true, "requires": true,
"packages": { "packages": {
"": { "": {
"name": "tiny-pattern-ts", "name": "tiny-pattern-ts",
"version": "0.1.6", "version": "0.6.0",
"license": "MIT", "license": "MIT",
"dependencies": {
"type-fest": "^5.9.0"
},
"devDependencies": { "devDependencies": {
"@arethetypeswrong/cli": "^0.18.5", "@arethetypeswrong/cli": "^0.18.5",
"@runwisp/pubv": "^1.5.1", "@runwisp/pubv": "^1.5.1",
"@tsconfig/node26": "^26.0.1", "@tsconfig/node26": "^26.0.1",
"@tsconfig/strictest": "^2.0.8", "@tsconfig/strictest": "^2.0.8",
"@types/node": "^26.4.1", "@types/node": "^26.6.1",
"c8": "^12.0.0", "c8": "^12.0.0",
"check-outdated": "^3.0.0", "check-outdated": "^3.0.0",
"cspell": "^10.2.2", "cspell": "^10.3.2",
"expect-type": "1.4.0", "expect-type": "1.4.0",
"knip": "^6.34.0", "knip": "^6.34.0",
"lefthook": "^2.1.12", "lefthook": "^2.1.12",
@@ -24,7 +27,8 @@
"oxlint": "^1.83.0", "oxlint": "^1.83.0",
"oxlint-tsgolint": "^7.0.2001", "oxlint-tsgolint": "^7.0.2001",
"publint": "^0.3.24", "publint": "^0.3.24",
"typescript": "^7.0.2" "typescript": "^7.0.2",
"vscode-languageserver-protocol": "^3.18.3"
}, },
"engines": { "engines": {
"node": ">=26" "node": ">=26"
@@ -122,9 +126,9 @@
} }
}, },
"node_modules/@cspell/cspell-bundled-dicts": { "node_modules/@cspell/cspell-bundled-dicts": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/cspell-bundled-dicts/-/cspell-bundled-dicts-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/cspell-bundled-dicts/-/cspell-bundled-dicts-10.3.2.tgz",
"integrity": "sha512-wHRmqaHrhmPHxsnYs9JhYCwD+lLsIOltbvaK9XfIkisblfBCjvsSihsJZhVEvSQ2pPNqESUaOQnBBeVbqv52qA==", "integrity": "sha512-b0f6fQCwcTP32dsibbPbdU2m5R0ZAwAVaB1u04187OqfRBJxr2m77bAXa50xSsjonRILLAGzxgT4+HkPojIBpA==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
@@ -193,22 +197,22 @@
} }
}, },
"node_modules/@cspell/cspell-json-reporter": { "node_modules/@cspell/cspell-json-reporter": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/cspell-json-reporter/-/cspell-json-reporter-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/cspell-json-reporter/-/cspell-json-reporter-10.3.2.tgz",
"integrity": "sha512-wdM5pdIDIDn5PHxEMU0uhu3Gxgpqp6Y0MD65eGr+sFXSxXyWwc3U0F1ghxsYCVIKfiF71tKRwtuKnMQJLXPNKw==", "integrity": "sha512-X4K1lWhrf2NUtLfX+9LrZPyN1XoYv0jzAyzME7qs/LFtmZlPnjlFjLfh2gO48bYJWnd9WN0AzzEzwOMD331l2A==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@cspell/cspell-types": "10.3.1" "@cspell/cspell-types": "10.3.2"
}, },
"engines": { "engines": {
"node": ">=22.18.0" "node": ">=22.18.0"
} }
}, },
"node_modules/@cspell/cspell-performance-monitor": { "node_modules/@cspell/cspell-performance-monitor": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/cspell-performance-monitor/-/cspell-performance-monitor-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/cspell-performance-monitor/-/cspell-performance-monitor-10.3.2.tgz",
"integrity": "sha512-zSFk/7YxYUCoxCxunigiW/q0U9XsIYNQJy6+bYaVYOT6/3WMOHZkzWffxAD8WNzzMd61QFpTb2FrrzudEhY/Yw==", "integrity": "sha512-n2/nXk4tOHzQDbh9X5yTuofQDprZTywrYow8Fua0Gy9gyanmRShTSpnooOMk8SraIuRhIPNm98ge2XNgQrsH7Q==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"engines": { "engines": {
@@ -216,9 +220,9 @@
} }
}, },
"node_modules/@cspell/cspell-pipe": { "node_modules/@cspell/cspell-pipe": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/cspell-pipe/-/cspell-pipe-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/cspell-pipe/-/cspell-pipe-10.3.2.tgz",
"integrity": "sha512-ErGssy4KPaI+PWbc92attUz4/hYcJW05c94tgzhiaEUumgrCMqV64sJlFyTh3ckMhAh9pPg2Kp+qpmS634pTwQ==", "integrity": "sha512-Iyy5aC6kgymCXwQkV56LJAbkVl8mfEVoyTgfi3Nv72CWvaPo7tStYdmyqFNs2oj3jpVArc8gRoi6uztV8wJ9rQ==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"engines": { "engines": {
@@ -226,9 +230,9 @@
} }
}, },
"node_modules/@cspell/cspell-resolver": { "node_modules/@cspell/cspell-resolver": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/cspell-resolver/-/cspell-resolver-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/cspell-resolver/-/cspell-resolver-10.3.2.tgz",
"integrity": "sha512-m072aE8NesdbSt8wieWJiCZOzSekzorsaXFxetkTFI2JIM7fqd+wvCtasLYY1CUbhjGdHOjTQ5GxXL6Z4rzCbA==", "integrity": "sha512-StPrbknIKYOmgKGUYb1YLFnOR309aG/Rvo8RbNBKCBtvRV9dDynwioK1H712uva3B/+8EDjW8bOduM8ZIrovyw==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
@@ -239,9 +243,9 @@
} }
}, },
"node_modules/@cspell/cspell-service-bus": { "node_modules/@cspell/cspell-service-bus": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/cspell-service-bus/-/cspell-service-bus-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/cspell-service-bus/-/cspell-service-bus-10.3.2.tgz",
"integrity": "sha512-Ha+H8SOBFA0QeWjYc9qY2/Jm41PGpmFjGqgOGZtI8BiJ5DTPLQpn2rPAxE6IKNUvtNE1kkknkbhsWVe/a14wkw==", "integrity": "sha512-WyBH2Ek3+viH/B3adXKUYH8mKqXx7qjUI3aro8Ci4KbCIqllRmfQisx4WnaW9b9Y471+xy4FCGRC77Qdclnewg==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"engines": { "engines": {
@@ -249,9 +253,9 @@
} }
}, },
"node_modules/@cspell/cspell-types": { "node_modules/@cspell/cspell-types": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/cspell-types/-/cspell-types-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/cspell-types/-/cspell-types-10.3.2.tgz",
"integrity": "sha512-c0ta73Z2KQdvOqlCWNCi9GYQSw/IUFm0R0FpNOaPZn3cjc6J6pMBd4IwD07TsOXMduCrmf/Ppg6gzcyviGHeAQ==", "integrity": "sha512-Ld9OiU4PhsaYFZ2AcnfqB+YA1piyMf/C9rASQBQrEEcB9n/2Hbmd3gSA1KF29FGyfuAJBrigt7N/GTSSUZVrWw==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"engines": { "engines": {
@@ -259,13 +263,13 @@
} }
}, },
"node_modules/@cspell/cspell-worker": { "node_modules/@cspell/cspell-worker": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/cspell-worker/-/cspell-worker-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/cspell-worker/-/cspell-worker-10.3.2.tgz",
"integrity": "sha512-mg4J9ia14qNoP8oqSBFU8BOq/VoI0s6xPdsw70oiDvCfxMePoe5PvcnrGNjWNHAdoOeMuFNgjpK5vl/CSjaLFQ==", "integrity": "sha512-YUGOI5u4aR/1Ld069mBVhi0/rDQrhmqg0TQgKy+PUhUcR4LdKZ/PFhA+3NObyZy8k2lPYdpbAYf27zuGA39HFA==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"cspell-lib": "10.3.1" "cspell-lib": "10.3.2"
}, },
"engines": { "engines": {
"node": ">=22.18.0" "node": ">=22.18.0"
@@ -697,13 +701,13 @@
"license": "MIT" "license": "MIT"
}, },
"node_modules/@cspell/dynamic-import": { "node_modules/@cspell/dynamic-import": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/dynamic-import/-/dynamic-import-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/dynamic-import/-/dynamic-import-10.3.2.tgz",
"integrity": "sha512-4OlYzARVBPlPjc1hsixRJObNhnzmBQOXuMjCmlLa5CiAB2y9fhVKN8EIZMSph/Tboo+LzCxUpOmklSwb1NqYRQ==", "integrity": "sha512-n7vpABAl6msXh5Li4dxBdA2n0ux3sCznb/F4ysEzyRJJ4gHXmC75fTeeDQbzdERxwz7bSc8K3nqlDiebyLq9aw==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@cspell/url": "10.3.1", "@cspell/url": "10.3.2",
"import-meta-resolve": "^4.2.0" "import-meta-resolve": "^4.2.0"
}, },
"engines": { "engines": {
@@ -711,9 +715,9 @@
} }
}, },
"node_modules/@cspell/filetypes": { "node_modules/@cspell/filetypes": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/filetypes/-/filetypes-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/filetypes/-/filetypes-10.3.2.tgz",
"integrity": "sha512-R7pQUshSh78yWEb5SSdeKlQBamYn15BpU3EEUHKXFZq70PvixXatVtygFBHawdk8YjSAVQTT+G5Rx4LOv/3QLQ==", "integrity": "sha512-6dunxj9bNfVR1l8yuW5tU165l8wYzQZJQAnunonnYTdk6zeguu2odpaKMebS/Mo2PuGknhhz53KBJzVBEQZFHQ==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"engines": { "engines": {
@@ -721,9 +725,9 @@
} }
}, },
"node_modules/@cspell/rpc": { "node_modules/@cspell/rpc": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/rpc/-/rpc-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/rpc/-/rpc-10.3.2.tgz",
"integrity": "sha512-3MJ62tcb27JM/Znpg9OE97iWHh0QDQsUZV15imAw2326yGAG7oyFEIyDDvhbJLQTfogs0oYdH7c5A4B/VfBIZg==", "integrity": "sha512-5TZJvPhNo8KhjFYWAlg7pX3+RnQsrLUWE3OdSsfQ6yAbJGP9SulPHjzr7wapGE/jhPVH3vg9OlZhO6o1lRKISA==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"engines": { "engines": {
@@ -731,9 +735,9 @@
} }
}, },
"node_modules/@cspell/strong-weak-map": { "node_modules/@cspell/strong-weak-map": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/strong-weak-map/-/strong-weak-map-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/strong-weak-map/-/strong-weak-map-10.3.2.tgz",
"integrity": "sha512-Bwe3+1GyKN1BcfdDsWW53ujWxUqn6onNAKJ6hIXaZCTAS/ZLMcoYP7fJQko/syEGerOvbcSgdCkXfahrM2dRfA==", "integrity": "sha512-P/QVqEzKedoRAOcQnAO23BvYdK47K4T0h3iSZE411EgAFG2RJSL2YNXyIhMe86XkK20ePXnh91/xtoC6oST7PQ==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"engines": { "engines": {
@@ -741,9 +745,9 @@
} }
}, },
"node_modules/@cspell/url": { "node_modules/@cspell/url": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/@cspell/url/-/url-10.3.1.tgz", "resolved": "https://registry.npmjs.org/@cspell/url/-/url-10.3.2.tgz",
"integrity": "sha512-S2+Sr9LwCrUATnODo8fdyF6NfJZYAmYmA0HaJ40OGEsOwi17T5aa1jHfw62RWyZYMkxFLcL7ABeFHnWDgI784A==", "integrity": "sha512-7KG8iDDIckYf6CSCn9CoHzxABREOSA2c8pLQz4lEBJcIL4NOZbD8O7Zw69rRQ2nDIDPAbHeu+6KAr86EQJ7lUQ==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"engines": { "engines": {
@@ -2362,9 +2366,9 @@
"license": "MIT" "license": "MIT"
}, },
"node_modules/@types/node": { "node_modules/@types/node": {
"version": "26.5.1", "version": "26.6.1",
"resolved": "https://registry.npmjs.org/@types/node/-/node-26.5.1.tgz", "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.1.tgz",
"integrity": "sha512-CzNm2FezW4VR/LjG6yUdiEgLE/rAQ9Slj5gCu/C2VrdcW7I0ahNZ8DRbHT7zOZ6r3ONgd/bsQIeSaoDGrd1C6g==", "integrity": "sha512-VqGJBMCtdhqkBUCcBLvywI0NJ+KLuVzgNnlBUNFOQjqVxzo2lxLUNg1DSey8+u2u6ktswSAxg+s68QLzWHNOuA==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
@@ -3123,30 +3127,29 @@
} }
}, },
"node_modules/cspell": { "node_modules/cspell": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/cspell/-/cspell-10.3.1.tgz", "resolved": "https://registry.npmjs.org/cspell/-/cspell-10.3.2.tgz",
"integrity": "sha512-fd16436V8lEQ2UT8gAwcXrgfB8k5qpIhFC4Zo753v/JA1eL9ZlCDYCMefAPKVq1CfFpImsTfxxeGqscaYJ/ISA==", "integrity": "sha512-r4G/4rjaFe/ASCX43+3T4sKJQQzbiyBzWQhTl+kjcEfDYZsG++Ut5dXeXVld364QrGOqry3KQbvwUijci4vrIA==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@cspell/cspell-json-reporter": "10.3.1", "@cspell/cspell-json-reporter": "10.3.2",
"@cspell/cspell-performance-monitor": "10.3.1", "@cspell/cspell-performance-monitor": "10.3.2",
"@cspell/cspell-pipe": "10.3.1", "@cspell/cspell-pipe": "10.3.2",
"@cspell/cspell-types": "10.3.1", "@cspell/cspell-types": "10.3.2",
"@cspell/cspell-worker": "10.3.1", "@cspell/cspell-worker": "10.3.2",
"@cspell/dynamic-import": "10.3.1", "@cspell/dynamic-import": "10.3.2",
"@cspell/url": "10.3.1", "@cspell/url": "10.3.2",
"ansi-regex": "^6.3.0", "ansi-regex": "^6.3.0",
"chalk": "^6.0.0", "chalk": "^6.0.0",
"chalk-template": "^1.1.2", "chalk-template": "^1.1.2",
"commander": "^15.0.0", "commander": "^15.0.0",
"cspell-config-lib": "10.3.1", "cspell-config-lib": "10.3.2",
"cspell-dictionary": "10.3.1", "cspell-dictionary": "10.3.2",
"cspell-gitignore": "10.3.1", "cspell-gitignore": "10.3.2",
"cspell-glob": "10.3.1", "cspell-glob": "10.3.2",
"cspell-io": "10.3.1", "cspell-io": "10.3.2",
"cspell-lib": "10.3.1", "cspell-lib": "10.3.2",
"fast-json-stable-stringify": "^2.1.0",
"flatted": "^3.4.4", "flatted": "^3.4.4",
"semver": "^7.8.5", "semver": "^7.8.5",
"tinyglobby": "^0.2.17" "tinyglobby": "^0.2.17"
@@ -3163,13 +3166,13 @@
} }
}, },
"node_modules/cspell-config-lib": { "node_modules/cspell-config-lib": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/cspell-config-lib/-/cspell-config-lib-10.3.1.tgz", "resolved": "https://registry.npmjs.org/cspell-config-lib/-/cspell-config-lib-10.3.2.tgz",
"integrity": "sha512-cSZEEhXqTjvoeohRW9ZhYziOTxApN9roHWKaGslsS9UGWbY4eOBO6FikDL1r/2PQ0rGLMu570XTEJYMmFlHraw==", "integrity": "sha512-ukPSVWkiNaiwW26yERfs2+o4rHZ5+YG9uSEqiTqRTcCTrItopyNTizurI+H3pzgrGwcZwPwxNsRZy9oKyOqfjQ==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@cspell/cspell-types": "10.3.1", "@cspell/cspell-types": "10.3.2",
"comment-json": "^5.0.0", "comment-json": "^5.0.0",
"smol-toml": "^1.8.0", "smol-toml": "^1.8.0",
"yaml": "^2.9.0" "yaml": "^2.9.0"
@@ -3179,16 +3182,16 @@
} }
}, },
"node_modules/cspell-dictionary": { "node_modules/cspell-dictionary": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/cspell-dictionary/-/cspell-dictionary-10.3.1.tgz", "resolved": "https://registry.npmjs.org/cspell-dictionary/-/cspell-dictionary-10.3.2.tgz",
"integrity": "sha512-IR4ApsnqSP0m+daR1lXjpTG4hzrH5Ow7E/yzgoAKKbP9OQRVgrpXC948aOVbB6JOC/Sk2BkWmeMlnJ3YBM3FFQ==", "integrity": "sha512-KHjGUEGNm9jvDQL3CK1vkFgRMk2AJ/6NvWHM5sh8eGX6HBEWd0GAlpnL8087YRao70gToGw/IFxTqsSTktkraw==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@cspell/cspell-performance-monitor": "10.3.1", "@cspell/cspell-performance-monitor": "10.3.2",
"@cspell/cspell-pipe": "10.3.1", "@cspell/cspell-pipe": "10.3.2",
"@cspell/cspell-types": "10.3.1", "@cspell/cspell-types": "10.3.2",
"cspell-trie-lib": "10.3.1", "cspell-trie-lib": "10.3.2",
"fast-equals": "^6.0.2" "fast-equals": "^6.0.2"
}, },
"engines": { "engines": {
@@ -3196,15 +3199,15 @@
} }
}, },
"node_modules/cspell-gitignore": { "node_modules/cspell-gitignore": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/cspell-gitignore/-/cspell-gitignore-10.3.1.tgz", "resolved": "https://registry.npmjs.org/cspell-gitignore/-/cspell-gitignore-10.3.2.tgz",
"integrity": "sha512-20I1vn8iZ4h5tVGzQA894uHaS6TPYADjTfP/ZDsSv7eQwgL+T/VQU6jDfveMg4FfGvCaSkRxFKoawa86B2UejA==", "integrity": "sha512-AnfW9XMHOJ1BgEsapLn7VHV9KT+SuqtDEy0chQtHG/2ZcP2UOFJC8bHH35DUD2cYdBNhp5Dr6BHnvvCHgQE1+w==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@cspell/url": "10.3.1", "@cspell/url": "10.3.2",
"cspell-glob": "10.3.1", "cspell-glob": "10.3.2",
"cspell-io": "10.3.1" "cspell-io": "10.3.2"
}, },
"bin": { "bin": {
"cspell-gitignore": "bin.mjs" "cspell-gitignore": "bin.mjs"
@@ -3214,13 +3217,13 @@
} }
}, },
"node_modules/cspell-glob": { "node_modules/cspell-glob": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/cspell-glob/-/cspell-glob-10.3.1.tgz", "resolved": "https://registry.npmjs.org/cspell-glob/-/cspell-glob-10.3.2.tgz",
"integrity": "sha512-w6DvrttxHpSYUYep7RzcIvTZbCtXovWkWVkuGw+RPLOSXbUEcoqDYg3EW9uTg57LIT3p5Jsop+VOTuJzQ8ahTw==", "integrity": "sha512-fmyBeErzjF0Vtf8oGqlc76qsx257x7bUQ7hHB2SQUOJb50KOoZ+en+hfE2g1eAIPX0yEXqU65D9f6D83XaaiLw==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@cspell/url": "10.3.1", "@cspell/url": "10.3.2",
"picomatch": "^4.0.7" "picomatch": "^4.0.7"
}, },
"engines": { "engines": {
@@ -3228,14 +3231,14 @@
} }
}, },
"node_modules/cspell-grammar": { "node_modules/cspell-grammar": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/cspell-grammar/-/cspell-grammar-10.3.1.tgz", "resolved": "https://registry.npmjs.org/cspell-grammar/-/cspell-grammar-10.3.2.tgz",
"integrity": "sha512-GLtG5fzT4+o9FMqB2M10LT/hnA0iFEO4OmKl1+XMyDrK4rdFrqsBpVfc9Uyk+5AZ+nkR9/PudZBEkFpDDrpgNg==", "integrity": "sha512-Dpi1PgyAk9fYKfJqHHWxBL51ESWR8EMn6NodplYcx8i0UVr8rCcUrISq9+yhgdsi0R547lxe3iufUBdaP1RiFg==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@cspell/cspell-pipe": "10.3.1", "@cspell/cspell-pipe": "10.3.2",
"@cspell/cspell-types": "10.3.1" "@cspell/cspell-types": "10.3.2"
}, },
"bin": { "bin": {
"cspell-grammar": "bin.mjs" "cspell-grammar": "bin.mjs"
@@ -3245,42 +3248,42 @@
} }
}, },
"node_modules/cspell-io": { "node_modules/cspell-io": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/cspell-io/-/cspell-io-10.3.1.tgz", "resolved": "https://registry.npmjs.org/cspell-io/-/cspell-io-10.3.2.tgz",
"integrity": "sha512-LGC739gKC/wzoCrLFl+F0F/wQQZNATzvMoIlFk7acr+xGrRVJUUudxh0Fh0yCBnYXtCGhbSUxLgg8eHgFScAag==", "integrity": "sha512-0tY0wMPHvGN0G1DG+NLlJNEcRzY2ycZwWOpz6p/zgaBimEanLY+NJjoOsYPBAhzXhFbDdamsttL0bBPoJKYJPA==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@cspell/cspell-service-bus": "10.3.1", "@cspell/cspell-service-bus": "10.3.2",
"@cspell/url": "10.3.1" "@cspell/url": "10.3.2"
}, },
"engines": { "engines": {
"node": ">=22.18.0" "node": ">=22.18.0"
} }
}, },
"node_modules/cspell-lib": { "node_modules/cspell-lib": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/cspell-lib/-/cspell-lib-10.3.1.tgz", "resolved": "https://registry.npmjs.org/cspell-lib/-/cspell-lib-10.3.2.tgz",
"integrity": "sha512-msDAL+F0suXMTFj6OCWPmeBUNUe+19Bb1yPtOkbGVBU65K7sKHfwjCt8ev3iTdhhIKi8hIaq6xmJShBb1vznmw==", "integrity": "sha512-svq9qWoMY58/BdyEQwY1YJhDKrmE8/z4VIiwvtgNkxV/km/6wPTNvm2iQNI4VjSa+DWYSvHyX16LwNjrcGp0sw==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@cspell/cspell-bundled-dicts": "10.3.1", "@cspell/cspell-bundled-dicts": "10.3.2",
"@cspell/cspell-performance-monitor": "10.3.1", "@cspell/cspell-performance-monitor": "10.3.2",
"@cspell/cspell-pipe": "10.3.1", "@cspell/cspell-pipe": "10.3.2",
"@cspell/cspell-resolver": "10.3.1", "@cspell/cspell-resolver": "10.3.2",
"@cspell/cspell-types": "10.3.1", "@cspell/cspell-types": "10.3.2",
"@cspell/dynamic-import": "10.3.1", "@cspell/dynamic-import": "10.3.2",
"@cspell/filetypes": "10.3.1", "@cspell/filetypes": "10.3.2",
"@cspell/rpc": "10.3.1", "@cspell/rpc": "10.3.2",
"@cspell/strong-weak-map": "10.3.1", "@cspell/strong-weak-map": "10.3.2",
"@cspell/url": "10.3.1", "@cspell/url": "10.3.2",
"cspell-config-lib": "10.3.1", "cspell-config-lib": "10.3.2",
"cspell-dictionary": "10.3.1", "cspell-dictionary": "10.3.2",
"cspell-glob": "10.3.1", "cspell-glob": "10.3.2",
"cspell-grammar": "10.3.1", "cspell-grammar": "10.3.2",
"cspell-io": "10.3.1", "cspell-io": "10.3.2",
"cspell-trie-lib": "10.3.1", "cspell-trie-lib": "10.3.2",
"env-paths": "^4.0.0", "env-paths": "^4.0.0",
"gensequence": "^8.0.8", "gensequence": "^8.0.8",
"import-fresh": "^4.0.0", "import-fresh": "^4.0.0",
@@ -3294,16 +3297,16 @@
} }
}, },
"node_modules/cspell-trie-lib": { "node_modules/cspell-trie-lib": {
"version": "10.3.1", "version": "10.3.2",
"resolved": "https://registry.npmjs.org/cspell-trie-lib/-/cspell-trie-lib-10.3.1.tgz", "resolved": "https://registry.npmjs.org/cspell-trie-lib/-/cspell-trie-lib-10.3.2.tgz",
"integrity": "sha512-6mJGGPEtD4CMoq9qxmRIa+XB7BgLPTgDSGFn1FluNbhF/x3VFeSErcTO+lcfqQhAdAZvEIqptzKt/m6CJJUUPg==", "integrity": "sha512-YYberpBG16hLviQHLkciXjtqEUc6Q7f9UL71GlJAflSD9TYFuXIvhpIYV80YXPyDrh2Jk3ZYeUqWLQmpZjKaeQ==",
"dev": true, "dev": true,
"license": "MIT", "license": "MIT",
"engines": { "engines": {
"node": ">=22.18.0" "node": ">=22.18.0"
}, },
"peerDependencies": { "peerDependencies": {
"@cspell/cspell-types": "10.3.1" "@cspell/cspell-types": "10.3.2"
} }
}, },
"node_modules/cspell/node_modules/chalk": { "node_modules/cspell/node_modules/chalk": {
@@ -3416,13 +3419,6 @@
"node": ">=6.0.0" "node": ">=6.0.0"
} }
}, },
"node_modules/fast-json-stable-stringify": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz",
"integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==",
"dev": true,
"license": "MIT"
},
"node_modules/fd-package-json": { "node_modules/fd-package-json": {
"version": "2.0.0", "version": "2.0.0",
"resolved": "https://registry.npmjs.org/fd-package-json/-/fd-package-json-2.0.0.tgz", "resolved": "https://registry.npmjs.org/fd-package-json/-/fd-package-json-2.0.0.tgz",
@@ -4630,6 +4626,18 @@
"url": "https://github.com/chalk/supports-hyperlinks?sponsor=1" "url": "https://github.com/chalk/supports-hyperlinks?sponsor=1"
} }
}, },
"node_modules/tagged-tag": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/tagged-tag/-/tagged-tag-1.0.0.tgz",
"integrity": "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==",
"license": "MIT",
"engines": {
"node": ">=20"
},
"funding": {
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/test-exclude": { "node_modules/test-exclude": {
"version": "8.0.0", "version": "8.0.0",
"resolved": "https://registry.npmjs.org/test-exclude/-/test-exclude-8.0.0.tgz", "resolved": "https://registry.npmjs.org/test-exclude/-/test-exclude-8.0.0.tgz",
@@ -4713,6 +4721,21 @@
"license": "0BSD", "license": "0BSD",
"optional": true "optional": true
}, },
"node_modules/type-fest": {
"version": "5.9.0",
"resolved": "https://registry.npmjs.org/type-fest/-/type-fest-5.9.0.tgz",
"integrity": "sha512-yANm3Jr3GiJ1qgJlxGAVxTOIcEOk1rhQHamlXtnrCK7EHP4HeM9OGxtMg/W7HFdrVzw/ZWJKGVIJusVH85sLtw==",
"license": "(MIT OR CC0-1.0)",
"dependencies": {
"tagged-tag": "^1.0.0"
},
"engines": {
"node": ">=20"
},
"funding": {
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/typescript": { "node_modules/typescript": {
"version": "7.0.2", "version": "7.0.2",
"resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz", "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz",
@@ -4800,6 +4823,27 @@
"node": "^14.17.0 || ^16.13.0 || >=18.0.0" "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
} }
}, },
"node_modules/vscode-jsonrpc": {
"version": "9.0.2",
"resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-9.0.2.tgz",
"integrity": "sha512-SbQSV9yRemARxeXw6LU5sS6Zq0e9/DgCCX5yelH263ZQWukbTk8EF8fjTrr1dziasf4GwlJbvTwFnTrnQFWZXQ==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=14.0.0"
}
},
"node_modules/vscode-languageserver-protocol": {
"version": "3.18.3",
"resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.18.3.tgz",
"integrity": "sha512-DF49+WeV5py4zO5hhobp60jjsDSK0lAqA0OuKBLBvp423HPWQcCbhZz3JgyfIewsEz2f8U+X75xNIFHdiXZm2w==",
"dev": true,
"license": "MIT",
"dependencies": {
"vscode-jsonrpc": "9.0.2",
"vscode-languageserver-types": "3.18.3"
}
},
"node_modules/vscode-languageserver-textdocument": { "node_modules/vscode-languageserver-textdocument": {
"version": "1.0.14", "version": "1.0.14",
"resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.14.tgz", "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.14.tgz",
@@ -4807,6 +4851,13 @@
"dev": true, "dev": true,
"license": "MIT" "license": "MIT"
}, },
"node_modules/vscode-languageserver-types": {
"version": "3.18.3",
"resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.18.3.tgz",
"integrity": "sha512-XIlzJ7Qp/jzSI1ds7/FwPAWrPeTZA7pAtlW4hdJ1J6xXWJL6dR9QYnDhJOdLzdKhUQ5Mm6mvUMw+3DcOQQasPw==",
"dev": true,
"license": "MIT"
},
"node_modules/vscode-uri": { "node_modules/vscode-uri": {
"version": "3.2.0", "version": "3.2.0",
"resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.2.0.tgz", "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.2.0.tgz",
package.json
+12 -5
View File
@@ -1,6 +1,6 @@
{ {
"name": "tiny-pattern-ts", "name": "tiny-pattern-ts",
"version": "0.1.6", "version": "0.6.0",
"description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)", "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
"keywords": [ "keywords": [
"adt", "adt",
@@ -27,6 +27,9 @@
], ],
"type": "module", "type": "module",
"sideEffects": false, "sideEffects": false,
"imports": {
"#test-utils/*": "./src/util/__tests__/*"
},
"exports": { "exports": {
".": { ".": {
"types": "./dist/index.d.ts", "types": "./dist/index.d.ts",
@@ -53,7 +56,7 @@
"create:release": "./scripts/release.sh", "create:release": "./scripts/release.sh",
"maintain": "npm run maintain:knip; npm run maintain:outdated", "maintain": "npm run maintain:knip; npm run maintain:outdated",
"maintain:knip": "knip --include dependencies,exports,files", "maintain:knip": "knip --include dependencies,exports,files",
"maintain:outdated": "check-outdated --ignore-pre-releases", "maintain:outdated": "check-outdated --ignore-pre-releases --ignore-packages @types/node",
"test": "npm run check:tsc && node --test --strip-types \"src/**/*.test.ts\"", "test": "npm run check:tsc && node --test --strip-types \"src/**/*.test.ts\"",
"test:ci": "c8 --reporter=text --reporter=lcov --reporter=html node --test --strip-types \"src/**/*.test.ts\"", "test:ci": "c8 --reporter=text --reporter=lcov --reporter=html node --test --strip-types \"src/**/*.test.ts\"",
"test:unit": "node --test --strip-types \"src/**/*.test.ts\"", "test:unit": "node --test --strip-types \"src/**/*.test.ts\"",
@@ -65,15 +68,18 @@
"setup": "npm run setup:git-commit-message", "setup": "npm run setup:git-commit-message",
"setup:git-commit-message": "git config commit.template commit-message-template" "setup:git-commit-message": "git config commit.template commit-message-template"
}, },
"dependencies": {
"type-fest": "^5.9.0"
},
"devDependencies": { "devDependencies": {
"@arethetypeswrong/cli": "^0.18.5", "@arethetypeswrong/cli": "^0.18.5",
"@runwisp/pubv": "^1.5.1", "@runwisp/pubv": "^1.5.1",
"@tsconfig/node26": "^26.0.1", "@tsconfig/node26": "^26.0.1",
"@tsconfig/strictest": "^2.0.8", "@tsconfig/strictest": "^2.0.8",
"@types/node": "^26.4.1", "@types/node": "^26.6.1",
"c8": "^12.0.0", "c8": "^12.0.0",
"check-outdated": "^3.0.0", "check-outdated": "^3.0.0",
"cspell": "^10.2.2", "cspell": "^10.3.2",
"expect-type": "1.4.0", "expect-type": "1.4.0",
"knip": "^6.34.0", "knip": "^6.34.0",
"lefthook": "^2.1.12", "lefthook": "^2.1.12",
@@ -81,7 +87,8 @@
"oxlint": "^1.83.0", "oxlint": "^1.83.0",
"oxlint-tsgolint": "^7.0.2001", "oxlint-tsgolint": "^7.0.2001",
"publint": "^0.3.24", "publint": "^0.3.24",
"typescript": "^7.0.2" "typescript": "^7.0.2",
"vscode-languageserver-protocol": "^3.18.3"
}, },
"engines": { "engines": {
"node": ">=26" "node": ">=26"
scripts/branch.sh
+10 -8
View File
@@ -73,9 +73,9 @@ git show-ref --verify --quiet "refs/heads/${BASE}" || {
exit 1 exit 1
} }
# Derive the remote rather than hardcoding it: this repo has `origin` (ssh) and # Derive the remote rather than hardcoding it: `main` tracks `origin` (ssh)
# `origin_https`, and `main` tracks the latter — `git fetch origin main` would # here; a hardcoded name would check currency against a ref that may not
# check currency against a ref that is never updated here. # exist on a differently configured clone.
# `--quiet` echoes the unresolved `main@{upstream}` literal to stdout on # `--quiet` echoes the unresolved `main@{upstream}` literal to stdout on
# failure, so it cannot be paired with a `$(...) || fallback`; the non-quiet # failure, so it cannot be paired with a `$(...) || fallback`; the non-quiet
# form prints nothing on failure and the fallback runs. # form prints nothing on failure and the fallback runs.
@@ -86,12 +86,14 @@ if [ -n "${UPSTREAM}" ]; then
echo " refusing to branch on a possibly stale '${BASE}'." >&2 echo " refusing to branch on a possibly stale '${BASE}'." >&2
exit 1 exit 1
} }
# Only *behind* is a problem. `create:finish` deliberately leaves the local
# merge on '${BASE}' until `create:release` pushes it, so being ahead is the
# normal state between a merge and the release that ships it; branching from
# those commits is intended. Missing remote commits is not.
BEHIND=$(git rev-list --count "${BASE}..${UPSTREAM}") BEHIND=$(git rev-list --count "${BASE}..${UPSTREAM}")
AHEAD=$(git rev-list --count "${UPSTREAM}..${BASE}") if [ "${BEHIND}" -ne 0 ]; then
if [ "${BEHIND}" -ne 0 ] || [ "${AHEAD}" -ne 0 ]; then echo "error: '${BASE}' is behind '${UPSTREAM}' (by ${BEHIND})." >&2
echo "error: '${BASE}' has diverged from '${UPSTREAM}' (ahead ${AHEAD}, behind ${BEHIND})." >&2 echo " update it: git switch ${BASE} && git pull --ff-only" >&2
[ "${AHEAD}" -ne 0 ] && echo " not yet pushed commits on '${BASE}': push them, or rebase this work onto them." >&2
[ "${BEHIND}" -ne 0 ] && echo " update it: git switch ${BASE} && git pull --ff-only" >&2
exit 1 exit 1
fi fi
else else
src/index.test.ts
-56
View File
@@ -1,56 +0,0 @@
/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
import { strict as assert } from "node:assert";
import { test } from "node:test";
import { expectTypeOf } from "expect-type";
import { type Matcher, P, match } from "./index.ts";
test("match returns a builder", () => {
const builder = match("x");
expectTypeOf(builder).toHaveProperty("with");
expectTypeOf(builder).toHaveProperty("exhaustive");
expectTypeOf(builder).toHaveProperty("otherwise");
});
test("P.literal narrows to its literal type", () => {
const matcher = P.literal("yes");
expectTypeOf(matcher).toMatchTypeOf<Matcher<"yes">>();
assert.equal(matcher.matches("yes"), true);
assert.equal(matcher.matches("no"), false);
});
test("P.type narrows to the typeof target", () => {
const matcher = P.type<string>("string");
expectTypeOf(matcher).toMatchTypeOf<Matcher<string>>();
assert.equal(matcher.matches("hi"), true);
assert.equal(matcher.matches(42), false);
});
test("exhaustive() returns the union of handler return types", () => {
const result = match<"a" | "b">("a")
.with(P.literal("a"), () => 1 as const)
.with(P.literal("b"), () => "two" as const)
.exhaustive();
expectTypeOf(result).toEqualTypeOf<1 | "two">();
assert.equal(result, 1);
});
test("otherwise() falls back when no case matches", () => {
const result = match<"x" | "y" | "z">("z")
.with(P.literal("x"), (v): string => `got ${v}`)
.otherwise((v): string => `fallback ${v}`);
assert.equal(result, "fallback z");
});
test("exhaustive throws when no case matches", () => {
assert.throws(
() =>
match<"a" | "b" | "c">("c")
.with(P.literal("a"), () => "A")
.with(P.literal("b"), () => "B")
.exhaustive(),
/no matching case/,
);
});
src/index.ts
+8 -2
View File
@@ -1,2 +1,8 @@
export { match, P } from "./match.ts"; export {
export type { Matcher, Pattern } from "./pattern.ts"; getPrimitiveUnionMatcher,
getPrimitiveUnionMatcherW,
} from "./primitive-union.ts";
export {
getTaggedUnionMatcher,
getTaggedUnionMatcherW,
} from "./tagged-union.ts";
src/match.ts
-62
View File
@@ -1,62 +0,0 @@
import { P, type Matcher, type Pattern } from "./pattern.ts";
type Cases<R> = readonly (readonly [Matcher<unknown>, (value: unknown) => R])[];
interface MatchBuilder<T, R> {
with<U extends T, V>(
pattern: Matcher<U>,
handler: (value: U) => V,
): MatchBuilder<T, R | V>;
exhaustive(): R;
otherwise(handler: (value: T) => R): R;
}
const buildMatch = <T, R>(value: T, cases: Cases<R>): MatchBuilder<T, R> => {
const apply = (): R | undefined => {
for (const [matcher, handler] of cases) {
if (matcher.matches(value)) {
return handler(value);
}
}
return undefined;
};
const builder = {
with<U extends T, V>(
pattern: Matcher<U>,
handler: (value: U) => V,
): MatchBuilder<T, R | V> {
const nextCases: Cases<R | V> = [
...cases,
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
[pattern, handler as (value: unknown) => R | V],
];
return buildMatch(value, nextCases);
},
exhaustive(): R {
const result = apply();
if (result === undefined) {
throw new Error(
"tiny-pattern-ts: match.exhaustive() called with no matching case",
);
}
return result;
},
otherwise(handler: (value: T) => R): R {
for (const [matcher, run] of cases) {
if (matcher.matches(value)) {
return run(value);
}
}
return handler(value);
},
};
return builder;
};
export const match = <T>(value: T): MatchBuilder<T, never> =>
buildMatch<T, never>(value, []);
export type { Matcher, Pattern };
export { P };
src/matcher-shared.ts
+60
View File
@@ -0,0 +1,60 @@
import type { ValueOf } from "type-fest";
// The primitive-union and tagged-union matchers differ in their universe, but the
// handler/fallback plumbing is identical; these are the shared pieces. The
// boundary is deliberate: `Handlers`, `Fallback` and `MustBePartial` stay with
// each matcher because they are built from its universe. See development/library.md.
// A handler: one universe member in, one return value out.
export type UnaryFn<T, R> = (shape: T) => R;
// The primitive universe a matcher can discriminate. The primitive-union matcher
// uses it directly; the tagged-union matcher uses it as the set of allowed
// discriminant (`Tag`) values. `boolean` is admitted as the pair `true | false`;
// see README § Caveats for the unsupported members.
export type Matchable = string | number | boolean | null | undefined;
// `boolean`, `null` and `undefined` cannot be property keys, so a mapped type
// over a universe that includes one keys each such member by its
// stringification. `PatternParam` inverts that projection, so a handler callback
// still receives the *real* member (`true`, not `"true"`). Both matchers use the
// projection: the primitive-union matcher over its universe, the tagged-union
// matcher over a discriminant property's values. See README § Caveats for the
// limits.
export type PatternKey<T> = T extends boolean
? T extends true
? "true"
: "false"
: T extends null
? "null"
: T extends undefined
? "undefined"
: T;
export type PatternParam<K> = K extends "true"
? true
: K extends "false"
? false
: K extends "null"
? null
: K extends "undefined"
? undefined
: K;
// `Extract` drops optional handlers (`undefined`) so `PatternReturns` also works
// when `P`'s constraint has optional keys.
export type PatternReturns<P> = ReturnType<
Extract<ValueOf<P>, (...args: never[]) => unknown>
>;
// The diagnostic raised when a fallback is supplied for an already-exhaustive
// handler map. Each matcher's `MustBePartial` folds it into `Handled`'s
// constraint so the guard is checked after inference.
export interface RedundantFallback {
readonly "every case is already handled, so the fallback is redundant": never;
}
// The runtime dispatch map the handler maps and fallback erase to.
export type HandlerMap = Record<
string | number,
UnaryFn<never, unknown> | undefined
>;
src/pattern.ts
-105
View File
@@ -1,105 +0,0 @@
/**
* Pattern matching primitives. Each constructor returns a lightweight
* matcher object whose `matches` method returns a type guard.
*/
export interface Matcher<T> {
readonly matches: (value: unknown) => value is T;
}
const literalMatcher = <
const L extends string | number | boolean | null | undefined,
>(
value: L,
): Matcher<L> => ({
matches: (candidate): candidate is L => candidate === value,
});
const typeMatcher = <T>(
type:
| "string"
| "number"
| "boolean"
| "bigint"
| "symbol"
| "undefined"
| "object"
| "function",
): Matcher<T> => {
const matches = (value: unknown): value is T => {
if (type === "undefined") {
return value === undefined;
}
if (type === "object") {
return (
(typeof value === "object" && value !== null) ||
typeof value === "function"
);
}
return typeof value === type;
};
return { matches };
},
whenMatcher = <T>(
predicate: (value: unknown) => value is T,
): Matcher<T> => ({
matches: predicate,
}),
whenMatcherAny = <T>(
predicate: (value: unknown) => boolean,
): Matcher<T> => ({
matches: (value: unknown): value is T => predicate(value),
}),
isNestedMatcher = (expected: unknown): expected is Matcher<unknown> =>
typeof expected === "object" &&
expected !== null &&
"matches" in expected,
// oxlint-disable-next-line typescript/no-unnecessary-type-parameters
keysMatch = <S extends object>(shape: S, candidate: object): boolean => {
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
for (const key of Object.keys(shape) as (keyof S)[]) {
if (!(key in candidate)) {
return false;
}
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
const expected = shape[key],
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
actual = candidate[key as keyof object];
if (isNestedMatcher(expected)) {
if (!expected.matches(actual)) {
return false;
}
} else if (actual !== expected) {
return false;
}
}
return true;
},
structuralMatcher = <S extends object, T extends S>(
shape: S,
refine?: (value: S) => value is T,
): Matcher<T> => ({
matches: (value: unknown): value is T => {
if (typeof value !== "object" || value === null) {
return false;
}
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
const candidate = value as S;
if (!keysMatch(shape, candidate)) {
return false;
}
if (refine && !refine(candidate)) {
return false;
}
return true;
},
});
export const P = {
literal: literalMatcher,
type: typeMatcher,
when: whenMatcher,
any: whenMatcherAny,
shape: structuralMatcher,
} as const;
export type Pattern<T> = Matcher<T>;
src/primitive-union.test.ts
+761
View File
@@ -0,0 +1,761 @@
import { strict as assert } from "node:assert";
import path from "node:path";
import { test } from "node:test";
import { expectTypeOf } from "expect-type";
import {
type CompletionTarget,
LspSession,
} from "#test-utils/lsp-completion.ts";
import {
getPrimitiveUnionMatcher,
getPrimitiveUnionMatcherW,
} from "./primitive-union.ts";
// ============================================================================
// API: getPrimitiveUnionMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
// ============================================================================
test("getPrimitiveUnionMatcher: exhaustive pattern infers one common return type", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<"a" | "b">();
// Act
const matcher = factory({
a: (s) => {
expectTypeOf(s).toEqualTypeOf<"a">();
assert.equal(s, "a");
return 1;
},
b: (s) => {
expectTypeOf(s).toEqualTypeOf<"b">();
assert.equal(s, "b");
return 2;
},
});
// Assert
// ✔️ ReturnsStrict: R is the best common return type, not a widening union.
expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => number>();
// ❌ a value outside T must not be accepted by the matcher
expectTypeOf<"c">().not.toExtend<Parameters<typeof matcher>[0]>();
assert.equal(matcher("a"), 1);
assert.equal(matcher("b"), 2);
});
test("getPrimitiveUnionMatcher: dispatches on numeric literal keys", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<1 | 2>();
// Act
const matcher = factory({
1: (n) => {
expectTypeOf(n).toEqualTypeOf<1>();
// A numeric key must not reach its handler as the string `"1"`.
assert.equal(n, 1);
return n + 1;
},
2: (n) => {
expectTypeOf(n).toEqualTypeOf<2>();
assert.equal(n, 2);
return n * 10;
},
});
// Assert
expectTypeOf(matcher).toEqualTypeOf<(shape: 1 | 2) => number>();
assert.equal(matcher(1), 2);
assert.equal(matcher(2), 20);
});
test("getPrimitiveUnionMatcher: dispatches on mixed string and numeric keys", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<"a" | "b" | 1 | 2>();
// Act
const matcher = factory({
a: (s) => {
expectTypeOf(s).toEqualTypeOf<"a">();
assert.equal(s, "a");
return 1;
},
b: (s) => {
expectTypeOf(s).toEqualTypeOf<"b">();
assert.equal(s, "b");
return 2;
},
1: (n) => {
expectTypeOf(n).toEqualTypeOf<1>();
assert.equal(n, 1);
return 10;
},
2: (n) => {
expectTypeOf(n).toEqualTypeOf<2>();
assert.equal(n, 2);
return 20;
},
});
// Assert
expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => number>();
assert.equal(matcher("a"), 1);
assert.equal(matcher("b"), 2);
assert.equal(matcher(1), 10);
assert.equal(matcher(2), 20);
});
test("getPrimitiveUnionMatcher: dispatches on boolean literals", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<boolean>();
// Act
const matcher = factory({
true: (s) => {
expectTypeOf(s).toEqualTypeOf<true>();
// The `true` key is a property name; the handler must still be
// called with the boolean `true`, not the string `"true"`.
assert.equal(s, true);
return 1;
},
false: (s) => {
expectTypeOf(s).toEqualTypeOf<false>();
assert.equal(s, false);
return 2;
},
});
// Assert
expectTypeOf(matcher).toEqualTypeOf<(shape: boolean) => number>();
assert.equal(matcher(true), 1);
assert.equal(matcher(false), 2);
});
test("getPrimitiveUnionMatcher: dispatches on null and undefined", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<null | undefined>();
// Act
const matcher = factory({
null: (s) => {
expectTypeOf(s).toEqualTypeOf<null>();
assert.equal(s, null);
return "null";
},
undefined: (s) => {
expectTypeOf(s).toEqualTypeOf<undefined>();
assert.equal(s, undefined);
return "undefined";
},
});
// Assert
expectTypeOf(matcher).toEqualTypeOf<(shape: null | undefined) => string>();
assert.equal(matcher(null), "null");
assert.equal(matcher(undefined), "undefined");
});
// ============================================================================
// API: getPrimitiveUnionMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict
// ============================================================================
test("getPrimitiveUnionMatcher: a `_` fallback receives the unhandled keys", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<"a" | "b" | "c">();
// Act
const matcher = factory(
{
a: (s) => {
expectTypeOf(s).toEqualTypeOf<"a">();
assert.equal(s, "a");
return 1 as const;
},
},
(s) => {
// The fallback sees only the keys `a` did not handle.
expectTypeOf(s).toEqualTypeOf<"b" | "c">();
assert.ok(s === "b" || s === "c");
return 2 as const;
},
);
// Assert
expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | "c") => 1 | 2>();
// ❌ a value outside T must not be accepted by the matcher
expectTypeOf<"d">().not.toExtend<Parameters<typeof matcher>[0]>();
assert.equal(matcher("a"), 1);
assert.equal(matcher("b"), 2);
assert.equal(matcher("c"), 2);
});
test("getPrimitiveUnionMatcher: a `_` fallback routes mixed string and numeric gaps", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<"a" | "b" | 1 | 2>();
// Act
const matcher = factory(
{
a: (s) => {
expectTypeOf(s).toEqualTypeOf<"a">();
assert.equal(s, "a");
return "A";
},
1: (n) => {
expectTypeOf(n).toEqualTypeOf<1>();
assert.equal(n, 1);
return "one";
},
},
(s) => {
expectTypeOf(s).toEqualTypeOf<"b" | 2>();
// The gap mixes a string and a number, so the number must reach the
// fallback as `2`, never as its key text `"2"`.
assert.ok(s === "b" || s === 2);
return "fallback";
},
);
// Assert
expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => string>();
assert.equal(matcher("a"), "A");
assert.equal(matcher("b"), "fallback");
assert.equal(matcher(1), "one");
assert.equal(matcher(2), "fallback");
});
test("getPrimitiveUnionMatcher: a `_` fallback receives unhandled boolean and nullish keys", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<
"a" | true | false | null | undefined
>();
// Act
const matcher = factory(
{
a: (s) => {
expectTypeOf(s).toEqualTypeOf<"a">();
assert.equal(s, "a");
return 1 as const;
},
null: (s) => {
expectTypeOf(s).toEqualTypeOf<null>();
assert.equal(s, null);
return 2 as const;
},
},
(s) => {
// `true` and `false` are keyed as `"true"`/`"false"` but the
// fallback still sees them as booleans.
expectTypeOf(s).toEqualTypeOf<true | false | undefined>();
assert.ok(s === true || s === false || s === undefined);
return 3 as const;
},
);
// Assert
expectTypeOf(matcher).toEqualTypeOf<
(shape: "a" | true | false | null | undefined) => 1 | 2 | 3
>();
assert.equal(matcher("a"), 1);
assert.equal(matcher(true), 3);
assert.equal(matcher(false), 3);
assert.equal(matcher(null), 2);
assert.equal(matcher(undefined), 3);
});
// ============================================================================
// API: getPrimitiveUnionMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
// ============================================================================
test("getPrimitiveUnionMatcherW: exhaustive pattern widens to the union of handler returns", () => {
// Arrange
const factory = getPrimitiveUnionMatcherW<"x" | "y">();
// Act
const matcher = factory({
x: (s) => {
expectTypeOf(s).toEqualTypeOf<"x">();
assert.equal(s, "x");
return 1 as const;
},
y: (s) => {
expectTypeOf(s).toEqualTypeOf<"y">();
assert.equal(s, "y");
return "two" as const;
},
});
// Assert
// ❌ ReturnsStrict: mixed handler returns widen to their union.
expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
// ❌ a value outside T must not be accepted by the matcher
expectTypeOf<"z">().not.toExtend<Parameters<typeof matcher>[0]>();
assert.equal(matcher("x"), 1);
assert.equal(matcher("y"), "two");
});
test("getPrimitiveUnionMatcherW: dispatches on mixed string and numeric keys", () => {
// Arrange
const factory = getPrimitiveUnionMatcherW<"a" | "b" | 1 | 2>();
// Act
const matcher = factory({
a: (s) => {
expectTypeOf(s).toEqualTypeOf<"a">();
assert.equal(s, "a");
return "A" as const;
},
b: (s) => {
expectTypeOf(s).toEqualTypeOf<"b">();
assert.equal(s, "b");
return "B" as const;
},
1: (n) => {
expectTypeOf(n).toEqualTypeOf<1>();
assert.equal(n, 1);
return 10 as const;
},
2: (n) => {
expectTypeOf(n).toEqualTypeOf<2>();
assert.equal(n, 2);
return 20 as const;
},
});
// Assert
expectTypeOf(matcher).toEqualTypeOf<
(shape: "a" | "b" | 1 | 2) => "A" | "B" | 10 | 20
>();
assert.equal(matcher("a"), "A");
assert.equal(matcher("b"), "B");
assert.equal(matcher(1), 10);
assert.equal(matcher(2), 20);
});
test("getPrimitiveUnionMatcherW: exhaustive boolean and nullish widen to the union", () => {
// Arrange
const factory = getPrimitiveUnionMatcherW<boolean | null | undefined>();
// Act
const matcher = factory({
true: (s) => {
expectTypeOf(s).toEqualTypeOf<true>();
assert.equal(s, true);
return "yes" as const;
},
false: (s) => {
expectTypeOf(s).toEqualTypeOf<false>();
assert.equal(s, false);
return "no" as const;
},
null: (s) => {
expectTypeOf(s).toEqualTypeOf<null>();
assert.equal(s, null);
return 0 as const;
},
undefined: (s) => {
expectTypeOf(s).toEqualTypeOf<undefined>();
assert.equal(s, undefined);
return 1 as const;
},
});
// Assert
expectTypeOf(matcher).toEqualTypeOf<
(shape: boolean | null | undefined) => "yes" | "no" | 0 | 1
>();
assert.equal(matcher(true), "yes");
assert.equal(matcher(false), "no");
assert.equal(matcher(null), 0);
assert.equal(matcher(undefined), 1);
});
// ============================================================================
// API: getPrimitiveUnionMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict
// ============================================================================
test("getPrimitiveUnionMatcherW: a `_` fallback widens gaps into the union", () => {
// Arrange
const factory = getPrimitiveUnionMatcherW<"x" | "y" | "z">();
// Act
const matcher = factory(
{
x: (s) => {
expectTypeOf(s).toEqualTypeOf<"x">();
assert.equal(s, "x");
return 1 as const;
},
},
(s) => {
// The fallback sees only the keys `x` did not handle.
expectTypeOf(s).toEqualTypeOf<"y" | "z">();
// Returning the shape verbatim lets the `Assert` block check the
// exact value dispatch passed.
return s;
},
);
// Assert
expectTypeOf(matcher).toEqualTypeOf<
(shape: "x" | "y" | "z") => 1 | "y" | "z"
>();
// ❌ a value outside T must not be accepted by the matcher
expectTypeOf<"w">().not.toExtend<Parameters<typeof matcher>[0]>();
assert.equal(matcher("x"), 1);
assert.equal(matcher("y"), "y");
assert.equal(matcher("z"), "z");
});
test("getPrimitiveUnionMatcherW: a `_` fallback widens mixed string and numeric returns", () => {
// Arrange
const factory = getPrimitiveUnionMatcherW<"a" | "b" | 1 | 2>();
// Act
const matcher = factory(
{
a: (s) => {
expectTypeOf(s).toEqualTypeOf<"a">();
assert.equal(s, "a");
return "A" as const;
},
1: (n) => {
expectTypeOf(n).toEqualTypeOf<1>();
assert.equal(n, 1);
return 10 as const;
},
},
(s) => {
expectTypeOf(s).toEqualTypeOf<"b" | 2>();
// The number must arrive as `2`, not as its key text `"2"`.
assert.ok(s === "b" || s === 2);
// Returning the shape verbatim lets the `Assert` block check the
// exact value dispatch passed.
return s;
},
);
// Assert
// ❌ ReturnsStrict: mixed handler returns widen to their union.
expectTypeOf(matcher).toEqualTypeOf<
(shape: "a" | "b" | 1 | 2) => "A" | 10 | "b" | 2
>();
assert.equal(matcher("a"), "A");
assert.equal(matcher("b"), "b");
assert.equal(matcher(1), 10);
assert.equal(matcher(2), 2);
});
// ============================================================================
// Factory contracts — calls that must not compile
// ============================================================================
test("getPrimitiveUnionMatcher factory rejects patterns outside its contract", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<"a" | "b">();
// Act / Assert — the calls below must not compile.
// `Parameters<typeof factory>[0]` resolves only the *last* overload, so it
// is not a sound "rejected" oracle (an accepted partial pattern does not
// extend it either); the call sites are the oracle instead.
factory({
a: () => 1,
b: () => 2,
// @ts-expect-error `c` is not part of the universe `"a" | "b"`
c: () => 3,
});
// @ts-expect-error a gap without a `_` fallback is not exhaustive
factory({ a: () => 1 });
// @ts-expect-error a `string` fallback does not fit the `number` handler
factory({ a: () => 1 }, () => "x");
// @ts-expect-error a fallback is redundant once the map covers the universe
factory({ a: () => 1, b: () => 2 }, () => 0);
});
test("getPrimitiveUnionMatcher factory rejects non-exhaustive boolean and nullish maps", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<boolean | null | undefined>();
// Act / Assert — the calls below must not compile
// @ts-expect-error only `true` is handled; `false`, `null`, `undefined` are not
factory({ true: () => 1 });
// @ts-expect-error `null` and `undefined` are not handled
factory({ true: () => 1, false: () => 2 });
factory(
// @ts-expect-error a fallback is redundant once the map covers the universe
{
true: () => 1,
false: () => 2,
null: () => 3,
undefined: () => 4,
},
() => 0,
);
});
test("getPrimitiveUnionMatcher: an open universe keeps the fallback's remainder open", () => {
// Arrange
const factory = getPrimitiveUnionMatcher<string>();
// Act
const matcher = factory({ a: () => 1 }, (s) => {
// The map's literal keys do not close an open universe, so the
// remainder stays `string` and the fallback is not redundant.
expectTypeOf(s).toEqualTypeOf<string>();
// A strict pattern fixes one `R` for every handler, so this fallback
// cannot return its shape; `typeof` is the strongest claim the value
// makes on its own — any string passes, including `""`.
assert.equal(typeof s, "string");
return 2 as const;
});
// Assert
expectTypeOf(matcher).toEqualTypeOf<(shape: string) => number>();
assert.equal(matcher("a"), 1);
assert.equal(matcher("b"), 2);
});
test("getPrimitiveUnionMatcherW factory rejects patterns outside its contract", () => {
// Arrange
const factory = getPrimitiveUnionMatcherW<"x" | "y">();
// Act / Assert — the calls below must not compile
factory({
x: () => 1 as const,
y: () => 2 as const,
// @ts-expect-error `z` is not part of the universe `"x" | "y"`
z: () => 3 as const,
});
// @ts-expect-error a gap without a `_` fallback is not exhaustive
factory({ x: () => 1 as const });
// @ts-expect-error a fallback is redundant once the map covers the universe
factory({ x: () => 1 as const, y: () => 2 as const }, () => 0);
});
// ============================================================================
// Dispatch — runtime behavior
// ============================================================================
test("getPrimitiveUnionMatcher: an unhandled shape throws without a fallback", () => {
// Arrange — an open universe types its handler map as an index signature,
// so the type system cannot prove the runtime map is exhaustive.
const handlers: Record<string, (shape: unknown) => number> = {
a: (shape) => {
// The raw shape reaches the handler, not the property key's text.
assert.equal(shape, "a");
return 1;
},
};
const matcher = getPrimitiveUnionMatcher<string>()(handlers);
// Act / Assert
assert.equal(matcher("a"), 1);
assert.throws(() => matcher("b"), /Unhandled shape: b/);
});
test("getPrimitiveUnionMatcher: an unhandled boolean shape throws without a fallback", () => {
// Arrange — an `string | boolean` universe widens its handler map to an
// index signature, so the runtime map's exhaustiveness is not provable.
const handlers: Record<string, (shape: unknown) => number> = {
true: (shape) => {
// `true` indexes the map as the property `"true"`, but the handler
// is still called with the boolean.
assert.equal(shape, true);
return 1;
},
};
const matcher = getPrimitiveUnionMatcher<string | boolean>()(handlers);
// Act / Assert
assert.equal(matcher(true), 1);
assert.throws(() => matcher(false), /Unhandled shape: false/);
});
// ============================================================================
// Autocomplete — the language server is the oracle, not the type system
// ============================================================================
// Completion is a contextual-type property that the type system cannot observe,
// so the cases below read the popup from the repo's language server (via the
// test helper) rather than pairing `expectTypeOf` with `assert` — see
// development/testing.md § Autocomplete. They probe the *matcher's* overloads,
// which is why they live with the matcher and not with the helper.
const REPO_ROOT = path.resolve(import.meta.dirname, "..");
const UNIVERSE = `"a" | "b" | "c"`;
// One session per probe: the tests share no language-server state (open
// documents, project membership), so they pass in any order.
interface LabelsProbe {
readonly name: string;
readonly factory: "getPrimitiveUnionMatcher" | "getPrimitiveUnionMatcherW";
readonly body: string;
readonly universe?: string;
readonly tail?: string;
}
const labelsFor = ({
name,
factory,
body,
universe = UNIVERSE,
tail = "",
}: LabelsProbe): Promise<readonly string[]> => {
const session = new LspSession(REPO_ROOT);
const target: CompletionTarget = {
file: `src/__autocomplete_${name}.ts`,
source: [
`import { ${factory} } from "./index.ts";`,
`const m = ${factory}<${universe}>()({`,
body,
`}${tail});`,
"",
].join("\n"),
};
return session
.completionLabelsAt(target)
.then((result) => result.labels)
.finally(() => session.close());
};
test("autocomplete: an exhaustive pattern requires the universe", () => {
// Arrange
const name = "getPrimitiveUnionMatcher_fresh";
// Act
const labels = labelsFor({
name,
factory: "getPrimitiveUnionMatcher",
body: " /*COMPLETE*/",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["a", "b", "c"]);
});
});
test("autocomplete: handled keys drop out of the popup", () => {
// Arrange
const name = "getPrimitiveUnionMatcher_after_key";
// Act
const labels = labelsFor({
name,
factory: "getPrimitiveUnionMatcher",
body: " a: () => 1,\n /*COMPLETE*/",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["b", "c"]);
});
});
test("autocomplete: a fallback makes the remaining keys optional", () => {
// Arrange
const name = "getPrimitiveUnionMatcher_with_fallback";
// Act
const labels = labelsFor({
name,
factory: "getPrimitiveUnionMatcher",
body: " /*COMPLETE*/",
tail: ", () => 0",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["a?", "b?", "c?"]);
});
});
test("autocomplete: with a fallback, handled keys stay optional", () => {
// Arrange
const name = "getPrimitiveUnionMatcher_with_fallback_after_key";
// Act
const labels = labelsFor({
name,
factory: "getPrimitiveUnionMatcher",
body: " a: () => 1,\n /*COMPLETE*/",
tail: ", () => 0",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["b?", "c?"]);
});
});
test("autocomplete: `getPrimitiveUnionMatcherW` offers the same popup as `getPrimitiveUnionMatcher`", () => {
// Arrange
const name = "getPrimitiveUnionMatcherW_fresh";
// Act
const labels = labelsFor({
name,
factory: "getPrimitiveUnionMatcherW",
body: " /*COMPLETE*/",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["a", "b", "c"]);
});
});
test("autocomplete: `getPrimitiveUnionMatcherW` also offers optional keys with a fallback", () => {
// Arrange
const name = "getPrimitiveUnionMatcherW_with_fallback";
// Act
const labels = labelsFor({
name,
factory: "getPrimitiveUnionMatcherW",
body: " /*COMPLETE*/",
tail: ", () => 0",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["a?", "b?", "c?"]);
});
});
test("autocomplete: boolean and nullish keys are offered by name", () => {
// Arrange
const name = "getPrimitiveUnionMatcher_boolean_nullish";
// Act
const labels = labelsFor({
name,
factory: "getPrimitiveUnionMatcher",
universe: "boolean | null | undefined",
body: " /*COMPLETE*/",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["false", "null", "true", "undefined"]);
});
});
test("autocomplete: a handled boolean literal drops out of the popup", () => {
// Arrange
const name = "getPrimitiveUnionMatcher_boolean_after_key";
// Act
const labels = labelsFor({
name,
factory: "getPrimitiveUnionMatcher",
universe: "boolean | null | undefined",
body: " true: () => 1,\n /*COMPLETE*/",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["false", "null", "undefined"]);
});
});
src/primitive-union.ts
+103
View File
@@ -0,0 +1,103 @@
import type { Exact } from "type-fest";
import type {
HandlerMap,
Matchable,
PatternKey,
PatternParam,
PatternReturns,
RedundantFallback,
UnaryFn,
} from "./matcher-shared.ts";
type Handlers<T extends Matchable, R> = {
[K in PatternKey<T>]: UnaryFn<PatternParam<K>, R>;
};
// The fallback is a *second argument*, not a property of the handler map,
// because its parameter is the remainder `Exclude<T, keyof Handled>` and TypeScript
// fixes a property's contextual type before it infers its sibling keys. A later
// argument, by contrast, is contextually typed from inference on an earlier
// one, so the split is what makes the remainder expressible at all.
// See development/library.md.
type Fallback<T extends Matchable, Handled, R> = UnaryFn<
Exclude<T, PatternParam<keyof Handled>>,
R
>;
// A fallback is redundant once the handler map covers `T`. The guard is folded
// into `Handled`'s own (self-referential) constraint so it is checked *after*
// inference; a conditional in the fallback's parameter type is evaluated while
// `Handled` is still its constraint and would reject context-sensitive partial
// maps. That placement also fixes where the diagnostic lands: the constraint
// failure is reported on the argument that inferred `Handled` (the handler
// map), so the required property is spelled as the message instead of relying
// on its position. See development/library.md.
type MustBePartial<T extends Matchable, Handled> =
PatternKey<T> extends keyof Handled ? RedundantFallback : unknown;
// TypeScript does not apply the excess-property check to a generic constraint,
// so `Exact` restores it for the generic forms: a handler map can otherwise
// carry keys outside `T`.
// Strict returns: one common `R`. Overload order is load-bearing:
// #1 Handlers (first) -> the exhaustive form and the autocomplete popup
// #2 Fallback (last) -> accepts a partial handler map plus a fallback
interface PrimitiveUnionMatcherStrict<T extends Matchable> {
<R>(handlers: Handlers<T, R>): UnaryFn<T, R>;
<
R,
Handled extends Exact<Partial<Handlers<T, R>>, Handled> &
MustBePartial<T, Handled>,
>(
handlers: Handled & Partial<Handlers<T, R>>,
fallback: Fallback<T, Handled, R>,
): UnaryFn<T, R>;
}
// Widened returns: the union of every handler's return type. `P` is inferred
// from the whole handler map, whose closed constraint supplies the
// contextual/autocomplete type.
interface PrimitiveUnionMatcherWidening<T extends Matchable> {
<P extends Exact<Handlers<T, unknown>, P>>(
handlers: P,
): UnaryFn<T, PatternReturns<P>>;
<
R,
Handled extends Exact<Partial<Handlers<T, unknown>>, Handled> &
MustBePartial<T, Handled>,
>(
handlers: Handled,
fallback: Fallback<T, Handled, R>,
): UnaryFn<T, PatternReturns<Handled> | R>;
}
const dispatch =
(handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
(shape: Matchable): unknown =>
// `handlers[true]` already coerces to the `"true"` property at runtime,
// identical to `handlers[String(shape)]`, so indexing with `shape`
// directly is sound: `shape` is a facade-checked universe member and
// `PatternKey` only ever produces valid property keys. The assertion is
// needed solely because TypeScript forbids indexing with
// `boolean`/`null`/`undefined` (TS2538); it buys the number fast path.
(
handlers[
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
shape as string | number
] ??
fallback ??
(() => {
throw new Error(`Unhandled shape: ${String(shape)}`);
})
)(
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
shape as never,
);
export const getPrimitiveUnionMatcher = <
T extends Matchable,
>(): PrimitiveUnionMatcherStrict<T> => dispatch;
export const getPrimitiveUnionMatcherW = <
T extends Matchable,
>(): PrimitiveUnionMatcherWidening<T> => dispatch;
src/tagged-union.test.ts
+640
View File
@@ -0,0 +1,640 @@
import { strict as assert } from "node:assert";
import path from "node:path";
import { test } from "node:test";
import { expectTypeOf } from "expect-type";
import {
type CompletionTarget,
LspSession,
} from "#test-utils/lsp-completion.ts";
import {
getTaggedUnionMatcher,
getTaggedUnionMatcherW,
} from "./tagged-union.ts";
interface Circle {
readonly kind: "circle";
readonly radius: number;
}
interface Square {
readonly kind: "square";
readonly side: number;
}
interface Triangle {
readonly kind: "triangle";
readonly base: number;
readonly height: number;
}
type Shape = Circle | Square | Triangle;
// ============================================================================
// API: getTaggedUnionMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
// ============================================================================
test("getTaggedUnionMatcher: exhaustive pattern infers one common return type", () => {
// Arrange
const factory = getTaggedUnionMatcher<Shape>()("kind");
// Act
const area = factory({
circle: (s) => {
// Each handler receives the member its tag selects, not the union.
expectTypeOf(s).toEqualTypeOf<Circle>();
assert.equal(s.kind, "circle");
return Math.PI * s.radius ** 2;
},
square: (s) => {
expectTypeOf(s).toEqualTypeOf<Square>();
assert.equal(s.kind, "square");
return s.side ** 2;
},
triangle: (s) => {
expectTypeOf(s).toEqualTypeOf<Triangle>();
assert.equal(s.kind, "triangle");
return (s.base * s.height) / 2;
},
});
// Assert
// ✔️ ReturnsStrict: R is the best common return type, not a widening union.
expectTypeOf(area).toEqualTypeOf<(shape: Shape) => number>();
assert.equal(area({ kind: "square", side: 2 }), 4);
assert.equal(area({ kind: "triangle", base: 2, height: 3 }), 3);
});
test("getTaggedUnionMatcher: dispatches on numeric tags", () => {
// Arrange
type Version =
| { readonly kind: 1; readonly a: number }
| {
readonly kind: 2;
readonly b: number;
};
const factory = getTaggedUnionMatcher<Version>()("kind");
// Act
const pick = factory({
1: (v) => {
expectTypeOf(v).toEqualTypeOf<{
readonly kind: 1;
readonly a: number;
}>();
assert.equal(v.kind, 1);
return v.a;
},
2: (v) => {
expectTypeOf(v).toEqualTypeOf<{
readonly kind: 2;
readonly b: number;
}>();
assert.equal(v.kind, 2);
return v.b;
},
});
// Assert
expectTypeOf(pick).toEqualTypeOf<(shape: Version) => number>();
assert.equal(pick({ kind: 1, a: 10 }), 10);
assert.equal(pick({ kind: 2, b: 20 }), 20);
});
test("getTaggedUnionMatcher: dispatches on boolean tags", () => {
// Arrange — a boolean discriminant is not a property key, so the handler
// map is keyed `true`/`false` and the callback still receives the boolean.
interface Ok {
readonly status: true;
readonly value: number;
}
interface Err {
readonly status: false;
readonly message: string;
}
type Result = Ok | Err;
const factory = getTaggedUnionMatcher<Result>()("status");
// Act
const pick = factory({
true: (s) => {
expectTypeOf(s).toEqualTypeOf<Ok>();
assert.equal(s.status, true);
return s.value;
},
false: (s) => {
expectTypeOf(s).toEqualTypeOf<Err>();
assert.equal(s.status, false);
return s.message.length;
},
});
// Assert
expectTypeOf(pick).toEqualTypeOf<(shape: Result) => number>();
assert.equal(pick({ status: true, value: 3 }), 3);
assert.equal(pick({ status: false, message: "hi" }), 2);
});
test("getTaggedUnionMatcher: dispatches on null and undefined tags", () => {
// Arrange
type Maybe =
| { readonly kind: null; readonly text: string }
| { readonly kind: undefined; readonly code: number };
const factory = getTaggedUnionMatcher<Maybe>()("kind");
// Act
const pick = factory({
null: (s) => {
expectTypeOf(s).toEqualTypeOf<{
readonly kind: null;
readonly text: string;
}>();
assert.equal(s.kind, null);
return s.text.length;
},
undefined: (s) => {
expectTypeOf(s).toEqualTypeOf<{
readonly kind: undefined;
readonly code: number;
}>();
assert.equal(s.kind, undefined);
return s.code;
},
});
// Assert
expectTypeOf(pick).toEqualTypeOf<(shape: Maybe) => number>();
assert.equal(pick({ kind: null, text: "hi" }), 2);
assert.equal(pick({ kind: undefined, code: 7 }), 7);
});
test("getTaggedUnionMatcher: a fallback receives unhandled boolean and nullish members", () => {
// Arrange
type Mixed =
| { readonly kind: "a"; readonly a: number }
| { readonly kind: true; readonly b: number }
| { readonly kind: false; readonly c: number }
| { readonly kind: null; readonly d: number };
const factory = getTaggedUnionMatcher<Mixed>()("kind");
// Act
const pick = factory({ a: () => 1 as const }, (s) => {
// The fallback sees the real members, not the projected keys.
expectTypeOf(s).toEqualTypeOf<
| { readonly kind: true; readonly b: number }
| { readonly kind: false; readonly c: number }
| { readonly kind: null; readonly d: number }
>();
// `true`/`false`/`null` are keyed as `"true"`/`"false"`/`"null"`,
// but the fallback still receives the boolean/null, not the string.
assert.ok(s.kind === true || s.kind === false || s.kind === null);
return 2 as const;
});
// Assert
expectTypeOf(pick).toEqualTypeOf<(shape: Mixed) => 1 | 2>();
assert.equal(pick({ kind: "a", a: 1 }), 1);
assert.equal(pick({ kind: true, b: 1 }), 2);
assert.equal(pick({ kind: false, c: 1 }), 2);
assert.equal(pick({ kind: null, d: 1 }), 2);
});
test("getTaggedUnionMatcherW: boolean and nullish tags widen to the union", () => {
// Arrange
type Maybe =
| { readonly kind: true; readonly a: number }
| { readonly kind: false; readonly b: number }
| { readonly kind: null; readonly c: number };
const factory = getTaggedUnionMatcherW<Maybe>()("kind");
// Act
const matcher = factory({
true: (s) => {
expectTypeOf(s).toEqualTypeOf<{
readonly kind: true;
readonly a: number;
}>();
assert.equal(s.kind, true);
return "yes" as const;
},
false: (s) => {
expectTypeOf(s).toEqualTypeOf<{
readonly kind: false;
readonly b: number;
}>();
assert.equal(s.kind, false);
return 0 as const;
},
null: (s) => {
expectTypeOf(s).toEqualTypeOf<{
readonly kind: null;
readonly c: number;
}>();
assert.equal(s.kind, null);
return null;
},
});
// Assert
expectTypeOf(matcher).toEqualTypeOf<(shape: Maybe) => "yes" | 0 | null>();
assert.equal(matcher({ kind: true, a: 1 }), "yes");
assert.equal(matcher({ kind: false, b: 1 }), 0);
assert.equal(matcher({ kind: null, c: 1 }), null);
});
// ============================================================================
// API: getTaggedUnionMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict
// ============================================================================
test("getTaggedUnionMatcher: a fallback receives the unhandled members", () => {
// Arrange
const factory = getTaggedUnionMatcher<Shape>()("kind");
// Act
const area = factory(
{
circle: (s) => {
expectTypeOf(s).toEqualTypeOf<Circle>();
assert.equal(s.kind, "circle");
return 1 as const;
},
},
(s) => {
// The fallback sees only the members `circle` did not handle.
expectTypeOf(s).toEqualTypeOf<Square | Triangle>();
assert.ok(s.kind === "square" || s.kind === "triangle");
return 2 as const;
},
);
// Assert
expectTypeOf(area).toEqualTypeOf<(shape: Shape) => 1 | 2>();
assert.equal(area({ kind: "circle", radius: 1 }), 1);
assert.equal(area({ kind: "square", side: 1 }), 2);
assert.equal(area({ kind: "triangle", base: 1, height: 1 }), 2);
});
test("getTaggedUnionMatcher: an open discriminant keeps the fallback open", () => {
// Arrange
interface Message {
readonly kind: string;
readonly text: string;
}
const factory = getTaggedUnionMatcher<Message>()("kind");
// Act
const matcher = factory({ info: () => 1 as const }, (s) => {
// The map's literal key does not close an open discriminant, so the
// remainder stays `Message` and the fallback is not redundant.
expectTypeOf(s).toEqualTypeOf<Message>();
assert.equal(typeof s.text, "string");
return 2 as const;
});
// Assert
expectTypeOf(matcher).toEqualTypeOf<(shape: Message) => 1 | 2>();
assert.equal(matcher({ kind: "info", text: "" }), 1);
assert.equal(matcher({ kind: "warn", text: "" }), 2);
});
// ============================================================================
// API: getTaggedUnionMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
// ============================================================================
test("getTaggedUnionMatcherW: exhaustive pattern widens to the union of returns", () => {
// Arrange
const factory = getTaggedUnionMatcherW<Shape>()("kind");
// Act
const describe = factory({
circle: (s) => {
expectTypeOf(s).toEqualTypeOf<Circle>();
assert.equal(s.kind, "circle");
return "round" as const;
},
square: (s) => {
expectTypeOf(s).toEqualTypeOf<Square>();
assert.equal(s.kind, "square");
return 4 as const;
},
triangle: (s) => {
expectTypeOf(s).toEqualTypeOf<Triangle>();
assert.equal(s.kind, "triangle");
return true as const;
},
});
// Assert
// ❌ ReturnsStrict: mixed handler returns widen to their union.
expectTypeOf(describe).toEqualTypeOf<
(shape: Shape) => "round" | 4 | true
>();
assert.equal(describe({ kind: "circle", radius: 1 }), "round");
assert.equal(describe({ kind: "square", side: 1 }), 4);
assert.equal(describe({ kind: "triangle", base: 1, height: 1 }), true);
});
// ============================================================================
// API: getTaggedUnionMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict
// ============================================================================
test("getTaggedUnionMatcherW: a fallback widens gaps into the union", () => {
// Arrange
const factory = getTaggedUnionMatcherW<Shape>()("kind");
// Act
const matcher = factory({ circle: () => 1 as const }, (s) => {
expectTypeOf(s).toEqualTypeOf<Square | Triangle>();
// Returning the member verbatim lets the `Assert` block check the
// exact value dispatch passed.
return s;
});
// Assert
expectTypeOf(matcher).toEqualTypeOf<
(shape: Shape) => 1 | Square | Triangle
>();
assert.equal(matcher({ kind: "circle", radius: 1 }), 1);
assert.deepEqual(matcher({ kind: "square", side: 1 }), {
kind: "square",
side: 1,
});
assert.deepEqual(matcher({ kind: "triangle", base: 1, height: 1 }), {
kind: "triangle",
base: 1,
height: 1,
});
});
// ============================================================================
// Factory contracts — calls that must not compile
// ============================================================================
test("getTaggedUnionMatcher factory rejects patterns outside its contract", () => {
// Arrange
const factory = getTaggedUnionMatcher<Shape>()("kind");
// Act / Assert — the calls below must not compile
factory({
circle: () => 1,
square: () => 2,
triangle: () => 3,
// @ts-expect-error `hexagon` is not a tag of Shape
hexagon: () => 4,
});
// @ts-expect-error a gap without a fallback is not exhaustive
factory({ circle: () => 1 });
// @ts-expect-error a `string` fallback does not fit the `number` handlers
factory({ circle: () => 1 }, () => "x");
// @ts-expect-error a fallback is redundant once the map covers the union
factory({ circle: () => 1, square: () => 2, triangle: () => 3 }, () => 0);
});
test("getTaggedUnionMatcher factory rejects a non-discriminant key", () => {
// Arrange
type Mixed =
| { readonly id: Date; readonly kind: "a" }
| { readonly id: Date; readonly kind: "b" };
// Act / Assert — the calls below must not compile
// @ts-expect-error `id` is a common key but its value is not a tag
getTaggedUnionMatcher<Mixed>()("id");
getTaggedUnionMatcher<Mixed>()("kind");
});
test("getTaggedUnionMatcher factory rejects non-exhaustive boolean and nullish maps", () => {
// Arrange
type Result =
| { readonly status: true; readonly a: number }
| { readonly status: false; readonly b: number };
type Maybe =
| { readonly status: null; readonly c: number }
| { readonly status: undefined; readonly d: number };
const resultFactory = getTaggedUnionMatcher<Result>()("status");
const maybeFactory = getTaggedUnionMatcher<Maybe>()("status");
// Act / Assert — the calls below must not compile
// @ts-expect-error only `true` is handled; `false` is not
resultFactory({ true: () => 1 });
// @ts-expect-error only `null` is handled; `undefined` is not
maybeFactory({ null: () => 1 });
// @ts-expect-error a fallback is redundant once both tags are handled
resultFactory({ true: () => 1, false: () => 2 }, () => 0);
});
test("getTaggedUnionMatcherW factory rejects patterns outside its contract", () => {
// Arrange
const factory = getTaggedUnionMatcherW<Shape>()("kind");
// Act / Assert — the calls below must not compile
factory({
circle: () => 1 as const,
square: () => 2 as const,
triangle: () => 3 as const,
// @ts-expect-error `hexagon` is not a tag of Shape
hexagon: () => 4 as const,
});
// @ts-expect-error a gap without a fallback is not exhaustive
factory({ circle: () => 1 as const });
factory(
// @ts-expect-error a fallback is redundant once the map covers the union
{
circle: () => 1 as const,
square: () => 2 as const,
triangle: () => 3 as const,
},
() => 0,
);
});
// ============================================================================
// Dispatch — runtime behavior
// ============================================================================
test("getTaggedUnionMatcher: an unhandled tag throws without a fallback", () => {
// Arrange — an open discriminant widens its handler map to an index
// signature, so the type system cannot prove the runtime map is exhaustive.
interface Message {
readonly kind: string;
}
const handlers: Record<string, (shape: Message) => number> = {
info: (shape) => {
// The full member reaches the handler, not its tag.
assert.equal(shape.kind, "info");
return 1;
},
};
const matcher = getTaggedUnionMatcher<Message>()("kind")(handlers);
// Act / Assert
assert.equal(matcher({ kind: "info" }), 1);
assert.throws(() => matcher({ kind: "warn" }), /Unhandled tag: warn/);
});
// ============================================================================
// Autocomplete — the language server is the oracle, not the type system
// ============================================================================
const REPO_ROOT = path.resolve(import.meta.dirname, "..");
const SHAPE_SOURCE = `type Shape = { kind: "a"; a: number } | { kind: "b"; b: number } | { kind: "c"; c: number };`;
interface LabelsProbe {
readonly name: string;
readonly factory: "getTaggedUnionMatcher" | "getTaggedUnionMatcherW";
readonly body: string;
readonly tail?: string;
readonly typeName?: string;
readonly typeSource?: string;
}
const labelsFor = ({
name,
factory,
body,
tail = "",
typeName = "Shape",
typeSource = SHAPE_SOURCE,
}: LabelsProbe): Promise<readonly string[]> => {
const session = new LspSession(REPO_ROOT);
const target: CompletionTarget = {
file: `src/__autocomplete_${name}.ts`,
source: [
`import { ${factory} } from "./index.ts";`,
typeSource,
`const m = ${factory}<${typeName}>()("kind")({`,
body,
`}${tail});`,
"",
].join("\n"),
};
return session
.completionLabelsAt(target)
.then((result) => result.labels)
.finally(() => session.close());
};
test("autocomplete: a tagged-union pattern requires the tags", () => {
// Arrange
const name = "tagged_union_fresh";
// Act
const labels = labelsFor({
name,
factory: "getTaggedUnionMatcher",
body: " /*COMPLETE*/",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["a", "b", "c"]);
});
});
test("autocomplete: a handled tag drops out of the popup", () => {
// Arrange
const name = "tagged_union_after_key";
// Act
const labels = labelsFor({
name,
factory: "getTaggedUnionMatcher",
body: " a: () => 1,\n /*COMPLETE*/",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["b", "c"]);
});
});
test("autocomplete: a fallback makes the remaining tags optional", () => {
// Arrange
const name = "tagged_union_with_fallback";
// Act
const labels = labelsFor({
name,
factory: "getTaggedUnionMatcher",
body: " /*COMPLETE*/",
tail: ", () => 0",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["a?", "b?", "c?"]);
});
});
// `true`/`false`/`null`/`undefined` tags are not property keys, so the popup
// must offer them by name through the `PatternKey` projection.
const STATUS_SOURCE = `type Status = { kind: true; a: number } | { kind: false; b: number } | { kind: null; c: number } | { kind: undefined; d: number };`;
test("autocomplete: boolean and nullish tags are offered by name", () => {
// Arrange
const name = "tagged_union_boolean_nullish";
// Act
const labels = labelsFor({
name,
factory: "getTaggedUnionMatcher",
typeName: "Status",
typeSource: STATUS_SOURCE,
body: " /*COMPLETE*/",
});
// Assert
return labels.then((result) => {
assert.deepEqual([...result], ["false", "null", "true", "undefined"]);
});
});
// `Mixed` has two common keys, but `id`'s value is not a tag, so only `kind`
// may serve as the discriminant.
const MIXED_SOURCE = `type Mixed = { id: Date; kind: "a"; a: number } | { id: Date; kind: "b"; b: number };`;
const discriminantLabelsFor = ({
name,
factory,
typeName,
typeSource,
}: {
readonly name: string;
readonly factory: "getTaggedUnionMatcher" | "getTaggedUnionMatcherW";
readonly typeName: string;
readonly typeSource: string;
}): Promise<readonly string[]> => {
const session = new LspSession(REPO_ROOT);
const target: CompletionTarget = {
file: `src/__autocomplete_${name}.ts`,
source: [
`import { ${factory} } from "./index.ts";`,
typeSource,
`const m = ${factory}<${typeName}>()(/*COMPLETE*/);`,
"",
].join("\n"),
};
return session
.completionLabelsAt(target)
.then((result) => result.labels)
.finally(() => session.close());
};
test("autocomplete: the discriminant key is offered at the key argument", () => {
// Arrange
const name = "tagged_union_discriminant";
// Act
const labels = discriminantLabelsFor({
name,
factory: "getTaggedUnionMatcher",
typeName: "Mixed",
typeSource: MIXED_SOURCE,
});
// Assert
return labels.then((result) => {
// The argument position also offers every global identifier, so assert
// inclusion of the discriminant and exclusion of the non-tag key.
assert.ok(result.includes('"kind"'));
assert.ok(!result.includes('"id"'));
});
});
src/tagged-union.ts
+142
View File
@@ -0,0 +1,142 @@
import type { Exact, UnknownRecord } from "type-fest";
import type {
HandlerMap,
Matchable,
PatternKey,
PatternParam,
PatternReturns,
RedundantFallback,
UnaryFn,
} from "./matcher-shared.ts";
// A tagged union is discriminated by one property whose values are the tags (a
// `Matchable`). `string` and `number` tags key a handler map directly;
// `boolean`, `null` and `undefined` are admitted too but are not property keys,
// so they go through the `PatternKey` projection. `symbol` has no literal syntax
// to write a handler under, and `bigint` is not a property key.
// The discriminant values of `T` under `K`. `Extract` keeps the finite literal
// tags and leaves a widened `string`/`number` as itself, so an open universe
// keeps an open fallback.
type Tags<T extends object, K extends keyof T> = Extract<T[K], Matchable>;
// The keys of `T` that can act as a discriminant. `getTaggedUnionMatcher<T>()`
// accepts only these, so the factory rejects a key whose values are not tags.
type Discriminated<T extends object> = {
[K in keyof T]: T[K] extends Matchable ? K : never;
}[keyof T];
// The member(s) of `T` tagged `V`. `Extract` distributes over the union, so a
// duplicated tag maps to a union of members rather than silently dropping one.
// Keyed by `PatternKey`, so `boolean`/`null`/`undefined` tags can key a mapped
// type; `PatternParam` inverts the projection to recover the member.
type MapTaggedUnion<T extends object, K extends keyof T> = {
[P in PatternKey<Tags<T, K>>]: Extract<T, Record<K, PatternParam<P>>>;
};
type Handlers<T extends object, K extends keyof T, R> = {
[P in PatternKey<Tags<T, K>>]: UnaryFn<MapTaggedUnion<T, K>[P], R>;
};
// The members `Handled` covers. Mapping over the projected keys keeps every
// index within `MapTaggedUnion`'s keys, and the conditional drops a stray key
// outside `T` so it cannot widen the remainder. The remainder is
// `Exclude<T, …>`, mirroring the primitive-union matcher's
// `Exclude<T, PatternParam<keyof Handled>>`.
type HandledMembers<T extends object, K extends keyof T, Handled> = {
[P in PatternKey<Tags<T, K>>]: P extends keyof Handled
? MapTaggedUnion<T, K>[P]
: never;
}[PatternKey<Tags<T, K>>];
// The fallback is a *second argument*, not a property of the handler map, so
// its parameter can be the remainder the map left open. See development/library.md.
type Fallback<T extends object, K extends keyof T, Handled, R> = UnaryFn<
Exclude<T, HandledMembers<T, K, Handled>>,
R
>;
// A fallback is redundant once the handler map covers every tag of `T`. Folded
// into `Handled`'s own (self-referential) constraint so it is checked *after*
// inference; see the primitive-union matcher for why a conditional in the fallback's
// parameter is evaluated too early.
type MustBePartial<T extends object, K extends keyof T, Handled> =
PatternKey<Tags<T, K>> extends keyof Handled ? RedundantFallback : unknown;
// TypeScript does not apply the excess-property check to a generic constraint,
// so `Exact` restores it for the generic forms.
// Strict returns: one common `R`. Overload order is load-bearing:
// #1 Handlers (first) -> the exhaustive form and the autocomplete popup
// #2 Fallback (last) -> accepts a partial handler map plus a fallback
interface TaggedUnionMatcherStrict<T extends object, K extends keyof T> {
<R>(handlers: Handlers<T, K, R>): UnaryFn<T, R>;
<
R,
Handled extends Exact<Partial<Handlers<T, K, R>>, Handled> &
MustBePartial<T, K, Handled>,
>(
handlers: Handled & Partial<Handlers<T, K, R>>,
fallback: Fallback<T, K, Handled, R>,
): UnaryFn<T, R>;
}
// Widened returns: the union of every handler's return type. `P` is inferred
// from the whole handler map, whose closed constraint supplies the
// contextual/autocomplete type.
interface TaggedUnionMatcherWidening<T extends object, K extends keyof T> {
<P extends Exact<Handlers<T, K, unknown>, P>>(
handlers: P,
): UnaryFn<T, PatternReturns<P>>;
<
R,
Handled extends Exact<Partial<Handlers<T, K, unknown>>, Handled> &
MustBePartial<T, K, Handled>,
>(
handlers: Handled,
fallback: Fallback<T, K, Handled, R>,
): UnaryFn<T, PatternReturns<Handled> | R>;
}
// The key-taking step of the curried factory. Naming it lets the factory return
// `dispatch` directly, the tacit twin of the primitive-union factory's bare
// `=> dispatch`.
type TaggedUnionMatcherFactory<T extends object> = <K extends Discriminated<T>>(
k: K,
) => TaggedUnionMatcherStrict<T, K>;
type TaggedUnionMatcherWideningFactory<T extends object> = <
K extends Discriminated<T>,
>(
k: K,
) => TaggedUnionMatcherWidening<T, K>;
const dispatch =
(k: PropertyKey) =>
(handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
(shape: object): unknown => {
// `object` carries no index signature, so the read needs the assertion;
// the factory admits only keys whose values are tags, and the map keys
// them by `PatternKey`, so the result is narrowed to the map's key space.
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
const tag = (shape as UnknownRecord)[k] as string | number;
return (
handlers[tag] ??
fallback ??
(() => {
throw new Error(`Unhandled tag: ${String(tag)}`);
})
)(
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
shape as never,
);
};
export const getTaggedUnionMatcher = <
T extends object,
>(): TaggedUnionMatcherFactory<T> => dispatch;
export const getTaggedUnionMatcherW = <
T extends object,
>(): TaggedUnionMatcherWideningFactory<T> => dispatch;
src/util/__tests__/lsp-completion.test.ts
+147
View File
@@ -0,0 +1,147 @@
import { strict as assert } from "node:assert";
import path from "node:path";
import { test } from "node:test";
import { expectTypeOf } from "expect-type";
import {
type CompletionResult,
type CompletionTarget,
LspSession,
} from "#test-utils/lsp-completion.ts";
const REPO_ROOT = path.resolve(import.meta.dirname, "../../..");
// The `#test-utils/*` self-reference (package.json#imports) is the one route
// scattered test files take to reach test helpers; this pins that it resolves
// and types without starting a language server
// (development/testing.md § Test helpers).
test("test-helper home: `#test-utils/…` resolves to the helper and types it", () => {
// Arrange
const target: CompletionTarget = {
file: "src/util/__tests__/lsp-completion.ts",
source: "",
};
// Assert — no session is constructed: the constructor spawns `tsc --lsp`,
// so only the resolved values and their types are checked here.
expectTypeOf(LspSession).toBeConstructibleWith("repo-root");
expectTypeOf<CompletionResult>().toMatchTypeOf<{
labels: readonly string[];
}>();
assert.equal(typeof LspSession, "function");
assert.equal(target.file, "src/util/__tests__/lsp-completion.ts");
});
// The helper drives a language server, so its contract is asserted against the
// server. Every document below is probed from memory and carries its
// contextual type inline, so the helper is tested without the library's code.
const probe = (source: string, marker?: string): Promise<CompletionResult> => {
const session = new LspSession(REPO_ROOT);
const target: CompletionTarget =
marker === undefined
? { file: "src/__probe.ts", source }
: { file: "src/__probe.ts", source, marker };
return session.completionLabelsAt(target).finally(() => session.close());
};
const HANDLERS = [
"type Handlers = { a: () => number; b: () => number; _?: () => number };",
"declare const apply: (handlers: Handlers) => Handlers;",
];
test("helper: a fresh object literal completes with its contextual keys", () => {
// Arrange
const source = [
...HANDLERS,
"const done = apply({",
" /*COMPLETE*/",
"});",
"export { done };",
].join("\n");
// Act
const probed = probe(source);
// Assert — the position is the marker's, which the helper strips
expectTypeOf(probed).toEqualTypeOf<Promise<CompletionResult>>();
return probed.then((result) => {
assert.deepEqual(result.position, { line: 3, character: 4 });
assert.deepEqual([...result.labels], ["_?", "a", "b"]);
});
});
test("helper: a handled key drops out of the popup", () => {
// Arrange
const source = [
...HANDLERS,
"const done = apply({",
" b: () => 1,",
" /*COMPLETE*/",
"});",
"export { done };",
].join("\n");
// Act
const probed = probe(source);
// Assert
expectTypeOf<CompletionResult["labels"]>().toEqualTypeOf<
readonly string[]
>();
return probed.then((result) => {
assert.deepEqual([...result.labels], ["_?", "a"]);
});
});
test("helper: a custom marker is located at the line start", () => {
// Arrange
const source = [
"type Handlers = { a: () => number; _?: () => number };",
"declare const apply: (handlers: Handlers) => Handlers;",
"const done = apply({",
"@@@",
"});",
"export { done };",
].join("\n");
// Act
const probed = probe(source, "@@@");
// Assert
expectTypeOf(probed).resolves.toEqualTypeOf<CompletionResult>();
return probed.then((result) => {
assert.deepEqual(result.position, { line: 3, character: 0 });
assert.deepEqual([...result.labels], ["_?", "a"]);
});
});
test("helper: labels are read from the server, not from a pattern literal", () => {
// Arrange
const source = [
'const text = "x";',
"const upper = text./*COMPLETE*/;",
"export { upper };",
].join("\n");
// Act
const probed = probe(source);
// Assert
expectTypeOf(probed).resolves.toHaveProperty("labels");
return probed.then((result) => {
assert.ok(result.labels.includes("toUpperCase"));
});
});
test("helper: a source without the marker rejects", () => {
// Arrange
const source = "const text = 1;\nexport { text };\n";
// Act
const probed = probe(source);
// Assert
expectTypeOf(probed).resolves.toEqualTypeOf<CompletionResult>();
return assert.rejects(probed, /marker not found/);
});
src/util/__tests__/lsp-completion.ts
+254
View File
@@ -0,0 +1,254 @@
// oxlint-disable no-magic-numbers unicorn/no-null - tolerable here, this is a helper
import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { setTimeout as delay } from "node:timers/promises";
import { pathToFileURL } from "node:url";
import {
type CompletionItem,
type CompletionList,
CompletionRequest,
ConfigurationRequest,
createMessageConnection,
DidOpenTextDocumentNotification,
InitializedNotification,
InitializeRequest,
type MessageConnection,
ShutdownRequest,
StreamMessageReader,
StreamMessageWriter,
} from "vscode-languageserver-protocol/node";
/**
* Print the completion labels TypeScript's language server offers at a marker
* inside a source file.
*
* Usage: node --strip-types src/util/__tests__/lsp-completion.ts <file> [<marker>]
*
* The marker (default `DEFAULT_MARKER`, a `COMPLETE` block comment) is stripped
* from the source before it is sent; the request position is where the marker
* stood. Point it at a scratch file whose expected type is a matcher pattern to
* inspect the popup.
*
* `LspSession` exposes the same probe to the test suite, so completion is
* asserted against the server rather than the type system.
*
* Why a script and not a type assertion: completion is a contextual-type
* property that `expect-type` cannot observe, and `Parameters<…>` resolves only
* a single overload. The server is the only ground truth. See
* development/testing.md § Autocomplete.
*/
const DEFAULT_MARKER = "/*COMPLETE*/";
const ARGV_PREFIX_LENGTH = 2;
const EXIT_DELAY_MS = 200;
const FAILURE_EXIT_CODE = 1;
const USAGE = "usage: lsp-completion.ts <file> [<marker>]";
export interface Position {
readonly line: number;
readonly character: number;
}
/** A document to probe: `source` carries `marker`, which is stripped. */
export interface CompletionTarget {
/** Path relative to the session's repo root; drives URI and resolution. */
readonly file: string;
readonly source: string;
readonly marker?: string;
}
export interface CompletionResult {
readonly position: Position;
readonly labels: readonly string[];
}
const completionLabels = (
result: CompletionItem[] | CompletionList | null,
): readonly string[] => {
if (result === null) {
return [];
}
const items = Array.isArray(result) ? result : result.items;
return items
.map((item) => item.label)
.toSorted((left, right) => left.localeCompare(right));
};
const markerPosition = (source: string, marker: string): Position => {
const index = source.indexOf(marker);
if (index === -1) {
throw new Error(`marker not found: ${marker}`);
}
const lines = source.slice(0, index).split("\n");
const lineIndex = lines.length - 1;
const line = lines[lineIndex];
return { line: lineIndex, character: line === undefined ? 0 : line.length };
};
/**
* One language server, initialized on first use, shared across probes. Callers
* own the lifecycle and must `close()` it.
*/
export class LspSession {
readonly #child: ChildProcessWithoutNullStreams;
readonly #connection: MessageConnection;
readonly #repoRoot: string;
#ready: Promise<void> | undefined;
public constructor(repoRoot: string) {
this.#repoRoot = repoRoot;
this.#child = spawn(
path.join(repoRoot, "node_modules", ".bin", "tsc"),
["--lsp", "--stdio"],
{ cwd: repoRoot },
);
this.#child.stderr.on("data", (chunk: Buffer) => {
process.stderr.write(chunk);
});
this.#connection = createMessageConnection(
new StreamMessageReader(this.#child.stdout),
new StreamMessageWriter(this.#child.stdin),
);
// Server -> client requests the server waits on: answer so it proceeds.
// `workspace/configuration` wants one reply per requested item; a
// catch-all covers the rest (e.g. `client/registerCapability`).
this.#connection.onRequest(ConfigurationRequest.type, ({ items }) =>
items.map(() => null),
);
this.#connection.onRequest(() => null);
this.#connection.listen();
}
public completionLabelsAt(
target: CompletionTarget,
): Promise<CompletionResult> {
return this.#ensureInitialized()
.then(() => this.#open(target))
.then(({ uri, position }) =>
this.#connection
.sendRequest(CompletionRequest.type, {
textDocument: { uri },
position,
context: { triggerKind: 1 },
})
.then((result) => ({
position,
labels: completionLabels(result),
})),
);
}
/** `shutdown` + close stdin, then kill the server; safe after a failed probe. */
public close(): Promise<void> {
return (
this.#connection
.sendRequest(ShutdownRequest.type)
// The TS 7 Go server logs a bare `context canceled` to stderr
// when it handles `exit`; EOF on stdin shuts it down cleanly
// (exit 0, no output) instead.
.then(() => {
this.#child.stdin.end();
})
.then(() => delay(EXIT_DELAY_MS))
.finally(() => {
this.#connection.dispose();
this.#child.kill();
})
);
}
#ensureInitialized(): Promise<void> {
this.#ready ??= this.#initialize();
return this.#ready;
}
#initialize(): Promise<void> {
return this.#connection
.sendRequest(InitializeRequest.type, {
processId: process.pid,
rootUri: pathToFileURL(this.#repoRoot).href,
workspaceFolders: [
{ uri: pathToFileURL(this.#repoRoot).href, name: "repo" },
],
capabilities: {
textDocument: {
completion: {
completionItem: { snippetSupport: false },
},
publishDiagnostics: {},
},
},
})
.then(() =>
this.#connection.sendNotification(
InitializedNotification.type,
{},
),
);
}
#open(target: CompletionTarget): Promise<{
readonly uri: string;
readonly position: Position;
}> {
const absolute = path.resolve(this.#repoRoot, target.file);
const marker = target.marker ?? DEFAULT_MARKER;
const position = markerPosition(target.source, marker);
const text = target.source.replace(marker, "");
const uri = pathToFileURL(absolute).href;
// The server handles `didOpen` in order before the completion request,
// so no settle delay is needed.
return this.#connection
.sendNotification(DidOpenTextDocumentNotification.type, {
textDocument: {
uri,
languageId: "typescript",
version: 1,
text,
},
})
.then(() => ({ uri, position }));
}
}
const main = (args: readonly string[]): Promise<void> => {
const [file, markerArgument] = args;
if (file === undefined) {
process.stderr.write(`${USAGE}\n`);
process.exitCode = FAILURE_EXIT_CODE;
return Promise.resolve();
}
const repoRoot = path.resolve(import.meta.dirname, "../../..");
const absolute = path.resolve(repoRoot, file);
const source = fs.readFileSync(absolute, "utf8");
const session = new LspSession(repoRoot);
return session
.completionLabelsAt({
file,
source,
marker: markerArgument ?? DEFAULT_MARKER,
})
.then(({ position, labels }) => {
process.stdout.write(
`\n[${file}] completions @ ${position.line}:${position.character}:\n${labels.join(", ")}\n`,
);
})
.finally(() => session.close());
};
const isEntryPoint = (): boolean => {
const [entry] = process.argv.slice(1, 2);
return entry !== undefined && import.meta.url === pathToFileURL(entry).href;
};
if (isEntryPoint()) {
main(process.argv.slice(ARGV_PREFIX_LENGTH)).catch((error: unknown) => {
process.stderr.write(
`${error instanceof Error ? error.message : String(error)}\n`,
);
process.exitCode = FAILURE_EXIT_CODE;
});
}