sb-dev/openquant / .agents/skills/node
node
VerifiedProvides domain-specific best practices for Node.js development with TypeScript, covering type stripping, async patterns, error handling, streams, modules, testing, performance, caching, logging, and more. Use when setting up Node.js projects with native TypeScript support, configuring type stripping (--experimental-strip-types), writing Node 22+ TypeScript without a build step, or when the user mentions 'native TypeScript in Node', 'strip types', 'Node 22 TypeScript', '.ts files without compilation', 'ts-node alternative', or needs guidance on error handling, graceful shutdown, flaky tests, profiling, or environment configuration in Node.js. Helps configure tsconfig.json for type stripping, set up package.json scripts, handle module resolution and import extensions, and apply robust patterns across the full Node.js stack.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.3 KB |
| rules/assets/graceful-server.test.ts | script | 2.6 KB |
| rules/assets/graceful-server.ts | script | 2.2 KB |
| rules/async-patterns.md | markdown | 3.1 KB |
| rules/caching.md | markdown | 4.8 KB |
| rules/environment.md | markdown | 6.0 KB |
| rules/error-handling.md | markdown | 3.8 KB |
| rules/flaky-tests.md | markdown | 10.4 KB |
| rules/graceful-shutdown.md | markdown | 4.6 KB |
| rules/logging.md | markdown | 4.4 KB |
| rules/modules.md | markdown | 2.0 KB |
| rules/node-modules-exploration.md | markdown | 3.6 KB |
| rules/performance.md | markdown | 2.8 KB |
| rules/profiling.md | markdown | 3.9 KB |
| rules/streams.md | markdown | 5.1 KB |
| rules/stuck-processes-and-tests.md | markdown | 3.9 KB |
| rules/testing.md | markdown | 4.4 KB |
| rules/typescript.md | markdown | 5.5 KB |
| tile.json | config | 1017 B |
rules/async-patterns.md
View on GitHub---
name: async-patterns
description: Async/await and Promise patterns
metadata:
tags: async, await, promises, concurrency
---
# Async Patterns in Node.js
## Always Prefer async/await
Use async/await over raw Promises for readability:
```typescript
// GOOD
async function processItems(items: Item[]): Promise<Result[]> {
const results: Result[] = [];
for (const item of items) {
const result = await processItem(item);
results.push(result);
}
return results;
}
// AVOID - callback-style Promise chains
function processItems(items: Item[]): Promise<Result[]> {
return Promise.resolve([])
.then((results) => {
return items.reduce((chain, item) => {
return chain.then((r) => processItem(item).then((res) => [...r, res]));
}, Promise.resolve(results));
});
}
```
## Parallel Execution with Promise.all
Use Promise.all for independent operations:
```typescript
async function fetchAllData(ids: string[]): Promise<Data[]> {
const promises = ids.map((id) => fetchData(id));
return Promise.all(promises);
}
```
## Controlled Concurrency
Limit concurrent operations to prevent resource exhaustion and extreme memory usage. Use [p-limit](https://github.com/sindresorhus/p-limit) or [p-map](https://github.com/sindresorhus/p-map):
```typescript
import pLimit from 'p-limit';
const limit = pLimit(5); // Max 5 concurrent operations
const results = await Promise.all(
items.map((item) => limit(() => processItem(item)))
);
```
Or use p-map for cleaner syntax:
```typescript
import pMap from 'p-map';
const results = await pMap(items, processItem, { concurrency: 5 });
```
## Promise.allSettled for Fault Tolerance
Use Promise.allSettled when some failures are acceptable:
```typescript
async function fetchMultiple(urls: string[]): Promise<Map<string, string | Error>> {
const results = await Promise.allSettled(
urls.map((url) => fetch(url).then((r) => r.text()))
);
const map = new Map<string, string | Error>();
urls.forEach((url, i) => {
const result = results[i];
map.set(
url,
result.status === 'fulfilled' ? result.value : result.reason
);
});
return map;
}
```
## Avoid Async in Constructors
Constructors cannot be async. Use factory functions instead:
```typescript
// BAD - constructor cannot await
class Database {
constructor() {
// Cannot use await here
}
}
// GOOD - factory function
class Database {
private constructor(private connection: Connection) {}
static async create(config: Config): Promise<Database> {
const connection = await connect(config);
return new Database(connection);
}
}
// Usage
const db = await Database.create(config);
```
## AbortController for Cancellation
Use AbortController to cancel long-running operations:
```typescript
async function fetchWithTimeout(
url: string,
timeoutMs: number
): Promise<Response> {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
try {
return await fetch(url, { signal: controller.signal });
} finally {
clearTimeout(timeoutId);
}
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |