Свой кеш: ключ из входа, метка вместо списка адресов

Модель с фильтром из прошлой статьи обслуживала одну функцию: ключом служили её сериализованные аргументы, и этого хватало. Настоящий "use cache" работает с любой функцией: как обёртка, которая принимает функцию, возвращает новую и пропускает через неё все вызовы. Такую обёртку и напишем. Главное в ней — единственная дверь: всё, что обёртка знает о вызове, пришло через ...args.

Первая версия берёт в ключ только аргументы, как модель с фильтром. Функций две, хранилище одно. Прогноз: что напечатает вторая строка?

const store = new Map<string, unknown>();
let runs = 0;

function cached<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R {
  return (...args: A): R => {
    const key = JSON.stringify(args);
    if (store.has(key)) return store.get(key) as R;
    runs += 1;
    const value = fn(...args);
    store.set(key, value);
    return value;
  };
}

const getUser = cached((id: string) => "пользователь " + id + ": Рико");
const getPost = cached((id: string) => "статья " + id + ": Свой кеш");

console.log(getUser("1"));
console.log(getPost("1"));
console.log("расчётов:", runs, "| записей:", store.size);

Статья вернула пользователя. Ключ ["1"] у обоих вызовов один, и второй вызов честно нашёл запись — чужую. В модели с фильтром это не было видно, потому что функция там была одна. А хранилище у Next тоже одно на всё приложение: обработчик кеша по умолчанию — это один словарь в памяти процесса, куда пишут все помеченные функции. Значит, в ключе обязано быть и то, чья это запись.

Добавим первое слагаемое — то самое имя, которое модель страницы из прошлой статьи ставила в ключ, не объясняя, зачем оно там. У Next это не имя, а хеш места и сигнатуры функции в коде, и вписывает его компилятор; мы передадим строку руками.

const store = new Map<string, unknown>();

// первое слагаемое ключа — чья это функция; у Next его вписывает компилятор
function cached<A extends unknown[], R>(id: string, fn: (...args: A) => R): (...args: A) => R {
  return (...args: A): R => {
    const key = id + JSON.stringify(args);
    if (store.has(key)) return store.get(key) as R;
    const value = fn(...args);
    store.set(key, value);
    return value;
  };
}

const getUser = cached("getUser", (id: string) => "пользователь " + id + ": Рико");
const getPost = cached("getPost", (id: string) => "статья " + id + ": Свой кеш");

console.log(getUser("1"));
console.log(getPost("1"));
console.log([...store.keys()].join("  "));

Два ключа — две записи. Теперь ключ отвечает на оба вопроса: какая функция и с чем её позвали. Номер сборки, который Next ставит в ключ самым первым, модели не нужен: он меняется только с выкатом, а модель живёт один запуск.

// ключ миниатюры — JSON.stringify от списка аргументов
const key = (...args: unknown[]): string => JSON.stringify(args);

console.log(key(undefined) === key(null));
console.log(key(new Map([["a", 1]])) === key(new Map([["b", 2]])));
console.log(key({ a: 1, b: 2 }) === key({ b: 2, a: 1 }));

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

Функцию объявляют внутри компонента, и userId она берёт из замыкания. Каждый вызов reportFor создаёт новую стрелку, то есть новый объект функции. Прогноз: разведёт ли это двух пользователей?

// обёртка из прошлого раздела — едет в песочницу подложкой
declare function cached<A extends unknown[], R>(id: string, fn: (...args: A) => R): (...args: A) => R;

// так функцию пишут внутри компонента: userId она берёт из замыкания
function reportFor(userId: string) {
  return cached("report", (period: string) => "отчёт за " + period + ", пользователь " + userId);
}

console.log(reportFor("1")("сентябрь"));
console.log(reportFor("2")("сентябрь"));

Не развело. Новая стрелка — новый объект, но на объект обёртка не смотрит: имя то же, "report", аргументы те же, ["сентябрь"]. А userId через ...args не проходил вовсе — он лежит в окружении функции, куда снаружи не заглянуть. Это не упущение модели: у обёртки просто нет способа узнать, что функция что-то захватила.

Честная обёртка из самого Next, unstable_cache, так и живёт: в ключ она берёт аргументы и текст функции, а захваченные переменные просит перечислить руками. Текст у двух экземпляров стрелки, кстати, тоже один.

Директива решает задачу раньше, чем код запустится. "use cache" — не вызов, а строка, которую читает компилятор, и он переписывает функцию: поднимает её на уровень модуля, захваченные переменные делает первыми параметрами, а на месте объявления оставляет привязку через bind. Сделаем за него то же самое руками. Прогноз: что окажется в последней строке — сколько ключей и какие?

declare function cached<A extends unknown[], R>(id: string, fn: (...args: A) => R): (...args: A) => R;
declare const store: Map<string, unknown>;

// так функцию переписывает компилятор Next: тело поднято на уровень модуля,
// а захваченная переменная стала первым параметром
const report = cached("report", (userId: string, period: string) =>
  "отчёт за " + period + ", пользователь " + userId);

function reportFor(userId: string) {
  // на месте объявления осталась только привязка: значение едет аргументом
  return report.bind(null, userId);
}

console.log(reportFor("1")("сентябрь"));
console.log(reportFor("2")("сентябрь"));
console.log([...store.keys()].join("  "));

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

Привязываются переменные объемлющих функций. Переменная уровня модуля после подъёма и так видна напрямую — привязывать её незачем, и в ключ она не входит. Модульный let, который меняется между запросами, кеш не заметит.

Модель меток из главы про мутации хранила у каждой записи список её меток, и revalidateTag перебирал весь кеш в поисках нужной. Работает, но связь там записана задом наперёд. Удобнее обратный указатель: метка → множество ключей. Тогда сброс — взять множество и удалить каждый ключ из него, не глядя на остальные записи.

Остаётся вопрос, откуда cacheTag знает, к какой записи прицепить метку. Ключа он не получает: cacheTag("post:" + id) — и всё. Ответ вы уже видели в статье про правила хуков: на время рендера React выставляет «текущий набор хуков», и useState обращается к нему — о компоненте он аргументом не получает ничего. Здесь то же самое: пока обёртка считает запись, она держит в переменной массив её меток, и cacheTag кладёт метки туда.

Прогноз: что будет лежать в индексе, сколько раз посчитается getPost и какие заголовки напечатает последняя строка?

const store = new Map<string, unknown>();
const tagIndex = new Map<string, Set<string>>();
// метки записи, которая считается прямо сейчас; null — никто не считается
let current: string[] | null = null;
let runs = 0;

function cacheTag(...tags: string[]): void {
  // ключа cacheTag не получает: он пишет в ту запись, что считается сейчас
  if (current === null) throw new Error("cacheTag вызван вне кешируемой функции");
  current.push(...tags);
}

function cached<A extends unknown[], R>(id: string, fn: (...args: A) => R): (...args: A) => R {
  return (...args: A): R => {
    const key = id + JSON.stringify(args);
    if (store.has(key)) return store.get(key) as R;
    runs += 1;
    const outer = current;
    current = [];
    const value = fn(...args);
    for (const tag of current) {
      const keys = tagIndex.get(tag) ?? new Set<string>();
      tagIndex.set(tag, keys.add(key));
    }
    current = outer;
    store.set(key, value);
    return value;
  };
}

function revalidateTag(tag: string): void {
  for (const key of tagIndex.get(tag) ?? []) store.delete(key);
  tagIndex.delete(tag);
}

const titles: Record<string, string> = { "1": "Свой рендер", "2": "Своя сверка" };
const getPost = cached("getPost", (id: string) => {
  cacheTag("post:" + id);
  return "«" + titles[id] + "»";
});

getPost("1");
getPost("2");
for (const [tag, keys] of tagIndex) console.log(tag, "→", [...keys].join(", "));
titles["1"] = "Свой рендер, вторая редакция";
revalidateTag("post:1");
console.log(getPost("1"), getPost("2"), "| расчётов:", runs);

Три расчёта: два при первом чтении и один после сброса. Метка post:1 вела ровно к одному ключу — его и выбросили; соседняя запись под post:2 не шелохнулась и отдалась из кеша. Перебора нет вовсе: revalidateTag даже не знает, сколько записей в хранилище.

Ошибка в cacheTag — не наша выдумка: настоящий cacheTag вне кешируемой функции бросает «cacheTag() can only be called inside a "use cache" function». Проверка та же — текущей записи нет.

Строка current = outer кажется лишней, пока вызовы плоские. Она понадобится, когда одна кешируемая функция позовёт другую, — и это следующий раздел.

В главе про мутации было сказано: кто из страниц показывает помеченные данные, знает кеш, и знает точнее вас. Проверим это на миниатюре. Список статей собран из тех же getPost, своих меток у него нет. Статью поправили, метку сбросили. Прогноз: что покажет список?

// миниатюра из прошлого раздела — подложкой, здесь только объявления
declare function cached<A extends unknown[], R>(id: string, fn: (...args: A) => R): (...args: A) => R;
declare function revalidateTag(tag: string): void;
declare const titles: Record<string, string>;
declare const getPost: (id: string) => string;

const getList = cached("getList", () => ["1", "2"].map((id) => getPost(id)).join(" "));

console.log(getList());
titles["1"] = "Свой рендер, вторая редакция";
revalidateTag("post:1");
console.log(getPost("1"));
console.log(getList());

Страница статьи уже с новым заголовком, а список — со старым: на одном сайте две версии одного текста, и ни одной ошибки. Метка post:1 висит на записи getPost, а запись списка про неё не знает. Пока считался список, cacheTag звали внутри getPost, и метки ушли в её собственный массив — строка current = outer вернула списку его пустой.

Лечится одной мыслью: запись, посчитанная внутри другой, отдаёт свои метки наружу. Тогда метки поднимаются по цепочке вызовов, как всплывает событие, и запись списка сама оказывается под post:1. Для этого запись должна помнить свои метки — иначе при попадании в кеш поднимать было бы нечего.

// хранилище, индекс, cacheTag и сброс — прежние, подложкой
declare const store: Map<string, { value: unknown; tags: string[] }>;
declare const tagIndex: Map<string, Set<string>>;
declare let current: string[] | null;
declare function cacheTag(...tags: string[]): void;
declare function revalidateTag(tag: string): void;
declare const titles: Record<string, string>;

function cached<A extends unknown[], R>(id: string, fn: (...args: A) => R): (...args: A) => R {
  return (...args: A): R => {
    const key = id + JSON.stringify(args);
    let entry = store.get(key);
    if (entry === undefined) {
      const outer = current;
      current = [];
      // запись теперь помнит свои метки: без них при попадании нечего поднимать
      entry = { value: fn(...args), tags: current };
      current = outer;
      for (const tag of entry.tags) {
        const keys = tagIndex.get(tag) ?? new Set<string>();
        tagIndex.set(tag, keys.add(key));
      }
      store.set(key, entry);
    }
    // метки уходят во внешнюю запись — и после расчёта, и при попадании
    current?.push(...entry.tags);
    return entry.value as R;
  };
}

const getPost = cached("getPost", (id: string) => {
  cacheTag("post:" + id);
  return "«" + titles[id] + "»";
});
const getList = cached("getList", () => ["1", "2"].map((id) => getPost(id)).join(" "));

console.log(getList());
console.log("post:1 →", [...tagIndex.get("post:1")!].join(", "));
titles["1"] = "Свой рендер, вторая редакция";
revalidateTag("post:1");
console.log(getList());

Во множестве post:1 теперь два ключа, и второй туда никто не вписывал руками: в списке нет ни одного cacheTag. Вот и ответ на вопрос, как кеш узнаёт, какие страницы показывают данные. Страница — такая же внешняя запись, и метки всего, что посчитали внутри неё, поднимаются в неё сами.

Обратите внимание, где стоит подъём: после условия, то есть и после расчёта, и при попадании. Почему это важно, разбирается в первой задаче.

В исходниках Next это функция propagateCacheLifeAndTagsToRevalidateStore. Вместе с метками она поднимает и сроки жизни — отсюда вложенный короткий кеш, укорачивающий внешний, из прошлой статьи.

Теперь ошибка, ради которой миниатюру стоило собирать. В кешируемой функции стоит cacheTag("post:" + id), а в действии рука набрала дефис. Страница ниже работает на миниатюре целиком: хранилище, индекс и getPost едут подложкой. Кнопка сохраняет новый заголовок, сбрасывает метку и перерисовывает страницу, как это делает ответ действия. Прогноз: ошибка, пустой экран или новый заголовок?

// миниатюра целиком едет подложкой: хранилище, индекс меток, getPost
declare function revalidateTag(tag: string): void;
declare const tagIndex: Map<string, Set<string>>;
declare const titles: Record<string, string>;
declare const getPost: (id: string) => string;

function PostPage() {
  const [, setVersion] = React.useState(0);
  const title = getPost("1");
  console.log("на экране:", title);

  function save() {
    titles["1"] = "Свой рендер, вторая редакция";
    revalidateTag("post-1");
    console.log("метки в индексе:", [...tagIndex.keys()].join(", "));
    // как ответ действия: страница собирается заново
    setVersion((v) => v + 1);
  }

  return (
    <div>
      <h1>{title}</h1>
      <button id="save" onClick={save}>Сохранить</button>
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<PostPage />);
setTimeout(() => document.getElementById("save")!.click(), 50);

Ни то, ни другое, ни третье: страница перерисовалась и показала старый заголовок. tagIndex.get("post-1") вернул undefined, ?? [] превратил его в пустой список, и цикл не сделал ни шага. Запись под post:1 цела, и следующий рендер честно достал её из кеша. Экран не пустеет, потому что сброс экрана не касается вообще: он только решает, будет ли следующий расчёт, — а до расчёта дело не дошло.

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

// сервер только что перезапущен
const store = new Map<string, unknown>();
const tagIndex = new Map<string, Set<string>>();

// «строгий» сброс: незнакомую метку считаем опечаткой
function revalidateTagStrict(tag: string): void {
  const keys = tagIndex.get(tag);
  if (keys === undefined) throw new Error("нет такой метки: " + tag);
  for (const key of keys) store.delete(key);
  tagIndex.delete(tag);
}

// редактор сохранил статью — метка написана без единой ошибки
try {
  revalidateTagStrict("post:1");
  console.log("сброшено");
} catch (error) {
  console.log((error as Error).message);
}

Упал вызов с верной меткой. Пустое место под меткой — не признак опечатки, а обычное состояние: после выката (номер сборки в ключе, и все записи новые), после истечения срока, на соседнем экземпляре сервера, просто пока страницу никто не открыл. Отличить «такой метки не бывает» от «под ней пока пусто» кеш не может, поэтому настоящий revalidateTag на незнакомое имя не ругается никогда.

// метка → когда её сбросили; ключей под меткой никто не хранит
const manifest = new Map<string, number>();
const entries = new Map<string, { value: string; at: number; tags: string[] }>();
let clock = 0; // условное время: двигаем руками, чтобы вывод не плавал

function save(key: string, value: string, tags: string[]): void {
  clock += 1;
  entries.set(key, { value, at: clock, tags });
}

function revalidateTag(tag: string): void {
  clock += 1;
  manifest.set(tag, clock); // ни одного ключа не перебрали
}

function read(key: string): string {
  const entry = entries.get(key);
  if (entry === undefined) return "промах";
  // запись устарела, если хоть одну её метку сбросили позже, чем её посчитали
  const stale = entry.tags.some((tag) => (manifest.get(tag) ?? 0) > entry.at);
  return stale ? "устарела, считаем заново" : entry.value;
}

save("getPost(1)", "«Свой рендер»", ["post:1"]);
revalidateTag("post-1");
console.log(read("getPost(1)"));
revalidateTag("post:1");
console.log(read("getPost(1)"));
console.log("в таблице меток:", [...manifest.keys()].join(", "));

Раз при выполнении опечатку не поймать, ловить её надо раньше — на компиляции. Next принимает метку как любую строку, поэтому тип сужают сами: все имена меток — в одном типе, а вызовы идут через свою тонкую обёртку.

// все метки проекта — один тип
type Tag = "posts" | `post:${string}`;

// метку собирают в одном месте — и в cacheTag, и в сбросе
const tag = {
  posts: "posts" as const,
  post: (id: string): Tag => `post:${id}`,
};

// в проекте здесь зовут revalidateTag из next/cache, а он принимает любую строку
function revalidate(name: Tag): void {
  console.log("сброшена метка", name);
}

revalidate("post-1");
revalidate(tag.post("1"));

Диагностика — Аргумент типа ""post-1"" нельзя назначить параметру типа "Tag" — указывает ровно на опечатку: "post-1" не подходит ни под "posts", ни под шаблон post:${string}. Шаблонные строковые типы из части III работают здесь как список допустимых имён, который не надо поддерживать руками. Выполнение при этом прошло — типы, как всегда, живут только до запуска. Помощник tag.post(id) закрывает вторую половину: метка собирается в одном месте, и дефису в ней неоткуда взяться.

Миниатюра честна в главном и упрощена во всём остальном. Чтобы не спутать одно с другим — сверка по частям.

Последняя строка объясняет, почему в главе про мутации revalidatePath и revalidateTag вели себя так похоже: внутри это одна и та же функция сброса. Адрес превращается в служебную метку, а дальше работает механизм, который вы только что собрали.

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