Метод config: глобальная настройка

Метод config задаёт базовые параметры работы библиотеки localForage на уровне глобального экземпляра. Эти настройки определяют поведение хранилища до момента начала операций чтения и записи, влияя на выбор драйвера, имя базы данных, имя хранилища и другие системные параметры.

Именно глобальная конфигурация используется по умолчанию всеми вызовами localForage, если не создан отдельный экземпляр через createInstance.

Сигнатура метода config

Метод вызывается напрямую на объекте localForage:

localForage.config(options);

Параметр options — это объект, содержащий набор поддерживаемых конфигурационных ключей.

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

Основные параметры конфигурации

name

Параметр name определяет имя базы данных (или namespace), которое будет использоваться во всех backend-хранилищах.

localForage.config({
  name: 'myApp'
});

В зависимости от драйвера это значение интерпретируется по-разному:

  • IndexedDB: имя базы данных
  • WebSQL: имя базы данных
  • localStorage: префикс ключей

Использование уникального name критично для предотвращения конфликтов между приложениями, работающими в одном origin.

storeName

storeName задаёт имя хранилища внутри базы данных.

localForage.config({
  name: 'myApp',
  storeName: 'userData'
});

Особенности:

  • В IndexedDB это object store
  • В WebSQL — таблица
  • В localStorage — часть ключевого пространства

Требования:

  • строка без пробелов
  • желательно использовать латиницу
  • нельзя начинать с цифры в IndexedDB-режиме

Ошибки в storeName часто приводят к исключениям при инициализации драйвера.

driver

Параметр driver задаёт список допустимых backend-хранилищ в порядке приоритета.

localForage.config({
  driver: [
    localForage.INDEXEDDB,
    localForage.WEBSQL,
    localForage.LOCALSTORAGE
  ]
});

Доступные значения:

  • localForage.INDEXEDDB
  • localForage.WEBSQL
  • localForage.LOCALSTORAGE

Механизм работы:

  1. localForage перебирает драйверы по порядку
  2. проверяет поддержку в браузере
  3. выбирает первый доступный вариант
  4. инициализирует его как активный backend

Такой подход обеспечивает деградацию без потери функциональности в старых окружениях.

version

Параметр version используется только для IndexedDB.

localForage.config({
  name: 'myApp',
  version: 2.0
});

При изменении версии:

  • IndexedDB может инициировать onupgradeneeded
  • структура базы данных может быть пересоздана
  • существующие данные могут быть мигрированы

Важно учитывать:

  • изменение версии без обработки миграции может привести к потере данных
  • WebSQL и localStorage игнорируют этот параметр

size

Параметр size актуален только для WebSQL.

localForage.config({
  size: 50 * 1024 * 1024
});

Задаёт максимальный размер базы данных в байтах.

Особенности:

  • браузеры могут игнорировать значение
  • используется только при создании WebSQL базы
  • не влияет на IndexedDB и localStorage

Поведение глобальной конфигурации

Метод config влияет исключительно на глобальный экземпляр localForage.

Это означает:

  • все вызовы localForage.setItem, getItem, removeItem используют эти настройки
  • изменение конфигурации после инициализации может быть проигнорировано или привести к непредсказуемому поведению
  • рекомендуется вызывать config до любых асинхронных операций

Порядок инициализации

Корректный порядок использования:

localForage.config({
  name: 'appDB',
  storeName: 'cache',
  driver: [
    localForage.INDEXEDDB,
    localForage.LOCALSTORAGE
  ]
});

localForage.setItem('key', 'value');

Некорректный порядок:

localForage.setItem('key', 'value');

localForage.config({
  name: 'appDB'
});

Во втором случае настройки могут не примениться к уже инициализированному драйверу.

Влияние на драйверную систему

Конфигурация напрямую определяет стратегию выбора backend-хранилища.

Алгоритм:

  1. Проверка массива driver
  2. Попытка подключения каждого драйвера
  3. Инициализация первого успешного
  4. Кэширование выбранного драйвера внутри экземпляра

Если ни один драйвер недоступен:

  • операции возвращают rejected Promise
  • библиотека не создаёт fallback вручную

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

При использовании IndexedDB параметры name, storeName и version формируют структуру базы:

  • name → имя database
  • version → номер версии schema
  • storeName → object store

При изменении version может происходить пересоздание object store, если обработчик миграции не задан библиотекой или не поддерживается окружением.

Особенности работы с localStorage

Для localStorage конфигурация упрощается:

  • name используется как префикс ключей
  • storeName добавляется как часть составного ключа
  • version и size игнорируются

Пример фактического ключа:

myApp/userData/someKey

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

Ограничения глобальной конфигурации

Глобальный config имеет ряд ограничений:

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

Для изолированных сценариев требуется использование createInstance, однако глобальный config остаётся базовой точкой входа.

Влияние на кэширование драйвера

После выбора драйвера localForage кэширует его внутри текущего контекста:

  • повторный вызов config не гарантирует смену драйвера
  • уже активный backend остаётся в памяти
  • смена возможна только до первого обращения к API

Это поведение связано с ленивой инициализацией (lazy initialization).

Пример комплексной конфигурации

localForage.config({
  name: 'projectDB',
  storeName: 'sessionStore',
  version: 1.0,
  size: 20 * 1024 * 1024,
  driver: [
    localForage.INDEXEDDB,
    localForage.WEBSQL,
    localForage.LOCALSTORAGE
  ]
});

Такая конфигурация задаёт:

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

Типичные ошибки конфигурации

Конфигурация после операций

Любые операции до вызова config могут закрепить драйвер до изменения настроек.

Неверный storeName

Использование пробелов, спецсимволов или кириллицы может привести к ошибкам в IndexedDB.

Пустой driver массив

Если передан пустой массив:

localForage.config({
  driver: []
});

библиотека не сможет выбрать backend и все операции завершатся ошибкой.

Влияние на архитектуру приложения

Глобальный config часто используется как точка централизованной настройки:

  • определение namespace приложения
  • разделение окружений (dev/prod)
  • выбор стратегии хранения данных
  • контроль совместимости браузеров

В крупных приложениях конфигурация задаётся один раз при bootstrap-фазе, после чего библиотека работает как абстрактный слой над storage-API браузера.

Поведение при отсутствии конфигурации

Если config не вызывается:

  • используются значения по умолчанию
  • name = "localforage"
  • storeName = "keyvaluepairs"
  • driver = автоматический выбор всех доступных

Такой режим подходит для простых сценариев, но не обеспечивает изоляции данных между приложениями.

Оглавление