TypeScript 배열 타입: 객체 배열, map과 filter

TypeScript의 배열 타입은 요소 타입 뒤에 []를 붙인 것입니다. string[]는 문자열 배열, number[]는 숫자 배열입니다. 제네릭 표기 Array<string>도 같은 타입입니다. 배열에 타입을 지정하면 추가하는 요소와 읽어 오는 요소가 모두 그 타입을 가집니다.

const names: string[] = ["Ada", "Grace"];
const scores: Array<number> = [90, 85, 72]; // same as number[]

names.push("Alan");
// @ts-expect-error: Argument of type 'number' is not assignable to parameter of type 'string'.
names.push(42);

const first: string = names[0];
const total = scores.reduce((sum, s) => sum + s, 0); // number

console.log(names, first, total);

@ts-expect-error 줄은 컴파일 오류(TS2345)입니다. 여기서는 예상된 오류로 표시했으므로 블록이 실행되며, 타입은 지워지기 때문에 런타임에는 42가 실제로 추가됩니다. 출력에서 확인할 수 있습니다.

string[] vs Array<string>

코드베이스마다 한 가지 스타일을 정하세요. typescript-eslint의 array-type 규칙은 기본값이 T[]입니다.

객체 배열

타입 별칭이나 인터페이스로 요소를 기술한 뒤 Type[]를 씁니다. 배열에서 읽어 온 모든 값이 그 형태에 맞는지 검사됩니다.

type User = { id: number; name: string; admin: boolean };

const users: User[] = [
    { id: 1, name: "Ada", admin: true },
    { id: 2, name: "Grace", admin: false },
    { id: 3, name: "Alan", admin: false },
];

users.push({ id: 4, name: "Linus", admin: false });

const admins = users.filter((u) => u.admin);       // User[]
const names = users.map((u) => u.name);            // string[]
const byId = users.find((u) => u.id === 2);        // User | undefined

console.log(admins.length, names);
console.log(byId?.name ?? "not found"); // Grace

users에 추가하는 객체 리터럴은 User와 정확히 일치해야 합니다. admin이 빠졌거나 프로퍼티 이름에 오타가 있으면 컴파일 오류입니다.

map, filter, reduce, find의 타입

배열 메서드는 제네릭이므로 결과에 타입이 붙습니다. 각 메서드가 런타임에 하는 일은 JavaScript 배열 메서드 페이지에서 다루고, 여기서는 TypeScript가 더하는 타입을 봅니다.

const prices = [4.5, 12, 8.25];

const labels = prices.map((p) => `$${p.toFixed(2)}`); // string[]
console.log(labels); // [ '$4.50', '$12.00', '$8.25' ]

const expensive = prices.find((p) => p > 100); // number | undefined
console.log(expensive ?? "none"); // none

// reduce's result type comes from the initial value,
// or from a type argument when the initial value is just {}
const byInitial = ["apple", "avocado", "banana"].reduce<Record<string, string[]>>(
    (acc, word) => {
        (acc[word[0]] ??= []).push(word);
        return acc;
    },
    {},
);
console.log(byInitial); // { a: [ 'apple', 'avocado' ], b: [ 'banana' ] }

// filter narrows when the callback is a type check
const raw = [1, undefined, 3, undefined];
const defined = raw.filter((n) => n !== undefined); // number[]
console.log(defined); // [ 1, 3 ]

마지막 예제가 동작하는 이유는 TypeScript(5.5부터)가 (n) => n !== undefined를 타입 서술어(type predicate)로 추론하기 때문입니다. 그래서 filter는 (number | undefined)[]가 아니라 number[]를 반환합니다. 추론할 수 없는 검사라면 서술어를 직접 쓰세요: filter((x): x is User => x !== null).

여러 타입을 담는 배열

유니언 요소 타입은 섞어 담는 것을 허용합니다. 배열 타입의 유니언은 허용하지 않습니다.

const mixed: (string | number)[] = [1, "two", 3]; // each element: string or number

let ids: string[] | number[] = [1, 2, 3]; // all numbers...
ids = ["a", "b"];                          // ...or all strings

// @ts-expect-error: (string | number)[] is not assignable to string[] | number[]
ids = [1, "b"];

for (const item of mixed) {
    // narrow each element before using type-specific methods
    console.log(typeof item === "string" ? item.toUpperCase() : item.toFixed(1));
}

[name, age] 쌍처럼 위치마다 타입이 정해져 있다면 튜플을 쓰세요. [string, number]는 인덱스 0이 문자열이고 인덱스 1이 숫자라는 것을 알지만, (string | number)[]는 모릅니다.

readonly 배열

readonly T[]는 배열을 변경하는 모든 메서드를 없앱니다. 함수가 바꾸면 안 되는 매개변수와 상수에 쓰세요.

// This does not compile: readonly arrays have no push.
function average(values: readonly number[]): number {
    values.push(0);
    return values.reduce((a, b) => a + b, 0) / values.length;
}

console.log(average([2, 4, 6]));

index.ts(3,12): error TS2339: Property 'push' does not exist on type 'readonly number[]'.

push 줄을 지우면 블록은 4를 출력합니다. 변경 가능한 number[]는 언제나 readonly number[]가 필요한 자리에 넘길 수 있으므로, readonly 매개변수는 호출하는 쪽에 아무 부담도 주지 않습니다. 이 검사는 컴파일 시점에만 이루어지며 런타임에는 평범한 배열입니다. readonly 배열을 정렬하려면 복사본을 정렬하세요: [...values].sort().

리터럴 배열에서 includes의 함정

as const는 배열을 리터럴 타입의 readonly 튜플로 바꿉니다. 허용 값 목록으로 쓰기에 좋지만, 그 includes는 해당 리터럴만 받습니다.

const COLORS = ["red", "green", "blue"] as const;
type Color = (typeof COLORS)[number]; // "red" | "green" | "blue"

function isColor(value: string): value is Color {
    // COLORS.includes(value) is error TS2345: 'string' is not assignable
    // to '"blue" | "green" | "red"'. Widen the array for the check:
    return (COLORS as readonly string[]).includes(value);
}

const input: string = "green";
if (isColor(input)) {
    const c: Color = input; // narrowed to Color
    console.log("valid color:", c);
}
console.log(isColor("purple")); // false

검사를 타입 가드(value is Color)로 감싸면 넓히는 작업은 한 번만 하고, 호출하는 쪽은 좁혀진 값을 돌려받습니다.

인덱싱과 빈 배열

arr[i]를 읽으면 i가 범위를 벗어나 런타임 값이 undefined여도 타입은 T입니다. at(i)의 타입은 T | undefined이고, 컴파일러 옵션 noUncheckedIndexedAccess를 켜면 일반 인덱싱도 T | undefined를 반환합니다.

const queue: string[] = []; // annotate empty arrays

const head = queue[0];     // type string, value undefined
const last = queue.at(-1); // type string | undefined

console.log(head, last);            // undefined undefined
console.log(last?.toUpperCase());   // undefined, safely

queue[0].toUpperCase()는 컴파일은 되지만 런타임에 TypeError를 던집니다. 인덱스에 값이 없을 수 있다면 at(), 길이 검사, 또는 noUncheckedIndexedAccess를 쓰세요.