Полная сигнатура ready

Сигнатура:

ready(callback?: Function): Promise<void>

Метод ready в localForage используется для контроля момента полной инициализации хранилища. Он гарантирует, что выбранный драйвер (IndexedDB, WebSQL или localStorage) уже определён, сконфигурирован и готов к выполнению операций чтения и записи.

Назначение метода ready

localForage работает поверх нескольких механизмов хранения данных, выбор которых может происходить автоматически или явно через setDriver. Поскольку инициализация драйвера может быть асинхронной (особенно IndexedDB), возникает необходимость в точке синхронизации.

ready выполняет роль такого синхронизатора:

  • завершает процесс выбора и инициализации драйвера;
  • гарантирует доступность внутреннего storage-адаптера;
  • обеспечивает безопасное выполнение операций getItem, setItem, removeItem, iterate и других.

Поведение и жизненный цикл

При первом обращении к localForage библиотека проходит несколько стадий:

  1. Чтение конфигурации (config)
  2. Определение доступных драйверов
  3. Выбор драйвера (автоматический или через setDriver)
  4. Инициализация выбранного драйвера
  5. Пометка состояния как ready

Метод ready возвращает Promise, который резолвится только после завершения всех этих этапов.

Если драйвер уже инициализирован, ready завершается мгновенно (микрозадача Promise).

Возвращаемое значение

Promise<void>

Promise всегда резолвится без значения (undefined), поскольку метод предназначен исключительно для синхронизации состояния.

Параметр callback

callback?: Function

Допускается передача функции обратного вызова для совместимости со старыми стилями кода.

Особенности поведения:

  • callback вызывается после готовности storage;
  • если ready уже завершён — callback вызывается асинхронно;
  • при ошибках инициализации callback получает ошибку первым аргументом (в редких случаях, зависящих от драйвера и окружения).

Эквивалентные формы:

localforage.ready().then(() => {
  // storage готов
});
localforage.ready((err) => {
  if (err) return;
  // storage готов
});

Типичная сигнатурная модель внутри библиотеки

Внутренне метод можно рассматривать как:

ready(callback?: (err?: any) => void): Promise<void>

При этом callback — необязательный слой поверх Promise API.

Гарантии после вызова ready

После завершения ready выполняются следующие гарантии:

  • выбран корректный драйвер (или завершён фолбэк-процесс);
  • внутренний instance storage полностью инициализирован;
  • доступ к ключам и значениям стабилен;
  • все операции CRUD безопасны для выполнения.

Важно, что ready не гарантирует наличие данных, он гарантирует только готовность системы хранения.

Асинхронная природа IndexedDB

Наиболее частый источник задержки — IndexedDB:

  • открытие базы данных требует запроса к браузерному API;
  • возможны события upgrade;
  • иногда происходит миграция структуры.

Поэтому ready фактически ожидает завершения indexedDB.open() и всех связанных событий.

Повторные вызовы ready

Метод можно вызывать многократно:

localforage.ready().then(...)
localforage.ready().then(...)

Поведение:

  • первый вызов инициирует процесс ожидания;
  • последующие вызовы возвращают уже существующий Promise;
  • повторной инициализации не происходит.

Это делает метод безопасным для использования в разных частях приложения.

Взаимодействие с config и setDriver

ready тесно связан с конфигурационными методами:

config

Изменение конфигурации до ready влияет на выбор драйвера.

localforage.config({
  name: 'app',
  storeName: 'cache'
});

setDriver

Явное задание драйвера влияет на процесс инициализации:

localforage.setDriver(localforage.INDEXEDDB).then(() => {
  return localforage.ready();
});

Если setDriver уже завершён, ready становится фактически мгновенным.

Типовые сценарии использования

1. Гарантированная инициализация перед доступом к данным

await localforage.ready();
const value = await localforage.getItem('key');

2. Безопасный старт приложения

localforage.ready().then(initApp);

3. Смешанный callback/Promise стиль

localforage.ready((err) => {
  if (err) return;
  startCacheLayer();
});

Ошибки и нестандартные ситуации

Хотя ready редко выбрасывает ошибки, возможны ситуации:

  • недоступность всех драйверов;
  • блокировка IndexedDB в приватном режиме (зависит от браузера);
  • повреждённое хранилище;
  • ограничения окружения (например, iframe sandbox).

В таких случаях Promise может быть отклонён или callback получит ошибку.

Отличие ready от обычных методов хранения

Метод не относится к CRUD-операциям и не работает с данными напрямую.

Сравнение:

  • setItem/getItem — работа с данными
  • clear/removeItem — модификация данных
  • ready — контроль состояния системы хранения

Порядок выполнения относительно других вызовов

Если вызовы происходят до готовности:

localforage.setItem('a', 1);
localforage.ready();

localForage автоматически ставит операции в очередь до завершения инициализации. Однако явное использование ready даёт контроль над моментом старта логики приложения.

Особенности Promise-реализации

  • ready возвращает стабильный Promise (idempotent);
  • резолв происходит один раз на instance;
  • не создаётся повторных внутренних подписок при множественных вызовах;
  • Promise может кешироваться внутри экземпляра localForage.

Практическая модель поведения

Упрощённо:

if (storage.initialized)
    resolve immediately
else
    wait for driver selection + initialization
    resolve

Важный аспект архитектуры

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

Она формирует границу между:

  • состоянием “конфигурация и выбор драйвера”
  • состоянием “готовое хранилище данных”
Оглавление