Articles
Введение в TypeScript
TypeScript и Web Storage

TypeScript и Web Storage

В этой статье рассматриваются TypeScript и Web Storage.

Мы рассматриваем TypeScript и Web Storage, включая практические примеры.

YouTube Video

TypeScript и Web Storage

Браузерный Web Storage — это хранилище ключ/значение для строк. Он легковесный с синхронным API, но учтите, что он может хранить только строки, и вам нужно обрабатывать исключения, такие как превышение квоты хранилища. В сочетании с TypeScript вы можете добавить типобезопасность, безопасную сериализацию/десериализацию, централизованное управление ключами, а также истечение срока действия и версионирование, в результате получится продакшен-готовое решение.

localStorage и sessionStorage

localStorage — это постоянное хранилище, которое сохраняется после закрытия браузера, тогда как sessionStorage — это сеансовое хранилище на вкладку/окно, которое очищается при закрытии вкладки. Оба хранят значения как пары ключ‑значение (строки).

1// Simple usage example: store and retrieve a string
2// This example uses localStorage to persist a username.
3localStorage.setItem('username', 'alice');
4console.log('saved username:', localStorage.getItem('username')); // "alice"
5
6// session storage example
7sessionStorage.setItem('session-id', 'xyz-123');
8console.log('session id:', sessionStorage.getItem('session-id')); // "xyz-123"
  • Этот код — пример сохранения и извлечения строк. Поскольку Web Storage может хранить только строки, объекты перед сохранением нужно преобразовывать в JSON.

Пример с разбором JSON

Чтобы сохранять и восстанавливать объекты в Web Storage, используйте JSON.stringify / JSON.parse.

1// Simple write & read with JSON
2// Store a small object as JSON and read it back.
3const user = { id: 1, name: "Alice" };
4localStorage.setItem("app:user", JSON.stringify(user));
5
6const raw = localStorage.getItem("app:user");
7const parsed = raw ? (JSON.parse(raw) as { id: number; name: string }) : null;
8
9console.log("user:", parsed); // user: { id: 1, name: "Alice" }
  • Этот код — минимальный рабочий пример. В реальных приложениях необходимо учитывать исключения, такие как ошибки парсинга и исчерпание квоты хранилища.

Пример обработки исключений при разборе JSON

Здесь мы предоставляем обертку, чтобы сделать чтение и запись безопасными и обрабатывать ошибки JSON.parse и исключения setItem.

 1// Safe JSON helpers
 2// These helpers handle parse errors and memory/storage issues separately.
 3export function safeParseJson<T>(raw: string | null): T | null {
 4  if (raw == null) return null;
 5
 6  try {
 7    return JSON.parse(raw) as T;
 8  } catch (error: any) {
 9    if (error instanceof SyntaxError) {
10      console.error("JSON parse error:", error.message);
11      return null;
12    }
13
14    console.error("Unexpected JSON error:", error);
15    return null;
16  }
17}
18
19// Safe setter for JSON values
20export function setJson(storage: Storage, key: string, value: unknown): void {
21  try {
22    const json = JSON.stringify(value);
23    storage.setItem(key, json);
24  } catch (error: any) {
25    if (error?.name === "QuotaExceededError") {
26      console.error("Storage quota exceeded while saving JSON:", error.message);
27    } else if (error instanceof TypeError) {
28      console.error("JSON serialization failed:", error.message);
29    } else {
30      console.error("Unexpected error while setting JSON:", error);
31    }
32  }
33}
34
35// Safe getter for JSON values
36export function getJson<T>(storage: Storage, key: string, fallback?: T): T | null {
37  const parsed = safeParseJson<T>(storage.getItem(key));
38  return parsed ?? (fallback ?? null);
39}
  • Этот утилитарный модуль можно переиспользовать по всему приложению. Добавляйте дополнительную обёртку, когда хотите добавить try/catch.

Пример сохранения с TTL (сроком действия)

Так как у самого Web Storage нет TTL, управляйте им, добавляя к значению expiresAt.

 1// TTL wrapper
 2// Store { value, expiresAt } and automatically expire items on read.
 3type WithTTL<T> = { value: T; expiresAt: number | null };
 4
 5export function setWithTTL<T>(storage: Storage, key: string, value: T, ttlMs?: number) {
 6  const payload: WithTTL<T> = { value, expiresAt: ttlMs ? Date.now() + ttlMs : null };
 7  setJson(storage, key, payload);
 8}
 9
10export function getWithTTL<T>(storage: Storage, key: string): T | null {
11  const payload = getJson<WithTTL<T>>(storage, key);
12  if (!payload) return null;
13  if (payload.expiresAt && Date.now() > payload.expiresAt) {
14    storage.removeItem(key);
15    return null;
16  }
17  return payload.value;
18}
  • TTL полезен для кеша и автосохранения (черновиков) и позволяет уменьшить несогласованности.

Пример централизованного управления ключами и пространств имён (избежание коллизий)

Стандартизация ключей в виде prefix + version + name снижает число коллизий и упрощает миграции.

 1// Key factory with namespacing and versioning
 2// Create namespaced keys like "myapp:v1:theme" to avoid collisions.
 3const APP = "myapp";
 4const V = "v1";
 5
 6const ns = (k: string) => `${APP}:${V}:${k}`;
 7
 8const Keys = {
 9  theme: ns("theme"),
10  user: ns("user"),
11  cart: ns("cart"),
12  draft: ns("draft"),
13};
  • Добавление пространства имен в ключ упрощает переключение версий или последующую очистку.

Пример превышения квоты (QuotaExceededError) и стратегий резервного поведения

Учтите, что при выполнении setItem может возникнуть QuotaExceededError, и продумайте стратегию резервного варианта на случай неудачи сохранения данных. Например, при превышении объема хранилища можно удалить старые данные или переключиться на sessionStorage либо кэш в памяти, чтобы сохранить общую стабильность приложения.

 1// Quota-safe set with fallback to in-memory storage
 2// Return true if stored, false otherwise.
 3export function trySetJson(storage: Storage, key: string, value: unknown, fallback?: Map<string, string>): boolean {
 4  try {
 5    storage.setItem(key, JSON.stringify(value));
 6    return true;
 7  } catch (err) {
 8    console.warn("Failed to set item:", key, err);
 9    if (fallback) {
10      try {
11        fallback.set(key, JSON.stringify(value));
12        return true;
13      } catch {
14        return false;
15      }
16    }
17    return false;
18  }
19}
20
21// Example fallback usage
22const inMemoryFallback = new Map<string, string>();
23const ok = trySetJson(localStorage, Keys.cart, { items: [] }, inMemoryFallback);
24if (!ok) console.log("Saved to fallback map instead");
  • В зависимости от выбранного резервного варианта долговременное хранение данных может не гарантироваться. Поэтому выбирайте подходящее место хранения в соответствии с вашим сценарием использования. Например, в режиме приватного просмотра или при ограничениях хранилища можно сохранить работоспособность, временно используя память или sessionStorage.

Пример синхронизации между вкладками (событие storage) и уведомлений в той же вкладке

С помощью window.addEventListener('storage', …) можно обнаруживать изменения хранилища, произошедшие в других вкладках. Однако это событие не срабатывает в той же вкладке. Поэтому для уведомлений об изменениях в той же вкладке публикуйте собственные события с помощью CustomEvent.

 1// Cross-tab and same-tab notification helpers
 2// storage event fires on other tabs; use CustomEvent for same-tab listeners.
 3const SAME_TAB_EVENT = "storage:changed";
 4
 5function notifyChanged(key: string) {
 6  window.dispatchEvent(new CustomEvent(SAME_TAB_EVENT, { detail: { key } }));
 7}
 8
 9function setJsonWithNotify(storage: Storage, key: string, value: unknown) {
10  setJson(storage, key, value);
11  notifyChanged(key);
12}
13
14// Listeners
15window.addEventListener("storage", (e) => {
16  if (e.key === Keys.theme) {
17    const theme = safeParseJson<string>(e.newValue);
18    console.log("Theme changed in another tab:", theme);
19  }
20});
21
22window.addEventListener(SAME_TAB_EVENT, (e: Event) => {
23  const detail = (e as CustomEvent).detail as { key: string };
24  console.log("Changed in this tab:", detail.key);
25});
  • С этим кодом можно синхронизировать изменения хранилища как между другими вкладками, так и в текущей вкладке.

Типобезопасный реестр (строгая типизация по ключам)

Определите соответствие ключей и типов в TypeScript, чтобы предотвратить ошибки при сохранении и извлечении.

 1// Typed registry that enforces types per key
 2// Registry maps keys to their allowed types.
 3type Registry = {
 4  [k in typeof Keys.theme]: "light" | "dark";
 5} & {
 6  [k in typeof Keys.user]: { id: number; name: string };
 7};
 8
 9type KeyOf<R> = Extract<keyof R, string>;
10
11export const TypedStore = {
12  get<K extends KeyOf<Registry>>(key: K, storage: Storage = localStorage): Registry[K] | null {
13    return getJson<Registry[K]>(storage, key);
14  },
15  set<K extends KeyOf<Registry>>(key: K, value: Registry[K], storage: Storage = localStorage): void {
16    setJson(storage, key, value);
17  },
18  remove<K extends KeyOf<Registry>>(key: K, storage: Storage = localStorage): void {
19    storage.removeItem(key);
20  },
21};
  • {^ i18n_speak 型をキーに関連付けることで、ランタイムでの誤使用をコンパイル時に検出でき、安全性を高めることができます。 ^}

Сериализация/восстановление для сложных типов (Date/Map и т. п.)

Чтобы корректно восстанавливать такие объекты, как Date и Map, используйте replacer и reviver в JSON.stringify.

 1// Serializing Dates with replacer and reviver
 2// Custom replacer marks Date objects for correct revival.
 3function replacer(_k: string, v: unknown) {
 4  if (v instanceof Date) return { __type: "Date", value: v.toISOString() };
 5  return v;
 6}
 7
 8function reviver(_k: string, v: any) {
 9  if (v && v.__type === "Date") return new Date(v.value);
10  return v;
11}
12
13function setJsonWithDates(storage: Storage, key: string, value: unknown) {
14  storage.setItem(key, JSON.stringify(value, replacer));
15}
16
17function getJsonWithDates<T>(storage: Storage, key: string): T | null {
18  const raw = storage.getItem(key);
19  if (!raw) return null;
20  try { return JSON.parse(raw, reviver) as T; } catch { return null; }
21}
  • При таком подходе объекты Date корректно восстанавливаются как Date. Аналогично, Map и Set также можно пометить и восстановить.

Пример версионирования и стратегий миграции

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

 1// Versioned payload pattern for migrations
 2// Keep { v, data } and migrate on read if necessary.
 3type VersionedPayload<T> = { v: number; data: T };
 4
 5function migrateUserV1toV2(u1: { id: number; name: string }) {
 6  return { id: u1.id, profile: { displayName: u1.name } };
 7}
 8
 9function readUserAnyVersion(): { id: number; profile: { displayName: string } } | null {
10  const raw = localStorage.getItem(Keys.user);
11  if (!raw) return null;
12  try {
13    const obj = JSON.parse(raw) as VersionedPayload<any>;
14    if (obj.v === 2) {
15      return obj.data;
16    } else if (obj.v === 1) {
17      const migrated = migrateUserV1toV2(obj.data);
18      localStorage.setItem(Keys.user, JSON.stringify({ v: 2, data: migrated }));
19      return migrated;
20    }
21    return null;
22  } catch (err) {
23    console.error("migration parse error", err);
24    return null;
25  }
26}
  • Наращивая небольшие миграции, можно сохранять обратную совместимость.

Пример обработки в SSR (server-side rendering)

В средах без window прямое обращение к localStorage приведёт к падению, поэтому используйте проверки окружения.

1// Guard for SSR
2// Return a Storage-compatible object or null when not in browser.
3export const isBrowser = (): boolean => typeof window !== "undefined" && typeof window.localStorage !== "undefined";
4
5export const safeLocalStorage = (): Storage | null => (isBrowser() ? window.localStorage : null);
6
7// Usage
8const ls = safeLocalStorage();
9if (ls) setJson(ls, Keys.theme, "dark");
  • Для кода с поддержкой SSR всегда проверяйте typeof window.

Практические советы

  • Ограничивайте частоту записей с помощью debounce/throttle (чтобы сгладить всплески из‑за действий в UI).
  • Управляйте ключами через пространство имён + версию, например app:v1:....
  • Как правило, не храните чувствительные данные (access tokens и т. п.). Если необходимо, используйте короткие сроки жизни плюс серверную валидацию или WebCrypto.
  • Ёмкость зависит от браузера (несколько мегабайт), поэтому большие данные храните в IndexedDB.
  • Используйте CustomEvent для уведомлений в той же вкладке и storage — для межвкладочной синхронизации.
  • В SSR всегда проверяйте typeof window.

Сводный класс «type‑safe store»

Давайте рассмотрим пример реализации обобщённого класса, который объединяет элементы, которые мы уже обсуждали, включая пространства имён, типобезопасность, истечение срока действия (TTL) и обработку исключений. В реальных продуктах стоит добавить тесты, логирование, удаление старых данных на основе LRU, шифрование и т. п.

 1// Comprehensive TypedStorage store integrating many patterns shown above.
 2// - type-safe registry per key
 3// - prefix (namespace + version)
 4// - trySet with fallback
 5// - same-tab notify
 6// - TTL optional getter/setter
 7type Jsonifiable = string | number | boolean | null | Jsonifiable[] | { [k: string]: Jsonifiable };
 8
 9interface StoreOptions {
10  storage?: Storage | null;   // default: auto-detected localStorage or null
11  prefix?: string;            // e.g., "myapp:v1"
12  sameTabEvent?: string | null;
13  fallback?: Map<string, string>; // in-memory fallback
14}
  • Этот код показывает конфигурацию и определения типов для построения типобезопасного, функционально богатого хранилища ключ-значение.
 1export class TypedStorage<Reg extends Record<string, Jsonifiable | object>> {
 2  private storage: Storage | null;
 3  private prefix: string;
 4  private sameTabEvent: string | null;
 5  private fallback?: Map<string, string>;
 6
 7  constructor(private registry: Reg, opts: StoreOptions = {}) {
 8    this.storage = opts.storage ?? (typeof window !== "undefined" ? window.localStorage : null);
 9    this.prefix = (opts.prefix ?? "app:v1") + ":";
10    this.sameTabEvent = opts.sameTabEvent ?? "storage:changed";
11    this.fallback = opts.fallback;
12  }
13
14  private k(key: keyof Reg & string) { return this.prefix + key; }
  • Этот код является ядром класса TypedStorage, обеспечивающего типобезопасное хранилище ключ-значение. Он управляет допустимыми ключами и их типами на основе registry и генерирует ключи хранилища с префиксом. Кроме того, он использует localStorage и резерв в памяти, а также позволяет задать имя события для уведомлений об изменениях в той же вкладке.
 1  // Basic get with optional TTL-aware retrieval
 2  get<K extends keyof Reg & string>(key: K): Reg[K] | null {
 3    const fullKey = this.k(key);
 4    try {
 5      const raw = this.storage ? this.storage.getItem(fullKey) : this.fallback?.get(fullKey) ?? null;
 6      if (!raw) return null;
 7      // Check if value is TTL-wrapped
 8      const maybe = safeParseJson<{ value: Reg[K]; expiresAt?: number }>(raw);
 9      if (maybe && typeof maybe.expiresAt === "number") {
10        if (maybe.expiresAt && Date.now() > maybe.expiresAt) {
11          this.remove(key);
12          return null;
13        }
14        return maybe.value;
15      }
16      return safeParseJson<Reg[K]>(raw);
17    } catch (err) {
18      console.error("TypedStorage.get error", err);
19      return null;
20    }
21  }
  • Метод get извлекает значение по указанному ключу типобезопасным способом и при необходимости поддерживает значения с TTL (сроком действия).
 1  // Basic set; returns success boolean
 2  set<K extends keyof Reg & string>(key: K, value: Reg[K]): boolean {
 3    const fullKey = this.k(key);
 4    const payload = JSON.stringify(value);
 5    try {
 6      if (this.storage) this.storage.setItem(fullKey, payload);
 7      else this.fallback?.set(fullKey, payload);
 8      if (this.sameTabEvent) window.dispatchEvent(new CustomEvent(this.sameTabEvent, { detail: { key: fullKey } }));
 9      return true;
10    } catch (err) {
11      console.warn("TypedStorage.set primary failed, trying fallback", err);
12      try {
13        if (this.fallback) {
14          this.fallback.set(fullKey, payload);
15          return true;
16        }
17        return false;
18      } catch (e) {
19        console.error("TypedStorage.set fallback failed", e);
20        return false;
21      }
22    }
23  }
  • Метод set сохраняет значение по указанному ключу и возвращает логическое значение, указывающее, была ли операция успешной.
1  // Set with TTL convenience
2  setWithTTL<K extends keyof Reg & string>(key: K, value: Reg[K], ttlMs?: number): boolean {
3    const payload = { value, expiresAt: ttlMs ? Date.now() + ttlMs : null };
4    return this.set(key, payload as unknown as Reg[K]);
5  }
  • Метод setWithTTL сохраняет значение с TTL (сроком действия).
1  remove<K extends keyof Reg & string>(key: K) {
2    const fullKey = this.k(key);
3    try {
4      if (this.storage) this.storage.removeItem(fullKey);
5      this.fallback?.delete(fullKey);
6    } catch (err) { console.warn("TypedStorage.remove error", err); }
7  }
  • Метод remove удаляет значение по указанному ключу как из хранилища, так и из резервного хранилища.
1  clear() {
2    try {
3      if (this.storage) this.storage.clear();
4      this.fallback?.clear();
5    } catch (err) { console.warn("TypedStorage.clear error", err); }
6  }
7}
  • Метод clear удаляет все данные как из хранилища, так и из резервного хранилища.
 1// Usage example
 2type MyReg = {
 3  theme: "light" | "dark";
 4  user: { id: number; name: string };
 5  draft: string;
 6};
 7
 8const memFallback = new Map<string, string>();
 9const store = new TypedStorage<MyReg>({} as MyReg, {
10  prefix: "myapp:v1",
11  sameTabEvent: "storage:changed",
12  fallback: memFallback
13});
14store.set("theme", "dark");
15console.log(store.get("theme")); // "dark"
16store.setWithTTL("draft", "in-progress...", 1000 * 60 * 60); // keep 1 hour

  • Этот код является примером использования TypedStorage, который сохраняет и извлекает значения, такие как "theme" и "draft", в типобезопасном хранилище ключ-значение, а также поддерживает TTL и резервный механизм (fallback). Он настраивает уведомления в той же вкладке и резерв в памяти, чтобы безопасно выполнять операции с хранилищем.

  • Класс TypedStorage служит практической отправной точкой. По мере необходимости реализуйте стратегии LRU, шифрование, сжатие и резервные варианты с переходом на IndexedDB.

Резюме

При использовании Web Storage с TypeScript всегда учитывайте четыре аспекта — типобезопасность, устойчивость к исключениям, безопасность и синхронизацию (несколько вкладок) — для надёжного дизайна. Обёртки и утилиты, которые мы рассмотрели, являются примерами этого. При необходимости можно перейти на другие браузерные хранилища, такие как IndexedDB.

Вы можете следовать этой статье, используя Visual Studio Code на нашем YouTube-канале. Пожалуйста, также посмотрите наш YouTube-канал.

YouTube Video

`Cookie` в TypeScript