100 lines
3.0 KiB
Markdown
100 lines
3.0 KiB
Markdown
# [←](../../../docs/README.md) @crux-kit/local-storage
|
|
|
|
Сервіс для роботи з `localStorage`: збереження, читання, видалення даних із серіалізацією/десеріалізацією та підтримкою TTL і namespace-префіксів.
|
|
|
|
## Як використовувати
|
|
|
|
### Ініціалізація
|
|
|
|
```ts
|
|
import { LocalStorageService } from '@crux-kit/local-storage';
|
|
|
|
export const storage = new LocalStorageService({
|
|
prefix: 'app',
|
|
logger: console,
|
|
});
|
|
```
|
|
|
|
- `prefix` — необов'язковий. Усі ключі зберігаються як `prefix:key`, що дозволяє уникнути конфліктів між різними модулями.
|
|
- `logger` — необов'язковий. Передається `console` або будь-який об'єкт із методами `error` / `log`.
|
|
|
|
### Запис і читання
|
|
|
|
```ts
|
|
storage.set('user', { id: 1, name: 'Randy Marsh' });
|
|
|
|
const user = storage.get<{ id: number; name: string }>('user');
|
|
```
|
|
|
|
Дані автоматично серіалізуються в JSON при записі та десеріалізуються при читанні.
|
|
|
|
### TTL (час життя)
|
|
|
|
```ts
|
|
// значення стане недоступним через 30 хвилин
|
|
storage.set('session', data, { ttlMs: 30 * 60 * 1000 });
|
|
|
|
// get поверне undefined і автоматично видалить ключ після закінчення TTL
|
|
const session = storage.get('session');
|
|
```
|
|
|
|
### getOrSet
|
|
|
|
Повертає збережене значення, або записує та повертає `fallback`, якщо ключ відсутній.
|
|
|
|
```ts
|
|
const lang = storage.getOrSet('lang', 'en');
|
|
|
|
// також підтримує TTL
|
|
const theme = storage.getOrSet('theme', 'dark', { ttlMs: 60 * 60 * 1000 });
|
|
```
|
|
|
|
### Перевірка існування ключа
|
|
|
|
```ts
|
|
storage.has('token'); // true | false
|
|
```
|
|
|
|
### Видалення
|
|
|
|
```ts
|
|
storage.remove('token');
|
|
```
|
|
|
|
### Всі значення як об'єкт
|
|
|
|
Повертає всі збережені записи поточного namespace у вигляді одного об'єкта. Ключі з вичерпаним TTL автоматично виключаються.
|
|
|
|
```ts
|
|
const lss = new LocalStorageService({ prefix: 'settings' });
|
|
|
|
lss.set('view', 'grid');
|
|
lss.set('sortBy', 'name');
|
|
lss.set('showHidden', true);
|
|
|
|
type Settings = {
|
|
view: string;
|
|
sortBy: string;
|
|
showHidden: boolean;
|
|
};
|
|
|
|
lss.getAll<Settings>();
|
|
// → Partial<Settings> — { view: 'grid', sortBy: 'name', showHidden: true }
|
|
```
|
|
|
|
### Список ключів
|
|
|
|
Повертає всі ключі. Якщо заданий `prefix` — повертає лише ключі поточного namespace без префікса.
|
|
|
|
```ts
|
|
storage.keys(); // ['user', 'session', 'lang']
|
|
```
|
|
|
|
### Очищення
|
|
|
|
```ts
|
|
storage.clear();
|
|
```
|
|
|
|
Якщо заданий `prefix` — видаляє лише ключі поточного namespace. Без `prefix` — очищає весь `localStorage`.
|