טיפוסים מדויקים ב-TypeScript: התאמת מבנה אובייקט קפדנית לקוד יציב

TypeScript, הרחבה (superset) של JavaScript, מביאה טיפוסים סטטיים לעולם הדינמי של פיתוח ווב. בעוד ש-TypeScript מציעה יתרונות משמעותיים במונחים של בטיחות טיפוסים ותחזוקתיות קוד, מערכת הטיפוסים המבנית שלה עלולה לפעמים להוביל להתנהגות בלתי צפויה. כאן נכנס לתמונה המושג "טיפוסים מדויקים". למרות של-TypeScript אין תכונה מובנית בשם "טיפוסים מדויקים", אנו יכולים להשיג התנהגות דומה באמצעות שילוב של תכונות וטכניקות של TypeScript. פוסט זה יעמיק באופן שבו ניתן לאכוף התאמת מבנה אובייקט קפדנית יותר ב-TypeScript כדי לשפר את יציבות הקוד ולמנוע שגיאות נפוצות.

הבנת מערכת הטיפוסים המבנית של TypeScript

TypeScript משתמשת בטיפוסים מבניים (הידועים גם כ-duck typing), מה שאומר שתאימות טיפוסים נקבעת על פי חברי הטיפוסים, ולא על פי שמותיהם המוצהרים. אם לאובייקט יש את כל המאפיינים הנדרשים על ידי טיפוס מסוים, הוא נחשב תואם לטיפוס זה, ללא קשר לשאלה אם יש לו מאפיינים נוספים.

לדוגמה:

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

const myPoint = { x: 10, y: 20, z: 30 };

function printPoint(point: Point) {
  console.log(`X: ${point.x}, Y: ${point.y}`);
}

printPoint(myPoint); // This works fine, even though myPoint has the 'z' property

בתרחיש זה, TypeScript מאפשרת להעביר את `myPoint` לפונקציה `printPoint` מכיוון שהוא מכיל את המאפיינים הנדרשים `x` ו-`y`, למרות שיש לו מאפיין נוסף `z`. גמישות זו יכולה להיות נוחה, אך היא עלולה גם להוביל לבאגים עדינים אם בטעות מעבירים אובייקטים עם מאפיינים בלתי צפויים.

הבעיה עם מאפיינים עודפים

הסלחנות של מערכת הטיפוסים המבנית עלולה לפעמים למסך שגיאות. חשבו על פונקציה שמצפה לקבל אובייקט תצורה:

interface Config {
  apiUrl: string;
  timeout: number;
}

function setup(config: Config) {
  console.log(`API URL: ${config.apiUrl}`);
  console.log(`Timeout: ${config.timeout}`);
}

const myConfig = { apiUrl: "https://api.example.com", timeout: 5000, typo: true };

setup(myConfig); // TypeScript doesn't complain here!

console.log(myConfig.typo); //prints true. The extra property silently exists

בדוגמה זו, ל-`myConfig` יש מאפיין נוסף `typo`. TypeScript אינה מציגה שגיאה מכיוון ש-`myConfig` עדיין עונה על דרישות הממשק `Config`. עם זאת, שגיאת ההקלדה לעולם לא נתפסת, והאפליקציה עלולה שלא להתנהג כצפוי אם הכוונה הייתה לכתוב `typoo`. בעיות שנראות חסרות משמעות כאלה יכולות להפוך לכאבי ראש גדולים בעת ניפוי באגים ביישומים מורכבים. מאפיין חסר או עם שגיאת כתיב יכול להיות קשה במיוחד לאיתור כאשר מתמודדים עם אובייקטים מקוננים בתוך אובייקטים אחרים.

גישות לאכיפת טיפוסים מדויקים ב-TypeScript

אף על פי ש"טיפוסים מדויקים" אמיתיים אינם זמינים ישירות ב-TypeScript, ישנן מספר טכניקות להשגת תוצאות דומות ולאכיפת התאמת מבנה אובייקט קפדנית יותר:

1. שימוש ב-Type Assertions עם `Omit`

טיפוס העזר `Omit` מאפשר ליצור טיפוס חדש על ידי השמטת מאפיינים מסוימים מטיפוס קיים. בשילוב עם type assertion, זה יכול לעזור למנוע מאפיינים עודפים.

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

const myPoint = { x: 10, y: 20, z: 30 };

// Create a type that includes only the properties of Point
const exactPoint: Point = myPoint as Omit & Point;

// Error: Type '{ x: number; y: number; z: number; }' is not assignable to type 'Point'.
// Object literal may only specify known properties, and 'z' does not exist in type 'Point'.

function printPoint(point: Point) {
  console.log(`X: ${point.x}, Y: ${point.y}`);
}


//Fix
const myPointCorrect = { x: 10, y: 20 };
const exactPointCorrect: Point = myPointCorrect as Omit & Point;
printPoint(exactPointCorrect);

גישה זו זורקת שגיאה אם ל-`myPoint` יש מאפיינים שאינם מוגדרים בממשק `Point`.

הסבר: `Omit` יוצר טיפוס שמשמיט את כל המפתחות הקיימים ב-`Point` מהטיפוס של `myPoint`. לאחר מכן, `& Point` מצליב (intersect) את הטיפוס הזה עם הטיפוס `Point`, ובכך למעשה דורש שהאובייקט יתאים לטיפוס `Point`. על ידי ביצוע המרה (assertion) של האובייקט לטיפוס המשולב הזה, המהדר בודק מאפיינים נוספים וזורק שגיאה אם נמצאו כאלה. זה מאלץ אותנו להכריז על המבנה הנכון בעת הגדרת האובייקט הראשונית.

2. שימוש בפונקציה ליצירת אובייקטים

ניתן ליצור פונקציית מפעל (factory function) שמקבלת רק את המאפיינים המוגדרים בממשק. גישה זו מספקת בדיקת טיפוסים חזקה בנקודת יצירת האובייקט.

interface Config {
  apiUrl: string;
  timeout: number;
}

function createConfig(config: Config): Config {
  return {
    apiUrl: config.apiUrl,
    timeout: config.timeout,
  };
}

const myConfig = createConfig({ apiUrl: "https://api.example.com", timeout: 5000 });

//This will not compile:
//const myConfigError = createConfig({ apiUrl: "https://api.example.com", timeout: 5000, typo: true });
//Argument of type '{ apiUrl: string; timeout: number; typo: true; }' is not assignable to parameter of type 'Config'.
// Object literal may only specify known properties, and 'typo' does not exist in type 'Config'.

על ידי החזרת אובייקט שנבנה רק עם המאפיינים המוגדרים בממשק `Config`, אתם מבטיחים ששום מאפיינים נוספים לא יוכלו להתגנב פנימה. זה הופך את יצירת התצורה לבטוחה יותר.

3. שימוש ב-Type Guards

Type guards הם פונקציות שמצמצמות את הטיפוס של משתנה בתוך היקף (scope) ספציפי. למרות שהם לא מונעים ישירות מאפיינים עודפים, הם יכולים לעזור לכם לבדוק אותם במפורש ולנקוט בפעולה המתאימה.

interface User {
  id: number;
  name: string;
}

function isUser(obj: any): obj is User {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'id' in obj && typeof obj.id === 'number' &&
    'name' in obj && typeof obj.name === 'string' &&
    Object.keys(obj).length === 2 //check for number of keys. Note: brittle and depends on User's exact key count.
  );
}

const potentialUser1 = { id: 123, name: "Alice" };
const potentialUser2 = { id: 456, name: "Bob", extra: true };

if (isUser(potentialUser1)) {
  console.log("Valid User:", potentialUser1.name);
} else {
  console.log("Invalid User");
}

if (isUser(potentialUser2)) {
  console.log("Valid User:", potentialUser2.name); //Will not hit here
} else {
  console.log("Invalid User");
}

בדוגמה זו, ה-type guard `isUser` בודק לא רק את קיומם של המאפיינים הנדרשים אלא גם את הטיפוסים שלהם ואת המספר ה*מדויק* של המאפיינים. גישה זו מפורשת יותר ומאפשרת לטפל באובייקטים לא חוקיים בצורה אלגנטית. עם זאת, בדיקת מספר המאפיינים היא שבירה. בכל פעם שמאפיינים נוספים או מוסרים מהטיפוס `User`, יש לעדכן את הבדיקה.

4. מינוף `Readonly` ו-`as const`

בעוד ש-`Readonly` מונע שינוי של מאפיינים קיימים, ו-`as const` יוצר טאפל (tuple) או אובייקט לקריאה בלבד שבו כל המאפיינים הם read-only לעומק ובעלי טיפוסים מילוליים (literal types), ניתן להשתמש בהם ליצירת הגדרה ובדיקת טיפוסים קפדנית יותר בשילוב עם שיטות אחרות. עם זאת, אף אחד מהם לא מונע מאפיינים עודפים בפני עצמו.

interface Options {
  width: number;
  height: number;
}

//Create the Readonly type
type ReadonlyOptions = Readonly;

const options: ReadonlyOptions = { width: 100, height: 200 };

//options.width = 300; //error: Cannot assign to 'width' because it is a read-only property.

//Using as const
const config = { api_url: "https://example.com", timeout: 3000 } as const;

//config.timeout = 5000; //error: Cannot assign to 'timeout' because it is a read-only property.

//However, excess properties are still allowed:
const invalidOptions: ReadonlyOptions = { width: 100, height: 200, depth: 300 }; //no error. Still allows excess properties.


interface StrictOptions {
  readonly width: number;
  readonly height: number;
}

//This will now error:
//const invalidStrictOptions: StrictOptions = { width: 100, height: 200, depth: 300 };
//Type '{ width: number; height: number; depth: number; }' is not assignable to type 'StrictOptions'.
//  Object literal may only specify known properties, and 'depth' does not exist in type 'StrictOptions'.

זה משפר את אי-השינוי (immutability), אך מונע רק מוטציה, לא את קיומם של מאפיינים נוספים. בשילוב עם `Omit`, או עם גישת הפונקציה, זה הופך ליעיל יותר.

5. שימוש בספריות (לדוגמה, Zod, io-ts)

ספריות כמו Zod ו-io-ts מציעות יכולות חזקות של אימות טיפוסים בזמן ריצה והגדרת סכמות. ספריות אלו מאפשרות להגדיר סכמות המתארות במדויק את המבנה הצפוי של הנתונים שלכם, כולל מניעת מאפיינים עודפים. למרות שהן מוסיפות תלות בזמן ריצה, הן מציעות פתרון יציב וגמיש מאוד.

דוגמה עם Zod:

import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

type User = z.infer;

const validUser = { id: 1, name: "John" };
const invalidUser = { id: 2, name: "Jane", extra: true };

const parsedValidUser = UserSchema.parse(validUser);
console.log("Parsed Valid User:", parsedValidUser);

try {
  const parsedInvalidUser = UserSchema.parse(invalidUser);
  console.log("Parsed Invalid User:", parsedInvalidUser); // This won't be reached
} catch (error) {
  console.error("Validation Error:", error.errors);
}

המתודה `parse` של Zod תזרוק שגיאה אם הקלט אינו תואם לסכמה, ובכך תמנע ביעילות מאפיינים עודפים. זה מספק אימות בזמן ריצה וגם מייצר טיפוסי TypeScript מהסכמה, מה שמבטיח עקביות בין הגדרות הטיפוסים שלכם ללוגיקת האימות בזמן ריצה.

שיטות עבודה מומלצות לאכיפת טיפוסים מדויקים

הנה כמה שיטות עבודה מומלצות שיש לקחת בחשבון בעת אכיפת התאמת מבנה אובייקט קפדנית יותר ב-TypeScript:

• בחרו את הטכניקה הנכונה: הגישה הטובה ביותר תלויה בצרכים הספציפיים ובדרישות הפרויקט שלכם. למקרים פשוטים, type assertions עם `Omit` או פונקציות מפעל עשויים להספיק. לתרחישים מורכבים יותר או כאשר נדרש אימות בזמן ריצה, שקלו להשתמש בספריות כמו Zod או io-ts.
• היו עקביים: ישמו את הגישה שבחרתם באופן עקבי בכל בסיס הקוד שלכם כדי לשמור על רמה אחידה של בטיחות טיפוסים.
• תעדו את הטיפוסים שלכם: תעדו בבירור את הממשקים והטיפוסים שלכם כדי לתקשר למפתחים אחרים את המבנה הצפוי של הנתונים.
• בדקו את הקוד שלכם: כתבו בדיקות יחידה כדי לוודא שמגבלות הטיפוסים שלכם פועלות כצפוי ושהקוד שלכם מטפל בנתונים לא חוקיים בצורה אלגנטית.
• שקלו את היתרונות והחסרונות: אכיפת התאמת מבנה אובייקט קפדנית יותר יכולה להפוך את הקוד שלכם ליציב יותר, אך היא גם יכולה להאריך את זמן הפיתוח. שקלו את היתרונות מול העלויות ובחרו את הגישה ההגיונית ביותר עבור הפרויקט שלכם.
• אימוץ הדרגתי: אם אתם עובדים על בסיס קוד קיים וגדול, שקלו לאמץ טכניקות אלו בהדרגה, החל מהחלקים הקריטיים ביותר של היישום שלכם.
• העדיפו ממשקים על פני כינויי טיפוס (type aliases) בעת הגדרת מבני אובייקטים: בדרך כלל עדיף להשתמש בממשקים מכיוון שהם תומכים במיזוג הצהרות (declaration merging), מה שיכול להיות שימושי להרחבת טיפוסים על פני קבצים שונים.

דוגמאות מהעולם האמיתי

בואו נסתכל על כמה תרחישים מהעולם האמיתי שבהם טיפוסים מדויקים יכולים להועיל:

• מטענים (payloads) של בקשות API: בעת שליחת נתונים ל-API, חיוני לוודא שהמטען תואם לסכמה הצפויה. אכיפת טיפוסים מדויקים יכולה למנוע שגיאות הנגרמות משליחת מאפיינים בלתי צפויים. לדוגמה, ממשקי API רבים לעיבוד תשלומים רגישים ביותר לנתונים בלתי צפויים.
• קבצי תצורה: קבצי תצורה מכילים לעתים קרובות מספר רב של מאפיינים, ושגיאות הקלדה יכולות להיות נפוצות. שימוש בטיפוסים מדויקים יכול לעזור לתפוס שגיאות אלו בשלב מוקדם. אם אתם מגדירים מיקומי שרתים בפריסה בענן, שגיאת הקלדה בהגדרת מיקום (למשל eu-west-1 לעומת eu-wet-1) תהפוך לקשה ביותר לניפוי באגים אם היא לא תיתפס מראש.
• צינורות עיבוד נתונים: בעת המרת נתונים מפורמט אחד לאחר, חשוב לוודא שנתוני הפלט תואמים לסכמה הצפויה.
• תורי הודעות: בעת שליחת הודעות דרך תור הודעות, חשוב לוודא שמטען ההודעה תקין ומכיל את המאפיינים הנכונים.

דוגמה: תצורת בינאום (i18n)

דמיינו שאתם מנהלים תרגומים עבור יישום רב-לשוני. ייתכן שיש לכם אובייקט תצורה כזה:

interface Translation {
  greeting: string;
  farewell: string;
}

interface I18nConfig {
  locale: string;
  translations: Translation;
}

const englishConfig: I18nConfig = {
  locale: "en-US",
  translations: {
    greeting: "Hello",
    farewell: "Goodbye"
  }
};


//This will be an issue, as an excess property exists, silently introducing a bug.
const spanishConfig: I18nConfig = {
  locale: "es-ES",
  translations: {
    greeting: "Hola",
    farewell: "Adiós",
    typo: "unintentional translation"
  }
};

//Solution: Using Omit
const spanishConfigCorrect: I18nConfig = {
  locale: "es-ES",
  translations: {
    greeting: "Hola",
    farewell: "Adiós"
  } as Omit & Translation
};

ללא טיפוסים מדויקים, שגיאת הקלדה במפתח תרגום (כמו הוספת השדה `typo`) עלולה לעבור מבלי שיבחינו בה, מה שיוביל לתרגומים חסרים בממשק המשתמש. על ידי אכיפת התאמת מבנה אובייקט קפדנית יותר, ניתן לתפוס שגיאות אלו במהלך הפיתוח ולמנוע מהן להגיע לסביבת הייצור (production).

סיכום

אף על פי של-TypeScript אין "טיפוסים מדויקים" מובנים, ניתן להשיג תוצאות דומות באמצעות שילוב של תכונות וטכניקות של TypeScript כמו type assertions עם `Omit`, פונקציות מפעל, type guards, `Readonly`, `as const`, וספריות חיצוניות כמו Zod ו-io-ts. על ידי אכיפת התאמת מבנה אובייקט קפדנית יותר, תוכלו לשפר את יציבות הקוד שלכם, למנוע שגיאות נפוצות, ולהפוך את היישומים שלכם לאמינים יותר. זכרו לבחור את הגישה המתאימה ביותר לצרכים שלכם ולהיות עקביים ביישומה בכל בסיס הקוד. על ידי בחינה מדוקדקת של גישות אלו, תוכלו לקבל שליטה רבה יותר על הטיפוסים ביישום שלכם ולהגביר את התחזוקתיות לטווח הארוך.