Initial commit

2026-06-25 15:53:49 +03:00
commit 1bb0b7e68a
1517 changed files with 218469 additions and 0 deletions
@@ -0,0 +1,99 @@
+# [←](../../../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`.