@bjnstnkvc/db 2.0.2 → 2.1.0

package/README.md

@@ -1119,22 +1119,23 @@ DB.onQueryExecuted((event: QueryExecuted): void => {
 });
 ```
 
-| Key                       | Class                   | Carries                                                                                |
-|---------------------------|-------------------------|----------------------------------------------------------------------------------------|
-| `query`                   | `QueryExecuted`         | `connection`, `table`, `plan`, `constraints`, `orders`, `limit`, `duration`, `records` |
-| `transaction-beginning`   | `TransactionBeginning`  | `connection`                                                                           |
-| `transaction-committed`   | `TransactionCommitted`  | `connection`                                                                           |
-| `transaction-rolled-back` | `TransactionRolledBack` | `connection`, `reason`                                                                 |
-| `migrations-started`      | `MigrationsStarted`     | `connection`, `migrations`                                                             |
-| `migration-started`       | `MigrationStarted`      | `migration`                                                                            |
-| `migration-ended`         | `MigrationEnded`        | `migration`                                                                            |
-| `migrations-ended`        | `MigrationsEnded`       | `connection`, `migrations`                                                             |
-| `no-pending-migrations`   | `NoPendingMigrations`   | `connection`                                                                           |
-| `seeding-started`         | `SeedingStarted`        | `connection`, `seeders`                                                                |
-| `seeder-started`          | `SeederStarted`         | `seeder`                                                                               |
-| `seeder-ended`            | `SeederEnded`           | `seeder`                                                                               |
-| `seeding-ended`           | `SeedingEnded`          | `connection`, `seeders`                                                                |
-| `database-blocked`        | `DatabaseBlocked`       | `database`                                                                             |
+| Key                        | Class                    | Carries                                                                                |
+|----------------------------|--------------------------|----------------------------------------------------------------------------------------|
+| `query`                    | `QueryExecuted`          | `connection`, `table`, `plan`, `constraints`, `orders`, `limit`, `duration`, `records` |
+| `transaction-beginning`    | `TransactionBeginning`   | `connection`                                                                           |
+| `transaction-committed`    | `TransactionCommitted`   | `connection`                                                                           |
+| `transaction-rolled-back`  | `TransactionRolledBack`  | `connection`, `reason`                                                                 |
+| `migrations-started`       | `MigrationsStarted`      | `connection`, `migrations`                                                             |
+| `migration-started`        | `MigrationStarted`       | `migration`                                                                            |
+| `migration-ended`          | `MigrationEnded`         | `migration`                                                                            |
+| `migrations-ended`         | `MigrationsEnded`        | `connection`, `migrations`                                                             |
+| `no-pending-migrations`    | `NoPendingMigrations`    | `connection`                                                                           |
+| `seeding-started`          | `SeedingStarted`         | `connection`, `seeders`                                                                |
+| `seeder-started`           | `SeederStarted`          | `seeder`                                                                               |
+| `seeder-ended`             | `SeederEnded`            | `seeder`                                                                               |
+| `seeding-ended`            | `SeedingEnded`           | `connection`, `seeders`                                                                |
+| `database-blocked`         | `DatabaseBlocked`        | `database`                                                                             |
+| `database-version-changed` | `DatabaseVersionChanged` | `database`, `version`                                                                  |
 
 A connection with no seeders announces nothing, so `seeding-started` firing always means at least
 one seeder is about to run.
@@ -1183,9 +1184,21 @@ IndexedDB is shared across tabs, which produces two situations worth handling:
 - Another tab holds an older version open, blocking an upgrade. The connection emits
   `database-blocked` and rejects with `DatabaseBlockedException`, so you can ask the user to close
   the other tabs.
-- Another tab upgrades the database. The connection closes its own handle so it does not block that
-  upgrade. If the other tab is running newer code with more migrations, this tab can no longer open
-  the database and reports `MigrationMismatchException`, so reload the page.
+- Another tab upgrades or deletes the database. The connection closes its own handle so it does not
+  block that tab, then emits `database-version-changed`. Its `version` is the version the other tab
+  is opening, or `null` when it is deleting the database.
+
+The other tab is usually running newer code with more migrations, after a deploy. This tab can no
+longer open the database, and its next query would reject with `MigrationMismatchException`. Reload
+the page when the event arrives, rather than querying again:
+
+```ts
+DB.onDatabaseVersionChanged((event: DatabaseVersionChanged): void => {
+    if (confirm('A new version is available. Reload now?')) {
+        location.reload();
+    }
+});
+```
 
 ### Connections
 

package/dist/main.cjs

@@ -30,6 +30,7 @@ __export(main_exports, {
   DatabaseBlocked: () => DatabaseBlocked,
   DatabaseBlockedException: () => DatabaseBlockedException,
   DatabaseManager: () => DatabaseManager,
+  DatabaseVersionChanged: () => DatabaseVersionChanged,
   Grouping: () => Grouping,
   Join: () => Join,
   Migration: () => Migration,
@@ -690,6 +691,38 @@ var DatabaseBlocked = class extends Event {
   }
 };
 
+// src/events/DatabaseVersionChanged.ts
+var DatabaseVersionChanged = class extends Event {
+  /**
+   * The name of the database.
+   */
+  #database;
+  /**
+   * The version the other tab is opening, or null when it is deleting the database.
+   */
+  #version;
+  /**
+   * Create a new Database Version Changed event instance.
+   */
+  constructor(database, version) {
+    super("db:database-version-changed");
+    this.#database = database;
+    this.#version = version;
+  }
+  /**
+   * Get the name of the database.
+   */
+  get database() {
+    return this.#database;
+  }
+  /**
+   * Get the version the other tab is opening, or null when it is deleting the database.
+   */
+  get version() {
+    return this.#version;
+  }
+};
+
 // src/events/MigrationEnded.ts
 var MigrationEnded = class extends Event {
   /**
@@ -3807,7 +3840,10 @@ var Connection = class {
     Migrator.verify(ran, Migrator.names(this.migrations));
     this.#schemas = new Map(registry.map((schema) => [schema.table, schema]));
     this.#database = database;
-    database.onversionchange = () => this.disconnect();
+    database.onversionchange = (event) => {
+      this.disconnect();
+      Dispatcher.dispatch(new DatabaseVersionChanged(this.#config.database, event.newVersion));
+    };
     return database;
   }
 };
@@ -4043,6 +4079,12 @@ var DatabaseManager = class {
   static onDatabaseBlocked(listener, options) {
     this.listen("database-blocked", listener, options);
   }
+  /**
+   * Register a listener on the "database-version-changed" event.
+   */
+  static onDatabaseVersionChanged(listener, options) {
+    this.listen("database-version-changed", listener, options);
+  }
   /**
    * Register a listener on the "seeding-started" event.
    */
@@ -4372,6 +4414,7 @@ var Seeder = class {
   DatabaseBlocked,
   DatabaseBlockedException,
   DatabaseManager,
+  DatabaseVersionChanged,
   Grouping,
   Join,
   Migration,

package/dist/main.d.cts

@@ -861,6 +861,22 @@ declare class DatabaseBlocked extends Event {
     get database(): string;
 }
 
+declare class DatabaseVersionChanged extends Event {
+    #private;
+    /**
+     * Create a new Database Version Changed event instance.
+     */
+    constructor(database: string, version: number | null);
+    /**
+     * Get the name of the database.
+     */
+    get database(): string;
+    /**
+     * Get the version the other tab is opening, or null when it is deleting the database.
+     */
+    get version(): number | null;
+}
+
 declare class MigrationEnded extends Event {
     #private;
     /**
@@ -1067,6 +1083,7 @@ declare class TransactionRolledBack extends Event {
 
 type DatabaseEvent = {
     'database-blocked': DatabaseBlocked;
+    'database-version-changed': DatabaseVersionChanged;
     'migration-ended': MigrationEnded;
     'migration-started': MigrationStarted;
     'migrations-ended': MigrationsEnded;
@@ -1205,6 +1222,10 @@ declare class DatabaseManager {
      * Register a listener on the "database-blocked" event.
      */
     static onDatabaseBlocked(listener: (event: DatabaseBlocked) => void, options?: ListenOptions): void;
+    /**
+     * Register a listener on the "database-version-changed" event.
+     */
+    static onDatabaseVersionChanged(listener: (event: DatabaseVersionChanged) => void, options?: ListenOptions): void;
     /**
      * Register a listener on the "seeding-started" event.
      */
@@ -1386,4 +1407,4 @@ declare class UniqueConstraintViolationException extends Error {
     constructor(table: string, index: string);
 }
 
-export { type Aggregated, type Aggregation, type Aggregations, Blueprint, Builder, CheckConstraintViolationException, ColumnDefinition, type ColumnSchema, type ColumnType, type Conjunction, Connection, type ConnectionConfig, ConnectionNotConfiguredException, type Constraint, DatabaseManager as DB, DatabaseBlocked, DatabaseBlockedException, type DatabaseConfig, type DatabaseEvent, type DatabaseEventListener, DatabaseManager, type DatePart, type Direction, type Enumerable, type FreshOptions, type Grouped, Grouping, type IndexSchema, Join, type JoinClause, type JoinCondition, type JoinType, type Key, type ListenOptions, Migration, type MigrationConstructor, MigrationEnded, MigrationMismatchException, MigrationStarted, type MigrationStatus, MigrationTransactionClosedException, MigrationsEnded, MigrationsStarted, MultipleRecordsFoundException, NoPendingMigrations, NotNullConstraintViolationException, type Operator, type Order, type Paginated, type Plan, type Projection, QueryExecuted, type QueryLogEntry, QuotaExceededException, RecordsNotFoundException, ReservedTableException, Schema, SchemaException, Seeder, type SeederConstructor, SeederEnded, SeederStarted, SeedingEnded, SeedingStarted, TableNotFoundException, type TableSchema, Transaction, TransactionBeginning, TransactionCommitted, type TransactionOptions, TransactionRolledBack, UniqueConstraintViolationException };
+export { type Aggregated, type Aggregation, type Aggregations, Blueprint, Builder, CheckConstraintViolationException, ColumnDefinition, type ColumnSchema, type ColumnType, type Conjunction, Connection, type ConnectionConfig, ConnectionNotConfiguredException, type Constraint, DatabaseManager as DB, DatabaseBlocked, DatabaseBlockedException, type DatabaseConfig, type DatabaseEvent, type DatabaseEventListener, DatabaseManager, DatabaseVersionChanged, type DatePart, type Direction, type Enumerable, type FreshOptions, type Grouped, Grouping, type IndexSchema, Join, type JoinClause, type JoinCondition, type JoinType, type Key, type ListenOptions, Migration, type MigrationConstructor, MigrationEnded, MigrationMismatchException, MigrationStarted, type MigrationStatus, MigrationTransactionClosedException, MigrationsEnded, MigrationsStarted, MultipleRecordsFoundException, NoPendingMigrations, NotNullConstraintViolationException, type Operator, type Order, type Paginated, type Plan, type Projection, QueryExecuted, type QueryLogEntry, QuotaExceededException, RecordsNotFoundException, ReservedTableException, Schema, SchemaException, Seeder, type SeederConstructor, SeederEnded, SeederStarted, SeedingEnded, SeedingStarted, TableNotFoundException, type TableSchema, Transaction, TransactionBeginning, TransactionCommitted, type TransactionOptions, TransactionRolledBack, UniqueConstraintViolationException };

package/dist/main.d.ts

@@ -861,6 +861,22 @@ declare class DatabaseBlocked extends Event {
     get database(): string;
 }
 
+declare class DatabaseVersionChanged extends Event {
+    #private;
+    /**
+     * Create a new Database Version Changed event instance.
+     */
+    constructor(database: string, version: number | null);
+    /**
+     * Get the name of the database.
+     */
+    get database(): string;
+    /**
+     * Get the version the other tab is opening, or null when it is deleting the database.
+     */
+    get version(): number | null;
+}
+
 declare class MigrationEnded extends Event {
     #private;
     /**
@@ -1067,6 +1083,7 @@ declare class TransactionRolledBack extends Event {
 
 type DatabaseEvent = {
     'database-blocked': DatabaseBlocked;
+    'database-version-changed': DatabaseVersionChanged;
     'migration-ended': MigrationEnded;
     'migration-started': MigrationStarted;
     'migrations-ended': MigrationsEnded;
@@ -1205,6 +1222,10 @@ declare class DatabaseManager {
      * Register a listener on the "database-blocked" event.
      */
     static onDatabaseBlocked(listener: (event: DatabaseBlocked) => void, options?: ListenOptions): void;
+    /**
+     * Register a listener on the "database-version-changed" event.
+     */
+    static onDatabaseVersionChanged(listener: (event: DatabaseVersionChanged) => void, options?: ListenOptions): void;
     /**
      * Register a listener on the "seeding-started" event.
      */
@@ -1386,4 +1407,4 @@ declare class UniqueConstraintViolationException extends Error {
     constructor(table: string, index: string);
 }
 
-export { type Aggregated, type Aggregation, type Aggregations, Blueprint, Builder, CheckConstraintViolationException, ColumnDefinition, type ColumnSchema, type ColumnType, type Conjunction, Connection, type ConnectionConfig, ConnectionNotConfiguredException, type Constraint, DatabaseManager as DB, DatabaseBlocked, DatabaseBlockedException, type DatabaseConfig, type DatabaseEvent, type DatabaseEventListener, DatabaseManager, type DatePart, type Direction, type Enumerable, type FreshOptions, type Grouped, Grouping, type IndexSchema, Join, type JoinClause, type JoinCondition, type JoinType, type Key, type ListenOptions, Migration, type MigrationConstructor, MigrationEnded, MigrationMismatchException, MigrationStarted, type MigrationStatus, MigrationTransactionClosedException, MigrationsEnded, MigrationsStarted, MultipleRecordsFoundException, NoPendingMigrations, NotNullConstraintViolationException, type Operator, type Order, type Paginated, type Plan, type Projection, QueryExecuted, type QueryLogEntry, QuotaExceededException, RecordsNotFoundException, ReservedTableException, Schema, SchemaException, Seeder, type SeederConstructor, SeederEnded, SeederStarted, SeedingEnded, SeedingStarted, TableNotFoundException, type TableSchema, Transaction, TransactionBeginning, TransactionCommitted, type TransactionOptions, TransactionRolledBack, UniqueConstraintViolationException };
+export { type Aggregated, type Aggregation, type Aggregations, Blueprint, Builder, CheckConstraintViolationException, ColumnDefinition, type ColumnSchema, type ColumnType, type Conjunction, Connection, type ConnectionConfig, ConnectionNotConfiguredException, type Constraint, DatabaseManager as DB, DatabaseBlocked, DatabaseBlockedException, type DatabaseConfig, type DatabaseEvent, type DatabaseEventListener, DatabaseManager, DatabaseVersionChanged, type DatePart, type Direction, type Enumerable, type FreshOptions, type Grouped, Grouping, type IndexSchema, Join, type JoinClause, type JoinCondition, type JoinType, type Key, type ListenOptions, Migration, type MigrationConstructor, MigrationEnded, MigrationMismatchException, MigrationStarted, type MigrationStatus, MigrationTransactionClosedException, MigrationsEnded, MigrationsStarted, MultipleRecordsFoundException, NoPendingMigrations, NotNullConstraintViolationException, type Operator, type Order, type Paginated, type Plan, type Projection, QueryExecuted, type QueryLogEntry, QuotaExceededException, RecordsNotFoundException, ReservedTableException, Schema, SchemaException, Seeder, type SeederConstructor, SeederEnded, SeederStarted, SeedingEnded, SeedingStarted, TableNotFoundException, type TableSchema, Transaction, TransactionBeginning, TransactionCommitted, type TransactionOptions, TransactionRolledBack, UniqueConstraintViolationException };

package/dist/main.js

@@ -626,6 +626,38 @@ var DatabaseBlocked = class extends Event {
   }
 };
 
+// src/events/DatabaseVersionChanged.ts
+var DatabaseVersionChanged = class extends Event {
+  /**
+   * The name of the database.
+   */
+  #database;
+  /**
+   * The version the other tab is opening, or null when it is deleting the database.
+   */
+  #version;
+  /**
+   * Create a new Database Version Changed event instance.
+   */
+  constructor(database, version) {
+    super("db:database-version-changed");
+    this.#database = database;
+    this.#version = version;
+  }
+  /**
+   * Get the name of the database.
+   */
+  get database() {
+    return this.#database;
+  }
+  /**
+   * Get the version the other tab is opening, or null when it is deleting the database.
+   */
+  get version() {
+    return this.#version;
+  }
+};
+
 // src/events/MigrationEnded.ts
 var MigrationEnded = class extends Event {
   /**
@@ -3743,7 +3775,10 @@ var Connection = class {
     Migrator.verify(ran, Migrator.names(this.migrations));
     this.#schemas = new Map(registry.map((schema) => [schema.table, schema]));
     this.#database = database;
-    database.onversionchange = () => this.disconnect();
+    database.onversionchange = (event) => {
+      this.disconnect();
+      Dispatcher.dispatch(new DatabaseVersionChanged(this.#config.database, event.newVersion));
+    };
     return database;
   }
 };
@@ -3979,6 +4014,12 @@ var DatabaseManager = class {
   static onDatabaseBlocked(listener, options) {
     this.listen("database-blocked", listener, options);
   }
+  /**
+   * Register a listener on the "database-version-changed" event.
+   */
+  static onDatabaseVersionChanged(listener, options) {
+    this.listen("database-version-changed", listener, options);
+  }
   /**
    * Register a listener on the "seeding-started" event.
    */
@@ -4307,6 +4348,7 @@ export {
   DatabaseBlocked,
   DatabaseBlockedException,
   DatabaseManager,
+  DatabaseVersionChanged,
   Grouping,
   Join,
   Migration,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bjnstnkvc/db",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "TypeScript database layer for IndexedDB with an API modeled on Laravel.",
   "type": "module",
   "main": "./dist/main.cjs",