# [←](../../../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`.