node-typescript-service

TypeScript Service on Node.js

Overview

A Node.js service is TypeScript at compile time and untyped JavaScript at run time. Every type at the edge — a request body, a header, an environment variable, a queue message, a row from a raw query — is a claim until something checks it.

Core principle: the repository's framework, package manager, module system and ORM win. Parse input at the boundary into typed values; keep the domain free of the framework.

Choosing, only when there is nothing to follow

• Fastify for a new HTTP service: schema-first routes, app.inject() for tests, pino logging built in.
• NestJS when the service is domain-rich and the team wants modules, DI and decorators (the Quarkus/Spring of Node).
• Express 5 or Hono only to match a repository or a platform that already uses them.

Layers

Patterns

• Package manager from the lockfile: pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm; install with the frozen form (pnpm install --frozen-lockfile, npm ci). Node version from .nvmrc, .node-version or engines; a new service targets the current Active LTS.
• Module system from package.json: "type": "module" means ESM (relative imports carry .js under NodeNext); otherwise CommonJS. Never mix them in one package.
• strict: true. No any; unknown at the boundary, narrowed by a parser. No non-null ! to silence a real undefined.
• Validate at runtime at the boundary: zod (or TypeBox / Fastify JSON schema, class-validator in NestJS — whatever the repository uses) on body, params, query and headers; derive the TypeScript type from the schema (z.infer) so the two cannot drift. Environment variables are parsed once at startup by the same means and the process exits on a bad one.
• Errors in one shape: a central error handler (setErrorHandler, a Nest exception filter, Express 5's error middleware) maps domain errors to 400/404/409 problem+json; an unknown error is logged with its stack and answered 500 without it.
• No floating promises: every promise is awaited, returned or explicitly handled (@typescript-eslint/no-floating-promises catches the rest). An unhandled rejection crashes the process in current Node.
• Outbound calls have a deadline: fetch(url, { signal: AbortSignal.timeout(5_000) }) or the client's own timeout; retries only for idempotent calls (resilient-io-and-jobs).
• Never block the event loop: no *Sync file or crypto calls on a request path, no unbounded JSON.parse of a large body, CPU-heavy work in a worker thread or a job.
• Database: the repository's tool — Prisma, Drizzle, Kysely, TypeORM, MikroORM or pg — with parameters, never string-built SQL ($queryRawUnsafe and sql.raw with input are bugs). Migrations through that tool (prisma migrate dev --name, drizzle-kit generate), committed with the schema change; postgres-migrations covers safe DDL.
• Logging: pino (Fastify's logger, nestjs-pino) with structured fields, request id bound per request; no console.log in service code; redact secrets and tokens (redact option).
• Graceful shutdown: on SIGTERM stop accepting connections, finish in-flight requests, close the pool, then exit — Fastify close(), Nest enableShutdownHooks().
• Dependencies: a new package is a decision (reuse-before-you-write) — exact name from the registry, added with the repository's package manager, lockfile in the same commit.