Capstone: выкатываем одну фичу, типизированную насквозь

Один источник истины, затем вывод (юниты 00, 02, 05, 08)

Вся стратегия держится на одном правиле из юнита 08: выводи, не дублируй. Выбери один артефакт, определяющий комментарий, и сделай каждый другой тип функцией от него. Схема zod — сильнейший выбор, потому что она одновременно рантайм-валидатор и статический тип:

import { z } from "zod";

// ЭТО источник истины. Всё ниже по течению выводится из него.
export const Comment = z.object({
  id: z.string().uuid(),
  threadId: z.string().uuid(),
  body: z.string().min(1).max(2000),
  authorId: z.string().uuid(),
  createdAt: z.coerce.date(),
});

// `z.infer` превращает рантайм-схему в статический тип (`infer` из юнита 05,
// тип-vs-значение из юнита 00: `Comment`-значение живёт в пространстве значений,
// `Comment`-тип — в пространстве типов; одно имя, два пространства имён).
export type Comment = z.infer<typeof Comment>;
//          ^? { id: string; threadId: string; body: string; authorId: string; createdAt: Date }

typeof Comment читает значение (объект схемы) и поднимает его в пространство типов; z.infer затем разворачивает его в объектный тип. Одна правка схемы — добавить editedAt — и каждый выведенный тип меняется вместе с ней. Нет второго объявления, которое можно забыть.

Вход для создания — строгое подмножество, и его мы тоже выводим, а не пишем руками (юнит 05 Pick/Omit, юнит 02 объектные типы):

export const NewComment = Comment.pick({ threadId: true, body: true, authorId: true });
export type NewComment = z.infer<typeof NewComment>;
//          ^? { threadId: string; body: string; authorId: string }

Моделируй результат дискриминированным объединением, обрабатывай исчерпывающе (юнит 02)

Когда ты возвращаешь Comment | null, вызывающая сторона знает, что вызов провалился, но не почему — и эта потерянная информация выливается в общие сообщения об ошибках и в оборонительные цепочки if, которые всё равно покрывают не все случаи. createComment может завершиться успехом, упереться в ошибку валидации или в несуществующий тред. Не возвращай Comment | null, теряя почему не вышло — смоделируй исходы дискриминированным объединением (discriminated union — объединение с общим дискриминирующим полем-тегом) по литеральному ключу tag (юнит 02), чтобы сужение по tag сообщало компилятору, какие именно остальные поля есть:

type CreateResult =
  | { tag: "created"; comment: Comment }
  | { tag: "invalid"; issues: string[] }
  | { tag: "thread_missing"; threadId: string };

function describe(r: CreateResult): string {
  switch (r.tag) {
    case "created":        return `#${r.comment.id}`;     // r.comment в области видимости
    case "invalid":        return r.issues.join(", ");    // r.issues в области видимости
    case "thread_missing": return `no thread ${r.threadId}`;
    default: {
      // Страж исчерпываемости: если добавить новый tag и не обработать его,
      // `r` здесь перестаёт быть `never`, и эта строка не скомпилируется.
      const _exhaustive: never = r;
      return _exhaustive;
    }
  }
}

Присваивание в never — приём из юнита 02: в полностью обработанном switch анализ потока управления сужает r до never в default, и присваивание проходит проверку. Когда позже добавишь четвёртый вариант и забудешь case — r станет этим вариантом, несовместимым с never, и компилятор укажет на точную дыру, а не даст необработанному случаю молча провалиться насквозь.

Валидируй на границе — типы лишь обещания, пока не проверены (юнит 08)

Вот ход, отделяющий настоящую типобезопасность от театра. Драйвер БД отдаёт вам unknown (или хуже — any). Статическая аннотация на этом значении — обещание, которого рантайм не давал (юнит 08 и тезис о стирании типов из юнита 00). Вы делаете обещание истинным разбором (parse), а не приведением:

declare function dbQuery(sql: string, args: unknown[]): Promise<unknown[]>;

async function listComments(threadId: string): Promise<Comment[]> {
  const rows = await dbQuery("select * from comments where thread_id = $1", [threadId]);
  //    ^? unknown[]  — драйвер ничего не знает о нашей форме

  // НЕПРАВИЛЬНО (так не делайте — это анти-паттерн из юнита 08):
  // return rows as Comment[];   // ложь: ноль проверок в рантайме, createdAt всё ещё строка

  // ПРАВИЛЬНО: разбор на границе. z.array(Comment) приводит createdAt и отбрасывает мусор.
  return z.array(Comment).parse(rows);
  //     ^? Comment[]   — теперь тип *заработан*, а не заявлен
}

as Comment[] скомпилируется, а затем взорвётся в рантайме при первом же createdAt, который оказался строкой, а не Date. parse превращает кривую строку в брошенный ZodError на границе, где можно залогировать и вернуть 400 — вместо загадочного .getTime is not a function на три слоя глубже.

Один маленький дженерик, в меру умный (юниты 03, 04, 05)

Эндпойнт списка постраничный, и каждый постраничный эндпойнт делит общую форму. Захвати её один раз дженериком — но держи скучной. Это урок сдержанности из юнита 05: дженерик зарабатывает место, убирая дублирование, а не красуясь гимнастикой условных типов, которая взрывает время компиляции.

// Одна переиспользуемая форма. `T` выводится в месте вызова, но тело остаётся
// простым объектом (юнит 03 дженерик-функции, юнит 04 система типов,
// юнит 05 «остановись, пока не стало умно»).
interface Paginated<T> {
  items: T[];
  nextCursor: string | null;
  total: number;
}

function makePage<T>(items: T[], total: number, nextCursor: string | null): Paginated<T> {
  return { items, total, nextCursor };
}

const page = makePage(await listComments("t-1"), 42, "cursor-43");
//    ^? Paginated<Comment>
page.items[0].body;   // полностью типизировано; T выведен как Comment из аргумента

T выводится из аргумента items — без аннотации в месте вызова. Мы намеренно не потянулись за DeepPartial<T> или условным кодировщиком курсора: по юниту 05 эта умность стоит понятности для читателя и времени компиляции (глубоко рекурсивные условные типы — реальный обрыв производительности) и не даёт ничего, что команде нужно здесь. В меру умно = минимум, убивающий дублирование.

satisfies для таблицы маршрутов; страж типа на границе авторизации (юнит 06)

Таблица маршрутов — это конфиг: вы хотите сохранить литеральные типы каждого обработчика (чтобы routes.listComments держал точную сигнатуру), при этом проверив весь объект на соответствие контракту. Ровно для этого и нужен satisfies (юнит 06, TS 4.9+) — : RouteTable расширил бы значения; satisfies RouteTable проверяет без расширения:

type Handler = (input: unknown) => Promise<unknown>;
type RouteTable = Record<string, Handler>;

const routes = {
  createComment: async (input: unknown) => z.array(Comment).parse([]),
  listComments:  async (input: unknown) => listComments(NewComment.parse(input).threadId),
} satisfies RouteTable;

// Ключи остаются литеральными — автодополнение знает "createComment" | "listComments",
// а не просто `string`, ведь `satisfies` проверил форму без расширения.
type RouteName = keyof typeof routes;
//   ^? "createComment" | "listComments"

На границе авторизации пользовательский страж типа (юнит 06) сужает неаутентифицированный запрос до аутентифицированного на весь остаток обработчика:

type Ctx = { userId: string | null };
function isAuthed(ctx: Ctx): ctx is Ctx & { userId: string } {
  return ctx.userId !== null;
}
// после `if (isAuthed(ctx))` ctx.userId — это `string`, а не `string | null`.

Поток между клиентом и сервером: выведи клиент, не переобъявляй его (юнит 08)

Вознаграждение. С tRPC-подобным серверным роутером (tRPC — библиотека для типобезопасного RPC между клиентом и сервером без дополнительной схемы) тип клиента выводится из сервера, так что форма комментария, объявленная один раз в схеме, доходит до React-компонента без единого переобъявления (юнит 08 trpc-end-to-end). Перетипизация ответа на клиенте — то самое дублирование, которое мы весь урок убивали:

// server.ts — форма роутера это просто объект процедур
const appRouter = {
  comments: {
    list: (input: { threadId: string }): Promise<Comment[]> => listComments(input.threadId),
    create: (input: NewComment): Promise<CreateResult> => { throw new Error("impl elided"); },
  },
};
export type AppRouter = typeof appRouter;   // контракт, выведенный, а не написанный

// client.tsx — клиент типизируется ИЗ AppRouter; здесь форма не переобъявляется
declare const trpc: {
  comments: { list: { useQuery: (i: { threadId: string }) => { data?: Comment[] } } };
};

function CommentList({ threadId }: { threadId: string }) {
  const { data } = trpc.comments.list.useQuery({ threadId });
  //      ^? Comment[] | undefined   — выведено насквозь из единственной схемы
  return data?.map((c) => c.body) ?? [];   // c это Comment, полностью типизирован
}

Поменяйте body на text в схеме zod — и React-компонент перестанет компилироваться: контракт по проводу обеспечивается выводом, а не дисциплиной. Про окружающую систему смотрите React Server Components и потоковую передачу Suspense (frontend) — где эти данные загружаются и рендерятся, и Моделирование REST-ресурсов (apis) — про форму эндпойнта, если вы отдаёте REST вместо tRPC.

Чего НЕ делать — переформулированные ловушки юнита 08

• Никакого as на границе. rows as Comment[] — непроверенная ложь; z.array(Comment).parse(rows) зарабатывает тип. Единственное, что as покупает на границе, — это рантайм-сбой позже, дальше от причины.
• Выводи, не дублируй. Если форма комментария появляется более чем в одном рукописном месте, удаление поля становится ручной охотой. Схема → z.infer → Pick/Omit → typeof appRouter означает: одна правка расходится по всему.
• Следи за производительностью вывода. Умный дженерик, который вы не написали, стоит ноль времени компиляции. Глубоко рекурсивные условные/маппированные типы (юнит 05) могут застопорить tsc и подсказки редактора — тянитесь к ним, только когда простой интерфейс действительно не может выразить форму.