patterns

Implementation Patterns

Reference for common implementation patterns. Use these patterns to write consistent, maintainable code.

Iron Law

FOLLOW EXISTING PATTERNS

Match the codebase style, don't invent new conventions. If the project uses Result types, use Result types. If it uses exceptions, use exceptions. Consistency trumps personal preference. The best pattern is the one already in use.

When This Skill Activates

• Implementing CRUD operations
• Creating API endpoints
• Writing event handlers
• Setting up configuration
• Adding logging
• Database operations

---

Pattern Categories

CRUD Operations

Create, Read, Update, Delete with Result types and proper error handling.

Core pattern: Validate -> Transform -> Persist -> Return

async function createUser(input: CreateUserInput): Promise<Result<User, CreateError>> {
  const validated = validateCreateUser(input);
  if (!validated.ok) return Err({ type: 'validation', details: validated.error });

  const user: User = { id: generateId(), ...validated.value, createdAt: new Date() };
  const saved = await userRepository.save(user);
  if (!saved.ok) return Err({ type: 'persistence', details: saved.error });

  return Ok(saved.value);
}

API Endpoints

REST endpoint structure with auth, validation, and error mapping.

Core pattern: Parse request -> Validate auth -> Execute -> Format response

export async function handleGetUser(req: Request): Promise<Response> {
  const id = parsePathParam(req, 'id');
  if (!id.ok) return errorResponse(400, 'Invalid user ID');

  const auth = await authenticate(req);
  if (!auth.ok) return errorResponse(401, 'Unauthorized');

  const result = await getUser(id.value);
  if (!result.ok) return handleError(result.error);

  return jsonResponse(200, result.value);
}

Event Handlers

Async event processing with idempotency and error recovery.

Core pattern: Validate event -> Process -> Handle errors -> Acknowledge