patterns

name	patterns
description	This skill should be used when the user asks to "create an API endpoint", "add CRUD operations", "implement event handlers", "set up logging", "add configuration", or builds features involving database operations, REST/GraphQL APIs, pub/sub patterns, or service configuration. Provides implementation patterns that follow existing codebase conventions.
user-invocable	false
allowed-tools	Read, Grep, Glob

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

async function handleUserCreated(event: UserCreatedEvent): Promise<void> {
  const validated = validateEvent(event);
  if (!validated.ok) { logger.warn('Invalid event'); return; }

  await sendWelcomeEmail(event.userId);
  await createDefaultSettings(event.userId);
  logger.info('Event processed successfully');
}

Configuration

Environment config with schema validation and feature flags.

Core pattern: Define schema -> Load from env -> Validate -> Export frozen

const ConfigSchema = z.object({
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
});

export const config = Object.freeze(ConfigSchema.parse(process.env));

Logging

Structured logging with context propagation and operation tracking.

Core pattern: Context -> Level -> Message -> Data

const logger = createLogger({ requestId: req.id, userId: user.id });
logger.info('Processing order', { orderId: order.id, items: order.items.length });

---

Anti-Patterns to Avoid

Anti-Pattern	Problem	Fix
God functions	500-line functions doing everything	Compose small, focused functions
Implicit dependencies	Using global state (db.query(...))	Inject dependencies explicitly
Swallowing errors	Empty catch blocks	Handle or propagate with Result types
Magic values	Unexplained numbers/strings	Extract to named constants

---

Build Optimization

Production builds must exclude test files, debug artifacts, and sourcemaps.

// tsconfig.prod.json
{
  "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/tests/**"]
}

---

Implementation Checklist

Before implementing, verify:

• Using Result types for operations that can fail
• Validating input at system boundaries
• Logging with context (requestId, userId, operation)
• Handling all error cases explicitly
• Making operations idempotent where possible
• Using transactions for multi-step operations
• No hardcoded values (use config)
• Following existing codebase patterns

---

Extended References

For full implementation examples:

• references/violations.md - Extended violation examples (CRUD, API, Events, Config, Logging)
• references/patterns.md - Extended correct patterns (CRUD, API, Events, Config, Logging)