API reference › @evolu/common › Task › SemaphoreByKey

Defined in: packages/common/src/Task.ts:5952

Coordinates concurrent Tasks independently for each key.

SemaphoreByKey intentionally exposes only Task-scoped acquisition helpers, not the complete Semaphore API. Methods like Semaphore.take and 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

isIdle

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

Defined in: packages/common/src/Task.ts:5963

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

snapshot

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

Defined in: packages/common/src/Task.ts:5966

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

withPermit

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

Defined in: packages/common/src/Task.ts:5954

Runs a Task while holding one permit for the key.

withPermits

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

Runs a Task while holding the requested permits for the key.