Angular IndexedDB Wrapper

Common errors

• Error: No `indexedDB` object found in `window`.

  cause This typically occurs when running an Angular application with SSR without proper `ngx-indexed-db` configuration for the server environment, or when using an older version that lacked full SSR support.
  fix Upgrade to `ngx-indexed-db@19.2.0` or newer. Ensure your SSR setup correctly uses `platform-server` and `ngx-indexed-db` is configured, potentially providing a custom `SERVER_INDEXED_DB` token if needed.

• DOMException: The database is not compatible with the version provided.

  cause The `version` specified in `DBConfig` is lower than the version of the database already existing in the user's browser, or a version was incremented without providing the necessary migration functions.
  fix Always increment the `DBConfig.version` when making schema changes. Ensure that a corresponding migration function exists in `migrationFactory` for each version increment that needs to apply schema changes or data transformations.

• DOMException: TransactionInactiveError: A request was placed against an IDBObjectStore, but the transaction which was used to retrieve it has since become inactive or finished.

  cause An attempt was made to use an `IDBObjectStore` or `IDBIndex` object after the transaction it belongs to has completed, committed, or aborted. This usually means trying to perform an operation outside the scope of an active transaction.
  fix Ensure all database operations are completed within the lifetime of a single IndexedDB transaction. `ngx-indexed-db`'s service methods manage transactions, so avoid holding references to `objectStore` or `index` objects from a finished transaction.

• NG0304: 'NgxIndexedDBModule' is not an NgModule

  cause This error can occur if `NgxIndexedDBModule` is imported incorrectly, or if there's a version mismatch between `@angular/core` and `ngx-indexed-db` that causes compilation issues.
  fix Verify that `@angular/core` and `ngx-indexed-db` versions are compatible. Ensure `NgxIndexedDBModule.forRoot(dbConfig)` is placed correctly in the `imports` array of an NgModule, or use `provideIndexedDb(dbConfig)` in your providers if using standalone components/bootstrap.

Warnings

• breaking Major version upgrades often coincide with Angular's ecosystem, requiring updates to maintain compatibility. Always check peer dependency ranges and release notes when upgrading Angular.
  Fix: Consult the `ngx-indexed-db` changelog and your Angular version's documentation for compatible package versions. Update `ngx-indexed-db` accordingly.
• gotcha Prior to version 19.2.0, `ngx-indexed-db` did not fully support Server-Side Rendering (SSR) and could lead to errors related to `window.indexedDB` being undefined. SSR is fully supported from v19.2.0 onwards.
  Fix: Upgrade to `ngx-indexed-db@19.2.0` or higher for robust SSR support. If using an older version, ensure IndexedDB operations are guarded by `isPlatformBrowser` or provide a custom `SERVER_INDEXED_DB` token.
• gotcha Database schema changes (e.g., adding new object stores or indexes) require incrementing the `DBConfig.version` and providing a `migrationFactory`. Failing to do so will result in `DOMException` errors when opening the database.
  Fix: Always increment your `DBConfig.version` when modifying the schema. Implement corresponding migration functions in the `migrationFactory` to handle schema updates for existing databases.
• gotcha IndexedDB operations are asynchronous and transaction-based. Mismanaging transactions or attempting operations outside an active transaction will lead to errors.
  Fix: Ensure all read/write operations are performed within an active transaction. `ngx-indexed-db`'s observable API generally handles this, but be mindful when directly interacting with the underlying IDB objects if custom logic is involved.

Install

• npm install ngx-indexed-db npm
• yarn add ngx-indexed-db yarn
• pnpm add ngx-indexed-db pnpm

Imports

• NgxIndexedDBModule
  wrong:

  const NgxIndexedDBModule = require('ngx-indexed-db')

  correct:

  import { NgxIndexedDBModule } from 'ngx-indexed-db'

  Used for module-based Angular applications (e.g., in an NgModule's imports array).
• DBConfig
  wrong:

  import type { DBConfig } from 'ngx-indexed-db'

  correct:

  import { DBConfig } from 'ngx-indexed-db'

  The interface for configuring your IndexedDB database schema and version.
• provideIndexedDb

  import { provideIndexedDb } from 'ngx-indexed-db'

  Recommended for standalone Angular applications or when using the providers array in an NgModule.
• NgxIndexedDBService

  import { NgxIndexedDBService } from 'ngx-indexed-db'

  The primary service injected into components/services to interact with the IndexedDB.
• SERVER_INDEXED_DB

  import { SERVER_INDEXED_DB } from 'ngx-indexed-db'

  An InjectionToken used to provide a custom IndexedDB implementation, primarily for SSR or testing environments.

Quickstart

This quickstart demonstrates configuring ngx-indexed-db for both NgModule and standalone Angular applications, including defining the database schema and implementing version migrations.

import { NgModule, ApplicationConfig } from '@angular/core';
import { NgxIndexedDBModule, provideIndexedDb, DBConfig } from 'ngx-indexed-db';

// Ahead of time compiles requires an exported function for factories
export function migrationFactory() {
  return {
    1: (db, transaction) => {
      const store = transaction.objectStore('people');
      store.createIndex('country', 'country', { unique: false });
    },
    3: (db, transaction) => {
      const store = transaction.objectStore('people');
      store.createIndex('age', 'age', { unique: false });
    }
  };
}

const dbConfig: DBConfig  = {
  name: 'MyDb',
  version: 3,
  objectStoresMeta: [{
    store: 'people',
    storeConfig: { keyPath: 'id', autoIncrement: true },
    storeSchema: [
      { name: 'name', keypath: 'name', options: { unique: false } },
      { name: 'email', keypath: 'email', options: { unique: false } }
    ]
  }, {
    store: 'animals',
    storeConfig: { keyPath: 'id', autoIncrement: true },
    storeSchema: [
      { name: 'name', keypath: 'name', options: { unique: true } }
    ]
  }],
  migrationFactory
};

// For NgModule-based applications
@NgModule({
  imports: [
    NgxIndexedDBModule.forRoot(dbConfig)
  ]
})
export class AppModule { }

// For Standalone API (main.ts or component providers)
const appConfig: ApplicationConfig = {
  providers: [
    provideIndexedDb(dbConfig)
  ]
};