as في TypeScript: تأكيد الأنواع (Type Assertion) والتحويل

value as Type تأكيد نوع (type assertion): يخبر TypeScript أن تعامل value على أنها Type. يسميه الناس تحويلًا (cast)، لكنه مجرد تعليمة للمترجم. يُحذف من ناتج JavaScript، ولا يحوّل شيئًا ولا يفحص شيئًا وقت التشغيل.

interface Config {
  port: number;
  host: string;
}

const text = '{"port": 8080, "host": "localhost"}';

// JSON.parse returns any; the assertion gives the result a useful type
const config = JSON.parse(text) as Config;

console.log(config.port + 1);            // 8081
console.log(config.host.toUpperCase());  // LOCALHOST

هذا هو الاستخدام المعتاد: تعرف عن قيمة ما أكثر مما يستطيع المترجم معرفته (هنا شكل بيانات JSON)، فتصرّح بذلك. إن كنت مخطئًا فلن ينبهك شيء. تبيّن الأقسام التالية ما يعنيه ذلك، ومتى يكون الفحص وقت التشغيل الخيار الأفضل.

as وصيغة الأقواس الزاوية

للتأكيد نفسه كتابتان:

const someValue: unknown = "hello";
const a = someValue as string;   // as syntax
const b = <string>someValue;     // angle-bracket syntax, same meaning

صيغة الأقواس الزاوية غير مسموحة في ملفات .tsx، حيث تُقرأ <string> على أنها وسم JSX. استخدم as في كل مكان ولن تواجه هذا السؤال. التأكيدات ضعيفة الارتباط، فضعها بين قوسين حين تكمل التعبير بعدها: (value as string).length.

التأكيدات لا تحوّل القيم

هذا الجزء هو ما يسبب أخطاء حقيقية. التأكيد يغيّر ما يعتقده المترجم عن القيمة، لا القيمة نفسها:

const input: unknown = "42";

const asserted = input as number;  // compiles: unknown can be asserted to anything
const converted = Number(input);   // an actual conversion

console.log(asserted + 1);   // 421 (string concatenation: it is still "42")
console.log(converted + 1);  // 43
console.log(typeof asserted, typeof converted); // string number

يعتقد المترجم أن asserted من نوع number، فيمر asserted + 1 في فحص الأنواع على أنه عملية حسابية. لكنها وقت التشغيل لا تزال النص "42"، فتدمج JavaScript النصين. لتغيير نوع قيمة حوّلها: Number(x)، وString(x)، وBoolean(x)، وBigInt(x)، وnew Date(x). تقارن صفحة تحويل النص إلى رقم بين دوال التحويل.

ما يسمح به المترجم

as ليست بلا حدود. تسمح TypeScript بـ x as T حين يكون أحد النوعين قابلًا للإسناد إلى الآخر: التوسيع ("a" as string، dog as Animal) والتضييق (animal as Dog، unknown as User) كلاهما مقبول. وحين لا يتداخل النوعان إطلاقًا ترفض:

// This does not compile: string and number do not overlap.
const input = "42";
const n = input as number;

console.log(n);

يبلّغ المترجم index.ts(3,11): error TS2352: Conversion of type 'string' to type 'number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first. الرسالة نفسها تذكر المخرج: input as unknown as number. هذا التأكيد المزدوج يُترجم بنجاح، وهو خاطئ وقت التشغيل تمامًا مثل المثال السابق. حين تشعر أنك تحتاجه، فالحل الصحيح عادة تحويل (Number(input)) أو نوع مختلف.

قاعدة التداخل متساهلة مع الكائنات. كائن literal يحتوي بعض الخصائص يُقبل، وهكذا تمرّر as الكائنات الناقصة بصمت:

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

const draft = { name: "Ada" } as User; // compiles: email is missing
const empty = {} as User;              // compiles too

console.log(draft.name);               // Ada
console.log(typeof draft.email);       // undefined, although the type says string
console.log(empty.name?.length);       // undefined

توصيف النوع (const draft: User = { name: "Ada" }) أو satisfies User كان سيبلّغ عن email الناقصة (TS2741). استخدم as على كائن literal فقط حين تنوي فعلًا إكماله لاحقًا، وفضّل بناء الكائن كاملًا.

as const شيء مختلف

تبدو as const تأكيدًا، لكنها تفعل عكس التوسيع: تجعل القيمة الحرفية أضيق ما يمكن. تبقى النصوص أنواعًا حرفية، وتصبح المصفوفات tuples للقراءة فقط، وتصبح خصائص الكائنات readonly.

const sizes = ["small", "medium", "large"] as const;
type Size = (typeof sizes)[number]; // "small" | "medium" | "large"

const point = { x: 1, y: 2 } as const; // { readonly x: 1; readonly y: 2 }

function isSize(value: string): value is Size {
  return (sizes as readonly string[]).includes(value);
}

console.log(isSize("medium"), isSize("huge")); // true false
console.log(point.x + point.y);                // 3

إنها آمنة، لأنها تصف القيمة الحرفية بدقة بدل أن تدّعي شيئًا لا يراه المترجم. (التأكيد sizes as readonly string[] داخل isSize تأكيد توسيع، وهو آمن أيضًا: يسمح لـ includes بقبول أي نص.) راجع الأنواع الحرفية للمزيد.

متى يكون الـ Type Guard الأداة الأفضل

as ادعاء، والـ type guard فحص. عند حدود البرنامج حيث تأتي البيانات من خارج الكود (JSON، وfetch، وlocalStorage، ومدخلات المستخدم، والرسائل)، قد يكون الادعاء خاطئًا، والتأكيد يحوّل خطأً واضحًا عند الحدود إلى خطأ محيّر في موضع آخر.

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

function isPoint(v: unknown): v is Point {
  return typeof v === "object" && v !== null &&
    "x" in v && typeof v.x === "number" &&
    "y" in v && typeof v.y === "number";
}

const raw: unknown = JSON.parse('{"x": 3, "y": "4"}');

// With as: compiles, and the bug surfaces later
const p1 = raw as Point;
console.log(p1.x + p1.y); // 34 (a string snuck in)

// With a guard: the bad data is caught where it enters
if (isPoint(raw)) console.log(raw.x + raw.y);
else console.log("invalid point");

دليل تقريبي للأدوات المتشابهة:

يبقى استخدامان جيدان لـ as: تضييق شيء لا يستطيع المترجم تتبعه (عنصر في Map أضفته قبل سطرين، أو قيمة من مكتبة بلا أنواع)، وكود الاختبارات الذي يبني بيانات تجريبية جزئية. اجعلها صغيرة وقريبة من الموضع الذي تعرف فيه أن الادعاء صحيح.