# flatMapConcurrently

Maps each element of an Fx to a new Fx, running them concurrently with a limit.

## Signatures

```ts
export declare const flatMapConcurrently: {
    <A, B, E2, R2>(f: (a: A) => Fx<B, E2, R2>, concurrency: number): <E, R>(self: Fx<A, E, R>) => Fx<B, E | E2 | Cause.IllegalArgumentError, R | R2 | Scope.Scope>;
    <A, E, R, B, E2, R2>(self: Fx<A, E, R>, f: (a: A) => Fx<B, E2, R2>, concurrency: number): Fx<B, E | E2 | Cause.IllegalArgumentError, R | R2 | Scope.Scope>;
};
```

## Why

This is the admission-controlled form of {@link flatMap }. It bounds active
work while retaining every source value, which is appropriate when a remote
service or local resource has a known concurrency budget.

## Concurrency, ordering, and buffering

Each source value creates one child fiber. A semaphore admits at most
`concurrency` inners into execution; excess fibers wait for a permit rather
than being dropped. Values from each inner retain local order, but admitted
inners may interleave and output is not reordered into source order.

## Ownership and lifetime

A non-positive, fractional, infinite, or unsafe-integer limit fails through
the Sink with `Cause.IllegalArgumentError`. Source and inner failures and
services remain typed. The required `Scope` owns waiting and active fibers;
source completion waits for all of them, and interruption cancels both groups
and runs active inner finalizers.

## Examples

```ts
import { Fx } from "@typed/fx"
import { Effect } from "effect"

const jobs = Fx.fromIterable([
  { id: "one", wait: "20 millis" as const },
  { id: "two", wait: "20 millis" as const },
  { id: "three", wait: "1 millis" as const }
])
const bounded = Fx.flatMapConcurrently(
  jobs,
  ({ id, wait }) => Fx.at(id, wait),
  2
)

Effect.runPromise(Effect.scoped(Fx.collectAll(bounded))).then(console.log)
// "three" waits for one of the first two permits despite its shorter delay
```