# Effection — Structured Concurrency for JavaScript

Effection is a JavaScript library for building reliable asynchronous and concurrent programs using
**structured concurrency**. It models async work as a tree of tasks with explicit lifetimes,
deterministic cancellation, and guaranteed cleanup.

Effection uses **generator functions** instead of async/await to represent long-lived,
cancellable operations that compose naturally and enforce parent/child task relationships.

This file provides a high-level map of the Effection concepts and documentation.
For detailed explanations, APIs, and examples, see `llms-full.txt`.

---

## Core Concepts

- **Structured Concurrency**
  All concurrent work has a parent. When a parent task exits, all child tasks are cancelled.
  Cleanup logic is guaranteed to run.

- **Tasks**
  Generator functions (`function*`) represent units of async work that can be started, paused,
  cancelled, and composed.

- **Cancellation & Cleanup**
  Cancellation is built into the execution model. `finally` blocks always run when a task is
  cancelled or completes.

- **Scopes**
  Scopes define the lifetime boundary for tasks and resources.

- **Resources**
  Resources model acquire/release lifecycles (e.g. sockets, processes, workers) and ensure cleanup
  when a scope exits.

---

## Core APIs (High Level)

- `run()` / `main()` — run a task to completion
- `spawn()` — start a concurrent child task
- `all()` / `race()` — structured concurrency combinators
- `resource()` / `provide()` — model managed resources
- `scoped()` — isolate effects with immediate cleanup
- `on()` / `once()` — event streams (EventTarget only)
- `useScope()` — access the current task scope
- Utilities: `sleep`, `interval`, `ensure`, `suspend`, `createChannel`, `createQueue`

> **Gotcha:** When iterating streams with `each()`, always call `yield* each.next()` at the end of the loop body.

---

## Common Use Cases

- Long-lived servers and daemons
- CLI tools and process orchestration
- WebSocket and streaming workflows
- Worker pools and background jobs
- Tests involving processes, signals, or concurrency
- Reactive state machines with explicit lifetimes

---

## Version Notes

- Effection v3 established the structured concurrency model
- Effection v4 refines ergonomics, scope handling, and priority semantics
- APIs are designed to work across Node.js, Deno, and browsers

---

## Codebase Map

For agents with file access:

- **Source:** `lib/` — core implementation files
- **Docs:** `docs/` — conceptual guides (MDX)
- **Tests:** `test/` — usage examples and edge cases
- **Full LLM reference:** `llms-full.txt`

---

## Detailed Reference

See **`llms-full.txt`** for:
- Conceptual explanations with examples
- API-level documentation
- Patterns and idioms
- async/await comparisons
- v3 → v4 migration guidance