@wazir-dev/cli 1.0.0

package/expertise/backend/node-typescript.md

@@ -0,0 +1,625 @@
+# Node.js + TypeScript -- Expertise Module
+
+> A Node.js/TypeScript backend specialist designs, builds, and maintains server-side applications
+> using Node.js (v22+) with TypeScript (5.x+). Scope spans API design, data layer integration,
+> authentication, background jobs, observability, and production deployment of performant, type-safe services.
+
+## Core Patterns & Conventions
+
+### Project Structure
+
+**Monorepo (Turborepo or Nx):**
+```
+apps/
+  api/               # Main HTTP service
+  worker/            # Background job processor
+packages/
+  shared/            # Shared types, utils, validation schemas
+  db/                # Database client, migrations, seed
+turbo.json
+tsconfig.base.json
+```
+
+**Feature-based single service:**
+```
+src/
+  modules/
+    users/
+      users.controller.ts
+      users.service.ts
+      users.repository.ts
+      users.schema.ts      # Zod schemas
+      users.test.ts
+  common/middleware/ errors/ guards/
+  infrastructure/database/ cache/ queue/
+  app.ts
+  server.ts
+```
+
+- Co-locate tests with source files. Keep barrel files minimal. Use `@/modules/*` path aliases.
+
+### Module System
+
+ESM is the default in 2025-2026. Use `"type": "module"` in `package.json`, `"module": "NodeNext"` and `"moduleResolution": "NodeNext"` in `tsconfig.json`. Use `.js` extensions in imports.
+
+### Naming Conventions
+
+- **Files:** kebab-case with role suffix (`user-auth.service.ts`)
+- **Classes:** PascalCase. **Functions/vars:** camelCase. **Constants:** UPPER_SNAKE_CASE
+- **Types/Interfaces:** PascalCase, no `I` prefix. Prefer `as const` objects over enums
+- **Tooling:** ESLint flat config (`eslint.config.js`) with `@typescript-eslint` v8+ and Prettier. Enforce via lint-staged + husky pre-commit hooks
+
+### Architecture
+
+**Clean Architecture / Hexagonal:**
+```
+Controller (HTTP) --> Service (business logic) --> Repository (data access)
+                          |
+                     Domain models (pure TS, no framework deps)
+```
+
+- Controllers: parse request, call service, format response. Services: business logic, depend on repository interfaces. Repositories: encapsulate data access. Domain models: plain TypeScript.
+- **DI:** NestJS built-in; otherwise `tsyringe`, `awilix`, or manual constructor injection.
+
+### Framework Selection
+
+| Framework | Best For | Key Trait |
+|-----------|----------|-----------|
+| **Express** | General purpose, max ecosystem | Middleware-based, massive plugin library |
+| **Fastify** | Performance-sensitive APIs | JSON schema validation, plugin architecture |
+| **NestJS** | Enterprise, large teams (10+) | Opinionated, DI, decorators, modules |
+| **Hono** | Edge/serverless, multi-runtime | Ultra-light (~14kb), Workers/Deno/Bun/Node |
+
+### Data Flow
+
+**Express/Fastify:** Request --> Auth middleware --> Validation --> Route handler --> Error middleware --> Response
+
+**NestJS:** Request --> Guards (auth) --> Interceptors (logging) --> Pipes (validation) --> Controller --> Interceptors (transform) --> Response
+
+### Error Handling
+
+Create custom error class hierarchies with `statusCode` and `isOperational` fields. Central error middleware converts operational `AppError` subclasses to structured JSON; non-operational errors log full stack and return generic 500.
+
+### Logging & Observability
+
+**Pino** -- 5x faster than Winston. Use structured JSON, `pino-pretty` in dev, `redact` for secrets. **OpenTelemetry** for distributed tracing: `@opentelemetry/sdk-node` with auto-instrumentation, correlate logs via `@opentelemetry/instrumentation-pino`. One OTel SDK per service. Use sampling in production (`TraceIdRatioBasedSampler(0.1)`).
+
+---
+
+## Production Patterns
+
+### Express.js Security Middleware Stack
+
+Apply security middleware early in the stack — before any route handlers. Order matters: helmet first (headers on every response), then rate limiting (reject abusers before doing work), then CORS (reject disallowed origins).
+
+```typescript
+import helmet from 'helmet';
+import rateLimit from 'express-rate-limit';
+import cors from 'cors';
+
+// Security headers — sets CSP, HSTS, X-Frame-Options, etc.
+app.use(helmet({
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      imgSrc: ["'self'", 'data:', 'https:'],
+    },
+  },
+  hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
+}));
+
+// Rate limiting — per-IP, sliding window
+app.use(rateLimit({
+  windowMs: 15 * 60 * 1000,  // 15 minutes
+  max: 100,                   // 100 requests per window per IP
+  standardHeaders: true,      // RateLimit-* headers (draft-6)
+  legacyHeaders: false,       // Disable X-RateLimit-* headers
+  message: { error: 'Too many requests, try again later' },
+}));
+
+// CORS — explicit origin whitelist from env
+app.use(cors({
+  origin: process.env.ALLOWED_ORIGINS?.split(',') ?? [],
+  credentials: true,
+  maxAge: 86400,  // Preflight cache 24h
+}));
+```
+
+**Key decisions:**
+- `ALLOWED_ORIGINS` from env — never hardcode origins in source
+- `credentials: true` requires explicit origin list (not `*`)
+- `legacyHeaders: false` — only emit the standardized `RateLimit-*` headers
+- Layer auth-specific rate limits separately (e.g., 10/min on `/auth/login`)
+
+### PostgreSQL Schema Patterns
+
+Index design is the highest-leverage performance optimization. These patterns cover the most common production needs.
+
+```sql
+-- Partial index: only index rows that match a condition
+-- Saves space and speeds up queries that always filter by status
+CREATE INDEX idx_orders_pending ON orders (created_at)
+  WHERE status = 'pending';
+
+-- GIN index for full-text search with weighted ranking
+ALTER TABLE products ADD COLUMN search_vector tsvector
+  GENERATED ALWAYS AS (
+    setweight(to_tsvector('english', coalesce(name, '')), 'A') ||
+    setweight(to_tsvector('english', coalesce(description, '')), 'B')
+  ) STORED;
+CREATE INDEX idx_products_search ON products USING GIN (search_vector);
+
+-- Covering index (INCLUDE avoids table lookup for frequently selected columns)
+CREATE INDEX idx_users_email ON users (email) INCLUDE (name, role, status);
+
+-- Expression index for case-insensitive lookups
+-- Pair with WHERE lower(email) = lower($1) in queries
+CREATE INDEX idx_users_email_lower ON users (lower(email));
+```
+
+**When to use each:**
+- **Partial index:** Queries always filter on a known condition (status, soft-delete flag, tenant)
+- **GIN + tsvector:** Full-text search without ElasticSearch — sufficient for <10M rows
+- **Covering index:** High-read endpoints that SELECT a small subset of columns
+- **Expression index:** Case-insensitive email lookup, JSONB field extraction
+
+### Graceful Shutdown Pattern
+
+Production servers must drain in-flight requests before exiting. Without this, deployments drop active connections and corrupt long-running operations.
+
+```typescript
+import net from 'node:net';
+
+const server = app.listen(port);
+const connections = new Set<net.Socket>();
+
+// Track all open connections
+server.on('connection', (conn) => {
+  connections.add(conn);
+  conn.on('close', () => connections.delete(conn));
+});
+
+async function shutdown(signal: string) {
+  console.log(`${signal} received, starting graceful shutdown`);
+
+  // Stop accepting new connections
+  server.close();
+
+  // Give existing requests time to complete, then force-close
+  setTimeout(() => {
+    connections.forEach((conn) => conn.destroy());
+    process.exit(0);
+  }, 10_000);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+```
+
+**Production checklist:**
+- Close DB connection pools and Redis clients inside `server.close()` callback
+- Set the force-exit timeout shorter than your orchestrator's kill grace period (e.g., 10s app vs 30s Kubernetes `terminationGracePeriodSeconds`)
+- Add a `shuttingDown` flag to reject new work in queue consumers during drain
+- Use `.unref()` on the timeout to prevent it from keeping the process alive if all connections close early
+
+### Request ID Correlation
+
+Attach a unique ID to every request for end-to-end tracing across logs, error reports, and downstream services.
+
+```typescript
+import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const requestContext = new AsyncLocalStorage<{ requestId: string }>();
+
+app.use((req, _res, next) => {
+  const requestId = req.headers['x-request-id'] as string ?? randomUUID();
+  req.headers['x-request-id'] = requestId;
+  requestContext.run({ requestId }, next);
+});
+
+// In any downstream code:
+export function getRequestId(): string | undefined {
+  return requestContext.getStore()?.requestId;
+}
+```
+
+**Why `AsyncLocalStorage`:** Unlike attaching data to `req`, this works in service/repository layers that do not (and should not) have access to the HTTP request object. Pino's `mixin` option can call `getRequestId()` to include it in every log line automatically.
+
+---
+
+## Anti-Patterns & Pitfalls
+
+### 1. Using `any` to Silence the Compiler
+**Why:** Defeats type safety, spreads virally to downstream types, allows runtime errors TypeScript should catch.
+**Fix:** Use `unknown` + type guards. Parse untrusted data with Zod. Enable `noImplicitAny`.
+
+### 2. Blocking the Event Loop
+**Why:** Node.js is single-threaded. A 50ms sync file read blocks ALL concurrent requests.
+**Fix:** Use `fs.promises`, stream large payloads, offload CPU work to worker threads or BullMQ.
+
+### 3. Swallowing Errors in `catch` Blocks
+**Why:** Silent failures make debugging impossible. System enters inconsistent state.
+**Fix:** Always log or re-throw. Use `catch (error: unknown)` and narrow. Add process-level unhandled rejection handlers.
+
+### 4. No Runtime Validation of External Input
+**Why:** TS types vanish at runtime. API bodies, env vars, queue messages are `unknown` regardless of annotations.
+**Fix:** Validate at trust boundaries with Zod `safeParse`. Validate env vars at startup.
+
+### 5. Fat Controllers
+**Why:** Business logic in route handlers is untestable without HTTP, violates SRP, couples logic to transport.
+**Fix:** Controllers parse/format only. Business logic in services, unit-tested in isolation.
+
+### 6. N+1 Query Patterns
+**Why:** 100 users + 1 query each = 101 DB round-trips. Latency scales linearly.
+**Fix:** Eager loading (`include` in Prisma, `with` in Drizzle), DataLoader for GraphQL, explicit JOINs.
+
+### 7. Leaking DB Models Through API Responses
+**Why:** Internal columns, sensitive fields (password hashes) leak. Schema changes break API contracts.
+**Fix:** Map to DTOs/response schemas. Use Zod `.pick()`/`.omit()`. Never `res.json(ormModel)`.
+
+### 8. Type Assertions (`as`) Instead of Type Guards
+**Why:** `as` performs zero runtime checks. Errors surface far from the assertion site.
+**Fix:** Discriminated unions, `instanceof`, user-defined type guards, or Zod `.parse()`.
+
+### 9. No Graceful Shutdown
+**Why:** Drops in-flight requests, leaks DB connections, loses queued jobs, can corrupt data.
+**Fix:** `SIGTERM`/`SIGINT` listeners, stop accepting connections, drain requests, close pools, force-exit timeout.
+
+### 10. Secrets in Git
+**Why:** Secrets in version control persist forever in history. Anyone with repo access gets prod credentials.
+**Fix:** `.env` in `.gitignore` for local dev. Production: AWS Secrets Manager, Vault, Doppler.
+
+### 11. Unstructured Error Responses
+**Why:** Clients cannot distinguish error types programmatically. Frontend resorts to string-matching.
+**Fix:** Structured errors: `{ code: "VALIDATION_ERROR", message: "...", details: [...] }`.
+
+### 12. Over-Wrapping API Responses
+**Why:** `{ success: true, data: ... }` restates HTTP status codes, creates `data.data` nesting.
+**Fix:** Use HTTP status codes semantically. Return resources directly. Error envelope only for errors.
+
+### 13. Lax TypeScript Config
+**Why:** Without `strict: true`, implicit `any` and unchecked `null` undermine type safety.
+**Fix:** Enable `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`.
+
+### 14. Global Mutable State
+**Why:** Race conditions across requests, non-deterministic tests, breaks horizontal scaling.
+**Fix:** `AsyncLocalStorage` for request context, DI, Redis/DB for shared state.
+
+---
+
+## Testing Strategy
+
+| Layer | Tool | Scope | Speed |
+|-------|------|-------|-------|
+| Unit | Vitest | Single function/class, mocked deps | ~1ms/test |
+| Integration | Vitest + Testcontainers | Service + real DB/queue | ~100ms/test |
+| E2E/API | Vitest + Supertest | Full HTTP request cycle | ~500ms/test |
+
+**Vitest over Jest** for new projects (2025-2026): native ESM/TS, 30-70% faster, compatible API, built-in coverage. Reserve Jest for React Native or legacy codebases.
+
+**Mocking:** Constructor injection (swap deps in tests), `vi.mock()` for third-party SDKs, MSW for outbound HTTP. Prefer real dependencies via Testcontainers over heavy mocking.
+
+**Coverage:** 80%+ for services, 90%+ for shared libs. Enforce in CI. Diminishing returns past ~90%.
+
+---
+
+## Performance Considerations
+
+### Event Loop
+Never block it. `JSON.parse()` on 50MB, sync crypto, CPU loops all block. Use `setImmediate()` to yield. Monitor lag with `monitorEventLoopDelay` from `perf_hooks`; alert if p99 > 100ms.
+
+### Memory Leaks
+Common sources: unbounded caches (no TTL/LRU), closures capturing large objects, undestroyed streams, per-request globals. Detect with `--inspect` + Chrome DevTools heap snapshots, `clinic.js heapprofile`, or Prometheus gauge on `process.memoryUsage().heapUsed`.
+
+### Connection Pooling
+DB: always pool (Prisma/Drizzle auto-manage; raw `pg` set `max: 20`). Redis: single `ioredis` client (multiplexes). HTTP: reuse agents with keep-alive (default in Node 22).
+
+### Profiling Tools
+
+| Tool | Purpose |
+|------|---------|
+| `node --inspect` + DevTools | CPU profiling, heap snapshots |
+| `clinic.js doctor/flame` | Auto-detect issues, flamegraphs |
+| `0x` | Lightweight flamegraph |
+| `autocannon` | HTTP load testing |
+
+### Scaling
+**Cluster mode:** PM2 or `cluster` module for multi-core. **Worker threads:** `piscina` pool for CPU-bound tasks. **Job queues:** BullMQ for async processing.
+
+### Thresholds
+
+| Metric | Target | Alert |
+|--------|--------|-------|
+| p50 latency | < 50ms | > 200ms |
+| p99 latency | < 500ms | > 2s |
+| Event loop lag p99 | < 50ms | > 100ms |
+| Heap usage | < 70% max | > 85% |
+| Error rate | < 0.1% | > 1% |
+
+---
+
+## Security Considerations
+
+### OWASP Top Risks for Node.js
+1. **Injection:** Parameterized queries only. Never interpolate user input into SQL or shell commands.
+2. **Broken Auth:** Use Lucia/Auth.js or SaaS (Clerk, Auth0). Hash with `bcrypt`/`argon2`. Enforce MFA.
+3. **Data Exposure:** Redact secrets from logs. Minimal API responses. HTTPS everywhere.
+4. **Broken Access Control:** RBAC/ABAC at service layer. Check ownership on every resource access.
+5. **Misconfiguration:** `helmet` for headers. Disable `X-Powered-By`. Strict CORS.
+6. **XSS:** `dompurify` for HTML. Content-Security-Policy headers.
+7. **SSRF:** Whitelist outbound URLs. Block internal IPs (169.254.x.x, 10.x.x.x).
+8. **Insecure Deps:** `npm audit` in CI. Snyk/Socket.dev for supply chain. Pin versions with lockfiles.
+
+### Input Validation
+Validate ALL external input with **Zod** at boundaries. Use `safeParse` in production. Infer TS types from schemas (`z.infer<typeof Schema>`). Validate env vars at startup (crash early).
+
+### Authentication
+- **JWT:** 15-min access tokens, 7-30 day refresh tokens in httpOnly cookies. Rotate on use. Use `jose` library.
+- **Sessions:** Server-side store (Redis) + cookies -- most battle-tested for web apps.
+- **OAuth2:** Passport.js or Auth.js. Validate ID tokens server-side.
+
+### Rate Limiting
+`express-rate-limit` with layered limits: global 1000/min/IP, auth endpoints 10/min/IP. Redis-backed store for distributed setups.
+
+### Secrets
+Dev: `.env` (`.gitignore`d). Production: AWS Secrets Manager / Vault / Doppler. Never log secrets (Pino `redact`). Type-safe via `@t3-oss/env-core` or Zod.
+
+---
+
+## Integration Patterns
+
+### Database ORMs
+
+| ORM | Approach | Strength | Trade-off |
+|-----|----------|----------|-----------|
+| **Prisma v6+** | Schema-first, codegen | Best migrations, DX, editor support | Generated client size |
+| **Drizzle v0.38+** | Code-first, TS schemas | ~7kb, zero deps, SQL-like API | Manual migration review |
+| **TypeORM** | Decorators, Active Record | NestJS integration | Losing ground to above |
+
+### Message Queues
+- **BullMQ** (Redis): First choice for Node.js. TS-native. Delayed/repeatable/priority jobs, parent-child flows, rate limiting.
+- **RabbitMQ** (AMQP): Cross-language, complex routing, guaranteed delivery. Use for polyglot systems.
+
+### API Design
+- **REST:** Public APIs, multi-language clients. Resource-oriented URLs. Consistent pagination envelope.
+- **GraphQL (Pothos/Apollo):** Flexible querying for multiple clients. DataLoader for N+1. Enable complexity/depth limits.
+- **tRPC v11+:** End-to-end type safety in TS monorepos. NOT for public APIs or polyglot clients.
+
+### File Handling
+Use streams for large files. `pipeline()` from `stream/promises` for safe chaining. Stream to S3 via `@aws-sdk/lib-storage`. Set `Content-Length` limits.
+
+---
+
+## DevOps & Deployment
+
+### Build Tools
+
+| Tool | Speed vs tsc | Notes |
+|------|-------------|-------|
+| `tsc` | 1x (baseline) | Only tool that type-checks. Use `tsc --noEmit` in CI. |
+| `tsup` | ~40x | Built on esbuild. Best for libraries (CJS + ESM + .d.ts). |
+| `esbuild` | ~45x | Go-based. No type checking. Great for app builds. |
+| `SWC` | ~20x | Rust-based. Used by Next.js. |
+
+**Pipeline:** `tsc --noEmit` for type checking, then `tsup src/server.ts --format esm --target node22 --minify` for production bundle.
+
+### Docker (Multi-Stage)
+
+```dockerfile
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+
+FROM deps AS build
+COPY . .
+RUN pnpm run build
+
+FROM node:22-alpine AS production
+WORKDIR /app
+RUN addgroup -g 1001 app && adduser -u 1001 -G app -s /bin/sh -D app
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+COPY package.json ./
+USER app
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
+CMD ["node", "dist/server.js"]
+```
+
+Alpine base (60-80% smaller), non-root user, HEALTHCHECK, `.dockerignore`, pinned versions.
+
+### CI/CD (GitHub Actions)
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    services:
+      postgres: { image: 'postgres:16-alpine', env: { POSTGRES_PASSWORD: test }, ports: ['5432:5432'] }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint && pnpm typecheck && pnpm test && pnpm build
+```
+
+### Environment Config
+Validate env vars at startup with Zod. Crash immediately on misconfiguration -- not at 3am when a code path reads it.
+
+### Process Management
+Dev: `tsx watch src/server.ts`. Production (containers): `node dist/server.js` directly (container runtime handles restarts). Bare metal: PM2 cluster mode. Always implement graceful shutdown.
+
+---
+
+## Decision Trees
+
+### Which Framework?
+```
+Team > 10 or enterprise compliance? --> NestJS
+  |NO
+Edge/serverless (Workers, Deno Deploy)? --> Hono
+  |NO
+Need max ecosystem & middleware? --> Express
+  |NO
+Default modern choice --> Fastify
+```
+
+### Which ORM?
+```
+Serverless/edge, cold start matters? --> Drizzle
+  |NO
+Team prefers SQL, wants query control? --> Drizzle
+  |NO
+Want best migration tooling & DX? --> Prisma
+  |NO
+Existing NestJS with decorators? --> TypeORM (or migrate)
+  |NO
+Safe default --> Prisma
+```
+
+### Monolith vs. Microservices?
+```
+Team < 8 AND no proven PMF? --> Monolith
+  |NO
+Components have vastly different scaling needs? --> Extract ONLY divergent component
+  |NO
+50+ engineers OR >1M req/day with clear boundaries?
+  YES --> Microservices (REQUIRES: K8s, tracing, centralized logging, per-service CI/CD)
+  NO  --> Modular monolith (extract later when pain emerges)
+```
+
+---
+
+## Code Examples
+
+### 1. Graceful Shutdown
+
+```typescript
+import { Server } from 'node:http';
+
+function setupGracefulShutdown(server: Server, cleanup: () => Promise<void>): void {
+  let shuttingDown = false;
+  const shutdown = async (signal: string) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    logger.info({ signal }, 'Draining connections...');
+    server.close(async () => {
+      await cleanup(); // close DB pools, Redis, queues
+      process.exit(0);
+    });
+    setTimeout(() => process.exit(1), 15_000).unref(); // force exit
+  };
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+```
+
+### 2. Zod Validation Middleware (Express)
+
+```typescript
+import { z, ZodSchema } from 'zod';
+import { Request, Response, NextFunction } from 'express';
+
+function validate<T extends ZodSchema>(schema: T) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const result = schema.safeParse(req.body);
+    if (!result.success) {
+      return res.status(400).json({
+        code: 'VALIDATION_ERROR',
+        errors: result.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message })),
+      });
+    }
+    req.body = result.data;
+    next();
+  };
+}
+
+// Usage:
+app.post('/orders', validate(z.object({
+  productId: z.string().uuid(),
+  quantity: z.number().int().positive().max(100),
+})), orderController.create);
+```
+
+### 3. Repository Pattern (Drizzle)
+
+```typescript
+import { eq } from 'drizzle-orm';
+import { db } from '../infrastructure/database';
+import { users } from '../infrastructure/schema';
+
+export interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  create(data: NewUser): Promise<User>;
+}
+
+export function createUserRepository(): UserRepository {
+  return {
+    async findById(id) {
+      const [user] = await db.select().from(users).where(eq(users.id, id)).limit(1);
+      return user ?? null;
+    },
+    async create(data) {
+      const [user] = await db.insert(users).values(data).returning();
+      return user;
+    },
+  };
+}
+```
+
+### 4. Type-Safe Env Config
+
+```typescript
+import { z } from 'zod';
+import 'dotenv/config';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  PORT: z.coerce.number().min(1).max(65535).default(3000),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  CORS_ORIGINS: z.string().transform((s) => s.split(',')),
+});
+
+const parsed = envSchema.safeParse(process.env);
+if (!parsed.success) {
+  console.error('Invalid env vars:', parsed.error.flatten().fieldErrors);
+  process.exit(1);
+}
+export const env = Object.freeze(parsed.data);
+```
+
+### 5. Structured Error Middleware
+
+```typescript
+class AppError extends Error {
+  constructor(public code: string, public statusCode: number, message: string, public details?: unknown) {
+    super(message);
+  }
+}
+
+function errorHandler(err: unknown, _req: Request, res: Response, _next: NextFunction): void {
+  if (err instanceof AppError) {
+    res.status(err.statusCode).json({ code: err.code, message: err.message, ...(err.details && { details: err.details }) });
+    return;
+  }
+  if (err instanceof ZodError) {
+    res.status(400).json({ code: 'VALIDATION_ERROR', message: 'Invalid data', details: err.issues });
+    return;
+  }
+  logger.error({ err }, 'Unhandled error');
+  res.status(500).json({ code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' });
+}
+```
+
+---
+
+*Researched: 2026-03-07 | Sources: [Encore -- Best TS Backend Frameworks 2026](https://encore.dev/articles/best-typescript-backend-frameworks), [DEV -- Modern Node.js + TS Setup 2025](https://dev.to/woovi/a-modern-nodejs-typescript-setup-for-2025-nlk), [OWASP Node.js Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html), [OneUptime -- Node.js API Security OWASP](https://oneuptime.com/blog/post/2026-01-06-nodejs-api-security-owasp-top-10/view), [Better Stack -- Drizzle vs Prisma](https://betterstack.com/community/guides/scaling-nodejs/drizzle-vs-prisma/), [Bytebase -- Drizzle vs Prisma 2026](https://www.bytebase.com/blog/drizzle-vs-prisma/), [DevTools Watch -- Vitest vs Jest 2026](https://devtoolswatch.com/en/vitest-vs-jest-2026), [SD Times -- tRPC vs GraphQL vs REST](https://sdtimes.com/graphql/trpc-vs-graphql-vs-rest-choosing-the-right-api-design-for-modern-web-applications/), [DEV -- REST vs GraphQL vs tRPC 2026](https://dev.to/pockit_tools/rest-vs-graphql-vs-trpc-vs-grpc-in-2026-the-definitive-guide-to-choosing-your-api-layer-1j8m), [DZone -- OpenTelemetry + Pino](https://dzone.com/articles/observability-nodejs-opentelemetry-pino), [SigNoz -- Pino Logger 2026](https://signoz.io/guides/pino-logger/), [Medium -- ESBuild SWC TSC 2026](https://medium.com/@mernstackdevbykevin/esbuild-swc-and-tsc-which-compiler-should-you-use-in-2026-a2df3c783ad2), [BullMQ Docs](https://docs.bullmq.io/), [AgileSoft -- Monolith vs Microservices 2026](https://www.agilesoftlabs.com/blog/2026/02/monolith-vs-microservices-decision), [Better Stack -- Node.js Memory Leaks](https://betterstack.com/community/guides/scaling-nodejs/high-performance-nodejs/nodejs-memory-leaks/), [Dash0 -- Production Logging with Pino](https://www.dash0.com/guides/logging-in-node-js-with-pino), [Docker Docs -- Containerize Node.js](https://docs.docker.com/guides/nodejs/containerize/)*