Type Alias في TypeScript: الكلمة المفتاحية type مع أمثلة

يعطي type alias اسمًا لنوع. تكتب type Name = ...، ومن ثم يمكن استخدام Name في أي مكان يُتوقع فيه نوع. وعلى خلاف interface، يستطيع الاسم المستعار تسمية أي نوع على الإطلاق، لا أشكال الكائنات فقط.

type UserId = string;                         // a primitive
type Point = { x: number; y: number };        // an object shape
type Status = "active" | "banned";            // a union of literals
type Pair = [string, number];                 // a tuple
type Formatter = (value: number) => string;   // a function

const id: UserId = "u_42";
const start: Point = { x: 0, y: 0 };
const current: Status = "active";
const entry: Pair = ["score", 90];
const money: Formatter = (v) => `$${v.toFixed(2)}`;

console.log(id, start, current, entry, money(3.5));
// u_42 { x: 0, y: 0 } active [ 'score', 90 ] $3.50

الأسماء المستعارة موجودة وقت الترجمة فقط. لا يحتوي كود JavaScript الناتج على أي من أسطر type هذه.

الصياغة

type Name = SomeType;
type Name<T> = SomeTypeUsing<T>;       // generic
export type Name = SomeType;           // exported from a module

الأسماء بصيغة PascalCase عرفًا. والجانب الأيمن من علامة = أي تعبير نوع، ويمكن للاسم المستعار استخدام أسماء مستعارة أخرى، ومنها نفسه (انظر الأنواع التعاودية أدناه). الاسم المستعار متاح في النطاق كله الذي عُرّف فيه، حتى قبل سطر التعريف، لأن الأنواع تُفحص وقت الترجمة ولا تُنفذ بالترتيب مثل const أو let.

أنواع الكائنات

لشكل كائن، يُكتب الاسم المستعار والواجهة بالطريقة نفسها تقريبًا. يستخدم الاسم المستعار = وينتهي عادة بفاصلة منقوطة.

type User = {
  id: number;
  name: string;
  email?: string;           // optional
  readonly createdAt: string; // cannot be reassigned
};

type Admin = User & { permissions: string[] }; // extend with an intersection

const root: Admin = {
  id: 1,
  name: "root",
  createdAt: "2024-03-15",
  permissions: ["*"],
};

console.log(`${root.name} can do ${root.permissions.join(", ")}`); // root can do *

لا يستطيع الاسم المستعار استخدام extends؛ ويؤدي intersection بالرمز & هذا الدور. وفحص الخصائص الزائدة والخصائص الاختيارية وreadonly تعمل تمامًا كما في الواجهات. أما أيهما تختار لأشكال الكائنات فمشروح في صفحة interface مقابل type.

Union وTuples والدوال

هذه هي الحالات التي لا يسميها إلا الاسم المستعار، والسبب الرئيسي لوجود type. يسرد الاسم المستعار لـ union البدائل، ويثبّت الاسم المستعار لـ tuple طول المصفوفة وأنواع عناصرها، ويصف الاسم المستعار للدالة توقيعًا.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

type Span = [start: number, end: number]; // labeled tuple elements

type Transform = (shape: Shape, factor: number) => Shape;

const scale: Transform = (shape, factor) =>
  shape.kind === "circle"
    ? { kind: "circle", radius: shape.radius * factor }
    : { kind: "rect", width: shape.width * factor, height: shape.height * factor };

const r: Span = [10, 20];
console.log(scale({ kind: "circle", radius: 2 }, 3)); // { kind: 'circle', radius: 6 }
console.log(r[1] - r[0]);                              // 10

في scale لا تحتاج المعاملات إلى تعليقات أنواع: يوفر الاسم المستعار Transform أنواعها. صياغة tuple مشروحة في tuples، وتضييق union في صفحة أنواع union.

Type Aliases العامة

تجعل معاملات الأنواع اسمًا مستعارًا واحدًا يعمل مع أنواع كثيرة. ويمكن أن تكون لها قيم افتراضية، تمامًا مثل معاملات الدوال.

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0
    ? { ok: true, value: n }
    : { ok: false, error: `not an age: ${text}` };
}

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? `age ${r.value}` : r.error);
}
// age 36
// not an age: abc

يستخدم Result<number> القيمة الافتراضية E = string. والأسماء المستعارة العامة الصغيرة مثل type Nullable<T> = T | null أو type Dict<T> = Record<string, T> شائعة في الكود الحقيقي. وأنواع الأدوات المدمجة (Partial<T> وPick<T, K> وReturnType<F>) أسماء مستعارة عامة أيضًا، معرّفة في المكتبة المعيارية.

الأسماء المستعارة أسماء لا أنواع جديدة

لا ينشئ الاسم المستعار نوعًا مميزًا. إنه اسم ثانٍ للنوع في الجانب الأيمن، ويعامل المترجم الاثنين على أنهما متطابقان. اسمان مستعاران لـ string قابلان للاستبدال تمامًا:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: UserId and OrderId are both just string

يطبع هذا cancelling u_42 دون أي خطأ، وهذا هو الخطأ الذي لا يستطيع الاسم المستعار منعه. ما زال الاسم المستعار يساعد القراء (المعامل الذي نوعه OrderId يقول أكثر من string)، لكن إذا كان يجب أن يكون الخلط بين معرّفين خطأ ترجمة، فاستخدم branded type مثل string & { readonly __brand: "OrderId" }.

Type Aliases التعاودية

يمكن للاسم المستعار أن يشير إلى نفسه، وهكذا تصف الأشجار والقوائم المتداخلة وJSON:

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | { [key: string]: Json };

type TreeNode = {
  value: number;
  children: TreeNode[];
};

function sum(node: TreeNode): number {
  return node.value + node.children.reduce((total, child) => total + sum(child), 0);
}

const tree: TreeNode = {
  value: 1,
  children: [
    { value: 2, children: [] },
    { value: 3, children: [{ value: 4, children: [] }] },
  ],
};

const payload: Json = { ok: true, items: [1, "two", null], meta: { page: 1 } };

console.log(sum(tree));               // 10
console.log(JSON.stringify(payload)); // {"ok":true,"items":[1,"two",null],"meta":{"page":1}}

يرفض الاسم المستعار Json القيم التي لا يستطيع JSON تمثيلها: إسناد { when: new Date() } أو { f: undefined } إلى Json خطأ ترجمة (TS2322).

أنواع من القيم: typeof

عندما تكون القيمة موجودة أصلًا، يمكنك تسمية نوعها بدل كتابته. يقرأ عامل الأنواع typeof نوع متغير، ويتركب مع عوامل أخرى:

const defaults = { retries: 3, verbose: false, level: "info" };

type Options = typeof defaults;
// { retries: number; verbose: boolean; level: string }

type OptionKey = keyof typeof defaults;
// "retries" | "verbose" | "level"

function start(port: number) {
  return { port, startedAt: new Date() };
}
type Server = ReturnType<typeof start>;
// { port: number; startedAt: Date }

تبقى القيمة مصدر الحقيقة الوحيد: أضف خاصية إلى defaults فيتبعها Options. المزيد في typeof.

تصدير الأسماء المستعارة واستيرادها

تُصدَّر الأسماء المستعارة وتُستورد مثل القيم. يوضّح import type أن المستورد نوع فقط، فيُحذف الاستيراد دائمًا من ناتج JavaScript:

// shapes.ts
export type Point = { x: number; y: number };
export type Shape = { kind: "circle"; center: Point; radius: number };

// main.ts
import type { Point, Shape } from "./shapes.js";

const p: Point = { x: 1, y: 2 };