TypeScript e IndexedDB

Articles

Este artículo explica sobre TypeScript e IndexedDB.

Explicaremos TypeScript e IndexedDB con ejemplos prácticos.

YouTube Video

TypeScript e IndexedDB

IndexedDB es un almacenamiento NoSQL de bajo nivel que te permite persistir datos estructurados en el navegador. Con TypeScript, puedes representar esquemas de forma segura en cuanto a tipos, reduciendo errores y mejorando la mantenibilidad.

Terminología básica y flujo de trabajo

IndexedDB es una pequeña base de datos dentro del navegador. Administra los datos mediante mecanismos como bases de datos con nombres y versiones, almacenes de objetos, transacciones, índices y cursores. Las bases de datos tienen versiones y, cuando la versión se actualiza, se llama a onupgradeneeded para actualizar el esquema, como crear o modificar tablas.

Abriendo IndexedDB (patrón básico)

Primero, mostramos un ejemplo de cómo abrir una base de datos con IndexedDB y crear un object store en onupgradeneeded si es necesario.

 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 la base de datos e informa si tuvo éxito o falló.
Si es necesario, la tienda todos se crea en onupgradeneeded.

Definiendo tipos en TypeScript (Modelos)

A continuación, definimos tipos de datos usando TypeScript. Esto garantiza la seguridad de tipos en las operaciones CRUD posteriores.

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}

Aquí, definimos el tipo Todo.

Ejemplos de implementación de funciones CRUD simples

A continuación, mostramos operaciones CRUD básicas como agregar, obtener, actualizar y eliminar del object store. Cada función recibe un IDBDatabase y devuelve una 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 función añade un nuevo Todo a la tienda todos en IndexedDB. Devuelve una Promise para el manejo asíncrono, que se resuelve cuando el proceso está completo.

 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 función recupera el Todo con el ID especificado y devuelve el objeto si se encuentra. Si no se encuentra el dato correspondiente, devuelve 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 función actualiza los datos de un Todo existente. En caso de éxito, se registra el ID del Todo actualizado.

 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 función elimina el Todo con el ID especificado. Cuando el procesamiento tiene éxito, se muestra el ID eliminado.
Estas funciones resuelven o rechazan una Promesa dependiendo de la finalización de la transacción o de los errores. Incluir la salida con console.log facilita el seguimiento de lo que sucede durante la ejecución.

Índices y consultas compuestas

Usando índices en IndexedDB, puedes buscar eficientemente en campos específicos. Aquí, creamos un índice para createdAt y damos un ejemplo de una consulta por rango.

 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 función abre la base de datos y crea o verifica el índice by-createdAt en el campo createdAt. Esto permite buscar y ordenar eficientemente por fecha de creación.

 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 función recupera solo los Todos creados después de la marca de tiempo especificada. Usar el índice permite escanear datos eficientemente en orden de fecha de creación.
En este ejemplo, se crea un índice by-createdAt durante la actualización de la base de datos, y los elementos Todo creados después del tiempo especificado se enumeran con un cursor.

Wrapper ligero basado en Promises

La API de bajo nivel de IndexedDB es compleja de escribir, y la repetición de operaciones similares puede generar redundancia y errores. Por lo tanto, al preparar una clase envoltorio genérica en TypeScript que abstraiga las operaciones, mejoramos la simplicidad y el mantenimiento del código. A continuación, mostramos una implementación centrada en la funcionalidad básica.

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 clase envuelve las operaciones de IndexedDB y proporciona métodos CRUD seguros en cuanto a tipos. Supone un object store donde la clave es 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  }

Abre la base de datos y crea un nuevo object store si es necesario. La inicialización de la tienda se realiza usando el evento de actualización.

 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  }

Agrega datos a la tienda de IndexedDB. Después de agregar, el ID se muestra en la consola.

 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 datos correspondientes al ID especificado. Se devuelve undefined si los datos no existen.

 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  }

Actualiza datos existentes o agrega nuevos datos. Después del procesamiento, el ID actualizado se muestra.

 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  }

Elimina los datos con el ID especificado. Al tener éxito, se muestra el ID eliminado.

 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 los datos en la tienda. El valor de retorno es un arreglo de 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 es un ejemplo real de uso de la clase IDBWrapper. Esto muestra el flujo para añadir, recuperar, actualizar, listar y eliminar datos de Todo.
Este wrapper permite un manejo sencillo de las operaciones CRUD básicas. En un entorno real, también necesitas gestionar el manejo de errores y la gestión del esquema (índices).

Migración de esquema (actualización de versión)

Para cambiar el esquema de la base de datos, aumenta el segundo argumento (versión) de indexedDB.open y actualízalo en onupgradeneeded. Debes diseñarlo de modo que las transacciones existentes hayan finalizado y se eviten cambios destructivos.

 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}

El procesamiento pesado dentro de onupgradeneeded puede bloquear la interfaz, así que mantenlo al mínimo y considera la migración diferida (procesamiento fuera del arranque de la aplicación) si es posible.

Precauciones sobre transacciones (ciclo de vida y errores)

Las transacciones se confirman automáticamente antes de que termine la ejecución del script que las creó. Al usar await dentro de una transacción, puede confirmarse inesperadamente; se debe tener precaución al realizar múltiples operaciones asíncronas dentro de la misma transacción.

 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}

Ten en cuenta la duración de las transacciones; usa transacciones separadas si es necesario, o programa las operaciones de forma sincrónica dentro de una sola transacción.

Aplicaciones de cursor y paginación

Mediante el uso de un cursor, puedes procesar datos a gran escala de forma secuencial o implementar paginación simple sin utilizar desplazamientos (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}

Al recuperar elementos uno a uno con cursores, se puede reducir el uso de memoria. Al implementar la paginación, es común recordar la última clave leída.

Manejo de errores y solución alternativa

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

Es posible que IndexedDB no esté disponible debido a diferencias de implementación entre navegadores o a la configuración de privacidad de los usuarios, como la navegación privada. Por lo tanto, verifica si indexedDB existe y, si no es así, proporciona una alternativa como localStorage.

Rendimiento y mejores prácticas

IndexedDB es rápido y potente, pero el rendimiento puede variar mucho según su diseño y cómo se manejen los datos. Dependiendo del caso de uso, la optimización puede hacerse de las siguientes maneras:.

Diseña el almacén de objetos de acuerdo al uso real. Por ejemplo, si hay muchas lecturas, proporciona índices; si hay muchas escrituras, mantén el diseño de claves simple.
Los datos binarios grandes, como imágenes y audio, deben almacenarse como Blobs o gestionarse usando la API de archivos o service workers si es necesario. También se puede considerar la compresión si es necesario.
Mantén las transacciones lo más cortas posible y realiza los procesos pesados fuera de la transacción para minimizar el tiempo de bloqueo.
Los índices pueden acelerar las búsquedas, pero ralentizan las inserciones y actualizaciones, así que crea solo los que sean realmente necesarios.
Al manejar muchos fragmentos pequeños de datos, recuperarlos todos de una vez con getAll() puede agotar la memoria. Puedes reducir el uso de memoria dividiendo el procesamiento con cursores.

Seguridad y privacidad

Los datos de IndexedDB están aislados por dominio y protocolo de acuerdo con la política del mismo origen. Diseña bajo la suposición de que los datos pueden perderse si los usuarios eliminan los datos del navegador o usan el modo privado.

Resumen y patrones de diseño recomendados

Para usar IndexedDB de manera efectiva con TypeScript, es importante preparar los tipos y procesos asíncronos, tener en cuenta la gestión de versiones y el diseño de transacciones, y envolver los procesos comunes para mejorar la mantenibilidad.

Definir tipos en TypeScript y envolver las operaciones de IndexedDB con Promise/async/await mejora la seguridad y la legibilidad del código.
Los cambios de esquema deben utilizar la gestión de versiones con onupgradeneeded y el procesamiento pesado debe retrasarse cuando sea posible.
Diseña las transacciones para que sean cortas y evita el procesamiento asíncrono pesado dentro de la misma transacción.
Al crear clases envoltorio, puedes reducir procesos comunes redundantes como la gestión de errores, el registro y las definiciones de tipos.

Puedes seguir el artículo anterior utilizando Visual Studio Code en nuestro canal de YouTube. Por favor, también revisa nuestro canal de YouTube.

YouTube Video

TypeScript y el almacenamiento web