[API reference](https://evolu.dev/docs/api-reference) › [@evolu/common](https://evolu.dev/docs/api-reference/common) › [Task](https://evolu.dev/docs/api-reference/common/Task) › SemaphoreByKey

Defined in: [packages/common/src/Task.ts:5952](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Task.ts#L5952)

Coordinates concurrent [Task](https://evolu.dev/docs/api-reference/common/Task/type-aliases/Task)s independently for each key.

`SemaphoreByKey` intentionally exposes only Task-scoped acquisition helpers,
not the complete [Semaphore](https://evolu.dev/docs/api-reference/common/Task/interfaces/Semaphore) API. Methods like [Semaphore.take](https://evolu.dev/docs/api-reference/common/Task/interfaces/Semaphore#take) and
[Semaphore.resize](https://evolu.dev/docs/api-reference/common/Task/interfaces/Semaphore#resize) would expose per-key semaphores as long-lived
resources, making idle-key cleanup less predictable and making accidental key
retention easier.

Use Semaphore directly when callers need to hold permits while starting
several child Tasks or resize a permit pool. Use `SemaphoreByKey` when permit
ownership should be tied to one Task lifetime and idle keys can be forgotten
automatically.

## Properties

<a id="isidle"></a>

### isIdle

```ts
readonly isIdle: (key: K) => boolean;
```

Defined in: [packages/common/src/Task.ts:5963](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Task.ts#L5963)

Whether no permits are held and no requests are queued for the key.

### snapshot

```ts
readonly snapshot: (key: K) =>
  | SemaphoreSnapshot
  | null;
```

Defined in: [packages/common/src/Task.ts:5966](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Task.ts#L5966)

Returns the current key state, or null when the key is idle.

### withPermit

```ts
readonly withPermit: <T, E, D>(key: K, task: Task<T, E, D>) => Task<T, E, D>;
```

Defined in: [packages/common/src/Task.ts:5954](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Task.ts#L5954)

Runs a [Task](https://evolu.dev/docs/api-reference/common/Task/type-aliases/Task) while holding one permit for the key.

### withPermits

```ts
readonly withPermits: (key: K, permits: Int1To100OrPositiveInt) => <T, E, D>(task: Task<T, E, D>) => Task<T, E, D>;
```

Defined in: [packages/common/src/Task.ts:5957](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Task.ts#L5957)

Runs a [Task](https://evolu.dev/docs/api-reference/common/Task/type-aliases/Task) while holding the requested permits for the key.