Sourced from ts-pattern's releases.

v5.8.0

TS-Pattern v5.8.0 Release Notes

New Feature: .narrow() Method for Deep Type Narrowing

.narrow() gives you fine-grained control over type narrowing of deeply nested union types during pattern matching.

What is .narrow()?

The .narrow() method allows you to explicitly narrow the input type to exclude all values that have been handled by previous patterns. This is especially useful when working with:

• Deeply nested union types
• Nullable properties at any nesting level
• Complex type structures where you need precise type information

When to Use .narrow()

By default, TS-Pattern automatically narrows top-level union types as you pattern match. However, for deeply nested types, this narrowing doesn't happen automatically to maintain optimal TypeScript performance. The .narrow() method gives you explicit control over when to perform this more computationally expensive operation.

Example Usage

type Input = { user: { role: 'admin' | 'editor' | 'viewer' } };
declare const input: Input;
const result = match(input)
.with({ user: { role: 'admin' } }, handleAdmin)
.narrow() // Explicitly narrow remaining cases
.with({ user: { role: 'editor' } }, handleEditor)
.narrow() // Narrow again if needed
.otherwise((remaining) => {
// remaining.user.role is now precisely 'viewer'
handleViewer(remaining);
});

Additional Improvements

• Improvements to release scripts
• Updated dependencies

Full Changelog: gvergnaud/ts-pattern@v5.7.1...v5.8.0

PRs

• feat: .narrow() method & typechecking perf improvement by @​gvergnaud in gvergnaud/ts-pattern#261

• 999128b Merge pull request #261 from gvergnaud/gvergnaud/feat-narrow-method
• 3ad74bc tooling: add release script
• ad743b7 5.8.0
• eb14da5 feat(narrow): Add docs
• 38aa25d Update roadmap.md
• 1856ad3 feat(narrow): add .narrow() method on Match
• 40e3ccf run audit fix
• See full diff in compare view

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot merge will merge this PR after your CI passes on it
• @dependabot squash and merge will squash and merge this PR after your CI passes on it
• @dependabot cancel merge will cancel a previously requested merge and block automerging
• @dependabot reopen will reopen this PR if it is closed
• @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
• @dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)