<h1 align="center">Neverthrow-Pattern</h1>
npm install neverthrow-pattern
Pattern matching for neverthrow using ts-pattern.
neverthrow-pattern bridges the gap between two powerful TypeScript libraries: neverthrow and ts-pattern. It provides a seamless integration layer that allows you to use pattern matching with the Result type from neverthrow, making your error handling code more expressive, concise, and type-safe.
``typescript
import { match } from "ts-pattern";
import { NP } from "neverthrow-pattern";
import { Result, ok, err } from "neverthrow";
const handleResult = (result: Result
match(result)
.with(NP.ok(), (value) => Success: ${value.value})Error: ${error.value}
.with(NP.ok(42), () => "The answer is 42!")
.with(NP.err(P.string), (error) => )
.exhaustive();
// Usage
handleResult(ok(42)); // "The answer is 42!"
handleResult(ok(7)); // "Success: 7"
handleResult(err("Something went wrong")); // "Error: Something went wrong"
`
- 🎯 Pattern match on neverthrow's Result type: Use expressive pattern matching for both Ok and Err valuesOk
- 🛡️ Type-safe: Full type inference and exhaustiveness checking
- 🧩 Composable patterns: Combine with other ts-pattern patterns for complex matching scenarios
- 🔍 Pattern validation: Match on the inner value of and Err instances
- 📝 Comprehensive type definitions: Works seamlessly with TypeScript
- 🔄 Match type interoperability: Enhances the standard match function to work with neverthrow Results
`bashUsing pnpm
pnpm add neverthrow-pattern
Make sure you have both
neverthrow and ts-pattern installed:`bash
pnpm add neverthrow ts-pattern
`Usage
$3
`typescript
// Import everything under a namespace (recommended)
import { NP } from "neverthrow-pattern";// Import match and other utilities from ts-pattern
import { match, P } from "ts-pattern";
// Import from neverthrow as usual
import { Result, ok, err } from "neverthrow";
`$3
Match on any
Ok or Err value:`typescript
const processResult = (result: Result) =>
match(result)
.with(NP.ok(), ({ value }) => Got success with value: ${value})
.with(NP.err(), ({ error }) => Got error: ${error})
.exhaustive();
`$3
Match on specific values inside
Ok or Err:`typescript
const processApiResult = (
result: Result<
{ status: "success" | "pending"; data: unknown },
{ code: number; message: string }
>
) =>
match(result)
.with(
NP.ok({ status: "success" }),
({ value }) => Success: ${JSON.stringify(value.data)}
)
.with(NP.ok({ status: "pending" }), () => "Operation in progress...")
.with(NP.err({ code: 404 }), () => "Not found")
.with(
NP.err({ code: P.number.gt(500) }),
({ error }) => Server error: ${error.message}
)
.with(NP.err({ code: P.number }), ({ error }) => Error: ${error})
.exhaustive();
`$3
Combine with other patterns from ts-pattern:
`typescript
match(result)
.with(NP.ok(P.when((n) => n > 10)), () => "Got a number greater than 10")
.with(NP.ok(), ({ value }) => Got: ${value})
.with(NP.err(P.string), ({ error }) => Error message: ${error})
.with(NP.err(P.any), () => "Some other error")
.exhaustive();
`$3
> Note: Currently, using
P.select() inside NP.ok() and NP.err() patterns is not supported. For example, NP.ok(P.select()) or NP.err(P.select()) won't work as expected. This feature may be implemented in a future version.$3
The library enhances the standard match function to work better with neverthrow Results.
When using neverthrow-pattern, the
match function from ts-pattern is automatically enhanced to work better with Result types. This means:1. You don't need any special imports or setup - just import the library and start using it
2. The type system correctly distributes union types within Results for precise pattern matching
3. Type inference works properly when destructuring Ok and Err values
API Documentation
$3
-
NP.ok(pattern?): Creates a pattern that matches Ok values
- NP.err(pattern?): Creates a pattern that matches Err valuesBoth functions can be used:
- Without arguments to match any Ok/Err value
- With a pattern to match against the inner value
$3
-
UnwrapOk: Extracts the success type from a Result
- UnwrapErr: Extracts the error type from a ResultFor complete API documentation, please refer to the generated TypeDoc documentation.
Contributing
Contributions are welcome! Here's how you can help:
1. Fork the repository
2. Create a feature branch:
git checkout -b my-new-feature
3. Make your changes
4. Create a changeset to document your changes: pnpm changeset
5. Commit your changes: git commit -am 'Add some feature'
6. Push to the branch: git push origin my-new-feature`Please make sure your code follows the existing style and includes appropriate tests.
For more detailed information, see the CONTRIBUTING.md guide.
This project is licensed under the MIT License - see the LICENSE file for details.
- neverthrow - A type-safe alternative to throwing exceptions
- ts-pattern - The exhaustive Pattern Matching library for TypeScript
- All contributors who have helped improve this library
---
Built with ❤️ for type-safe error handling in TypeScript.