yield-result 0.1.2 → 0.1.4

package/README.md

@@ -2,6 +2,8 @@
 
 > Rust-style `?` operator for TypeScript using generators (`yield*`). Zero dependencies, lightweight, type-safe error handling without runtime exceptions.
 
+[![npm version](https://img.shields.io/npm/v/yield-result.svg?style=flat)](https://www.npmjs.com/package/yield-result)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/yield-result.svg)](https://bundlephobia.com/package/yield-result)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.5+-blue.svg)](https://www.typescriptlang.org/)
 [![Vitest](https://img.shields.io/badge/tested%20with-vitest-blueviolet.svg)](https://vitest.dev/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
@@ -129,10 +131,129 @@ const fetchRes = await fromPromise(
 const asyncRes = await fromAsyncFn(() => loadData());
 ```
 
+### 4. Strongly-Typed Errors with `taggedError`
+
+Use `taggedError` to create clean, discriminated error unions with custom payloads:
+
+```typescript
+import { taggedError, err, safe, match } from "yield-result";
+
+// Define domain errors
+const HttpError = (status: number) => taggedError("HttpError", { status });
+const ValidationError = (field: string) => taggedError("ValidationError", { field });
+
+// Functions returning different error types
+const fetchUser = (id: string) => err(HttpError(404));
+const validateAge = (age: number) => err(ValidationError("age"));
+
+// safe.sync automatically infers the error union: Result<User, TaggedError<"HttpError"> | TaggedError<"ValidationError">>
+const result = safe.sync(function* () {
+  const user = yield* fetchUser("123");
+  yield* validateAge(user.age);
+  return user;
+});
+```
+
+---
+
+## 🏷️ Automatic Error Union Inference (`InferYieldErr`)
+
+`yield-result` features automatic error type extraction and union distribution (`InferYieldErr<G>`). When yielding different error types across pipeline steps, TypeScript automatically unifies them without requiring manual type annotations!
+
+### Before vs After
+
+```typescript
+type DbError = { _tag: "DbError"; code: string };
+type ValidationError = { _tag: "ValidationError"; field: string };
+
+const queryUser = (): Result<User, DbError> => ...;
+const validateUser = (u: User): Result<boolean, ValidationError> => ...;
+
+// ❌ BEFORE: Manual generic type parameters required:
+const res = safe.sync<User, DbError | ValidationError>(function* () {
+  const user = yield* queryUser();
+  const valid = yield* validateUser(user);
+  return user;
+});
+
+// ✅ AFTER: 100% AUTOMATIC INFERENCE (Zero type arguments needed!):
+// Automatically inferred as: Result<User, DbError | ValidationError>
+const res = safe.sync(function* () {
+  const user = yield* queryUser();        // Yields Err<DbError>
+  const valid = yield* validateUser(user); // Yields Err<ValidationError>
+  return user;
+});
+```
+
+---
+
+## 🌐 Complete Real-World API Workflow Example
+
+Here is a full end-to-end production API endpoint handler (**Fetch → Validation → DB → HTTP Response**):
+
+```typescript
+import { safe, ok, err, fromPromise, taggedError, match, Result } from "yield-result";
+
+// 1. Define Discriminated Domain Errors
+const ApiError = (status: number, message: string) => taggedError("ApiError", { status, message });
+const DbError = (query: string) => taggedError("DbError", { query });
+const ValidationError = (field: string, reason: string) => taggedError("ValidationError", { field, reason });
+
+type DomainError = 
+  | ReturnType<typeof ApiError>
+  | ReturnType<typeof DbError>
+  | ReturnType<typeof ValidationError>;
+
+// 2. Domain Services
+async function fetchExternalOrder(orderId: string): Promise<Result<{ id: string; amount: number }, DomainError>> {
+  return fromPromise(
+    fetch(`https://api.payments.com/orders/${orderId}`).then(r => r.json()),
+    () => ApiError(502, "External Payment Gateway unreachable")
+  );
+}
+
+function validateOrderAmount(order: { id: string; amount: number }): Result<{ id: string; amount: number }, DomainError> {
+  if (order.amount <= 0) return err(ValidationError("amount", "Order amount must be positive"));
+  return ok(order);
+}
+
+async function saveOrderToDb(order: { id: string; amount: number }): Promise<Result<{ saved: boolean }, DomainError>> {
+  // Simulating DB write
+  return ok({ saved: true });
+}
+
+// 3. Complete Business Pipeline with safe.async
+export async function handleOrderCheckout(orderId: string) {
+  const pipelineResult = await safe.async(async function* () {
+    const rawOrder = yield* await fetchExternalOrder(orderId); // Step 1: External API
+    const validOrder = yield* validateOrderAmount(rawOrder);   // Step 2: Domain Validation
+    const dbRecord = yield* await saveOrderToDb(validOrder);    // Step 3: Database Save
+    
+    return { status: 200, data: { orderId: validOrder.id, dbRecord } };
+  });
+
+  // 4. Exhaustive Pattern Matching for HTTP Response
+  return match(pipelineResult, {
+    ok: (res) => ({ statusCode: 200, body: JSON.stringify(res) }),
+    err: (error) => {
+      switch (error._tag) {
+        case "ApiError":
+          return { statusCode: error.status, body: JSON.stringify({ error: error.message }) };
+        case "ValidationError":
+          return { statusCode: 400, body: JSON.stringify({ error: `Invalid ${error.field}: ${error.reason}` }) };
+        case "DbError":
+          return { statusCode: 500, body: JSON.stringify({ error: "Database transaction failed" }) };
+      }
+    },
+  });
+}
+```
+
 ---
 
 ## 🛡️ Built-in Safety Features
 
+
 ### Runtime Protection against Missing Asterisk (`*`)
 
 Forgetting the asterisk (`yield` instead of `yield*`) is automatically intercepted at runtime and in TypeScript:
@@ -156,9 +277,9 @@ safe.sync(function* () {
 * **`err(error)`** / **`Result.err(error)`** — Creates an `Err<E>` result.
 * **`isOk(result)`** / **`isErr(result)`** — TypeScript type guards.
 
-### Flow Runners (`safe`)
-* **`safe.sync(function* () { ... })`** — Executes a synchronous generator function with early-return short-circuiting on `Err`.
-* **`safe.async(async function* () { ... })`** — Executes an async generator function with early-return short-circuiting on `Err`.
+### Flow Runners (`safe` & `Result.gen`)
+* **`safe.sync(function* () { ... })`** / **`Result.gen(function* () { ... })`** — Executes a synchronous generator function with early-return short-circuiting on `Err`.
+* **`safe.async(async function* () { ... })`** / **`Result.gen.async(async function* () { ... })`** — Executes an async generator function with early-return short-circuiting on `Err`.
 
 ### Exception Wrappers
 * **`fromThrowable(fn, errorMapper?)`** — Wraps a throwing function into a `Result<T, E>`.

package/dist/types.d.ts

@@ -88,7 +88,17 @@ export declare const partition: <T, E>(results: Result<T, E>[]) => {
     errors: E[];
 };
 /**
- * Namespace object grouping all Result constructors, guards, and combinators.
+ * Interface representing a discriminated error object with a `_tag` property.
+ */
+export interface TaggedError<T extends string> {
+    readonly _tag: T;
+}
+/**
+ * Creates an immutable TaggedError object with a `_tag` property and optional payload properties.
+ */
+export declare const taggedError: <T extends string, P extends Record<string, unknown> = {}>(tag: T, props?: P) => Readonly<TaggedError<T> & P>;
+/**
+ * Namespace object grouping all Result constructors, guards, combinators, and generator runners.
  */
 export declare const Result: {
     readonly ok: <T>(value: T) => Ok<T>;
@@ -112,4 +122,9 @@ export declare const Result: {
         values: T[];
         errors: E[];
     };
+    readonly taggedError: <T extends string, P extends Record<string, unknown> = {}>(tag: T, props?: P) => Readonly<TaggedError<T> & P>;
+    readonly gen: (<G extends Generator<Err<unknown>, unknown, unknown>>(fn: () => G) => Result<G extends Generator<unknown, infer R, unknown> ? R : G extends AsyncGenerator<unknown, infer R_1, unknown> ? R_1 : never, G extends Generator<infer Y, unknown, unknown> ? Y extends Err<infer E> ? E : never : G extends AsyncGenerator<infer Y_1, unknown, unknown> ? Y_1 extends Err<infer E_1> ? E_1 : never : never>) & {
+        sync: <G extends Generator<Err<unknown>, unknown, unknown>>(fn: () => G) => Result<G extends Generator<unknown, infer R, unknown> ? R : G extends AsyncGenerator<unknown, infer R_1, unknown> ? R_1 : never, G extends Generator<infer Y, unknown, unknown> ? Y extends Err<infer E> ? E : never : G extends AsyncGenerator<infer Y_1, unknown, unknown> ? Y_1 extends Err<infer E_1> ? E_1 : never : never>;
+        async: <G extends AsyncGenerator<Err<unknown>, unknown, unknown>>(fn: () => G) => Promise<Result<G extends Generator<unknown, infer R, unknown> ? R : G extends AsyncGenerator<unknown, infer R_1, unknown> ? R_1 : never, G extends Generator<infer Y, unknown, unknown> ? Y extends Err<infer E> ? E : never : G extends AsyncGenerator<infer Y_1, unknown, unknown> ? Y_1 extends Err<infer E_1> ? E_1 : never : never>>;
+    };
 };

package/dist/types.js

@@ -134,7 +134,19 @@ export const partition = (results) => {
     return { values, errors };
 };
 /**
- * Namespace object grouping all Result constructors, guards, and combinators.
+ * Creates an immutable TaggedError object with a `_tag` property and optional payload properties.
+ */
+export const taggedError = (tag, props) => Object.freeze({
+    _tag: tag,
+    ...(props ?? {}),
+});
+import { safe } from "./flow.js";
+const genRunner = Object.assign((fn) => safe.sync(fn), {
+    sync: safe.sync,
+    async: safe.async,
+});
+/**
+ * Namespace object grouping all Result constructors, guards, combinators, and generator runners.
  */
 export const Result = {
     ok,
@@ -152,4 +164,6 @@ export const Result = {
     match,
     all,
     partition,
+    taggedError,
+    gen: genRunner,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yield-result",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Rust-style ? operator for TypeScript using generators (yield*). Zero dependencies, type-safe error handling.",
   "type": "module",
   "main": "./dist/index.js",