Constructor ב-TypeScript: Parameter Properties ו-Overloads

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

class Product {
    name: string;
    price: number;

    constructor(name: string, price: number) {
        this.name = name;
        this.price = price;
    }
}

const p = new Product("Lamp", 39);
console.log(p); // Product { name: 'Lamp', price: 39 }

// @ts-expect-error: Expected 2 arguments, but got 1.
new Product("Chair");

כתיבה של constructor(): Product היא השגיאה TS1093 (Type annotation cannot appear on a constructor declaration). כל השאר באופן שבו new עובד הוא JavaScript רגיל.

Parameter Properties

הדפוס שלמעלה (להצהיר על שדה, לקבל פרמטר, להעתיק אותו) נפוץ כל כך שיש ל-TypeScript קיצור. שימו public, private, protected או readonly לפני פרמטר של בנאי, והוא הופך לשדה:

class Product {
    constructor(
        public name: string,
        private price: number,
        readonly sku: string,
    ) {}

    label(): string {
        return `${this.name} (${this.sku}): $${this.price}`;
    }
}

const lamp = new Product("Lamp", 39, "LMP-1");
console.log(lamp.label()); // Lamp (LMP-1): $39
console.log(lamp.name, lamp.sku); // Lamp LMP-1
// lamp.price is private: accessing it outside the class is a compile error

זו אחת התכונות הבודדות של TypeScript שמייצרות קוד. הקומפיילר כותב בשבילכם את ההשמות:

class Product {
    name;
    price;
    sku;
    constructor(name, price, sku) {
        this.name = name;
        this.price = price;
        this.sku = sku;
    }
    // ...
}

מכיוון שזה לא רק טיפוסים שנמחקים, parameter properties לא רצים תחת ה-type stripping המובנה של Node (node file.ts נכשל עם ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX), ואפשרות הקומפיילר erasableSyntaxOnly מדווחת עליהם כשגיאה TS1294. פרויקטים שמריצים קבצי .ts ישירות כותבים את השדות ביד.

פרמטרים אופציונליים וברירות מחדל

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

class Logger {
    constructor(
        readonly prefix: string,
        readonly level: "info" | "debug" = "info",
        readonly color?: string,
    ) {}
}

console.log(new Logger("app"));
// Logger { prefix: 'app', level: 'info', color: undefined }
console.log(new Logger("db", "debug", "blue"));
// Logger { prefix: 'db', level: 'debug', color: 'blue' }

גם ל-parameter properties יכולות להיות ברירות מחדל. הטיפוס של color בתוך המחלקה הוא string | undefined, ולכן קוד שמשתמש בו צריך לבדוק קודם undefined.

לבנאים עם הרבה אפשרויות, אובייקט אפשרויות אחד קריא יותר מרשימה ארוכה של פרמטרים לפי מיקום: constructor(opts: { prefix: string; level?: "info" | "debug" }).

סדר האתחול של שדות

ערכים התחלתיים של שדות מחושבים לפני גוף הבנאי, ו-parameter properties מקבלים ערך בתחילת גוף הבנאי. לכן ערך התחלתי של שדה לא יכול לקרוא parameter property. TypeScript תופסת את זה:

// This does not compile: the initializer reads `size` too early.
class Grid {
    cells = this.size * this.size;

    constructor(public size: number) {}
}

console.log(new Grid(3).cells);

index.ts(3,18): error TS2729: Property 'size' is used before its initialization.
index.ts(3,30): error TS2729: Property 'size' is used before its initialization.

בזמן ריצה הערך ההתחלתי היה רואה undefined ומייצר NaN. במקום זה, חשבו את הערך בגוף הבנאי:

class Grid {
    cells: number;

    constructor(public size: number) {
        this.cells = size * size;
    }
}

console.log(new Grid(3).cells); // 9

Overloads של בנאים

למחלקה יש בדיוק מימוש אחד של בנאי, אבל אפשר לפרט מעליו כמה חתימות overload. הקוראים רואים רק את ה-overloads; חתימת המימוש חייבת להיות תואמת לכולן.

class Color {
    r: number;
    g: number;
    b: number;

    constructor(hex: string);
    constructor(r: number, g: number, b: number);
    constructor(a: string | number, g = 0, b = 0) {
        if (typeof a === "string") {
            const n = parseInt(a.replace("#", ""), 16);
            this.r = (n >> 16) & 255;
            this.g = (n >> 8) & 255;
            this.b = n & 255;
        } else {
            this.r = a;
            this.g = g;
            this.b = b;
        }
    }
}

console.log(new Color("#ff8800")); // Color { r: 255, g: 136, b: 0 }
console.log(new Color(10, 20, 30)); // Color { r: 10, g: 20, b: 30 }
// new Color(10, 20) is an error: no overload takes 2 arguments

overloads נהיים קשים לקריאה אחרי שתיים או שלוש צורות. מתודות factory סטטיות עם שמות תיאוריים (Color.fromHex("#ff8800"), Color.fromRgb(10, 20, 30)) לרוב ברורות יותר, ולא צריכות צמצום טיפוסים בתוך גוף אחד.

קריאה ל-super בתת-מחלקה

מחלקה נגזרת שמצהירה על בנאי משלה חייבת לקרוא ל-super(...) עם הארגומנטים של מחלקת האב, ולעשות את זה לפני שהיא נוגעת ב-this. שכחת הקריאה היא השגיאה TS2377 (Constructors for derived classes must contain a 'super' call), ושימוש ב-this קודם הוא TS17009 ('super' must be called before accessing 'this' in the constructor of a derived class). שתיהן משקפות כללי זמן ריצה של JavaScript.

class Animal {
    constructor(public name: string) {}
}

class Dog extends Animal {
    tricks: string[];

    constructor(name: string, ...tricks: string[]) {
        super(name); // must come first
        this.tricks = tricks;
    }
}

const rex = new Dog("Rex", "sit", "roll");
console.log(rex); // Dog { name: 'Rex', tricks: [ 'sit', 'roll' ] }

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

בנאים פרטיים והכנה אסינכרונית

אפשר לקרוא לבנאי private רק מתוך המחלקה. מבחוץ, new הוא השגיאה TS2673. כך מכריחים את הקוראים לעבור דרך factory, בשביל singleton או בשביל הכנה שחייבת להיות אסינכרונית (בנאים לא יכולים להיות async).

class Connection {
    private constructor(readonly url: string, readonly version: number) {}

    static async open(url: string): Promise<Connection> {
        const version = await Promise.resolve(3); // stands in for a real handshake
        return new Connection(url, version);
    }
}

async function main() {
    const conn = await Connection.open("db://local");
    console.log(conn.url, conn.version); // db://local 3
}
main();

private כאן הוא כלל של זמן קומפילציה בלבד. ב-JavaScript שנוצר יש בנאי רגיל, ולכן קוד JavaScript רגיל עדיין יכול לקרוא ל-new Connection(...).

טיפוסי בנאי

כדי לקבל מחלקה כערך, תנו לפרמטר טיפוס עם construct signature: new (...args) => Instance. גם typeof MyClass עובד, אבל הוא קושר את הפרמטר לחתימת הבנאי ולאיברים הסטטיים של המחלקה הספציפית הזו.

class Circle {
    constructor(public r: number) {}
}
class Square {
    constructor(public r: number) {}
}

type ShapeCtor<T> = new (size: number) => T;

function makeAll<T>(ctor: ShapeCtor<T>, sizes: number[]): T[] {
    return sizes.map((s) => new ctor(s));
}

console.log(makeAll(Circle, [1, 2])); // [ Circle { r: 1 }, Circle { r: 2 } ]
console.log(makeAll(Square, [5]));    // [ Square { r: 5 } ]

type CircleArgs = ConstructorParameters<typeof Circle>; // [r: number]
const args: CircleArgs = [7];
console.log(new Circle(...args)); // Circle { r: 7 }

ConstructorParameters ו-InstanceType מחלצים את ה-tuple של הפרמטרים ואת טיפוס המופע מטיפוס של בנאי; הם מוסברים יחד עם שאר עוזרי הפונקציות ב-ReturnType ו-Parameters.