Добавление и изменение через действия

Здесь будет встроен видео-разбор темы (5–7 минут, YouTube / RuTube / VK Видео) — тем, кто лучше воспринимает на слух, текст ниже не обязателен.

Всё, что проект умел до сих пор, — это чтение: listTasks() в серверном компоненте и getTask(id) на странице задачи. Запись начинается с двух операций, и обе живут не в компоненте, а в отдельном файле.

Файл	Что в нём
`lib/tasks.ts`	доступ к данным: к `listTasks` и `getTask` добавляются `createTask` и `setStatus`
`app/board/actions.ts`	действия: разбор входа, вызов хранилища, `revalidatePath`
`app/board/page.tsx`	серверный компонент: читает список и отдаёт его клиентскому
`app/board/board.tsx`	`"use client"`: форма, наложение и кнопки статуса

Отдельный файл — не вкусовщина. Действие нужно и серверной странице, и клиентскому компоненту, а "use server" в прологе файла делает вызываемым из браузера каждый его экспорт. Вот каркас обоих действий: тела хранилища здесь только объявлены, потому что песочница выполняет один файл, а не проект.

tsx

// ── app/board/actions.ts ── в проекте файл начинается с импортов:
// revalidatePath из "next/cache" и доступ к данным из "@/lib/tasks".
// Песочница выполняет один файл, поэтому здесь они только объявлены
"use server";

const STATUSES = ["todo", "doing", "done"] as const;
type Status = (typeof STATUSES)[number];

interface Task {
  id: string;
  title: string;
  status: Status;
}

declare function createTask(title: string): Promise<Task>;
declare function setStatus(id: string, status: Status): Promise<void>;
declare function revalidatePath(path: string): void;
// разбор входа напишем в следующем разделе — пока только подписи
declare function isStatus(value: unknown): value is Status;
declare function parseTitle(value: unknown): { ok: true; value: string } | { ok: false; error: string };

// то, что действие вернёт форме: размеченное объединение из части III
type FormState =
  | { status: "idle" }
  | { status: "error"; title: string; message: string }
  | { status: "ok"; title: string };

// первым аргументом идёт предыдущее состояние — подпись под useActionState
async function addTask(prev: FormState, form: FormData): Promise<FormState> {
  const raw = form.get("title");
  const parsed = parseTitle(raw);
  if (!parsed.ok) {
    // введённое возвращается наружу: после отправки форма сбрасывается,
    // и вернуть текст в поле она сможет только из состояния
    return { status: "error", title: typeof raw === "string" ? raw : "", message: parsed.error };
  }
  const task = await createTask(parsed.value);
  // без этой строки страница соберётся из прежних данных
  revalidatePath("/board");
  return { status: "ok", title: task.title };
}

// второе действие — кнопка: возвращать нечего, id привязан заранее
async function moveTask(id: string, form: FormData): Promise<void> {
  const next = form.get("status");
  if (!isStatus(next)) return;
  await setStatus(id, next);
  revalidatePath("/board");
}

// ── app/board/actions.ts ── в проекте файл начинается с импортов:
// revalidatePath из "next/cache" и доступ к данным из "@/lib/tasks".
// Песочница выполняет один файл, поэтому здесь они только объявлены
"use server";

const STATUSES = ["todo", "doing", "done"] as const;
type Status = (typeof STATUSES)[number];

interface Task {
  id: string;
  title: string;
  status: Status;
}

declare function createTask(title: string): Promise<Task>;
declare function setStatus(id: string, status: Status): Promise<void>;
declare function revalidatePath(path: string): void;
// разбор входа напишем в следующем разделе — пока только подписи
declare function isStatus(value: unknown): value is Status;
declare function parseTitle(value: unknown): { ok: true; value: string } | { ok: false; error: string };

// то, что действие вернёт форме: размеченное объединение из части III
type FormState =
  | { status: "idle" }
  | { status: "error"; title: string; message: string }
  | { status: "ok"; title: string };

// первым аргументом идёт предыдущее состояние — подпись под useActionState
async function addTask(prev: FormState, form: FormData): Promise<FormState> {
  const raw = form.get("title");
  const parsed = parseTitle(raw);
  if (!parsed.ok) {
    // введённое возвращается наружу: после отправки форма сбрасывается,
    // и вернуть текст в поле она сможет только из состояния
    return { status: "error", title: typeof raw === "string" ? raw : "", message: parsed.error };
  }
  const task = await createTask(parsed.value);
  // без этой строки страница соберётся из прежних данных
  revalidatePath("/board");
  return { status: "ok", title: task.title };
}

// второе действие — кнопка: возвращать нечего, id привязан заранее
async function moveTask(id: string, form: FormData): Promise<void> {
  const next = form.get("status");
  if (!isStatus(next)) return;
  await setStatus(id, next);
  revalidatePath("/board");
}

страница примера

Сначала предположите, что выведет код

Три вещи, которые задают весь остаток статьи. Первая: отказ проверки — это возвращённое значение, а не исключение; брошенная ошибка доедет до error.tsx, а в проде превратится в общую фразу. Вторая: второе действие не возвращает ничего — форме-кнопке результат не нужен, ей достаточно, что страница пересоберётся. Третья: id у moveTask стоит первым аргументом, и придёт он не из полей, а из bind.

Действие — это открытый эндпоинт. Разметка вокруг кнопки ничего не решает: проверки живут внутри действия.

Директивы "use client" и "use server" в одном файле не уживаются: первая говорит «этот модуль уезжает в браузер», вторая — «эти функции остаются на сервере». Поэтому клиентская часть доски действия только импортирует.

tsx

// ── app/board/board.tsx ── клиентская часть доски
"use client";

// действия приезжают обычным импортом; в браузер уедет не их код,
// а идентификаторы — это разбиралось в статье про Server Actions
// import { addTask, moveTask } from "./actions";

declare function addTask(prev: string, form: FormData): Promise<string>;

function Board() {
  const [message, formAction] = React.useActionState(addTask, "");
  return (
    <form action={formAction}>
      <input name="title" />
      <button>добавить</button>
      <p>{message}</p>
    </form>
  );
}

страница примера

Сначала предположите, что выведет код

Второй способ — объявить действие прямо в серверном компоненте, с "use server" первой строкой в теле функции. Для доски он неудобен: одно и то же действие нужно и списку, и странице задачи.

Статус задачи на доске — не строка, а один из трёх литералов. Из формы же приезжает FormDataEntryValue | null: строка, файл или ничего. Прогноз перед запуском: на что здесь пожалуется компилятор — и что при этом напечатает пример?

tsx

// список статусов и тип из него — приём части III: as const превращает массив
// в кортеж литералов, а (typeof …)[number] достаёт из него объединение
const STATUSES = ["todo", "doing", "done"] as const;
type Status = (typeof STATUSES)[number];

function setStatus(id: string, status: Status): void {
  console.log("переносим", id, "в", status);
}

// то же, что приедет в действие: поля формы, собранные браузером
const form = new FormData();
form.append("status", "done");

const raw = form.get("status");
console.log("пришло:", raw, "| тип:", typeof raw);

setStatus("t1", String(raw));

const value = String(raw);
if (STATUSES.includes(value)) setStatus("t1", value);

страница примера

Сначала предположите, что выведет код

Отметок будет три, на двух строках. Первая ожидаема: String(raw) даёт string, а setStatus просит одно из трёх слов. Две другие стоят на одной строке — и обе интереснее. Ругается сам includes: у кортежа, замороженного через as const, тип элемента — то же объединение трёх литералов, и метод требует аргумент этого же типа. Проверка, которая должна была доказать, что строка годится, отказывается принимать недоказанную строку.

Третья отметка — на setStatus внутри if, и она объясняет, почему одной проверкой дело не кончается: includes возвращает boolean, а не сужение, и в теле условия значение осталось всё той же string. Сужать умеет предикат из статьи «Свои проверки типа: предикаты is и assert» — функция, которая отвечает не «да/нет», а «да, и это Status».

tsx

const STATUSES = ["todo", "doing", "done"] as const;
type Status = (typeof STATUSES)[number];

// предикат из части III: одна функция и проверяет значение, и сужает тип
function isStatus(value: unknown): value is Status {
  // это расширение, а не сужение: as здесь ничего не скрывает, а лишь
  // разрешает includes принять произвольную строку
  return typeof value === "string" && (STATUSES as readonly string[]).includes(value);
}

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

function parseTitle(value: unknown): Parsed<string> {
  if (typeof value !== "string") return { ok: false, error: "название не пришло строкой" };
  const title = value.trim();
  if (title.length === 0 || title.length > 60) return { ok: false, error: "название: от 1 до 60 символов" };
  return { ok: true, value: title };
}

const honest = new FormData();
honest.append("title", "  сверстать доску  ");
honest.append("status", "doing");
console.log(parseTitle(honest.get("title")));
console.log("статус годится:", isStatus(honest.get("status")));

const hostile = new FormData();
// поле подменили в инспекторе: под именем title уехал файл
hostile.append("title", new Blob(["картинка"]), "photo.png");
hostile.append("status", "deleted");
console.log(parseTitle(hostile.get("title")));
console.log("статус годится:", isStatus(hostile.get("status")));
console.log("поля вовсе нет:", isStatus(new FormData().get("status")));

const STATUSES = ["todo", "doing", "done"] as const;
type Status = (typeof STATUSES)[number];

// предикат из части III: одна функция и проверяет значение, и сужает тип
function isStatus(value: unknown): value is Status {
  // это расширение, а не сужение: as здесь ничего не скрывает, а лишь
  // разрешает includes принять произвольную строку
  return typeof value === "string" && (STATUSES as readonly string[]).includes(value);
}

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

const honest = new FormData();
honest.append("title", "  сверстать доску  ");
honest.append("status", "doing");
console.log(parseTitle(honest.get("title")));
console.log("статус годится:", isStatus(honest.get("status")));

const hostile = new FormData();
// поле подменили в инспекторе: под именем title уехал файл
hostile.append("title", new Blob(["картинка"]), "photo.png");
hostile.append("status", "deleted");
console.log(parseTitle(hostile.get("title")));
console.log("статус годится:", isStatus(hostile.get("status")));
console.log("поля вовсе нет:", isStatus(new FormData().get("status")));

страница примера

Сначала предположите, что выведет код

Обратите внимание на as внутри предиката: он расширяет кортеж до readonly string[], а не сужает что-то до нужного типа. Такое утверждение ничего не прячет — оно лишь разрешает includes принять произвольную строку, и после него проверка остаётся настоящей. Утверждения вида value as Status, наоборот, гасят ровно ту диагностику, ради которой всё и затевалось.

parseTitle устроен так же: сначала typeof отсекает и null (поля нет), и File (поле подменили на type="file"), и только потом строка обрезается и меряется. Наружу уходит размеченное объединение — тот же приём, что и в разборе входных данных из части III.

Правило доски: в базу не попадает ничего, что не прошло через parseTitle или isStatus.

STATUSES нужен не только проверке. Из него же берутся колонки и их порядок, а подписи держит Record<Status, string> — забыть колонку компилятор не даст.

tsx

const STATUSES = ["todo", "doing", "done"] as const;
type Status = (typeof STATUSES)[number];

// подписи выводятся из типа: забыть колонку компилятор не даст,
// а лишний ключ подсветит сразу
const COLUMNS: Record<Status, string> = {
  todo: "Сделать",
  doing: "В работе",
  done: "Готово"
};

interface Task {
  id: string;
  title: string;
  status: Status;
}

const tasks: Task[] = [
  { id: "t1", title: "сверстать доску", status: "todo" },
  { id: "t2", title: "написать действия", status: "done" }
];

// тот же кортеж рисует колонки — порядок доски задан в одном месте
for (const status of STATUSES) {
  const inColumn = tasks.filter((task) => task.status === status);
  console.log(COLUMNS[status] + ":", inColumn.length);
}

страница примера

Сначала предположите, что выведет код

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

Прогноз перед запуском: что останется в поле после отказа и что — после успешного добавления?

tsx

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

interface Task {
  id: string;
  title: string;
}

// сервера в песочнице нет: базу изображает массив, дорогу до неё — таймер
const stored: Task[] = [];

type FormState =
  | { status: "idle" }
  | { status: "error"; title: string; message: string }
  | { status: "ok" };

async function addTask(prev: FormState, form: FormData): Promise<FormState> {
  const raw = form.get("title");
  const title = typeof raw === "string" ? raw.trim() : "";
  if (title.length < 3) {
    // отказ — обычный возврат: вместе с текстом ошибки едет и введённое
    return { status: "error", title, message: "название: минимум 3 символа" };
  }
  await wait(300);
  stored.push({ id: "t" + (stored.length + 1), title });
  return { status: "ok" };
}

function AddForm() {
  const initial: FormState = { status: "idle" };
  const [state, formAction, isPending] = React.useActionState(addTask, initial);
  return (
    <form action={formAction}>
      <input name="title" defaultValue={state.status === "error" ? state.title : ""} />
      <button id="send" disabled={isPending}>{isPending ? "сохраняем…" : "добавить"}</button>
      {state.status === "error" && <p>{state.message}</p>}
      <p>в базе: {stored.length}</p>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<AddForm />);

const field = () => document.querySelector("input") as HTMLInputElement;
const send = (value: string) => {
  field().value = value;
  document.getElementById("send")!.click();
};

// сценарий за читателя: сперва слишком короткое название, потом годное.
// пробелы вокруг «да» напечатаны нарочно — по ним видно, откуда взялся текст
void (async () => {
  await wait(100);
  send("  да  ");
  await wait(400);
  console.log("после отказа в поле:", JSON.stringify(field().value));
  send("сверстать доску");
  await wait(600);
  console.log("после успеха в поле:", JSON.stringify(field().value), "| в базе:", stored.length);
})();

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

interface Task {
  id: string;
  title: string;
}

// сервера в песочнице нет: базу изображает массив, дорогу до неё — таймер
const stored: Task[] = [];

type FormState =
  | { status: "idle" }
  | { status: "error"; title: string; message: string }
  | { status: "ok" };

async function addTask(prev: FormState, form: FormData): Promise<FormState> {
  const raw = form.get("title");
  const title = typeof raw === "string" ? raw.trim() : "";
  if (title.length < 3) {
    // отказ — обычный возврат: вместе с текстом ошибки едет и введённое
    return { status: "error", title, message: "название: минимум 3 символа" };
  }
  await wait(300);
  stored.push({ id: "t" + (stored.length + 1), title });
  return { status: "ok" };
}

ReactDOM.createRoot(document.getElementById("root")!).render(<AddForm />);

const field = () => document.querySelector("input") as HTMLInputElement;
const send = (value: string) => {
  field().value = value;
  document.getElementById("send")!.click();
};

// сценарий за читателя: сперва слишком короткое название, потом годное.
// пробелы вокруг «да» напечатаны нарочно — по ним видно, откуда взялся текст
void (async () => {
  await wait(100);
  send("  да  ");
  await wait(400);
  console.log("после отказа в поле:", JSON.stringify(field().value));
  send("сверстать доску");
  await wait(600);
  console.log("после успеха в поле:", JSON.stringify(field().value), "| в базе:", stored.length);
})();

страница примера

Сначала предположите, что выведет код

После отказа в поле стоит «да» — без пробелов, которые мы туда напечатали. Значит, текст не «остался», а приехал: форма сброшена, но defaultValue к моменту сброса уже другой — действие вернуло обрезанное название в состоянии, и разметка подставила его обратно. После успеха действие возвращает { status: "ok" } без текста, defaultValue становится пустым — и поле очищается само, без reset().

Ошибка здесь — обычное значение, поэтому её видно и в разметке, и в типах: state.message существует только в варианте error, и обратиться к нему мимо проверки компилятор не даст. Это тот же разбор вариантов, что был в useReducer, только редьюсер асинхронный и живёт на сервере.

required и minLength из части II остаются: они ловят опечатку до сети и не дают отправить пустую форму. Но действие — открытый адрес, и запрос к нему приходит и мимо браузера, поэтому те же границы повторяются в parseTitle.

tsx

interface FieldProps {
  defaultValue: string;
}

// разметка отсекает опечатки, но проверку в действии она не отменяет:
// required и minLength живут в браузере, а действие зовут и мимо браузера
function TitleField({ defaultValue }: FieldProps) {
  return <input name="title" defaultValue={defaultValue} required minLength={3} maxLength={60} />;
}

страница примера

Сначала предположите, что выведет код

Между кликом и новым списком проходит время: запись в базу, пересборка страницы, дорога обратно. Полсекунды экран честно показывает старое — карточки нет, будто кнопка не нажалась. useOptimistic рисует ожидаемое сразу, а когда действие заканчивается, отпускает нарисованное.

Прогноз: сколько карточек в списке через 200 мс после клика и сколько — через 700 мс?

tsx

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

interface Task {
  id: string;
  title: string;
}

function Board() {
  // в проекте этот список приезжает пропсом из серверного компонента;
  // здесь его изображает состояние
  const [tasks, setTasks] = React.useState<Task[]>([{ id: "t1", title: "сверстать доску" }]);
  // useOptimistic — не второе хранилище, а наложение поверх первого
  const [shown, addDraft] = React.useOptimistic(tasks, (current: Task[], title: string) => [
    ...current,
    // временный id: настоящий выдаст база, а рисовать надо сейчас
    { id: "draft", title }
  ]);

  const add = async (form: FormData) => {
    const title = String(form.get("title") ?? "");
    addDraft(title);
    await wait(500); // здесь была бы запись в базу и revalidatePath
    setTasks((prev) => [...prev, { id: "t" + (prev.length + 1), title }]);
  };

  return (
    <form action={add}>
      <input name="title" defaultValue="" />
      <button id="send">добавить</button>
      <ul>
        {shown.map((task) => (
          <li key={task.id}>{task.title}{task.id === "draft" ? " …" : ""}</li>
        ))}
      </ul>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Board />);

const cards = () => Array.from(document.querySelectorAll("li")).map((li) => li.textContent).join(" | ");

void (async () => {
  await wait(100);
  (document.querySelector("input") as HTMLInputElement).value = "написать действия";
  document.getElementById("send")!.click();
  await wait(200);
  console.log("через 200 мс:", cards());
  await wait(500);
  console.log("через 700 мс:", cards());
})();

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

interface Task {
  id: string;
  title: string;
}

function Board() {
  // в проекте этот список приезжает пропсом из серверного компонента;
  // здесь его изображает состояние
  const [tasks, setTasks] = React.useState<Task[]>([{ id: "t1", title: "сверстать доску" }]);
  // useOptimistic — не второе хранилище, а наложение поверх первого
  const [shown, addDraft] = React.useOptimistic(tasks, (current: Task[], title: string) => [
    ...current,
    // временный id: настоящий выдаст база, а рисовать надо сейчас
    { id: "draft", title }
  ]);

const add = async (form: FormData) => {
    const title = String(form.get("title") ?? "");
    addDraft(title);
    await wait(500); // здесь была бы запись в базу и revalidatePath
    setTasks((prev) => [...prev, { id: "t" + (prev.length + 1), title }]);
  };

return (
    <form action={add}>
      <input name="title" defaultValue="" />
      <button id="send">добавить</button>
      <ul>
        {shown.map((task) => (
          <li key={task.id}>{task.title}{task.id === "draft" ? " …" : ""}</li>
        ))}
      </ul>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Board />);

const cards = () => Array.from(document.querySelectorAll("li")).map((li) => li.textContent).join(" | ");

void (async () => {
  await wait(100);
  (document.querySelector("input") as HTMLInputElement).value = "написать действия";
  document.getElementById("send")!.click();
  await wait(200);
  console.log("через 200 мс:", cards());
  await wait(500);
  console.log("через 700 мс:", cards());
})();

страница примера

Сначала предположите, что выведет код

Наложение — не второе хранилище: shown вычисляется из tasks и живёт ровно столько, сколько идёт действие. Поэтому у него есть неприятная изнанка, на которой в проекте спотыкаются все.

Следующий пример — та же доска, но действие честно пишет в базу и не зовёт revalidatePath. Прогноз: что покажет список после того, как действие закончится, и что при этом будет лежать в базе?

tsx

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

interface Task {
  id: string;
  title: string;
}

// «база» — массив вне компонента, как хранилище на сервере
const stored: Task[] = [{ id: "t1", title: "сверстать доску" }];

function Board() {
  const [tasks] = React.useState<Task[]>(() => stored.slice());
  const [shown, addDraft] = React.useOptimistic(tasks, (current: Task[], title: string) => [
    ...current,
    { id: "draft", title }
  ]);

  const add = async (form: FormData) => {
    const title = String(form.get("title") ?? "");
    addDraft(title);
    await wait(400);
    stored.push({ id: "t" + (stored.length + 1), title });
  };

  return (
    <form action={add}>
      <input name="title" defaultValue="" />
      <button id="send">добавить</button>
      <ul>
        {shown.map((task) => (
          <li key={task.id}>{task.title}</li>
        ))}
      </ul>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Board />);

const cards = () => document.querySelectorAll("li").length;

void (async () => {
  await wait(100);
  (document.querySelector("input") as HTMLInputElement).value = "написать действия";
  document.getElementById("send")!.click();
  await wait(200);
  console.log("пока действие идёт, карточек:", cards());
  await wait(500);
  console.log("после конца действия карточек:", cards(), "| в базе:", stored.length);
})();

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

interface Task {
  id: string;
  title: string;
}

// «база» — массив вне компонента, как хранилище на сервере
const stored: Task[] = [{ id: "t1", title: "сверстать доску" }];

function Board() {
  const [tasks] = React.useState<Task[]>(() => stored.slice());
  const [shown, addDraft] = React.useOptimistic(tasks, (current: Task[], title: string) => [
    ...current,
    { id: "draft", title }
  ]);

const add = async (form: FormData) => {
    const title = String(form.get("title") ?? "");
    addDraft(title);
    await wait(400);
    stored.push({ id: "t" + (stored.length + 1), title });
  };

return (
    <form action={add}>
      <input name="title" defaultValue="" />
      <button id="send">добавить</button>
      <ul>
        {shown.map((task) => (
          <li key={task.id}>{task.title}</li>
        ))}
      </ul>
    </form>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Board />);

const cards = () => document.querySelectorAll("li").length;

void (async () => {
  await wait(100);
  (document.querySelector("input") as HTMLInputElement).value = "написать действия";
  document.getElementById("send")!.click();
  await wait(200);
  console.log("пока действие идёт, карточек:", cards());
  await wait(500);
  console.log("после конца действия карточек:", cards(), "| в базе:", stored.length);
})();

страница примера

Сначала предположите, что выведет код

Карточка мигнула и пропала, хотя запись прошла. Наложение отпустилось — а источник, из которого рисуется список, остался прежним. В Next.js этот источник обновляет не setState, а revalidatePath внутри действия: он помечает адрес устаревшим, страница собирается заново, и к моменту, когда наложение исчезает, под ним уже лежат новые данные. Без этой строки useOptimistic выглядит как сломанный, хотя сломано соседнее.

Диагноз простой: если карточка появляется и исчезает, а после перезагрузки страницы она на месте — забыли пометить адрес устаревшим.

У нарисованной заранее карточки ещё нет настоящего id — его выдаст база. Временный ключ должен не совпасть ни с соседним черновиком, ни с будущим идентификатором из базы.

tsx

interface Task {
  id: string;
  title: string;
}

const tasks: Task[] = [{ id: "t1", title: "сверстать доску" }];

// id черновика станет ключом в списке, а при одинаковых ключах React пожалуется
// в консоль браузера и перепутает узлы при перерисовке
const badDraft = (current: Task[], title: string): Task[] => [...current, { id: "draft", title }];

// ключ, который не столкнётся ни с соседним черновиком, ни с id из базы
const goodDraft = (current: Task[], title: string): Task[] => [
  ...current,
  { id: "draft-" + current.length, title }
];

console.log(badDraft(badDraft(tasks, "первая"), "вторая").map((task) => task.id));
console.log(goodDraft(goodDraft(tasks, "первая"), "вторая").map((task) => task.id));

страница примера

Сначала предположите, что выведет код

Вторая операция устроена иначе: полей для ввода нет, есть кнопка внутри карточки. Форма всё равно нужна — она собирает FormData и зовёт действие, — но состоит из скрытого поля и кнопки. Задача, которую переносим, приходит не полем, а привязкой: move.bind(null, task.id).

Прогноз: что напечатают строки про «Готово» через 200 мс и через 700 мс после клика — и что покажет строка рендера про сервер и экран?

tsx

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

const STATUSES = ["todo", "doing", "done"] as const;
type Status = (typeof STATUSES)[number];
const COLUMNS: Record<Status, string> = { todo: "Сделать", doing: "В работе", done: "Готово" };

function isStatus(value: unknown): value is Status {
  return typeof value === "string" && (STATUSES as readonly string[]).includes(value);
}

interface Task {
  id: string;
  title: string;
  status: Status;
}

interface Move {
  id: string;
  status: Status;
}

function Board() {
  const [tasks, setTasks] = React.useState<Task[]>([
    { id: "t1", title: "сверстать доску", status: "todo" },
    { id: "t2", title: "написать действия", status: "todo" }
  ]);
  // наложение живёт у списка, а не в карточке: перенос — событие сразу двух
  // колонок, да и сама карточка при переезде размонтируется
  const [shown, applyMove] = React.useOptimistic(tasks, (current: Task[], move: Move) =>
    current.map((task) => (task.id === move.id ? { ...task, status: move.status } : task))
  );
  const inDone = (list: Task[]) => list.filter((task) => task.status === "done").length;
  console.log("рендер | с сервера в «Готово»:", inDone(tasks), "| на экране:", inDone(shown));

  // id привязан заранее, из формы приезжает только новый статус
  const move = async (id: string, form: FormData) => {
    const next = form.get("status");
    if (!isStatus(next)) return; // мусор из подменённого поля просто отбрасываем
    applyMove({ id, status: next });
    await wait(500); // здесь setStatus и revalidatePath
    setTasks((prev) => prev.map((task) => (task.id === id ? { ...task, status: next } : task)));
  };

  return (
    <div>
      {STATUSES.map((status) => (
        <section key={status}>
          <h3>{COLUMNS[status]}</h3>
          <ul>
            {shown
              .filter((task) => task.status === status)
              .map((task) => (
                <li key={task.id}>
                  {task.title}
                  <form action={move.bind(null, task.id)}>
                    <input type="hidden" name="status" defaultValue="done" />
                    <button id={task.id + "-done"}>готово</button>
                  </form>
                </li>
              ))}
          </ul>
        </section>
      ))}
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Board />);

const done = () => document.querySelectorAll("section")[2].querySelectorAll("li").length;

void (async () => {
  await wait(100);
  document.getElementById("t2-done")!.click();
  await wait(200);
  console.log("через 200 мс в «Готово»:", done());
  await wait(500);
  console.log("через 700 мс в «Готово»:", done());
})();

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));

const STATUSES = ["todo", "doing", "done"] as const;
type Status = (typeof STATUSES)[number];
const COLUMNS: Record<Status, string> = { todo: "Сделать", doing: "В работе", done: "Готово" };

function isStatus(value: unknown): value is Status {
  return typeof value === "string" && (STATUSES as readonly string[]).includes(value);
}

interface Task {
  id: string;
  title: string;
  status: Status;
}

interface Move {
  id: string;
  status: Status;
}

// id привязан заранее, из формы приезжает только новый статус
  const move = async (id: string, form: FormData) => {
    const next = form.get("status");
    if (!isStatus(next)) return; // мусор из подменённого поля просто отбрасываем
    applyMove({ id, status: next });
    await wait(500); // здесь setStatus и revalidatePath
    setTasks((prev) => prev.map((task) => (task.id === id ? { ...task, status: next } : task)));
  };

return (
    <div>
      {STATUSES.map((status) => (
        <section key={status}>
          <h3>{COLUMNS[status]}</h3>
          <ul>
            {shown
              .filter((task) => task.status === status)
              .map((task) => (
                <li key={task.id}>
                  {task.title}
                  <form action={move.bind(null, task.id)}>
                    <input type="hidden" name="status" defaultValue="done" />
                    <button id={task.id + "-done"}>готово</button>
                  </form>
                </li>
              ))}
          </ul>
        </section>
      ))}
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Board />);

const done = () => document.querySelectorAll("section")[2].querySelectorAll("li").length;

void (async () => {
  await wait(100);
  document.getElementById("t2-done")!.click();
  await wait(200);
  console.log("через 200 мс в «Готово»:", done());
  await wait(500);
  console.log("через 700 мс в «Готово»:", done());
})();

страница примера

Сначала предположите, что выведет код

Две последние строки рендера одинаковы, и это хорошая новость: сначала наложение рисует карточку поверх уже обновлённого списка, потом снимается — и на экране ничего не меняется, потому что настоящие данные совпали с нарисованными. Именно так выглядит удачное предсказание: перерисовки не видно.

Наложение объявлено у списка, а не в карточке, и это принципиально. Во-первых, перенос — событие сразу двух колонок: карточка не знает, куда её переставляют. Во-вторых, при переезде карточка размонтируется, а вместе с ней исчезло бы и её собственное состояние — включая наложение, которое как раз и должно пережить этот момент.

Скрытое поле здесь несёт статус, а не идентификатор задачи. Разница не косметическая: поле легко переписать в инспекторе, поэтому статус проходит через isStatus, а id вообще не едет из браузера — он замкнут в привязке на сервере. Что бывает, когда про bind забывают, компилятор показывает сам.

tsx

interface CardProps {
  id: string;
  title: string;
}

async function moveTask(id: string, form: FormData): Promise<void> {
  console.log("переносим", id, "в", form.get("status"));
}

function Card({ id, title }: CardProps) {
  return (
    <form action={moveTask}>
      <input type="hidden" name="status" defaultValue="done" />
      <button>{title}: готово</button>
    </form>
  );
}

страница примера

Сначала предположите, что выведет код

Диагностика заканчивается неожиданно вывернутой фразой: «Целевая подпись предоставляет слишком мало аргументов. Ожидал 2 или больше, но получил 1». Читать её надо со стороны разметки: action обещает вызвать функцию с одной FormData, а подсунутая функция ждёт два аргумента. bind как раз и превращает её в функцию одного аргумента.

Собранный путь записи выглядит так — и каждый его шаг знает только своё дело.

Шаг	Где живёт	Что делает
Клик	браузер	форма собирает `FormData` и зовёт действие
Наложение	клиентский компонент	`useOptimistic` рисует ожидаемое
Разбор	действие на сервере	`typeof` и предикат превращают `unknown` в модель
Запись	`lib/tasks.ts`	`createTask`, `setStatus`
Обновление	`revalidatePath`	адрес помечен устаревшим, страница собирается заново
Ответ	`useActionState`	отказ возвращается в форму вместе с введённым

Действия доски лежат в отдельном файле с "use server": их импортируют и серверная страница, и клиентский компонент.
Всё, что приезжает из формы, — unknown: typeof отсекает null и файл, предикат value is Status сужает строку до статуса.
Отказ проверки возвращается из действия значением, а не бросается: вместе с сообщением едет введённый текст, иначе форма после сброса опустеет.
useOptimistic не хранит данные, а накладывает ожидаемое поверх настоящего состояния — и снимает наложение, как только действие закончилось.
Если карточка мигает и пропадает, дело не в наложении: действие не пометило адрес устаревшим через revalidatePath.
Идентификатор задачи привязывается через bind и остаётся на сервере; из браузера едут только те поля, которые можно перепроверить.

1/4Массив статусов объявлен как const STATUSES = ["todo", "doing", "done"] as const. В переменной value лежит string. Что скажет компилятор на STATUSES.includes(value)?

2/4Действие вернуло { status: "error", title: "да", message: "…" }, а в разметке стоит <input name="title" defaultValue={state.status === "error" ? state.title : ""} />. Что окажется в поле после отправки?

3/4Действие добавило задачу в базу, наложение useOptimistic нарисовало карточку. Действие закончилось — карточка пропала, хотя после перезагрузки страницы она на месте. В чём причина?

4/4Действие объявлено как moveTask(id: string, form: FormData) и передано в разметку как <form action={moveTask}>, без bind. Что будет?

Предикат вместо as

Функция isStatus возвращает true на что угодно, и в setStatus попадает статус deleted, которого на доске нет. Перепишите её в настоящий предикат: проверка должна и отсеивать чужие значения, и сужать тип — так, чтобы утверждение raw as Status стало ненужным и его можно было убрать.

tsx

const STATUSES = ["todo", "doing", "done"] as const;
type Status = (typeof STATUSES)[number];

function setStatus(id: string, status: Status): void {
  console.log("переносим", id, "в", status);
}

// ваш код: сделать из этой функции предикат, который сужает тип
function isStatus(value: unknown): boolean {
  return true;
}

const form = new FormData();
form.append("status", "deleted"); // такого статуса на доске нет

const raw = form.get("status");
// as должен исчезнуть вместе с задачей: после настоящего предиката
// компилятор и сам увидит здесь Status
if (isStatus(raw)) setStatus("t1", raw as Status);
console.log("конец"); // сейчас перед этим печатается «переносим t1 в deleted»

страница примера

Сначала предположите, что выведет код

Предикат отличается от обычной проверки типом возврата: value is Status вместо boolean. Внутри — две проверки: строка ли это вообще и есть ли она в списке.

tsлистинг · не запускается

function isStatus(value: unknown): value is Status {
  return typeof value === "string" && (STATUSES as readonly string[]).includes(value);
}

const raw = form.get("status");
if (isStatus(raw)) setStatus("t1", raw); // as больше не нужен: тип сужен
console.log("конец"); // теперь печатается только эта строка

function isStatus(value: unknown): value is Status {
  return typeof value === "string" && (STATUSES as readonly string[]).includes(value);
}

const raw = form.get("status");
if (isStatus(raw)) setStatus("t1", raw); // as больше не нужен: тип сужен
console.log("конец"); // теперь печатается только эта строка

Расширение STATUSES as readonly string[] обязательно: у кортежа as const метод includes принимает только сами литералы. Это единственный безопасный вид утверждения — оно разрешает больше, а не обещает лишнего.

Наложение, которое переносит

Редьюсер наложения возвращает список без изменений, поэтому карточка переезжает в «Готово» только после ответа сервера — через 400 мс. Напишите редьюсер так, чтобы она оказывалась там сразу, а по окончании действия оставалась на месте.

tsx

type Status = "todo" | "doing" | "done";

interface Task {
  id: string;
  title: string;
  status: Status;
}

interface Move {
  id: string;
  status: Status;
}

function Board() {
  const [tasks, setTasks] = React.useState<Task[]>([{ id: "t1", title: "сверстать доску", status: "todo" }]);
  // ваш код: редьюсер должен переносить карточку, а не оставлять список как есть
  const [shown, applyMove] = React.useOptimistic(tasks, (current: Task[], move: Move) => current);

  const move = async (id: string, status: Status) => {
    applyMove({ id, status });
    await new Promise((resolve) => setTimeout(resolve, 400));
    setTasks((prev) => prev.map((task) => (task.id === id ? { ...task, status } : task)));
  };

  return (
    <div>
      {/* кнопка обёрнута формой: наложение держится, пока идёт действие */}
      <form action={() => move("t1", "done")}>
        <button id="go">готово</button>
      </form>
      <p id="out">в «Готово»: {shown.filter((task) => task.status === "done").length}</p>
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Board />);

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
const out = () => document.getElementById("out")!.textContent;

void (async () => {
  await wait(100);
  document.getElementById("go")!.click();
  await wait(200);
  console.log("через 200 мс:", out());
  await wait(500);
  console.log("через 700 мс:", out());
})();
// сейчас: «в «Готово»: 0», затем «в «Готово»: 1» — а нужно, чтобы единица
// появилась уже в первой строке

type Status = "todo" | "doing" | "done";

interface Task {
  id: string;
  title: string;
  status: Status;
}

interface Move {
  id: string;
  status: Status;
}

function Board() {
  const [tasks, setTasks] = React.useState<Task[]>([{ id: "t1", title: "сверстать доску", status: "todo" }]);
  // ваш код: редьюсер должен переносить карточку, а не оставлять список как есть
  const [shown, applyMove] = React.useOptimistic(tasks, (current: Task[], move: Move) => current);

return (
    <div>
      {/* кнопка обёрнута формой: наложение держится, пока идёт действие */}
      <form action={() => move("t1", "done")}>
        <button id="go">готово</button>
      </form>
      <p id="out">в «Готово»: {shown.filter((task) => task.status === "done").length}</p>
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Board />);

const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
const out = () => document.getElementById("out")!.textContent;

void (async () => {
  await wait(100);
  document.getElementById("go")!.click();
  await wait(200);
  console.log("через 200 мс:", out());
  await wait(500);
  console.log("через 700 мс:", out());
})();
// сейчас: «в «Готово»: 0», затем «в «Готово»: 1» — а нужно, чтобы единица
// появилась уже в первой строке

страница примера

Сначала предположите, что выведет код

Редьюсер получает текущий список и описание переноса, а возвращает новый список — тем же map, которым массив в состоянии меняют в статье «Объекты и массивы в состоянии».

jsлистинг · не запускается

const [shown, applyMove] = React.useOptimistic(tasks, (current: Task[], move: Move) =>
  current.map((task) => (task.id === move.id ? { ...task, status: move.status } : task))
);

const [shown, applyMove] = React.useOptimistic(tasks, (current: Task[], move: Move) =>
  current.map((task) => (task.id === move.id ? { ...task, status: move.status } : task))
);

Обе строки вывода теперь показывают единицу. Вторая — уже не наложение: к этому моменту действие закончилось, наложение снято, а карточка лежит в настоящем состоянии, потому что действие его обновило. Если бы не обновило — второй строкой снова стал бы ноль.

Третье действие: удалить

На доске не хватает удаления. Напишите действие deleteTask по образцу moveTask: идентификатор приходит привязкой, из формы не читается ничего, после записи адрес помечается устаревшим. Опишите заодно, каким будет редьюсер наложения для удаления.

tsx

// ── app/board/actions.ts ──
"use server";

declare function removeTask(id: string): Promise<void>;
declare function revalidatePath(path: string): void;

// ваш код: действие удаления. Подпись должна подойти под <form action={…}>
// после привязки id через bind

страница примера

Сначала предположите, что выведет код

Действие получается короче остальных: разбирать нечего — из браузера не приезжает ни одного поля.

tsлистинг · не запускается

export async function deleteTask(id: string): Promise<void> {
  await removeTask(id);
  revalidatePath("/board");
}

export async function deleteTask(id: string): Promise<void> {
  await removeTask(id);
  revalidatePath("/board");
}

Первым аргументом стоит id, а FormData React добавит последней — поэтому подпись (id: string, form: FormData) тоже подойдёт, если поля всё-таки понадобятся. В разметке действие привязывается так же, как перенос:

jsлистинг · не запускается

<form action={deleteTask.bind(null, task.id)}>
  <button>удалить</button>
</form>

<form action={deleteTask.bind(null, task.id)}>
  <button>удалить</button>
</form>

Наложение — фильтр вместо map: (current: Task[], id: string) => current.filter((task) => task.id !== id). И то же правило: объявлять его надо у списка, иначе карточка успеет размонтироваться вместе со своим состоянием.

Добавление и изменение через действия

Видеоразбор темы за 5–7 минут

Два действия и один файлКуда положить запись и что она возвращает

Форма приносит unknownСтрока из формы — ещё не статус

Ошибка возвращается вместе с введённымuseActionState держит отказ, форма — текст

Карточка появляется до ответаНаложение поверх серверного списка

Перенос карточкиbind, скрытое поле и наложение у списка

Итогошпаргалка по теме

Проверьте себявопросы по теме

Задачизадачи с решениями

Предикат вместо as

Наложение, которое переносит

Третье действие: удалить