Особенности

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

(English Documentation —> README.md)

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

— Поддержка LocalStorage, SessionStorage, мини-программы WeChat, QQ, Alipay, Baidu и Toutiao и возможность настройки адаптеров для адаптации к другим средам хранения.

— Поддержка пространств имён для изоляции хранения в разных пространствах имён.

— Стратегия истечения срока действия поддерживается.

— Сильное чтение и запись (зависит от сериализации JSON).

— Синхронный и асинхронный вызовы поддерживаются (в зависимости от адаптера).

— Поддерживается TypeScript.

Использование:

Установка:

npm install @skit/storage

Импорт:

/* require */
const $$storage = require('@skit/storage');

/* import */
import $$storage from '@skit/storage';

Основное использование:

/* Запись строки */
$$storage.set('key', 'value');

/* Запись числового значения */
$$storage.set('key', 1);

/* Запись объекта */
$$storage.set('key', { value: 'object' });

/* Чтение */
let val = $$storage.get('key'); // Автоматически попытается десериализовать тип, записанный при записи

/* Чтение, если не существует, возвращает значение по умолчанию */
let val = $$storage.get('key', 'default value');

/* Определить, существует ли указанный ключ */
let flag = $$storage.has('key');

/* Удалить */
$$storage.remove('key');

/* Очистить */
$$storage.clear();

Пакетная операция:

/* Пакетная запись */
$$storage.setAll({ key1: 'val1', key2: 'val2' });

/* Пакетное чтение */
let item = $$storage.getAll(['key1', 'key2']); // { key1: 'val1', key2: 'val2' }

/* Пакетное удаление */
$$storage.removeAll(['key1', 'key2']);

/* Получить все ключи */
$$storge.keys(); // ['key1', 'key2']

Стратегия истечения срока:

/* Записать и установить относительное время истечения срока (единица измерения: миллисекунды) */
$$storage.set('key', 'val', { ttl: 1000 });

/* Записать, затем установить относительное время истечения срока (единица измерения: миллисекунды) */
$$storage.set('key', 'val');
$$storage.ttl('key', 1000);

/* Установить абсолютное время истечения срока */
$$storage.ttl('key', new Date('2020-12-31 23:59:59'));

/* Отменить срок действия */
$$storage.ttl('key', -1);

/* Посмотреть, сколько времени осталось до истечения срока (единицы измерения: миллисекунды) */
$$storage.ttl('key'); // null означает, что срок действия не истёк

Пространство имён:

/* Создать два пространства имён */
let storage1 = $$storage.create({ namespace: 'ns1' });
let storage2 = $$storage.create({ namespace: 'ns1' });

/* Пространства имён изолированы друг от друга, и можно установить один и тот же ключ */
storage1.set('key', 'val1');
storage2.set('key', 'val2');
storage1.get('key'); // val1
storage2.get('key'); // val2

/* Очистить ключи в отдельном пространстве имён */
storage1.clear();

/* Очистить все ключи во всех пространствах имён */
$$storage.clear();

Асинхронная операция:

/* Асинхронная запись */
$$storage.setAsync('key', 'val');

/* Асинхронное чтение */
$$storage.getAsync('key').then((val) => {});

/* Другие методы опущены, все они являются синхронными методами с добавлением Async */

Часто задаваемые вопросы:

1. Как использовать LocalStorage / SessionStorage?

По умолчанию используется LocalStorage. Если вы хотите переключиться на SessionStorage, вы можете:

import $$storage, { SessionStorageAdapter } from '@skit/storage';

const storage = $$storage.create({ adapter: SessionStorageAdapter });
storage.set('key', 'val');
storage.get('key');

2. Как использовать его в мини-программах?

Аналогично предыдущему:

import $$storage, { MiniprogramAdapter } from '@skit/storage';

const storage = $$storage.create({ adapter: MiniprogramAdapter });
storage.set('key', 'val');
storage.get('key');

3. Как написать собственный адаптер?

Вы можете создать собственный адаптер, следуя примеру встроенных адаптеров, для доступа к локальному хранилищу в различных средах (например, в плагине Chrome).

При использовании просто создайте его так же, как и выше:

import MyAdapter from './my-adapter';

const storage = $$storage.create({ adapter: MyAdapter });

4. Как реализуется стратегия истечения срока?

Поскольку базовое локальное хранилище не предоставляет метода установки TTL, фактически при записи записывается время истечения срока для каждого ключа, и при извлечении оно сравнивается с текущим временем. Если срок истёк, ключ удаляется.

Следует отметить, что это поведение является «ленивым», то есть только операции чтения удаляют просроченные ключи.

Из-за высокой стоимости этой операции только несколько методов, таких как has(), get() и ttl(), выполняют ленивое удаление. По умолчанию метод keys() не выполняет ленивого удаления. Если вам нужно вернуть только ключи с неистёкшим сроком действия, вы можете сделать следующее:

/* Возвращает только ключи с неистёкшим сроком */
$$storage.keys({ eliminated: true });

5. Как хранить Function и другие специальные типы?

Первоначально планировалось реализовать сериализатор JS для поддержки хранения Function, Symbol, BigInt и других специальных объектов. Однако, учитывая, что для восстановления после eval() и других операций, которые не поддерживаются в мини-приложениях, а также сложность реализации этого сериализатора, эта функция была исключена из инструмента. Простое решение проблемы циклических ссылок в JSON.stringify() было реализовано.

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

6. Поддерживает ли он IE?

В каталоге dist есть несколько версий на выбор: index.min.js: UMD версия, минимально адаптирован для IE8.

index.modern.min.js: UMD версия, адаптирован только для современных браузеров, поддерживающих все функции ES6.

index.cjs.min.js: CommonJS версия, адаптирована только для среды Node.js 9.0+.

index.esm.min.js: версия на основе модулей ES, адаптирована только для современных браузеров или среды Node.js, поддерживающих модули ES.

P.S. В принципе, index.min.js также может поддерживать IE6, но из-за отсутствия в IE6 функции LocalStorage необходимо самостоятельно написать адаптер на основе IE UserData или использовать полифил от третьей стороны.