האופרטור 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 פותר

עם הערת טיפוס, הטיפוס של המשתנה הוא ההערה. הקומפיילר שוכח מה הוא ראה בליטרל. כאן אותה פלטה מקבלת במקום זאת הערת טיפוס, ועכשיו 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 ....

כלל אצבע: הוסיפו הערת טיפוס כשאתם רוצים שלמשתנה יהיה הטיפוס המוצהר (ערך שתבצעו לו השמה מחדש, API ציבורי), והשתמשו ב-satisfies כשאתם רוצים בדיקה, אבל הטיפוס של הערך עצמו שימושי יותר.

תפיסת טעויות בליטרלי אובייקט

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'?

הבדיקה גם נותנת לליטרל טיפוס הקשרי (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.

כדי לדרוש קבוצה קבועה של מפתחות, השתמשו ב-satisfies מול Record על איחוד: 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 הוא איחוד של הנתיבים האמיתיים. השתמשו ב-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). הוסיפו הערת טיפוס למשתנים שאתם מתכוונים לשנות.
• אתם רוצים את הטיפוס המוצהר בכוונה. לערך החזרה של פונקציה או לקבוע מיוצא שהוא חלק מ-API, הטיפוס של ההערה הוא החוזה, וחשיפת הטיפוס הליטרלי המדויק עלולה להפוך שינויים עתידיים לשוברים.
• הערך אינו ליטרל. satisfies בולט על ליטרלים של אובייקטים ומערכים. על משתנה או על תוצאה של קריאה הוא בדיקת שיוך פשוטה, שהערת טיפוס כבר נותנת לכם.