Диск под памятью: перезапуск и миграция схемы

Всё, что собрано в двух прошлых статьях, — хранилище, журнал, счётчики имён — живёт в памяти одного процесса JavaScript. Пока приложение на экране, это не беда. Но свёрнутое приложение система выгружает, когда ей нужна память, и последнего слова ему не даёт: AppState сообщит об уходе в фон, а об убийстве процесса не сообщит никто (статья «Свернули и вернулись» в главе 7). Следующий запуск начинается с пустой памяти — ни журнала, ни подходов из зала.

Под память нужен диск. Рука, прошедшая часть II, тянется к localStorage из статьи «localStorage и sessionStorage». Рядом у браузера есть и настоящие базы — IndexedDB и Cache. Прогноз: что скажет компилятор, что напечатает пример и что он напечатает, если запустить его ещё раз?

// привычка из части II: сохранить число запусков и прочитать его после перезапуска
const runs = Number(localStorage.getItem("runs") ?? "0") + 1;
localStorage.setItem("runs", String(runs));
console.log("запуск №" + runs);

// у браузера есть и настоящие базы — IndexedDB и Cache
try {
  indexedDB.open("podhod");
  console.log("IndexedDB: открыт");
} catch (error) {
  console.log("IndexedDB:", (error as Error).name);
}
try {
  caches.open("podhod");
  console.log("Cache: открыт");
} catch (error) {
  console.log("Cache:", (error as Error).name);
}

Компилятор находит четыре ошибки: «Не удается найти имя "localStorage".» — дважды, — и такие же про indexedDB и caches. Пример всё равно выполняется: печатает «запуск №1», а обе базы бросают SecurityError. Второй запуск снова напечатает «запуск №1», и десятый тоже. Здесь правы все трое, но каждый о своём.

Компилятор говорит о телефоне. У набора rn нет библиотеки DOM, а Web Storage, IndexedDB и Cache — это API браузера. React Native 0.86 ставит свои глобали — fetch, XMLHttpRequest, WebSocket и другие, список был в прошлой статье у crypto, — и хранилищ среди них нет. На телефоне первая же строка упадёт с ReferenceError.

Песочница говорит о себе. Кадр примера живёт в уникальном происхождении, и настоящий localStorage в нём запрещён — обращение бросило бы SecurityError. Чтобы примеры части II работали, учебник подставляет вместо него хранилище в памяти кадра. Оно ведёт себя как настоящее, но каждый запуск создаёт новый кадр, и память начинается заново: заглушка работает, а перезапуск не переживает. IndexedDB и Cache учебник не подменял, и браузер честно отказал: у кадра нет флага allow-same-origin.

В веб-версии «Подхода», собранной Expo для браузера, localStorage настоящий. Так устроено и в приложении автора: session-storage.web.ts в браузере пишет в globalThis.localStorage, а session-storage.ts на телефоне — в SecureStore, и сборщик выбирает файл по расширению. На телефоне же для JavaScript нужен свой ящик.

Песочница может изобразить диск, но не может его иметь: всё, что в ней «сохранено», исчезает вместе с кадром.

Обычный ящик для данных JavaScript на телефоне — пакет @react-native-async-storage/async-storage. Когда-то он входил в сам React Native, потом его вынесли в пакет сообщества; в react-native 0.86 от него остался только отладочный геттер, который бросает «AsyncStorage has been removed from react-native core». К Expo SDK он тоже не относится, но Expo знает, какая его версия совместима с каждым SDK: в bundledNativeModules.json пакета expo 57 записано 2.2.0, и ставится он так же, как модули Expo:

npx expo install @react-native-async-storage/async-storage

Интерфейс знаком по localStorage: getItem, setItem, removeItem, внутри только строки — объект придётся превращать в JSON, как в разделе «Внутри только строки» части II. Разница одна, зато главная: каждый вызов возвращает промис. Значение лежит не в памяти JavaScript, а у нативного модуля, и тот ходит на диск в своём потоке. Где именно лежат данные:

Веб-строка таблицы — приём из статьи «Одно приложение, три платформы». В пакете рядом лежат AsyncStorage.native.ts и AsyncStorage.ts, а index.ts импортирует просто ./AsyncStorage. Сборщик для телефона берёт файл с .native, и тот через RCTAsyncStorage.ts ищет нативный модуль в TurboModuleRegistry. Для веба берётся второй файл:

// @react-native-async-storage/async-storage 2.2.0, src/AsyncStorage.ts — файл для веба; сокращено
const AsyncStorage: AsyncStorageStatic = {
  getItem: (key, callback) => {
    return createPromise(() => window.localStorage.getItem(key), callback);
  },
  setItem: (key, value, callback) => {
    return createPromise(
      () => window.localStorage.setItem(key, value),
      callback
    );
  },
  // …
};

Пакетов в песочнице нет, а будь этот там, сборщик взял бы веб-файл — то есть ту же заглушку в памяти кадра. Поэтому ящик для примеров лежит в подложке: disk с методами getItem и setItem, строками по ключу и промисами, как у AsyncStorage. Запросы он выполняет по одному и по порядку, как настоящий, а ответ отдаёт следующей задачей. Главное его свойство — он живёт вне «процесса» примера. Внутри одного запуска можно выбросить всё, что пример держал в памяти, а диск останется. На телефоне на его место встаёт файл той же формы:

// shared/disk.ts в проекте на телефоне
import AsyncStorage from "@react-native-async-storage/async-storage";

// та же форма, что у disk в песочнице: строки по ключу, каждый вызов — промис
export const disk = {
  getItem: (key: string) => AsyncStorage.getItem(key),
  setItem: (key: string, value: string) => AsyncStorage.setItem(key, value),
};

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

Второе решение — сколько ключей. Транзакций у ящика нет, и два ключа — это две записи, между которыми процесс может умереть. Прошлая статья разбирала этот сбой в разделе «Строка и операция — одним шагом». А одно значение под одним ключом ложится одним setItem — это и есть один шаг. Поэтому на диске одно значение: журнал вместе со счётчиками имён. Задача 1 прошлой статьи советовала хранить их именно так — рядом с журналом и в том же шаге записи.

Процесс теперь — функция boot. Она читает диск, собирает строки свёрткой и отдаёт хранилище и журнал. «Убить процесс» значит выбросить всё, что вернула boot, и позвать её снова: память пуста, диск на месте. Лента подписана на хранилище, как в статье «Главная копия — в телефоне». Сценарий: первый запуск записывает подход и правит вес. Второй поднимается с диска и монтирует ленту, а человек добавляет ещё один подход. Прогноз: сколько операций поднимется с диска, что покажет лента и какое имя получит новый подход?

type Fields = Record<string, string | number>;
type Row = Fields & { id: string };
type Op = { opId: string; rowId: string; fields: Fields; at: number };
interface Store {
  write(row: Row): void;
  get(id: string): Row | undefined;
  list(): Row[];
  subscribe(listener: () => void): () => void;
}
interface Disk {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
}
declare const disk: Disk;
declare function createStore(): Store;
declare function now(): number;
declare function apply(row: Row | undefined, op: Op): Row;
declare function fold(log: Op[]): Map<string, Row>;
const { View, Text, Pressable } = ReactNative;

// на диске одно значение: журнал вместе со счётчиками, то есть одним шагом
type Saved = { rowSeq: number; opSeq: number; log: Op[] };

// процесс: всё, что в памяти, собирается из того, что лежит на диске
async function boot(device: string) {
  const text = await disk.getItem("podhod");
  const saved: Saved = text ? JSON.parse(text) : { rowSeq: 0, opSeq: 0, log: [] };
  const store = createStore();
  fold(saved.log).forEach((row) => store.write(row));
  return {
    store,
    saved,
    newId: () => device + "-" + ++saved.rowSeq,
    change(rowId: string, fields: Fields) {
      const op = { opId: device + ":" + ++saved.opSeq, rowId, fields: { ...fields }, at: now() };
      saved.log.push(op);
      store.write(apply(store.get(rowId), op));
      // экран диска не ждёт: память уже изменилась, запись на диск догонит
      return disk.setItem("podhod", JSON.stringify(saved));
    },
  };
}

interface FeedProps {
  app: Awaited<ReturnType<typeof boot>>;
}
function Feed({ app }: FeedProps) {
  const sets = React.useSyncExternalStore(app.store.subscribe, app.store.list);
  console.log("лента:", sets.map((s) => s.id + " " + s.kg + "×" + s.reps).join(" | "));
  const add = () => app.change(app.newId(), { exercise: "bench", kg: 80, reps: 5 });
  return (
    <View>
      {sets.map((s) => <Text key={s.id}>{s.exercise}: {s.kg} × {s.reps}</Text>)}
      <Pressable testID="add" onPress={add}><Text>+ подход</Text></Pressable>
    </View>
  );
}

(async () => {
  // первый запуск: подход и правка веса
  const first = await boot("A");
  const bench = first.newId();
  first.change(bench, { exercise: "bench", kg: 80, reps: 5 });
  await first.change(bench, { kg: 82.5 });
  // «убить процесс»: first со всей своей памятью выброшен, остался только диск
  const app = await boot("A");
  console.log("поднято с диска:", app.saved.log.length, "операции");
  mount(<Feed app={app} />);
  setTimeout(() => fireEvent.press("add"), 50);
})();

С диска поднялись две операции, свёртка собрала из них строку с поправленным весом, и лента показала её в первой же отрисовке. boot закончилась до mount, поэтому экрану нечего ждать: ни «загрузка…», ни мелькнувшей пустоты. Новый подход получил имя A-2, а не A-1: счётчик приехал с диска вместе с журналом. Не будь счётчика на диске, имена после перезапуска повторились бы, как в задаче прошлой статьи.

Экран диска не ждёт. change возвращает промис записи, но onPress его не ждёт: правка уже в памяти, лента уже перерисовалась. Первую change сценарий тоже не ждёт, и это безопасно по двум причинам. Каждое значение — журнал целиком, а ящик выполняет запросы по одному в порядке вызова, как AsyncStorage на обеих платформах, так что последняя запись несёт всё. Окно, в котором убийство процесса отнимет правку, — миллисекунды между нажатием и ответом нативного модуля. Не «пока приложение не свернули»: запись на диск начинается в том же обработчике, что и запись в память.

Цена тоже видна: каждое нажатие переписывает весь журнал. На iOS журнал быстро перерастёт 1024 символа и станет отдельным файлом, который пишется целиком. На Android все ключи вместе упираются в 6 МБ. Для первых месяцев дневника этого хватит, для лет — нет. Настоящая база пишет одну строку на операцию — это последняя статья главы, expo-sqlite.

Приложение обновляется — из магазина или по воздуху (глава 11), — а диск остаётся от прошлой версии. В версии 1.1 «Подхода» в настройках появятся фунты, и поле веса переименовано: было weight, стало weightKg, с единицей в имени. Код 1.1 читает weightKg, а на диске лежит журнал 1.0. Поэтому в значении на диске хранится номер схемы, а в приложении — лестница миграций: шаг с версии 1 на 2, с 2 на 3 и дальше. Телефон мог пропустить обновления: человек поставил 1.0 и через полгода сразу 1.3. Лестница проходит все ступени подряд, и старые шаги из неё не удаляют, пока где-то могут жить старые данные.

Лестница идёт до первого кадра — внутри boot, до mount. Иначе экран 1.1 успеет прочитать строки 1.0, не найдёт в них weightKg и покажет подход без веса. Что показывать человеку, пока она идёт, решает следующая статья.

Кеш при смене версии сносят и загружают заново: оригинал лежит на сервере. У «Подхода» оригинал здесь. Неотправленное существует только на этом телефоне, и снести базу — значит стереть его навсегда.

Миграцию обычно формулируют про таблицу: «в таблице подходов колонка weight стала weightKg». Пусть первая лестница так и делает — соберёт строки свёрткой и переименует поле в строках. Сценарий: на диске журнал 1.0 — подход и неотправленная правка веса, — и его открывает версия 1.1. Прогноз: что будет в таблице, что останется в журнале и что покажет второй запуск той же 1.1?

type Fields = Record<string, string | number>;
type Row = Fields & { id: string };
type Op = { opId: string; rowId: string; fields: Fields; at: number };
interface Store {
  write(row: Row): void;
  list(): Row[];
}
interface Disk {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
}
declare const disk: Disk;
declare function createStore(): Store;
declare function fold(log: Op[]): Map<string, Row>;

type Saved = { schema: number; rowSeq: number; opSeq: number; log: Op[] };
// так диск оставила версия 1.0: вес в поле weight, правка веса ещё не отправлена
const fromV1: Saved = {
  schema: 1,
  rowSeq: 1,
  opSeq: 2,
  log: [
    { opId: "A:1", rowId: "A-1", fields: { exercise: "bench", weight: 80, reps: 5 }, at: 1 },
    { opId: "A:2", rowId: "A-1", fields: { weight: 82 }, at: 2 },
  ],
};

// версия 1.1: в настройках появятся фунты, поэтому вес называется с единицей
const SCHEMA = 2;
const FIELDS = ["exercise", "weightKg", "reps"];
const unknown = (fields: Fields) => Object.keys(fields).filter((key) => !FIELDS.includes(key));

// миграция, написанная про таблицу: «колонка weight стала weightKg»
const renameRow = ({ weight, ...rest }: Row): Row => ({ ...rest, weightKg: weight });

async function boot() {
  const saved: Saved = JSON.parse((await disk.getItem("podhod")) ?? "null");
  let rows = [...fold(saved.log).values()];
  if (saved.schema < SCHEMA) {
    rows = rows.map(renameRow);
    saved.schema = SCHEMA;
    await disk.setItem("podhod", JSON.stringify(saved));
  }
  const store = createStore();
  rows.forEach((row) => store.write(row));
  return { store, saved };
}

(async () => {
  await disk.setItem("podhod", JSON.stringify(fromV1));
  const app = await boot();
  const last = app.saved.log[app.saved.log.length - 1].fields;
  console.log("таблица:", JSON.stringify(app.store.list()));
  console.log("журнал:", JSON.stringify(last), "| схема 2 не знает:", JSON.stringify(unknown(last)));
  const again = await boot();
  console.log("второй запуск 1.1:", JSON.stringify(again.store.list()));
})();

Первый запуск выглядит безупречно: в таблице weightKg: 82, экран прав. Но журнал — тот самый, что уедет на сервер, — хранит правку { weight: 82 } с полем, которого схема 2 не знает. А второй запуск той же версии вернул таблице форму 1.0. Номер схемы на диске уже 2, лестница больше не идёт, а строки снова собраны свёрткой из старого журнала. Таблица здесь производная, и мигрировать её бесполезно: она пересобирается при каждом запуске. Мигрировать надо то, что лежит на диске, — журнал.

В базе из последней статьи главы строки будут лежать на диске таблицей, и её миграция перезапуск переживёт. Но журнал рядом — те же частичные правки. Если поля правки лежат в нём строкой JSON, ALTER TABLE до них не дотянется, и шаг журнала понадобится всё равно.

Шаг журнала работает с операциями, а операция — не строка: в ней только поля, которые изменились. Правка { weight: 82 } — кусок строки, правка { reps: 6 } — кусок совсем без веса. Поэтому шаг журнала переименовывает поле только там, где оно есть, и не трогает остальное. Лестница — объект шагов, где ключ — версия, с которой шаг поднимает, и цикл от версии на диске до версии приложения. Поднятый журнал ложится на диск вместе с новым номером одним значением: иначе номер и содержимое разойдутся так же, как строка и операция. Сценарий тот же. Прогноз: что изменится в трёх строках вывода?

type Fields = Record<string, string | number>;
type Row = Fields & { id: string };
type Op = { opId: string; rowId: string; fields: Fields; at: number };
interface Store {
  write(row: Row): void;
  list(): Row[];
}
interface Disk {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
}
declare const disk: Disk;
declare function createStore(): Store;
declare function fold(log: Op[]): Map<string, Row>;

type Saved = { schema: number; rowSeq: number; opSeq: number; log: Op[] };
// так диск оставила версия 1.0: вес в поле weight, правка веса ещё не отправлена
const fromV1: Saved = {
  schema: 1,
  rowSeq: 1,
  opSeq: 2,
  log: [
    { opId: "A:1", rowId: "A-1", fields: { exercise: "bench", weight: 80, reps: 5 }, at: 1 },
    { opId: "A:2", rowId: "A-1", fields: { weight: 82 }, at: 2 },
  ],
};

// версия 1.1: в настройках появятся фунты, поэтому вес называется с единицей
const SCHEMA = 2;
const FIELDS = ["exercise", "weightKg", "reps"];
const unknown = (fields: Fields) => Object.keys(fields).filter((key) => !FIELDS.includes(key));

// лестница: шаг с версии n на n + 1. Шаг журнала трогает только те поля,
// что в правке есть: у операции нет строки целиком
const steps: Record<number, (fields: Fields) => Fields> = {
  1: (fields) => {
    if (!("weight" in fields)) return fields;
    const { weight, ...rest } = fields;
    return { ...rest, weightKg: weight };
  },
};

function migrate(saved: Saved): Saved {
  while (saved.schema < SCHEMA) {
    const step = steps[saved.schema];
    const log = saved.log.map((op) => ({ ...op, fields: step(op.fields) }));
    saved = { ...saved, schema: saved.schema + 1, log };
  }
  return saved;
}

async function boot() {
  let saved: Saved = JSON.parse((await disk.getItem("podhod")) ?? "null");
  if (saved.schema < SCHEMA) {
    saved = migrate(saved);
    // новая версия и поднятый журнал — одно значение, то есть один шаг
    await disk.setItem("podhod", JSON.stringify(saved));
  }
  const store = createStore();
  fold(saved.log).forEach((row) => store.write(row));
  return { store, saved };
}

(async () => {
  await disk.setItem("podhod", JSON.stringify(fromV1));
  const app = await boot();
  const last = app.saved.log[app.saved.log.length - 1].fields;
  console.log("таблица:", JSON.stringify(app.store.list()));
  console.log("журнал:", JSON.stringify(last), "| схема 2 не знает:", JSON.stringify(unknown(last)));
  const again = await boot();
  console.log("второй запуск 1.1:", JSON.stringify(again.store.list()));
})();

Таблица та же, но теперь она собрана из журнала в форме 1.1, и второй запуск её не теряет. Неотправленная правка стала { weightKg: 82 }: в главе 7 она уедет на сервер в форме, которую схема 2 знает. Шаг таблицы — функция «строка 1.0 → строка 1.1» — сюда не подходит: он считает, что в строке есть все поля, а в правке их нет. Что именно он ломает и почему это видно не при каждом запуске, покажет задача 1.

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

Ящик, boot и лестница с шагом журнала переезжают в подложку следующей статьи. Там выяснится, что показать человеку, пока boot читает диск и поднимает журнал по лестнице, и чем «не открылась» отличается от «пусто».