@dojocho/effect-ts 0.0.1

package/katas/005-pipe-composition/SENSEI.md

@@ -0,0 +1,81 @@
+# SENSEI — 005 Pipe Composition
+
+## Briefing
+
+### Goal
+
+Compose multi-step Effect transformations using pipe and the fluent `.pipe()` style.
+
+### Tasks
+
+1. Implement `processNumber(n)` — pipe a number through: double, add 1, convert to string
+2. Implement `processUser(name, age)` — pipe through validation and formatting using `.pipe()`
+3. Implement `pipeline(s)` — compose parse, validate, and format using `.pipe()` chaining
+
+### Hints
+
+```ts
+import { Effect, pipe } from "effect";
+
+// Standalone pipe function
+const result = pipe(
+  Effect.succeed(10),
+  Effect.map((n) => n * 2),
+  Effect.map((n) => `Result: ${n}`)
+);
+
+// Fluent .pipe() style
+const fluent = Effect.succeed("hello").pipe(
+  Effect.map((s) => s.toUpperCase()),
+  Effect.map((s) => `${s}!`)
+);
+```
+
+## Prerequisites
+
+- **001 Hello Effect** — `Effect.succeed`, `Effect.sync`
+- **002 Transform with Map** — `Effect.map`, `pipe`
+- **003 Generator Pipelines** — `Effect.gen`, `yield*`, `Effect.fail`
+- **004 FlatMap and Chaining** — `Effect.flatMap`, `Effect.andThen`, `Effect.tap`
+
+> **Note**: `Effect.runSync`, `Effect.runSyncExit`, and `Exit.isFailure` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `processNumber(5) succeeds with '11'` | `pipe` + `Effect.map` | Multi-step: double, +1, toString |
+| `processNumber(0) succeeds with '1'` | `pipe` | Edge case — 0 doubled + 1 = 1 |
+| `processUser('Alice', 30) succeeds with 'Alice (age 30)'` | `.pipe()` + `Effect.flatMap` | Fluent style with validation |
+| `processUser('', 30) fails with 'InvalidName'` | `.pipe()` + `Effect.fail` | Validation — empty name |
+| `processUser('Alice', -1) fails with 'InvalidAge'` | `.pipe()` + `Effect.fail` | Validation — negative age |
+| `pipeline('5') succeeds with 'Value: 5'` | `.pipe()` composition | Parse + validate + format |
+| `pipeline('abc') fails` | `.pipe()` + `Effect.fail` | Parse failure |
+| `pipeline('-3') fails with not positive` | `.pipe()` + `Effect.fail` | Validation failure |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "You've used `pipe` before in kata 002. What's different about using `.pipe()` as a method on an Effect?"
+- "For `processNumber`, the steps are: double, add 1, to string. Which operator works for each step?"
+- "In `processUser`, you need to validate TWO things before formatting. What happens if the first validation fails — does the second one run?"
+- "For `pipeline`, there are three phases: parse, validate, format. Which might fail? What error should each produce?"
+
+### Common pitfalls
+
+1. **Standalone `pipe()` vs fluent `.pipe()`** — both work the same way but read differently. `pipe(value, fn1, fn2)` vs `value.pipe(fn1, fn2)`. Ask: "Which style makes this code more readable?"
+2. **Validation ordering in `processUser`** — students may validate name and age in a single step. Nudge: "What if name is empty AND age is negative? Which error should win? Check the tests."
+3. **Parse + validate confusion in `pipeline`** — parsing and positivity check are separate concerns. Ask: "What does `parseInt` return for `'abc'`? How about `'-3'` — does it parse? Is it positive?"
+4. **String conversion** — `processNumber` needs the final value as a string. Students may forget the `String()` or template literal step.
+5. **Start with `processNumber`** — it's pure `pipe` + `map`, no errors: three maps in a row (double, add one, stringify).
+
+## On Completion
+
+### Insight
+
+You've now completed the Basics area. You can create Effects (`succeed`, `sync`, `fail`), transform them (`map`), chain them (`flatMap`, `andThen`), observe them (`tap`), sequence them with generators (`gen`, `yield*`), and compose them into pipelines (`pipe`, `.pipe()`). These are the atoms of Effect programming — everything else builds on them.
+
+### Bridge
+
+With the basics solid, it's time for what makes Effect truly powerful: **typed error handling**. Kata 006 introduces `Effect.fail`, `catchAll`, and `catchTag` — giving you fine-grained control over what goes wrong and how to recover. In regular TypeScript, errors are `unknown`. In Effect, they're part of the type signature.

package/katas/005-pipe-composition/solution.test.ts

@@ -0,0 +1,41 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { processNumber, processUser, pipeline } from "@/katas/005-pipe-composition/solution.js";
+
+describe("005 — Pipe Composition", () => {
+  it("processNumber(5) succeeds with '11'", () => {
+    expect(Effect.runSync(processNumber(5))).toBe("11");
+  });
+
+  it("processNumber(0) succeeds with '1'", () => {
+    expect(Effect.runSync(processNumber(0))).toBe("1");
+  });
+
+  it("processUser('Alice', 30) succeeds with 'Alice (age 30)'", () => {
+    expect(Effect.runSync(processUser("Alice", 30))).toBe("Alice (age 30)");
+  });
+
+  it("processUser('', 30) fails with 'InvalidName'", () => {
+    const exit = Effect.runSyncExit(processUser("", 30));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("processUser('Alice', -1) fails with 'InvalidAge'", () => {
+    const exit = Effect.runSyncExit(processUser("Alice", -1));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("pipeline('5') succeeds with 'Value: 5'", () => {
+    expect(Effect.runSync(pipeline("5"))).toBe("Value: 5");
+  });
+
+  it("pipeline('abc') fails", () => {
+    const exit = Effect.runSyncExit(pipeline("abc"));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("pipeline('-3') fails with not positive", () => {
+    const exit = Effect.runSyncExit(pipeline("-3"));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+});

package/katas/005-pipe-composition/solution.ts

@@ -0,0 +1,19 @@
+import { Effect, pipe } from "effect";
+
+/** Use pipe to: start with Effect.succeed(n), double it, add 1, convert to string */
+export const processNumber = (n: number): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};
+
+/** Use .pipe() fluent style to validate name is non-empty and age >= 0,
+ * then format as "{name} (age {age})"
+ * Fail with "InvalidName" or "InvalidAge" respectively */
+export const processUser = (name: string, age: number): Effect.Effect<string, string> => {
+  throw new Error("Not implemented");
+};
+
+/** Use pipe to compose: parse string to int (fail with "ParseError"),
+ * validate > 0 (fail with "NotPositive"), format as "Value: {n}" */
+export const pipeline = (s: string): Effect.Effect<string, string> => {
+  throw new Error("Not implemented");
+};

package/katas/006-handle-errors/SENSEI.md

@@ -0,0 +1,86 @@
+# SENSEI — 006 Handle Errors
+
+## Briefing
+
+### Goal
+
+Create Effects that can fail, and recover from those failures.
+
+### Tasks
+
+1. Implement `divide(a, b)` — returns an Effect that divides `a / b`, failing with `{ _tag: "DivisionByZero" }` when `b === 0`
+2. Implement `safeDivide(a, b)` — wraps `divide` and recovers from `DivisionByZero` by returning `0`
+3. Implement `parseInteger(s)` — parses a string to int, failing with `{ _tag: "ParseError", input: s }` on invalid input
+
+### Hints
+
+```ts
+import { Effect } from "effect";
+
+// Effect.fail creates a failed Effect
+const failed = Effect.fail({ _tag: "MyError" as const });
+
+// catchAll recovers from any error
+const recovered = Effect.catchAll(failed, (error) =>
+  Effect.succeed("fallback"),
+);
+
+// catchTag recovers from a specific tagged error
+const recovered2 = Effect.catchTag(failed, "MyError", (error) =>
+  Effect.succeed("recovered"),
+);
+```
+
+## Prerequisites
+
+- **001 Hello Effect** — `Effect.succeed`, `Effect.sync`
+- **002 Transform with Map** — `Effect.map`, `pipe`
+- **003 Generator Pipelines** — `Effect.gen`, `yield*`, `Effect.fail`
+- **004 FlatMap and Chaining** — `Effect.flatMap`, `Effect.andThen`, `Effect.tap`
+- **005 Pipe Composition** — `pipe`, `.pipe()`, composition
+
+## Skills
+
+Invoke `effect-patterns-error-handling` before teaching this kata.
+
+> **Note**: `Effect.runSync`, `Effect.runSyncExit`, and `Exit.isFailure` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `divide(10, 2) succeeds with 5` | `Effect.succeed` | Happy path — normal division |
+| `divide(10, 0) fails with DivisionByZero` | `Effect.fail` | Error path — division by zero |
+| `safeDivide(10, 2) succeeds with 5` | `Effect.catchAll` or `Effect.catchTag` | Recovery pass-through on success |
+| `safeDivide(10, 0) recovers with 0` | `Effect.catchAll` or `Effect.catchTag` | Recovery — returning a default on error |
+| `parseInteger('42') succeeds with 42` | `Effect.succeed` | Parsing a valid positive integer |
+| `parseInteger('-7') succeeds with -7` | `Effect.succeed` | Parsing a valid negative integer |
+| `parseInteger('abc') fails with ParseError` | `Effect.fail` | Non-numeric input |
+| `parseInteger('3.14') fails with ParseError` | `Effect.fail` | Float input rejected |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "In regular TypeScript, division by zero gives `Infinity`. What if you want to treat it as an error instead?"
+- "What does the type `Effect<number, DivisionByZero>` tell you that `number` alone doesn't?"
+- "`safeDivide` has no error type — `Effect<number>`. How did the error disappear? Where did it go?"
+- "What's the difference between `catchAll` and `catchTag`? When would you prefer one over the other?"
+
+### Common pitfalls
+
+1. **Forgetting to check for zero** — `divide` needs an explicit check before dividing. Ask: "What should `divide` do first — compute the result or check the divisor?"
+2. **Using try/catch instead of Effect.fail** — students coming from imperative code may wrap division in try/catch. Nudge: "In Effect, errors are values, not exceptions. How do you create an error value?"
+3. **Double-wrapping in safeDivide** — students may try `Effect.succeed(divide(a, b))` instead of calling `divide` and catching errors. Ask: "What does `divide(a, b)` return? Is it a plain number or an Effect?"
+4. **ParseError for integers** — `parseInt('3.14')` returns `3`, not `NaN`. Students need to check that the string represents a whole number. Ask: "Does `parseInt('3.14')` fail? How do you detect that `'3.14'` isn't an integer?"
+5. **Start with `divide`** — check the divisor first; if it's zero, fail; otherwise, succeed with the result.
+
+## On Completion
+
+### Insight
+
+Effect errors are typed — the type system tracks exactly what can go wrong. Unlike try/catch where errors are `unknown`, an `Effect<number, DivisionByZero>` tells you at the type level that this computation either produces a number or fails with a `DivisionByZero`. When you use `catchAll` or `catchTag` to handle all possible errors, the error channel becomes `never` — the compiler proves your code handles every failure case.
+
+### Bridge
+
+Now that you can create and catch errors, the next step is making them richer. Kata 007 introduces `Data.TaggedError` — class-based errors with `_tag` discrimination that enable `catchTag` to selectively recover from specific error types while letting others propagate.

package/katas/006-handle-errors/solution.test.ts

@@ -0,0 +1,53 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { divide, parseInteger, safeDivide } from "@/katas/006-handle-errors/solution.js";
+
+describe("006 — Handle Errors", () => {
+  it("divide(10, 2) succeeds with 5", () => {
+    expect(Effect.runSync(divide(10, 2))).toBe(5);
+  });
+
+  it("divide(10, 0) fails with DivisionByZero", () => {
+    const exit = Effect.runSyncExit(divide(10, 0));
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (Exit.isFailure(exit)) {
+      const error = exit.cause;
+      expect(error).toMatchObject({
+        _tag: "Fail",
+        error: { _tag: "DivisionByZero" },
+      });
+    }
+  });
+
+  it("safeDivide(10, 2) succeeds with 5", () => {
+    expect(Effect.runSync(safeDivide(10, 2))).toBe(5);
+  });
+
+  it("safeDivide(10, 0) recovers with 0", () => {
+    expect(Effect.runSync(safeDivide(10, 0))).toBe(0);
+  });
+
+  it("parseInteger('42') succeeds with 42", () => {
+    expect(Effect.runSync(parseInteger("42"))).toBe(42);
+  });
+
+  it("parseInteger('-7') succeeds with -7", () => {
+    expect(Effect.runSync(parseInteger("-7"))).toBe(-7);
+  });
+
+  it("parseInteger('abc') fails with ParseError", () => {
+    const exit = Effect.runSyncExit(parseInteger("abc"));
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (Exit.isFailure(exit)) {
+      expect(exit.cause).toMatchObject({
+        _tag: "Fail",
+        error: { _tag: "ParseError", input: "abc" },
+      });
+    }
+  });
+
+  it("parseInteger('3.14') fails with ParseError", () => {
+    const exit = Effect.runSyncExit(parseInteger("3.14"));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+});

package/katas/006-handle-errors/solution.ts

@@ -0,0 +1,30 @@
+import { Effect } from "effect";
+
+export interface DivisionByZero {
+  readonly _tag: "DivisionByZero";
+}
+
+export interface ParseError {
+  readonly _tag: "ParseError";
+  readonly input: string;
+}
+
+/** Return a / b as an Effect. Fail with DivisionByZero when b === 0. */
+export const divide = (
+  a: number,
+  b: number,
+): Effect.Effect<number, DivisionByZero> => {
+  throw new Error("Not implemented");
+};
+
+/** Wrap divide and recover from DivisionByZero by returning 0. */
+export const safeDivide = (a: number, b: number): Effect.Effect<number> => {
+  throw new Error("Not implemented");
+};
+
+/** Parse s as an integer. Fail with ParseError if it's not a valid integer. */
+export const parseInteger = (
+  s: string,
+): Effect.Effect<number, ParseError> => {
+  throw new Error("Not implemented");
+};

package/katas/007-tagged-errors/SENSEI.md

@@ -0,0 +1,79 @@
+# SENSEI — 007 Tagged Errors
+
+## Briefing
+
+### Goal
+
+Model domain errors using `Data.TaggedError` for type-safe error handling.
+
+### Tasks
+
+1. Define `NotFoundError` and `ValidationError` as `Data.TaggedError` classes
+2. Implement `findUser(id)` — fails with `NotFoundError` when `id < 0`, succeeds with `{ id, name: "User {id}" }`
+3. Implement `validateAge(age)` — fails with `ValidationError` when `age < 0 || age > 150`, succeeds with the age
+4. Implement `findUserOrDefault(id)` — wraps `findUser`, recovering from `NotFoundError` with a default user `{ id: 0, name: "Guest" }`
+
+### Hints
+
+```ts
+import { Data, Effect } from "effect";
+
+class MyError extends Data.TaggedError("MyError")<{
+  readonly message: string;
+}> {}
+
+const failing = Effect.fail(new MyError({ message: "oops" }));
+
+// catchTag matches on the _tag field
+const recovered = Effect.catchTag(failing, "MyError", (e) =>
+  Effect.succeed(`Recovered: ${e.message}`),
+);
+```
+
+## Prerequisites
+
+- **006 Handle Errors** — `Effect.fail`, `Effect.catchAll`, `Effect.catchTag`
+
+> **Note**: `Effect.runSync`, `Effect.runSyncExit`, and `Exit.isFailure` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `findUser(1) succeeds with { id: 1, name: 'User 1' }` | `Effect.succeed` | Happy path — known user |
+| `findUser(42) succeeds with { id: 42, name: 'User 42' }` | `Effect.succeed` | Happy path — any positive id |
+| `findUser(-1) fails with NotFoundError` | `Data.TaggedError` + `Effect.fail` | Negative id triggers typed error |
+| `validateAge(25) succeeds with 25` | `Effect.succeed` | Valid age in range |
+| `validateAge(0) succeeds with 0` | `Effect.succeed` | Boundary case — zero is valid |
+| `validateAge(150) succeeds with 150` | `Effect.succeed` | Boundary case — 150 is valid |
+| `validateAge(-1) fails with ValidationError` | `Effect.fail` | Below minimum boundary |
+| `validateAge(151) fails with ValidationError` | `Effect.fail` | Above maximum boundary |
+| `findUserOrDefault(1) succeeds with { id: 1, name: 'User 1' }` | `Effect.catchTag` | Pass-through on success |
+| `findUserOrDefault(-1) recovers with { id: 0, name: 'Guest' }` | `Effect.catchTag` | Selective recovery from NotFoundError |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "In kata 006 you used plain objects as errors. What does `Data.TaggedError` add on top of that?"
+- "What is the `_tag` property on a TaggedError? How does `catchTag` use it?"
+- "In `findUserOrDefault`, you only want to catch `NotFoundError`. What happens to other error types if there were any?"
+- "What's the difference between `catchAll` (kata 006) and `catchTag`? Which is more precise?"
+
+### Common pitfalls
+
+1. **Forgetting `new` when constructing TaggedError** — `Effect.fail(NotFoundError())` won't work. It must be `Effect.fail(new NotFoundError())`. Ask: "TaggedError creates a class — how do you create an instance of a class in JavaScript?"
+2. **Boundary conditions in validateAge** — the tests show `0` and `150` are valid, but `-1` and `151` are not. Ask: "What exact range is valid? Check the boundary test cases carefully."
+3. **Using `catchAll` instead of `catchTag`** — for `findUserOrDefault`, `catchAll` works but `catchTag` is the lesson. Nudge: "Can you be more specific about which error you're catching?"
+4. **Wrong user format** — `findUser` must return `{ id, name: 'User ${id}' }`. Students may forget the name format. Ask: "Check the test expectations — what shape does the user object need?"
+5. **Start with error classes** — define `NotFoundError` and `ValidationError` using `Data.TaggedError` first, then implement the functions that use them.
+
+## On Completion
+
+### Insight
+
+TaggedError gives you class-based errors with `_tag` discrimination. This enables `catchTag` to selectively recover from specific error types while letting others propagate. The pattern is powerful: define your domain errors as TaggedError classes, fail with them, and catch only the ones you want to handle. The type system ensures you know exactly which errors remain unhandled.
+
+### Bridge
+
+You can now create and selectively catch typed errors. Kata 008 expands your error-handling toolbox with `catchTags` (handle multiple error types at once), `orElse` (try a fallback effect), and `match` (handle both success and failure) — completing the Error Patterns area.

package/katas/007-tagged-errors/solution.test.ts

@@ -0,0 +1,82 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import {
+  findUser,
+  findUserOrDefault,
+  NotFoundError,
+  validateAge,
+  ValidationError,
+} from "@/katas/007-tagged-errors/solution.js";
+
+describe("007 — Tagged Errors", () => {
+  describe("findUser", () => {
+    it("findUser(1) succeeds with { id: 1, name: 'User 1' }", () => {
+      const result = Effect.runSync(findUser(1));
+      expect(result).toEqual({ id: 1, name: "User 1" });
+    });
+
+    it("findUser(42) succeeds with { id: 42, name: 'User 42' }", () => {
+      const result = Effect.runSync(findUser(42));
+      expect(result).toEqual({ id: 42, name: "User 42" });
+    });
+
+    it("findUser(-1) fails with NotFoundError", () => {
+      const exit = Effect.runSyncExit(findUser(-1));
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (Exit.isFailure(exit)) {
+        expect(exit.cause).toMatchObject({
+          _tag: "Fail",
+          error: { _tag: "NotFoundError" },
+        });
+      }
+    });
+  });
+
+  describe("validateAge", () => {
+    it("validateAge(25) succeeds with 25", () => {
+      expect(Effect.runSync(validateAge(25))).toBe(25);
+    });
+
+    it("validateAge(0) succeeds with 0", () => {
+      expect(Effect.runSync(validateAge(0))).toBe(0);
+    });
+
+    it("validateAge(150) succeeds with 150", () => {
+      expect(Effect.runSync(validateAge(150))).toBe(150);
+    });
+
+    it("validateAge(-1) fails with ValidationError", () => {
+      const exit = Effect.runSyncExit(validateAge(-1));
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (Exit.isFailure(exit)) {
+        expect(exit.cause).toMatchObject({
+          _tag: "Fail",
+          error: { _tag: "ValidationError" },
+        });
+      }
+    });
+
+    it("validateAge(151) fails with ValidationError", () => {
+      const exit = Effect.runSyncExit(validateAge(151));
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (Exit.isFailure(exit)) {
+        expect(exit.cause).toMatchObject({
+          _tag: "Fail",
+          error: { _tag: "ValidationError" },
+        });
+      }
+    });
+  });
+
+  describe("findUserOrDefault", () => {
+    it("findUserOrDefault(1) succeeds with { id: 1, name: 'User 1' }", () => {
+      const result = Effect.runSync(findUserOrDefault(1));
+      expect(result).toEqual({ id: 1, name: "User 1" });
+    });
+
+    it("findUserOrDefault(-1) recovers with { id: 0, name: 'Guest' }", () => {
+      const result = Effect.runSync(findUserOrDefault(-1));
+      expect(result).toEqual({ id: 0, name: "Guest" });
+    });
+  });
+});

package/katas/007-tagged-errors/solution.ts

@@ -0,0 +1,37 @@
+import { Data, Effect } from "effect";
+
+/** Define NotFoundError as a Data.TaggedError with a message field */
+export class NotFoundError extends Data.TaggedError("NotFoundError")<{
+  readonly message: string;
+}> {}
+
+/** Define ValidationError as a Data.TaggedError with a message field */
+export class ValidationError extends Data.TaggedError("ValidationError")<{
+  readonly message: string;
+}> {}
+
+export interface User {
+  readonly id: number;
+  readonly name: string;
+}
+
+/** Return user { id, name: "User {id}" }. Fail with NotFoundError when id < 0. */
+export const findUser = (
+  id: number,
+): Effect.Effect<User, NotFoundError> => {
+  throw new Error("Not implemented");
+};
+
+/** Fail with ValidationError when age < 0 or age > 150. Succeed with the age. */
+export const validateAge = (
+  age: number,
+): Effect.Effect<number, ValidationError> => {
+  throw new Error("Not implemented");
+};
+
+/** Wrap findUser, recovering from NotFoundError with { id: 0, name: "Guest" }. */
+export const findUserOrDefault = (
+  id: number,
+): Effect.Effect<User> => {
+  throw new Error("Not implemented");
+};

package/katas/008-error-patterns/SENSEI.md

@@ -0,0 +1,89 @@
+# SENSEI — 008 Error Patterns
+
+## Briefing
+
+### Goal
+
+Master advanced error handling patterns using catchTags, orElse, and match.
+
+### Tasks
+
+1. Implement `handleAllErrors` — use `Effect.catchTags` to handle NetworkError, TimeoutError, and AuthError differently
+2. Implement `withFallback` — use `Effect.orElse` to try a primary effect, falling back on failure
+3. Implement `toResult` — use `Effect.match` to wrap success as "ok: {value}" and failure as "err: {error}"
+
+### Hints
+
+```ts
+import { Effect } from "effect";
+
+// catchTags handles each tagged error by _tag
+const handled = effect.pipe(
+  Effect.catchTags({
+    NetworkError: (e) => Effect.succeed(`network: ${e.url}`),
+    TimeoutError: (e) => Effect.succeed(`timeout: ${e.ms}`),
+  })
+);
+
+// orElse runs fallback if primary fails
+const withFallback = primary.pipe(Effect.orElse(() => fallback));
+
+// match folds both channels into a single success value
+const matched = effect.pipe(
+  Effect.match({
+    onFailure: (e) => `err: ${e}`,
+    onSuccess: (a) => `ok: ${a}`,
+  })
+);
+```
+
+## Prerequisites
+
+- **006 Handle Errors** — `Effect.fail`, `Effect.catchAll`, `Effect.catchTag`
+- **007 Tagged Errors** — `Data.TaggedError`, selective recovery
+
+## Skills
+
+Invoke `effect-patterns-error-handling-resilience` before teaching this kata.
+
+> **Note**: `Effect.runSync` appears only in tests. Never attribute it to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `handleAllErrors handles NetworkError` | `Effect.catchTags` | Recovery from NetworkError |
+| `handleAllErrors handles TimeoutError` | `Effect.catchTags` | Recovery from TimeoutError |
+| `handleAllErrors handles AuthError` | `Effect.catchTags` | Recovery from AuthError |
+| `handleAllErrors passes through success` | `Effect.catchTags` | Success is unaffected |
+| `withFallback uses primary on success` | `Effect.orElse` | Primary Effect succeeds — fallback not used |
+| `withFallback uses fallback on failure` | `Effect.orElse` | Primary Effect fails — fallback takes over |
+| `toResult wraps success` | `Effect.match` | Success path folded to string |
+| `toResult wraps failure` | `Effect.match` | Failure path folded to string |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "In kata 007 you used `catchTag` for one error type. What if you have three different error types to handle? Would you chain three `catchTag` calls?"
+- "`catchTags` takes an object with handlers. What happens to the error channel if you handle every possible error type?"
+- "`orElse` ignores the original error and tries something else. How is that different from `catchAll`?"
+- "`match` handles both success and failure. What type does the result have — can it still fail?"
+
+### Common pitfalls
+
+1. **Incomplete `catchTags` object** — if the effect has three error types, the handler object needs all three keys. The compiler will tell you if you miss one. Ask: "What errors can this effect produce? Does your handler cover all of them?"
+2. **Confusing `orElse` and `catchAll`** — `orElse` takes a function that returns an Effect (ignoring the error), while `catchAll` receives the error as a parameter. Ask: "Do you need to inspect the error, or just try something else entirely?"
+3. **`match` return types** — both the success and failure handlers in `match` must return the same type. Ask: "If success returns a string, what must failure return?"
+4. **`withFallback` error type** — when both primary and fallback can fail, the resulting error type is the fallback's error type. Students may be surprised that the primary's error disappears.
+5. **Start with `handleAllErrors`** — use `Effect.catchTags` with an object mapping each `_tag` to a recovery function; check the error type definitions in solution.ts for the exact `_tag` values to handle.
+
+## On Completion
+
+### Insight
+
+`catchTags` is exhaustive — if you handle all error types, the error channel becomes `never`. This is the compiler helping you handle every case. `orElse` is for "try plan B" scenarios where you don't care why plan A failed. `match` collapses both channels into one, eliminating the error type entirely. Together with `catchAll` and `catchTag` from earlier katas, you now have a complete toolkit for error recovery.
+
+### Bridge
+
+Error handling is now complete. The next area is **Value Handling** — starting with `Option` in kata 009. Option represents values that might not exist, which is different from errors. Use Option when absence is a normal case (e.g., looking up a key), not an exceptional condition.

package/katas/008-error-patterns/solution.test.ts

@@ -0,0 +1,41 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import { handleAllErrors, withFallback, toResult, NetworkError, TimeoutError, AuthError } from "@/katas/008-error-patterns/solution.js";
+
+describe("008 — Error Patterns", () => {
+  it("handleAllErrors handles NetworkError", () => {
+    const effect = Effect.fail(new NetworkError({ url: "https://api.com" }));
+    expect(Effect.runSync(handleAllErrors(effect))).toBe("network error: https://api.com");
+  });
+
+  it("handleAllErrors handles TimeoutError", () => {
+    const effect = Effect.fail(new TimeoutError({ ms: 5000 }));
+    expect(Effect.runSync(handleAllErrors(effect))).toBe("timeout after 5000ms");
+  });
+
+  it("handleAllErrors handles AuthError", () => {
+    const effect = Effect.fail(new AuthError({ reason: "expired token" }));
+    expect(Effect.runSync(handleAllErrors(effect))).toBe("auth failed: expired token");
+  });
+
+  it("handleAllErrors passes through success", () => {
+    const effect = Effect.succeed("data") as Effect.Effect<string, NetworkError | TimeoutError | AuthError>;
+    expect(Effect.runSync(handleAllErrors(effect))).toBe("data");
+  });
+
+  it("withFallback uses primary on success", () => {
+    expect(Effect.runSync(withFallback(Effect.succeed("primary"), Effect.succeed("fallback")))).toBe("primary");
+  });
+
+  it("withFallback uses fallback on failure", () => {
+    expect(Effect.runSync(withFallback(Effect.fail("oops"), Effect.succeed("fallback")))).toBe("fallback");
+  });
+
+  it("toResult wraps success", () => {
+    expect(Effect.runSync(toResult(Effect.succeed("hello")))).toBe("ok: hello");
+  });
+
+  it("toResult wraps failure", () => {
+    expect(Effect.runSync(toResult(Effect.fail("boom")))).toBe("err: boom");
+  });
+});