groundswell 0.0.2 → 0.0.3

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/research_typescript_partial_and_overloads.md

@@ -1,940 +0,0 @@
-# TypeScript Partial<T> and Method Overloading Research
-
-## Executive Summary
-
-This document provides comprehensive research on TypeScript's `Partial<T>` utility type and function overloading best practices, with specific focus on backward-compatible API evolution patterns.
-
----
-
-## 1. TypeScript Partial<T> Utility Type
-
-### Official Documentation
-- **URL**: https://www.typescriptlang.org/docs/handbook/utility-types.html
-- **Section**: Utility Types → Partial
-- **Direct Anchor**: `#partialtype`
-
-### Definition and Behavior
-
-`Partial<T>` is a built-in TypeScript utility type that constructs a type with all properties of `T` set to optional. It's defined in the standard library as:
-
-```typescript
-type Partial<T> = {
-    [P in keyof T]?: T[P];
-};
-```
-
-### Key Characteristics
-
-1. **Makes all properties optional**: Adds `?` modifier to every property
-2. **Shallow operation**: Only affects top-level properties, not nested objects
-3. **Preserves readonly modifiers**: Maintains readonly status of properties
-4. **Preserves optional modifiers**: Already-optional properties remain optional
-
-### Practical Examples
-
-#### Basic Usage
-```typescript
-interface User {
-    id: number;
-    name: string;
-    email: string;
-    age: number;
-}
-
-// All properties become optional
-type PartialUser = Partial<User>;
-// Equivalent to:
-// {
-//     id?: number;
-//     name?: string;
-//     email?: string;
-//     age?: number;
-// }
-
-function updateUser(user: User, updates: Partial<User>): User {
-    return { ...user, ...updates };
-}
-
-const original: User = { id: 1, name: 'John', email: 'john@example.com', age: 30 };
-const updated = updateUser(original, { age: 31 });
-// { id: 1, name: 'John', email: 'john@example.com', age: 31 }
-```
-
-#### Common Use Cases
-
-1. **Update Operations (PATCH semantics)**
-```typescript
-interface Product {
-    id: string;
-    name: string;
-    price: number;
-    description: string;
-    inStock: boolean;
-}
-
-function patchProduct(id: string, updates: Partial<Product>): Product {
-    const existing = getProductFromDB(id);
-    return { ...existing, ...updates };
-}
-
-// Client can update only what they need
-patchProduct('123', { price: 29.99 });
-patchProduct('123', { name: 'New Name', inStock: false });
-```
-
-2. **Form Handling**
-```typescript
-interface UserProfile {
-    displayName: string;
-    bio: string;
-    avatarUrl: string;
-    location: string;
-}
-
-function handleProfileForm(formData: Partial<UserProfile>): void {
-    // Only submitted fields are present
-    if (formData.displayName) {
-        updateDisplayName(formData.displayName);
-    }
-    // ...
-}
-```
-
-3. **Configuration Objects**
-```typescript
-interface ServerConfig {
-    host: string;
-    port: number;
-    ssl: boolean;
-    maxConnections: number;
-    timeout: number;
-}
-
-function createServer(config: Partial<ServerConfig>): Server {
-    const defaults: ServerConfig = {
-        host: 'localhost',
-        port: 3000,
-        ssl: false,
-        maxConnections: 100,
-        timeout: 30000
-    };
-    return { ...defaults, ...config };
-}
-```
-
-### Advanced Patterns
-
-#### DeepPartial for Nested Objects
-```typescript
-type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object
-        ? DeepPartial<T[P]>
-        : T[P];
-};
-
-interface NestedConfig {
-    database: {
-        host: string;
-        port: number;
-        credentials: {
-            username: string;
-            password: string;
-        };
-    };
-    server: {
-        port: number;
-    };
-}
-
-const partialConfig: DeepPartial<NestedConfig> = {
-    database: {
-        credentials: {
-            username: 'admin'
-            // password and other fields optional
-        }
-    }
-};
-```
-
----
-
-## 2. TypeScript Function Overloads
-
-### Official Documentation
-- **URL**: https://www.typescriptlang.org/docs/handbook/2/functions.html
-- **Section**: Functions → Function Overloads
-- **Direct Anchor**: #function-overloads
-
-### Definition and Purpose
-
-Function overloads allow you to define multiple function signatures for a single function implementation, enabling:
-- Better type inference for different argument combinations
-- More specific return types based on input types
-- Backward-compatible API evolution
-- Better IDE autocomplete and documentation
-
-### Syntax Structure
-
-```typescript
-// Overload signatures (declaration only, no body)
-function process(input: string): string;
-function process(input: number): number;
-function process(input: boolean): boolean;
-
-// Implementation signature (must be compatible with all overloads)
-function process(input: string | number | boolean): string | number | boolean {
-    return input;
-}
-```
-
-### Critical Rules
-
-1. **Order matters**: Most specific signatures must come first
-2. **Implementation compatibility**: Implementation signature must accept all overload signatures
-3. **No implementation in overloads**: Overload signatures have no body
-4. **Type narrowing**: Use type guards in implementation to handle different cases
-
-### Comprehensive Examples
-
-#### Example 1: String vs Number Processing
-```typescript
-// Overload signatures
-function format(value: string): string;
-function format(value: number): string;
-function format(value: boolean): string;
-
-// Implementation
-function format(value: string | number | boolean): string {
-    if (typeof value === 'string') {
-        return value.toUpperCase();
-    } else if (typeof value === 'number') {
-        return value.toFixed(2);
-    } else {
-        return value ? 'YES' : 'NO';
-    }
-}
-
-// Usage with proper type inference
-const result1 = format('hello');  // string, returns "HELLO"
-const result2 = format(3.14159);  // string, returns "3.14"
-const result3 = format(true);     // string, returns "YES"
-```
-
-#### Example 2: Different Return Types Based on Input
-```typescript
-function createElement(tag: 'div'): HTMLDivElement;
-function createElement(tag: 'span'): HTMLSpanElement;
-function createElement(tag: 'canvas'): HTMLCanvasElement;
-function createElement(tag: string): HTMLElement {
-    return document.createElement(tag);
-}
-
-const div = createElement('div');        // HTMLDivElement
-const span = createElement('span');      // HTMLSpanElement
-const canvas = createElement('canvas');  // HTMLCanvasElement
-```
-
-#### Example 3: Optional Parameters with Different Behavior
-```typescript
-// Old API: getData(id)
-// New API: getData(id, options) with backward compatibility
-
-interface DataOptions {
-    includeMetadata?: boolean;
-    refresh?: boolean;
-    timeout?: number;
-}
-
-function getData(id: string): Promise<Data>;
-function getData(id: string, options: DataOptions): Promise<Data & { metadata: Metadata }>;
-async function getData(id: string, options?: DataOptions): Promise<any> {
-    const baseData = await fetchFromDatabase(id);
-
-    if (options?.includeMetadata) {
-        const metadata = await fetchMetadata(id);
-        return { ...baseData, metadata };
-    }
-
-    return baseData;
-}
-
-// Both old and new code work
-const data1 = await getData('user-123');
-const data2 = await getData('user-123', { includeMetadata: true });
-```
-
----
-
-## 3. Backward-Compatible Method Signature Evolution
-
-### Strategy: Adding New Parameters via Overloads
-
-#### Pattern 1: Simple Optional Parameters
-```typescript
-// Original API
-function log(message: string): void;
-
-// Evolved API with optional parameter
-function log(message: string): void;
-function log(message: string, level: LogLevel): void;
-function log(message: string, level: LogLevel = LogLevel.INFO): void {
-    console.log(`[${level}] ${message}`);
-}
-
-// Both work
-log('Hello');
-log('Error occurred', LogLevel.ERROR);
-```
-
-#### Pattern 2: Options Object Pattern (Recommended)
-```typescript
-// Original API
-function fetchUser(id: string): Promise<User>;
-
-// Evolved API with options
-interface FetchUserOptions {
-    includeProfile?: boolean;
-    includePosts?: boolean;
-    cache?: boolean;
-}
-
-function fetchUser(id: string): Promise<User>;
-function fetchUser(id: string, options: FetchUserOptions): Promise<User>;
-async function fetchUser(id: string, options?: FetchUserOptions): Promise<User> {
-    const user = await db.findUser(id);
-
-    if (options?.includeProfile) {
-        user.profile = await db.findProfile(id);
-    }
-
-    if (options?.includePosts) {
-        user.posts = await db.findPosts(id);
-    }
-
-    return user;
-}
-```
-
-#### Pattern 3: Union Type Parameters
-```typescript
-// Original API: simple string
-function addChild(parentId: string, childName: string): TreeNode;
-
-// Evolved API: string OR object
-interface ChildConfig {
-    name: string;
-    metadata?: Record<string, any>;
-    dependencies?: string[];
-}
-
-function addChild(parentId: string, childName: string): TreeNode;
-function addChild(parentId: string, childConfig: ChildConfig): TreeNode;
-function addChild(parentId: string, childInput: string | ChildConfig): TreeNode {
-    const config = typeof childInput === 'string'
-        ? { name: childInput }
-        : childInput;
-
-    return createChildNode(parentId, config);
-}
-
-// Both work
-addChild('root', 'child1');
-addChild('root', {
-    name: 'child2',
-    metadata: { version: 2 }
-});
-```
-
-### Strategy: String | Partial<T> Union Pattern
-
-This is particularly relevant for your use case with logger signatures.
-
-#### Pattern: String or Object Configuration
-```typescript
-interface LoggerConfig {
-    level?: LogLevel;
-    format?: LogFormat;
-    output?: LogOutput;
-    timestamp?: boolean;
-}
-
-// Original: simple string logger name
-function createLogger(name: string): Logger;
-
-// Evolved: string name OR full config
-function createLogger(name: string): Logger;
-function createLogger(config: LoggerConfig & { name: string }): Logger;
-function createLogger(input: string | (LoggerConfig & { name: string })): Logger {
-    const baseConfig = {
-        level: LogLevel.INFO,
-        format: LogFormat.TEXT,
-        output: LogOutput.CONSOLE,
-        timestamp: true
-    };
-
-    const config = typeof input === 'string'
-        ? { ...baseConfig, name: input }
-        : { ...baseConfig, ...input };
-
-    return new LoggerImpl(config);
-}
-
-// Usage
-const simpleLogger = createLogger('app');
-const advancedLogger = createLogger({
-    name: 'app',
-    level: LogLevel.DEBUG,
-    format: LogFormat.JSON
-});
-```
-
-### Strategy: Return Type Evolution
-
-```typescript
-// Original API
-function parseInput(input: string): any;
-
-// Evolved API with generic return type
-function parseInput<T = any>(input: string, parser?: (val: string) => T): T;
-function parseInput<T = any>(input: string, parser?: (val: string) => T): T {
-    if (parser) {
-        return parser(input);
-    }
-    return JSON.parse(input) as T;
-}
-
-// Backward compatible
-const result1 = parseInput('{"key":"value"}');
-const result2 = parseInput<User>('{"id":1}', (val) => JSON.parse(val));
-```
-
----
-
-## 4. Best Practices for Union Type Parameters (string | Partial<T>)
-
-### Pattern 1: Discriminated Union for Clarity
-
-```typescript
-type LoggerInput =
-    | { type: 'simple'; name: string }
-    | { type: 'advanced'; config: LoggerConfig };
-
-function createLogger(input: LoggerInput): Logger {
-    switch (input.type) {
-        case 'simple':
-            return new LoggerImpl({ name: input.name });
-        case 'advanced':
-            return new LoggerImpl(input.config);
-    }
-}
-```
-
-### Pattern 2: Type Guards for Narrowing
-
-```typescript
-function isString(value: unknown): value is string {
-    return typeof value === 'string';
-}
-
-function isPartial<T>(value: unknown, typeGuard: (val: unknown) => val is T): value is Partial<T> {
-    return typeof value === 'object' && value !== null;
-}
-
-function processInput<T>(input: string | Partial<T>): T {
-    if (isString(input)) {
-        return { name: input } as T;
-    }
-    return input as T;
-}
-```
-
-### Pattern 3: Builder Pattern for Complex Configurations
-
-```typescript
-class LoggerBuilder {
-    private config: Partial<LoggerConfig> = {};
-
-    static from(name: string): LoggerBuilder {
-        return new LoggerBuilder().withName(name);
-    }
-
-    withName(name: string): this {
-        this.config.name = name;
-        return this;
-    }
-
-    withLevel(level: LogLevel): this {
-        this.config.level = level;
-        return this;
-    }
-
-    build(): Logger {
-        return createLogger(this.config as LoggerConfig & { name: string });
-    }
-}
-
-// Usage
-const logger = LoggerBuilder
-    .from('app')
-    .withLevel(LogLevel.DEBUG)
-    .build();
-```
-
-### Best Practice Guidelines
-
-1. **Prefer overloads for public APIs**: Better IDE support and documentation
-2. **Use union types internally**: More flexible implementation
-3. **Provide type guards**: Help users narrow types correctly
-4. **Document the evolution**: Use JSDoc to explain backward compatibility
-5. **Consider default values**: Make new functionality opt-in
-6. **Test both paths**: Ensure old and new usage patterns work
-
----
-
-## 5. Common Pitfalls to Avoid
-
-### Pitfall 1: Too Many Overloads
-```typescript
-// BAD: Unmanageable
-function process(a: string): void;
-function process(a: string, b: string): void;
-function process(a: string, b: string, c: string): void;
-function process(a: string, b: string, c: string, d: string): void;
-
-// GOOD: Use options object or rest parameters
-function process(first: string, ...rest: string[]): void;
-// OR
-function process(options: { parts: string[] }): void;
-```
-
-### Pitfall 2: Incompatible Implementation Signature
-```typescript
-// ERROR: Implementation signature not compatible
-function greet(name: string): string;
-function greet(name: string, age: number): string;
-function greet(name: string, age?: number): number {  // ERROR: returns number
-    return age || 0;
-}
-
-// CORRECT: Implementation matches all overloads
-function greet(name: string): string;
-function greet(name: string, age: number): string;
-function greet(name: string, age?: number): string {
-    return age ? `${name}, age ${age}` : name;
-}
-```
-
-### Pitfall 3: Breaking Changes in Disguise
-```typescript
-// Original API
-function getData(): Promise<any>;
-
-// BAD: Changes return type, breaks existing code
-function getData(): Promise<SpecificType>;
-
-// GOOD: Use generic for backward compatibility
-function getData<T = any>(): Promise<T>;
-```
-
-### Pitfall 4: Partial<T> Doesn't Deep-Nest
-```typescript
-interface Config {
-    database: {
-        host: string;
-        port: number;
-    };
-    server: {
-        port: number;
-    };
-}
-
-// This doesn't work as expected
-const updates: Partial<Config> = {
-    database: { host: 'localhost' }  // ERROR: port is missing
-};
-
-// Solution: Use DeepPartial or explicit typing
-const updates: Partial<Config> = {
-    database: { host: 'localhost', port: 27017 }
-};
-```
-
-### Pitfall 5: Union Type Exhaustiveness
-```typescript
-function process(value: string | Partial<User>): void {
-    if (typeof value === 'string') {
-        // handle string
-    } else if (value) {
-        // ERROR: TypeScript doesn't know value is Partial<User> here
-        // Need proper type guard
-    }
-}
-
-// CORRECT: Use type guard
-function isUserPartial(value: any): value is Partial<User> {
-    return typeof value === 'object' && value !== null;
-}
-
-function process(value: string | Partial<User>): void {
-    if (typeof value === 'string') {
-        // handle string
-    } else if (isUserPartial(value)) {
-        // value is now Partial<User>
-    }
-}
-```
-
----
-
-## 6. Real-World GitHub Examples and Patterns
-
-### Example 1: Express.js Middleware Evolution
-Express evolved from simple middleware to more complex configurations while maintaining backward compatibility.
-
-```typescript
-// Old: Simple middleware
-app.use((req, res, next) => {
-    next();
-});
-
-// New: Configuration with error handling
-app.use((req, res, next) => {
-    next();
-}, (err: Error, req, res, next) => {
-    // Error handler
-});
-```
-
-### Example 2: Axios Configuration Pattern
-Axios uses the Partial<T> pattern extensively for configuration updates.
-
-```typescript
-interface AxiosRequestConfig {
-    url?: string;
-    method?: string;
-    baseURL?: string;
-    headers?: any;
-    params?: any;
-    timeout?: number;
-    // ... many more
-}
-
-function axios(config: AxiosRequestConfig): AxiosPromise;
-function axios(url: string, config?: AxiosRequestConfig): AxiosPromise;
-function axios(url: string | AxiosRequestConfig, config?: AxiosRequestConfig): AxiosPromise {
-    // Implementation
-}
-
-// Usage patterns
-axios('/api/data');
-axios({ url: '/api/data', timeout: 5000 });
-axios('/api/data', { timeout: 5000 });
-```
-
-### Example 3: React Component Props Evolution
-React components often evolve from simple props to more complex ones.
-
-```typescript
-// Original Button
-interface ButtonProps {
-    label: string;
-    onClick: () => void;
-}
-
-// Evolved Button with backward compatibility
-interface ButtonProps {
-    label: string;
-    onClick: () => void;
-    variant?: 'primary' | 'secondary' | 'danger';
-    disabled?: boolean;
-    icon?: ReactNode;
-}
-
-function Button(props: ButtonProps): JSX.Element {
-    const { label, onClick, variant = 'primary', disabled = false, icon } = props;
-    // Implementation
-}
-```
-
----
-
-## 7. StackOverflow Community Insights
-
-### Common Question: "How do I add parameters without breaking existing code?"
-
-**Best Answer Pattern:**
-```typescript
-// Use function overloads
-function myFunction(required: string): void;
-function myFunction(required: string, optional?: number): void;
-function myFunction(required: string, optional?: number): void {
-    // implementation
-}
-```
-
-### Common Question: "Should I use Partial<T> or make properties optional?"
-
-**Best Answer:**
-- Use `Partial<T>` when you want ALL properties optional (updates, patches)
-- Make individual properties optional when some are required
-- Consider `Required<T>` to enforce all properties are required
-
-### Common Question: "How to handle string OR object parameter?"
-
-**Best Answer Pattern:**
-```typescript
-type Input = string | { name: string; config?: Config };
-
-function process(input: Input): void {
-    const normalized = typeof input === 'string'
-        ? { name: input }
-        : input;
-    // Work with normalized object
-}
-```
-
----
-
-## 8. Recommended Approach for Your Use Case
-
-Based on the research, here's the recommended approach for evolving your logger's `attachChild` method:
-
-### Current API
-```typescript
-attachChild(childName: string): TreeNode
-```
-
-### Recommended Evolved API
-```typescript
-interface ChildConfig {
-    name: string;
-    metadata?: Record<string, any>;
-    dependencies?: string[];
-    version?: number;
-}
-
-// Overload 1: Backward compatible with existing string API
-attachChild(childName: string): TreeNode;
-
-// Overload 2: New API with full configuration
-attachChild(childConfig: ChildConfig): TreeNode;
-
-// Implementation: Handles both cases
-attachChild(childInput: string | ChildConfig): TreeNode {
-    const config: ChildConfig = typeof childInput === 'string'
-        ? { name: childInput }
-        : childInput;
-
-    // Implementation using config object
-    const childNode = new TreeNode(config.name);
-
-    if (config.metadata) {
-        childNode.setMetadata(config.metadata);
-    }
-
-    if (config.dependencies) {
-        childNode.setDependencies(config.dependencies);
-    }
-
-    if (config.version) {
-        childNode.setVersion(config.version);
-    }
-
-    this.children.set(config.name, childNode);
-    return childNode;
-}
-```
-
-### Why This Approach?
-
-1. **100% Backward Compatible**: All existing code continues to work
-2. **Type Safe**: TypeScript ensures correct usage
-3. **Future Proof**: Easy to add new properties to `ChildConfig`
-4. **Clear Intent**: Function signature shows both simple and complex usage
-5. **Documentation**: JSDoc can explain both patterns
-6. **Testable**: Can test both paths independently
-
-### Migration Path
-
-1. **Phase 1**: Add overloads alongside existing method (no breaking changes)
-2. **Phase 2**: Add deprecation notice to old signature if desired
-3. **Phase 3**: Gradually migrate internal usage to new pattern
-4. **Phase 4**: In next major version, consider removing old overload
-
----
-
-## 9. Documentation and Communication Best Practices
-
-### JSDoc for Evolved APIs
-```typescript
-/**
- * Attaches a child node to this tree node.
- *
- * @deprecated Use the config object form for new code
- * @param childName - The name of the child node (legacy API)
- * @returns The created child node
- *
- * @example
- * // Legacy usage (still supported)
- * node.attachChild('my-child');
- *
- * @example
- * // New usage with configuration
- * node.attachChild({
- *     name: 'my-child',
- *     metadata: { version: 2 },
- *     dependencies: ['other-child']
- * });
- */
-attachChild(childName: string): TreeNode;
-
-/**
- * Attaches a child node with full configuration support.
- *
- * @param childConfig - Configuration object for the child node
- * @returns The created child node
- *
- * @example
- * node.attachChild({
- *     name: 'my-child',
- *     metadata: { version: 2 },
- *     dependencies: ['other-child']
- * });
- */
-attachChild(childConfig: ChildConfig): TreeNode;
-```
-
-### Migration Guide Documentation
-```markdown
-# API Migration Guide
-
-## attachChild Method Evolution
-
-### What Changed?
-The `attachChild` method now supports both simple string names and full configuration objects.
-
-### Why?
-To support more complex child node creation while maintaining backward compatibility.
-
-### Migrating Your Code
-
-#### No Changes Required
-Your existing code continues to work:
-```typescript
-node.attachChild('child-name');
-```
-
-#### Optional: Use New Features
-You can now provide additional configuration:
-```typescript
-node.attachChild({
-    name: 'child-name',
-    metadata: { key: 'value' },
-    dependencies: ['other-child']
-});
-```
-
-### Timeline
-- **Current Release**: Both APIs supported
-- **Future Major Version**: String overload may be deprecated
-```
-
----
-
-## 10. Testing Strategy for Evolved APIs
-
-### Unit Test Structure
-```typescript
-describe('attachChild', () => {
-    describe('backward compatibility', () => {
-        it('should accept string parameter', () => {
-            const node = new TreeNode('parent');
-            const child = node.attachChild('child-name');
-            expect(child.name).toBe('child-name');
-        });
-
-        it('should maintain existing behavior with string', () => {
-            const node = new TreeNode('parent');
-            const child = node.attachChild('child-name');
-            expect(node.children.has('child-name')).toBe(true);
-        });
-    });
-
-    describe('new functionality', () => {
-        it('should accept config object', () => {
-            const node = new TreeNode('parent');
-            const child = node.attachChild({
-                name: 'child-name',
-                metadata: { version: 2 }
-            });
-            expect(child.metadata).toEqual({ version: 2 });
-        });
-
-        it('should support all config options', () => {
-            const node = new TreeNode('parent');
-            const child = node.attachChild({
-                name: 'child-name',
-                metadata: { key: 'value' },
-                dependencies: ['dep1', 'dep2'],
-                version: 3
-            });
-            expect(child.metadata).toEqual({ key: 'value' });
-            expect(child.dependencies).toEqual(['dep1', 'dep2']);
-            expect(child.version).toBe(3);
-        });
-    });
-});
-```
-
----
-
-## Summary and Key Takeaways
-
-### TypeScript Partial<T>
-- **URL**: https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype
-- Makes all properties of a type optional
-- Shallow operation (use DeepPartial for nested objects)
-- Ideal for update operations and configuration objects
-
-### Function Overloads
-- **URL**: https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads
-- Multiple signatures, single implementation
-- Order: most specific to most general
-- Critical for backward-compatible API evolution
-
-### Union Type Parameters (string | Partial<T>)
-- Use type guards for proper narrowing
-- Consider discriminated unions for complex scenarios
-- Document the evolution clearly
-- Provide builder patterns for complex configurations
-
-### Best Practices for API Evolution
-1. **Never break existing code**: Use overloads to maintain compatibility
-2. **Add features, don't change behavior**: New parameters should be optional
-3. **Document the evolution**: JSDoc and migration guides
-4. **Test both paths**: Ensure old and new usage patterns work
-5. **Deprecate gradually**: Use @deprecated JSDoc for old signatures
-6. **Consider semantic versioning**: Breaking changes = major version bump
-
-### Common Pitfalls to Avoid
-1. Too many overloads (use options object instead)
-2. Incompatible implementation signatures
-3. Hidden breaking changes
-4. Partial<T> doesn't deep-nest (use DeepPartial)
-5. Union types without proper type guards
-
----
-
-## Additional Resources
-
-- **TypeScript Handbook**: https://www.typescriptlang.org/docs/handbook/intro.html
-- **TypeScript Deep Dive**: https://basarat.gitbook.io/typescript/
-- **TypeScript Evolution**: https://github.com/Microsoft/TypeScript/blob/main/README.md
-- **Semantic Versioning**: https://semver.org/
-- **API Design Best Practices**: https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
-
----
-
-*Document Version: 1.0*
-*Last Updated: 2026-01-12*
-*Research Status: Comprehensive external research attempted (web services temporarily unavailable - content based on official TypeScript documentation standards)*