Generic trong TypeScript: hàm, kiểu và lớp generic

Generic là các tham số kiểu. Một hàm generic khai báo một kiểu giữ chỗ, thường gọi là T, và mỗi lời gọi sẽ điền nó vào, nên kiểu đi vào quyết định kiểu đi ra. Nhờ vậy một hàm dùng được với số, chuỗi và đối tượng do bạn tự định nghĩa, mà mọi lời gọi vẫn có kiểu đầy đủ.

function first<T>(items: T[]): T | undefined {
  return items[0];
}

const n = first([10, 20, 30]);        // T = number, n: number | undefined
const s = first(["ada", "grace"]);    // T = string, s: string | undefined
const u = first([{ id: 1 }]);         // T = { id: number }

console.log(n?.toFixed(1));           // 10.0
console.log(s?.toUpperCase());        // ADA
console.log(u?.id);                   // 1

<T> sau tên hàm khai báo tham số kiểu. items: T[] dùng nó cho đầu vào và T | undefined cho đầu ra, gắn hai thứ đó với nhau. Bạn không hề viết number hay string: TypeScript đã suy ra T từ đối số.

Sao không dùng any hay unknown?

Không có generic, bạn sẽ khai báo kiểu tham số là any hoặc unknown. Cả hai đều nhận mọi mảng, và cả hai đều đánh mất mối liên hệ giữa đầu vào và đầu ra:

function firstAny(items: any[]): any {
  return items[0];
}

function firstUnknown(items: unknown[]): unknown {
  return items[0];
}

function firstGeneric<T>(items: T[]): T | undefined {
  return items[0];
}

const a = firstAny(["x"]);
console.log(typeof a.toFixed);         // undefined: a.toFixed(2) would compile, then throw

const b = firstUnknown(["x"]);
// b.toUpperCase();                    // error TS18046: 'b' is of type 'unknown'.
console.log(typeof b === "string" ? b.toUpperCase() : "?"); // X (after narrowing)

const c = firstGeneric(["x"]);
console.log(c?.toUpperCase());         // X, with no narrowing needed

Suy luận đối số kiểu

Thường thì TypeScript suy ra các đối số kiểu từ những giá trị bạn truyền vào. Bạn cũng có thể viết rõ chúng trong dấu ngoặc nhọn khi gọi, điều cần thiết khi không có đối số nào nhắc đến T, hoặc khi việc suy luận chọn ra thứ bạn không muốn.

function pair<T>(a: T, b: T): [T, T] {
  return [a, b];
}

function emptyList<T>(): T[] {
  return [];
}

const p1 = pair(1, 2);                      // T inferred as number
const p2 = pair<string | number>(1, "one"); // explicit: mixing allowed
const names = emptyList<string>();          // nothing to infer from, so pass it
names.push("Ada");

console.log(p1, p2, names); // [ 1, 2 ] [ 1, 'one' ] [ 'Ada' ]

Có hai kết quả suy luận đáng biết. pair(1, "one") không có đối số kiểu viết rõ là lỗi: TypeScript suy ra T = number từ đối số đầu tiên rồi báo Argument of type 'string' is not assignable to parameter of type 'number'. (TS2345). Còn emptyList() không có đối số nào thì nhận T = unknown, cho ra unknown[], hiếm khi là thứ bạn muốn.

Nhiều tham số kiểu

Một hàm có thể khai báo bao nhiêu tham số kiểu tùy ý, ngăn cách bằng dấu phẩy. Mỗi tham số được suy ra độc lập.

function zip<A, B>(left: A[], right: B[]): [A, B][] {
  const length = Math.min(left.length, right.length);
  const out: [A, B][] = [];
  for (let i = 0; i < length; i++) out.push([left[i], right[i]]);
  return out;
}

function mapValues<K extends string, V, R>(obj: Record<K, V>, fn: (value: V) => R): Record<K, R> {
  const out = {} as Record<K, R>;
  for (const key of Object.keys(obj) as K[]) out[key] = fn(obj[key]);
  return out;
}

console.log(zip(["a", "b", "c"], [1, 2]));        // [ [ 'a', 1 ], [ 'b', 2 ] ]
const prices = mapValues({ tea: 2.5, cake: 4 }, (v) => `$${v.toFixed(2)}`);
console.log(prices);                               // { tea: '$2.50', cake: '$4.00' }

mapValues suy ra ba thứ cùng lúc: K là "tea" | "cake", V là number, và R là string từ giá trị trả về của callback. K extends string là một ràng buộc, được trình bày ở trang tiếp theo.

Interface và type alias generic

Kiểu cũng nhận được tham số. Khi đó bạn viết đối số lúc dùng kiểu: Box<number>, ApiResponse<User>. Hầu hết các kiểu tập hợp có sẵn hoạt động theo cách này: Array<T>, Map<K, V>, Promise<T>, Record<K, V>.

interface ApiResponse<T> {
  status: number;
  data: T;
}

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

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

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0 ? { ok: true, value: n } : { ok: false, error: `bad age: ${text}` };
}

const res: ApiResponse<User[]> = { status: 200, data: [{ id: 1, name: "Ada" }] };
console.log(res.data[0].name);   // Ada

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? r.value + 1 : r.error); // 37, then bad age: abc
}

Result<T, E = string> cũng cho thấy một tham số kiểu mặc định: Result<number> nghĩa là Result<number, string>. Giống như tham số không bắt buộc của hàm, các tham số có giá trị mặc định phải đứng sau những tham số bắt buộc.

Lớp generic

Một lớp nhận tham số kiểu sau tên của nó, và mỗi instance cố định chúng. Trường, phương thức và tham số của hàm khởi tạo đều dùng được chúng.

class Stack<T> {
  private items: T[] = [];

  push(item: T): void {
    this.items.push(item);
  }

  pop(): T | undefined {
    return this.items.pop();
  }

  peek(): T | undefined {
    return this.items.at(-1);
  }

  get size(): number {
    return this.items.length;
  }
}

const visited = new Stack<string>();
visited.push("/home");
visited.push("/docs");
console.log(visited.pop(), visited.size); // /docs 1

const numbers = new Stack<number>();
numbers.push(42);
// numbers.push("42"); // error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
console.log(numbers.peek()); // 42

Nếu hàm khởi tạo nhận một T, bạn có thể bỏ đối số viết rõ: new Box(5) suy ra Box<number>. Thành viên static thuộc về chính lớp, không thuộc về một instance, nên chúng không dùng được tham số kiểu của lớp (Static members cannot reference class type parameters., TS2302).

Arrow function generic và kiểu hàm generic

Danh sách tham số kiểu đặt trước danh sách tham số. Cùng cú pháp đó mô tả một kiểu hàm generic.

const last = <T>(items: T[]): T | undefined => items[items.length - 1];

type Mapper = <T, R>(items: T[], fn: (item: T) => R) => R[];
const mapAll: Mapper = (items, fn) => items.map(fn);

// In a .tsx file, <T> looks like a JSX tag. Add a trailing comma:
const lastTsx = <T,>(items: T[]) => items[items.length - 1];

Suy ra kiểu literal với const type parameter

Mặc định, generic suy ra kiểu đã được mở rộng: pair("a", "b") cho ra [string, string]. Khi giá trị chính xác là quan trọng (tên route, tên sự kiện, danh sách cột), hãy đánh dấu tham số là const (TypeScript 5.0 trở lên) và nó sẽ suy ra như thể đối số được viết kèm as const:

function defineColumns<const T extends readonly string[]>(columns: T): T {
  return columns;
}

const loose = ["id", "name"];                  // string[]
const columns = defineColumns(["id", "name"]); // readonly ["id", "name"]

type Column = (typeof columns)[number];        // "id" | "name"
const sortBy: Column = "name";
console.log(columns, sortBy, loose.length);    // [ 'id', 'name' ] name 2

Nơi gọi viết một mảng bình thường, còn hàm giữ lại các kiểu literal.

Khi nào không nên dùng generic

Một tham số kiểu xứng đáng có mặt khi nó kết nối hai thứ: một tham số và kiểu trả về, hai tham số, hoặc một tham số và một callback. Nếu T chỉ xuất hiện một lần, nó chẳng thêm được gì và một kiểu thông thường sẽ rõ ràng hơn.

// Pointless: T is used once, so it is just a longer way to write unknown
function logValue<T>(value: T): void {
  console.log(value);
}

// Clearer
function logValueSimple(value: unknown): void {
  console.log(value);
}

// Also pointless: returns T but nothing connects T to an argument,
// so the caller is really just asserting a type
function parseJson<T>(text: string): T {
  return JSON.parse(text);
}

Trường hợp cuối rất phổ biến và dễ gây hiểu lầm: parseJson<User>(text) trông có vẻ an toàn kiểu nhưng không kiểm tra gì cả, y như JSON.parse(text) as User. Thay vào đó, hãy trả về unknown rồi xác thực dữ liệu. Những dấu hiệu lạm dụng khác: một tham số kiểu luôn được truyền cùng một đối số, hoặc một tham số có thể thay bằng union của hai kiểu đã biết.

Với những generic cần biết điều gì đó về T (rằng nó có length, hoặc K là một khóa của T), bước tiếp theo là ràng buộc bằng extends.