feat: add TaskSemaphore utility

[edelauna]

Related GitHub Issue

Closes: #362

Description

Adds TaskSemaphore, a small wrapper around the existing async-mutexSemaphore dependency for task concurrency control.

Key behavior:

• exposes available via the underlying semaphore value
• exposes waiting for queued acquire observability
• returns the underlying release function from acquire()
• rejects queued waiters through cancel()

The wrapper keeps waiting scoped to actual queued acquires: immediate acquires are not counted, and cancel() resets the local waiting count synchronously while guarding stale rejection continuations with a generation token.

Test Procedure

Ran the focused utility test:

source~/.nvm/nvm.sh
nvm use 20.20.2
pnpm --filter zoo-code exec vitest run utils/__tests__/TaskSemaphore.spec.ts

Result: 7 tests passed.

Pre-Submission Checklist

• Issue Linked: This PR is linked to an approved GitHub Issue.
• Scope: My changes are focused on the linked issue.
• Self-Review: I have performed a thorough self-review of my code.
• Testing: New tests have been added to cover my changes.
• Documentation Impact: I have considered whether documentation updates are required.
• Contribution Guidelines: I have read and agree to the Contributor Guidelines.

Screenshots / Videos

Not applicable; this is a utility-only change.

Documentation Updates

• No documentation updates are required.

Additional Notes

This is part of #356, Epic 1: Foundation.

Summary by CodeRabbit

• New Features
  • Added a new TaskSemaphore utility to help limit concurrent task execution, with built-in tracking of pending work and support for canceling queued waits.
• Tests
  • Added comprehensive tests covering immediate and queued acquisition behavior, correct waiting/availability tracking, and cancellation/reset scenarios, including safe behavior when cancel is called while idle.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6db38804-b521-43fd-8e4d-23964b24be8d

📥 Commits

Reviewing files that changed from the base of the PR and between 356b83c and 33fa87a.

📒 Files selected for processing (2)

• src/utils/TaskSemaphore.ts
• src/utils/__tests__/TaskSemaphore.spec.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/utils/TaskSemaphore.ts

---

📝 Walkthrough

Walkthrough

Adds src/utils/TaskSemaphore.ts, a new exported class wrapping async-mutex's Semaphore with an introspectable waiting counter and generation-based cancellation guard. A matching Vitest suite in src/utils/__tests__/TaskSemaphore.spec.ts validates all counter transitions and cancellation semantics.

Changes

TaskSemaphore utility

Layer / File(s)	Summary
TaskSemaphore class: state, acquire, cancel src/utils/TaskSemaphore.ts	Defines TaskSemaphore with a Semaphore backing field, _waiting counter, and _generation value. acquire() increments _waiting only when the semaphore is locked and decrements under a generation guard on both success and error paths. cancel() resets _waiting, bumps _generation, and delegates to Semaphore.cancel().
Test suite for all counter and cancellation semantics src/utils/__tests__/TaskSemaphore.spec.ts	Vitest suite using fake timers covering immediate resolution, queued acquire ordering, per-release unblocking, available/waiting accuracy across acquire–release cycles, cancel() rejecting all waiters, waiting staying 0 during an in-flight immediate acquire, cancel() resetting waiting synchronously before promise callbacks fire, acquire still working after cancel, and cancel being safe on an idle semaphore.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 A semaphore wraps with a watchful eye,
counting the waiters as futures fly.
Generations tick when cancels appear,
stale decrements banished — no drift to fear.
Permits restore, the queue hops along,
TaskSemaphore hums its concurrency song! 🎶

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly and concisely summarizes the main change: adding the TaskSemaphore utility. It is specific, descriptive, and accurately reflects the primary objective.
Description check	✅ Passed	The PR description comprehensively addresses all required template sections with concrete details about the implementation, test procedure, and completion of the pre-submission checklist.
Linked Issues check	✅ Passed	The implementation fully satisfies issue #362 requirements: TaskSemaphore wrapper is created with available/waiting properties, acquire() and cancel() methods, generation-based cancellation safety, and comprehensive test coverage addressing all specified scenarios.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #362: adding TaskSemaphore.ts and its test file. No modifications to existing code or unrelated functionality are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue/362

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 94.11765% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/utils/TaskSemaphore.ts	94.11%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[navedmerchant]

Code review notes — two low-severity suggestions for the test suite (L1, L2). Implementation logic is correct; these are about test robustness and contract coverage.