Ограничения хранилища по умолчанию

Idb-keyval — это минималистичная библиотека для работы с IndexedDB в JavaScript, обеспечивающая простую асинхронную работу с ключ-значение хранилищем. Несмотря на свою простоту, она наследует все ограничения и особенности самой IndexedDB, так как является лишь обёрткой над ней.

Размер хранилища

Объем доступного хранилища напрямую зависит от браузера и платформы. IndexedDB не накладывает строгого лимита на размер базы данных, однако существуют практические ограничения, связанные с безопасностью и производительностью:

Десктопные браузеры (Chrome, Firefox, Edge, Safari) обычно позволяют использовать до 50–60% свободного места на диске для всех веб-приложений. При достижении этого лимита браузер может запросить у пользователя разрешение на увеличение хранилища.
Мобильные браузеры часто ограничивают размер одной базы данных десятками мегабайт (например, 50–100 МБ), и могут автоматически очищать хранилище при нехватке памяти.
Квота на сайт может быть как фиксированной, так и динамической. В Chrome и Edge динамическая квота вычисляется по формуле: Math.min(0.6 * свободное место, 2 ГБ), где 0.6 — это максимальная доля, которую сайт может использовать без запроса разрешения.

Важно учитывать, что Idb-keyval не контролирует эти лимиты напрямую — ошибки при переполнении базы данных будут выбрасываться из IndexedDB, например QuotaExceededError.

Размер отдельных объектов

IndexedDB поддерживает хранение объектов любого размера в пределах доступной квоты, однако на практике:

Малые объекты (строки, числа, небольшие JSON) обрабатываются быстро и безопасно.
Большие объекты (например, файлы или большие массивы) могут вызвать задержки при записи и чтении, а также увеличивают вероятность отказа при недостатке квоты.
Для объектов свыше десятков мегабайт рекомендуется использовать Blob или File, чтобы избежать чрезмерного потребления памяти при сериализации.

Idb-keyval автоматически сериализует объекты с помощью structuredClone, что позволяет хранить сложные структуры данных, но не снижает размер самого объекта в IndexedDB.

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

Idb-keyval поддерживает любые данные, которые поддерживает IndexedDB:

Примитивные типы: string, number, boolean, null, undefined.
Объекты и массивы (любая вложенность).
Date, Blob, File, ArrayBuffer и TypedArray.
Map, Set и другие коллекции поддерживаются через structuredClone, но при этом объекты сериализуются, что может влиять на производительность при больших данных.

Не поддерживаются функции, DOM-элементы, циклические ссылки внутри объектов (если использовать старые браузеры без полноценного structuredClone).

Ограничения на ключи

Ключи должны быть строкой, числом, датой или массивом примитивов.
Объекты и функции не могут использоваться как ключи напрямую.
Использование сложных типов в ключах может привести к ошибкам DataError.

Idb-keyval автоматически конвертирует ключи в допустимые форматы, но в сложных случаях рекомендуется вручную нормализовать ключи (например, сериализовать объект в JSON).

Ограничения по транзакциям

Все операции Idb-keyval выполняются в асинхронных транзакциях типа readwrite или readonly:

Множественные операции могут быть выполнены последовательно или параллельно, но каждая транзакция имеет ограниченный жизненный цикл.
Длительные транзакции с большим количеством данных могут быть прерваны браузером, если пользователь закроет вкладку или возникнут ошибки квоты.
Для пакетной записи рекомендуется использовать метод setMany или группировать операции внутри одной транзакции, чтобы минимизировать количество открытых транзакций.

Поведение при переполнении

При превышении квоты IndexedDB выбрасывает ошибки, которые Idb-keyval передает вызывающему коду:

QuotaExceededError — превышена максимальная доступная квота для сайта.
UnknownError или AbortError — возможны при нестандартных сбоях транзакции.

Реакция на эти ошибки должна быть встроена в код приложения, например, через обработку try/catch или через Promise.catch для асинхронных методов.

Ограничения синхронизации

IndexedDB и, соответственно, Idb-keyval, работают локально в браузере.
Данные не синхронизируются автоматически между устройствами. Для этого нужно использовать сторонние механизмы (например, серверное API или библиотеку типа Firebase).