Add generic type parameters for database-specific type safety

[vlavrynovych]

Problem

Currently, MSR uses the generic IDB interface throughout the codebase, which provides limited type safety and forces users to cast to specific database types when accessing database-specific features.

Current Implementation:

interface IDatabaseMigrationHandler {
  db: IDB;  // Generic IDB type - no type safety
  // ...
}

interface IRunnableScript {
  up(db: IDB, info: IMigrationInfo, handler: IDatabaseMigrationHandler): Promise<string>;
  down(db: IDB, info: IMigrationInfo, handler: IDatabaseMigrationHandler): Promise<string>;
}

Issues:

• ❌ No IDE autocomplete for database-specific methods
• ❌ Requires as any or type casting in migration scripts
• ❌ No compile-time validation of database operations
• ❌ Cannot access PostgreSQL-specific features (COPY, etc.)
• ❌ Cannot access MySQL-specific features without casting

---

Proposed Solution

Introduce generic type parameters to make database types strongly typed throughout the interface hierarchy.

Proposed Implementation:

interface IDatabaseMigrationHandler<DB extends IDB = IDB> {
  db: DB;  // Specific database type (IPostgresDB, IMySQLDB, etc.)
  schemaVersion: ISchemaVersion<DB>;
  backup?: IBackup<DB>;
  transactionManager?: ITransactionManager<DB>;
  // ...
}

interface IRunnableScript<DB extends IDB = IDB> {
  up(
    db: DB, 
    info: IMigrationInfo, 
    handler: IDatabaseMigrationHandler<DB>
  ): Promise<string>;
  
  down(
    db: DB, 
    info: IMigrationInfo, 
    handler: IDatabaseMigrationHandler<DB>
  ): Promise<string>;
}

interface ISchemaVersion<DB extends IDB = IDB> {
  migrationRecords: IMigrationRecords<DB>;
  // ...
}

// Usage example:
class PostgreSQLHandler implements IDatabaseMigrationHandler<IPostgresDB> {
  db: IPostgresDB;  // Strongly typed!
  // ...
}

// In migration script:
const migration: IRunnableScript<IPostgresDB> = {
  async up(db, info, handler) {
    // db is IPostgresDB - full autocomplete and type safety!
    await db.query('COPY users FROM ...');  // PostgreSQL-specific
  }
};

---

Benefits

1. Type Safety

• ✅ Compile-time validation of database-specific operations
• ✅ Prevent runtime errors from calling unsupported methods
• ✅ No more as any casting in migration scripts

2. Developer Experience

• ✅ Full IDE autocomplete for database-specific methods
• ✅ Inline documentation for available operations
• ✅ Better refactoring support

3. Code Quality

• ✅ Self-documenting code (types show what's available)
• ✅ Easier to maintain and extend
• ✅ Catches errors at compile time, not runtime

4. Database-Specific Features

• ✅ Access PostgreSQL features (COPY, LISTEN/NOTIFY, etc.)
• ✅ Access MySQL features (specific functions, etc.)
• ✅ Access SQLite features without casting

---

Implementation Considerations

1. Backward Compatibility

Challenge: This is a breaking change for existing handlers and migration scripts.

Mitigation:

• Use default type parameter <DB extends IDB = IDB> for backward compatibility
• Existing code without generics continues to work with base IDB type
• Provide migration guide for upgrading to typed versions
• Consider making this a major version bump (v1.0.0?)

2. Cascade Effect

Challenge: Generic type needs to flow through multiple interfaces.

Affected interfaces:

• IDatabaseMigrationHandler<DB>
• IRunnableScript<DB>
• ISchemaVersion<DB>
• IMigrationRecords<DB>
• IBackup<DB>
• ITransactionManager<DB>
• MigrationScriptExecutor constructor
• MigrationScript<DB> class

3. API Complexity

Challenge: Adds complexity to public API.

Considerations:

• Keep default parameter for simple use cases
• Document when generics are needed vs optional
• Provide examples for common patterns
• Balance type safety vs API simplicity

4. Testing Impact

Challenge: All tests need to be updated.

Scope:

• Update all test mocks to use generics
• Test with different database types
• Verify backward compatibility
• Maintain 100% coverage

---

Implementation Phases

Phase 1: Analysis & Design (🔍 Investigation Required)

• Analyze all interfaces that need generic parameters
• Map dependencies and cascade effects
• Design backward-compatible approach
• Create proof of concept
• Identify breaking changes vs non-breaking changes
• Evaluate impact on existing handlers (@migration-script-runner/postgresql, etc.)

Phase 2: Core Interfaces

• Update IDB and related interfaces
• Update IDatabaseMigrationHandler<DB>
• Update IRunnableScript<DB>
• Update ISchemaVersion<DB>
• Update tests

Phase 3: Supporting Interfaces

• Update IMigrationRecords<DB>
• Update IBackup<DB>
• Update ITransactionManager<DB>
• Update MigrationScript<DB>
• Update tests

Phase 4: Executor & Services

• Update MigrationScriptExecutor
• Update all service classes
• Update loader implementations
• Update tests

Phase 5: Documentation & Migration

• Update all API documentation
• Create migration guide for existing projects
• Update examples to show typed usage
• Document when to use generics vs defaults
• Update DBMS-specific package examples

---

Examples

PostgreSQL Handler

import { IDatabaseMigrationHandler, IPostgresDB } from '@migration-script-runner/core';

class PostgreSQLHandler implements IDatabaseMigrationHandler<IPostgresDB> {
  db: IPostgresDB;
  
  constructor(db: IPostgresDB) {
    this.db = db;
  }
}

Strongly-Typed Migration Script

import { IRunnableScript, IPostgresDB, IMigrationInfo } from '@migration-script-runner/core';

const migration: IRunnableScript<IPostgresDB> = {
  async up(db, info, handler) {
    // Full autocomplete for PostgreSQL-specific features!
    await db.query('CREATE INDEX CONCURRENTLY idx_email ON users(email)');
    await db.copy('COPY users FROM STDIN');  // PostgreSQL COPY command
    
    // TypeScript knows about PostgreSQL-specific methods
    const result = await db.query<{count: number}>('SELECT COUNT(*) FROM users');
  },
  
  async down(db, info, handler) {
    await db.query('DROP INDEX idx_email');
  }
};

export default migration;

Backward Compatible (Default Generic)

// Still works - uses default IDB type
const migration: IRunnableScript = {
  async up(db, info, handler) {
    // db is IDB (base interface)
    await db.checkConnection();
  }
};

---

Open Questions

1. Breaking Change Strategy: Should this be v1.0.0 or can we maintain backward compatibility?
2. Opt-in vs Mandatory: Should generics be optional (with defaults) or required?
3. Database Interface Hierarchy: Do we need IPostgresDB extends IDB, IMySQLDB extends IDB, etc.?
4. Migration Script Typing: How do we infer database type in migration files without explicit typing?
5. Loader Impact: How do loaders (TypeScriptLoader, SqlLoader) handle generic types?

---

Success Criteria

• All core interfaces support generic database types
• Backward compatibility maintained (existing code works)
• Full type safety for database-specific operations
• IDE autocomplete works for typed database instances
• No as any casting needed in migrations
• 100% test coverage maintained
• Documentation updated with typed examples
• Migration guide for upgrading existing projects

---

Related Issues

• Related to DBMS-specific packages (@migration-script-runner/postgresql, etc.)
• May impact Add migration template generator command #83 (Generator) - templates should generate typed migrations
• Complements Support additional config file formats (YAML, TOML, XML) #98 (Config formats) - type safety for config validation

---

Priority

Backlog - Requires deep analysis during implementation to ensure:

• Minimal breaking changes
• Clean generic type propagation
• Backward compatibility where possible
• Clear migration path for existing users

Note: This is a significant architectural change that will improve type safety across the entire framework but requires careful planning and execution.

[vlavrynovych]

✅ Implementation Complete

Successfully implemented generic type parameters throughout MSR core for database-specific type safety.

---

🔨 Breaking Changes

Constructor Signature Change

BEFORE (v0.5.x):

new MigrationScriptExecutor(handler, config)

AFTER (v0.6.0):

new MigrationScriptExecutor<IDB>({ handler }, config)

Changes:

• Handler now required in dependencies object as first parameter
• Config is now second parameter and optional (auto-loads via ConfigLoader if not provided)
• Enables dependency injection pattern for future extensibility

---

✨ Key Improvements

1. Generic Type Parameters

Added <DB extends IDB = IDB> to all core interfaces and classes:

• IDatabaseMigrationHandler<DB>
• IRunnableScript<DB>
• MigrationScriptExecutor<DB>
• ISchemaVersionService<DB>
• ITransactionManager<DB>
• Plus 20+ other interfaces and services

2. Database-Specific Type Safety

// PostgreSQL example
interface IPostgresDB extends ITransactionalDB {
  query<T>(sql: string, params?: any[]): Promise<T[]>;
  copy(sql: string): Promise<void>;
}

// Full autocomplete in migrations
const migration: IRunnableScript<IPostgresDB> = {
  async up(db, info, handler) {
    await db.query('SELECT * FROM users');  // ✅ Autocomplete works!
    await db.copy('COPY users FROM STDIN'); // ✅ PostgreSQL-specific
  }
};

3. Enhanced Type Guards

Type guards now preserve specific database types:

const db: IPostgresDB = new PostgresDB(pool);

if (isImperativeTransactional(db)) {
  // db is now: IPostgresDB & ITransactionalDB
  // Has BOTH PostgreSQL methods AND transaction methods
  await db.beginTransaction();
  await db.query('SELECT * FROM users'); // ✅ No cast needed!
  await db.commit();
}

4. Compile-Time Validation

• TypeScript catches database method errors at compile time
• Eliminates need for as any type assertions
• Full IntelliSense support for database-specific operations

---

📝 Documentation

Migration Guide

• Created comprehensive v0.5-to-v0.6 migration guide (620 lines)
• Includes BEFORE/AFTER examples for all patterns
• Real-world PostgreSQL, MongoDB, and Firestore examples
• Step-by-step adoption guide
• Troubleshooting section and FAQ

API Documentation

• Updated all API reference docs with generic examples
• Added @template DB tags to 48 files with generics
• Fixed 14 JSDoc typos (<DB><IDB> → <IDB>)
• Enhanced JSDoc for all public interfaces

Navigation Improvements

• Reorganized version migration sidebar (v0.5→v0.6 at top, older under "Previous")
• Fixed "Extending MSR" sidebar navigation (all child pages now visible)
• Added "important" callout styling to Jekyll config (purple background)

---

🧪 Testing

• ✅ All 1127 tests passing
• ✅ 100% test coverage maintained
• ✅ Added ConfigLoader.load() branch coverage
• ✅ TypeScript compilation successful
• ✅ No regression in existing functionality

---

🎯 Benefits

For TypeScript Users

• Full IDE autocomplete for database-specific methods
• Compile-time type checking catches errors before runtime
• Self-documenting code - types show what's available
• Safe refactoring with full type safety
• No more as any casting needed

For JavaScript Users

• Simple constructor update (5-minute change)
• Better JSDoc autocomplete in VS Code
• Same runtime behavior
• No type annotations required

---

📊 Impact

Files Changed:

• Source code: 48 files with generic type parameters
• Tests: All updated, 100% coverage maintained
• Documentation: 25+ files updated with generic examples

Lines of Documentation:

• Migration guide: 620 lines
• JSDoc comments: 150+ enhanced/added
• API examples: 50+ code samples updated

---

🚀 Migration Path

Users can adopt generics incrementally:

1. Update constructor calls (required)
2. Define database interface (optional)
3. Type migrations one at a time (optional)
4. Adopt at your own pace

Default type parameter = IDB ensures interface implementations work without modification.

---

🔗 Related

• Migration guide: v0.5.x → v0.6.0
• API reference: Core Classes
• Database handler: IDatabaseMigrationHandler