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

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

Метод поддерживает несколько форм вызова:

localforage.key(index);
localforage.key(index, callback);

Также всегда возвращает Promise:

localforage.key(index).then(key => {});

Полная логическая сигнатура:

key(index: number, callback?: (err: any, key: string | null) => void): Promise<string | null>

Параметры

index

Числовой индекс ключа в текущем хранилище.

  • Тип: number
  • Обязательный параметр
  • Индексация начинается с 0
  • Порядок ключей не гарантируется как стабильный между сессиями при разных драйверах

Особенность заключается в том, что порядок ключей определяется внутренним механизмом конкретного драйвера:

  • IndexedDB — использует порядок курсора
  • WebSQL — порядок строк результата SELECT
  • localStorage — порядок перечисления ключей объекта хранения

Это означает, что index не следует воспринимать как устойчивую бизнес-индексацию данных.

callback

Функция обратного вызова (опционально).

  • Тип: (err, key) => void
  • Используется для поддержки callback-стиля
  • Если указана, вызывается после завершения операции

Параметры callback:

  • err — ошибка выполнения или null
  • key — строковый ключ или null, если индекс вне диапазона

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

Метод возвращает:

Promise<string | null>

Поведение Promise:

  • resolve → строка ключа
  • resolve → null, если индекс выходит за пределы диапазона
  • reject → ошибка драйвера или хранения

Поведение метода

Метод key извлекает список всех ключей текущего хранилища и возвращает ключ, расположенный на позиции index.

Внутренне процесс можно представить следующим образом:

  1. Получение всех ключей из активного драйвера
  2. Формирование массива ключей
  3. Проверка границ индекса
  4. Возврат элемента массива по индексу

Однако реальная реализация зависит от драйвера:

IndexedDB

Используется курсор объекта хранения. Порядок соответствует сортировке ключей в объектном store.

WebSQL

Выполняется SQL-запрос вида:

SEL ECT key FR OM table

с последующей выборкой строки по индексу.

localStorage

Используется перечисление свойств объекта localStorage, что может давать непредсказуемый порядок в зависимости от движка браузера.

Особенности и ограничения

Нестабильность порядка

Главная особенность метода заключается в том, что индекс не является стабильным идентификатором:

  • добавление нового элемента может изменить порядок
  • удаление элемента сдвигает индексы
  • разные драйверы дают разный порядок ключей

Поэтому key(index) не следует использовать как основу для логики, зависящей от постоянного порядка.

Потенциальные расхождения между драйверами

При переключении драйвера через конфигурацию:

localforage.setDriver(...)

результаты key(index) могут измениться, так как изменится внутренняя модель хранения.

Асинхронность

Несмотря на простоту операции, метод всегда асинхронный, поскольку унифицированная модель localForage предполагает единый Promise-интерфейс для всех операций, включая синхронные источники вроде localStorage.

Использование callback-стиля

Поддержка обратного вызова сохраняется для совместимости:

localforage.key(0, (err, key) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(key);
});

В callback-режиме Promise также создаётся, но его можно игнорировать.

Использование Promise-стиля

Основной рекомендуемый способ:

localforage.key(0)
  .then(key => {
    console.log('Ключ:', key);
  })
  .catch(err => {
    console.error('Ошибка:', err);
  });

Обработка выходов за пределы индекса

Если индекс превышает количество доступных ключей:

  • результатом будет null
  • ошибка не выбрасывается автоматически

Это поведение важно учитывать при итерации:

let i = 0;

while (true) {
  const key = await localforage.key(i);
  if (key === null) break;
  i++;
}

Влияние изменений хранилища

При параллельных операциях:

  • добавление ключей
  • удаление ключей
  • очистка хранилища

результаты key(index) могут изменяться между вызовами. Это особенно важно в асинхронных сценариях, где состояние storage не фиксировано.

Сравнение с keys()

Метод тесно связан с:

localforage.keys()

Разница:

  • keys() возвращает массив всех ключей
  • key(index) возвращает один элемент по позиции

Фактически key можно рассматривать как частный случай обращения к результату keys().

Эквивалентная логика:

const keys = await localforage.keys();
const key = keys[index] ?? null;

Типичные сценарии применения

  • постраничный обход ключей
  • отладка содержимого хранилища
  • выборка первого/последнего элемента при условной сортировке
  • построение индексного интерфейса поверх storage

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

Оглавление