@shirudo/result 1.1.0 → 1.1.1

package/README.md

@@ -1,15 +1,18 @@
 # @shirudo/result
 
-Robust, type-safe error handling for TypeScript.
+A `Result<T, E>` type for TypeScript. Functions return their failures instead of throwing them.
 
-`@shirudo/result` models expected failures as values instead of hidden exceptions. Functions return `Result<T, E>`, callers must handle both states, and TypeScript narrows access to `value` and `error` only when the state is known.
+```ts docs-check:skip
+function loadUser(id: string): Result<User, UserError>
+```
+
+The failure is part of the signature: callers see exactly what can go wrong, the compiler insists both cases are handled, and `value`/`error` are only accessible after narrowing. What used to be a forgotten `catch` is now a type error.
+
+The rest of the package is tooling around that one type: pipe operators, async variants, generator-based do-notation, exhaustive error matching, and collection helpers. The library has zero dependencies, ships as ESM and CJS, and runs on Node 20+ and edge runtimes.
 
 [![CI](https://github.com/shi-rudo/result-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/shi-rudo/result-ts/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@shirudo/result.svg)](https://www.npmjs.com/package/@shirudo/result)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.7%2B-blue.svg)](https://www.typescriptlang.org/)
-[![Node](https://img.shields.io/badge/Node-%3E%3D20-green.svg)](https://nodejs.org/)
-![Edge Runtime](https://img.shields.io/badge/Edge_Runtime-compatible-brightgreen.svg)
 
 ## Installation
 
@@ -22,12 +25,13 @@ yarn add @shirudo/result
 ## Quick Start
 
 ```ts
-import { Result } from '@shirudo/result';
+import { err, ok, type Result } from '@shirudo/result';
+import { map, match } from '@shirudo/result/operators';
 
 type User = { id: string; email: string; active: boolean };
 type UserError =
-    | { type: 'not-found'; id: string }
-    | { type: 'inactive'; id: string };
+    | { code: 'not-found'; id: string }
+    | { code: 'inactive'; id: string };
 
 const users = new Map<string, User>([
     ['1', { id: '1', email: 'ada@example.com', active: true }],
@@ -35,35 +39,53 @@ const users = new Map<string, User>([
 
 function loadUser(id: string): Result<User, UserError> {
     const user = users.get(id);
-    if (!user) return Result.err({ type: 'not-found', id });
-    if (!user.active) return Result.err({ type: 'inactive', id });
-    return Result.ok(user);
+    if (!user) return err({ code: 'not-found', id });
+    if (!user.active) return err({ code: 'inactive', id });
+    return ok(user);
 }
 
+// Narrow explicitly:
 const result = loadUser('1');
-
 if (result.isOk()) {
-    console.log(result.value.email);
-} else {
-    switch (result.error.type) {
-        case 'not-found':
-            console.error(`Missing user ${result.error.id}`);
-            break;
-        case 'inactive':
-            console.error(`Inactive user ${result.error.id}`);
-            break;
-    }
+    console.log(result.value.email); // `value` is only accessible in this branch
 }
+
+// Or compose and resolve in one expression. `map` only runs on Ok,
+// and the error keeps its type all the way to `match`:
+const message = loadUser('1').pipe(
+    map(user => `Welcome back, ${user.email}`),
+    match({
+        ok: greeting => greeting,
+        err: error =>
+            error.code === 'not-found'
+                ? `No user with id ${error.id}`
+                : `User ${error.id} is deactivated`,
+    }),
+);
 ```
 
-## Why This Library
+## Why Result Instead of try/catch?
+
+TypeScript cannot type a `catch` block: every thrown value arrives as `unknown`, and nothing in a function's signature reveals that it throws at all. Callers either remember to catch, or they find out in production.
+
+A `Result<User, UserError>` puts the failure into the signature. The compiler forces both states to be handled, narrows `value` and `error` access to the matching state (as in the Quick Start above), and keeps the error type intact across every transformation.
+
+## Why This Library?
+
+There are several Result implementations for TypeScript. This one is built around a few hard guarantees:
+
+- **Error types that cannot lie.** Declaring an explicit error type requires an error mapper: `fromPromise<User, ApiError>(promise)` without one is a compile error, so `E` never silently holds an unmapped `unknown`. And bugs inside the mapper itself are rethrown instead of being disguised as `Err` values.
+- **Exhaustive matching, checked at compile time.** `matchError().when(NotFoundError, ...).run()` only compiles once every error case is handled, and `matchTag` does the same for discriminated unions. Add a new error variant, and every unhandled match site turns red.
+- **Four interchangeable styles, one type.** Explicit `isOk()`/`isErr()` checks, `pipe`/`pipeAsync` operator chains, generator-based do-notation (`task`), and builder-based error matching all work on the same immutable, frozen `Result`. Use whichever style fits each call site.
+- **Safe at runtime boundaries.** `isResult()` validates an internal brand plus payload shape instead of accepting lookalike objects, and `toSerialized()`/`fromSerialized()` round-trip Results through JSON without ambiguity.
+- **Zero dependencies, runs anywhere.** The package ships ESM and CJS builds with tree-shakeable subpath exports, and it runs on Node 20+ and in edge runtimes.
+- **Verified, not promised.** Every TypeScript snippet in this README and the docs is compile-checked in CI, the API is covered by 400+ runtime tests plus compile-time type tests, and the package exports are verified for ESM, CJS, and TypeScript consumers.
 
-- `Ok` does not expose `error`, and `Err` does not expose `value`; accidental reads require proper narrowing.
-- `isResult` uses a stable internal brand plus payload validation instead of accepting random lookalike objects.
-- `Result.fromPromise()` maps promise rejections but rethrows bugs inside the error mapper.
-- Sync, async, generator, collection, and matching workflows are first-class.
-- README and docs TypeScript snippets are compile-checked.
-- Package exports are tested for ESM, CJS, and TypeScript consumers.
+## When Not to Use It
+
+- If your codebase is already built on [Effect](https://effect.website/), you do not need this package. Its `Either`/`Exit` types come with the surrounding ecosystem.
+- For short scripts and prototypes, plain `try`/`catch` is often the simpler tool. The value of typed errors grows with the number of call sites that must handle them.
+- Keep throwing for programmer errors. Broken invariants and failed assertions should crash loudly; `Result` is for failures the caller is expected to handle.
 
 ## Common Workflows
 
@@ -74,14 +96,14 @@ import { Result } from '@shirudo/result';
 
 const parseJson = Result.fromThrowable(
     JSON.parse,
-    error => ({ type: 'parse' as const, cause: error }),
+    error => ({ code: 'parse' as const, cause: error }),
 );
 
 const parsed = parseJson('{"valid": true}');
 
 const response = await Result.fromPromise(
     Promise.resolve({ ok: true }),
-    error => ({ type: 'network' as const, cause: error }),
+    error => ({ code: 'network' as const, cause: error }),
 );
 ```
 
@@ -131,27 +153,53 @@ function findUser(id: string) {
 function ensureEmail(user: { id: string; email?: string }) {
     return user.email
         ? Result.ok(user.email)
-        : Result.err({ type: 'missing-email' as const, id: user.id });
+        : Result.err({ code: 'missing-email' as const, id: user.id });
 }
 
-const email = task(function* () {
+const emailResult = await task(function* () {
     const user = yield* findUser('1');
     return yield* ensureEmail(user);
 });
 ```
 
+### Handle error classes exhaustively
+
+```ts
+import { Result } from '@shirudo/result';
+
+class NotFoundError extends Error {
+    readonly code = 'not-found';
+}
+class RateLimitError extends Error {
+    readonly code = 'rate-limited';
+    constructor(readonly retryAfter: number) {
+        super(`rate limited, retry in ${retryAfter}s`);
+    }
+}
+
+const result: Result<string, NotFoundError | RateLimitError> = Result.err(new RateLimitError(30));
+
+if (result.isErr()) {
+    const message = result
+        .matchError()
+        .when(NotFoundError, () => 'No such record')
+        .when(RateLimitError, error => `Retry in ${error.retryAfter}s`)
+        .run(); // run() only compiles because every error class is handled
+}
+```
+
 ### Match discriminated-union errors
 
 ```ts
 import { Result, matchTag } from '@shirudo/result';
 
 type DomainError =
-    | { type: 'network'; retryAfter: number }
-    | { type: 'validation'; field: string };
+    | { code: 'network'; retryAfter: number }
+    | { code: 'validation'; field: string };
 
-const failed = Result.err<DomainError>({ type: 'network', retryAfter: 30 });
+const failed = Result.err<DomainError>({ code: 'network', retryAfter: 30 });
 
-const message = matchTag(failed, 'type', {
+const message = matchTag(failed, 'code', {
     network: error => `Retry in ${error.retryAfter}s`,
     validation: error => `Invalid field: ${error.field}`,
 });
@@ -186,7 +234,7 @@ The full documentation lives in `docs/` and is built with VitePress.
 - [Collections](docs/api/collections.md)
 - [Error Classes](docs/api/errors.md)
 - [Version 1 Migration](docs/migration/v1.md)
-- [Design Decisions](docs/decisions/lazy-async-abstraction.md)
+- [Design Decisions](docs/decisions/lazy-async-abstraction.md) ([Defensive State Checks](docs/decisions/defensive-state-checks.md))
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shirudo/result",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Robust, type-safe error handling for TypeScript using the Result pattern (Monad)",
   "type": "module",
   "private": false,