effect-parallelization
/effect-parallelization
Run Effect computations concurrently with Effect.all/forEach concurrency options, racing combinators (race, raceAll, raceFirst), and coordination primitives (Semaphore, PartitionedSemaphore, Latch). Use when fanning out work over a collection, limiting parallelism, racing alternatives for first-success, enforcing per-key or global rate limits, or gating fibers on a startup signal.
- Author
- mpsuesser ↗
- Repository
- opencode-effect-enforcer ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 1
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Run Effect computations concurrently with Effect.all/forEach concurrency options, racing combinators (race, raceAll, raceFirst), and coordination primitives (Semaphore, PartitionedSemaphore, Latch). Use when fanning out work over a collection, limiting parallelism, racing alternatives for first-success, enforcing per-key or global rate limits, or gating fibers on a startup signal.
Original author description
Run Effect computations concurrently with Effect.all/forEach concurrency options, racing combinators (race, raceAll, raceFirst), and coordination primitives (Semaphore, PartitionedSemaphore, Latch). Use when fanning out work over a collection, limiting parallelism, racing alternatives for first-success, enforcing per-key or global rate limits, or gating fibers on a startup signal.
How it works
- Effect Source Reference
- Core Model
- 1. The concurrency Option
- 2. Effect.all — Tuples, Arrays, Records, Iterables
- 3. Effect.forEach — Effectful Iteration
- 4. Concurrent Zips
- 5. Racing
- 6. Concurrent Filtering, Partitioning, Validation
- 7. Semaphore — Bounded Access to Shared Resources
- 8. PartitionedSemaphore — Keyed Fairness over a Shared Pool
SKILL.md preview
---
name: effect-parallelization
description: Run Effect computations concurrently with Effect.all/forEach concurrency options, racing combinators (race, raceAll, raceFirst), and coordination primitives (Semaphore, PartitionedSemaphore, Latch). Use when fanning out work over a collection, limiting parallelism, racing alternatives for first-success, enforcing per-key or global rate limits, or gating fibers on a startup signal.
---
You are an Effect TypeScript expert specializing in declarative concurrency — `Effect.all`, `Effect.forEach`, racing, and the coordination primitives `Semaphore`, `PartitionedSemaphore`, and `Latch`.
## Effect Source Reference
Baseline: **effect@4.0.6 stable**. Inspect paths with
`git show effect@4.0.6:<path>`; newer main is not the release contract.
The Effect v4 source is at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`. Read it directly when in doubt — Effect v4 differs substantially from v3 and from most training data.
Key files:
- `packages/effect/src/Effect.ts` — `all`, `forEach`, `race`/`raceAll`/`raceFirst`/`raceAllFirst`, `firstSuccessOf`, `timeout`/`timeoutOption`/`timeoutOrElse`, `zip`/`zipWith`, `filter`/`filterMap`/`filterMapEffect`, `partition`, `validate`, `findFirst`, and `replicate`/`replicateEffect` (very large file — grep for the export, then read its JSDoc)
- `packages/effect/src/Types.ts` — the `Concurrency` type (`number | "unbounded"`)
- `packages/effect/src/Semaphore.ts` — counting semaphore: `make`, `withPermit(s)`, `withPermitsIfAvailable`, `take`/`release`/`releaseAll`, `resize`
- `packages/effect/src/PartitionedSemaphore.ts` — keyed permit pool with round-robin fairness across partitions
- `packages/effect/src/Latch.ts` — open/closed gate: `make`, `open`, `close`, `release`, `await`, `whenOpen`
- `packages/effect/src/internal/effect.ts` — the actual implementations (`forEachConcurrent`, `raceAll`, ...) when you need exact semantics
- `packages/effect/test/Effect.test.ts` — `forEach`/`all`/`partition`/`validate`/`raceAll` describe blocks with interruption edge cases
- `packages/effect/test/Semaphore.test.ts`, `test/PartitionedSemaphore.test.ts`, `test/Latch.test.ts` — real usage with `TestClock`
- `migration/v3-to-v4.md` — rename map (e.g. `Effect.makeSemaphore` → `Semaphore.make`)
## Core Model
Concurrency in Effect is declarative: combinators that operate on many effects take a `concurrency` option, fork child fibers internally, and uphold structured concurrency — when the combined effect finishes, fails, or is interrupted, every in-flight child fiber is interrupted before the result is produced.
```ts
// Types.Concurrency
type Concurrency = number | 'unbounded';
```
| Value | Meaning |
| --- | --- |
| omitted | Sequential (concurrency 1). **This is the default.** |
| `n: number` | At most `n` effects run at once (values < 1 are clamped to 1) |
| `'unbounded'` | All effects start at once |
The two central signatures:
```ts
// Combine a fixed structure of effects (tuple, array, iterable, or record)
Effect.all(arg, options?: {
concurrency?: Concurrency;
discard?: boolean; // true => Effect<void>
mode?: 'default' | 'result'; // 'result' => typed E is never, each slot is a Result<A, E>
});
// Apply an effectful function over an Iterable
Effect.forEach(elements, (a, index) => Effect<B, E, R>, options?: {
concurrency?: Concurrency;
discard?: boolean;
});
// Standalone data-last form
Effect.forEach((a, index) => Effect<B, E, R>, options?)(elements);
```
Imports used throughout this skill (all from the stable `effect` barrel):
```ts
import { Effect, Latch, PartitionedSemaphore, Result, Semaphore } from 'effect';
```
For manual fiber control (`Effect.forkChild`, `Fiber.join`, `FiberSet`, ...) see the `effect-fiber` skill. For pipelines over values produced over time, see the `effect-stream` skill.
---
## 1. The `concurrency` Option
Every collection combinator (`all`, `forEach`, `filter`, `partition`, `validate`, `replicateEffect`, `filterMapEffect`) accepts the same option. Without it, execution is **sequential**:
```ts
// Sequential — one at a time (the default!)
yield* Effect.forEach(ids, fetchUser);
// At most 8 in flight
yield* Effect.forEach(ids, fetchUser, { concurrency: 8 });
// All at once
yield* Effect.forEach(ids, fetchUser, { concurrency: 'unbounded' });
```
Reusable APIs that expose fan-out policy should accept a `Types.Concurrency` value and pass it explicitly to each combinator instead of relying on ambient configuration.
### Failure semantics under concurrency
The default mode is fail-fast: on the first failure, in-flight siblings are interrupted, not-yet-started items are skipped, and the combined effect fails. If several concurrent effects fail before interruption lands, their failure reasons are merged into a single `Cause`. Results are always collected by input index, so success order matches input order regardless of completion order (exceptions: `filter` and `filterMapEffect`, see section 6).
---
## 2. `Effect.all` — Tuples, Arrays, Records, Iterables
The output shape follows the input shape, with types tracked precisely:
```ts
// Tuple — heterogeneous, result is a typed tuple
const [n, s] = yield* Effect.all([Effect.succeed(42), Effect.succeed('hi')]);
// [number, string]
// Record — results collected under the same keys
const page = yield* Effect.all(
{
user: fetchUser(id),
posts: fetchPosts(id),
ads: fetchAds()
},
{ concurrency: 'unbounded' }
);
// { user: User; posts: Post[]; ads: Ad[] }
// Any iterable (Array, Set, generator, ...) — result is an Array
const results = yield* Effect.all(new Set([eff1, eff2, eff3]));
```
### `discard: true` — run for effects only
```ts
yield* Effect.all([logA, logB, logC], { concurrency: 'unbounded', discard: true });
// Effect<void, E, R>
```
### `mode: 'result'` — collect typed outcomes
Each slot becomes a `Result<A, E>` and the error channel becomes `never`. Typed
failures do not short-circuit the batch. A cause containing a defect propagates
with every typed failure promoted to a defect, preserving order and interrupts.
Pure interruption still terminates it, but a typed failure plus interruption
without a defect can be collected as a `Result`, discarding that interruption:
```ts
const results = yield* Effect.all(
[mightFail1, mightFail2, mightFail3],
{ mode: 'result', concurrency: 'unbounded' }
);
// [Result<A1, E1>, Result<A2, E2>, Result<A3, E3>]
const successes = results.filter(Result.isSuccess).map((r) => r.success);
```
`mode: 'result'` works for records too — each value becomes a `Result`. The v3 modes `'either'` and `'validate'` no longer exist; `Result` replaced `Either` in v4, and validate-style accumulation lives in `Effect.validate` (section 6).
### Replication
```ts
// Array of n identical effects (not yet run) — feed to a combinator
const effects = Effect.replicate(pingServer, 5);
yield* Effect.all(effects, { concurrency: 'unbounded' });
// Run an effect n times with Effect.all semantics
const samples = yield* Effect.replicateEffect(measureLatency, 10, {
concurrency: 'unbounded'
});
// Effect<Array<A>, E, R>; supports { discard: true } as well
```
---
## 3. `Effect.forEach` — Effectful Iteration
The workhorse for fan-out over a work list. The callback receives the element and its index:
```ts
const enriched = yield* Effect.forEach(
orders,
(order, index) => enrichOrder(order),
{ concurrency: 8 }
);
// Array<EnrichedOrder> — in input order
// Standalone data-last usage is supported; the callback determines A.
const fetchUsers = Effect.forEach(fetchUser, { concurrency: 8 });
const users = yield* fetchUsers(userIds);
// Side effects only
yield* Effect.forEach(events, publishEvent, {
concurrency: 4,
discard: true
});
```
Notes:
- Works on any `Iterable` — including strings (`Effect.forEach('abc', f)` iterates characters).
- Results are written by index: input order is preserved even with `concurrency: 'unbounded'`.
- Sequential mode (no option) stops at the first failure without starting later elements; concurrent mode interrupts in-flight siblings on failure.
- Interrupting the parent fiber interrupts all in-flight children; items beyond the concurrency window that were never forked simply never run.
- Concurrent `Effect.request` calls inside `forEach` trigger automatic batching — see the `effect-batching` skill.
For an unbounded or infinite source, do not collect into an array — use `Stream.fromIterable(...).pipe(Stream.mapEffect(f, { concurrency }))` instead (see the `effect-stream` skill).
---
## 4. Concurrent Zips
`Effect.zip` and `Effect.zipWith` combine exactly two effects. Their option key is `concurrent: boolean` — **not** `concurrency`:
```ts
// Sequential by default
const pair = yield* Effect.zip(task1, task2);
// [A, B]
// Run both at once
const pair2 = yield* Effect.zip(task1, task2, { concurrent: true });
const combined = yield* Effect.zipWith(
fetchPrice,
fetchQuantity,
(price, qty) => price * qty,
{ concurrent: true }
);
```
`{ concurrent: true }` is implemented as `Effect.all([self, that], { concurrency: 2 })`, so it inherits fail-fast semantics: if one side fails, the other is interrupted.
The v3 `Effect.zipRight`/`Effect.zipLeft` are renamed: use `Effect.andThen` / `Effect.tap`.
---
## 5. Racing
Four combinators, two axes: two effects vs. many, and first-*success* vs. first-*completion*:
| | First success wins | First completion wins (even failure) |
| --- | --- | --- |
| Two effects | `Effect.race(a, b)` | `Effect.raceFirst(a, b)` |
| Iterable | `Effect.raceAll(effects)` | `Effect.raceAllFirst(effects)` |
```ts
// First successful replica wins; losers are interrupted
const fastest = yield* Effect.raceAll(replicaUrls.map(queryReplica));
// First completion settles the race — a fast failure loses you the result
const settled = yield* Effect.raceFirst(primary, secondary);
```
Semantics (verified in `internal/effect.ts`):
- **Loser interruption is awaited**: when a winner settles, the remaining fibers are interrupted uninterruptibly and the race only resumes with the winning exit after those interruptions (including finalizers) complete.
- Cleanup also covers losers still starting when the race settles or the caller is interrupted. Use the race combinators directly rather than custom start/cancel bookkeeping.
- `race`/`raceAll`: early failures do not finish the race — the race keeps waiting until one effect succeeds or all have failed. If all fail, the failure reasons are collected into one combined `Cause`.
- `raceFirst`/`raceAllFirst`: the first fiber to settle (success *or* failure) decides the outcome.
- Effects are forked in iteration order; if an early effect completes synchronously, later effects may never start at all.
- All four accept an optional `onWinner` callback for observing the winning fiber:
```ts
Effect.raceAll(candidates, {
onWinner: ({ fiber, index, parentFiber }) => {
console.log(`candidate ${index} won`);
}
});
```
### Sequential fallback: `firstSuccessOf`
`Effect.firstSuccessOf` is **not** a race — it tries effects one at a time, in order, returning the first success. Later effects never start if an earlier one succeeds. If all fail, it fails with the *last* error; an empty iterable is a defect.
```ts
const config = yield* Effect.firstSuccessOf([
readFromEnv,
readFromFile,
Effect.succeed(defaultConfig)
]);
```
### Timeouts are races against the clock
`Effect.timeout(effect, '5 seconds')` (typed `Cause.TimeoutError` failure), `Effect.timeoutOption` (`Option.none` on timeout), and `Effect.timeoutOrElse` all interrupt the source effect when the timer wins — same structured guarantees as racing.
---
## 6. Concurrent Filtering, Partitioning, Validation
### `Effect.filter` — keep elements passing a predicate
Accepts a plain predicate/refinement, or an effectful predicate with a `concurrency` option:
```ts
// Sync predicate
const evens = yield* Effect.filter([1, 2, 3, 4], (n) => n % 2 === 0);
// Effectful predicate, concurrent
const reachable = yield* Effect.filter(
hosts,
(host) => pingHost(host),
{ concurrency: 10 }
);
```
**Order caveat**: with `concurrency > 1`, `filter` and `filterMapEffect` collect kept values in *completion* order, not input order (they push on completion rather than writing by index).
### `Effect.filterMap` / `Effect.filterMapEffect` — filter + transform
These take a `Filter` (a function returning `Result.succeed(b)` to keep-and-transform or `Result.fail(x)` to skip). `filterMap` is synchronous; `filterMapEffect` is effectful with a `concurrency` option (note: its callback receives only the element, no index):
```ts
const strong = yield* Effect.filterMapEffect(
candidates,
(c) =>
Effect.map(score(c), (s) =>
s > 0.8 ? Result.succeed({ ...c, score: s }) : Result.fail(s)
),
{ concurrency: 4 }
);
// Array of kept, transformed values
```
### `Effect.partition` — collect successes and typed failures
Typed failures do not short-circuit. Returns `[passes, fails]` — **successes first**.
Both arrays preserve input order. Defects and pure interruption propagate;
typed-error-plus-interruption causes follow the `mode: 'result'` rule above:
```ts
const [users, failures] = yield* Effect.partition(
userIds,
(id) => fetchUser(id),
{ concurrency: 8 }
);
// Effect<[passes: Array<User>, fails: Array<E>], never, R>
```
`Arr.partition`, `Arr.separate`, the corresponding `Chunk` / `Record` helpers,
and `Option.partitionMap` also put successes first, matching `Stream.partition`.
Name destructured tuple elements by meaning rather than assuming the older order.
<!-- typecheck -->
```ts
import { Effect } from 'effect';
const partitioned = Effect.partition(
[1, 2, 3],
(n) => n === 2 ? Effect.fail('rejected') : Effect.succeed(n),
{ concurrency: 2 }
);
// Success value: [[1, 3], ['rejected']]
```
### `Effect.validate` — accumulate all failures
Like `partition`, but fails with a `NonEmptyArray<E>` of every failure if at least one element failed; succeeds with all results otherwise. Supports `{ discard: true }`:
```ts
const validated = yield* Effect.validate(
formFields,
(field) => validateField(field),
{ concurrency: 'unbounded' }
);
// Effect<Array<Valid>, NonEmptyArray<FieldError>, R>
```
### `Effect.findFirst` / `Effect.findFirstFilter` — sequential short-circuit search
```ts
const firstHealthy = yield* Effect.findFirst(servers, (s) => checkHealth(s));
// Effect<Option<Server>, E, R> — stops at the first match, always sequential
```
`findFirstFilter` is the transforming variant: the callback returns `Effect<Result<B, X>>` and the first `Result.succeed` short-circuits with `Option.some(b)`.
---
## 7. `Semaphore` — Bounded Access to Shared Resources
A counting semaphore from the `effect/Semaphore` module (exported from the `effect` barrel). Unlike a `concurrency` option — which bounds one call site — a semaphore bounds access *across* call sites and fibers.
```ts
const program = Effect.gen(function* () {
const sem = yield* Semaphore.make(4); // 4 permits
// or synchronously, outside Effect: Semaphore.makeUnsafe(4)
yield* Effect.forEach(
jobs,
(job) => sem.withPermit(processJob(job)),
{ concurrency: 'unbounded', discard: true }
);
});
```
### Instance API
```ts
sem.withPermit(effect); // acquire 1 permit, run, release on exit
sem.withPermits(2)(effect); // weighted — note: curried!
sem.withPermitsIfAvailable(1)(effect); // Effect<Option<A>, E, R> — Option.none if permits unavailable, no waiting
sem.take(2); // Effect<number> — manual acquire (waits; see fairness note below); returns acquired count
sem.takeIfAvailable(2); // Effect<boolean> — acquire immediately or return false
sem.release(2); // Effect<number> — manual release; returns resulting free permits
sem.releaseAll; // Effect<number> — return every taken permit
sem.resize(8); // Effect<void> — change total permits in place
```
### Module-level duals
Every operation also exists as a module function, usable data-first or in pipes:
```ts
yield* Semaphore.withPermit(sem, criticalSection);
yield* Semaphore.withPermits(sem, 2, heavyTask);
yield* heavyTask.pipe(Semaphore.withPermits(sem, 2));
yield* Semaphore.withPermitsIfAvailable(sem, 1, optionalWork); // Option<A>
yield* Semaphore.takeIfAvailable(sem, 2); // boolean; manual non-blocking acquire
yield* Semaphore.resize(sem, 8);
```
Guarantees and gotchas (verified in source/tests):
- `withPermit*` releases permits on success, failure, *and* interruption — acquisition and release are wrapped in `uninterruptibleMask`.
- Pending `take`s are woken in arrival order, but a waiter requesting more permits than are currently free is skipped while later, smaller requests proceed — a `take(1)` can overtake a blocked `take(3)`. Strict FIFO holds only when all requests use the same permit count (e.g. `withPermit`).
- `take(n)`/`release(n)` are a low-level protocol: an unbalanced `release` inflates the permit count; an interrupted fiber between `take` and `release` leaks permits. Prefer `withPermits`.
- Requesting more permits than the total never completes (unless the semaphore is later `resize`d up).
- `resize` can shrink below the currently-taken count; existing holders keep their permits and new acquisitions wait until enough are released.
- `Semaphore.make(1)` is the idiomatic mutex for serializing access to mutable state.
---
## 8. `PartitionedSemaphore` — Keyed Fairness over a Shared Pool
A `PartitionedSemaphore<K>` shares one permit pool across many partition keys, but tracks waiters *per key* and distributes released permits across waiting partitions in **round-robin** order. Use it when independent groups (tenants, hosts, queues) compete for the same bounded resource and a busy group must not starve the others. A plain `Semaphore` serves its single arrival-order queue regardless of key; the partitioned variant interleaves: `p1, p2, p1, p2, ...`.
```ts
const program = Effect.gen(function* () {
const sem = yield* PartitionedSemaphore.make<string>({ permits: 10 });
const handle = (tenantId: string, req: Request) =>
sem.withPermit(tenantId)(processRequest(req));
// Weighted variant
const handleBig = (tenantId: string, req: Request) =>
sem.withPermits(tenantId, 3)(processBigRequest(req));
});
```
### API surface
```ts
PartitionedSemaphore.make<K>({ permits: number }); // Effect<PartitionedSemaphore<K>>
PartitionedSemaphore.makeUnsafe<K>({ permits }); // synchronous
sem.withPermit(key)(effect); // 1 permit for this key
sem.withPermits(key, n)(effect); // n permits — curried, like Semaphore
sem.withPermitsIfAvailable(n)(effect); // NOT keyed — Option<A>, no waiting
sem.take(key, n); // Effect<void> — manual, keyed
sem.release(n); // Effect<number> — manual, not keyed
sem.available; // Effect<number> — free permits (snapshot)
sem.capacity; // number — fixed total
// Module-level duals exist for all of the above:
yield* PartitionedSemaphore.withPermits(sem, 'tenant-a', 2, task);
yield* task.pipe(PartitionedSemaphore.withPermit(sem, 'tenant-a'));
```
Gotchas (verified in source/tests):
- **Requesting more permits than `capacity` never completes** — the take resolves to `Effect.never`, silently hanging the fiber.
- Zero or negative permit requests run the effect immediately without acquiring anything.
- Non-finite `permits` (e.g. `Infinity`) creates an unbounded semaphore where every operation is a no-op pass-through; negative capacities are clamped to 0.
- Interruption while waiting returns any partially-acquired permits to the pool — no leaks.
- `withPermitsIfAvailable` takes no key: it only checks the shared pool.
---
## 9. `Latch` — Gating Fibers on a Signal
A `Latch` is a reusable open/closed gate. Closed: `await` and `whenOpen` suspend. Open: they pass through immediately. Unlike `Deferred` (one-shot, carries a value — see the `effect-fiber` skill), a latch is value-less and can be closed and reopened any number of times.
```ts
const program = Effect.gen(function* () {
const ready = yield* Latch.make(); // starts CLOSED; Latch.make(true) starts open
// or synchronously: Latch.makeUnsafe(false)
// Workers block until the latch opens
const worker = (id: number) =>
Effect.gen(function* () {
yield* ready.await; // suspends while closed
yield* Effect.log(`worker ${id} running`);
});
const fibers = yield* Effect.forEach([1, 2, 3], (id) =>
Effect.forkChild(worker(id))
);
yield* loadConfiguration;
yield* ready.open; // releases all current AND future waiters
});
```
### Operations
```ts
latch.await; // Effect<void> — suspend until open (or released)
latch.open; // Effect<boolean> — open; wake current + future waiters; true if state changed
latch.close; // Effect<boolean> — future waiters suspend again; true if state changed
latch.release; // Effect<boolean> — wake CURRENT waiters only; latch stays closed
latch.whenOpen(effect); // run effect once the latch allows passage
latch.openUnsafe(); // synchronous variants for non-Effect code
latch.closeUnsafe();
// Module-level equivalents
yield* Latch.open(latch);
yield* Latch.await(latch);
yield* Latch.whenOpen(latch, effect);
```
`open` vs `release`: `open` flips the state so all future `await`s pass immediately; `release` is a one-shot pulse — current waiters proceed, the latch remains closed, and the next waiter suspends again. Use close/open pairs to implement pause/resume:
```ts
const running = yield* Latch.make(true); // open = running
// In a polling loop:
const step = running.whenOpen(pollOnce);
// Elsewhere: pause and resume
yield* running.close;
yield* running.open;
```
---
## 10. Structured Concurrency Guarantees
All combinators in this skill uphold the same invariants:
1. **No leaked fibers**: children forked by `all`/`forEach`/`race*`/`zip { concurrent: true }` cannot outlive the combinator. Completion, failure, or interruption of the parent interrupts all in-flight children first.
2. **Fail-fast with cleanup**: in default mode, the first failure interrupts siblings; their finalizers (`Effect.ensuring`, `acquireRelease` releases) run before the combined effect settles.
3. **Interruption propagates**: interrupting the fiber running `Effect.forEach(..., { concurrency: 8 })` interrupts the 8 in-flight workers and skips the rest.
4. **Deterministic results**: `all`/`forEach`/`partition`/`validate` order results by input index regardless of completion order.
When you need to *escape* structure — background fibers, daemons, fiber handles — that is `Effect.forkChild` / `forkScoped` / `forkDetach` territory: see the `effect-fiber` skill. To test concurrent code deterministically with `TestClock`, see the `effect-concurrency-testing` skill.
---
## Key Patterns
### Bounded fan-out with error partitioning
Process a work list with a concurrency cap; collect failures without aborting the batch:
```ts
import { Effect } from 'effect';
const syncAllUsers = (userIds: ReadonlyArray<string>) =>
Effect.gen(function* () {
const [synced, failures] = yield* Effect.partition(
userIds,
(id) => syncUser(id),
{ concurrency: 8 }
);
if (failures.length > 0) {
yield* Effect.log(`${failures.length} of ${userIds.length} failed`);
}
return synced;
});
```
### First-success-wins with sequential fallback
Race the fast replicas concurrently; only if all of them fail, try the expensive cold standby:
```ts
const fetchQuote = Effect.firstSuccessOf([
Effect.raceAll(replicaUrls.map((url) => queryReplica(url))),
queryColdStandby
]);
```
### Hedged requests
Start a backup request only if the primary has not answered within 200ms; whichever succeeds first wins and the loser is interrupted:
```ts
const hedged = Effect.race(
queryPrimary,
Effect.delay(queryBackup, '200 millis')
);
```
### Global rate limit shared across call sites
A `concurrency` option only bounds one combinator call. To bound a resource globally (DB pool, external API), put a semaphore in the service and wrap every operation:
```ts
import { Context, Effect, Layer, Semaphore } from 'effect';
class GeoApi extends Context.Service<
GeoApi,
{ geocode(address: string): Effect.Effect<Coords, GeoError> }
>()('app/GeoApi') {
static readonly layer = Layer.effect(
GeoApi,
Effect.gen(function* () {
const sem = yield* Semaphore.make(5); // provider allows 5 in-flight
const geocode = (address: string) =>
sem.withPermit(callProvider(address));
return { geocode } as const;
})
);
}
// Callers can use any concurrency they like — at most 5 hit the provider
const geocodeMany = (addresses: ReadonlyArray<string>) =>
Effect.gen(function* () {
const { geocode } = yield* GeoApi;
return yield* Effect.forEach(addresses, geocode, {
concurrency: 'unbounded'
});
});
```
### Per-tenant concurrency with cross-tenant fairness
```ts
import { Effect, PartitionedSemaphore } from 'effect';
const makeIngestor = Effect.gen(function* () {
// 16 workers total, shared by all tenants; released permits rotate
// round-robin across tenants with queued work
const sem = yield* PartitionedSemaphore.make<string>({ permits: 16 });
const ingest = (tenantId: string, batch: ReadonlyArray<Event>) =>
sem.withPermit(tenantId)(writeBatch(tenantId, batch));
return { ingest } as const;
});
```
### Coordinated startup with a latch
Fork workers eagerly, but hold them at a gate until initialization completes:
```ts
import { Effect, Latch } from 'effect';
const main = Effect.gen(function* () {
const ready = yield* Latch.make(); // closed
yield* Effect.forEach(
queueNames,
(name) => Effect.forkChild(ready.whenOpen(consumeQueue(name))),
{ discard: true }
);
yield* runMigrations;
yield* warmCaches;
yield* ready.open; // all consumers start together
});
```
### Throttled batch processing
Combine chunking with bounded concurrency — at most 4 batches in flight, each batch written atomically:
```ts
import { Array as Arr, Effect } from 'effect';
const writeAll = (rows: ReadonlyArray<Row>) =>
Effect.forEach(
Arr.chunksOf(rows, 100),
(batch) => insertBatch(batch),
{ concurrency: 4, discard: true }
);
```
### Validate everything, report every error
```ts
const checkConfig = (entries: ReadonlyArray<Entry>) =>
Effect.validate(entries, validateEntry, { concurrency: 'unbounded' }).pipe(
Effect.mapError((errors) => new ConfigInvalid({ errors }))
);
```
---
## Common Mistakes
1. **Assuming `Effect.all` / `Effect.forEach` are parallel by default** — they are sequential. Pass `{ concurrency: n | 'unbounded' }` explicitly; without it you also silently lose request batching (see effect-batching).
2. **Relying on ambient concurrency** — pass a number or `"unbounded"` explicitly at each combinator.
3. **Wrong option key on zips** — `Effect.zip`/`zipWith` take `{ concurrent: true }` (boolean), not `{ concurrency: ... }`.
4. **v3 `mode: 'either'` / `mode: 'validate'` on `Effect.all`** — gone. v4 has `mode: 'result'` (slots become `Result<A, E>`); for accumulate-all-failures use `Effect.validate`, which fails with `NonEmptyArray<E>`.
5. **`Effect.makeSemaphore` / `Effect.makeLatch` no longer exist** — they moved to their own modules: `Semaphore.make(n)`, `Latch.make(open?)`, both importable from `'effect'`.
6. **Expecting `firstSuccessOf` to race** — it is strictly sequential (and fails with only the *last* error). For concurrent first-success with loser interruption, use `Effect.raceAll`.
7. **Confusing `race` with `raceFirst`** — `race`/`raceAll` ignore failures until something succeeds (or everything fails); `raceFirst`/`raceAllFirst` settle on the first completion, so a fast failure wins the race and fails the whole thing.
8. **Relying on output order from concurrent `Effect.filter`/`filterMapEffect`** — they collect in completion order. `forEach`, `all`, `partition`, and `validate` preserve input order; the filters do not.
9. **Calling `sem.withPermits(2, effect)` on the instance** — instance `withPermits(n)` is curried: `sem.withPermits(2)(effect)`. Only the module-level `Semaphore.withPermits(sem, 2, effect)` takes the effect as a third argument. Same for `PartitionedSemaphore`.
10. **Manual `take`/`release` instead of `withPermits`** — an interrupt between `take` and `release` leaks permits and an extra `release` inflates the pool. `withPermit(s)` is interruption-safe.
11. **Requesting more permits than capacity** — on `PartitionedSemaphore` this resolves to `Effect.never` (silent hang); on `Semaphore` it waits forever unless someone calls `resize`. Validate weights against capacity.
12. **Using `latch.release` to open a latch** — `release` only wakes the *current* waiters and leaves the latch closed; the next `await` suspends again. Use `latch.open` to let future waiters through.
13. **Hand-rolling `Promise.allSettled` semantics** — don't wrap exits manually; `Effect.all(..., { mode: 'result' })` or `Effect.partition` already run everything and surface per-item outcomes.
14. **Using v3 fork names (`Effect.fork`, `forkDaemon`)** — see the effect-fiber skill for the v4 equivalents.
15. **Fanning out an unbounded source through `forEach`** — `forEach` materializes the iterable into an array under concurrency. For large or infinite inputs use `Stream.mapEffect(f, { concurrency })` (effect-stream skill) to keep backpressure.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mpsuesser/opencode-effect-enforcer | 95 | MIT |
| mpsuesser/opencode-effect-enforcer | 95 | MIT |
Database snapshot: 13.11.2026 · package version 85e30dc1dac9 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95effect-concurrency-testing
Test Effect concurrency primitives including PubSub, Deferred, Latch, Fiber coordination, SubscriptionRef, and Stream. Use this skill when testing concurrent effects, event-driven systems, or fiber coordination. - 95effect-concurrency-testing
Test Effect concurrency primitives including PubSub, Deferred, Latch, Fiber coordination, SubscriptionRef, and Stream. Use this skill when testing concurrent effects, event-driven systems, or fiber coordination. - 95effect-concurrency
Use when Effect concurrency patterns including fibers, fork, join, parallel execution, and race conditions. Use for concurrent operations in Effect applications. - 100effect-v3-to-v4
Use this skill when migrating a codebase from Effect v3 to Effect v4, upgrading `effect` or any `@effect/*` package across the v3/v4 boundary. - 100effect
Writes and reviews Effect v4 TypeScript code against the installed release instead of remembered Effect 3 APIs. Use when changing Effect services, layers, errors, schemas, resources, fibers, retries, config, logging, HttpApi or HttpClient, SQL, effect/cli commands or @effect/vitest tests. - 100effect-ts
Effect-TS guide for TypeScript, v4 default with v3 support. Use when writing, debugging, or reviewing Effect code across errors, concurrency, services, streams, and schema, or when code imports from 'effect' or any '@effect/*' package.