metacoding 1.5.1 → 2.0.1

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

@@ -1,760 +0,0 @@
----
-description: 'TypeScript/Node.js-specific documentation standards and JSDoc patterns'
-applyTo: '**/*.{ts,js}'
----
-
-# 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
-}
-```
-
-## Repeated TypeScript Documentation Tasks and Checklist Templates
-
-For any recurring TypeScript documentation process (such as API releases, type definition updates, or migration guides), always use a dedicated checklist template to ensure all necessary documentation steps are followed and nothing is missed.
-
-- **TypeScript Documentation Checklist Template Principle:**
-  - Maintain a template checklist file for each repeated TypeScript documentation process (e.g., `api-release-docs-checklist.md`, `type-migration-docs-checklist.md`).
-  - For each new instance (e.g., each API release or migration), copy the template checklist and tag it with the relevant version or context, preserving the original template for future use.
-  - Systematically work through the checklist for every instance of the repeated documentation task, marking each step as completed.
-  - Proactively identify any TypeScript documentation process that would benefit from a checklist and prompt the user to use or create one if it does not exist.
-  - If, during execution, you or the user identify missing or unclear documentation steps, update the template checklist to improve future reliability.
-
-**Examples of repeated TypeScript documentation tasks requiring checklists:**
-
-- API releases (JSDoc updates, type definition exports, example verification, TypeDoc generation)
-- TypeScript version migrations (type system changes, breaking changes documentation, compatibility guides)
-- Package documentation (README updates, API reference generation, installation guides, usage examples)
-- Type definition updates (interface changes, generic constraints, utility type documentation)
-- Node.js documentation (environment setup, deployment guides, configuration documentation)
-- Any other TypeScript documentation process with multiple required steps or risk of omission
-
-**Agent Guidance for TypeScript Documentation Tasks:**
-
-- Always check for the existence of a TypeScript documentation checklist template before starting a repeated documentation task.
-- If a template does not exist, prompt the user to create one and assist in drafting it.
-- When using a documentation checklist, copy it for the specific instance (e.g., `api-release-v3.2.0.md`), and work through each step systematically.
-- If new documentation steps are discovered or improvements are needed, update the template and inform the user.