TypeScript e IndexedDB

Articles

Este artigo explica sobre TypeScript e IndexedDB.

Vamos explicar TypeScript e IndexedDB com exemplos práticos.

YouTube Video

TypeScript e IndexedDB

IndexedDB é um armazenamento NoSQL de baixo nível que permite persistir dados estruturados no navegador. Com TypeScript, você pode representar esquemas de maneira segura em relação aos tipos, reduzindo erros e melhorando a manutenção.

Terminologia Básica e Fluxo de Trabalho

IndexedDB é um pequeno banco de dados dentro do navegador. Ele gerencia os dados utilizando mecanismos como bancos de dados com nomes e versões, repositórios de objetos, transações, índices e cursores. Os bancos de dados possuem versões, e quando a versão é atualizada, onupgradeneeded é chamado para atualizar o esquema, como criar ou modificar tabelas.

Abrindo IndexedDB (padrão básico)

Primeiro, mostramos um exemplo de abertura de um banco de dados com IndexedDB e criação de um object store em onupgradeneeded se necessário.

 1// Open an IndexedDB database and create an object store if needed.
 2// This code shows the classic callback-based IndexedDB API wrapped into a Promise.
 3function openDatabase(dbName: string, version: number): Promise<IDBDatabase> {
 4  return new Promise((resolve, reject) => {
 5    const request = indexedDB.open(dbName, version);
 6
 7    request.onerror = () => {
 8      reject(request.error);
 9    };
10
11    request.onupgradeneeded = (event) => {
12      const db = request.result;
13      if (!db.objectStoreNames.contains('todos')) {
14        // Create object store with keyPath 'id'
15        db.createObjectStore('todos', { keyPath: 'id' });
16      }
17    };
18
19    request.onsuccess = () => {
20      resolve(request.result);
21    };
22  });
23}
24
25// Usage example:
26openDatabase('my-db', 1)
27  .then(db => {
28    console.log('DB opened', db.name, db.version);
29    db.close();
30  })
31  .catch(err => console.error('Failed to open DB', err));

Este código abre o banco de dados e registra se a operação foi bem-sucedida ou falhou.
Se necessário, o store todos é criado em onupgradeneeded.

Definição de tipos no TypeScript (Modelos)

Em seguida, definimos os tipos de dados usando TypeScript. Isso garante a segurança dos tipos nas operações CRUD subsequentes.

1// Define the TypeScript interface for a Todo item.
2// This helps with type safety in the database operations.
3interface Todo {
4  id: string;          // primary key
5  title: string;
6  completed: boolean;
7  createdAt: number;
8}

Aqui, definimos o tipo Todo.

Exemplos de implementação de funções CRUD simples

Em seguida, mostramos operações CRUD básicas como adicionar, recuperar, atualizar e excluir do object store. Cada função recebe um IDBDatabase e retorna uma Promise.

 1// CRUD utilities for the 'todos' object store.
 2// Each operation uses a transaction and returns a Promise for easier async/await usage.
 3
 4function addTodo(db: IDBDatabase, todo: Todo): Promise<void> {
 5  return new Promise((resolve, reject) => {
 6    const tx = db.transaction('todos', 'readwrite');
 7    const store = tx.objectStore('todos');
 8    const req = store.add(todo);
 9
10    req.onsuccess = () => {
11      console.log('Todo added', todo.id);
12    };
13    req.onerror = () => reject(req.error);
14
15    tx.oncomplete = () => resolve();
16    tx.onerror = () => reject(tx.error);
17  });
18}

Esta função adiciona um novo Todo ao repositório todos no IndexedDB. Ela retorna uma Promise para o tratamento assíncrono, que é resolvida quando o processamento é concluído.

 1function getTodo(db: IDBDatabase, id: string): Promise<Todo | undefined> {
 2  return new Promise((resolve, reject) => {
 3    const tx = db.transaction('todos', 'readonly');
 4    const store = tx.objectStore('todos');
 5    const req = store.get(id);
 6
 7    req.onsuccess = () => resolve(req.result as Todo | undefined);
 8    req.onerror = () => reject(req.error);
 9  });
10}

Esta função recupera o Todo com o ID especificado e retorna o objeto se encontrado. Se nenhum dado correspondente for encontrado, retorna undefined.

 1function updateTodo(db: IDBDatabase, todo: Todo): Promise<void> {
 2  return new Promise((resolve, reject) => {
 3    const tx = db.transaction('todos', 'readwrite');
 4    const store = tx.objectStore('todos');
 5    const req = store.put(todo);
 6
 7    req.onsuccess = () => {
 8      console.log('Todo updated', todo.id);
 9    };
10    req.onerror = () => reject(req.error);
11
12    tx.oncomplete = () => resolve();
13    tx.onerror = () => reject(tx.error);
14  });
15}

Esta função atualiza os dados existentes do Todo. Em caso de sucesso, o ID do Todo atualizado é registrado.

 1function deleteTodo(db: IDBDatabase, id: string): Promise<void> {
 2  return new Promise((resolve, reject) => {
 3    const tx = db.transaction('todos', 'readwrite');
 4    const store = tx.objectStore('todos');
 5    const req = store.delete(id);
 6
 7    req.onsuccess = () => {
 8      console.log('Todo deleted', id);
 9    };
10    req.onerror = () => reject(req.error);
11
12    tx.oncomplete = () => resolve();
13    tx.onerror = () => reject(tx.error);
14  });
15}

Esta função exclui o Todo com o ID especificado. Quando o processamento é bem sucedido, o ID excluído é registrado.
Essas funções resolvem ou rejeitam uma Promise dependendo da conclusão ou erros da transação. Incluir saídas via console.log facilita acompanhar o que está acontecendo durante a execução.

Índices e consultas compostas

Ao usar índices no IndexedDB, é possível buscar eficientemente em campos específicos. Aqui, criamos um índice para createdAt e apresentamos um exemplo de consulta por intervalo.

 1// When opening DB, create an index for createdAt.
 2// Then demonstrate a range query using the index.
 3
 4function openDatabaseWithIndex(dbName: string, version: number): Promise<IDBDatabase> {
 5  return new Promise((resolve, reject) => {
 6    const request = indexedDB.open(dbName, version);
 7
 8    request.onupgradeneeded = () => {
 9      const db = request.result;
10      if (!db.objectStoreNames.contains('todos')) {
11        const store = db.createObjectStore('todos', { keyPath: 'id' });
12        // Create an index on createdAt for sorting/filtering
13        store.createIndex('by-createdAt', 'createdAt', { unique: false });
14      } else {
15        const store = request.transaction!.objectStore('todos');
16        if (!store.indexNames.contains('by-createdAt')) {
17          store.createIndex('by-createdAt', 'createdAt', { unique: false });
18        }
19      }
20    };
21
22    request.onerror = () => reject(request.error);
23    request.onsuccess = () => resolve(request.result);
24  });
25}

Esta função abre o banco de dados e cria ou verifica o índice by-createdAt no campo createdAt. Isso permite buscas e ordenações eficientes pela data de criação.

 1async function getTodosCreatedAfter(db: IDBDatabase, timestamp: number): Promise<Todo[]> {
 2  return new Promise((resolve, reject) => {
 3    const tx = db.transaction('todos', 'readonly');
 4    const store = tx.objectStore('todos');
 5    const index = store.index('by-createdAt');
 6    const range = IDBKeyRange.lowerBound(timestamp, true); // exclusive
 7    const req = index.openCursor(range);
 8
 9    const results: Todo[] = [];
10    req.onsuccess = (event) => {
11      const cursor = (event.target as IDBRequest).result as IDBCursorWithValue | null;
12      if (cursor) {
13        results.push(cursor.value as Todo);
14        cursor.continue();
15      } else {
16        resolve(results);
17      }
18    };
19    req.onerror = () => reject(req.error);
20  });
21}

Esta função recupera apenas os Todos criados após o carimbo de data/hora especificado. Usar o índice permite a varredura eficiente dos dados na ordem da data de criação.
Neste exemplo, um índice by-createdAt é criado durante a atualização do banco de dados, e os itens Todo criados após o tempo especificado são enumerados com um cursor.

Wrapper leve baseado em Promise

A API de baixo nível do IndexedDB é complexa de escrever, e operações semelhantes repetidas podem levar à redundância e a bugs. Portanto, ao preparar uma classe wrapper genérica em TypeScript que abstrai as operações, melhoramos a simplicidade e a manutenibilidade do código. Abaixo está uma implementação focada em funcionalidades básicas.

1// A minimal TypeScript wrapper around IndexedDB to simplify common operations.
2// This class is generic over the store's value type and assumes 'keyPath' is 'id'.
3
4class IDBWrapper<T extends { id: string }> {
5  private dbPromise: Promise<IDBDatabase>;
6
7  constructor(private dbName: string, private version: number, private storeName: string) {
8    this.dbPromise = this.open();
9  }

Esta classe encapsula operações do IndexedDB e fornece métodos CRUD seguros quanto aos tipos. Ela pressupõe um object store onde a chave é id.

 1  private open(): Promise<IDBDatabase> {
 2    return new Promise((resolve, reject) => {
 3      const req = indexedDB.open(this.dbName, this.version);
 4      req.onerror = () => reject(req.error);
 5      req.onupgradeneeded = () => {
 6        const db = req.result;
 7        if (!db.objectStoreNames.contains(this.storeName)) {
 8          db.createObjectStore(this.storeName, { keyPath: 'id' });
 9        }
10      };
11      req.onsuccess = () => resolve(req.result);
12    });
13  }

Ela abre o banco de dados e cria um novo object store se necessário. A inicialização do store é feita usando o evento de upgrade.

 1  async add(item: T): Promise<void> {
 2    const db = await this.dbPromise;
 3    await new Promise<void>((resolve, reject) => {
 4      const tx = db.transaction(this.storeName, 'readwrite');
 5      const store = tx.objectStore(this.storeName);
 6      const req = store.add(item);
 7      req.onsuccess = () => {
 8        console.log('added', item.id);
 9      };
10      req.onerror = () => reject(req.error);
11      tx.oncomplete = () => resolve();
12      tx.onerror = () => reject(tx.error);
13    });
14  }

Adiciona dados ao store no IndexedDB. Após adicionar, o ID é registrado no console.

 1  async get(id: string): Promise<T | undefined> {
 2    const db = await this.dbPromise;
 3    return new Promise((resolve, reject) => {
 4      const tx = db.transaction(this.storeName, 'readonly');
 5      const store = tx.objectStore(this.storeName);
 6      const req = store.get(id);
 7      req.onsuccess = () => resolve(req.result as T | undefined);
 8      req.onerror = () => reject(req.error);
 9    });
10  }

Recupera dados correspondentes ao ID especificado. undefined é retornado se o dado não existir.

 1  async put(item: T): Promise<void> {
 2    const db = await this.dbPromise;
 3    return new Promise((resolve, reject) => {
 4      const tx = db.transaction(this.storeName, 'readwrite');
 5      const store = tx.objectStore(this.storeName);
 6      const req = store.put(item);
 7      req.onsuccess = () => {
 8        console.log('put', item.id);
 9      };
10      req.onerror = () => reject(req.error);
11      tx.oncomplete = () => resolve();
12      tx.onerror = () => reject(tx.error);
13    });
14  }

Atualiza dados existentes ou adiciona novos dados. Após o processamento, o ID atualizado é registrado.

 1  async delete(id: string): Promise<void> {
 2    const db = await this.dbPromise;
 3    return new Promise((resolve, reject) => {
 4      const tx = db.transaction(this.storeName, 'readwrite');
 5      const store = tx.objectStore(this.storeName);
 6      const req = store.delete(id);
 7      req.onsuccess = () => {
 8        console.log('deleted', id);
 9      };
10      req.onerror = () => reject(req.error);
11      tx.oncomplete = () => resolve();
12      tx.onerror = () => reject(tx.error);
13    });
14  }

Exclui o dado com o ID especificado. Em caso de sucesso, o ID excluído é registrado.

 1  async getAll(): Promise<T[]> {
 2    const db = await this.dbPromise;
 3    return new Promise((resolve, reject) => {
 4      const tx = db.transaction(this.storeName, 'readonly');
 5      const store = tx.objectStore(this.storeName);
 6      const req = store.getAll();
 7      req.onsuccess = () => resolve(req.result as T[]);
 8      req.onerror = () => reject(req.error);
 9    });
10  }
11}

Recupera todos os dados do store. O valor de retorno é um array do tipo T.

 1// Example usage with Todo type:
 2interface Todo {
 3  id: string;
 4  title: string;
 5  completed: boolean;
 6  createdAt: number;
 7}
 8
 9const todoStore = new IDBWrapper<Todo>('my-db', 1, 'todos');
10
11(async () => {
12  const newTodo: Todo = { id: '1', title: 'Learn IndexedDB', completed: false, createdAt: Date.now() };
13  await todoStore.add(newTodo);
14  const fetched = await todoStore.get('1');
15  console.log('fetched', fetched);
16  newTodo.completed = true;
17  await todoStore.put(newTodo);
18  const all = await todoStore.getAll();
19  console.log('all todos', all);
20  await todoStore.delete('1');
21})();

Este código é um exemplo real de uso da classe IDBWrapper. Isto mostra o fluxo para adicionar, recuperar, atualizar, listar e excluir dados de Todo.
Este wrapper permite o manejo simples das operações CRUD básicas. Em um ambiente real, também é necessário lidar com tratamento de erros e gerenciamento de esquemas (índices).

Migração de esquema (atualização de versão)

Para alterar o esquema do banco de dados, aumente o segundo argumento (versão) de indexedDB.open e atualize-o em onupgradeneeded. É necessário projetar de forma que as transações existentes tenham sido concluídas e alterações destrutivas sejam evitadas.

 1// Example of handling upgrade to version 2: add an index and perhaps migrate data.
 2// onupgradeneeded receives an event where oldVersion and newVersion are accessible.
 3
 4function upgradeToV2(dbName: string): Promise<IDBDatabase> {
 5  return new Promise((resolve, reject) => {
 6    const req = indexedDB.open(dbName, 2);
 7    req.onupgradeneeded = (ev) => {
 8      const db = req.result;
 9      const oldVersion = (ev as IDBVersionChangeEvent).oldVersion;
10      console.log('Upgrading DB from', oldVersion, 'to', db.version);
11      let store: IDBObjectStore;
12      if (!db.objectStoreNames.contains('todos')) {
13        store = db.createObjectStore('todos', { keyPath: 'id' });
14      } else {
15        store = req.transaction!.objectStore('todos');
16      }
17      // Add index if not present
18      if (!store.indexNames.contains('by-completed')) {
19        store.createIndex('by-completed', 'completed', { unique: false });
20      }
21
22      // Optional: data migration logic if necessary can go here,
23      // but heavy migrations often should be done lazily on read.
24    };
25    req.onsuccess = () => resolve(req.result);
26    req.onerror = () => reject(req.error);
27  });
28}

Processamentos pesados dentro de onupgradeneeded podem travar a interface do usuário, então mantenha-os no mínimo e considere migrações adiadas (processamento em etapas no início do app) se possível.

Cuidados com transações (ciclo de vida e erros)

Transações são automaticamente confirmadas antes do término da execução do script que as criou. Ao usar await dentro de uma transação, ela pode ser confirmada inesperadamente; cuidado ao realizar múltiplas operações assíncronas na mesma transação.

 1// Bad pattern: awaiting outside transaction callbacks can cause tx to auto-commit.
 2// Good pattern is to chain requests and resolve on tx.oncomplete as shown earlier.
 3
 4// Example: Do multiple operations inside single tx, avoid awaiting inside.
 5function multiOperation(db: IDBDatabase, items: Todo[]): Promise<void> {
 6  return new Promise((resolve, reject) => {
 7    const tx = db.transaction('todos', 'readwrite');
 8    const store = tx.objectStore('todos');
 9
10    for (const item of items) {
11      const req = store.put(item);
12      req.onerror = () => console.error('put error', req.error);
13      // Do NOT await here; just schedule requests synchronously.
14    }
15
16    tx.oncomplete = () => {
17      console.log('All operations in transaction completed');
18      resolve();
19    };
20    tx.onerror = () => reject(tx.error);
21  });
22}

Atente ao tempo de vida da transação; use transações separadas se necessário ou agende operações de forma síncrona dentro de uma transação.

Aplicações de cursor e paginação

Ao usar um cursor, você pode processar grandes volumes de dados sequencialmente ou implementar paginação simples sem usar offsets.

 1// Example: fetch first N items using a cursor (ascending by key).
 2function fetchFirstN(db: IDBDatabase, n: number): Promise<Todo[]> {
 3  return new Promise((resolve, reject) => {
 4    const tx = db.transaction('todos', 'readonly');
 5    const store = tx.objectStore('todos');
 6    const req = store.openCursor();
 7    const out: Todo[] = [];
 8    req.onsuccess = (ev) => {
 9      const cursor = (ev.target as IDBRequest).result as IDBCursorWithValue | null;
10      if (cursor && out.length < n) {
11        out.push(cursor.value as Todo);
12        cursor.continue();
13      } else {
14        resolve(out);
15      }
16    };
17    req.onerror = () => reject(req.error);
18  });
19}

Ao buscar itens um a um com cursores, o uso de memória pode ser reduzido. Ao implementar paginação, é comum lembrar da última chave lida.

Tratamento de erros e fallback

1// Feature detection
2if (!('indexedDB' in window)) {
3  console.warn('IndexedDB is not supported. Falling back to localStorage.');
4  // implement fallback logic...
5}

O IndexedDB pode não estar disponível devido a diferenças de implementação entre navegadores ou às configurações de privacidade dos usuários, como navegação privada. Portanto, verifique se o indexedDB existe e, caso não exista, forneça uma alternativa como o localStorage.

Performance e melhores práticas

IndexedDB é rápido e poderoso, mas o desempenho pode variar muito dependendo de seu design e de como os dados são manipulados. Dependendo do caso de uso, a otimização pode ser feita das seguintes maneiras:.

Projete o repositório de objetos de acordo com o uso real. Por exemplo, se houver muitas leituras, forneça índices; se houver muitas gravações, mantenha o design das chaves simples.
Grandes dados binários, como imagens e áudio, devem ser armazenados como Blobs, ou gerenciados usando a API de Arquivos ou service workers, se necessário. A compactação também pode ser considerada, se necessário.
Mantenha as transações o mais curtas possível e execute processamentos pesados fora da transação para minimizar o tempo de bloqueio.
Os índices podem acelerar as buscas, mas diminuir a velocidade de inserções e atualizações, portanto, crie apenas os que forem realmente necessários.
Ao lidar com muitos pequenos pedaços de dados, recuperá-los todos de uma vez usando getAll() pode esgotar a memória. Você pode reduzir o uso de memória dividindo o processamento com cursores.

Segurança e privacidade

Os dados do IndexedDB são isolados por domínio e protocolo conforme a política de mesma origem. Projete considerando a possibilidade de perda de dados se os usuários excluírem os dados do navegador ou utilizarem o modo privado.

Resumo e padrões de design recomendados

Para usar IndexedDB de forma eficaz com TypeScript, é importante preparar os tipos e processos assíncronos, estar atento ao gerenciamento de versões e ao design das transações, e envolver os processamentos comuns para melhorar a manutenibilidade.

Definir tipos em TypeScript e encapsular operações do IndexedDB com Promise/async/await melhora a segurança e a legibilidade do código.
Mudanças de esquema devem usar gerenciamento de versão com onupgradeneeded e processamentos pesados devem ser adiados quando possível.
Projete as transações para serem curtas e evite processamentos assíncronos pesados na mesma transação.
Ao criar classes wrapper, você pode reduzir processos comuns redundantes, como tratamento de erros, logging e definições de tipos.

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

TypeScript e Web Storage