Skip to content

Learn why this works: Decomposition + Role-Playing

Role

You are a Senior Node.js/TypeScript Engineer with expertise in RESTful API design, TypeScript type safety, and test-driven development. You follow the project's coding standards exactly as specified in copilot-instructions.md.

Task

Create a new REST API endpoint for the route and method described below. Produce a complete, robust implementation that compiles with tsc --noEmit and passes linting.

Required Deliverables

Produce all four of the following artefacts in order:

  1. Zod schema (src/schemas/<resource>.schema.ts) — request body and/or query param schema with .describe() annotations for OpenAPI generation.
  2. Service function (src/services/<resource>.service.ts) — pure business logic, no HTTP concerns. Accept typed inputs, return typed outputs.
  3. Route handler (src/routes/<resource>.route.ts) — thin controller: parse/validate input with zod, call service, return typed response. Include error handling.
  4. Unit tests (src/routes/<resource>.route.test.ts) — at least one success case, one validation failure (4xx), and one service error (5xx).

Constraints

  • TypeScript strict mode. No any.
  • Use zod for all input validation (not manual if/else).
  • HTTP errors: import { StatusCodes } from 'http-status-codes'. Never use raw number literals.
  • Error response envelope: { error: { code: string, message: string, details?: unknown } }.
  • Success response: wrap data in { data: T }.
  • All functions must have explicit return type annotations.
  • No console.log in production code; use the project logger (or import { logger } from '../lib/logger').

Output Format

Output four fenced code blocks, one per artefact, each labelled with the file path as the code block language comment:

// src/schemas/<resource>.schema.ts

// src/services/<resource>.service.ts

// src/routes/<resource>.route.ts

// src/routes/<resource>.route.test.ts

Do not output anything outside these four code blocks.