# Effection — Structured Concurrency for JavaScript

> Effection is a JavaScript library for building reliable asynchronous and
> concurrent programs using structured concurrency.

Effection models async work as **lazy operations** with explicit lifetimes,
deterministic cancellation, and guaranteed cleanup. It uses **generator
functions (`function*`)**, not `async` / `await`, to express long-lived,
cancellable work.

---

## IMPORTANT FOR AI AGENTS

If you will **write, modify, refactor, or debug Effection code**, you **must**
read [AGENTS.md] first.

**AGENTS.md is the normative behavioral contract.**
- Do not invent APIs
- Do not infer semantics from Promises or other ecosystems
- Do not substitute primitives that "look equivalent"
- If information is missing or uncertain, consult the API reference

If any other document conflicts with AGENTS.md, **AGENTS.md takes precedence**.

---

## Where to look (routing)

- **Behavioral rules & invariants (authoritative):** [AGENTS.md]
- **Public API reference (authoritative):** [API]
- **Conceptual guides & explanations (human-oriented):** [Guides]
  - [Thinking in Effection]
  - [Async Rosetta Stone]
  - [Operations]
  - [Scope]
  - [Resources]
  - [Spawn]
  - [Collections]
  - [Browse all guides][docs/]

---

## EffectionX Packages

Extension packages for common JavaScript tasks. Install from npm (`@effectionx/*`) or JSR (`jsr:@effectionx/*`).

- [@effectionx/bdd](https://frontside.com/effection/x/bdd): BDD testing harness with describe/it/beforeEach for Effection operations
- [@effectionx/chain](https://frontside.com/effection/x/chain): Promise-like chaining with then/catch/finally for Effection operations
- [@effectionx/context-api](https://frontside.com/effection/x/context-api): Algebraic effects pattern for context-dependent operations with middleware
- [@effectionx/converge](https://frontside.com/effection/x/converge): Poll and wait for conditions to be met with automatic retry and timeout
- [@effectionx/effect-ts](https://frontside.com/effection/x/effect-ts): Bidirectional interop between Effect-TS and Effection
- [@effectionx/fs](https://frontside.com/effection/x/fs): File system operations wrapped as Effection operations
- [@effectionx/fx](https://frontside.com/effection/x/fx): Utility functions for async workflows adapted from starfx
- [@effectionx/jsonl-store](https://frontside.com/effection/x/jsonl-store): Streaming JSONL document store with glob-based file selection
- [@effectionx/node](https://frontside.com/effection/x/node): Node.
- [@effectionx/process](https://frontside.com/effection/x/process): Spawn and manage child processes with structured concurrency
- [@effectionx/raf](https://frontside.com/effection/x/raf): Stream of requestAnimationFrame updates for Effection
- [@effectionx/scope-eval](https://frontside.com/effection/x/scope-eval): Evaluate operations in a scope while retaining resources across evaluations
- [@effectionx/signals](https://frontside.com/effection/x/signals): Reactive signals and computed values for Effection operations
- [@effectionx/stream-helpers](https://frontside.com/effection/x/stream-helpers): Type-safe stream operators like filter, map, reduce, and forEach
- [@effectionx/stream-yaml](https://frontside.com/effection/x/stream-yaml): Parse streams of strings as YAML documents
- [@effectionx/task-buffer](https://frontside.com/effection/x/task-buffer): Limit concurrent task execution with automatic queuing
- [@effectionx/test-adapter](https://frontside.com/effection/x/test-adapter): Abstract helper for integrating Effection with testing frameworks
- [@effectionx/timebox](https://frontside.com/effection/x/timebox): Constrain operations to complete within a time limit
- [@effectionx/tinyexec](https://frontside.com/effection/x/tinyexec): Lightweight process execution wrapper around tinyexec
- [@effectionx/vitest](https://frontside.com/effection/x/vitest): Vitest adapter for writing tests as Effection generator functions
- [@effectionx/watch](https://frontside.com/effection/x/watch): Run commands and restart them gracefully when source files change
- [@effectionx/websocket](https://frontside.com/effection/x/websocket): WebSocket client with stream-based message handling and automatic cleanup
- [@effectionx/worker](https://frontside.com/effection/x/worker): Web Worker integration with two-way messaging and graceful shutdown

## Optional

- [Full EffectionX catalog with documentation](https://frontside.com/effection/x/)
- [Effection Blog](https://frontside.com/effection/blog)

---

[AGENTS.md]: https://raw.githubusercontent.com/thefrontside/effection/v4/AGENTS.md
[API]: https://frontside.com/effection/api/
[Guides]: https://frontside.com/effection/guides/v4
[Thinking in Effection]: https://raw.githubusercontent.com/thefrontside/effection/v4/docs/thinking-in-effection.mdx
[Async Rosetta Stone]: https://raw.githubusercontent.com/thefrontside/effection/v4/docs/async-rosetta-stone.mdx
[Operations]: https://raw.githubusercontent.com/thefrontside/effection/v4/docs/operations.mdx
[Scope]: https://raw.githubusercontent.com/thefrontside/effection/v4/docs/scope.mdx
[Resources]: https://raw.githubusercontent.com/thefrontside/effection/v4/docs/resources.mdx
[Spawn]: https://raw.githubusercontent.com/thefrontside/effection/v4/docs/spawn.mdx
[Collections]: https://raw.githubusercontent.com/thefrontside/effection/v4/docs/collections.mdx