idb-ts
    Preparing search index...

    Class Database

    Central access point for an IndexedDB database managed by idb-ts.

    A Database instance owns the IDB connection, maintains entity repositories, and runs retention-cleanup background jobs. Always obtain instances through the async factory Database.build - the constructor is private.

    Schema versioning. The effective database version is the highest version value across all registered @DataClass entities. On each onupgradeneeded event, only stores whose version exceeds the previous database version are created or updated, so additive schema evolution is handled automatically.

    Retention cleanup. When entities declare @RetentionPolicy, a periodic setInterval job is started after the database opens. The interval is the GCD of all configured retention periods (in milliseconds), ensuring every policy is evaluated at the right frequency with a single timer.

    Repository access. After build resolves, each registered entity is accessible as a named property on the returned object:

    const db = await Database.build<{ User: EntityRepository<User> }>('mydb', [User]);
    await db.User.create(new User('u1', 'Alice'));

    const db = await Database.build<{
      User:  EntityRepository<User>;
      Order: EntityRepository<Order>;
    }>('shop', [User, Order]);

    await db.User.create(new User('u1', 'Alice', 30));
    const alice = await db.User.read('u1');
    db.close();
    Index

    Methods

    beginTransaction close getAvailableEntities getDatabaseVersion getEntityVersion getEntityVersions transaction build

    Methods

    • Opens a multi-store IDB transaction and returns a TransactionalDatabase with per-entity repositories that share the underlying IDBTransaction.

      Use the returned handle's commit() and rollback() methods to finalise or discard the transaction. For automatic commit/rollback, prefer the callback-based Database.transaction method.

      Parameters

      • entityNames: string[]

        Names of the entity classes whose stores will be enrolled in the transaction.

      • mode: IDBTransactionMode = 'readwrite'

        IDB transaction mode ('readonly' or 'readwrite'). Defaults to 'readwrite'.

      Returns Promise<TransactionalDatabase<Record<string, EntityRepository<any>>>>

      A promise resolving to a TransactionalDatabase handle.

      Error if any name in entityNames is not registered.

      const tx = await db.beginTransaction(['User', 'Order']);
      try {
        await tx.User.create(user);
        await tx.Order.create(order);
        await tx.commit();
      } catch (e) {
        await tx.rollback();
      }

    • Closes the underlying IDB connection and stops the retention cleanup timer. The instance must not be used after calling this method.

      Returns void

      db.close();

    • Returns the names of all entity classes registered with this database.

      Returns string[]

      An array of entity class name strings.

    • Returns the current IDB database version, derived from the highest version annotation across all registered entities.

      Returns number

      The database version number.

    • Returns the schema version of a single registered entity.

      Parameters

      • entityName: string

        The class name of the entity to look up.

      Returns number | undefined

      The entity's version number, or undefined if not registered.

    • Returns a Map of each registered entity name to its configured schema version.

      Returns Map<string, number>

      A Map<string, number> where keys are entity class names and values are version numbers.

    • Executes callback within a single readwrite IDB transaction that spans all registered entities. Commits automatically on success; rolls back and rethrows on any error.

      Type Parameters

      • T

        The type of the value returned by callback.

      Parameters

      • callback: (
            tx: TransactionalDatabase<Record<string, EntityRepository<any>>>,
        ) => T | Promise<T>

        An async or synchronous function receiving the TransactionalDatabase handle. The callback's return value is forwarded to the caller.

      Returns Promise<T>

      A promise resolving to the value returned by callback.

      Re-throws any error thrown by callback after rolling back.

      await db.transaction(async (tx) => {
        await tx.User.create(user);
        await tx.Order.create(order);
        await tx.OrderItem.create(item);
      });

    • Creates and initialises a new Database instance, opening the underlying IndexedDB database and generating entity repositories.

      This is the only public way to obtain a Database instance.

      Type Parameters

      • T extends Record<string, EntityRepository<any>>

        A Record mapping entity names to their EntityRepository types, used to type the returned object's named repository properties.

      Parameters

      • dbName: string

        The name passed to indexedDB.open.

      • classes: Function[]

        The @DataClass-decorated entity constructors to register.

      Returns Promise<DatabaseWithRepositories<T>>

      A promise resolving to a fully initialised DatabaseWithRepositories instance.

      Error - If any class is not decorated with @DataClass.

      IDBRequest error - If the underlying indexedDB.open call fails.

      const db = await Database.build<{
        User:  EntityRepository<User>;
        Order: EntityRepository<Order>;
      }>('shop', [User, Order]);

    Settings

    Member Visibility

    On This Page

    Methods