Метод setItem: сохранение значения

Общая концепция операции сохранения

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

В отличие от синхронного localStorage.setItem, операция выполняется асинхронно и возвращает Promise, что позволяет не блокировать основной поток выполнения JavaScript.

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

localforage.setItem(key, value)

Параметры:

  • key — строковый идентификатор записи
  • value — сохраняемое значение любого поддерживаемого типа

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

  • Promise → разрешается сохранённым значением

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

Операция записи не выполняется мгновенно. Внутренне библиотека выбирает доступный драйвер и делегирует сохранение соответствующему API браузера.

Основные этапы выполнения:

  1. Определение активного драйвера (IndexedDB, WebSQL, localStorage)
  2. Сериализация значения (при необходимости)
  3. Запись в хранилище
  4. Возврат результата через Promise

Асинхронность позволяет избегать блокировки UI, что особенно критично при работе с большими объектами.

Поддерживаемые типы данных

Метод setItem способен сохранять широкий спектр структур:

  • строки
  • числа
  • булевы значения
  • объекты
  • массивы
  • Date
  • бинарные данные (Blob, ArrayBuffer)
  • вложенные структуры

Пример:

localforage.setItem('user', {
  id: 42,
  name: 'Alex',
  preferences: {
    theme: 'dark',
    language: 'ru'
  }
});

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

Поведение при повторной записи

При вызове setItem с уже существующим ключом выполняется полное перезаписывание значения.

await localforage.setItem('session', { token: 'abc' });
await localforage.setItem('session', { token: 'def' });

После выполнения второй операции в хранилище останется только последнее значение.

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

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

localforage.setItem('counter', 10)
  .then((value) => {
    console.log(value); // 10
  });

Это поведение позволяет строить цепочки операций без дополнительного чтения из хранилища.

Работа с драйверами хранения

Поведение setItem зависит от выбранного драйвера:

IndexedDB

  • Асинхронная запись
  • Поддержка сложных объектов
  • Высокая производительность
  • Используется по умолчанию в современных браузерах

WebSQL (устаревший)

  • Ограниченная поддержка
  • SQL-подобные операции внутри реализации

localStorage

  • Синхронная эмуляция асинхронного интерфейса
  • Сериализация в строки (JSON)
  • Ограничение по объёму данных

Сериализация данных

При использовании драйвера, не поддерживающего structured clone, выполняется сериализация в JSON.

Ограничения такого подхода:

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

Пример:

localforage.setItem('config', {
  mode: 'test',
  flags: [true, false, true]
});

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

setItem может завершиться отклонением Promise в следующих случаях:

  • превышение квоты хранилища
  • отсутствие доступа к API браузера
  • блокировка со стороны приватного режима
  • ошибки драйвера IndexedDB
  • некорректные данные для сериализации

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

localforage.setItem('largeData', bigObject)
  .catch((err) => {
    console.error('Ошибка сохранения:', err);
  });

Производительность операции

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

  • выбранного драйвера
  • размера сохраняемого объекта
  • структуры данных
  • состояния браузера

Наиболее быстрым вариантом считается IndexedDB, особенно при работе с большими наборами данных. localStorage демонстрирует худшую производительность из-за синхронной природы и строковой сериализации.

Работа с большими данными

При сохранении больших объектов возможны дополнительные задержки, связанные с копированием структур данных.

Особенно значимыми становятся:

  • глубокие вложенные объекты
  • массивы с тысячами элементов
  • бинарные данные (изображения, файлы)
const buffer = new ArrayBuffer(1024 * 1024);

localforage.setItem('binary', buffer);

Поведение при конкурентных операциях

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

localforage.setItem('key', 1);
localforage.setItem('key', 2);
localforage.setItem('key', 3);

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

Особенности работы с ключами

Ключи интерпретируются как уникальные идентификаторы записей. Повторное использование ключа приводит к перезаписи.

Рекомендуется учитывать:

  • чувствительность к регистру
  • отсутствие автоматической нормализации
  • строковый тип ключа как основной

Внутренний механизм записи

При вызове setItem библиотека выполняет следующие действия:

  1. Проверка доступности драйвера
  2. Подготовка транзакции (в IndexedDB)
  3. Преобразование значения
  4. Запись в хранилище
  5. Возврат результата через Promise API

Эта цепочка скрыта от разработчика и управляется внутренним API библиотеки.

Особенности использования с различными средами

В браузерных окружениях операция работает через Web APIs. В гибридных средах (например, Electron) поведение зависит от реализации IndexedDB в Chromium.

В старых браузерах fallback-механизм может переключаться на localStorage, что снижает функциональность.

Итоговые характеристики метода

Метод setItem в localForage характеризуется следующими свойствами:

  • асинхронная модель выполнения
  • универсальная работа с типами данных
  • автоматический выбор драйвера
  • поддержка больших структур
  • единый API для различных хранилищ
  • прозрачная обработка сериализации
Оглавление