Skip to content

jdanigo/hydraia / skills/node-patterns

node-patterns

Verified

Node/TypeScript Backend Patterns

Project layout

  • Feature folders over layer folders: src/orders/{orders.router,orders.service,orders.repo,orders.test}.ts beats src/{routes,services,repos}/orders.ts scattered 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 AbortSignal through 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.all for independent work, for…of await when 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.ts exports the parsed object; nothing else reads process.env.

Errors

  • Central error taxonomy: AppError subtypes 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", tsconfig module, and tooling. Mixed default/named interop errors are config bugs, not code bugs.
  • __dirname does 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.log in request paths. Log the error object, not err.message alone (stack + cause matter).
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall