العامل satisfies في TypeScript: مقارنة مع توصيف النوع وas

يتحقق value satisfies Type من أن value تطابق Type وقت الترجمة، ثم يترك نوع القيمة نفسها، الأكثر دقة، دون تغيير. توصيف النوع كان سيستبدل هذا النوع الدقيق بـ Type؛ أما satisfies فيتحقق دون توسيع.

type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
} satisfies Record<ColorName, Color>;

// Checked against the Record, yet every property keeps its own type:
console.log(palette.green.toUpperCase());      // #00FF00 (green: string)
console.log(palette.red.map((c) => c / 255));  // [ 1, 0, 0 ] (red: [number, number, number])

يظل satisfies يقوم بالفحص: لون ناقص، أو مفتاح مكتوب خطأً مثل bleu، أو قيمة مثل true، كلها خطأ ترجمة في ذلك السطر. وهو موجود منذ TypeScript 4.9، ويُحذف من JavaScript الناتج مثل أي توصيف نوع.

المشكلة التي يحلها satisfies

مع توصيف النوع يكون نوع المتغير هو التوصيف. ينسى المترجم ما رآه في الـ literal. هنا اللوحة نفسها بتوصيف نوع بدلًا من ذلك، ولم تعد TypeScript تعرف أن green نص:

// This does not compile: the annotation widens every property to Color.
type ColorName = "red" | "green" | "blue";
type Color = string | [number, number, number];

const palette: Record<ColorName, Color> = {
  red: [255, 0, 0],
  green: "#00ff00",
  blue: [0, 0, 255],
};

console.log(palette.green.toUpperCase());

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

index.ts(11,27): error TS2339: Property 'toUpperCase' does not exist on type 'Color'.
  Property 'toUpperCase' does not exist on type '[number, number, number]'.

قبل TypeScript 4.9 كانت الخيارات: إما التوصيف ثم التضييق يدويًا في كل مكان (typeof palette.green === "string")، وإما حذف التوصيف وخسارة الفحص. يعطيك satisfies الاثنين. غيّر : Record<ColorName, Color> إلى satisfies Record<ColorName, Color> بعد القوس المعقوف الأخير فيعمل الكود.

satisfies مقابل توصيف النوع مقابل as

كائن الإعدادات نفسه مكتوبًا بثلاث طرق:

type Settings = {
  theme: "light" | "dark";
  fontSize: number;
  lang: string;
};

const annotated: Settings = { theme: "dark", fontSize: 14, lang: "en" };
const asserted = { theme: "dark", fontSize: 14 } as Settings; // lang is missing!
const satisfied = { theme: "dark", fontSize: 14, lang: "en" } satisfies Settings;

// annotated.theme: "light" | "dark"   (the annotation's type)
// satisfied.theme: "dark"             (what was actually written)
const isDark: "dark" = satisfied.theme; // fine; annotated.theme would be rejected

console.log(annotated.lang, asserted.lang, satisfied.lang); // en undefined en
console.log(isDark);                                         // dark

سمحت as بمرور lang الناقصة، وasserted.lang قيمتها undefined وقت التشغيل بينما يقول نوعها string. احذف lang من السطرين الآخرين فيفشل كلاهما بالخطأ TS2741، Property 'lang' is missing in type ....

قاعدة عملية: استخدم توصيف النوع حين تريد أن يحمل المتغير النوع المُعلن (قيمة ستعيد إسنادها، أو واجهة برمجية عامة)، واستخدم satisfies حين تريد الفحص لكن نوع القيمة نفسها أنفع.

اكتشاف الأخطاء في كائنات الـ Literal

يُجري satisfies فحص قابلية الإسناد كاملًا، بما في ذلك فحص الخصائص الزائدة، فتصبح الأخطاء الإملائية في المفاتيح أخطاء ترجمة:

type Route = { path: string; method: "GET" | "POST" };

const home = { path: "/", metod: "GET" } satisfies Route;
// error TS2561: Object literal may only specify known properties, but 'metod' does not exist in type 'Route'. Did you mean to write 'method'?

يعطي الفحص الـ literal أيضًا نوعًا سياقيًا (contextual type)، تمامًا كما يفعل توصيف النوع. ولهذا أثران. تبقى النصوص الحرفية أنواعًا حرفية حين يتوقعها النوع الهدف: { path: "/", method: "GET" } satisfies Route يحمل method: "GET"، بينما الكائن نفسه دون توصيف سيُستنتج method: string. وتُستنتج معاملات الـ callbacks من النوع الهدف:

type Handlers = {
  onSave: (doc: { id: number; title: string }) => string;
  onDelete: (id: number) => boolean;
};

const handlers = {
  onSave: (doc) => `saved #${doc.id}: ${doc.title}`, // doc is typed from Handlers
  onDelete: (id) => id > 0,
} satisfies Handlers;

console.log(handlers.onSave({ id: 7, title: "Notes" })); // saved #7: Notes
console.log(handlers.onDelete(-1));                      // false

مفاتيح Record تبقى معروفة

من الاستخدامات الشائعة جدول البحث. حين يُوصَف بـ Record<string, T> يصبح كل نص مفتاحًا صالحًا ويُترجم أي خطأ إملائي، فيعيد undefined وقت التشغيل. ومع satisfies تظل القيم مفحوصة مقابل T، لكن نوع المتغير يسرد المفاتيح التي كتبتها بالضبط:

type Endpoint = { url: string; timeoutMs: number };

const loose: Record<string, Endpoint> = {
  users: { url: "/api/users", timeoutMs: 3000 },
};

const endpoints = {
  users: { url: "/api/users", timeoutMs: 3000 },
  orders: { url: "/api/orders", timeoutMs: 8000 },
} satisfies Record<string, Endpoint>;

console.log(loose.userz?.url); // undefined: the typo compiles
console.log(endpoints.orders.timeoutMs); // 8000

type EndpointName = keyof typeof endpoints; // "users" | "orders"
const endpointName: EndpointName = "users";
console.log(endpoints[endpointName].url); // /api/users

// @ts-expect-error: TS2551 Property 'userz' does not exist on type ... Did you mean 'users'?
endpoints.userz;

keyof typeof endpoints مفيد فقط لأن المفاتيح بقيت. مع توصيف النوع سيكون مجرد string.

لفرض مجموعة ثابتة من المفاتيح، طابق Record على union: يبلّغ satisfies Record<"dev" | "prod", string> عن prod الناقصة بالخطأ TS2741 وعن staging غير المعروفة بالخطأ TS2353.

as const satisfies

يجتمع as const وsatisfies. اكتب as const أولًا: تجعل القيمة readonly بعمق مع أنواع حرفية، ثم يفحص satisfies تلك القيمة بالضبط.

type Route = { path: string; method: "GET" | "POST"; auth: boolean };

const routes = [
  { path: "/", method: "GET", auth: false },
  { path: "/login", method: "POST", auth: false },
  { path: "/account", method: "GET", auth: true },
] as const satisfies readonly Route[];

type Path = (typeof routes)[number]["path"]; // "/" | "/login" | "/account"

function link(path: Path): string {
  return `<a href="${path}">`;
}

console.log(link("/account"));                           // <a href="/account">
console.log(routes.filter((r) => r.auth).map((r) => r.path)); // [ '/account' ]

كل مسار يُفحص مقابل Route (القيمة method: "PUT" ستكون خطأ)، ويبقى الـ tuple من الأنواع الحرفية متاحًا، فيكون Path union من المسارات الحقيقية. استخدم readonly Route[] (أو ReadonlyArray<Route>) نوعًا هدفًا، لأن مصفوفة as const للقراءة فقط.

كائنات الإعدادات

الإعدادات هي المكان الذي يثبت فيه satisfies قيمته: يجب أن يكون الشكل صحيحًا، والكود في مواضع أخرى يريد القيم الدقيقة.

type Env = "development" | "production";

type AppConfig = {
  port: number;
  logLevel: "debug" | "info" | "warn";
  features: Record<string, boolean>;
};

const configs = {
  development: { port: 3000, logLevel: "debug", features: { newCheckout: true } },
  production: { port: 8080, logLevel: "warn", features: { newCheckout: false } },
} satisfies Record<Env, AppConfig>;

function start(env: Env): string {
  const c = configs[env];
  return `${env}: port ${c.port}, log ${c.logLevel}, newCheckout=${c.features.newCheckout}`;
}

console.log(start("development")); // development: port 3000, log debug, newCheckout=true
console.log(start("production"));  // production: port 8080, log warn, newCheckout=false

انسَ العنصر production، أو اكتب logLevel خطأً، أو اكتب logLevel: "verbose"، فيشير المترجم إلى السطر بالضبط. النمط نفسه يناسب ملفات *.config.ts: يفحص export default { ... } satisfies SomeConfig الملف كله بينما يحتفظ الكائن المُصدَّر بقيمه الحرفية.

متى لا تستخدم satisfies

• سيُعاد إسناد المتغير. يعطي let cfg = { port: 3000 } satisfies { port: number | string } المتغير cfg النوع { port: number }، فيفشل لاحقًا cfg = { port: "80" } (TS2322). استخدم توصيف النوع للمتغيرات التي تنوي تغييرها.
• تريد النوع المُعلن عن قصد. لقيمة مُعادة من دالة أو ثابت مُصدَّر يشكّل جزءًا من واجهة برمجية، نوع التوصيف هو العقد، وتسريب النوع الحرفي الدقيق قد يجعل التغييرات اللاحقة كاسرة للتوافق.
• القيمة ليست literal. يتألق satisfies مع كائنات ومصفوفات الـ literal. أما على متغير أو نتيجة استدعاء فهو مجرد فحص قابلية إسناد، يعطيك إياه توصيف النوع أصلًا.