أفضل ممارسات TypeScript: 8 قواعد بأمثلة قبل وبعد

القواعد التالية هي التي تمنع أكبر عدد من الأخطاء في كود TypeScript الحقيقي. كل واحدة تعرض النسخة الشائعة أولًا ثم النسخة الأفضل، في كود يمكنك تشغيله. القاعدة الأولى هي الأهم: توقّف عن استخدام any.

استخدم unknown بدلًا من any

يعطّل any فحص الأنواع للقيمة ولكل ما يُحسب منها. أما unknown فيقبل أيضًا أي قيمة، لكن عليك فحصها قبل استخدامها، وهذا يضع الفحص حيث تدخل البيانات إلى برنامجك:

// Before: any switches off checking for everything it touches.
function totalAny(items: any): number {
  return items.reduce((sum: number, item: any) => sum + item.price, 0);
}
console.log(totalAny([{ price: 2 }, { cost: 3 }])); // NaN, no error anywhere

// After: take unknown, check once at the boundary, then work with real types.
interface Item {
  price: number;
}

function isItems(value: unknown): value is Item[] {
  return Array.isArray(value) && value.every((i) => typeof i?.price === "number");
}

function total(input: unknown): number {
  if (!isItems(input)) throw new Error("Expected a list of items with prices");
  return input.reduce((sum, item) => sum + item.price, 0);
}

console.log(total([{ price: 2 }, { price: 3 }])); // 5
try {
  total([{ price: 2 }, { cost: 3 }]);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Expected a list of items with prices
}

الحدود هي الأماكن التي تتوقف فيها الأنواع عن كونها مضمونة: JSON.parse، واستجابات fetch، وlocalStorage، ومدخلات النماذج، ومتغيرات البيئة، والرسائل القادمة من عمليات أخرى. تحقق هناك بـ type guard أو بمكتبة مخططات، ويستطيع بقية الكود الوثوق بأنواعه.

أبقِ strict مفعّلًا

strict هو الإعداد الافتراضي في TypeScript 7؛ لا توقفه. وأضف الفحوص التي يتركها والتي تكتشف أكثر الأخطاء:

{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noImplicitOverride": true,
        "noFallthroughCasesInSwitch": true
    }
}

يجعل noUncheckedIndexedAccess نوع arr[i] وrecord[key] يتضمن undefined، وهو ما تعيده فعلًا عند فهرس غير موجود. ويجعل noImplicitOverride دالة الصنف الفرعي تصرّح بـ override، ويرفض noFallthroughCasesInSwitch أي case يمتد تنفيذه إلى الذي يليه.

دع الاستنتاج يعمل

حدد ما لا يستطيع TypeScript معرفته: معاملات الدوال، وأنواع الإعادة للدوال التي تستخدمها وحدات أخرى. واترك المتغيرات المحلية ومعاملات دوال الاستدعاء للاستنتاج. تحديد النوع غير الضروري ليس مجرد ضجيج؛ فقد يجعل النوع أوسع من القيمة:

type Status = "active" | "banned";

function setStatus(status: Status): string {
  return `status set to ${status}`;
}

const annotated: string = "active"; // annotation widens the type to string
// @ts-expect-error string is not assignable to Status
setStatus(annotated);

const inferred = "active"; // inferred as the literal type "active"
console.log(setStatus(inferred)); // status set to active

const users = [{ id: 1, name: "Ada" }, { id: 2, name: "Lin" }];
const ids = users.map((u) => u.id); // inferred: number[]
console.log(ids); // [ 1, 2 ]

دون التعليق @ts-expect-error يكون setStatus(annotated) الخطأ TS2345. أما الـ const المستنتج فيحتفظ بالنوع الحرفي "active"، فيُقبل. مرّر المؤشر فوق متغير في محررك لترى ما استُنتج قبل أن تضيف نوعًا.

فضّل أنواع Union على Enum

الـ union من نصوص حرفية يعطي الإكمال التلقائي والفحص الشامل دون أي كود مولَّد. وعندما تحتاج أيضًا إلى قائمة القيم وقت التشغيل، اشتق النوع من مصفوفة as const:

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function canEdit(role: Role): boolean {
  return role !== "viewer";
}

console.log(canEdit("editor"));     // true
console.log(ROLES.filter(canEdit)); // [ 'admin', 'editor' ]

canEdit("owner"); // error TS2345: Argument of type '"owner"' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

يُترجم enum Role { Admin, Viewer } إلى كائن فيه ربط عكسي، والمعامل من نوع enum رقمي يقبل أي متغير number، حتى لو كانت قيمته غير مذكورة في الـ enum. ولا تعمل الـ enums أيضًا مع حذف الأنواع في Node (TypeScript enum is not supported in strip-only mode). المقارنة بين الخيارين موجودة في صفحة الـ enums.

افحص كائنات الإعدادات بـ satisfies

تحديد نوع كائن بنوع واسع مثل Record<string, Route> يفحص قيمه لكنه ينسى مفاتيحه. أما satisfies فيفحص الشيء نفسه ويحتفظ بالنوع الدقيق:

interface Route {
  path: string;
  auth: boolean;
}

// Annotated: every string key is allowed, so typos are not caught.
const loose: Record<string, Route> = {
  home: { path: "/", auth: false },
};
console.log(loose.hmoe); // undefined, and no compile error

// satisfies: checked against Route, but the exact keys are kept.
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;

console.log(routes.admin.path); // /admin
// @ts-expect-error Property 'hmoe' does not exist
routes.hmoe;

استخدم تحديد النوع عندما يجب أن يكون للمتغير النوع المصرّح به بالضبط (معامل دالة، قيمة ستعيد إسنادها). واستخدم satisfies لجداول البحث، وخرائط المسارات، ورموز السمات (theme tokens)، والكائنات الثابتة الأخرى.

صمّم الحالة بـ Discriminated Unions

الكائن الواحد ذو الحقول الاختيارية يسمح بحالات لا يمكن أن تحدث: loading: true مع error معًا، أو غياب data بعد النجاح. أما union من كائنات تشترك في وسم واحد فلا يسمح إلا بالحالات الحقيقية، ولا يرى كل فرع إلا حقوله:

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; message: string };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", "); // data exists only here
    case "error":
      return `Error: ${state.message}`;
    default: {
      const unreachable: never = state; // fails if a case is missing
      return unreachable;
    }
  }
}

console.log(render({ status: "success", data: ["a", "b"] })); // a, b
console.log(render({ status: "error", message: "timeout" }));  // Error: timeout

سطر never هو الفحص الشامل. عندما يضيف أحدهم حالة وينسى معالجتها، يفشل البناء عند ذلك السطر:

// This does not compile: a new state was added but not handled.
type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "cancelled" };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", ");
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
}

console.log(render({ status: "loading" }));

الخطأ هو index.ts(14,13): error TS2322: Type '{ status: "cancelled"; }' is not assignable to type 'never'. وهو يسمّي الحالة غير المعالجة. أضف case "cancelled": فيُترجم الكود.

تجنب ! وas

تأكيد عدم القيمة الفارغة x! وتأكيد النوع x as T يطلبان من المترجم التوقف عن الفحص. لا يغيّر أي منهما القيمة وقت التشغيل، لذلك يصبح التأكيد الخاطئ انهيارًا لاحقًا، بعيدًا عن سببه:

interface User {
  name: string;
}

const users = new Map<string, User>([["ada", { name: "Ada" }]]);

// Before: ! and as silence the compiler, and the crash moves to run time.
try {
  console.log(users.get("bob")!.name);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Cannot read properties of undefined (reading 'name')
}
const fake = {} as User;
console.log(fake.name); // undefined, typed as string

// After: handle the missing case where it can happen.
const bob = users.get("bob");
console.log(bob?.name ?? "unknown user"); // unknown user

استبدل ! بـ ?. أو ?? أو return مبكر أو خطأ مرمي برسالة مفيدة. واستبدل as بـ type guard يختبر القيمة فعلًا. التأكيد الوحيد الآمن دائمًا هو as const، لأنه يجعل النوع أضيق وللقراءة فقط لا أكثر. وإعداد جيد لأداة الفحص (القاعدتان no-non-null-assertion وno-explicit-any في typescript-eslint) ينبّه إلى البقية.

اجعل البيانات readonly

ميّز الخصائص والمصفوفات بـ readonly عندما لا ينبغي للكود تغييرها. عندها يرفض المترجم push وsort والإسناد، وتعيد الدوال قيمًا جديدة بدلًا من تعديل مدخلاتها:

interface Settings {
  readonly theme: "light" | "dark";
  readonly tags: readonly string[];
}

function withTag(settings: Settings, tag: string): Settings {
  // settings.tags.push(tag) would not compile
  return { ...settings, tags: [...settings.tags, tag] };
}

const before: Settings = { theme: "dark", tags: ["a"] };
const after = withTag(before, "b");
console.log(before.tags, after.tags); // [ 'a' ] [ 'a', 'b' ]

// @ts-expect-error Cannot assign to 'theme' because it is a read-only property.
before.theme = "light";

يُفحص readonly وقت الترجمة فقط وعلى مستوى واحد فقط: لا يجمّد الكائن وقت التشغيل. ومع ذلك يكفي هذا لاكتشاف التعديل غير المقصود للحالة المشتركة، وهو سبب معظم هذه الأخطاء.