memory-journal-mcp 7.0.1 → 7.2.0

package/skills/typescript/references/enterprise-patterns.md

@@ -0,0 +1,531 @@
+# Enterprise Patterns Reference
+
+> **Load when:** User asks about error handling, validation, project architecture, migration strategies, or large-scale TypeScript patterns.
+
+Proven patterns for building maintainable TypeScript applications.
+
+## Contents
+
+- [Error Handling](#error-handling)
+- [Validation Patterns](#validation-patterns)
+- [Project Organization](#project-organization)
+- [Migration Strategies](#migration-strategies)
+- [Security Patterns](#security-patterns)
+
+---
+
+## Error Handling
+
+### Result Type Pattern
+
+Instead of throwing exceptions, return typed results:
+
+```typescript
+// Define Result type
+type Result<T, E = Error> = { success: true; data: T } | { success: false; error: E }
+
+// Helper functions
+function ok<T>(data: T): Result<T, never> {
+  return { success: true, data }
+}
+
+function err<E>(error: E): Result<never, E> {
+  return { success: false, error }
+}
+
+// Usage
+interface ValidationError {
+  field: string
+  message: string
+}
+
+function parseEmail(input: string): Result<string, ValidationError> {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+  if (!emailRegex.test(input)) {
+    return err({ field: 'email', message: 'Invalid email format' })
+  }
+
+  return ok(input.toLowerCase())
+}
+
+// Consuming Result
+const result = parseEmail(userInput)
+
+if (result.success) {
+  console.log(`Valid email: ${result.data}`)
+} else {
+  console.error(`Error in ${result.error.field}: ${result.error.message}`)
+}
+```
+
+### Typed Error Classes
+
+```typescript
+// Base application error
+abstract class AppError extends Error {
+  abstract readonly code: string
+  abstract readonly statusCode: number
+
+  constructor(message: string) {
+    super(message)
+    this.name = this.constructor.name
+    Error.captureStackTrace(this, this.constructor)
+  }
+}
+
+// Specific error types
+class NotFoundError extends AppError {
+  readonly code = 'NOT_FOUND'
+  readonly statusCode = 404
+
+  constructor(resource: string, id: string) {
+    super(`${resource} with id ${id} not found`)
+  }
+}
+
+class ValidationError extends AppError {
+  readonly code = 'VALIDATION_ERROR'
+  readonly statusCode = 400
+
+  constructor(
+    message: string,
+    public readonly fields: Record<string, string[]>
+  ) {
+    super(message)
+  }
+}
+
+class UnauthorizedError extends AppError {
+  readonly code = 'UNAUTHORIZED'
+  readonly statusCode = 401
+
+  constructor(message = 'Authentication required') {
+    super(message)
+  }
+}
+
+// Type guard for app errors
+function isAppError(error: unknown): error is AppError {
+  return error instanceof AppError
+}
+
+// Error handler
+function handleError(error: unknown): { status: number; body: object } {
+  if (isAppError(error)) {
+    return {
+      status: error.statusCode,
+      body: {
+        code: error.code,
+        message: error.message,
+        ...(error instanceof ValidationError && { fields: error.fields }),
+      },
+    }
+  }
+
+  console.error('Unexpected error:', error)
+  return {
+    status: 500,
+    body: { code: 'INTERNAL_ERROR', message: 'Internal server error' },
+  }
+}
+```
+
+---
+
+## Validation Patterns
+
+### Zod Schema Validation
+
+```typescript
+import { z } from 'zod'
+
+// Define schemas
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150).optional(),
+  role: z.enum(['user', 'admin', 'moderator']),
+  metadata: z.record(z.string()).optional(),
+})
+
+// Infer TypeScript type
+type User = z.infer<typeof UserSchema>
+
+// Create DTO schemas
+const CreateUserSchema = UserSchema.omit({ id: true })
+type CreateUserDto = z.infer<typeof CreateUserSchema>
+
+const UpdateUserSchema = UserSchema.partial().omit({ id: true })
+type UpdateUserDto = z.infer<typeof UpdateUserSchema>
+
+// Validation functions
+function validateCreateUser(data: unknown): Result<CreateUserDto, z.ZodError> {
+  const result = CreateUserSchema.safeParse(data)
+
+  if (result.success) {
+    return ok(result.data)
+  }
+
+  return err(result.error)
+}
+
+// Transform Zod errors to user-friendly format
+function formatZodError(error: z.ZodError): Record<string, string[]> {
+  const formatted: Record<string, string[]> = {}
+
+  for (const issue of error.issues) {
+    const path = issue.path.join('.')
+    if (!formatted[path]) {
+      formatted[path] = []
+    }
+    formatted[path].push(issue.message)
+  }
+
+  return formatted
+}
+```
+
+### Branded Types for Validation
+
+```typescript
+// Branded/Nominal types
+declare const EmailBrand: unique symbol
+type Email = string & { readonly [EmailBrand]: true }
+
+declare const UserIdBrand: unique symbol
+type UserId = string & { readonly [UserIdBrand]: true }
+
+// Validation functions that return branded types
+function validateEmail(input: string): Email {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+  if (!emailRegex.test(input)) {
+    throw new ValidationError('Invalid email', { email: ['Invalid format'] })
+  }
+  return input as Email
+}
+
+function validateUserId(input: string): UserId {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+  if (!uuidRegex.test(input)) {
+    throw new ValidationError('Invalid user ID', { id: ['Must be UUID'] })
+  }
+  return input as UserId
+}
+
+// Usage: Functions require validated types
+function sendEmail(to: Email, subject: string): void {
+  // to is guaranteed to be valid email
+}
+
+function getUser(id: UserId): Promise<User> {
+  // id is guaranteed to be valid UUID
+}
+
+// Compiler enforces validation
+sendEmail('invalid', 'Hello') // Error: string not assignable to Email
+sendEmail(validateEmail('a@b.com'), 'Hello') // OK
+```
+
+---
+
+## Project Organization
+
+### Feature-Based Structure
+
+```
+src/
+├── features/
+│   ├── users/
+│   │   ├── index.ts           # Public exports (barrel)
+│   │   ├── user.types.ts      # Types and interfaces
+│   │   ├── user.schema.ts     # Zod schemas
+│   │   ├── user.service.ts    # Business logic
+│   │   ├── user.repository.ts # Data access
+│   │   ├── user.controller.ts # HTTP handlers
+│   │   └── __tests__/
+│   │       ├── user.service.test.ts
+│   │       └── user.controller.test.ts
+│   ├── auth/
+│   │   ├── index.ts
+│   │   ├── auth.types.ts
+│   │   └── ...
+│   └── posts/
+│       └── ...
+├── shared/
+│   ├── types/
+│   │   ├── result.ts
+│   │   └── pagination.ts
+│   ├── utils/
+│   │   ├── validation.ts
+│   │   └── date.ts
+│   └── errors/
+│       └── app-error.ts
+├── infrastructure/
+│   ├── database/
+│   │   └── client.ts
+│   ├── cache/
+│   │   └── redis.ts
+│   └── logging/
+│       └── logger.ts
+└── config/
+    ├── index.ts
+    └── env.ts
+```
+
+### Barrel Exports
+
+```typescript
+// features/users/index.ts
+export type { User, CreateUserDto, UpdateUserDto } from './user.types'
+export { UserSchema, CreateUserSchema } from './user.schema'
+export { UserService } from './user.service'
+export { UserController } from './user.controller'
+
+// Don't export repository (internal detail)
+// Don't export internal helper functions
+
+// Usage in other modules
+import { User, UserService } from '@/features/users'
+```
+
+### Path Aliases
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@features/*": ["src/features/*"],
+      "@shared/*": ["src/shared/*"],
+      "@config/*": ["src/config/*"]
+    }
+  }
+}
+```
+
+---
+
+## Migration Strategies
+
+### Incremental Migration from JavaScript
+
+**Phase 1: Enable TypeScript alongside JavaScript**
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "outDir": "./dist",
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": false,
+    "noImplicitAny": false
+  },
+  "include": ["src/**/*"]
+}
+```
+
+**Phase 2: Rename files gradually**
+
+```bash
+# Convert one file at a time
+mv src/utils/helpers.js src/utils/helpers.ts
+
+# Add minimal type annotations
+# Fix any type errors
+# Run tests to verify
+```
+
+**Phase 3: Enable stricter checks incrementally**
+
+```json
+// Progression of strict options
+{
+  "compilerOptions": {
+    // Step 1: Basic strictness
+    "noImplicitAny": true,
+
+    // Step 2: Null safety
+    "strictNullChecks": true,
+
+    // Step 3: Full strict mode
+    "strict": true,
+
+    // Step 4: Extra safety (optional)
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+### JSDoc for Gradual Typing
+
+```javascript
+// Before full migration, use JSDoc
+/**
+ * @typedef {Object} User
+ * @property {string} id
+ * @property {string} name
+ * @property {string} email
+ */
+
+/**
+ * Find user by ID
+ * @param {string} id - User ID
+ * @returns {Promise<User | null>}
+ */
+async function findUser(id) {
+  // implementation
+}
+
+/**
+ * @template T
+ * @param {T[]} items
+ * @returns {T | undefined}
+ */
+function first(items) {
+  return items[0]
+}
+```
+
+### CommonJS to ESM Migration
+
+```json
+// package.json
+{
+  "type": "module"
+}
+```
+
+```typescript
+// Before (CommonJS)
+const express = require('express')
+const { UserService } = require('./user.service')
+module.exports = { router }
+
+// After (ESM)
+import express from 'express'
+import { UserService } from './user.service.js' // Note .js extension
+export { router }
+```
+
+---
+
+## Security Patterns
+
+### Input Sanitization
+
+```typescript
+import { z } from 'zod'
+import DOMPurify from 'isomorphic-dompurify'
+
+// Sanitized string schema
+const SanitizedString = z.string().transform((val) => {
+  return DOMPurify.sanitize(val.trim())
+})
+
+// HTML content schema (for rich text)
+const HtmlContentSchema = z.string().transform((val) => {
+  return DOMPurify.sanitize(val, {
+    ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p', 'br'],
+    ALLOWED_ATTR: ['href', 'target'],
+  })
+})
+
+// SQL-safe identifier
+const SafeIdentifierSchema = z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'Invalid identifier')
+```
+
+### Type-Safe Environment Variables
+
+```typescript
+import { z } from 'zod'
+
+const EnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  REDIS_URL: z.string().url().optional(),
+})
+
+// Validate on startup
+function loadEnv() {
+  const result = EnvSchema.safeParse(process.env)
+
+  if (!result.success) {
+    console.error('Invalid environment variables:')
+    console.error(result.error.format())
+    process.exit(1)
+  }
+
+  return result.data
+}
+
+export const env = loadEnv()
+
+// Usage: fully typed
+env.PORT // number
+env.NODE_ENV // "development" | "production" | "test"
+env.REDIS_URL // string | undefined
+```
+
+### Secure API Response Types
+
+```typescript
+// Never expose internal fields
+interface InternalUser {
+  id: string
+  name: string
+  email: string
+  passwordHash: string
+  internalNotes: string
+}
+
+// Public API response (Pick only safe fields)
+type PublicUser = Pick<InternalUser, 'id' | 'name' | 'email'>
+
+// Or explicitly define
+interface UserResponse {
+  id: string
+  name: string
+  email: string
+}
+
+// Transform function
+function toPublicUser(user: InternalUser): UserResponse {
+  return {
+    id: user.id,
+    name: user.name,
+    email: user.email,
+  }
+}
+```
+
+### Rate Limiting Types
+
+```typescript
+interface RateLimitConfig {
+  windowMs: number
+  maxRequests: number
+}
+
+interface RateLimitResult {
+  allowed: boolean
+  remaining: number
+  resetAt: Date
+}
+
+const rateLimits: Record<string, RateLimitConfig> = {
+  api: { windowMs: 60000, maxRequests: 100 },
+  auth: { windowMs: 300000, maxRequests: 5 },
+  upload: { windowMs: 3600000, maxRequests: 10 },
+} as const satisfies Record<string, RateLimitConfig>
+```