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

Метод keys в библиотеке localForage имеет следующую сигнатуру:

localforage.keys(callback?: Function): Promise<string[]>

или в полностью промис-ориентированном виде:

localforage.keys(): Promise<string[]>

Метод возвращает промис, который разрешается массивом строк — ключей, хранящихся в текущем хранилище.

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

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

Основная задача метода — предоставить возможность:

  • перечислить все сохранённые записи;
  • выполнить массовую обработку данных;
  • реализовать синхронизацию или миграцию;
  • построить индексы поверх ключей;
  • анализировать состояние хранилища.

Поведение и особенности выполнения

Метод работает асинхронно вне зависимости от выбранного драйвера хранения. Даже если backend фактически синхронный (например, localStorage), localForage приводит вызов к промис-формату.

Внутренне выполнение зависит от драйвера:

  • IndexedDB — асинхронная транзакция с курсором по store;
  • WebSQL — выполнение SQL-запроса SEL ECT key FR OM table;
  • localStorage — итерация по localStorage.length.

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

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

Promise<string[]>

Содержимое массива:

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

Полная сигнатура с типизацией

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

interface LocalForage {
  keys(): Promise<string[]>;
  keys(callback?: (err: any, keys: string[]) => void): Promise<string[]>;
}

Важно учитывать, что callback-стиль считается устаревающим паттерном и применяется только для обратной совместимости.

Поведение callback-параметра

Если передан callback:

localforage.keys((err, keys) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(keys);
});
  • err содержит ошибку при сбое доступа к storage;
  • keys — массив строк ключей;
  • промис при этом всё равно возвращается.

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

1. Отсутствие гарантии порядка

Порядок ключей не является детерминированным. Например:

  • IndexedDB может возвращать порядок по вставке;
  • localStorage — порядок по внутреннему хранению ключей;
  • WebSQL — порядок зависит от SQL-запроса без ORDER BY.

2. Отсутствие фильтрации

Метод возвращает все ключи без исключений:

  • служебные ключи (если использовались);
  • ключи разных типов данных;
  • ключи, созданные в разных версиях приложения.

Фильтрация выполняется на уровне приложения.

3. Производительность

Сложность операции:

  • IndexedDB: O(n) по количеству записей;
  • localStorage: O(n);
  • WebSQL: O(n), но с накладными затратами на SQL.

При большом объёме данных вызов может быть затратным по времени.

Пример базового использования

localforage.keys().then((keys) => {
  console.log('Все ключи:', keys);
});

Обработка ошибок

Ошибки могут возникать в следующих случаях:

  • повреждение storage;
  • отсутствие прав доступа (например, приватный режим браузера);
  • квота хранилища;
  • сбой IndexedDB транзакции.

Пример обработки:

localforage.keys()
  .then(keys => {
    console.log(keys);
  })
  .catch(err => {
    console.error('Ошибка получения ключей:', err);
  });

Использование с async/await

async function getAllKeys() {
  const keys = await localforage.keys();
  return keys;
}

Асинхронная форма упрощает композицию с другими операциями:

async function clearIfEmpty() {
  const keys = await localforage.keys();
  if (keys.length === 0) {
    console.log('Хранилище пустое');
  }
}

Работа в разных драйверах

IndexedDB

  • наиболее стабильная реализация;
  • использует cursor iteration;
  • лучше масштабируется на больших объёмах.

WebSQL

  • встречается редко;
  • использует SQL запросы;
  • может иметь различия в порядке выдачи.

localStorage

  • полностью синхронное внутреннее хранилище;
  • keys извлекаются через перебор Object.keys(localStorage);
  • возможны сторонние ключи от других приложений на домене.

Сравнение с аналогичными методами

  • length — возвращает количество записей, но не сами ключи;
  • iterate — позволяет обход с доступом к значениям;
  • getItem — работает по конкретному ключу;
  • keys — даёт только список идентификаторов без значений.

Метод keys занимает промежуточную позицию между статистикой и полным обходом данных.

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

Инвентаризация хранилища

const keys = await localforage.keys();

Далее возможно:

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

Массовая очистка по условию

const keys = await localforage.keys();

for (const key of keys) {
  if (key.startsWith('temp_')) {
    await localforage.removeItem(key);
  }
}

Синхронизация с сервером

const keys = await localforage.keys();
const data = await Promise.all(keys.map(k => localforage.getItem(k)));

Ограничения метода

  • отсутствие сортировки;
  • отсутствие фильтра на уровне API;
  • возможные задержки при больших наборах данных;
  • невозможность частичной выборки (нет параметров offset/limit).

Внутренние аспекты поведения

При вызове метод:

  1. определяет активный драйвер;
  2. открывает соединение с storage;
  3. выполняет итерацию всех ключей;
  4. собирает результаты в массив;
  5. возвращает промис с массивом строк.

Каждый драйвер реализует этот процесс по-своему, но контракт API остаётся единым.

Особенности совместимости

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

Оглавление