Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/skarab42/result
Provides a robust and type-safe way to handle success and failure outcomes in TypeScript, utilizing symbolic indexing for clear result differentiation.
https://github.com/skarab42/result
error-handling functional-programming typescript
Last synced: 15 days ago
JSON representation
Provides a robust and type-safe way to handle success and failure outcomes in TypeScript, utilizing symbolic indexing for clear result differentiation.
- Host: GitHub
- URL: https://github.com/skarab42/result
- Owner: skarab42
- License: mit
- Created: 2024-01-12T15:52:39.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-04-03T17:34:04.000Z (7 months ago)
- Last Synced: 2024-10-08T09:53:58.965Z (about 1 month ago)
- Topics: error-handling, functional-programming, typescript
- Language: TypeScript
- Homepage:
- Size: 121 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# @skarab/result
`@skarab/result` is a TypeScript library providing a robust pattern for handling success and failure outcomes in a functional programming style. Utilizing advanced TypeScript features, it allows developers to create expressive, type-safe APIs that clearly distinguish between successful results and errors.
## Features
- **Type-Safe Success and Failure Handling:** Clearly differentiate between success and failure cases using TypeScript types.
- **Functional Approach:** Embrace a functional programming style for handling results.
- **Easy to Use:** Simple API with powerful type inference.
## Installation
To install the package, use pnpm, npm or yarn:
## Installation
```bash
pnpm add @skarab/result
```
## Usage
Here's a basic example of how to use `@skarab/result`:
```ts
import { success, failure, isSuccess, unwrap } from '@skarab/result';
function performOperation(): Result {
// some operation
if (/* operation successful */) {
return success(42);
} else {
return failure(new Error('Operation failed'));
}
}
const result = performOperation();
if (isSuccess(result)) {
console.log('Success with value:', unwrap(result));
} else {
console.log('Failure with error:', unwrap(result));
}
```
## API Documentation
### Types
#### `Success`
- A type representing a successful result.
- Contains a value of type `SuccessValue`.
- Indexed by a unique success symbol, ensuring type safety and avoiding property clashes.
#### `Failure`
- A type representing a failure result.
- Contains a value of type `FailureValue`.
- Indexed by a unique failure symbol, providing clear differentiation from the `Success` type.
#### `Result`
- A union type representing either a success or a failure.
- Encapsulates `Success` and `Failure`.
### Functions
#### `success(value: SuccessValue): Success`
- Creates a success result containing the provided value.
- Useful for wrapping successful outcomes in a type-safe manner.
- **Parameters:**
- `value`: The value to be associated with the success.
#### `failure(value: FailureValue): Failure`
- Creates a failure result containing the provided value.
- Ideal for expressing error states or unsuccessful outcomes.
- **Parameters:**
- `value`: The value to be associated with the failure.
#### `isSuccess(result: Result): result is Success`
- A type guard function that checks if a given result is a success.
- Returns `true` if the result is a success, otherwise `false`.
- Helps in narrowing down the type of the result to `Success` when true.
#### `isFailure(result: Result): result is Failure`
- A type guard function that checks if a given result is a failure.
- Returns `true` if the result is a failure, otherwise `false`.
- Assists in type narrowing to `Failure` when the result is a failure.
#### `unwrap(result: Result): FailureValue | SuccessValue`
- Extracts the value from a success or failure result.
- Simplifies the process of accessing the underlying value of a result.
- **Parameters:**
- `result`: The `Result` instance from which the value should be unwrapped.
## Contributing
Contributions are welcome! Please open an issue or submit a pull request for any features or fixes.
## License
This project is licensed under the MIT License.
---
Scaffolded with [@skarab/skaffold](https://www.npmjs.com/package/@skarab/skaffold)