Từ khóa declare và tệp .d.ts trong TypeScript là gì

Tệp khai báo (declaration file, .d.ts) chỉ chứa kiểu và không gì khác: chữ ký hàm, interface và hình dạng class cho JavaScript nằm ở nơi khác. Từ khóa declare làm cùng việc đó bên trong một tệp bình thường. Nó báo cho trình biên dịch rằng "thứ này tồn tại lúc chạy, cứ tin đi", và không sinh ra code nào.

declare const __APP_VERSION__: string; // a bundler would replace this

console.log(typeof __APP_VERSION__); // undefined: nothing defined it

try {
  console.log(__APP_VERSION__.length); // type checks, fails at run time
} catch (e) {
  console.log(e instanceof Error ? e.message : e);
}

Trình biên dịch chấp nhận __APP_VERSION__.length vì lời khai báo nói đó là một chuỗi. Lúc chạy không có biến nào như vậy, nên đọc .length sẽ ném ra ReferenceError: __APP_VERSION__ is not defined, một ngoại lệ lúc chạy mà trình biên dịch không hề lường trước. Đó là giao kèo của mọi lời khai báo: kiểu chỉ đúng khi JavaScript phía sau nó đúng.

Tệp .d.ts chứa những gì

Biên dịch với declaration: true cho thấy rõ ý tưởng này nhất. Từ mã nguồn này:

// price.ts
export interface LineItem {
    name: string;
    price: number;
    qty: number;
}

const TAX = 0.2;

export function total(items: LineItem[]) {
    const sum = items.reduce((acc, item) => acc + item.price * item.qty, 0);
    return Math.round(sum * (1 + TAX) * 100) / 100;
}

export class Cart {
    private items: LineItem[] = [];
    add(item: LineItem) {
        this.items.push(item);
        return this;
    }
}

tsc viết ra price.js và tệp price.d.ts này:

export interface LineItem {
    name: string;
    price: number;
    qty: number;
}
export declare function total(items: LineItem[]): number;
export declare class Cart {
    private items;
    add(item: LineItem): this;
}

Thân hàm biến mất, kiểu trả về được suy ra thì được viết rõ (number, this), thuộc tính private giữ tên nhưng mất kiểu, còn TAX không được export thì hoàn toàn không có mặt. Một thư viện phát hành tệp .js cho Node và tệp .d.ts cho trình soạn thảo và trình biên dịch của bạn. emitDeclarationOnly: true chỉ tạo ra các tệp .d.ts, dành cho dự án dùng bundler để build JavaScript.

Các đối tượng có sẵn của ES2022 mà bạn dùng hằng ngày cũng đến từ tệp khai báo: lib.es2022.d.ts và các tệp cùng loại đi kèm TypeScript và được chọn qua target và lib.

Các dạng declare

Mỗi câu lệnh declare mô tả một thứ đã tồn tại. Trong một tệp .d.ts không có import hay export (một tệp khai báo toàn cục), mỗi khai báo sau đây đều hiện diện trong toàn bộ dự án:

// globals.d.ts
declare const API_URL: string;                     // a global constant
declare let debugMode: boolean;                    // a global variable
declare function track(event: string, props?: Record<string, string>): void;
declare class Widget {                             // a class from a script tag
    constructor(el: string);
    render(): void;
}
declare namespace Analytics {                      // a global object
    function page(name: string): void;
}
declare module "legacy-charts" {                   // a module you import
    export function draw(data: number[]): void;
}

Bên trong tệp .d.ts, interface và type không cần declare; mọi khai báo cấp cao nhất khác mà không có declare hay export là lỗi TS1046. Khi một tệp có import hoặc export, các khai báo của nó chỉ có tác dụng cục bộ trong tệp, và những phần bổ sung vào phạm vi toàn cục phải nằm trong khối declare global (xem bên dưới). Chữ ký được khai báo là thứ trình biên dịch dùng để kiểm tra lời gọi:

// This does not compile: the declaration says every prop is a string.
declare function track(event: string, props?: Record<string, string>): void;

track("signup");
track("purchase", { items: 3 });

Trình biên dịch báo index.ts(5,21): error TS2322: Type 'number' is not assignable to type 'string'. Hãy truyền { items: "3" }, hoặc sửa lời khai báo nếu hàm thật nhận số.

Package @types

Nhiều package npm đi kèm sẵn tệp .d.ts, được tham chiếu từ trường types (hoặc một điều kiện types trong exports) của package.json. Với các package chỉ có JavaScript, dự án DefinitelyTyped do cộng đồng duy trì phát hành kiểu dưới scope @types:

npm i lodash
npm i -D @types/lodash

Khi bạn import một package, TypeScript tự động tìm node_modules/@types/{name}. Những kiểu mô tả biến toàn cục thay vì một thứ được import, như @types/node (process, Buffer) hay describe và it của một test runner, phải được liệt kê trong tsconfig.json:

{
    "compilerOptions": {
        "types": ["node"]
    }
}

Thiếu mục đó, TypeScript 7 không nạp chúng, kể cả khi package đã được cài:

error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

tsc --init ghi "types": [] vào cấu hình mới, kèm một chú thích gợi ý dùng ["node"] cho dự án Node.

Gán kiểu cho module chưa có kiểu

Import một package JavaScript không có kiểu, dù đi kèm hay trong @types, là lỗi TS7016:

error TS7016: Could not find a declaration file for module 'fakelib'. '/project/node_modules/fakelib/index.js' implicitly has an 'any' type.

Hãy sửa bằng một tệp .d.ts ở bất kỳ đâu trong dự án (thư mục types/ là lựa chọn phổ biến; chỉ cần nó nằm trong phạm vi include) và không có import hay export ở cấp cao nhất. Mô tả những phần bạn dùng:

// types/fakelib.d.ts
declare module "fakelib" {
    export function hi(name: string): string;
    export const version: string;
}

// Non-code files a bundler lets you import
declare module "*.svg" {
    const url: string;
    export default url;
}

Phiên bản ngắn nhất, declare module "fakelib"; trên một dòng, làm mọi thứ import từ package trở thành any. Nó xóa lỗi nhưng cũng xóa luôn mọi phép kiểm tra, nên chỉ coi đó là bước tạm thời.

declare global

Code bổ sung vào phạm vi toàn cục, như một polyfill, một phương thức mới trên đối tượng có sẵn, hay một biến toàn cục do thẻ script đặt ra, cần có kiểu tương ứng. declare global thêm các kiểu đó. Nó phải nằm trong một module (một tệp có import hoặc export), đó là lý do export {} nằm ở đầu tệp:

export {}; // declare global only works in a module

declare global {
  interface Array<T> {
    last(): T | undefined;
  }
  var appName: string;
}

Array.prototype.last = function () {
  return this[this.length - 1];
};
globalThis.appName = "Inventory";

const prices = [4, 8, 15];
console.log(prices.last(), [].last(), appName); // 15 undefined Inventory

interface Array<T> hợp nhất với interface Array có sẵn thay vì thay thế nó, và var (không phải let hay const) mới là thứ thêm thuộc tính vào globalThis. Mở rộng prototype của đối tượng có sẵn là rủi ro trong code dùng chung; cũng kỹ thuật declare global này là cách các dự án thêm biến riêng vào process.env qua interface NodeJS.ProcessEnv của @types/node.

Module augmentation

Để bổ sung vào kiểu của một package bạn import, hãy khai báo lại tên module của nó và mở lại interface. Bản thân tệp phải là một module (import làm điều đó; export {} cũng được). Không có import hay export, cùng khối code đó sẽ khai báo một module config-lib hoàn toàn mới, che mất kiểu thật của package:

// types/config-lib.d.ts
import "config-lib";

declare module "config-lib" {
    interface Settings {
        beta: boolean; // merged into the package's own Settings interface
    }
}

Sau đó, load().beta từ config-lib có kiểu boolean ở mọi nơi. Interface hợp nhất được; type alias thì không, nên thư viện phải export một interface thì cách này mới dùng được. Đây là cách các plugin thêm trường vào đối tượng request hoặc config của một framework.

skipLibCheck

skipLibCheck: true khiến trình biên dịch không kiểm tra kiểu các tệp .d.ts, kể cả các tệp trong node_modules. Code của bạn vẫn được kiểm tra dựa trên chúng. Tùy chọn này tiết kiệm thời gian và tránh lỗi từ hai package có khai báo mâu thuẫn nhau, đó là lý do tsc --init bật nó. Cái giá là lỗi bên trong chính các tệp .d.ts của bạn cũng không được báo.