← Back to Index

Chapter 2.5: Data Structures

Annotate your data containers with the right types

🆚 Comparison with Python: Python's list is dynamically typed and can mix types; TS's Array requires elements of the same type by default. Python's dict corresponds to TS's Record or Map. Python's tuple is immutable, while TS's Tuple focuses on fixed length and types.

1. Array

Two equivalent array type annotation methods, plus commonly used type-safe array methods:

// 两种写法完全等价
const nums: number[] = [1, 2, 3];
const strs: Array<string> = ["a", "b", "c"];

// map —— 返回新数组，类型自动推断
const doubled: number[] = nums.map(n => n * 2);

// filter —— 可以用类型守卫缩窄类型
const mixed: (string | number)[] = [1, "a", 2, "b"];
const onlyStrings: string[] = mixed.filter(
    (x): x is string => typeof x === "string"
);

// reduce —— 需要提供初始值的类型
const sum: number = nums.reduce((acc, cur) => acc + cur, 0);

// find / some / every
const found: number | undefined = nums.find(n => n > 2);
const hasNeg: boolean = nums.some(n => n < 0);
const allPos: boolean = nums.every(n => n > 0);

// 只读数组
const frozen: readonly number[] = [1, 2, 3];
// frozen.push(4); // ✗ 编译错误

2. Tuple

Tuples are fixed-length arrays with a specific type at each position. Ideal for functions returning multiple values:

// 基本元组
const point: [number, number] = [10, 20];
const entry: [string, number] = ["age", 30];

// 带标签的元组——提高可读性
type Range = [start: number, end: number];
const r: Range = [0, 100];

// 可选元素
type OptionalTuple = [string, number?];
const t1: OptionalTuple = ["hello"];
const t2: OptionalTuple = ["hello", 42];

// Rest 元素
type StringAndNumbers = [string, ...number[]];
const sn: StringAndNumbers = ["sum", 1, 2, 3, 4];

// 实际用途：函数返回多个值
function useState<T>(initial: T): [T, (v: T) => void] {
    let value = initial;
    const setter = (v: T) => { value = v; };
    return [value, setter];
}
const [count, setCount] = useState(0);

When destructuring tuples, variable names are arbitrary — types are determined by position. Unlike Python's namedtuple, this is more similar to Go's multiple return values.

3. Enum

// 数字枚举——默认从 0 开始自增
enum Direction {
    Up,    // 0
    Down,  // 1
    Left,  // 2
    Right  // 3
}

// 字符串枚举——每个成员必须显式赋值
enum Status {
    Active = "ACTIVE",
    Inactive = "INACTIVE",
    Pending = "PENDING"
}

// const enum——编译时内联，不生成运行时对象
const enum Color {
    Red = "#ff0000",
    Green = "#00ff00",
    Blue = "#0000ff"
}
const c = Color.Red; // 编译后直接替换为 "#ff0000"

// 数字枚举支持反向映射
console.log(Direction[0]); // "Up"
console.log(Direction.Up); // 0

Enum vs Union Types: In most cases, using type Status = "active" | "inactive" union types is recommended over enums — lighter with no runtime overhead. Enums have advantages when you need reverse mapping or member iteration.

4. Map and Set

// Map<K, V> —— 有序键值对集合
const userMap = new Map<number, string>();
userMap.set(1, "Alice");
userMap.set(2, "Bob");

const name = userMap.get(1);     // string | undefined
const exists = userMap.has(3);   // false
userMap.delete(2);
console.log(userMap.size);       // 1

// 遍历 Map
for (const [id, name] of userMap) {
    console.log(`${id}: ${name}`);
}

// Set<T> —— 值唯一的集合
const tags = new Set<string>();
tags.add("typescript");
tags.add("javascript");
tags.add("typescript"); // 不会重复添加
console.log(tags.size); // 2

// WeakMap / WeakSet —— 键为弱引用，不阻止垃圾回收
const cache = new WeakMap<object, string>();
let obj = { id: 1 };
cache.set(obj, "cached");
// obj = null 后，cache 中的条目可被 GC 回收

5. Record Type

Record<K, V> is used to create key-value pair types, similar to Python's Dict[str, T]:

// Record 作为字典
type ScoreBoard = Record<string, number>;
const scores: ScoreBoard = {
    alice: 95,
    bob: 87,
    charlie: 92
};

// 限定键的范围
type Role = "admin" | "editor" | "viewer";
type Permissions = Record<Role, string[]>;
const perms: Permissions = {
    admin: ["read", "write", "delete"],
    editor: ["read", "write"],
    viewer: ["read"]
};

// Record vs Map：
// Record 编译为普通对象，键只能是 string | number | symbol
// Map 键可以是任意类型，有更好的增删性能和迭代顺序保证

6. Destructuring and Spread

// 对象解构 + 类型注解
const user = { name: "Alice", age: 30, email: "a@b.com" };
const { name, age }: { name: string; age: number } = user;

// 重命名 + 默认值
const { name: userName, role = "user" } = { name: "Bob" };

// 数组解构
const [first, second, ...rest] = [1, 2, 3, 4, 5];
// first: number, second: number, rest: number[]

// 展开运算符——合并对象
const defaults = { theme: "light", lang: "zh" };
const custom = { theme: "dark" };
const config = { ...defaults, ...custom };
// { theme: "dark", lang: "zh" }

// 展开运算符——合并数组
const arr1 = [1, 2];
const arr2 = [3, 4];
const merged = [...arr1, ...arr2]; // [1, 2, 3, 4]

// Rest 参数解构
function printInfo({ name, ...rest }: {
    name: string;
    age: number;
    email: string;
}) {
    console.log(name, rest); // rest: { age: number; email: string }
}

📝 Chapter Summary