| name | handling-async |
| description | Manages TypeScript async/await and Promise patterns. Use to prevent common async mistakes, optimize concurrency, and handle promise rejections correctly. |
| metadata | {"sources":["You Don't Know JS: Async & Performance (Kyle Simpson)","Node.js Best Practices (goldbergyoni)","JavaScript: The Definitive Guide (David Flanagan)"]} |
Async Patterns - TypeScript Best Practices
Master async/await, promises, and concurrent operations to build reliable async code.
When to Use
- Reviewing async/await code
- Optimizing API calls and I/O operations
- Debugging promise-related issues
- Implementing concurrent workflows
- Handling timeouts and cancellation
Trigger Phrases:
- "Review async code"
- "Optimize async operations"
- "Fix promise handling"
- "Check concurrent execution"
Rules Overview
Detailed guidance for these rules is available in RULES.md.
Critical (2 rules)
- critical-promise-not-awaited — Always await promises or handle with
.then(). Floating promises cause silent failures.
- critical-promise-constructor-anti — Avoid
new Promise() wrapping existing async operations.
High Priority (5 rules)
- high-async-without-await — An
async function with no await is usually unnecessary overhead. (Heuristic: interface conformance or returning a pre-existing promise may justify it.)
- high-parallel-sequential-confusion — Use
Promise.all() for independent parallel operations.
- high-promise-timeout — Implement timeouts to prevent hanging operations. Use
AbortController / AbortSignal.timeout() for fetch-like APIs, or Promise.race() for generic orchestration.
- high-async-forEach — Don't use
forEach() with async callbacks — promises are silently dropped.
- high-promise-chaining — Prefer async/await over long
.then() chains for readability.
Medium Priority (3 rules)
- medium-concurrent-limit — Limit concurrent operations with pooling to prevent resource exhaustion.
- medium-promise-allsettled — Use
Promise.allSettled() when partial failures are acceptable.
- medium-async-iife — Use top-level await (ES2022+) or async IIFE with proper error handling.
Summary
Async patterns ensure:
- ✅ All promises awaited or explicitly handled
- ✅ Parallel execution where possible
- ✅ Timeouts via AbortController or Promise.race()
- ✅ Proper forEach alternatives
- ✅ Fault-tolerant concurrent operations
- ✅ Readable async/await over chains
Refer to the Detailed Rule Catalog for examples and detection criteria.
