yield-result 0.1.2 → 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/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.2",
+  "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",