node-typescript-service

Skill: Node.js/TypeScript Service

Purpose

Create or modify Node.js/TypeScript backend services with proper validation, error handling, logging, and testing.

Inputs

• serviceName: Service or module identifier
• endpointSpec: HTTP method, path, request schema, response schema
• businessLogic: Description of what the endpoint does
• framework: Express, Nest, Fastify (detected from project)

Outputs

• Route handler or controller file
• Validation schemas
• Error handling implementation
• Test file with unit and integration tests

Procedures

1. Detect Project Framework

Check package.json dependencies:

• express → Express.js
• @nestjs/core → Nest.js
• fastify → Fastify

If unclear, request clarification.

2. Load Backend Policy

Read: ../../../policies/backend-policy.md

Follow Node.js/TypeScript conventions.

3. Define Request Validation Schema

Create validation schema using the project's validation library.

Common libraries:

• Zod
• Joi
• class-validator (Nest.js)

Example (Zod):

import { z } from 'zod'

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1),
  age: z.number().int().positive().optional()
})

type CreateUserRequest = z.infer<typeof CreateUserSchema>

Refer to: references/validation-and-errors.md

4. Implement Route Handler

Structure varies by framework.

Express.js

import express, { Request, Response } from 'express'

router.post('/users', async (req: Request, res: Response) => {
  try {
    const data = CreateUserSchema.parse(req.body)
    const user = await createUser(data)
    res.status(201).json({ success: true, data: user })
  } catch (error) {
    handleError(error, res)
  }
})

Nest.js

import { Controller, Post, Body } from '@nestjs/common'
import { CreateUserDto } from './dto/create-user.dto'

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  async create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto)
  }
}