الأنواع الحرفية و as const في TypeScript مع أمثلة

النوع الحرفي نوع له قيمة واحدة بالضبط: "up" نوع عضوه الوحيد هو النص "up"، و404 نوع عضوه الوحيد هو الرقم 404. وحدها ليست مفيدة كثيرًا. لكن عند جمعها في union تعطيك متغيرًا يقبل مجموعة ثابتة من القيم ولا شيء غيرها.

type Direction = "up" | "down" | "left" | "right";

function move(dir: Direction, steps: number) {
  console.log(`moving ${dir} by ${steps}`);
}

move("up", 3);
move("left", 1);

// @ts-expect-error: Argument of type '"north"' is not assignable to parameter of type 'Direction'.
move("north", 1);

دون تعليق @ts-expect-error يكون الاستدعاء الأخير خطأ وقت الترجمة (TS2345). ومعه يُترجم البرنامج ويعمل الاستدعاء ويطبع moving north by 1: الأنواع الحرفية موجودة للمترجم فقط، ووقت التشغيل تكون القيمة نصًا عاديًا.

القيم الحرفية النصية والرقمية والمنطقية

يمكن كتابة أي قيمة نصية أو رقمية أو bigint أو منطقية كنوع. عندها لا يقبل المترجم إلا تلك القيمة بالضبط.

let method: "GET" = "GET";
let code: 404 = 404;
let ok: true = true;
let big: 10n = 10n;

type Port = 80 | 443 | 8080;
const port: Port = 443;

boolean نفسه مجرد union هو true | false، ولهذا يترك تضييق boolean بـ if (flag) القيمة false في فرع else.

Union من القيم الحرفية

الاستخدام الشائع هو union يسرد كل القيم المسموحة. داخل الدالة يضيّق المترجم الـ union كلما فحصته، فيعرف كل فرع القيمة التي لديه بالضبط.

type Size = "sm" | "md" | "lg";

function padding(size: Size): number {
  if (size === "sm") return 4;
  if (size === "md") return 8;
  return 16; // size is "lg" here
}

const sizes: Size[] = ["sm", "md", "lg"];
console.log(sizes.map(padding)); // [ 4, 8, 16 ]

الـ union من النصوص الحرفية هو البديل المعتاد في TypeScript عن enum. لا يكلف شيئًا وقت التشغيل، والقيم نصوص عادية يمكنك تسجيلها وإرسالها عبر JSON، والخطأ الإملائي خطأ ترجمة. المزيد عن الموازنة بينهما في enums.

التوسيع: let مقابل const

عندما تستنتج TypeScript نوعًا من قيمة حرفية، تنظر في ما إذا كانت القيمة قابلة للتغيير. لا يمكن أبدًا إعادة إسناد متغير const، لذلك يحتفظ بالنوع الحرفي. أما متغير let فيمكن، لذلك يُوسَّع نوعه إلى النوع العام.

const a = "hello"; // type: "hello"
let b = "hello";   // type: string
b = "bye";         // fine, b is a string

const n = 42;      // type: 42
let m = 42;        // type: number

let c = a;         // type: string (copying a literal into a let widens it)

console.log(a, b, n, m, c); // hello bye 42 42 hello

مرّر المؤشر فوق كل اسم في المحرر لترى النوع المستنتج. إذا أردت let لا يحمل إلا قيمًا محددة، فحدد نوعه: let mode: "light" | "dark" = "light".

لماذا تتوسع خصائص الكائنات

خصائص الكائن الحرفي قابلة للتغيير، لذلك تتوسع هي أيضًا، حتى عندما يُخزَّن الكائن في const. هذه أكثر طريقة شائعة لمصادفة الأنواع الحرفية دون قصد:

// This does not compile: req.method is string, not "GET" | "POST"
function send(url: string, method: "GET" | "POST") {
  console.log(method, url);
}

const req = { url: "/users", method: "GET" };
send(req.url, req.method);

يبلّغ المترجم:

index.ts(7,15): error TS2345: Argument of type 'string' is not assignable to parameter of type '"GET" | "POST"'.

يُستنتج req على أنه { url: string; method: string } لأن كودًا لاحقًا قد يشغّل req.method = "DELETE". هناك ثلاثة حلول:

type Method = "GET" | "POST";

function send(url: string, method: Method) {
  console.log(method, url);
}

// 1. Annotate the object (or the property)
const r1: { url: string; method: Method } = { url: "/users", method: "GET" };

// 2. as const on the whole object: every property becomes readonly and literal
const r2 = { url: "/posts", method: "POST" } as const;

// 3. as const on one property only
const r3 = { url: "/tags", method: "GET" as const };

send(r1.url, r1.method);
send(r2.url, r2.method);
send(r3.url, r3.method);

وخيار رابع هو satisfies، الذي يفحص الكائن مقابل نوع مع الحفاظ على الأنواع الحرفية لخصائصه.

as const

as const تأكيد const. ضعه بعد تعبير فيستنتج المترجم أضيق نوع يستطيعه:

• تحتفظ القيم النصية والرقمية والمنطقية بأنواعها الحرفية
• تصبح خصائص الكائن readonly
• تصبح المصفوفات الحرفية tuples readonly بطول ثابت

const config = {
  env: "production",
  retries: 3,
  hosts: ["a.example.com", "b.example.com"],
} as const;
// type: { readonly env: "production"; readonly retries: 3;
//         readonly hosts: readonly ["a.example.com", "b.example.com"] }

// @ts-expect-error: Cannot assign to 'env' because it is a read-only property.
config.env = "staging";

const point = [3, 4] as const; // type: readonly [3, 4]
const [x, y] = point;
console.log(config.retries, x + y); // 3 7

التأكيد وقت الترجمة فقط. كود JavaScript الناتج هو الكائن الحرفي نفسه بعد حذف as const، فلا شيء يمنع كودًا آخر من تعديله وقت التشغيل. إذا احتجت إلى ضمان وقت التشغيل، فاستدعِ Object.freeze أيضًا.

Union type من مصفوفة as const

نمط شائع هو الاحتفاظ بالقيم المسموحة في مصفوفة واحدة يمكنك التكرار عليها وقت التشغيل، واشتقاق الـ union منها. يعني (typeof arr)[number] «نوع أي عنصر من arr».

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

function isRole(value: string): value is Role {
  return (ROLES as readonly string[]).includes(value);
}

for (const input of ["editor", "owner"]) {
  console.log(input, isRole(input)); // editor true, then owner false
}

دون as const يكون ROLES من نوع string[] ويكون Role مجرد string. التحويل إلى readonly string[] في isRole لازم لأن includes على tuple من القيم الحرفية لا يقبل إلا تلك القيم، والغرض من الدالة هو اختبار نص قد لا يكون منها. والنمط نفسه مع الكائنات يعمل لخرائط المفاتيح والقيم: const Status = { Active: "active", Banned: "banned" } as const، ثم type Status = (typeof Status)[keyof typeof Status].

معاملات النوع const

الدالة العامة (generic) توسّع عادة القيم الحرفية التي تمررها إليها. منذ TypeScript 5.0 يمكنك تعليم معامل نوع بـ const، فيستنتج المترجم الوسيط كما لو كان عليه as const، دون أن يُطلب من المستدعي كتابته.

function plain<T>(value: T) {
  return value;
}

function exact<const T>(value: T) {
  return value;
}

const a = plain({ kind: "circle", sizes: [1, 2] });
// type: { kind: string; sizes: number[] }

const b = exact({ kind: "circle", sizes: [1, 2] });
// type: { readonly kind: "circle"; readonly sizes: readonly [1, 2] }

console.log(a.kind === b.kind); // true

هذه في الغالب أداة لمؤلفي المكتبات: تستخدمها تعريفات المسارات وأدوات البناء ومساعدات المخططات حتى يحصل المستدعون على أنواع دقيقة من قيم حرفية عادية.

معاني const

تظهر الكلمة const في أربعة أماكن مختلفة في كود TypeScript:

لا يجمد أي منها كائنًا وقت التشغيل. const obj = { a: 1 } ما زال يسمح بـ obj.a = 2؛ الخطأ فقط هو إعادة إسناد obj نفسه.