@bjnstnkvc/db 2.0.1 → 2.1.0

package/README.md

@@ -835,6 +835,7 @@ await DB.table<User>('users').where('id', 1).increment('visits');
 await DB.table<User>('users').where('id', 1).decrement('credits', 5);
 
 await DB.table<User>('users').where('role', 'guest').delete();
+await DB.table<User>('users').oldest('created_at').limit(100).delete();
 await DB.table<User>('users').truncate();
 ```
 
@@ -851,9 +852,10 @@ enforce anything else. Any other column throws `SchemaException`.
 
 The key path may not be updated, so `update`, `upsert` and `increment` all refuse it.
 
-`update` and `delete` honour `limit` and `offset` in the order the plan scans, which is index order
-when an index drives the query and key order otherwise. Pair them with an indexed `orderBy` if you
-need a defined order.
+`update`, `delete`, `increment` and `decrement` honor `orderBy` together with `limit` and
+`offset`, so they touch the same records a read of the query would return, whether or not an index
+serves the order. Without an `orderBy`, they follow the order the plan scans, which is index order
+when an index drives the query and key order otherwise.
 
 > Modeled on Laravel's [Database: Query Builder](https://laravel.com/docs/12.x/queries). The method
 > names and their semantics match, and every terminal is asynchronous because IndexedDB is.
@@ -1117,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.
@@ -1181,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 {
   /**
@@ -2910,7 +2943,7 @@ var Builder = class _Builder {
     }
   }
   /**
-   * Apply a change to every record matching the query, in the order the plan scans them.
+   * Apply a change to every record matching the query, in the order the query asks for.
    */
   async #modify(apply) {
     const schema = await this.#connection.schema(this.#table);
@@ -2919,8 +2952,20 @@ var Builder = class _Builder {
     const started = performance.now();
     const matches = Predicate.compile(plan.residual);
     const ceiling = this.#limit === null ? null : this.#offset + this.#limit;
+    const collects = !plan.ordered && this.#orders.length > 0 && (this.#limit !== null || this.#offset > 0);
     let seen = 0;
     let affected = 0;
+    if (collects) {
+      const collected = plan.values === null ? await this.#cursored(store, plan, matches) : await this.#points(store, plan, matches);
+      for (const entry of this.#paged(this.#sorted(collected))) {
+        await Request.walk(store.openCursor(IDBKeyRange.only(entry.key)), (cursor) => {
+          apply(cursor);
+          affected++;
+        });
+      }
+      this.#emit(Planner.describe(plan), started, affected);
+      return affected;
+    }
     const visit = (cursor) => {
       if (!matches(cursor.value)) {
         return true;
@@ -2937,6 +2982,9 @@ var Builder = class _Builder {
       await Request.walk(source.openCursor(plan.range, plan.direction), visit);
     } else {
       for (const value of plan.values) {
+        if (ceiling !== null && seen >= ceiling) {
+          break;
+        }
         const source = plan.index === null ? store : store.index(plan.index);
         await Request.walk(source.openCursor(IDBKeyRange.only(value)), visit);
       }
@@ -3792,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;
   }
 };
@@ -4028,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.
    */
@@ -4357,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 {
   /**
@@ -2846,7 +2878,7 @@ var Builder = class _Builder {
     }
   }
   /**
-   * Apply a change to every record matching the query, in the order the plan scans them.
+   * Apply a change to every record matching the query, in the order the query asks for.
    */
   async #modify(apply) {
     const schema = await this.#connection.schema(this.#table);
@@ -2855,8 +2887,20 @@ var Builder = class _Builder {
     const started = performance.now();
     const matches = Predicate.compile(plan.residual);
     const ceiling = this.#limit === null ? null : this.#offset + this.#limit;
+    const collects = !plan.ordered && this.#orders.length > 0 && (this.#limit !== null || this.#offset > 0);
     let seen = 0;
     let affected = 0;
+    if (collects) {
+      const collected = plan.values === null ? await this.#cursored(store, plan, matches) : await this.#points(store, plan, matches);
+      for (const entry of this.#paged(this.#sorted(collected))) {
+        await Request.walk(store.openCursor(IDBKeyRange.only(entry.key)), (cursor) => {
+          apply(cursor);
+          affected++;
+        });
+      }
+      this.#emit(Planner.describe(plan), started, affected);
+      return affected;
+    }
     const visit = (cursor) => {
       if (!matches(cursor.value)) {
         return true;
@@ -2873,6 +2917,9 @@ var Builder = class _Builder {
       await Request.walk(source.openCursor(plan.range, plan.direction), visit);
     } else {
       for (const value of plan.values) {
+        if (ceiling !== null && seen >= ceiling) {
+          break;
+        }
         const source = plan.index === null ? store : store.index(plan.index);
         await Request.walk(source.openCursor(IDBKeyRange.only(value)), visit);
       }
@@ -3728,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;
   }
 };
@@ -3964,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.
    */
@@ -4292,6 +4348,7 @@ export {
   DatabaseBlocked,
   DatabaseBlockedException,
   DatabaseManager,
+  DatabaseVersionChanged,
   Grouping,
   Join,
   Migration,

package/package.json

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