@iahuang/result-ts 1.2.0 → 2.0.0

package/.claude/settings.local.json

@@ -1,7 +1,10 @@
 {
   "permissions": {
     "allow": [
-      "Bash(npm run build:*)"
+      "Bash(npm run build:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npm test:*)",
+      "Bash(npm install:*)"
     ]
   }
 }

package/README.md

@@ -5,7 +5,7 @@ A TypeScript implementation of Rust's [`std::result::Result`](https://doc.rust-l
 This library provides a lightweight, type-safe way to handle errors without exceptions. It aims to:
 - Stay close to Rust's original API design
 - Provide strict type safety with full TypeScript inference
-- Use plain objects (not classes) for easy serialization
+- Use plain objects as opposed to classes to allow for JSON serialization
 - Support both synchronous and asynchronous operations
 
 ## Installation
@@ -16,58 +16,38 @@ npm install @iahuang/result-ts
 
 ## Quick Start
 
+Define your error types, then use `resultType()` to create a type-safe result builder:
+
 ```ts
+import { resultType, chain, match } from '@iahuang/result-ts';
+
 type ParseErrors = {
-    invalid_number: string; // the string that failed to parse as a number
-    negative: number; // the number that was negative
+    invalid_number: string;
+    negative: number;
 };
 
 const parseResult = resultType<number, ParseErrors>();
 
-type ParseError = Err<ParseErrors>; // { ok: false, error: "invalid_number", detail: string } | { ok: false, error: "negative", detail: number }
-type ParseOk = Ok<number>; // { ok: true, value: number }
-
-type ParseResult = ResultType<typeof parseResult>; // ParseError | ParseOk
-
-function parseIntStrict(s: string): ParseResult {
+function parsePositiveInt(s: string): Result<number, ParseErrors> {
     const n = Number.parseInt(s, 10);
     if (Number.isNaN(n)) return parseResult.err("invalid_number", s);
     if (n < 0) return parseResult.err("negative", n);
     return parseResult.ok(n);
 }
-
-const timesTwo = resultMap(parseIntStrict("123"), (n) => n * 2);
-
-// construct plain results manually
-const okResult = parseResult.ok(123); // { ok: true, value: 123 }
-const errResult = parseResult.err("invalid_number", "123"); // { ok: false, error: "invalid_number", detail: "123" }
 ```
 
-The equivalent Rust code is:
-
-```rust
-enum ParseError {
-    InvalidNumber(String),
-    Negative(i32),
-}
-
-fn parse_int_strict(s: &str) -> Result<i32, ParseError> {
-    match s.parse::<i32>() {
-        Ok(n) => {
-            if n < 0 {
-                Err(ParseError::Negative(n))
-            } else {
-                Ok(n)
-            }
-        },
-        Err(_) => Err(ParseError::InvalidNumber(s.to_string())),
-    }
-}
+Chain operations and handle results:
 
-let times_two = parse_int_strict("123").map(|n| n * 2);
+```ts
+const value = chain(parsePositiveInt("42"))
+    .map((n) => n * 2)
+    .unwrapOr(0);
 
-let ok_result = Ok(123);
-let err_result = Err(ParseError::InvalidNumber("123".to_string()));
+// Or use pattern matching for full control
+match(parsePositiveInt("-5"), {
+    ok: (n) => console.log(`Got ${n}`),
+    err: (e) => console.log(`Error: ${e.type}`)
+});
 ```
 
 ## Core Concepts
@@ -75,22 +55,26 @@ let err_result = Err(ParseError::InvalidNumber("123".to_string()));
 ### Result Types
 
 A `Result<T, E>` is either:
-- `Ok<T>`: Success, containing a value of type `T`
+- Success, containing a value of type `T`
   ```ts
   { ok: true, value: T }
   ```
-- `Err<E>`: Failure, containing an error variant and detail
+- Failure, containing an `Err<E>` under the `error` field
   ```ts
-  { ok: false, error: keyof E, detail: E[keyof E] }
+  { ok: false, error: Err<E> }
   ```
 
+Where `Err<E>` is a discriminated union of `{ type: K, detail: E[K] }` for each key `K` in `E`.
+
+This is analogous to creating a `Result<T, E>` type in Rust, with `E` being an enum type with variants for different error types. The constraint that `E` be an enum-like type is baked into this library's type system to encourage the implementation of fixed, statically-known sets of error types which can each be handled appropriately.
+
 ### Creating Results
 
 You can create results in two ways:
 
-#### 1. Using `resultType()` (Recommended)
+#### 1. **Recommended:** Using `resultType()`
 
-This provides full type safety and inference:
+This method provides the strongest type safety and inference.
 
 ```ts
 type MyErrors = {
@@ -129,7 +113,21 @@ import { match } from '@iahuang/result-ts';
 
 const message = match(parsePositiveInt("123"), {
     ok: (value) => `Success: ${value}`,
-    err: (e) => `Error: ${e.error} - ${e.detail}`
+    err: (e) => `Error: ${e.type} - ${e.detail}`
+});
+```
+
+For exhaustive matching on individual error variants, use `matchNested`:
+
+```ts
+import { matchNested } from '@iahuang/result-ts';
+
+const message = matchNested(parsePositiveInt("123"), {
+    ok: (value) => `Success: ${value}`,
+    err: {
+        invalid_number: (s) => `Invalid number: ${s}`,
+        negative: (n) => `Negative number: ${n}`,
+    }
 });
 ```
 
@@ -218,10 +216,10 @@ resultInspectErr(result, (err) => {
 All Result functions have async versions for working with Promises:
 
 ```ts
-import { asyncResultMap, asyncResultAndThen, tryCatchResultAsync } from '@iahuang/result-ts';
+import { asyncResultMap, asyncResultAndThen, resultFromThrowingAsyncFunction } from '@iahuang/result-ts';
 
 async function fetchUser(id: string): Promise<Result<User, FetchErrors>> {
-    return tryCatchResultAsync(
+    return resultFromThrowingAsyncFunction(
         async () => {
             const response = await fetch(`/api/users/${id}`);
             return await response.json();
@@ -249,7 +247,7 @@ const email = await asyncChain(fetchUser("123"))
 Convert throwing code to Results:
 
 ```ts
-import { tryCatchResult } from '@iahuang/result-ts';
+import { resultFromThrowingFunction, resultType, Result } from '@iahuang/result-ts';
 
 type JsonErrors = {
     parse_error: string;
@@ -257,8 +255,8 @@ type JsonErrors = {
 
 const jsonResult = resultType<any, JsonErrors>();
 
-function parseJSON(jsonString: string): ResultType<typeof jsonResult> {
-    return tryCatchResult(
+function parseJSON(jsonString: string): Result<any, JsonErrors> {
+    return resultFromThrowingFunction(
         () => JSON.parse(jsonString),
         (e) => jsonResult.err("parse_error", String(e))
     );
@@ -268,73 +266,41 @@ const data = parseJSON('{"valid": "json"}');
 // Ok({ valid: "json" })
 
 const invalid = parseJSON('invalid json');
-// Err({ ok: false, error: "parse_error", detail: "SyntaxError: ..." })
+// Err({ ok: false, error: { type: "parse_error", detail: "SyntaxError: ..." } })
 ```
 
-## Complete Example: File Processing
+## Complete Example: Config Loader
 
-Here's a comprehensive example showing real-world usage:
+A realistic example showing how to chain fallible operations:
 
 ```ts
-import { resultType, ResultType, chain, match } from '@iahuang/result-ts';
+import { resultType, chain, match } from '@iahuang/result-ts';
 import * as fs from 'fs';
 
-type FileErrors = {
-    not_found: string;
-    permission_denied: string;
-    invalid_json: string;
-};
-
-const fileResult = resultType<any, FileErrors>();
-type FileResult = ResultType<typeof fileResult>;
+type ConfigErrors = { not_found: string; invalid_json: string };
+const configResult = resultType<any, ConfigErrors>();
 
-function readFile(path: string): FileResult {
+function loadConfig(path: string) {
+    // Read file
+    let content: string;
     try {
-        const content = fs.readFileSync(path, 'utf-8');
-        return fileResult.ok(content);
-    } catch (e: any) {
-        if (e.code === 'ENOENT') {
-            return fileResult.err("not_found", path);
-        }
-        if (e.code === 'EACCES') {
-            return fileResult.err("permission_denied", path);
-        }
-        throw e;
+        content = fs.readFileSync(path, 'utf-8');
+    } catch {
+        return configResult.err("not_found", path);
     }
-}
 
-function parseJSON(content: string): FileResult {
+    // Parse JSON
     try {
-        return fileResult.ok(JSON.parse(content));
+        return configResult.ok(JSON.parse(content));
     } catch (e) {
-        return fileResult.err("invalid_json", String(e));
+        return configResult.err("invalid_json", String(e));
     }
 }
 
-// Process the file with chaining
-const result = chain(readFile("config.json"))
-    .andThen(parseJSON)
-    .map((config) => config.database)
-    .result;
-
-// Handle the result
-const config = match(result, {
-    ok: (db) => db,
-    err: (e) => {
-        switch (e.error) {
-            case "not_found":
-                console.error(`File not found: ${e.detail}`);
-                break;
-            case "permission_denied":
-                console.error(`Permission denied: ${e.detail}`);
-                break;
-            case "invalid_json":
-                console.error(`Invalid JSON: ${e.detail}`);
-                break;
-        }
-        return null;
-    }
-});
+// Usage
+const dbHost = chain(loadConfig("config.json"))
+    .map((config) => config.database.host)
+    .unwrapOr("localhost");
 ```
 
 ## API Reference
@@ -342,8 +308,7 @@ const config = match(result, {
 ### Core Types
 
 - `Result<T, E>` - The main Result type
-- `Ok<T>` - Success type
-- `Err<E>` - Error type
+- `Err<E>` - Error type (discriminated union of `{ type, detail }`)
 - `resultType<T, E>()` - Creates type-safe Result constructors
 
 ### Query Methods
@@ -379,22 +344,124 @@ const config = match(result, {
 
 ### Utilities
 
+These utility functions do not have any analogous functions in Rust, but are provided for convenience.
+
 - `match(result, handlers)` - Pattern matching
+- `matchNested(result, handlers)` - Pattern matching with per-variant error handlers
 - `chain(result)` - Method chaining API
-- `tryCatchResult(fn, errFn)` - Convert exceptions to Results
-- `tryCatchResultAsync(fn, errFn)` - Async exception handling
-- `tryCatchResultPromise(promise, errFn)` - Promise rejection handling
+- `resultFromThrowingFunction(fn, errFn)` - Convert exceptions to Results
+- `resultFromThrowingAsyncFunction(fn, errFn)` - Async exception handling
+- `resultFromThrowingPromise(promise, errFn)` - Promise rejection handling
+- `resultAll(results)` - Combine multiple Results into one
 
 All sync functions have async equivalents prefixed with `async`:
-- `asyncResultMap`, `asyncResultAndThen`, `asyncChain`, etc.
+- `asyncResultMap`, `asyncResultAndThen`, `asyncChain`, `asyncResultAll`, etc.
 
 ## Comparison with Other Libraries
 
-### vs. `neverthrow`
+### vs. [`neverthrow`](https://github.com/supermacro/neverthrow)
 
 Unlike `neverthrow`, this library uses plain objects instead of class instances:
 - Results can be safely serialized/deserialized (e.g., JSON.stringify)
-- No runtime overhead from class instantiation
-- More memory efficient for large datasets
 - Closer to functional programming principles
 
+### vs. [Effect](https://effect.website/)
+
+Effect provides a much more comprehensive and opinionated ecosystem implementing functional programming principles in TypeScript. This library is focused on providing a lightweight, type-safe framework for error handling without any additional tooling, dependencies, or specific use cases in mind.
+
+## Migrating from v1
+
+### Breaking Changes
+
+#### Result structure changed
+
+Errors are now nested under an `error` field instead of being spread flat on the result object. The error object uses `type` instead of `error` for the variant key.
+
+```ts
+// v1
+{ ok: false, error: "not_found", detail: "/path" }
+
+// v2
+{ ok: false, error: { type: "not_found", detail: "/path" } }
+```
+
+This means code that accessed `result.error` or `result.detail` directly on a failed result must now access `result.error.type` and `result.error.detail`.
+
+#### `Ok<T>` and `Undetailed<E>` types removed
+
+`Ok<T>` is no longer exported as a separate type. Use `Result<T, never>` if you need to represent a result that is always successful. `Undetailed<E>` has been removed entirely.
+
+#### `ResultType<T>` helper type removed
+
+The `ResultType<typeof myResult>` pattern for extracting a Result type from constructors is no longer supported. Use `Result<T, E>` directly instead.
+
+```ts
+// v1
+const parseResult = resultType<number, ParseErrors>();
+type ParseResult = ResultType<typeof parseResult>;
+
+// v2
+const parseResult = resultType<number, ParseErrors>();
+type ParseResult = Result<number, ParseErrors>;
+```
+
+#### `resultType()` no longer returns chain constructors
+
+The `okChain` and `errChain` constructors have been removed from the object returned by `resultType()`. Use `chain()` to wrap results instead.
+
+```ts
+// v1
+const r = myResult.okChain(value);
+
+// v2
+const r = chain(myResult.ok(value));
+```
+
+#### `tryCatchResult` functions renamed
+
+| v1 | v2 |
+|----|-----|
+| `tryCatchResult` | `resultFromThrowingFunction` |
+| `tryCatchResultAsync` | `resultFromThrowingAsyncFunction` |
+| `tryCatchResultPromise` | `resultFromThrowingPromise` |
+
+#### `asyncMatch` replaced by `matchNested`
+
+`asyncMatch` has been removed. The new `matchNested` function provides per-variant error handlers instead.
+
+```ts
+// v1
+await asyncMatch(asyncResult, {
+    ok: async (value) => ...,
+    err: (e) => ...
+});
+
+// v2
+matchNested(result, {
+    ok: (value) => ...,
+    err: {
+        not_found: (detail) => ...,
+        timeout: (detail) => ...,
+    }
+});
+```
+
+#### `match` error handler receives `Err<E>` instead of the full result
+
+The `err` handler in `match` now receives the `Err<E>` value (i.e. `{ type, detail }`) rather than the entire result object.
+
+```ts
+// v1
+match(result, {
+    ok: (v) => ...,
+    err: (e) => console.log(e.error, e.detail)
+});
+
+// v2
+match(result, {
+    ok: (v) => ...,
+    err: (e) => console.log(e.type, e.detail)
+});
+```
+
+#### `asyncResultUnwrapOrElse` is no longer exported