{"id":16919,"library":"typescript-migration","title":"TypeScript Type Migrations CLI","description":"This package is a command-line interface (CLI) tool designed to help developers manage migrations of TypeScript type definitions within a project. It leverages the `ts-morph` library to programmatically analyze and modify TypeScript Abstract Syntax Trees (ASTs), enabling structured, versioned changes to existing type declarations across a codebase. Unlike broader migration tools that convert JavaScript to TypeScript, this tool focuses specifically on evolving existing TypeScript types. The current stable version is 1.1.1. The project's development appears to be in maintenance mode, with no significant updates since 2021, suggesting a stable but not actively evolving codebase. Its key differentiator is its focus on managing discrete 'up' and 'down' type migrations.","status":"maintenance","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/saleae/typescript-migration","tags":["javascript","typescript"],"install":[{"cmd":"npm install typescript-migration","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-migration","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-migration","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for building the command-line interface (CLI).","package":"commander"},{"reason":"Used for matching file paths to locate migration files and source code.","package":"glob"},{"reason":"Core dependency for programmatic manipulation of TypeScript Abstract Syntax Trees (ASTs), which is fundamental to how migrations are applied.","package":"ts-morph"}],"imports":[{"note":"The primary class to extend when creating a new type migration. CommonJS `require` is not officially supported and may lead to issues.","wrong":"const { Migration } = require('typescript-migration');","symbol":"Migration","correct":"import { Migration } from 'typescript-migration';"},{"note":"The core class responsible for running defined migrations. Typically used internally by the CLI, but can be instantiated for programmatic execution.","wrong":"const { Migrator } = require('typescript-migration');","symbol":"Migrator","correct":"import { Migrator } from 'typescript-migration';"},{"note":"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`.","symbol":"SourceFile","correct":"import { SourceFile } from 'ts-morph';"}],"quickstart":{"code":"import { Migration } from 'typescript-migration';\nimport { SourceFile } from 'ts-morph';\nimport * as path from 'path';\nimport * as fs from 'fs';\n\n// 1. Define your migration in a file, e.g., 'src/migrations/001-rename-user-interface.ts'\n// This migration renames an interface from 'IUser' to 'User'.\nclass RenameUserInterface extends Migration {\n  name = 'Rename IUser to User Interface';\n\n  async up(sourceFile: SourceFile): Promise<void> {\n    const oldInterface = sourceFile.getInterface('IUser');\n    if (oldInterface) {\n      oldInterface.rename('User');\n      this.log(`Renamed IUser to User in ${sourceFile.getFilePath()}`);\n    }\n  }\n\n  async down(sourceFile: SourceFile): Promise<void> {\n    const newInterface = sourceFile.getInterface('User');\n    if (newInterface) {\n      newInterface.rename('IUser');\n      this.log(`Renamed User back to IUser in ${sourceFile.getFilePath()}`);\n    }\n  }\n}\n\n// For demonstration, create a dummy TypeScript file to migrate.\nconst dummyFilePath = path.join(process.cwd(), 'temp-source.ts');\nconst dummyContent = `interface IUser { id: string; name: string; }\\nconst user: IUser = { id: '1', name: 'Alice' };`;\n\n// For CLI usage, you would place this migration file in a designated migrations directory.\n// For programmatic usage (shown here for simplicity):\nasync function runMigrationProgrammatically() {\n  // Ensure temp-source.ts exists for the demo\n  fs.writeFileSync(dummyFilePath, dummyContent);\n  console.log('Created temp-source.ts');\n\n  // To run this via the CLI, you would save RenameUserInterface to a file\n  // and execute: npx typescript-migration run --up path/to/migrations_folder\n\n  // Programmatic execution example:\n  const { Migrator } = await import('typescript-migration');\n  const migrator = new Migrator();\n\n  // Instantiate your migration\n  const migrationInstance = new RenameUserInterface();\n\n  // Apply the 'up' migration to the dummy file\n  console.log('\\n--- Running UP migration ---');\n  await migrator.run([migrationInstance], [dummyFilePath], 'up');\n  console.log('Migration UP finished.');\n\n  // Verify changes (read the file content after migration)\n  const updatedContent = fs.readFileSync(dummyFilePath, 'utf8');\n  console.log('\\nUpdated temp-source.ts content:\\n', updatedContent);\n\n  // Revert the 'down' migration\n  console.log('\\n--- Running DOWN migration ---');\n  await migrator.run([migrationInstance], [dummyFilePath], 'down');\n  console.log('Migration DOWN finished.');\n\n  const revertedContent = fs.readFileSync(dummyFilePath, 'utf8');\n  console.log('\\nReverted temp-source.ts content:\\n', revertedContent);\n\n  // Clean up\n  fs.unlinkSync(dummyFilePath);\n  console.log('\\nCleaned up temp-source.ts');\n}\n\nrunMigrationProgrammatically().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Review GitHub issues/PRs for community contributions addressing newer TypeScript versions. Consider contributing or forking if critical compatibility issues arise.","message":"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.","severity":"gotcha","affected_versions":">=1.1.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`).","cause":"The package is not installed or the TypeScript configuration does not correctly resolve modules.","error":"Error: Cannot find module 'typescript-migration' or its corresponding type declarations."},{"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.","cause":"Incorrect usage of `ts-morph` API within a migration, or `ts-morph` itself might be an incompatible version.","error":"TypeError: project.getSourceFile is not a function (or similar ts-morph error)"}],"ecosystem":"npm","meta_description":null}