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

טיפוס אובייקט ב-TypeScript מפרט את המאפיינים שיש לאובייקט ואת הטיפוס של כל אחד מהם: { name: string; age: number }. הוסיפו ? כדי להפוך מאפיין לאופציונלי ו-readonly כדי למנוע השמה מחדש שלו. כתבו את הטיפוס inline, או תנו לו שם עם type או interface כדי להשתמש בו שוב.

// Inline object type
let point: { x: number; y: number } = { x: 3, y: 4 };

// Named object type with optional and readonly properties
type User = {
    readonly id: number;
    name: string;
    email?: string; // optional: may be missing
};

const ada: User = { id: 1, name: "Ada" };
const grace: User = { id: 2, name: "Grace", email: "grace@example.com" };

console.log(point.x + point.y);           // 7
console.log(ada.email ?? "no email");      // no email
console.log(grace.email?.toUpperCase());   // GRACE@EXAMPLE.COM

כתיבת טיפוסי אובייקט

מפרידים בין מאפיינים עם ; או , (שניהם עובדים, ; הוא הסגנון המקובל), וגם ירידת שורה לבדה מספיקה. טיפוס inline מתאים לפרמטר חד פעמי; לכל דבר שמשתמשים בו פעמיים, תנו שם.

// Inline, in a parameter
function area(rect: { width: number; height: number }): number {
    return rect.width * rect.height;
}

// Named with a type alias
type Rect = { width: number; height: number };

// Named with an interface (the same shape)
interface RectShape {
    width: number;
    height: number;
}

type ו-interface מתארים צורות של אובייקטים באותה מידה. ההבדלים (מיזוג הצהרות, איחודים) מוסברים בדף interface מול type.

גישה למאפיין שהטיפוס לא מצהיר עליו היא שגיאת קומפילציה: point.z נותן TS2339, Property 'z' does not exist on type '{ x: number; y: number; }'.

מאפיינים אופציונליים

? אחרי השם מאפשר להשמיט את המאפיין. קריאה של מאפיין אופציונלי נותנת T | undefined, ולכן TypeScript מחייב אתכם לטפל במקרה החסר לפני השימוש בו.

type Profile = {
    name: string;
    nickname?: string;
    age?: number;
};

function greet(p: Profile): string {
    // p.nickname is string | undefined
    const shown = p.nickname ?? p.name;         // default with ??
    const ageText = p.age !== undefined ? ` (${p.age})` : ""; // or check
    return `Hi, ${shown}${ageText}`;
}

console.log(greet({ name: "Ada" }));                        // Hi, Ada
console.log(greet({ name: "Grace", nickname: "Amazing Grace", age: 85 }));
console.log("age" in { name: "Ada" });                      // false

קריאה למתודה על מאפיין אופציונלי בלי בדיקה היא שגיאה: p.nickname.toUpperCase() נכשל עם TS18048, 'p.nickname' is possibly 'undefined'. השתמשו ב-optional chaining (p.nickname?.toUpperCase()) כש-undefined הוא תוצאה מקובלת.

prop?: T ו-prop: T | undefined אינם אותו דבר. הראשון מתיר שהמפתח ייעדר; השני מחייב את המפתח, גם אם הערך שלו יכול להיות undefined:

type A = { note?: string };
type B = { note: string | undefined };

const a1: A = {};                    // fine: key left out
const b1: B = { note: undefined };   // fine: key present
// @ts-expect-error: Property 'note' is missing in type '{}' but required in type 'B'.
const b2: B = {};

console.log(a1, b1, b2); // {} { note: undefined } {}

מאפייני readonly

readonly מונע השמה מחדש של מאפיין אחרי שהאובייקט נוצר. זו בדיקה בזמן קומפילציה בלבד, והיא רדודה: אובייקט או מערך ששמורים במאפיין readonly עדיין ניתנים לשינוי מבפנים.

type Order = {
    readonly id: string;
    readonly items: string[];
    status: "open" | "paid";
};

const order: Order = { id: "A-17", items: ["tea"], status: "open" };

order.status = "paid"; // fine
// @ts-expect-error: Cannot assign to 'id' because it is a read-only property.
order.id = "B-2";
order.items.push("cake"); // allowed: readonly is shallow

console.log(order); // { id: 'B-2', items: [ 'tea', 'cake' ], status: 'paid' }

הפלט מראה את שתי המגבלות: ה-id באמת השתנה בזמן ריצה (רק הקומפיילר ידע שהוא readonly), והמערך שבפנים שונה. למערך לקריאה בלבד השתמשו ב-readonly string[]; כדי להפוך את כל המאפיינים ל-readonly בבת אחת, השתמשו ב-Readonly<Order>.

בדיקת מאפיינים עודפים

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

// This does not compile: 'colour' is not a property of Options.
type Options = { color?: string; size?: number };

function draw(opts: Options) {
    console.log(opts.color ?? "black", opts.size ?? 1);
}

draw({ colour: "red", size: 2 });

index.ts(8,8): error TS2561: Object literal may only specify known properties, but 'colour' does not exist in type 'Options'. Did you mean to write 'color'?

הקוד הוא TS2561 כי הקומפיילר מצא התאמה קרובה; מאפיין נוסף בלי שם דומה נותן TS2353, Object literal may only specify known properties, and 'z' does not exist in type 'Point'. בלי הבדיקה, שגיאת ההקלדה הייתה עוברת קומפילציה, color היה undefined, והתוכנית הייתה מציירת בשחור בלי שום התראה. הבדיקה חלה רק על ליטרלים חדשים. אובייקט שכבר נמצא במשתנה יכול לשאת מאפיינים נוספים, כי מערכת הטיפוסים של TypeScript מבנית: ערך מתאים לטיפוס כשיש לו לפחות את המאפיינים הנדרשים.

type Point = { x: number; y: number };

const point3d = { x: 1, y: 2, z: 3 };
const p: Point = point3d; // fine: point3d has x and y

function show(pt: Point) {
    console.log(pt.x, pt.y);
}
show(point3d); // 1 2

אובייקטים מקוננים ומתודות

טיפוסי אובייקט ניתנים לקינון, והם יכולים לתאר מתודות בתחביר מתודה או כמאפיין עם טיפוס פונקציה.

type Company = {
    name: string;
    address: {
        city: string;
        zip?: string;
    };
    tags: string[];
    describe(): string;                  // method syntax
    rename: (newName: string) => void;   // function property
};

const acme: Company = {
    name: "Acme",
    address: { city: "Berlin" },
    tags: ["b2b"],
    describe() {
        return `${this.name} in ${this.address.city}`;
    },
    rename(newName) {
        this.name = newName;
    },
};

acme.rename("Acme GmbH");
console.log(acme.describe());               // Acme GmbH in Berlin
console.log(acme.address.zip ?? "no zip");  // no zip

type Address = Company["address"]; // reuse a nested type by indexing
const home: Address = { city: "Paris", zip: "75001" };
console.log(home);

לצורות עמוקות או כאלה שחוזרות, תנו שם לטיפוס הפנימי (type Address = { ... }) והפנו אליו, או חלצו אותו מהטיפוס החיצוני בגישה לפי אינדקס, Company["address"], כמו בשורות האחרונות.

object מול {} מול Object

שלושה טיפוסים נשמעים דומים ומשמעותם שונה:

const a: object = { id: 1 };
const b: object = [1, 2];
const c: {} = 42;          // allowed: {} does not mean "empty object"
const d: {} = "text";      // allowed too

// @ts-expect-error: Type 'number' is not assignable to type 'object'.
const e: object = 42;

console.log(a, b, c, d, e);

{} לא אומר "אובייקט ריק"; הוא אומר "לא null ולא undefined". כדי לקבל כל אובייקט עם מפתחות לא ידועים, השתמשו ב-Record<string, unknown>; למיפוי של מפתחות לערכים, השתמשו ב-index signature או ב-Record, כמו שמוצג בדף dictionary. ברוב המקרים, צורה ספציפית עדיפה על כל אחד משלושתם.