yield-result 0.1.1 → 0.1.3

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:

package/dist/flow.d.ts

@@ -1,4 +1,6 @@
 import { Result, Err } from "./types.js";
+type InferYieldErr<G> = G extends Generator<infer Y, unknown, unknown> ? Y extends Err<infer E> ? E : never : G extends AsyncGenerator<infer Y, unknown, unknown> ? Y extends Err<infer E> ? E : never : never;
+type InferReturn<G> = G extends Generator<unknown, infer R, unknown> ? R : G extends AsyncGenerator<unknown, infer R, unknown> ? R : never;
 /**
  * Control flow runners for evaluating generator functions with short-circuiting on Err.
  */
@@ -6,11 +8,14 @@ export declare const safe: {
     /**
      * Evaluates a synchronous generator function, returning Ok(value) on completion,
      * or short-circuiting on the first yielded Err(error).
+     * Automatically infers and unifies error types yielded across all steps.
      */
-    sync: <T, E = unknown>(fn: () => Generator<Err<E>, T, unknown>) => Result<T, E>;
+    sync: <G extends Generator<Err<unknown>, unknown, unknown>>(fn: () => G) => Result<InferReturn<G>, InferYieldErr<G>>;
     /**
      * Evaluates an async generator function, returning Ok(value) on completion,
      * or short-circuiting on the first yielded Err(error).
+     * Automatically infers and unifies error types yielded across all steps.
      */
-    async: <T, E = unknown>(fn: () => AsyncGenerator<Err<E>, T, unknown>) => Promise<Result<T, E>>;
+    async: <G extends AsyncGenerator<Err<unknown>, unknown, unknown>>(fn: () => G) => Promise<Result<InferReturn<G>, InferYieldErr<G>>>;
 };
+export {};

package/dist/flow.js

@@ -6,6 +6,7 @@ export const safe = {
     /**
      * Evaluates a synchronous generator function, returning Ok(value) on completion,
      * or short-circuiting on the first yielded Err(error).
+     * Automatically infers and unifies error types yielded across all steps.
      */
     sync: (fn) => {
         let gen;
@@ -56,6 +57,7 @@ export const safe = {
     /**
      * Evaluates an async generator function, returning Ok(value) on completion,
      * or short-circuiting on the first yielded Err(error).
+     * Automatically infers and unifies error types yielded across all steps.
      */
     async: async (fn) => {
         let gen;

package/dist/types.d.ts

@@ -87,6 +87,16 @@ export declare const partition: <T, E>(results: Result<T, E>[]) => {
     values: T[];
     errors: E[];
 };
+/**
+ * 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, and combinators.
  */
@@ -112,4 +122,5 @@ 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>;
 };

package/dist/types.js

@@ -133,6 +133,13 @@ export const partition = (results) => {
     }
     return { values, errors };
 };
+/**
+ * Creates an immutable TaggedError object with a `_tag` property and optional payload properties.
+ */
+export const taggedError = (tag, props) => Object.freeze({
+    _tag: tag,
+    ...(props ?? {}),
+});
 /**
  * Namespace object grouping all Result constructors, guards, and combinators.
  */
@@ -152,4 +159,5 @@ export const Result = {
     match,
     all,
     partition,
+    taggedError,
 };

package/package.json

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