Code migration strategy

Overview of Code Migration Strategy

Code migration is the process of transferring an existing codebase from one technology stack to another. For TypeScript developers, migration strategies need to consider differences in type systems, module systems, and toolchains. A successful migration requires balancing business needs, team capabilities, and technical debt.

Evaluating the Existing Codebase

Before starting the migration, conduct a comprehensive evaluation of the existing codebase:

// Example: Analyzing potential type issues in JavaScript code
function calculateTotal(items) {  // Parameter lacks type annotation
  return items.reduce((total, item) => {
    return total + item.price * item.quantity;  // Potential property access issues
  }, 0);
}

Key evaluation points include:

• Code size (number of files, lines of code)
• Dependencies (third-party libraries, internal modules)
• Test coverage
• Build toolchain configuration
• Potential type problem areas

Incremental Migration Strategy

Mixed-Mode Development

Allow .ts and .js files to coexist in the same project:

// tsconfig.json configuration
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

Implementation phases:

1. First, add type declaration files (.d.ts)
2. Gradually rename .js files to .ts
3. Finally, enable strict type checking

Module Wrapping Strategy

For modules that cannot be migrated immediately:

// legacy-module.d.ts
declare module 'legacy-module' {
  const value: any;
  export default value;
}

// Usage in new code
import legacy from 'legacy-module';

Automated Migration Tools

Use tools to accelerate the migration process:

# Use ts-migrate for automatic conversion
npx ts-migrate-full <project-path>

Common toolchains:

• JSDoc to TypeScript conversion
• Automatic type inference
• Code template conversion
• Test case migration

Type System Adaptation Strategy

Gradual Type Enhancement

Start with loose types and gradually tighten them:

// Phase 1: Basic types
interface Product {
  id: number;
  name: string;
}

// Phase 2: Add optional properties
interface EnhancedProduct extends Product {
  description?: string;
  variants?: Variant[];
}

// Phase 3: Strict types
type StrictProduct = {
  readonly id: number;
  name: string;
  price: number;
  inStock: boolean;
};

Third-Party Library Type Handling

Dealing with libraries without type definitions:

// Method 1: Use @types
npm install --save-dev @types/lodash

// Method 2: Custom declarations
declare module 'untyped-lib' {
  export function doSomething(config: {
    timeout?: number;
    retries?: number;
  }): Promise<ResultType>;
}

Build Tool Adaptation

Webpack Configuration Adjustment

// webpack.config.ts
import { Configuration } from 'webpack';

const config: Configuration = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
      {
        test: /\.js$/,
        enforce: 'pre',
        use: ['source-map-loader'],
      },
    ],
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.js'],
  },
};

Babel and TypeScript Integration

// .babelrc
{
  "presets": [
    "@babel/preset-env",
    "@babel/preset-typescript"
  ],
  "plugins": [
    "@babel/plugin-proposal-class-properties"
  ]
}

Test Strategy Adjustment

Test Code Migration

// Original Jasmine test
describe('Calculator', () => {
  it('should add two numbers', () => {
    expect(add(1, 2)).toBe(3);
  });
});

// Migrated to TypeScript + Jest
interface TestCase {
  a: number;
  b: number;
  expected: number;
}

describe('Calculator', () => {
  const testCases: TestCase[] = [
    { a: 1, b: 2, expected: 3 },
    { a: 0, b: 0, expected: 0 },
  ];

  test.each(testCases)('adds $a and $b', ({a, b, expected}) => {
    expect(add(a, b)).toBe(expected);
  });
});

Type Testing Tools

// Use dtslint for type testing
// $ExpectType number
const result = add(1, 2);

// $ExpectError
const error = add('1', 2);

Team Collaboration Strategy

Code Review Focus

During reviews, focus on:

• Whether type definitions are reasonable
• Whether the use of any is necessary
• Whether type guards are sufficient
• Whether generics are used appropriately

Knowledge Sharing Mechanisms

Create type definition documentation:

# Core Type Specifications

## Data Models
The `User` type must include:
- `id: string`
- `name: string`
- `email: string`

## API Responses
Use generic wrappers:
```typescript
type ApiResponse<T> = {
  data: T;
  error: null | {
    code: number;
    message: string;
  };
};

Performance Optimization Considerations

Incremental Compilation Configuration

// tsconfig.json
{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./build/.tsbuildinfo"
  }
}

Project Reference Optimization

Large projects can be split into multiple subprojects:

// tsconfig.json
{
  "references": [
    { "path": "./core" },
    { "path": "./ui" },
    { "path": "./services" }
  ]
}

Error Handling Strategy

Best Practices for Type Assertions

// Avoid direct use of 'as'
const element = document.getElementById('app');

// Correct approach
if (element instanceof HTMLElement) {
  element.style.display = 'none';
}

// Necessary type assertions should include comments
const data = JSON.parse(response) as UserData; // Known response format

Defensive Programming Patterns

function processInput(input: unknown) {
  if (typeof input === 'string') {
    return input.trim();
  }
  
  if (typeof input === 'number' && !isNaN(input)) {
    return input.toFixed(2);
  }
  
  throw new Error('Invalid input type');
}

Continuous Integration Adaptation

Type Checking Pipeline

# .github/workflows/typecheck.yml
name: TypeCheck
on: [push, pull_request]

jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
      - run: npm install
      - run: npx tsc --noEmit

Differentiated Build Configuration

// tsconfig.build.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

Documentation Strategy Update

Documenting Type Definitions

/**
 * Represents user account information
 * @property id - Unique user identifier
 * @property name - User display name
 * @property email - User contact email
 * @since v1.2.0
 */
interface User {
  id: string;
  name: string;
  email: string;
}

Maintaining Example Code

Create a type example repository:

// examples/advanced-types.ts
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

const partialConfig: DeepPartial<AppConfig> = {
  database: {
    host: 'localhost'
  }
};