TypeScript e StorageManager

Este artigo explica TypeScript e StorageManager.

Fornecemos exemplos práticos para explicar TypeScript e StorageManager.

YouTube Video

TypeScript e StorageManager

O que é StorageManager?

StorageManager é uma API que permite às aplicações web estimar quanto armazenamento estão utilizando e qual a capacidade disponível. Ela também fornece uma solicitação de persistência (persist()) para evitar a remoção automática de dados pelo usuário ou pelo navegador. Isso permite controlar se há espaço livre suficiente ou se os dados serão excluídos automaticamente, como ao armazenar grandes quantidades de dados no IndexedDB para aplicações offline.

Detecção de Recursos

Primeiro, verifique se o navegador suporta navigator.storage.

 1// TypeScript: feature detection for StorageManager
 2function supportsStorageManager(): boolean {
 3  return typeof navigator !== "undefined" &&
 4         typeof navigator.storage !== "undefined" &&
 5         typeof navigator.storage.estimate === "function";
 6}
 7
 8// Example usage
 9if (supportsStorageManager()) {
10  console.log("StorageManager is supported.");
11} else {
12  console.warn("StorageManager not supported. Falling back to localStorage or IndexedDB.");
13}

• Esta função verifica a disponibilidade da API StorageManager em etapas.
• Como navigator.storage não existe em alguns navegadores como o Safari, é importante verificar sua existência de forma segura usando typeof.

Estimativa do Uso de Armazenamento (estimate())

Após verificar a funcionalidade com supportsStorageManager(), obtenha o uso (usage) e a cota (quota) a partir de navigator.storage.estimate().

 1// TypeScript: safely get storage estimate
 2async function getStorageEstimate(): Promise<{ usage: number; quota: number } | null> {
 3  if (!supportsStorageManager()) {
 4    console.warn("StorageManager not supported.");
 5    return null;
 6  }
 7
 8  const estimate = await navigator.storage.estimate();
 9  return { usage: estimate.usage ?? 0, quota: estimate.quota ?? 0 };
10}
11
12// Example usage
13getStorageEstimate().then(result => {
14  if (result) {
15    console.log(`Usage: ${result.usage} bytes / Quota: ${result.quota} bytes`);
16  }
17});

• Esta função sempre opera de forma segura e retorna null se o navegador não a suportar.
• usage e quota são estimativas e podem variar entre navegadores.

Solicitar Persistência de Dados (persist())

Use persist() para solicitar persistência de modo que dados importantes (por exemplo, cache offline) não sejam excluídos automaticamente pelo navegador. No entanto, ela não é bem-sucedida em todos os ambientes.

 1// TypeScript: safely request persistent storage
 2async function requestPersistence(): Promise<boolean> {
 3  if (!supportsStorageManager()) {
 4    console.warn("StorageManager not supported.");
 5    return false;
 6  }
 7
 8  if (typeof navigator.storage.persist !== "function") {
 9    console.warn("persist() not available in this browser.");
10    return false;
11  }
12
13  try {
14    const granted = await navigator.storage.persist();
15    return Boolean(granted);
16  } catch (err) {
17    console.error("persist() error:", err);
18    return false;
19  }
20}
21
22// Example usage
23requestPersistence().then(granted => {
24  console.log("Persistence granted?", granted);
25});

• Se persist() for bem-sucedido, os dados não serão excluídos automaticamente pelo navegador, exceto por intervenção manual do usuário. No entanto, as solicitações podem ser rejeitadas dependendo das ações do usuário ou das configurações do navegador.

Verifique o Armazenamento Disponível Antes de Salvar Dados

Verifique o espaço disponível antes de salvar grandes quantidades de dados para evitar falhas de gravação (QuotaExceededError).

 1// TypeScript: ensure enough space before writing
 2async function ensureSpaceAndWrite(neededBytes: number, writeFn: () => Promise<void>): Promise<boolean> {
 3  const estimate = await getStorageEstimate();
 4  if (!estimate) {
 5    console.warn("Cannot check storage space. Proceeding without validation.");
 6    await writeFn();
 7    return true;
 8  }
 9
10  const free = estimate.quota - estimate.usage;
11  if (free < neededBytes) {
12    console.warn(`Not enough space. Free: ${free} bytes, needed: ${neededBytes} bytes.`);
13    return false;
14  }
15
16  await writeFn();
17  return true;
18}
19
20// Example usage
21ensureSpaceAndWrite(10 * 1024 * 1024, async () => {
22  console.log("Saving large data...");
23});

• Verificando o armazenamento disponível antes de salvar, você pode reduzir o risco de interrupções de gravação devido à capacidade insuficiente.

Lidando com localStorage de forma Tipada em TypeScript

localStorage é conveniente para armazenar dados de configuração leves e informações similares.

A classe a seguir usa generics para criar um wrapper tipado.

 1// TypeScript: typed localStorage wrapper
 2type Serializer<T> = {
 3  serialize: (v: T) => string;
 4  deserialize: (s: string) => T;
 5};
 6
 7class TypedLocalStorage<K extends string, V> {
 8  constructor(private storage: Storage, private serializer: Serializer<V>) {}
 9
10  set(key: K, value: V): void {
11    this.storage.setItem(key, this.serializer.serialize(value));
12  }
13
14  get(key: K): V | null {
15    const raw = this.storage.getItem(key);
16    if (raw === null) return null;
17    try {
18      return this.serializer.deserialize(raw);
19    } catch {
20      return null;
21    }
22  }
23
24  remove(key: K): void {
25    this.storage.removeItem(key);
26  }
27
28  clear(): void {
29    this.storage.clear();
30  }
31}
32
33// Example usage
34const jsonSerializer: Serializer<any> = {
35  serialize: v => JSON.stringify(v),
36  deserialize: s => JSON.parse(s),
37};
38
39const appStorage = new TypedLocalStorage<'theme' | 'token', any>(localStorage, jsonSerializer);
40appStorage.set('theme', { dark: true });
41console.log(appStorage.get('theme'));

• Esta classe ajuda a reduzir o risco de armazenar ou recuperar dados com o tipo incorreto.

Considerações Práticas e Melhores Práticas

• Sempre verifique se o navegador suporta StorageManager Como o StorageManager é uma API relativamente nova, sempre confirme sua existência antes de utilizar.

• Fique atento aos limites de armazenamento e compatibilidade O valor retornado por estimate() varia conforme o navegador e é apenas uma estimativa.

• Projete levando em conta APIs assíncronas estimate() e persist() são APIs assíncronas baseadas em promise. Projete seu código para não bloquear a interface do usuário.

• Considerações de Segurança Não armazene informações sensíveis, como tokens de acesso, em localStorage. Considere usar cookies HttpOnly ou criptografia, se possível.

• Projeto de Alternativa (Fallback) Se supportsStorageManager() retornar falso, forneça uma lógica para alternar o uso apenas para localStorage ou IndexedDB.

Resumo

Com a detecção de recursos usando supportsStorageManager(), você pode suportar todos os ambientes de forma segura, verificar o uso e a cota com navigator.storage.estimate(), e solicitar persistência com persist(). Em TypeScript, use funções wrapper e definições de tipo para escrever um código legível e seguro. O fluxo básico é: verificar existência, estimar, solicitar persistência e checar a capacidade antes de gravar no armazenamento.

Você pode acompanhar o artigo acima usando o Visual Studio Code em nosso canal do YouTube. Por favor, confira também o canal do YouTube.

YouTube Video