typeof في TypeScript: Type Guards وعامل الأنواع typeof

لـ typeof معنيان في TypeScript. في التعبير هو عامل JavaScript: يُنفذ ويعيد نصًا مثل "string" أو "number"، وتضيّق TypeScript المتغير عندما تقارن ذلك النص. وفي موضع نوع هو استعلام نوع: typeof config يعطي النوع الثابت للمتغير config.

// 1. The runtime operator: a check that narrows
function double(value: string | number): string | number {
  if (typeof value === "string") {
    return value.repeat(2); // value: string
  }
  return value * 2;         // value: number
}
console.log(double("ab"), double(21)); // abab 42

// 2. The type query: reuse the type of an existing value
const defaults = { retries: 3, verbose: false };
type Options = typeof defaults; // { retries: number; verbose: boolean }

const custom: Options = { retries: 5, verbose: true };
console.log(typeof custom, custom); // object { retries: 5, verbose: true }

يُظهر السطر الأخير الفرق: typeof custom داخل console.log هو العامل وقت التشغيل ويطبع object، بينما typeof defaults بعد type Options = هو الاستعلام وقت الترجمة ولا يصل أبدًا إلى JavaScript.

المعنيان في لمحة

تميّز TypeScript بينهما بالموضع، فلا تعني الكلمة نفسها الاثنين في آن واحد.

نتائج typeof وقت التشغيل

يعيد العامل وقت التشغيل أحد ثمانية نصوص. شغّل هذا لترى ما تعطيه القيم الشائعة:

const samples: [string, unknown][] = [
  ['"hi"', "hi"],
  ["42", 42],
  ["NaN", NaN],
  ["10n", 10n],
  ["true", true],
  ["undefined", undefined],
  ["null", null],
  ["{}", {}],
  ["[]", []],
  ["new Date(0)", new Date(0)],
  ['new String("x")', new String("x")],
  ["() => 1", () => 1],
  ["class A {}", class A {}],
  ['Symbol("id")', Symbol("id")],
];

for (const [label, value] of samples) {
  console.log(label.padEnd(16), typeof value);
}

في JavaScript العادية يعيد typeof على متغير لم يُعلن قط القيمة "undefined" بدل رمي خطأ. أما في TypeScript فلا يُترجم هذا الكود: Cannot find name 'notDeclared'. (TS2304).

التضييق باستخدام typeof

مقارنة typeof في if أو switch أو تعبير ثلاثي أو بعد && تضيّق المتغير في كل فرع. إنها الطريقة المعيارية لمعالجة union من الأنواع البدائية، وأول فحص تلجأ إليه مع unknown.

function format(value: unknown): string {
  switch (typeof value) {
    case "string":
      return `"${value}"`;                 // value: string
    case "number":
    case "bigint":
      return value.toLocaleString("en-US"); // value: number | bigint
    case "boolean":
      return value ? "yes" : "no";         // value: boolean
    case "function":
      return `function ${value.name}()`;   // value: Function
    default:
      return String(value);
  }
}

console.log(format("hi"));          // "hi"
console.log(format(1234567.891));   // 1,234,567.891
console.log(format(2n ** 64n));     // 18,446,744,073,709,551,616
console.log(format(true));          // yes
console.log(format(Math.max));      // function max()
console.log(format(undefined));     // undefined

يضيّق typeof x !== "string" في الاتجاه الآخر، إلى كل شيء ما عدا string. ويعرف المترجم النصوص الثمانية الممكنة، فيكون الخطأ الإملائي في المقارنة خطأ ترجمة لا فحصًا يكون خاطئًا دائمًا بصمت:

// This does not compile: "strnig" is not a possible typeof result.
function kind(value: string | number): string {
  if (typeof value === "strnig") {
    return "text";
  }
  return "number";
}

console.log(kind("hey"));

يطبع المترجم index.ts(3,7): error TS2367: This comparison appears to be unintentional because the types '"bigint" | "boolean" | "function" | "number" | "object" | "string" | "symbol" | "undefined"' and '"strnig"' have no overlap. في JavaScript العادية كان الخطأ الإملائي سيرسل كل نص بهدوء إلى مسار number. صحح الإملاء فيطبع text.

فخ typeof null

لأن typeof null يساوي "object"، تضيّق TypeScript الفحص typeof x === "object" إلى object | null لا إلى object. أضف فحص null، وإلا تكون قراءة الخاصية خطأ (TS18047 'x' is possibly 'null'.).

function hasId(value: unknown): boolean {
  // typeof alone leaves value as object | null
  if (typeof value === "object" && value !== null) {
    // value: object
    return "id" in value;
  }
  return false;
}

console.log(hasId({ id: 7 }));  // true
console.log(hasId(null));       // false
console.log(hasId([1, 2]));     // false (arrays pass the typeof check but have no id)
console.log(hasId("id"));       // false

لا يستطيع typeof التمييز بين المصفوفات والتواريخ والخرائط والكائنات العادية: كلها "object". استخدم Array.isArray(x) للمصفوفات وx instanceof Date لنسخ الأصناف. ولا يستطيع typeof ولا غيره التحقق وقت التشغيل من أن قيمة تطابق interface، لأن الواجهات تُمحى؛ لذلك اكتب دالة type guard تفحص الخصائص.

typeof في مواضع الأنواع

في النوع، ينسخ typeof someVariable النوع الذي استنتجته TypeScript (أو أعلنته أنت) لذلك المتغير. يوفر عليك كتابة نوع يدويًا لقيمة موجودة أصلًا، ويبقي الاثنين متزامنين.

const theme = {
  primary: "#3178c6",
  spacing: 8,
  dark: false,
};

type Theme = typeof theme;
// { primary: string; spacing: number; dark: boolean }

function withSpacing(t: Theme, factor: number): Theme {
  return { ...t, spacing: t.spacing * factor };
}

console.log(withSpacing(theme, 2)); // { primary: '#3178c6', spacing: 16, dark: false }

let userName = "Ada";
const fixed = "Ada";
type A = typeof userName; // string
type B = typeof fixed;    // "Ada" (a const keeps its literal type)

يعتمد الناتج على طريقة تعريف المتغير: let أو خاصية الكائن يتوسعان (string وnumber)، والقيمة البدائية المعلنة بـ const تحتفظ بنوعها الحرفي. أضف as const إلى كائن أو مصفوفة فيعطي typeof أنواعًا حرفية للقراءة فقط حتى أعمق مستوى. ويقبل typeof أيضًا الوصول إلى الخصائص، فـ typeof theme.spacing هو number، لكنه لا يقبل تعبيرات عشوائية: type T = typeof getTheme(); خطأ صياغة (';' expected.، TS1005). وللنوع الذي يعيده استدعاء، استخدم ReturnType<typeof getTheme>.

keyof typeof: مفاتيح كائن كنوع

keyof typeof obj هو التركيب الأكثر شيوعًا. يحوّل typeof الكائن إلى نوع، ويأخذ keyof مفاتيحه، فتحصل على union من أسماء الخصائص يبقى صحيحًا كلما تغيّر الكائن.

const prices = { apple: 1.2, pear: 0.8, kiwi: 0.5 };

type Fruit = keyof typeof prices; // "apple" | "pear" | "kiwi"

function priceOf(fruit: Fruit, quantity: number): string {
  return (prices[fruit] * quantity).toFixed(2);
}

console.log(priceOf("pear", 3)); // 2.40

// @ts-expect-error: Argument of type '"mango"' is not assignable to parameter of type '"apple" | "kiwi" | "pear"'.
priceOf("mango", 1);

والحيلة نفسها على مصفوفة ثابتة تعطي union من قيمها: مع const roles = ["admin", "editor"] as const يكون النوع (typeof roles)[number] هو "admin" | "editor". ودون as const سيكون مجرد string. وتغطي صفحة keyof العامل keyof وحده.

ReturnType<typeof fn> وtypeof على الأصناف

تأخذ أنواع الأدوات مثل ReturnType وParameters نوع دالة. واسم الدالة قيمة، فمرّره عبر typeof أولًا:

function createUser(name: string, admin = false) {
  return { id: name.toLowerCase(), name, admin };
}

type User = ReturnType<typeof createUser>;
// { id: string; name: string; admin: boolean }
type CreateArgs = Parameters<typeof createUser>;
// [name: string, admin?: boolean | undefined]

const args: CreateArgs = ["Grace", true];
const user: User = createUser(...args);
console.log(user); // { id: 'grace', name: 'Grace', admin: true }

كتابة ReturnType<createUser> تفشل بـ 'createUser' refers to a value, but is being used as a type here. Did you mean 'typeof createUser'? (TS2749)، وهذا المترجم يطلب بالضبط ما سبق.

الأصناف هي الحالة الوحيدة التي يكون فيها الاسم قيمة ونوعًا معًا. User كنوع يعني نسخة من الصنف؛ وtypeof User يعني الصنف نفسه، أي المُنشئ، بما في ذلك أعضاؤه الثابتة:

class Point {
  static origin = new Point(0, 0);
  constructor(public x: number, public y: number) {}
}

const p: Point = new Point(1, 2);        // an instance
const Ctor: typeof Point = Point;        // the class (constructor + statics)
const q = new Ctor(3, 4);                // q: Point
type Instance = InstanceType<typeof Point>; // Point

typeof مقابل instanceof مقابل type guard

اختر أضيق أداة مناسبة. لنسخ الأصناف انظر instanceof؛ وللأشكال التي يصفها interface، تكون دالة type guard هي الفحص الوحيد المتاح وقت التشغيل.