metacoding 1.0.0 → 1.1.0

package/templates/typescript/typescript.docs.instructions.md

@@ -0,0 +1,734 @@
+---
+description: 'TypeScript/Node.js-specific documentation standards and JSDoc patterns'
+applyTo: '**/*.{ts,js}'
+language: 'typescript'
+---
+
+# TypeScript/Node.js Documentation Standards
+
+## JSDoc Documentation Standards
+
+### Function Documentation
+
+````typescript
+/**
+ * Retrieves user information by ID with caching support.
+ *
+ * This function first checks the cache for existing user data before
+ * making a database query. If the user is not found in cache, it queries
+ * the database and stores the result in cache for future requests.
+ *
+ * @param userId - The unique identifier for the user
+ * @param options - Configuration options for the retrieval
+ * @param options.useCache - Whether to use cached data if available (default: true)
+ * @param options.cacheTimeout - Cache timeout in milliseconds (default: 300000)
+ * @returns Promise that resolves to user data or null if not found
+ *
+ * @throws {ValidationError} When userId format is invalid
+ * @throws {DatabaseConnectionError} When database connection fails
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const user = await getUserById('123');
+ *
+ * // With options
+ * const user = await getUserById('123', {
+ *   useCache: false,
+ *   cacheTimeout: 600000
+ * });
+ *
+ * // Error handling
+ * try {
+ *   const user = await getUserById('invalid-id');
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.log('Invalid user ID format');
+ *   }
+ * }
+ * ```
+ *
+ * @since 1.2.0
+ * @see {@link User} for user data structure
+ * @see {@link UserRepository.findById} for underlying database query
+ */
+async function getUserById(
+  userId: string,
+  options: GetUserOptions = {}
+): Promise<User | null> {
+  // Implementation here
+}
+````
+
+### Class Documentation
+
+````typescript
+/**
+ * Service for managing user data with caching and validation.
+ *
+ * The UserService provides a high-level interface for user operations,
+ * including automatic caching, input validation, and error handling.
+ * All operations are logged for debugging and monitoring purposes.
+ *
+ * @example
+ * ```typescript
+ * const userService = new UserService({
+ *   repository: new UserRepository(database),
+ *   cache: new RedisCache(),
+ *   logger: new Logger('UserService')
+ * });
+ *
+ * // Create a new user
+ * const user = await userService.createUser({
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * });
+ *
+ * // Retrieve user with caching
+ * const foundUser = await userService.getUserById(user.id);
+ * ```
+ *
+ * @public
+ * @since 1.0.0
+ */
+export class UserService {
+  /**
+   * User repository for database operations.
+   * @private
+   */
+  private readonly repository: UserRepository;
+
+  /**
+   * Cache instance for storing frequently accessed user data.
+   * @private
+   */
+  private readonly cache: CacheService;
+
+  /**
+   * Logger instance for service operations.
+   * @private
+   */
+  private readonly logger: Logger;
+
+  /**
+   * Creates a new UserService instance.
+   *
+   * @param dependencies - Service dependencies
+   * @param dependencies.repository - Repository for user data persistence
+   * @param dependencies.cache - Cache service for performance optimization
+   * @param dependencies.logger - Logger for operation tracking
+   *
+   * @throws {Error} When required dependencies are not provided
+   */
+  constructor(dependencies: UserServiceDependencies) {
+    if (!dependencies.repository) {
+      throw new Error('UserRepository is required');
+    }
+
+    this.repository = dependencies.repository;
+    this.cache = dependencies.cache;
+    this.logger = dependencies.logger || new NullLogger();
+  }
+
+  /**
+   * Creates a new user with validation and duplicate checking.
+   *
+   * @param userData - Data for the new user
+   * @returns Promise resolving to the created user with generated ID
+   *
+   * @throws {ValidationError} When user data is invalid
+   * @throws {DuplicateEmailError} When email already exists
+   *
+   * @example
+   * ```typescript
+   * const newUser = await userService.createUser({
+   *   name: 'Jane Doe',
+   *   email: 'jane@example.com',
+   *   preferences: { theme: 'dark' }
+   * });
+   * ```
+   */
+  async createUser(userData: CreateUserData): Promise<User> {
+    // Implementation here
+  }
+}
+````
+
+### Interface and Type Documentation
+
+````typescript
+/**
+ * Configuration options for user retrieval operations.
+ *
+ * @public
+ */
+export interface GetUserOptions {
+  /**
+   * Whether to use cached data if available.
+   * @defaultValue true
+   */
+  useCache?: boolean;
+
+  /**
+   * Cache timeout in milliseconds.
+   * @defaultValue 300000 (5 minutes)
+   */
+  cacheTimeout?: number;
+
+  /**
+   * Additional fields to include in the response.
+   * @defaultValue []
+   */
+  includeFields?: Array<'preferences' | 'metadata' | 'lastLogin'>;
+}
+
+/**
+ * User data structure returned by the API.
+ *
+ * @example
+ * ```typescript
+ * const user: User = {
+ *   id: '123e4567-e89b-12d3-a456-426614174000',
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ *   createdAt: new Date('2023-01-01T00:00:00Z'),
+ *   updatedAt: new Date('2023-06-01T12:00:00Z'),
+ *   isActive: true,
+ *   preferences: {
+ *     theme: 'dark',
+ *     notifications: true
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface User {
+  /** Unique identifier for the user (UUID v4 format) */
+  id: string;
+
+  /** Full name of the user */
+  name: string;
+
+  /**
+   * Email address (unique across all users)
+   * @format email
+   */
+  email: string;
+
+  /** Timestamp when the user was created */
+  createdAt: Date;
+
+  /** Timestamp when the user was last updated */
+  updatedAt: Date;
+
+  /**
+   * Whether the user account is active
+   * @defaultValue true
+   */
+  isActive: boolean;
+
+  /**
+   * User preferences and settings
+   * @optional
+   */
+  preferences?: UserPreferences;
+}
+
+/**
+ * Discriminated union type for different user roles.
+ *
+ * @example
+ * ```typescript
+ * function handleUser(user: UserRole) {
+ *   switch (user.type) {
+ *     case 'admin':
+ *       // user.permissions is available here
+ *       console.log('Admin permissions:', user.permissions);
+ *       break;
+ *     case 'member':
+ *       // user.membershipLevel is available here
+ *       console.log('Membership level:', user.membershipLevel);
+ *       break;
+ *     case 'guest':
+ *       // user.expiresAt is available here
+ *       console.log('Guest expires at:', user.expiresAt);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type UserRole =
+  | { type: 'admin'; permissions: string[] }
+  | { type: 'member'; membershipLevel: 'basic' | 'premium' }
+  | { type: 'guest'; expiresAt: Date };
+````
+
+### Error Class Documentation
+
+````typescript
+/**
+ * Error thrown when user validation fails.
+ *
+ * This error includes detailed information about which validation
+ * rules failed and can be used to provide specific feedback to users.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await userService.createUser(invalidData);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.log('Validation failed:', error.details);
+ *     error.details.forEach(detail => {
+ *       console.log(`${detail.field}: ${detail.message}`);
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export class ValidationError extends Error {
+  /**
+   * Detailed information about validation failures.
+   * Each entry contains the field name and specific error message.
+   */
+  public readonly details: ValidationDetail[];
+
+  /**
+   * Error code for programmatic handling.
+   * @defaultValue 'VALIDATION_ERROR'
+   */
+  public readonly code: string = 'VALIDATION_ERROR';
+
+  /**
+   * Creates a new ValidationError.
+   *
+   * @param message - High-level error message
+   * @param details - Specific validation failure details
+   */
+  constructor(message: string, details: ValidationDetail[]) {
+    super(message);
+    this.name = 'ValidationError';
+    this.details = details;
+  }
+
+  /**
+   * Returns a formatted string of all validation errors.
+   *
+   * @returns Multi-line string with each validation error on a separate line
+   */
+  getFormattedDetails(): string {
+    return this.details
+      .map((detail) => `${detail.field}: ${detail.message}`)
+      .join('\n');
+  }
+}
+````
+
+### Module and Namespace Documentation
+
+````typescript
+/**
+ * @fileoverview User management utilities and services.
+ *
+ * This module provides a comprehensive set of tools for managing user data,
+ * including validation, caching, and database operations. It follows the
+ * repository pattern for data access and includes extensive error handling.
+ *
+ * @example
+ * ```typescript
+ * import { UserService, ValidationError } from './user-module';
+ *
+ * const userService = new UserService(dependencies);
+ *
+ * try {
+ *   const user = await userService.createUser(userData);
+ *   console.log('User created:', user.id);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error('Validation failed:', error.getFormattedDetails());
+ *   }
+ * }
+ * ```
+ *
+ * @author Development Team <dev@example.com>
+ * @since 1.0.0
+ * @version 2.1.0
+ */
+
+/**
+ * Namespace containing user-related utility functions.
+ *
+ * @namespace UserUtils
+ */
+export namespace UserUtils {
+  /**
+   * Validates email format using RFC 5322 compliant regex.
+   *
+   * @param email - Email address to validate
+   * @returns True if email format is valid
+   *
+   * @example
+   * ```typescript
+   * if (UserUtils.isValidEmail('user@example.com')) {
+   *   console.log('Valid email format');
+   * }
+   * ```
+   */
+  export function isValidEmail(email: string): boolean {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+  }
+
+  /**
+   * Generates a display name from user data.
+   *
+   * @param user - User object
+   * @returns Formatted display name
+   *
+   * @internal
+   */
+  export function getDisplayName(user: Pick<User, 'name' | 'email'>): string {
+    return user.name || user.email.split('@')[0];
+  }
+}
+````
+
+### API Route Documentation
+
+````typescript
+/**
+ * @fileoverview User API routes and handlers.
+ *
+ * This module defines REST API endpoints for user management operations.
+ * All endpoints require authentication except for user registration.
+ *
+ * @version 2.0.0
+ */
+
+import { Router, Request, Response } from 'express';
+
+/**
+ * User-related API endpoints.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { userRoutes } from './routes/user-routes';
+ *
+ * const app = express();
+ * app.use('/api/users', userRoutes);
+ * ```
+ */
+export const userRoutes = Router();
+
+/**
+ * GET /api/users/:id - Retrieve user by ID.
+ *
+ * @route GET /api/users/:id
+ * @param {string} id - User ID (UUID format)
+ * @returns {User} User object if found
+ * @returns {404} Not found if user doesn't exist
+ * @returns {400} Bad request if ID format is invalid
+ *
+ * @example
+ * ```bash
+ * curl -X GET /api/users/123e4567-e89b-12d3-a456-426614174000 \
+ *   -H "Authorization: Bearer YOUR_TOKEN"
+ * ```
+ *
+ * @example Response
+ * ```json
+ * {
+ *   "id": "123e4567-e89b-12d3-a456-426614174000",
+ *   "name": "John Doe",
+ *   "email": "john@example.com",
+ *   "createdAt": "2023-01-01T00:00:00.000Z",
+ *   "isActive": true
+ * }
+ * ```
+ */
+userRoutes.get('/:id', async (req: Request, res: Response) => {
+  // Implementation here
+});
+
+/**
+ * POST /api/users - Create a new user.
+ *
+ * @route POST /api/users
+ * @param {CreateUserData} body - User data for creation
+ * @returns {User} Created user object with generated ID
+ * @returns {400} Bad request if validation fails
+ * @returns {409} Conflict if email already exists
+ *
+ * @example Request Body
+ * ```json
+ * {
+ *   "name": "Jane Doe",
+ *   "email": "jane@example.com",
+ *   "preferences": {
+ *     "theme": "dark",
+ *     "notifications": true
+ *   }
+ * }
+ * ```
+ */
+userRoutes.post('/', async (req: Request, res: Response) => {
+  // Implementation here
+});
+````
+
+### Configuration and Constants Documentation
+
+````typescript
+/**
+ * @fileoverview Application configuration and constants.
+ *
+ * This module contains all configuration values and constants used
+ * throughout the application. Values are loaded from environment
+ * variables with sensible defaults for development.
+ */
+
+/**
+ * Database configuration settings.
+ *
+ * @example
+ * ```typescript
+ * import { DatabaseConfig } from './config';
+ *
+ * const connection = new DatabaseConnection(DatabaseConfig);
+ * ```
+ */
+export const DatabaseConfig = {
+  /**
+   * Database connection URL.
+   * @env DATABASE_URL
+   * @defaultValue 'postgresql://localhost:5432/myapp_dev'
+   */
+  url: process.env.DATABASE_URL || 'postgresql://localhost:5432/myapp_dev',
+
+  /**
+   * Maximum number of database connections in pool.
+   * @env DB_POOL_SIZE
+   * @defaultValue 10
+   */
+  poolSize: parseInt(process.env.DB_POOL_SIZE || '10', 10),
+
+  /**
+   * Connection timeout in milliseconds.
+   * @env DB_TIMEOUT
+   * @defaultValue 30000
+   */
+  timeout: parseInt(process.env.DB_TIMEOUT || '30000', 10),
+} as const;
+
+/**
+ * User validation constants.
+ *
+ * These constants define the validation rules for user data
+ * and are used throughout the application for consistency.
+ */
+export const UserValidation = {
+  /** Minimum length for user names */
+  NAME_MIN_LENGTH: 2,
+
+  /** Maximum length for user names */
+  NAME_MAX_LENGTH: 100,
+
+  /** Maximum length for email addresses */
+  EMAIL_MAX_LENGTH: 254,
+
+  /** Regex pattern for valid email format */
+  EMAIL_PATTERN: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+
+  /** List of reserved usernames that cannot be used */
+  RESERVED_NAMES: ['admin', 'root', 'system', 'api'] as const,
+} as const;
+````
+
+## Node.js Specific Documentation
+
+### Process and Environment Documentation
+
+````typescript
+/**
+ * @fileoverview Process management and graceful shutdown handling.
+ *
+ * This module handles process lifecycle events and ensures graceful
+ * shutdown of the application with proper cleanup of resources.
+ */
+
+/**
+ * Graceful shutdown manager for Node.js applications.
+ *
+ * Handles SIGINT and SIGTERM signals to ensure clean shutdown
+ * with proper cleanup of database connections, file handles, and
+ * other resources.
+ *
+ * @example
+ * ```typescript
+ * const shutdownManager = new GracefulShutdown();
+ *
+ * shutdownManager.addHandler('database', async () => {
+ *   await database.disconnect();
+ * });
+ *
+ * shutdownManager.addHandler('server', async () => {
+ *   await server.close();
+ * });
+ *
+ * shutdownManager.start();
+ * ```
+ */
+export class GracefulShutdown {
+  /**
+   * Map of cleanup handlers by name.
+   * @private
+   */
+  private handlers = new Map<string, () => Promise<void>>();
+
+  /**
+   * Whether shutdown process has started.
+   * @private
+   */
+  private isShuttingDown = false;
+
+  /**
+   * Adds a cleanup handler for a named resource.
+   *
+   * @param name - Unique name for the handler
+   * @param handler - Async function to clean up the resource
+   *
+   * @throws {Error} If handler name already exists
+   */
+  addHandler(name: string, handler: () => Promise<void>): void {
+    if (this.handlers.has(name)) {
+      throw new Error(`Handler '${name}' already exists`);
+    }
+    this.handlers.set(name, handler);
+  }
+}
+````
+
+### Stream Documentation
+
+````typescript
+/**
+ * Custom transform stream for processing large datasets.
+ *
+ * This stream processes data in chunks to handle large files
+ * efficiently without loading everything into memory at once.
+ *
+ * @example
+ * ```typescript
+ * import fs from 'fs';
+ * import { DataProcessor } from './data-processor';
+ *
+ * const processor = new DataProcessor({
+ *   batchSize: 1000,
+ *   transform: (chunk) => chunk.toUpperCase()
+ * });
+ *
+ * fs.createReadStream('input.txt')
+ *   .pipe(processor)
+ *   .pipe(fs.createWriteStream('output.txt'));
+ * ```
+ */
+export class DataProcessor extends Transform {
+  /**
+   * Number of items to process in each batch.
+   * @private
+   */
+  private readonly batchSize: number;
+
+  /**
+   * Function to transform each data chunk.
+   * @private
+   */
+  private readonly transformFn: (chunk: string) => string;
+
+  /**
+   * Creates a new DataProcessor stream.
+   *
+   * @param options - Processor configuration
+   * @param options.batchSize - Number of items per batch
+   * @param options.transform - Function to transform each chunk
+   */
+  constructor(options: DataProcessorOptions) {
+    super({ objectMode: true });
+    this.batchSize = options.batchSize || 100;
+    this.transformFn = options.transform || ((x) => x);
+  }
+}
+````
+
+## README and Package Documentation
+
+### Package.json Documentation Guidelines
+
+```json
+{
+  "name": "user-management-service",
+  "version": "2.1.0",
+  "description": "Comprehensive user management service with caching, validation, and REST API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "test:watch": "jest --watch",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "docs": "typedoc src --out docs"
+  },
+  "keywords": [
+    "user-management",
+    "authentication",
+    "rest-api",
+    "typescript",
+    "caching"
+  ],
+  "author": "Your Name <your.email@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/username/user-management-service.git"
+  },
+  "bugs": {
+    "url": "https://github.com/username/user-management-service/issues"
+  },
+  "homepage": "https://github.com/username/user-management-service#readme"
+}
+```
+
+### TypeDoc Configuration
+
+```javascript
+// typedoc.json
+{
+  "entryPoints": ["src/index.ts"],
+  "out": "docs",
+  "excludePrivate": true,
+  "excludeProtected": false,
+  "excludeInternal": false,
+  "categorizeByGroup": true,
+  "sort": ["source-order"],
+  "kindSortOrder": [
+    "Module",
+    "Namespace",
+    "Enum",
+    "Class",
+    "Interface",
+    "Function",
+    "Variable"
+  ],
+  "theme": "default",
+  "readme": "README.md",
+  "includeVersion": true
+}
+```