Handler tipizzati, validazione al confine, log strutturati, mai bloccare l’event loop.
Constitution — Node.js + Express API
Version 1.0.0 · Ratified 2026-11-10
These principles hold for every spec, plan and task of the project. A spec may add rules; it never weakens these.
-
Typed handlers. Every route handler declares the types of its params, body, query and response through
Request<Params, ResBody, ReqBody, Query>or a typed router helper.anyin a handler fails the review andstrictis on. -
Validation at the edge. Every body, query and params object is parsed with a schema (zod or similar) in a middleware before the handler runs. Handlers receive parsed values only; a request that fails the schema gets a 400 with the failing fields.
-
Structured logs. Logs are JSON written by pino (or an equivalent) with a request id from
pino-http, the route and the status.console.login application code fails the lint. -
Never block the event loop. No synchronous file, crypto or zlib calls (
readFileSync,pbkdf2Sync) in request paths, and no CPU work over 10 ms in a handler; heavy work goes to a worker thread or a queue. Event loop delay is measured and alerts above 100 ms at p99. -
One error middleware. Async errors reach a single error-handling middleware (Express 5 forwards rejected promises; on Express 4 every async handler is wrapped). It maps typed errors to status codes and never sends a stack trace to the client.
-
Secure defaults.
helmet, a body size limit onexpress.json(), CORS with an explicit origin list andapp.disable("x-powered-by")are set in the app factory. A route that needs a looser rule says why in the plan. -
Testable app factory. The app is built by a function that takes its dependencies and does not listen, so supertest runs every route in tests without a port. Each route has tests for its success and its validation failure.