@dojocho/effect-ts 0.0.1

package/DOJO.md

@@ -0,0 +1,22 @@
+# Effect-TS Kata Dojo
+
+Hands-on katas for learning Effect-TS. Use `/kata` to begin.
+
+## Teaching Rules
+
+**Never give solutions.** Your role is Socratic guide.
+
+- Ask questions that steer toward the answer
+- Point to type signatures or API names
+- Narrow scope: "Focus on the first failing test"
+- Never write or show solution code
+
+**SENSEI.md is the authority.** Each kata has one. Read it first — it has the Test Map, teaching prompts, and completion guidance. It overrides these defaults.
+
+**Concept accuracy.** Only teach APIs the student writes. Test-only APIs (`runSync`, `runSyncExit`) belong to the harness — don't attribute them to the student.
+
+**Area introductions.** At area boundaries, invoke the skill listed in SENSEI.md's "Skills" section.
+
+## Style
+
+Clean, minimal, encouraging. No walls of text.

package/dojo.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://dojocho.ai/schema/v1/dojo.json",
+  "name": "@dojocho/effect-ts",
+  "version": "0.0.1",
+  "description": "Master Effect-TS through 40 hands-on katas",
+
+  "test": "pnpm vitest run {template}",
+  "katas": [
+    { "template": "katas/001-hello-effect/solution.ts" },
+    { "template": "katas/002-transform-with-map/solution.ts" },
+    { "template": "katas/003-generator-pipelines/solution.ts" },
+    { "template": "katas/004-flatmap-and-chaining/solution.ts" },
+    { "template": "katas/005-pipe-composition/solution.ts" },
+    { "template": "katas/006-handle-errors/solution.ts" },
+    { "template": "katas/007-tagged-errors/solution.ts" },
+    { "template": "katas/008-error-patterns/solution.ts" },
+    { "template": "katas/009-option-type/solution.ts" },
+    { "template": "katas/010-either-and-exit/solution.ts" },
+    { "template": "katas/011-services-and-context/solution.ts" },
+    { "template": "katas/012-layers/solution.ts" },
+    { "template": "katas/013-testing-effects/solution.ts" },
+    { "template": "katas/014-schema-basics/solution.ts" },
+    { "template": "katas/015-domain-modeling/solution.ts" },
+    { "template": "katas/016-retry-and-schedule/solution.ts" },
+    { "template": "katas/017-parallel-effects/solution.ts" },
+    { "template": "katas/018-race-and-timeout/solution.ts" },
+    { "template": "katas/019-ref-and-state/solution.ts" },
+    { "template": "katas/020-fibers/solution.ts" },
+    { "template": "katas/021-acquire-release/solution.ts" },
+    { "template": "katas/022-scoped-layers/solution.ts" },
+    { "template": "katas/023-resource-patterns/solution.ts" },
+    { "template": "katas/024-streams-basics/solution.ts" },
+    { "template": "katas/025-stream-operations/solution.ts" },
+    { "template": "katas/026-combining-streams/solution.ts" },
+    { "template": "katas/027-data-pipelines/solution.ts" },
+    { "template": "katas/028-logging-and-spans/solution.ts" },
+    { "template": "katas/029-http-client/solution.ts" },
+    { "template": "katas/030-capstone/solution.ts", "test": "pnpm vitest run katas/" },
+    { "template": "katas/031-config-and-environment/solution.ts" },
+    { "template": "katas/032-cause-and-defects/solution.ts" },
+    { "template": "katas/033-pattern-matching/solution.ts" },
+    { "template": "katas/034-deferred-and-coordination/solution.ts" },
+    { "template": "katas/035-queue-and-backpressure/solution.ts" },
+    { "template": "katas/036-schema-advanced/solution.ts" },
+    { "template": "katas/037-cache-and-memoization/solution.ts" },
+    { "template": "katas/038-metrics/solution.ts" },
+    { "template": "katas/039-managed-runtime/solution.ts" },
+    { "template": "katas/040-request-batching/solution.ts", "test": "pnpm vitest run katas/" }
+  ]
+}

package/katas/001-hello-effect/SENSEI.md

@@ -0,0 +1,72 @@
+# SENSEI — 001 Hello Effect
+
+## Briefing
+
+### Goal
+
+Create and run your first Effects.
+
+### Tasks
+
+1. Implement `hello()` — returns an Effect that succeeds with `"Hello, Effect!"`
+2. Implement `lazyRandom()` — returns an Effect that lazily produces a random number (0–1)
+3. Implement `greet(name)` — returns an Effect that succeeds with `"Hello, {name}!"`
+
+### Hints
+
+```ts
+import { Effect } from "effect";
+
+// Effect.succeed wraps a plain value
+const myEffect = Effect.succeed(42);
+
+// Effect.sync wraps a lazy computation
+const lazy = Effect.sync(() => Math.random());
+
+// Effect.runSync executes synchronously
+const value = Effect.runSync(myEffect); // 42
+```
+
+## Prerequisites
+
+None — this is the first kata.
+
+## Skills
+
+Invoke `effect-patterns-getting-started` before teaching this kata.
+
+> **Note**: `Effect.runSync` appears only in tests. The student does NOT write it. Never attribute it to their learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `hello() succeeds with 'Hello, Effect!'` | `Effect.succeed` | Wrapping a string literal |
+| `lazyRandom() produces a number between 0 and 1` | `Effect.sync` | Lazy computation wrapping `Math.random()` |
+| `lazyRandom() is lazy (re-evaluates on each run)` | `Effect.sync` | Same Effect produces different values across multiple runs |
+| `greet('World') succeeds with 'Hello, World!'` | `Effect.succeed` | Parameterized value wrapping |
+| `greet('Effect') succeeds with 'Hello, Effect!'` | `Effect.succeed` | Parameterized value wrapping |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "What's the difference between wrapping a value directly vs wrapping a function that produces a value?"
+- "If you use `Effect.succeed(Math.random())`, when does `Math.random()` actually run?"
+- "What does the type `Effect.Effect<string>` tell you about what this Effect produces?"
+
+### Common pitfalls
+
+1. **Using `succeed` for `lazyRandom`** — `Effect.succeed(Math.random())` evaluates `Math.random()` immediately when the function is called, not when the Effect is run. The value gets "baked in". Ask: "Try running `lazyRandom()` twice and comparing — are they always different? Why or why not?"
+2. **Overcomplicating `greet`** — students may try template literals inside `sync`. Nudge: "Does `greet` need laziness? It already has the name parameter."
+3. **Tackle one function at a time** — get `hello()` passing first, then think about what makes `lazyRandom` different.
+
+## On Completion
+
+### Insight
+
+You used two ways to create Effects: `succeed` for values you already have, and `sync` for computations you want to defer. The tests used `Effect.runSync` to execute your Effects — but notice **you** never wrote `runSync`. In Effect, creating a computation and running it are separate concerns. This separation is what makes Effects composable.
+
+### Bridge
+
+Now that you can create Effects, the next step is **transforming** them. Kata 002 introduces `Effect.map` and `pipe` — the building blocks for turning one Effect's output into something new without leaving the Effect world.

package/katas/001-hello-effect/solution.test.ts

@@ -0,0 +1,35 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import { greet, hello, lazyRandom } from "@/katas/001-hello-effect/solution.js";
+
+describe("001 — Hello Effect", () => {
+  it("hello() succeeds with 'Hello, Effect!'", () => {
+    const result = Effect.runSync(hello());
+    expect(result).toBe("Hello, Effect!");
+  });
+
+  it("lazyRandom() produces a number between 0 and 1", () => {
+    const result = Effect.runSync(lazyRandom());
+    expect(result).toBeTypeOf("number");
+    expect(result).toBeGreaterThanOrEqual(0);
+    expect(result).toBeLessThan(1);
+  });
+
+  it("lazyRandom() is lazy (re-evaluates on each run)", () => {
+    const effect = lazyRandom();
+    const results = Array.from({ length: 10 }, () => Effect.runSync(effect));
+    const unique = new Set(results);
+    // Running the same Effect 10 times should produce multiple distinct values
+    expect(unique.size).toBeGreaterThan(1);
+  });
+
+  it("greet('World') succeeds with 'Hello, World!'", () => {
+    const result = Effect.runSync(greet("World"));
+    expect(result).toBe("Hello, World!");
+  });
+
+  it("greet('Effect') succeeds with 'Hello, Effect!'", () => {
+    const result = Effect.runSync(greet("Effect"));
+    expect(result).toBe("Hello, Effect!");
+  });
+});

package/katas/001-hello-effect/solution.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+
+/** Return an Effect that succeeds with "Hello, Effect!" */
+export const hello = (): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};
+
+/** Return an Effect that lazily produces a random number (0–1) */
+export const lazyRandom = (): Effect.Effect<number> => {
+  throw new Error("Not implemented");
+};
+
+/** Return an Effect that succeeds with "Hello, {name}!" */
+export const greet = (name: string): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};

package/katas/002-transform-with-map/SENSEI.md

@@ -0,0 +1,72 @@
+# SENSEI — 002 Transform with Map
+
+## Briefing
+
+### Goal
+
+Transform Effect values using `map` and `pipe`.
+
+### Tasks
+
+1. Implement `double(n)` — returns an Effect that succeeds with `n * 2`
+2. Implement `strlen(s)` — returns an Effect that succeeds with the length of `s`
+3. Implement `doubleAndFormat(n)` — uses pipe + map to double a number and format as `"Result: {n}"`
+
+### Hints
+
+```ts
+import { Effect, pipe } from "effect";
+
+// Effect.map transforms the success value
+const doubled = Effect.map(Effect.succeed(21), (n) => n * 2);
+
+// pipe lets you compose left-to-right
+const result = pipe(
+  Effect.succeed(10),
+  Effect.map((n) => n + 1),
+  Effect.map((n) => `Value: ${n}`),
+);
+```
+
+## Prerequisites
+
+- **001 Hello Effect** — `Effect.succeed`, `Effect.sync` (creating Effects)
+
+> **Note**: `Effect.runSync` appears only in tests. Never attribute it to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `double(5) succeeds with 10` | `Effect.succeed` + `Effect.map` | Basic numeric transformation |
+| `double(0) succeeds with 0` | `Effect.map` | Edge case — identity under doubling |
+| `double(-3) succeeds with -6` | `Effect.map` | Negative numbers |
+| `strlen('hello') succeeds with 5` | `Effect.succeed` + `Effect.map` | String-to-number transformation |
+| `strlen('') succeeds with 0` | `Effect.map` | Empty string edge case |
+| `doubleAndFormat(5) succeeds with 'Result: 10'` | `pipe` + `Effect.map` | Chained transformations |
+| `doubleAndFormat(0) succeeds with 'Result: 0'` | `pipe` + `Effect.map` | Chained edge case |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "You know how to create Effects with `succeed`. What if you want to change the value inside without leaving the Effect world?"
+- "What does `Effect.map` return — a plain value or an Effect?"
+- "In `doubleAndFormat`, you need two steps. How does `pipe` help you connect them?"
+
+### Common pitfalls
+
+1. **Returning plain values from map** — `Effect.map(effect, (n) => n * 2)` is correct. Students sometimes try `Effect.succeed(Effect.map(...))` — double-wrapping. Ask: "What does `map` already return?"
+2. **Skipping pipe for `doubleAndFormat`** — students may try to nest maps or create intermediate variables. Nudge: "Can you express both steps in a single `pipe` chain?"
+3. **Confusing `pipe` import** — `pipe` comes from `"effect"`, not a separate module. The type signature helps: it takes a value and a series of functions.
+4. **Start simple** — start with `double` (just `succeed` + `map`), then for `doubleAndFormat` add a second `map` step in the same `pipe`.
+
+## On Completion
+
+### Insight
+
+`Effect.map` keeps you inside the Effect world — you never have to "unwrap" the value, transform it, and "re-wrap" it. This is what makes Effects composable: each transformation step produces a new Effect that chains naturally into the next. Think of `pipe` as a conveyor belt where each `map` is a station that modifies the item passing through.
+
+### Bridge
+
+Pipe chains with `map` work great when each step is synchronous and infallible. But what happens when a step itself needs to create an Effect — like parsing that might fail? Kata 003 introduces **generators** (`Effect.gen`), giving you an imperative-looking way to sequence multiple Effect steps.

package/katas/002-transform-with-map/solution.test.ts

@@ -0,0 +1,33 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import { double, doubleAndFormat, strlen } from "@/katas/002-transform-with-map/solution.js";
+
+describe("002 — Transform with Map", () => {
+  it("double(5) succeeds with 10", () => {
+    expect(Effect.runSync(double(5))).toBe(10);
+  });
+
+  it("double(0) succeeds with 0", () => {
+    expect(Effect.runSync(double(0))).toBe(0);
+  });
+
+  it("double(-3) succeeds with -6", () => {
+    expect(Effect.runSync(double(-3))).toBe(-6);
+  });
+
+  it("strlen('hello') succeeds with 5", () => {
+    expect(Effect.runSync(strlen("hello"))).toBe(5);
+  });
+
+  it("strlen('') succeeds with 0", () => {
+    expect(Effect.runSync(strlen(""))).toBe(0);
+  });
+
+  it("doubleAndFormat(5) succeeds with 'Result: 10'", () => {
+    expect(Effect.runSync(doubleAndFormat(5))).toBe("Result: 10");
+  });
+
+  it("doubleAndFormat(0) succeeds with 'Result: 0'", () => {
+    expect(Effect.runSync(doubleAndFormat(0))).toBe("Result: 0");
+  });
+});

package/katas/002-transform-with-map/solution.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+
+/** Return an Effect that succeeds with n * 2 */
+export const double = (n: number): Effect.Effect<number> => {
+  throw new Error("Not implemented");
+};
+
+/** Return an Effect that succeeds with the length of s */
+export const strlen = (s: string): Effect.Effect<number> => {
+  throw new Error("Not implemented");
+};
+
+/** Use pipe + Effect.map to double n, then format as "Result: {doubled}" */
+export const doubleAndFormat = (n: number): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};

package/katas/003-generator-pipelines/SENSEI.md

@@ -0,0 +1,72 @@
+# SENSEI — 003 Generator Pipelines
+
+## Briefing
+
+### Goal
+
+Use `Effect.gen` to write imperative-style Effect pipelines with generators.
+
+### Tasks
+
+1. Implement `fetchAndDouble(n)` — uses `Effect.gen` to get a value, double it, and return it
+2. Implement `combinedLength(a, b)` — uses `Effect.gen` to get lengths of two strings and add them
+3. Implement `pipeline(s)` — uses `Effect.gen` to parse an integer string, double it, and format as `"Result: {n}"`; fails with `ParseError` on invalid input
+
+### Hints
+
+```ts
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const a = yield* Effect.succeed(10);
+  const b = yield* Effect.succeed(20);
+  return a + b;
+});
+
+// Effect.runSync(program) => 30
+```
+
+## Prerequisites
+
+- **001 Hello Effect** — `Effect.succeed`, `Effect.sync`
+- **002 Transform with Map** — `Effect.map`, `pipe`
+
+> **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 |
+|------|---------|----------|
+| `fetchAndDouble(5) succeeds with 10` | `Effect.gen` + `yield*` | Basic generator with single yield |
+| `fetchAndDouble(0) succeeds with 0` | `Effect.gen` | Edge case |
+| `combinedLength('hello', 'world') succeeds with 10` | `Effect.gen` + multiple `yield*` | Combining results from multiple Effects |
+| `combinedLength('', 'test') succeeds with 4` | `Effect.gen` | Empty string edge case |
+| `pipeline('5') succeeds with 'Result: 10'` | `Effect.gen` | Multi-step pipeline in generator |
+| `pipeline('0') succeeds with 'Result: 0'` | `Effect.gen` | Edge case |
+| `pipeline('abc') fails with ParseError` | `Effect.fail` | Error handling inside generator |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "In kata 002 you used `pipe` + `map`. What if you want to use an intermediate value in a later step — how would you do that with just `map`?"
+- "What does `yield*` do to an Effect? What type does the variable get?"
+- "Inside `Effect.gen`, if you `yield*` an Effect that fails, what happens to the rest of the generator?"
+
+### Common pitfalls
+
+1. **Forgetting `yield*`** — writing `const x = Effect.succeed(5)` inside a generator gives you an Effect, not the value 5. Ask: "What's the type of `x` without `yield*`?"
+2. **Using `return` vs `yield*` for the final value** — the last expression in `Effect.gen` should be a plain `return`, not `yield* Effect.succeed(...)`. Nudge: "You can just `return` the computed value directly."
+3. **ParseError shape** — the `pipeline` function needs to fail with `{ _tag: "ParseError", input: s }`. Students may forget the `input` field. Ask: "What does the `ParseError` interface require?"
+4. **Checking for NaN** — `parseInt("abc")` returns `NaN`, not an error. Ask: "How do you detect when parsing didn't work?"
+5. **Break `pipeline` into steps** — parse, check validity, format. Ask: "Which step might fail?" and point to the `ParseError` interface in solution.ts.
+
+## On Completion
+
+### Insight
+
+Generators give you imperative-style code that's still fully Effect-powered. Each `yield*` is a suspension point — if any yielded Effect fails, the generator short-circuits, just like `throw` in regular code. You now have two styles: `pipe` chains (functional) and `gen` blocks (imperative). Neither is "better" — use whichever reads more clearly for the situation.
+
+### Bridge
+
+Generators and pipe both sequence Effects, but they hide the underlying mechanism: `Effect.flatMap`. Kata 004 makes flatMap explicit, along with `andThen` and `tap` — giving you direct control over how Effects chain together.

package/katas/003-generator-pipelines/solution.test.ts

@@ -0,0 +1,40 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { combinedLength, fetchAndDouble, pipeline } from "@/katas/003-generator-pipelines/solution.js";
+
+describe("003 — Generator Pipelines", () => {
+  it("fetchAndDouble(5) succeeds with 10", () => {
+    expect(Effect.runSync(fetchAndDouble(5))).toBe(10);
+  });
+
+  it("fetchAndDouble(0) succeeds with 0", () => {
+    expect(Effect.runSync(fetchAndDouble(0))).toBe(0);
+  });
+
+  it("combinedLength('hello', 'world') succeeds with 10", () => {
+    expect(Effect.runSync(combinedLength("hello", "world"))).toBe(10);
+  });
+
+  it("combinedLength('', 'test') succeeds with 4", () => {
+    expect(Effect.runSync(combinedLength("", "test"))).toBe(4);
+  });
+
+  it("pipeline('5') succeeds with 'Result: 10'", () => {
+    expect(Effect.runSync(pipeline("5"))).toBe("Result: 10");
+  });
+
+  it("pipeline('0') succeeds with 'Result: 0'", () => {
+    expect(Effect.runSync(pipeline("0"))).toBe("Result: 0");
+  });
+
+  it("pipeline('abc') fails with ParseError", () => {
+    const exit = Effect.runSyncExit(pipeline("abc"));
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (Exit.isFailure(exit)) {
+      expect(exit.cause).toMatchObject({
+        _tag: "Fail",
+        error: { _tag: "ParseError", input: "abc" },
+      });
+    }
+  });
+});

package/katas/003-generator-pipelines/solution.ts

@@ -0,0 +1,29 @@
+import { Effect } from "effect";
+
+export interface ParseError {
+  readonly _tag: "ParseError";
+  readonly input: string;
+}
+
+/** Use Effect.gen to succeed with n * 2 */
+export const fetchAndDouble = (n: number): Effect.Effect<number> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Effect.gen to get the length of a and b, then return their sum */
+export const combinedLength = (
+  a: string,
+  b: string,
+): Effect.Effect<number> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Effect.gen to:
+ *   1. Parse s as an integer (fail with ParseError if invalid)
+ *   2. Double the result
+ *   3. Return formatted as "Result: {doubled}" */
+export const pipeline = (
+  s: string,
+): Effect.Effect<string, ParseError> => {
+  throw new Error("Not implemented");
+};

package/katas/004-flatmap-and-chaining/SENSEI.md

@@ -0,0 +1,80 @@
+# SENSEI — 004 FlatMap and Chaining
+
+## Briefing
+
+### Goal
+
+Chain Effects together using flatMap, andThen, and tap.
+
+### Tasks
+
+1. Implement `lookupAndGreet(id)` — flatMap a lookup to return a greeting
+2. Implement `validateAndProcess(input)` — chain validation then processing
+3. Implement `logAndReturn(value, sideEffects)` — use tap to log a side effect without changing the value
+
+### Hints
+
+```ts
+import { Effect } from "effect";
+
+// Effect.flatMap chains a dependent Effect
+const result = Effect.succeed(1).pipe(
+  Effect.flatMap((n) => Effect.succeed(n + 1))
+);
+
+// Effect.andThen sequences two Effects
+const chained = Effect.succeed("hello").pipe(
+  Effect.andThen((s) => Effect.succeed(s.toUpperCase()))
+);
+
+// Effect.tap runs a side effect without altering the result
+const tapped = Effect.succeed(42).pipe(
+  Effect.tap((n) => Effect.sync(() => console.log(n)))
+);
+```
+
+## Prerequisites
+
+- **001 Hello Effect** — `Effect.succeed`, `Effect.sync`
+- **002 Transform with Map** — `Effect.map`, `pipe`
+- **003 Generator Pipelines** — `Effect.gen`, `yield*`, `Effect.fail`
+
+> **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 |
+|------|---------|----------|
+| `lookupAndGreet(0) succeeds with 'Hello, Alice!'` | `Effect.flatMap` | Chain dependent Effects — success path |
+| `lookupAndGreet(1) succeeds with 'Hello, Bob!'` | `Effect.flatMap` | Chain dependent Effects — different lookup |
+| `lookupAndGreet(99) fails with 'NotFound'` | `Effect.flatMap` + `Effect.fail` | Error propagation in chain |
+| `validateAndProcess('hello') succeeds with 'HELLO'` | `Effect.andThen` | Sequential processing — success |
+| `validateAndProcess('') fails with 'EmptyInput'` | `Effect.andThen` + `Effect.fail` | Validation failure |
+| `logAndReturn records side effect and returns value` | `Effect.tap` + `Effect.sync` | Side effect without value change |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "In `map`, your function returns a plain value. In `flatMap`, your function returns an Effect. Why would you need that?"
+- "What's the difference between `flatMap` and `andThen`? Try looking at their type signatures."
+- "If `tap` doesn't change the value, what's it useful for?"
+- "For `lookupAndGreet`, you need a lookup step that might fail. Can a `map` callback fail? What can?"
+
+### Common pitfalls
+
+1. **Using `map` instead of `flatMap`** — if your callback returns an Effect, you'll get `Effect<Effect<...>>` (nested). Ask: "What type does `map` give you if your function returns an Effect?"
+2. **Lookup logic** — students may overcomplicate the id-to-name mapping. Nudge: "A simple `if/else` or ternary works. What should happen for id 0? For id 1? For anything else?"
+3. **`tap` changing the value** — the callback in `tap` runs for its side effect; its return value is ignored (the original value passes through). Ask: "After `tap`, what value does the chain continue with?"
+4. **`logAndReturn` side effect** — students need to push to the `sideEffects` array. This is a mutation, so use `Effect.sync(() => { ... })` inside `tap`.
+5. **Start with `lookupAndGreet`** — first create an Effect that looks up the name, then use `flatMap` to turn that name into a greeting Effect.
+
+## On Completion
+
+### Insight
+
+`flatMap` is the fundamental chaining operation in Effect. Everything else builds on it: `gen` desugars `yield*` into flatMap calls, `andThen` is a more flexible flatMap, and `map` is flatMap where the callback wraps its return in `succeed` automatically. Understanding flatMap means understanding how Effect sequences computations.
+
+### Bridge
+
+You now have all the individual building blocks: `succeed`, `sync`, `fail`, `map`, `flatMap`, `andThen`, `tap`, `gen`. Kata 005 brings them together with **pipe composition** — building multi-step pipelines using both the standalone `pipe()` function and the fluent `.pipe()` method. It's the capstone of the Basics area.

package/katas/004-flatmap-and-chaining/solution.test.ts

@@ -0,0 +1,34 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { lookupAndGreet, validateAndProcess, logAndReturn } from "@/katas/004-flatmap-and-chaining/solution.js";
+
+describe("004 — FlatMap and Chaining", () => {
+  it("lookupAndGreet(0) succeeds with 'Hello, Alice!'", () => {
+    expect(Effect.runSync(lookupAndGreet(0))).toBe("Hello, Alice!");
+  });
+
+  it("lookupAndGreet(1) succeeds with 'Hello, Bob!'", () => {
+    expect(Effect.runSync(lookupAndGreet(1))).toBe("Hello, Bob!");
+  });
+
+  it("lookupAndGreet(99) fails with 'NotFound'", () => {
+    const exit = Effect.runSyncExit(lookupAndGreet(99));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("validateAndProcess('hello') succeeds with 'HELLO'", () => {
+    expect(Effect.runSync(validateAndProcess("hello"))).toBe("HELLO");
+  });
+
+  it("validateAndProcess('') fails with 'EmptyInput'", () => {
+    const exit = Effect.runSyncExit(validateAndProcess(""));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("logAndReturn records side effect and returns value", () => {
+    const log: string[] = [];
+    const result = Effect.runSync(logAndReturn("test", log));
+    expect(result).toBe("test");
+    expect(log).toContain("test");
+  });
+});

package/katas/004-flatmap-and-chaining/solution.ts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+
+/** Use Effect.flatMap to look up a name by id (0→"Alice", 1→"Bob", else fail with "NotFound")
+ * then return "Hello, {name}!" */
+export const lookupAndGreet = (id: number): Effect.Effect<string, string> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Effect.andThen to first validate input is non-empty (fail with "EmptyInput" if empty),
+ * then transform to uppercase */
+export const validateAndProcess = (input: string): Effect.Effect<string, string> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Effect.tap to record the value to a mutable array (sideEffects), then return the value unchanged */
+export const logAndReturn = (value: string, sideEffects: string[]): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};