feat: add task concurrency control

[Teages]

🔗 Linked issue

#1974

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

The PR added a concurrency option to task, allow developer to control task concurrency behavior.

By default it is dedupe and key: (event) => ohash(event.payload).

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[vercel]

@Teages is attempting to deploy a commit to the Nitro Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ed340864-5537-4c7f-9225-681f36399990

📥 Commits

Reviewing files that changed from the base of the PR and between 7b8a8a5 and 665dbd3.

📒 Files selected for processing (4)

• docs/1.docs/50.tasks.md
• src/runtime/internal/task.ts
• src/types/runtime/task.ts
• test/unit/task-concurrency.test.ts

✅ Files skipped from review due to trivial changes (1)

• docs/1.docs/50.tasks.md

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

• src/runtime/internal/task.ts
• test/unit/task-concurrency.test.ts

---

📝 Walkthrough

Walkthrough

Adds a TaskConcurrency type and optional concurrency on Task; refactors runTask to support parallel, dedupe (default), and serial modes with per-key keys and Maps for tracking; includes comprehensive Vitest coverage and documentation updates describing semantics and example usage.

Changes

Task Concurrency Support

Layer / File(s)	Summary
Task Concurrency Type Contract src/types/runtime/task.ts	Introduces exported TaskConcurrency type with parallel, dedupe, and serial modes, optional key?: (event: TaskEvent) => string, and adds optional concurrency?: TaskConcurrency to the Task interface.
runTask Concurrency Implementation src/runtime/internal/task.ts	Refactors runTask to derive handler.concurrency ?? { mode: "dedupe" } and dispatch parallel/dedupe/serial. Adds module-scoped Maps (__runningTasks__, __serialQueues__), helper functions (_callTask, _getTaskConcurrencyKey, _runTaskOnce, _runTaskSerially), and input validation for invalid modes.
Task Concurrency Test Suite test/unit/task-concurrency.test.ts	New Vitest suite mocking virtual tasks and testing default dedupe, custom key dedupe (scoped per task and receiving full TaskEvent), dedupe cleanup after rejection, parallel independence, serial ordering per key, non-blocking across keys, queue continuation after rejection, invalid-mode errors, and missing/unimplemented task errors; includes test helpers.
Task Concurrency Documentation docs/1.docs/50.tasks.md	Updates Task docs to add the concurrency field and rewrite the “Concurrency” section: documents default single-running-instance behavior, explains dedupe/parallel/serial semantics, how key affects grouping, and updates the example to use serial keyed by tenant.

---

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add task concurrency control' follows conventional commits format with the 'feat:' prefix and clearly describes the main change.
Description check	✅ Passed	The description is directly related to the changeset, explaining the new concurrency option for tasks, the default dedupe mode, and the default key function.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/runtime/internal/task.ts (1)

62-109: ⚡ Quick win

Move internal helper functions to the end of the file.

Lines 62-109 introduce non-exported helpers before later exported APIs. Please move these helpers below exported declarations to match project structure conventions.

As per coding guidelines, “Place non-exported/internal helpers at the end of the file.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/runtime/internal/task.ts` around lines 62 - 109, The four internal helper
functions _callTask, _getTaskConcurrencyKey, _runTaskOnce, and _runTaskSerially
(which reference __runningTasks__ and __serialQueues__) are defined before
exported APIs; move these non-exported helpers to the end of the file after all
exported declarations so they live as internal utilities per project convention,
preserving their implementations and imports/closures exactly as-is to avoid
changing behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/runtime/internal/task.ts`:
- Around line 49-60: The current task dispatcher treats any concurrency.mode
value other than "parallel" or "serial" as dedupe, silently accepting invalid
configs; update the logic in the function containing concurrency.mode (which
calls _callTask, _getTaskConcurrencyKey, _runTaskSerially, and _runTaskOnce) to
explicitly handle known modes and throw a clear Error for unknown
concurrency.mode values instead of falling through to _runTaskOnce, so invalid
runtime configuration surfaces immediately.

---

Nitpick comments:
In `@src/runtime/internal/task.ts`:
- Around line 62-109: The four internal helper functions _callTask,
_getTaskConcurrencyKey, _runTaskOnce, and _runTaskSerially (which reference
__runningTasks__ and __serialQueues__) are defined before exported APIs; move
these non-exported helpers to the end of the file after all exported
declarations so they live as internal utilities per project convention,
preserving their implementations and imports/closures exactly as-is to avoid
changing behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bcb5d5cf-826b-4b19-ae17-e53f7a0e72e6

📥 Commits

Reviewing files that changed from the base of the PR and between 4ab22a9 and 8fe7a2a.

📒 Files selected for processing (4)

• docs/1.docs/50.tasks.md
• src/runtime/internal/task.ts
• src/types/runtime/task.ts
• test/unit/task-concurrency.test.ts

[pi0]

Thanks for PR. This is nice to add control but i suggest to keep it simple. Main thing we should do (by default) is to hash task params and make sure name+params is unique (i made pr draft to update it)

[Teages]

This stems from our actual needs: some data synchronization tasks can be dedupeed, but some update tasks should run in serial.

A custom key function is also necessary: ​​I usually add some extra parameters to params, which only used in logging.

@pi0 I have update the default key to ohash(event.payload). It is a breaking change now, but it is experimental feature so that should be fine.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nitro@4315

commit: 665dbd3

[pi0x]

Rebased this on latest main locally. Only the docs concurrency section conflicted, and it was easy to resolve.

• Blocker: ohash is not a Nitro dependency, so pnpm typecheck fails with Cannot find module 'ohash'. Please add it to dependencies and to tracePkgs in build.config.ts, next to croner. With that added, all 11 of your tests pass.
• Docs nit: in the example, payload.tenant is unknown, so the key function needs String(payload.tenant) to typecheck.
• Heads up: fix(tasks): stop scheduled tasks on runtime close #4416 and feat(tasks): add one-time tasks #3237 also change runTask / startScheduleRunner. Whichever lands first, the others will need a rebase. Of the two API proposals, yours reads closer to how Nitro does things.

This comment was written by an AI assistant on behalf of the Nitro maintainers. Please double-check anything that looks wrong.