TypeScript Type Migrations CLI

Common errors

• Error: Cannot find module 'typescript-migration' or its corresponding type declarations.

  cause The package is not installed or the TypeScript configuration does not correctly resolve modules.
  fix Ensure the package is installed: `npm install typescript-migration` or `yarn add typescript-migration`. For programmatic usage, ensure your `tsconfig.json` has `moduleResolution` set appropriately (e.g., `node`).

• TypeError: project.getSourceFile is not a function (or similar ts-morph error)

  cause Incorrect usage of `ts-morph` API within a migration, or `ts-morph` itself might be an incompatible version.
  fix Consult the `ts-morph` documentation for the correct API usage. Ensure `ts-morph` is installed as a dependency and its version is compatible with `typescript-migration` (though this package is a CLI, your migration files are TypeScript). The `Migration` class provides the `sourceFile` argument directly.

Warnings

• gotcha The project has not seen significant updates since July 2021. While functional for its stated purpose, compatibility with very recent TypeScript versions or new language features may not be guaranteed. Users should test thoroughly when integrating with newer TypeScript compilers.
  Fix: Review GitHub issues/PRs for community contributions addressing newer TypeScript versions. Consider contributing or forking if critical compatibility issues arise.
• gotcha This tool focuses solely on migrating TypeScript *types* via AST manipulation. It is not intended for initial JavaScript-to-TypeScript codebase conversion, for which other tools like Airbnb's `ts-migrate` or TypeStat exist.
  Fix: Understand the scope: use this for structured changes to *existing* TypeScript declarations. For JS-to-TS migration, explore tools like `ts-migrate` or TypeStat.
• gotcha Migrations can be destructive if not carefully crafted. The `up` and `down` methods should be idempotent and reversible, handling cases where the target types may or may not exist.
  Fix: Always test migrations on a separate branch or staging environment. Implement robust checks within your `up` and `down` logic (e.g., `if (node)` before attempting to modify). Ensure your codebase is under version control before running migrations.

Install

• npm install typescript-migration npm
• yarn add typescript-migration yarn
• pnpm add typescript-migration pnpm

Imports

• Migration
  wrong:

  const { Migration } = require('typescript-migration');

  correct:

  import { Migration } from 'typescript-migration';

  The primary class to extend when creating a new type migration. CommonJS `require` is not officially supported and may lead to issues.
• Migrator
  wrong:

  const { Migrator } = require('typescript-migration');

  correct:

  import { Migrator } from 'typescript-migration';

  The core class responsible for running defined migrations. Typically used internally by the CLI, but can be instantiated for programmatic execution.
• SourceFile

  import { SourceFile } from 'ts-morph';

  While not directly exported by `typescript-migration`, `SourceFile` from `ts-morph` is a critical type for interacting with the AST within your `Migration` classes. You will import this directly from `ts-morph`.

Quickstart

Demonstrates defining an `up` and `down` TypeScript type migration and applying it programmatically to a source file. Typically, this would be run via the CLI against a directory of migration files.

import { Migration } from 'typescript-migration';
import { SourceFile } from 'ts-morph';
import * as path from 'path';
import * as fs from 'fs';

// 1. Define your migration in a file, e.g., 'src/migrations/001-rename-user-interface.ts'
// This migration renames an interface from 'IUser' to 'User'.
class RenameUserInterface extends Migration {
  name = 'Rename IUser to User Interface';

  async up(sourceFile: SourceFile): Promise<void> {
    const oldInterface = sourceFile.getInterface('IUser');
    if (oldInterface) {
      oldInterface.rename('User');
      this.log(`Renamed IUser to User in ${sourceFile.getFilePath()}`);
    }
  }

  async down(sourceFile: SourceFile): Promise<void> {
    const newInterface = sourceFile.getInterface('User');
    if (newInterface) {
      newInterface.rename('IUser');
      this.log(`Renamed User back to IUser in ${sourceFile.getFilePath()}`);
    }
  }
}

// For demonstration, create a dummy TypeScript file to migrate.
const dummyFilePath = path.join(process.cwd(), 'temp-source.ts');
const dummyContent = `interface IUser { id: string; name: string; }\nconst user: IUser = { id: '1', name: 'Alice' };`;

// For CLI usage, you would place this migration file in a designated migrations directory.
// For programmatic usage (shown here for simplicity):
async function runMigrationProgrammatically() {
  // Ensure temp-source.ts exists for the demo
  fs.writeFileSync(dummyFilePath, dummyContent);
  console.log('Created temp-source.ts');

  // To run this via the CLI, you would save RenameUserInterface to a file
  // and execute: npx typescript-migration run --up path/to/migrations_folder

  // Programmatic execution example:
  const { Migrator } = await import('typescript-migration');
  const migrator = new Migrator();

  // Instantiate your migration
  const migrationInstance = new RenameUserInterface();

  // Apply the 'up' migration to the dummy file
  console.log('\n--- Running UP migration ---');
  await migrator.run([migrationInstance], [dummyFilePath], 'up');
  console.log('Migration UP finished.');

  // Verify changes (read the file content after migration)
  const updatedContent = fs.readFileSync(dummyFilePath, 'utf8');
  console.log('\nUpdated temp-source.ts content:\n', updatedContent);

  // Revert the 'down' migration
  console.log('\n--- Running DOWN migration ---');
  await migrator.run([migrationInstance], [dummyFilePath], 'down');
  console.log('Migration DOWN finished.');

  const revertedContent = fs.readFileSync(dummyFilePath, 'utf8');
  console.log('\nReverted temp-source.ts content:\n', revertedContent);

  // Clean up
  fs.unlinkSync(dummyFilePath);
  console.log('\nCleaned up temp-source.ts');
}

runMigrationProgrammatically().catch(console.error);