Что происходит после мутации: revalidatePath и revalidateTag

// Модель обработчика действия из Next: сначала выполняется ваша функция,
// потом сервер решает, собирать ли страницу заново
type Store = { tasks: string[]; revalidated: boolean };

function renderPage(store: Store): string {
  return "задач на экране: " + store.tasks.length;
}

function runAction(store: Store, action: (s: Store) => void): string {
  action(store);
  // Ключевая строка: без пометки страница не собирается вовсе, и в ответе
  // для браузера просто нет новой разметки — обновлять экран нечем
  if (!store.revalidated) return "(разметки в ответе нет)";
  return renderPage(store);
}

const store: Store = { tasks: ["купить хлеб"], revalidated: false };
console.log(renderPage(store));

console.log(runAction(store, (s) => s.tasks.push("починить кран")));
console.log("а в базе уже:", store.tasks.length);

// Модель пометки по адресу: сервер держит собранные страницы по ключу-маршруту
const rendered = new Map<string, string>();
const db: string[] = ["купить хлеб"];

function visit(route: string): string {
  const hit = rendered.get(route);
  if (hit !== undefined) return hit + " (из кеша)";
  const page = route + " → задач: " + db.length;
  rendered.set(route, page);
  return page;
}

// сигнатура один в один из next/cache, тело — модель
function revalidatePath(path: string, type?: "layout" | "page"): undefined {
  for (const route of rendered.keys()) {
    // без второго аргумента помечается ровно один маршрут,
    // с "layout" — ещё и всё, что лежит под ним
    if (route === path || (type === "layout" && route.startsWith(path + "/"))) {
      rendered.delete(route);
    }
  }
  return undefined;
}

console.log(visit("/tasks"));
console.log(visit("/tasks/42"));

db.push("починить кран");
revalidatePath("/tasks");

console.log(visit("/tasks"));
console.log(visit("/tasks/42"));

// сигнатура один в один из next/cache; тело — заглушка ради запуска
function revalidatePath(path: string, type?: "layout" | "page"): undefined {
  console.log("устарело:", path, "| тип:", type);
  return undefined;
}

revalidatePath("/tasks/[id]", "all");
revalidatePath("/tasks/[id]", "page");

// в проекте: import { revalidatePath } from "next/cache";
// здесь заглушки — сети и базы у песочницы нет
declare function revalidatePath(path: string, type?: "layout" | "page"): undefined;
declare function insertTask(title: string): Promise<void>;

async function addTask(formData: FormData): Promise<void> {
  "use server";
  const title = String(formData.get("title") ?? "").trim();
  if (title === "") return;
  await insertTask(title);
  // Сначала запись, потом пометка. Порядок не косметический: пометка без
  // дождавшейся записи оставит в кеше прежние данные — про это следующий раздел
  revalidatePath("/tasks");
}

function TasksPage() {
  return (
    <form action={addTask}>
      <input name="title" />
      <button>Добавить</button>
    </form>
  );
}

// Модель меток: кеш помнит не только значение, но и чем оно помечено
const cache = new Map<string, { tags: string[]; value: string }>();

function readCached(key: string, tags: string[], compute: () => string): string {
  const hit = cache.get(key);
  if (hit !== undefined) return hit.value;
  const value = compute();
  cache.set(key, { tags, value });
  return value;
}

function revalidateTag(tag: string): void {
  for (const [key, entry] of cache) {
    if (entry.tags.includes(tag)) cache.delete(key); // адресов не перечисляли
  }
}

let tasks = ["купить хлеб"];
const countTasks = () => "задач: " + tasks.length;

console.log(readCached("/", ["tasks"], countTasks));
console.log(readCached("/tasks", ["tasks"], countTasks));
console.log(readCached("/about", ["pages"], () => "о нас"));

tasks = [...tasks, "починить кран"];
revalidateTag("tasks");

console.log(readCached("/", ["tasks"], countTasks));
console.log(readCached("/about", ["pages"], () => "о нас"));
console.log("записей в кеше:", cache.size);

// в проекте: import { cacheTag, revalidateTag } from "next/cache";
declare function cacheTag(...tags: string[]): void;
declare function revalidateTag(tag: string, profile: string | { expire?: number }): undefined;
declare function selectTasks(): Promise<string[]>;
declare function insertTask(title: string): Promise<void>;

async function getTasks(): Promise<string[]> {
  "use cache";
  cacheTag("tasks"); // метка на данных, а не на адресе
  return selectTasks();
}

async function addTask(title: string): Promise<void> {
  "use server";
  await insertTask(title);
  // страницы найдутся сами: их адреса знает кеш, а не автор действия
  revalidateTag("tasks", "max");
}

// Сигнатура один в один из next/cache 16-й версии; тело — заглушка,
// чтобы пример можно было запустить
function revalidateTag(tag: string, profile: string | { expire?: number }): undefined {
  console.log("метка:", tag, "| профиль:", profile);
  return undefined;
}

revalidateTag("tasks");
revalidateTag("tasks", "max");

const db: string[] = ["купить хлеб"];
const cache = new Map<string, string>();

function readTasks(): string {
  const hit = cache.get("/tasks");
  if (hit !== undefined) return hit;
  const value = "задач: " + db.length;
  cache.set("/tasks", value);
  return value;
}

async function insertTask(title: string): Promise<void> {
  await new Promise<void>((done) => setTimeout(() => done(), 50)); // поход в базу
  db.push(title);
}

async function addTask(title: string): Promise<void> {
  insertTask(title); // забытый await
  cache.delete("/tasks");
}

console.log(readTasks());
addTask("починить кран").then(() => {
  console.log("сразу после действия:", readTasks());
});
setTimeout(() => {
  console.log("в базе:", db.length, "| на экране:", readTasks());
}, 200);

declare function revalidatePath(path: string, type?: "layout" | "page"): undefined;
declare function selectTasks(): Promise<string[]>;

async function TasksPage() {
  const tasks = await selectTasks();
  // Соблазн понятный: данные протухли — обновлю прямо здесь. Next обрывает
  // такой запрос ошибкой: Route /tasks used "revalidatePath /tasks" during
  // render which is unsupported. To ensure revalidation is performed
  // consistently it must always happen outside of renders and cached functions.
  revalidatePath("/tasks");
  return <p>{tasks.length}</p>;
}

declare function revalidatePath(path: string, type?: "layout" | "page"): undefined;
declare function redirect(url: string): never;
declare function insertTask(title: string): Promise<number>;

async function addTask(title: string): Promise<void> {
  "use server";
  const id = await insertTask(title);
  revalidatePath("/tasks"); // до редиректа — иначе список останется старым
  redirect("/tasks/" + id);
}

// Модель клиентского кеша: компонент показывает разметку, которую ему
// однажды прислал сервер, и сам её не перепроверяет
const db = { tasks: ["купить хлеб"] };

function serverRender(): string {
  return "задач: " + db.tasks.length;
}

function TasksPage() {
  const [payload, setPayload] = React.useState(serverRender);
  console.log("отрисовка с разметкой:", payload);
  return (
    <div>
      <p>{payload}</p>
      <button id="add" onClick={() => db.tasks.push("починить кран")}>
        Изменить мимо действия
      </button>
      <button id="refresh" onClick={() => setPayload(serverRender())}>
        router.refresh()
      </button>
    </div>
  );
}

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

setTimeout(() => {
  document.getElementById("add")!.click();
  console.log("в базе:", db.tasks.length);
}, 100);
setTimeout(() => document.getElementById("refresh")!.click(), 300);