jdanigo/hydraia / skills/node-patterns
node-patterns
VerifiedNode/TypeScript Backend Patterns
Project layout
- Feature folders over layer folders:
src/orders/{orders.router,orders.service,orders.repo,orders.test}.tsbeatssrc/{routes,services,repos}/orders.tsscattered three places. - One composition root (
src/app.ts) wires everything; entry (src/main.ts) only boots. Handlers stay thin — parse/validate → service call → shape response.
Async discipline
- No floating promises: every promise is awaited, returned, or explicitly
void-ed with a comment. Unhandled rejection = crash in modern Node. - Propagate
AbortSignalthrough request-scoped work (fetch, DB timeouts); cancel on client disconnect for expensive handlers. - No sync I/O (
readFileSync,execSync) on request paths — boot time only. - Concurrency with intent:
Promise.allfor independent work,for…of awaitwhen order matters, a limiter (p-limit) when fan-out is unbounded.
Config
- Typed and validated at boot (zod or equivalent): missing/invalid env kills the process at startup with a clear message — never
process.env.X!scattered through the codebase. - One
config.tsexports the parsed object; nothing else readsprocess.env.
Errors
- Central error taxonomy:
AppErrorsubtypes with status + code (NotFound,Validation,Conflict,Upstream). Handlers throw domain errors; ONE error middleware maps them to responses (problem+json shape). - Never
catch (e) {}— swallow nothing; wrap-and-rethrow with context or let it propagate.
DI boundaries
- NestJS: providers with explicit scopes; beware request-scoped bleeding into singletons.
- Express/Fastify: manual factories — services take dependencies as constructor/args, never import singletons directly. Makes the testing shape below possible.
ESM/CJS pitfalls
- Pick ONE module system per package and align
"type",tsconfigmodule, and tooling. Mixed default/named interop errors are config bugs, not code bugs. __dirnamedoes not exist in ESM —import.meta.url+fileURLToPath.
Testing shape
- vitest/jest for units (services with faked repos), supertest against the composed app for HTTP behavior (status, body, headers — not internals).
- Test files co-located with the feature. Integration tests own their fixtures.
Logging
- Structured (pino), request-correlated (request-id middleware); never
console.login request paths. Log the error object, noterr.messagealone (stack + cause matter).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |