Mastering IndexedDB with TypeScript

In modern web development, handling data storage on the client - side is crucial. IndexedDB is a powerful browser - based database that allows web applications to store large amounts of structured data. When combined with TypeScript, which adds static typing to JavaScript, it becomes even more robust and maintainable. This blog post will guide you through the fundamental concepts, usage methods, common practices, and best practices of using IndexedDB with TypeScript.

Table of Contents#

  1. Fundamental Concepts
  2. Usage Methods
  3. Common Practices
  4. Best Practices
  5. Conclusion
  6. References

Fundamental Concepts#

IndexedDB Basics#

IndexedDB is a transactional database system in the browser. It stores data in key - value pairs and supports multiple data types. The main components of IndexedDB are:

  • Database: A container for object stores. You can have multiple databases in a single web application.
  • Object Store: Similar to a table in a relational database. It stores data records.
  • Transaction: All database operations must be performed within a transaction. Transactions ensure data consistency.
  • Index: An index allows you to query data based on a specific property of the stored objects.

TypeScript and IndexedDB#

TypeScript provides static typing, which means you can define the structure of your data in advance. This helps catch type - related errors at compile - time rather than runtime. For example, if you are storing user objects in IndexedDB, you can define a User type in TypeScript:

interface User {
    id: number;
    name: string;
    age: number;
}

Usage Methods#

Opening a Database#

To start using IndexedDB with TypeScript, you first need to open a database. Here is an example:

const request = indexedDB.open('myDatabase', 1);
 
request.onsuccess = (event) => {
    const db = (event.target as IDBOpenDBRequest).result;
    console.log('Database opened successfully');
};
 
request.onerror = (event) => {
    console.error('Error opening database', (event.target as IDBOpenDBRequest).error);
};
 
request.onupgradeneeded = (event) => {
    const db = (event.target as IDBOpenDBRequest).result;
    const objectStore = db.createObjectStore('users', { keyPath: 'id' });
    objectStore.createIndex('name', 'name', { unique: false });
};

Adding Data#

Once the database is open, you can add data to an object store:

const addUser = (user: User) => {
    const request = indexedDB.open('myDatabase', 1);
 
    request.onsuccess = (event) => {
        const db = (event.target as IDBOpenDBRequest).result;
        const transaction = db.transaction(['users'], 'readwrite');
        const objectStore = transaction.objectStore('users');
        const addRequest = objectStore.add(user);
 
        addRequest.onsuccess = () => {
            console.log('User added successfully');
        };
 
        addRequest.onerror = () => {
            console.error('Error adding user', addRequest.error);
        };
 
        transaction.oncomplete = () => {
            db.close();
        };
    };
};
 
const newUser: User = { id: 1, name: 'John Doe', age: 30 };
addUser(newUser);

Retrieving Data#

You can retrieve data from an object store using a key:

const getUser = (id: number) => {
    const request = indexedDB.open('myDatabase', 1);
 
    request.onsuccess = (event) => {
        const db = (event.target as IDBOpenDBRequest).result;
        const transaction = db.transaction(['users'], 'readonly');
        const objectStore = transaction.objectStore('users');
        const getRequest = objectStore.get(id);
 
        getRequest.onsuccess = () => {
            const user = getRequest.result;
            if (user) {
                console.log('User retrieved:', user);
            } else {
                console.log('User not found');
            }
        };
 
        getRequest.onerror = () => {
            console.error('Error retrieving user', getRequest.error);
        };
 
        transaction.oncomplete = () => {
            db.close();
        };
    };
};
 
getUser(1);

Common Practices#

Error Handling#

Always handle errors when working with IndexedDB. As shown in the previous examples, the onerror event of requests and transactions should be used to log errors and take appropriate actions.

Transaction Management#

All database operations should be performed within a transaction. Make sure to close the database after the transaction is complete to free up resources.

Indexing#

Use indexes when you need to query data based on a specific property. Indexes can significantly improve the performance of data retrieval.

Best Practices#

Use Promises or Async/Await#

The native IndexedDB API uses events, which can lead to callback hell. You can wrap the API in Promises or use async/await to make the code more readable. Here is an example of wrapping the open method in a Promise:

const openDatabase = async () => {
    return new Promise<IDBDatabase>((resolve, reject) => {
        const request = indexedDB.open('myDatabase', 1);
 
        request.onsuccess = (event) => {
            const db = (event.target as IDBOpenDBRequest).result;
            resolve(db);
        };
 
        request.onerror = (event) => {
            reject((event.target as IDBOpenDBRequest).error);
        };
 
        request.onupgradeneeded = (event) => {
            const db = (event.target as IDBOpenDBRequest).result;
            const objectStore = db.createObjectStore('users', { keyPath: 'id' });
            objectStore.createIndex('name', 'name', { unique: false });
        };
    });
};
 
const main = async () => {
    try {
        const db = await openDatabase();
        console.log('Database opened successfully');
        db.close();
    } catch (error) {
        console.error('Error opening database', error);
    }
};
 
main();

Versioning#

When making changes to the database schema, increment the database version number. The onupgradeneeded event will be triggered, allowing you to update the object stores and indexes.

Data Validation#

Before adding data to the database, validate it to ensure it meets the expected structure. TypeScript's static typing can help with this.

Conclusion#

IndexedDB combined with TypeScript provides a powerful and reliable way to store and manage data on the client - side. By understanding the fundamental concepts, using proper usage methods, following common practices, and implementing best practices, you can build robust web applications with efficient data storage.

References#

2025-10