Nodejs Backend

Node.js Backend

Verify before implementing: For framework-specific APIs (Express 5, Fastify 5, Node.js 22+ built-ins), look up current docs via Context7 (query-docs) before writing code. Training data may lag current releases.

Framework Selection

Ask user: deployment target, cold start needs, team experience, existing codebase.

Architecture

src/
├── routes/          # HTTP: parse request, call service, format response
├── middleware/       # Auth, validation, rate limiting, logging
├── services/        # Business logic (no HTTP types)
├── repositories/    # Data access only (queries, ORM)
├── config/          # Env, DB pool, constants
└── types/           # Shared TypeScript interfaces

• Routes never contain business logic
• Services never import Request/Response
• Repositories never throw HTTP errors
• Dependencies point inward only (Clean Architecture rule): routes -> services -> repositories. Never the reverse.
• For scripts/prototypes: single file is fine -- ask "will this grow?"

TypeScript Rules

• Use import type { } for type-only imports -- eliminates runtime overhead
• Prefer interface for object shapes (2-5x faster type resolution than intersections)
• Prefer unknown over any -- forces explicit narrowing
• Use z.infer<typeof Schema> as single source of truth -- never duplicate types and schemas
• Minimize as assertions -- use type guards instead
• Add explicit return types to exported functions (faster declaration emit)
• Untyped package? declare module 'pkg' { const v: unknown; export default v; } in types/ambient.d.ts

Validation

Zod (TypeScript inference) or TypeBox (Fastify native). Validate at boundaries only: request entry, before DB ops, env vars at startup. Use .extend(), .pick(), .omit(), .partial(), .merge() for DRY schemas.

Error Handling

Custom error hierarchy: AppError(message, statusCode, isOperational) → ValidationError(400), NotFoundError(404), UnauthorizedError(401), ForbiddenError(403), ConflictError(409)

Centralized handler middleware:

• AppError → return { error: message } with statusCode
• Unknown → log full stack, return 500 + generic message in production
• Async wrapper: const asyncHandler = (fn) => (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);

Codes: 400 bad input | 401 no auth | 403 no permission | 404 missing | 409 conflict | 422 business rule | 429 rate limited | 500 server fault

API Design

Contract-first: define route schemas (Zod schemas, Fastify JSON Schema, or OpenAPI spec) before writing handler logic. The schema is the contract -- implementation follows. Generate OpenAPI/Swagger docs from these schemas for interactive API documentation.

• Hyrum's Law awareness: every observable response field, ordering, or timing becomes a dependency for callers. Use Zod schemas or Fastify response schemas to control exactly what's serialized -- never return raw ORM objects or untyped objects from handlers.
• Addition over modification: add new optional fields rather than changing or removing existing ones. Removing a field from a response schema breaks callers silently. Deprecate first (mark in OpenAPI spec), remove in a later version.
• Consistent error envelope: all errors -- validation, auth, not-found, application -- must produce the same { error: { code, message, details? } } structure. Centralize in the error handler middleware. Callers build error handling once; inconsistent errors force per-endpoint special cases.
• Boundary validation: validate at the middleware/route handler level (Zod .parse() on request body/params, Fastify schema validation). Services and repositories trust that input was validated at entry -- no redundant checks scattered through business logic.
• Third-party responses are untrusted data: validate shape and content of external API responses before using them in logic, rendering, or decision-making. A compromised or misbehaving service can return unexpected types, malicious content, or missing fields. Parse through a Zod schema before use.
• Resources: plural nouns (/users), max 2 nesting levels (/users/:id/orders)
• Methods: GET read | POST create | PUT replace | PATCH partial | DELETE remove
• Versioning: URL path /api/v1/
• Response: { data, pagination?: { page, limit, total, totalPages } }
• Queries: ?page=1&limit=20&status=active&sort=createdAt,desc
• Return Location header on 201. Use 204 for successful DELETE with no body.

Async Patterns

Never use readFileSync or other sync methods in production -- use fs.promises or stream equivalents. Offload CPU work to worker threads (Piscina). Stream large payloads.

Production Resilience

• Fail-fast env validation: parse and validate all environment variables at startup with a Zod schema (const env = envSchema.parse(process.env)). If invalid, crash before serving traffic. Never discover a missing env var on the first request that needs it.
• Health endpoints: expose both /health (shallow, always 200 if process is alive) and /ready (deep, verifies database, cache, and critical dependencies are reachable). Load balancers probe /ready for traffic routing; monitoring probes /health for process liveness. Don't conflate them.
• Caching: Redis cache-aside for DB/API responses; in-memory LRU with TTL for hot paths. Always invalidate on writes.
• Load shedding: @fastify/under-pressure (or equivalent) -- monitor event loop delay, heap, RSS; return 503 when thresholds exceeded.
• Response schemas: In Fastify, always define response schemas -- enables fast-json-stringify for 2-3x faster serialization.
• Circuit breaker: use opossum for outbound service calls. States: CLOSED (normal) -> OPEN (failing, return fallback) -> HALF_OPEN (probe). Prevents cascade failures when downstream services are down.

Observability

• Define "working" before instrumenting: write the questions an on-call engineer will ask when this is broken at 3am ("which dependency is timing out?", "is it all users or one tenant?"), then add only the telemetry that answers them. Instrumentation with no question behind it is cost and noise.
• Pick the signal by the question it answers: logs = "what happened in this one case?" (high-detail, structured, sampled under load); metrics = "how often / how fast / how saturated?" (cheap aggregates — keep label cardinality bounded, never user IDs or request IDs as labels); traces = "where did the time or the error go across services?".
• Structured logging: pino with a stable set of event names and a correlation/request ID propagated through async context (AsyncLocalStorage). Never console.log in production paths.
• Metrics: prom-client for RED per route — Rate (request count), Errors (error count), Duration (latency histogram). OpenTelemetry Node SDK for distributed traces across services.
• Initialize tracing before app imports, then verify it fires: the OTel SDK must start before the modules it instruments are required, or auto-instrumentation silently no-ops. Before relying on any signal, force an error and send test traffic in staging and confirm the log/metric/trace actually lands — untested instrumentation fails silent.
• Alert on symptoms, not causes: page on user-visible symptoms (error-rate spike, latency SLO burn, /ready flapping), not on causes (CPU high, heap growing). A cause with no symptom is a dashboard, not a page.

Discipline

• Simplicity first -- every change as simple as possible, impact minimal code
• Only touch what's necessary -- avoid introducing unrelated changes
• No hacky workarounds -- if a fix feels wrong, step back and implement the clean solution
• Before adding a new abstraction, verify it appears in 3+ places. If not, inline it.
• If a fix requires bypassing TypeScript (as any, non-null assertions on untrusted data, // @ts-ignore), treat it as a design smell and find the typed solution
• Verify: tsc --noEmit && npm test pass with zero warnings before declaring done

Verify

• tsc --noEmit passes with zero errors
• npm test passes with zero failures
• No TypeScript bypasses (as any, @ts-ignore) in new code

References

• TypeScript config -- tsconfig, ESM, branded types, compiler performance
• Security -- JWT, password hashing, rate limiting, OWASP
• API design patterns -- pagination, filtering, sorting, deprecation
• Database & production -- connection pooling, transactions, Docker, logging

API Design Patterns

When to read: when designing a REST or RPC endpoint surface — pagination, error envelopes, idempotency, versioning, contract-first vs code-first.

Pagination

Cursor implementation:

SELECT * FROM items
WHERE id > :cursor_id
ORDER BY id ASC
LIMIT :limit + 1;  -- fetch N+1 to determine has_next

Response: { data, pagination: { next_cursor, has_next } }. Encode cursor as opaque base64 to prevent client manipulation.

Filtering

Bracket notation for comparison operators:

?price[gte]=10&price[lte]=100
?status[in]=active,pending
?customer.country=US          # dot notation for nested fields

Comma-separated for multi-value equality:

?category=electronics,clothing

Sorting

Prefix - for descending, comma-separated for multi-field:

?sort=-created_at,name        # newest first, then alphabetical

Sparse Fieldsets

?fields=id,name,email         # return only these fields

Deprecation Protocol

1. Add Sunset header with retirement date: Sunset: Sat, 01 Jan 2028 00:00:00 GMT 2. Minimum 6-month notice before removal 3. After sunset: return 410 Gone with migration guidance

Breaking vs non-breaking changes:

Pre-Ship Endpoint Checklist

Before shipping any new endpoint, verify:

• [ ] Resource naming: plural nouns, max 2 nesting levels
• [ ] HTTP method matches semantics (GET reads, POST creates, etc.)
• [ ] Status codes correct (201 + Location on create, 204 on delete, 404 vs 400 distinction)
• [ ] Request validation with schema (rejects invalid input with 400 + detail)
• [ ] Response schema defined (controls serialized fields, no raw objects)
• [ ] Pagination on list endpoints (cursor or offset with has_next)
• [ ] Auth/authz enforced (401 vs 403 distinction)
• [ ] Rate limiting configured
• [ ] Error envelope matches project standard
• [ ] Idempotency for non-safe methods (POST with idempotency key where needed)
• [ ] External API responses validated before use
• [ ] OpenAPI/docs updated

Database & Production

When to read: when picking an ORM, configuring connection pooling, planning a migration, or hardening a Node service for production deploy.

Database

ORM: Drizzle (SQL-like, lightweight) or Prisma (schema-first, migrations built-in)

Connection pooling: new Pool({ max: 20, idleTimeoutMillis: 30000, connectionTimeoutMillis: 2000 })

Transactions: BEGIN → ops → COMMIT / catch → ROLLBACK / finally → client.release()

Index strategies:

CREATE INDEX idx_col ON t(col);                            -- equality
CREATE INDEX idx_multi ON t(col1, col2);                   -- composite
CREATE INDEX idx_partial ON t(col) WHERE status = 'active'; -- filtered
CREATE INDEX idx_cover ON t(col) INCLUDE (name);            -- covering

Always EXPLAIN ANALYZE slow queries. Watch for sequential scans on large tables.

Migrations:

• Separate schema and data migrations -- data backfills in their own migration file
• Renames/removals use expand-contract: add new column → backfill → switch reads → drop old (see ia-postgresql skill for the full pattern)
• Never edit a migration that has already run in a shared environment
• Kysely: always type migrations as Kysely<any>, not your app's typed DB interface -- migrations are frozen in time and the schema will evolve past them
• Drizzle/Prisma: keep migration SQL files under version control, review generated SQL before applying

Production

• Docker: multi-stage build -- node:20-alpine builder + prod image with npm ci --omit=dev
• Process: PM2 cluster mode (instances: 'max') or container orchestration
• Shutdown: SIGTERM → stop accepting connections → drain in-flight → close DB pool
• Logging: Pino (structured JSON), not console.log
• Health: GET /health returning { status: 'ok' }
• Compression: gzip/brotli via middleware

Authentication & Security

For comprehensive security auditing (OWASP compliance, vulnerability scanning, checklist), use the ia-security-sentinel agent. This reference covers Node.js-specific tooling and patterns only.

Authentication Pattern

• Access token: JWT, 15min expiry, payload: { userId, email }
• Refresh token: JWT, 7d expiry, stored in DB (revocable)
• Passwords: bcrypt (10+ rounds) or argon2
• Middleware: extract Bearer token → jwt.verify → attach req.user → next()
• Authorization: after auth, check role or resource ownership per request
• Always return generic "Invalid credentials" -- never reveal if user exists

Node.js Security Tooling

TypeScript Configuration & Patterns

When to read: when setting up tsconfig, picking strictness flags, or choosing between branded types / discriminated unions / utility types for a backend service.

Configuration

tsconfig essentials:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

ESM-first: set "type": "module" in package.json.

Dev: tsx watch src/server.ts | Build: tsc | Node 22+: --experimental-strip-types for scripts

Type-safe env at startup -- Zod schema as source of truth:

import { z } from 'zod';
const EnvSchema = z.object({
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
});
export type Env = z.infer<typeof EnvSchema>;
export const env = EnvSchema.parse(process.env);

Type Patterns

Branded types -- prevent mixing domain primitives:

type Brand<K, T> = K & { __brand: T };
type UserId = Brand<string, 'UserId'>;
type OrderId = Brand<string, 'OrderId'>;
// Compiler prevents passing OrderId where UserId expected

Discriminated unions -- make illegal states unrepresentable:

type Result<T> = { ok: true; data: T } | { ok: false; error: string };

Exhaustive switch -- catch missing cases at compile time:

default: { const _: never = status; throw new Error(`Unhandled: ${_}`); }

Type guards for runtime narrowing:

function isAppError(err: unknown): err is AppError { return err instanceof AppError; }

`satisfies` -- validate constraints, preserve literal types:

const config = { port: 3000, host: 'localhost' } satisfies Record<string, string | number>;

`as const` -- literal unions from arrays:

const ROLES = ['admin', 'user', 'guest'] as const;
type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'

Compiler Performance

• incremental: true -- 50-90% faster rebuilds
• skipLibCheck: true -- skip .d.ts checking
• isolatedModules: true -- enables fast single-file transpilation
• Avoid deeply nested generics and large unions (>100 members)
• Diagnose: npx tsc --extendedDiagnostics

ia-nodejs-backend Specification

Intent

ia-nodejs-backend is a language-class skill (stack-specific patterns and idioms). Node.js backend patterns: layered architecture, TypeScript, validation, error handling, security, deployment. Use when building REST APIs, Express/Fastify/Hono/NestJS servers, or server-side TypeScript.

Scope

In scope:

• Behaviors described in SKILL.md and routed via the should_trigger phrasings in distillery/tests/fixtures/triggers/ia-nodejs-backend.jsonl.
• Updates to runtime behavior, structure, trigger precision, references, and validation.

Out of scope:

• Acting as the runtime instructions themselves (those live in SKILL.md).
• Trigger phrasings already covered by adjacent ia-* skills (validate-plugin flags >70% description overlap as DUPLICATE_TRIGGER).
• <!-- to fill in: domain-specific exclusions when the skill drifts -->

Trigger Context

• Class: language
• Hook regex: plugins/whetstone/hooks/skill-patterns.sh -> SKILL_PATTERNS[ia-nodejs-backend]
• Common requests (from fixture should_trigger):
• "set up an Express server with middleware"
• "build a Fastify API endpoint"
• "write a Node.js backend API service"
• Should not trigger for (from fixture should_not_trigger):
• "write a Laravel controller for orders"
• "create a React component for filters"
• "write a Python script for ETL"

Source And Evidence Model

Authoritative sources:

• SKILL.md -- runtime instructions and reference routing.
• references/*.md -- bundled supplementary content (4 file(s)).
• distillery/tests/fixtures/triggers/ia-nodejs-backend.jsonl -- positive and negative trigger phrasings under regression test.
• plugins/whetstone/hooks/skill-patterns.sh -- regex pattern that fires this skill.
• distillery/.eval-data/ia-nodejs-backend/ -- harvested session examples (when present).

Data that must not be stored in this skill or its references:

• Secrets, credentials, tokens.
• Machine-specific filesystem paths (/home/..., /Users/..., ~/ai/...). The validator (MACHINE_PATH_LEAK) flags these as HIGH.
• Private URLs, customer data, or unredacted personal information.

Coverage matrix

Evaluation

Lightweight (run on every change):

python3 distillery/scripts/distiller.py validate-plugin --component ia-nodejs-backend
python3 distillery/scripts/distiller.py test-triggers --skill ia-nodejs-backend

Deeper (when behavior risk warrants):

python3 distillery/scripts/distiller.py dspy-eval ia-nodejs-backend
python3 distillery/scripts/distiller.py diagnose-negatives ia-nodejs-backend

Acceptance gates:

• validate-plugin --component ia-nodejs-backend returns 0 HIGH findings.
• test-triggers --skill ia-nodejs-backend returns F1 = 1.0 with floors of 5 should_trigger and 5 should_not_trigger.
• For dspy-eval, the composite score does not regress against the most recent saved baseline (see distillery/.eval-data/ia-nodejs-backend/history.json).

Known Limitations

<!-- to fill in over time as drift surfaces. Default rule: any time diagnose-negatives surfaces a recurring failure pattern, document it here so future maintainers understand the trade-off the current implementation accepts. -->

Maintenance Notes

• Update SKILL.md when the runtime workflow, branch conditions, or output contract changes.
• Update this SPEC.md when intent, scope, evidence model, evaluation gates, or maintenance expectations change.
• Update the trigger fixture when adding new positive phrasings, removing stale ones, or expanding scope (the 5/5 floor is a hard validator gate).
• Update the hook regex in skill-patterns.sh whenever fixture positives expose a missed phrasing; verify F1 = 1.0 with eval-triggers before committing.
• Run the full release pipeline via /release -- never bump versions or update CHANGELOG.md from a per-skill edit.