TypeScript: ترحيل مشروع TypeScript JS إلى TS

1. Initialization tsconfig.json（Relaxed Mode）
2. Install @types packages
3. Open allowJs——TS and JS Coexistence
4. File by file .js → .ts（Starting with the leaf file）
5. Gradually Enable Strict Options
6. Finally Unlocked strict

tsc --init

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "allowJs": true,
    "checkJs": false,
    "noImplicitAny": false,
    "strict": false,
    "outDir": "./dist",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

# Install the type declarations required by the project
npm install @types/node @types/express @types/lodash --save-dev

{
  "compilerOptions": {
    "allowJs": true
  }
}

// main.ts —— Can be imported .js Documents
import { helper } from "./utils";  // utils.js Just being there is enough

// utils.js —— JS Documents，Untyped Annotations
function helper(value) {
  return value.toString();
}

{
  "compilerOptions": {
    "checkJs": true
  }
}

Recommended Migration Order：
1. Constants File（config.js → config.ts）
2. Utility Functions（utils.js → utils.ts）
3. Type Definitions（types.js → types.ts）
4. Data Model（models.js → models.ts）
5. Service Layer（services.js → services.ts）
6. Controller/Routing（controllers.js → controllers.ts）
7. Input File（index.js → index.ts）

// ── Before the Migration：utils.js ──
function formatPrice(price, currency) {
  return currency + price.toFixed(2);
}

function clamp(value, min, max) {
  return Math.min(Math.max(value, min), max);
}

// ── After the migration：utils.ts ──
function formatPrice(price: number, currency: string = "¥"): string {
  return currency + price.toFixed(2);
}

function clamp(value: number, min: number, max: number): number {
  return Math.min(Math.max(value, min), max);
}

// Step 1：Add a type annotation，Uncertain usage any
function process(data: any, options: any): any {
  return data.filter(item => item.active);
}

// Step 2：Gradual Replacement any For a specific type
interface DataItem {
  id: number;
  name: string;
  active: boolean;
}

interface Options {
  limit?: number;
  sort?: "asc" | "desc";
}

function process(data: DataItem[], options: Options = {}): DataItem[] {
  let result = data.filter(item => item.active);
  if (options.sort === "desc") result.reverse();
  if (options.limit) result = result.slice(0, options.limit);
  return result;
}

// ── Before the Migration：users.js ──
const express = require("express");
const router = express.Router();

router.get("/", async (req, res) => {
  const users = await User.findAll();
  res.json(users);
});

router.post("/", async (req, res) => {
  const { name, email } = req.body;
  const user = await User.create({ name, email });
  res.status(201).json(user);
});

module.exports = router;

// API endpoint response (status 200)
// Returns JSON data

// ── After the migration：users.ts ──
import { Router, Request, Response } from "express";

const router = Router();

interface CreateUserBody {
  name: string;
  email: string;
}

router.get("/", async (_req: Request, res: Response) => {
  const users = await User.findAll();
  res.json(users);
});

router.post("/", async (req: Request<{}, {}, CreateUserBody>, res: Response) => {
  const { name, email } = req.body;
  const user = await User.create({ name, email });
  res.status(201).json(user);
});

export default router;

// utils.js — Use JSDoc to add types
/**
 * Pricing Format
 * @param {number} price - Price
 * @param {string} [currency="¥"] - Currency Symbol
 * @returns {string} Formatted Price
 */
function formatPrice(price, currency = "¥") {
  return currency + price.toFixed(2);
}

/**
 * @typedef {Object} User
 * @property {number} id
 * @property {string} name
 * @property {string} email
 */

/**
 * Search for a User
 * @param {number} id
 * @returns {Promise<User>}
 */
async function findUser(id) {
  // ...
}

module.exports = { formatPrice, findUser };

// main.ts
import { findUser } from "./utils";  // utils.js has JSDoc types

let user = await findUser(1);  // ✅ Type inference is correct（From JSDoc）

// A large number of implicit variables after migration any——Don't rush to start it noImplicitAny
function process(data) {  // data Implicit any
  return data.map(item => item.name);  // item Me too any
}

// JS For use with documents module.exports
module.exports = function() { /* ... */ };

// TS Import Requirements esModuleInterop
import fn from "./legacy";  // Required esModuleInterop: true

import untypedLib from "untyped-lib";  // ❌ Cannot find the declaration file

// Temporary solution——Create shim.d.ts
declare module "untyped-lib" {
  const lib: any;
  export default lib;
}

// JS in this Dynamic Binding
const obj = {
  name: "Charlie",
  greet() {
    console.log(this.name);  // ✅ JS in OK
  }
};

// TS in this Needs annotation
const obj2 = {
  name: "Charlie",
  greet(this: { name: string }) {
    console.log(this.name);  // ✅ TS Needed in this Parameters
  }
};

// ── Before: shapes.js ──
const shapes = [
  { type: "circle", radius: 5 },
  { type: "rectangle", width: 10, height: 20 },
  { type: "circle", radius: 3 }
];

function totalArea(shapes) {
  return shapes.reduce((sum, s) => {
    if (s.type === "circle") return sum + Math.PI * s.radius * s.radius;
    return sum + s.width * s.height;
  }, 0);
}

// Executed successfully

// ── After: shapes.ts ──
interface Circle { type: "circle"; radius: number; }
interface Rectangle { type: "rectangle"; width: number; height: number; }
type Shape = Circle | Rectangle;

const shapes: Shape[] = [
  { type: "circle", radius: 5 },
  { type: "rectangle", width: 10, height: 20 },
  { type: "circle", radius: 3 }
];

function totalArea(shapes: Shape[]): number {
  return shapes.reduce((sum, s) => {
    if (s.type === "circle") return sum + Math.PI * s.radius * s.radius;
    return sum + s.width * s.height;
  }, 0);
}

// ── Before: math.js (JSDoc-typed) ──
/**
 * @template T
 * @param {T[]} arr
 * @param {(item: T) => boolean} predicate
 * @returns {T[]}
 */
function filter(arr, predicate) {
  return arr.filter(predicate);
}

/**
 * @typedef {Object} Point
 * @property {number} x
 * @property {number} y
 */

/**
 * @param {Point} a
 * @param {Point} b
 * @returns {number}
 */
function distance(a, b) {
  return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2);
}

// Executed successfully

// ── After: math.ts (native TS types) ──
function filter<T>(arr: T[], predicate: (item: T) => boolean): T[] {
  return arr.filter(predicate);
}

interface Point {
  x: number;
  y: number;
}

function distance(a: Point, b: Point): number {
  return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2);
}