From 4c022a5816f039c5bc44eff9321d1278576587ac Mon Sep 17 00:00:00 2001 From: Devin Bidwell Date: Tue, 26 Aug 2025 20:17:00 -0700 Subject: [PATCH 1/3] Update readme --- README.md | 118 +++++++++++++++++++++++------------------------------- 1 file changed, 51 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 71cc888..0097bf4 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,78 @@ -# TypeScript Rust-Like Utility Types +# Typescript Rust-Like Utility Types -A TypeScript library that provides utility types inspired by Rust's powerful type system, including `Result` and `Option`. These types help to enhance type safety and improve error handling in TypeScript applications. +A Typescript library that provides utility types inspired by Rust's powerful type +system, including `Result` and `Option`. These types help to enhance +type safety and improve error handling in Typescript applications. ## Installation -You can install the library via npm: +You can install the library via `npm`: ```bash -npm install @dbidwell94/ts-utils +npm i @dbidwell94/ts-utils ``` -## Usage - -### Option +```bash +yarn add @dbidwell94/ts-utils +``` -The `Option` type is used to represent a value that can either be `Some(value)` or `None`. This is useful for scenarios where a value may or may not be present. +```bash +pnpm add @dbidwell94/ts-utils +``` -```typescript -import { Option, option } from '@dbidwell94/ts-utils'; +## Documentation -// Example usage -function findUserById(id: string): Option { - const user = database.find(user => user.id === id); - return user ? option.some(user) : option.none(); -} +Documentation is provided via `typedoc` and is published [on GitHub Pages](https://dbidwell94.github.io/ts-utils/) -const userOption = findUserById('123'); +## Quick Start -if (userOption.isSome()) { - console.log(`Found user: ${userOption.value}`); -} else { - console.log('User not found'); -} -``` +### Option -### Result +```ts +import { option, Option } from "@dbidwell94/ts-utils"; -The `Result` type is used to represent the result of an operation that can either succeed with a value of type `T` or fail with an error of type `E`. This is ideal for handling operations that can fail. +const myOption = option.some(123); -```typescript -import { Result, result } from '@dbidwell94/ts-utils'; - -// Example usage -function divide(a: number, b: number): Result { // Result can be used instead of `Result`, however you can make the 2nd type param anything that extends `Error` - if (b === 0) { - return result.err("Cannot divide by zero"); - } - return result.ok(a / b); +function doSomethingWithOptions(optionParam: Option) { + if (optionParam.isSome()) { + console.log(`Option value is ${optionParam.value}`); + } else { + console.log("The provided Option has no value"); + } } -const divideResult = divide(10, 0); +doSomethingWithOptions(myOption); // Option value is 123 +doSomethingWithOptions(option.none()); // The provided Option has no value -if (divideResult.isOk()) { - console.log(`Result: ${result.value}`); -} else { - console.error(`Error: ${result.error}`); +function doSomethingNullishValue(val: number | null | undefined) { + doSomethingWithOptions(option.unknown(val)); } -``` -## API Reference - -### `Option` +doSomethingNullishValue(null); // The provided Option has no value +``` -- `some(value: T)`: Represents a value that is present. -- `none()`: Represents the absence of a value. -- `isSome()`: Returns `true` if the option contains a value. -- `isNone()`: Returns `true` if the option does not contain a value. -- `unwrap()`: Returns the value contained in `Some`, or throws an error if it is `None`. -- `unwrapOr(err: E)`: Returns the value contained in `Some`, or throws the provided error if it is `None`. -- `map(newValue: NewT)`: Maps the value of `T` into a `NewT` if the provided value is `Some`. -- `serialize()`: Converts the `Option` into a serializable Option without any helper functions. Useful if you want to store the `Option` in Redux, or send the value over the net -- `fromSerializableOption(option: SerializableOption)`: Converts a `SerializableOption` into an `Option` with all the helper functions +### Result +```ts +import { result, Result } from "@dbidwell94/ts-utils"; -### `Result` +const myResult = result.ok(123); -- `ok(value: T)`: Represents a successful result. -- `err(error: E)`: Represents a failed result. -- `isOk()`: Returns `true` if the result is successful. -- `isError()`: Returns `true` if the result is an error. -- `unwrap()`: Returns the value contained in `Ok`, or throws an error if it is `Err`. -- `unwrapOr(default: T)`: Returns the value contained in `Ok`, or returns the default value `T`. -- `unwrapOrElse(error: E)`: Returns the value contained in `Ok`, or throws the provided error `E`. -- `ok()`: Converts the `Result` into an `Option`. -- `err()`: Converts the `Result` into an `Option`. -- `mapOk(newValue: NewT)`: Maps the value of `T` into a `NewT`, returning a new `Result`. -- `mapErr(newError: NewE)`: Maps the error `E` into a `NewE`, returning a new `Result`. +function doSomethingWithResult(resultParam: Result) { + if (resultParam.isOk()) { + console.log(`The provided value was ${resultParam.value}`); + } else { + console.log( + `The provided Result errored with ${resultParam.error.toString()}`, + ); + } +} +``` ## Contributing -Contributions are welcome! Please open an issue or submit a pull request if you'd like to add features or fix bugs. +Contributions are welcome! Please open an issue or submit a pull request if +you'd like to add features or fix bugs. 1. Fork the repository. 2. Create a new branch (`git checkout -b feature-branch`). @@ -100,9 +83,10 @@ Contributions are welcome! Please open an issue or submit a pull request if you' ## License -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file +for details. ## Acknowledgements -Inspired by the elegant type system of Rust, this library aims to bring similar concepts to TypeScript for improved type safety and error handling. - +Inspired by the elegant type system of Rust, this library aims to bring similar +concepts to Typescript for improved type safety and error handling. From 2ff8a97f5017770e447f2b242d77c3bdeab3fdf7 Mon Sep 17 00:00:00 2001 From: Devin Bidwell Date: Tue, 26 Aug 2025 20:17:27 -0700 Subject: [PATCH 2/3] 1.0.0 --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 4fbbae4..393e104 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@dbidwell94/ts-utils", - "version": "0.7.0", + "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@dbidwell94/ts-utils", - "version": "0.7.0", + "version": "1.0.0", "license": "MIT", "devDependencies": { "@types/jest": "^30.0.0", diff --git a/package.json b/package.json index b46cb4b..a0e565b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@dbidwell94/ts-utils", - "version": "0.7.0", + "version": "1.0.0", "description": "A collection of helpful TypeScript utilities with the aim of having limited production dependencies.", "main": "dist/index.js", "files": [ From 6f541339dfc7647a0adf946b50f5177085e8b8be Mon Sep 17 00:00:00 2001 From: Devin Bidwell Date: Tue, 26 Aug 2025 20:24:00 -0700 Subject: [PATCH 3/3] update changelog --- CHANGELOG.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a283b3..a596ee8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,23 +1,44 @@ # Changelog +## [1.0.0] + +- Removed multiple named exports from the base library in favor of + one singular named export (e.g. `result` and `option`) + - If using those named exports (e.g. `err()`) then you simply have to + import the namespaced export and use it as an object. (e.g. `result.err()`) + - `import {option, result} from '@dbidwell94/ts-utils';` + +## [0.7.0] + +- Added new "static" functions to help with `SerializableOption` + - `option.isSome(val)` + - `option.isNone(val)` + ## [0.6.3] + - Update dev-dependencies to latest versions to resolve audit issues - Update `ts-jest` to version 29.2.6 - Update `typescript` to version 5.8.2 ## [0.6.2] + - Refactor `unknown` function signature to accept optional or null parameters - - This change allows for more flexible usage of the `unknown` function when dealing with potentially null or undefined values + - This change allows for more flexible usage of the `unknown` function when + dealing with potentially null or undefined values - Add documentation for the `unknown` function ## [0.6.1] + - Add new utility function `unknown` to the `Option` namespace - - This function constructs an `Option` type from an unknown value, returning a `Some` if the value is not null or undefined, otherwise returning `None` + - This function constructs an `Option` type from an unknown value, + returning a `Some` if the value is not null or undefined, otherwise + returning `None` ## [0.6.0] - Add new utility function `andThen` for both `Result` and `Option` types -- Added function overload for `fromPromise` which will convert a `Result, E>` to a `Promise>` +- Added function overload for `fromPromise` which will convert a + `Result, E>` to a `Promise>` ## [0.5.2] @@ -29,7 +50,8 @@ ## [0.5.0] -- Changed function signature of `fromSerializableOption` to accept a possibly undefined object +- Changed function signature of `fromSerializableOption` to accept a possibly + undefined object - If undefined is provided, a `None` type is returned. - Changed conditional for `fromSerializableOption` to be more resilient with possibly bad types passed as a parameter