dexie 4.0.4 → 4.0.7

package/README.md

@@ -1,83 +1,153 @@
-Dexie.js
-========
+# Dexie.js
 
 [![NPM Version][npm-image]][npm-url] ![Build Status](https://github.com/dexie/Dexie.js/actions/workflows/main.yml/badge.svg)
 
-Dexie.js is a wrapper library for indexedDB - the standard database in the browser. https://dexie.org
+Dexie.js is a wrapper library for indexedDB - the standard database in the browser. https://dexie.org.
 
-#### Why?
-Dexie solves three main issues with the native IndexedDB API:
+#### Why Dexie.js?
 
- 1. Ambiguous error handling
- 2. Poor queries
- 3. Code complexity
+IndexedDB is the portable database for all browser engines. Dexie.js makes it fun and easy to work with.
 
-Dexie provides a neat database API with a well thought-through API design, robust error handling, extendability, change tracking awareness and extended KeyRange support (case insensitive search, set matches and OR operations).
+But also:
+
+* Dexie.js is widely used by 100,000 of web sites, apps and other projects and supports all browsers, Electron for Desktop apps, Capacitor for iOS / Android apps and of course pure PWAs.
+* Dexie.js works around bugs in the IndexedDB implementations, giving a more stable user experience.
+* It's an easy step to [make it sync](https://dexie.org/#sync).
 
 #### Hello World
 
 ```html
-<!doctype html>
+<!DOCTYPE html>
 <html>
- <head>
-  <script src="https://unpkg.com/dexie@latest/dist/dexie.js"></script>
-  <script>
-   //
-   // Declare Database
-   //
-   var db = new Dexie("FriendDatabase");
-   db.version(1).stores({
-     friends: "++id,name,age"
-   });
-
-   //
-   // Manipulate and Query Database
-   //
-   db.friends.add({name: "Josephine", age: 21}).then(function() {
-       return db.friends.where("age").below(25).toArray();
-   }).then(function (youngFriends) {
-       alert ("My young friends: " + JSON.stringify(youngFriends));
-   }).catch(function (e) {
-       alert ("Error: " + (e.stack || e));
-   });
-  </script>
- </head>
+  <head>
+    <script src="https://unpkg.com/dexie/dist/dexie.js"></script>
+    <script>
+
+      //
+      // Declare Database
+      //
+      const db = new Dexie('FriendDatabase');
+      db.version(1).stores({
+        friends: '++id, age'
+      });
+
+      //
+      // Play with it
+      //
+      db.friends.add({ name: 'Alice', age: 21 }).then(() => {
+        return db.friends
+          .where('age')
+          .below(30)
+          .toArray();
+      }).then(youngFriends => {
+        alert (`My young friends: ${JSON.stringify(youngFriends)}`);
+      }).catch (e => {
+        alert(`Oops: ${e}`);
+      });
+
+    </script>
+  </head>
 </html>
 ```
-Yes, it's that simple. 
 
-An equivalent modern version (works in all modern browsers):
+Yes, it's that simple. Read [the docs](https://dexie.org/docs/) to get into the details.
+
+#### Hello World (for modern browsers)
+
+All modern browsers support ES modules and top-level awaits. No transipler needed. Here's the previous example in a modern flavour:
 
 ```html
-<!doctype html>
+<!DOCTYPE html>
 <html>
- <head>
-  <script type="module">
-   import Dexie from "https://unpkg.com/dexie@latest/dist/modern/dexie.mjs";
-   //
-   // Declare Database
-   //
-   const db = new Dexie("FriendDatabase");
-   db.version(1).stores({
-     friends: "++id,name,age"
-   });
-
-   //
-   // Manipulate and Query Database
-   //
-   try {
-     await db.friends.add({name: "Josephine", age: 21});
-     const youngFriends = await db.friends.where("age").below(25).toArray();
-     alert (`My young friends: ${JSON.stringify(youngFriends)}`);
-   } catch (e) {
-     alert (`Error: ${e}`);
-   }
-  </script>
- </head>
+  <head>
+    <script type="module">
+      // Import Dexie
+      import { Dexie } from 'https://unpkg.com/dexie/dist/modern/dexie.mjs';
+
+      //
+      // Declare Database
+      //
+      const db = new Dexie('FriendDatabase');
+      db.version(1).stores({
+        friends: '++id, age'
+      });
+
+      //
+      // Play with it
+      //
+      try {
+        await db.friends.add({ name: 'Alice', age: 21 });
+
+        const youngFriends = await db.friends
+            .where('age')
+            .below(30)
+            .toArray();
+
+        alert(`My young friends: ${JSON.stringify(youngFriends)}`);
+      } catch (e) {
+        alert(`Oops: ${e}`);
+      }
+    </script>
+  </head>
 </html>
 ```
 
-[Tutorial](https://dexie.org/docs/Tutorial)
+#### Hello World (React + Typescript)
+
+Real-world apps are often built using components in various frameworks. Here's a version of Hello World written for React and Typescript. There are also links below this sample to more tutorials for different frameworks...
+
+```tsx
+import React from 'react';
+import { Dexie, type EntityTable } from 'dexie';
+import { useLiveQuery } from 'dexie-react-hooks';
+
+// Typing for your entities (hint is to move this to its own module)
+export interface Friend {
+  id: number;
+  name: string;
+  age: number;
+}
+
+// Database declaration (move this to its own module also)
+export const db = new Dexie('FriendDatabase') as Dexie & {
+  friends: EntityTable<Friend, 'id'>;
+};
+db.version(1).stores({
+  friends: '++id, age',
+});
+
+// Component:
+export function MyDexieReactComponent() {
+  const youngFriends = useLiveQuery(() =>
+    db.friends
+      .where('age')
+      .below(30)
+      .toArray()
+  );
+
+  return (
+    <>
+      <h3>My young friends</h3>
+      <ul>
+        {youngFriends?.map((f) => (
+          <li key={f.id}>
+            Name: {f.name}, Age: {f.age}
+          </li>
+        ))}
+      </ul>
+      <button
+        onClick={() => {
+          db.friends.add({ name: 'Alice', age: 21 });
+        }}
+      >
+        Add another friend
+      </button>
+    </>
+  );
+}
+```
+
+[Tutorials for React, Svelte, Vue, Angular and vanilla JS](https://dexie.org/docs/Tutorial/Getting-started)
 
 [API Reference](https://dexie.org/docs/API-Reference)
 
@@ -85,9 +155,10 @@ An equivalent modern version (works in all modern browsers):
 
 ### Performance
 
-Dexie has kick-ass performance. Its [bulk methods](https://dexie.org/docs/Table/Table.bulkPut()) take advantage of a lesser-known feature in IndexedDB that makes it possible to store stuff without listening to every onsuccess event. This speeds up the performance to a maximum.
+Dexie has kick-ass performance. Its [bulk methods](<https://dexie.org/docs/Table/Table.bulkPut()>) take advantage of a lesser-known feature in IndexedDB that makes it possible to store stuff without listening to every onsuccess event. This speeds up the performance to a maximum.
 
 #### Supported operations
+
 ```js
 above(key): Collection;
 aboveOrEqual(key): Collection;
@@ -139,113 +210,76 @@ uniqueKeys(): Promise;
 until(filter: (value) => boolean, includeStopEntry?: boolean): Collection;
 update(key: Key, changes: { [keyPath: string]: any }): Promise;
 ```
-This is a mix of methods from [WhereClause](https://dexie.org/docs/WhereClause/WhereClause), [Table](https://dexie.org/docs/Table/Table) and [Collection](https://dexie.org/docs/Collection/Collection). Dive into the [API reference](https://dexie.org/docs/API-Reference) to see the details.
-
-#### Hello World (Typescript)
-
-```js
-import Dexie, { Table } from 'dexie';
 
-interface Friend {
-    id?: number;
-    name?: string;
-    age?: number;
-}
-
-//
-// Declare Database
-//
-class FriendDatabase extends Dexie {
-    public friends!: Table<Friend, number>; // id is number in this case
-
-    public constructor() {
-        super("FriendDatabase");
-        this.version(1).stores({
-            friends: "++id,name,age"
-        });
-    }
-}
+This is a mix of methods from [WhereClause](https://dexie.org/docs/WhereClause/WhereClause), [Table](https://dexie.org/docs/Table/Table) and [Collection](https://dexie.org/docs/Collection/Collection). Dive into the [API reference](https://dexie.org/docs/API-Reference) to see the details.
 
-const db = new FriendDatabase();
+## Dexie Cloud
 
-db.transaction('rw', db.friends, async() => {
+[Dexie Cloud](https://dexie.org/cloud/) is a commercial offering that can be used as an add-on to Dexie.js. It syncs a Dexie database with a server and enables developers to build apps without having to care about backend or database layer else than the frontend code with Dexie.js as the sole database layer.
 
-    // Make sure we have something in DB:
-    if ((await db.friends.where({name: 'Josephine'}).count()) === 0) {
-        const id = await db.friends.add({name: "Josephine", age: 21});
-        alert (`Addded friend with id ${id}`);
-    }
+Source for a sample Dexie Cloud app: [Dexie Cloud To-do app](https://github.com/dexie/Dexie.js/tree/master/samples/dexie-cloud-todo-app)
 
-    // Query:
-    const youngFriends = await db.friends.where("age").below(25).toArray();
+See the sample Dexie Cloud app in action: https://dexie.github.io/Dexie.js/dexie-cloud-todo-app/
 
-    // Show result:
-    alert ("My young friends: " + JSON.stringify(youngFriends));
+## Samples
 
-}).catch(e => {
-    alert(e.stack || e);
-});
-```
-
-Samples
--------
 https://dexie.org/docs/Samples
 
 https://github.com/dexie/Dexie.js/tree/master/samples
 
-Knowledge Base
------
+## Knowledge Base
+
 [https://dexie.org/docs/Questions-and-Answers](https://dexie.org/docs/Questions-and-Answers)
 
-Website
--------
+## Website
+
 [https://dexie.org](https://dexie.org)
 
-Install over npm
-----------------
+## Install via npm
+
 ```
 npm install dexie
 ```
 
+## Download
 
-Download
---------
 For those who don't like package managers, here's the download links:
 
-### Legacy:
+### UMD (for legacy script includes as well as commonjs require):
+
 https://unpkg.com/dexie@latest/dist/dexie.min.js
 
 https://unpkg.com/dexie@latest/dist/dexie.min.js.map
 
-### Modern:
+### Modern (ES module):
+
 https://unpkg.com/dexie@latest/dist/modern/dexie.min.mjs
 
 https://unpkg.com/dexie@latest/dist/modern/dexie.min.mjs.map
 
 ### Typings:
-https://unpkg.com/dexie@latest/dist/dexie.d.ts
 
+https://unpkg.com/dexie@latest/dist/dexie.d.ts
 
+# Contributing
 
-Contributing
-============
 See [CONTRIBUTING.md](CONTRIBUTING.md)
 
-Build
------
+## Build
+
 ```
 pnpm install
 pnpm run build
 ```
 
-Test
-----
+## Test
+
 ```
 pnpm test
 ```
 
-Watch
------
+## Watch
+
 ```
 pnpm run watch
 ```

package/dist/dexie.d.ts

@@ -4,7 +4,7 @@
  *
  * By David Fahlander, david.fahlander@gmail.com
  *
- * Version 4.0.4, Wed Apr 10 2024
+ * Version 4.0.7, Sun May 26 2024
  *
  * https://dexie.org
  *
@@ -63,6 +63,7 @@ export interface Transaction {
 	db: Dexie;
 	active: boolean;
 	mode: IDBTransactionMode;
+	idbtrans: IDBTransaction;
 	//tables: { [type: string]: Table<any, any> }; Deprecated since 2.0. Obsolete from v3.0.
 	storeNames: Array<string>;
 	explicit?: boolean;
@@ -72,6 +73,7 @@ export interface Transaction {
 	table(tableName: string): Table<any, any>;
 	table<T>(tableName: string): Table<T, any>;
 	table<T, Key>(tableName: string): Table<T, Key>;
+	table<T, Key, TInsertType>(tableName: string): Table<T, Key, TInsertType>;
 }
 export interface CreatingHookContext<T, Key> {
 	onsuccess?: (primKey: Key) => void;
@@ -369,6 +371,8 @@ export type PropModSpec = {
 		string,
 		string
 	];
+	add?: number | BigInt | Array<string | number>;
+	remove?: number | BigInt | Array<string | number>;
 };
 export class PropModification implements PropModSpec {
 	[PropModSymbol]?: true;
@@ -376,6 +380,8 @@ export class PropModification implements PropModSpec {
 		string,
 		string
 	];
+	add?: number | BigInt | Array<string | number>;
+	remove?: number | BigInt | Array<string | number>;
 	execute<T>(value: T): T;
 	constructor(spec: PropModSpec);
 }
@@ -566,6 +572,7 @@ export interface DBCorePutRequest {
 	changeSpec?: {
 		[keyPath: string]: any;
 	}; // Common changeSpec for each key
+	isAdditionalChunk?: boolean;
 	updates?: {
 		keys: any[];
 		changeSpecs: {
@@ -584,6 +591,7 @@ export interface DBCoreDeleteRequest {
 		index: string | null;
 		range: DBCoreKeyRange;
 	};
+	isAdditionalChunk?: boolean;
 }
 export interface DBCoreDeleteRangeRequest {
 	type: "deleteRange";
@@ -810,7 +818,7 @@ export interface Dexie {
 	version(versionNumber: number): Version;
 	on: DbEvents;
 	open(): PromiseExtended<Dexie>;
-	table<T = any, TKey = IndexableType>(tableName: string): Table<T, TKey>;
+	table<T = any, TKey = IndexableType, TInsertType = T>(tableName: string): Table<T, TKey, TInsertType>;
 	transaction<U>(mode: TransactionMode, tables: readonly (string | Table)[], scope: (trans: TXWithTables<this>) => PromiseLike<U> | U): PromiseExtended<U>;
 	transaction<U>(mode: TransactionMode, table: string | Table, scope: (trans: TXWithTables<this>) => PromiseLike<U> | U): PromiseExtended<U>;
 	transaction<U>(mode: TransactionMode, table: string | Table, table2: string | Table, scope: (trans: TXWithTables<this>) => PromiseLike<U> | U): PromiseExtended<U>;
@@ -1157,6 +1165,8 @@ export function mergeRanges(target: IntervalTree, newSet: IntervalTree): void;
 export function rangesOverlap(rangeSet1: IntervalTree, rangeSet2: IntervalTree): boolean;
 export function cmp(a: any, b: any): number;
 export function replacePrefix(a: string, b: string): PropModification;
+export function add(num: number | bigint | any[]): PropModification;
+export function remove(num: number | bigint | any[]): PropModification;
 /** Exporting 'Dexie' as the default export.
  **/
 export default Dexie;

package/dist/dexie.js

@@ -4,7 +4,7 @@
  *
  * By David Fahlander, david.fahlander@gmail.com
  *
- * Version 4.0.4, Wed Apr 10 2024
+ * Version 4.0.7, Sun May 26 2024
  *
  * https://dexie.org
  *
@@ -1150,7 +1150,7 @@
         }
     }
 
-    var DEXIE_VERSION = '4.0.4';
+    var DEXIE_VERSION = '4.0.7';
     var maxString = String.fromCharCode(65535);
     var minKey = -Infinity;
     var INVALID_KEY_ARGUMENT = "Invalid key provided. Keys must be of type string, number, Date or Array<string | number | Date>.";
@@ -1810,6 +1810,40 @@
         }
         PropModification.prototype.execute = function (value) {
             var _a;
+            if (this.add !== undefined) {
+                var term = this.add;
+                if (isArray(term)) {
+                    return __spreadArray(__spreadArray([], (isArray(value) ? value : []), true), term, true).sort();
+                }
+                if (typeof term === 'number')
+                    return (Number(value) || 0) + term;
+                if (typeof term === 'bigint') {
+                    try {
+                        return BigInt(value) + term;
+                    }
+                    catch (_b) {
+                        return BigInt(0) + term;
+                    }
+                }
+                throw new TypeError("Invalid term ".concat(term));
+            }
+            if (this.remove !== undefined) {
+                var subtrahend_1 = this.remove;
+                if (isArray(subtrahend_1)) {
+                    return isArray(value) ? value.filter(function (item) { return !subtrahend_1.includes(item); }).sort() : [];
+                }
+                if (typeof subtrahend_1 === 'number')
+                    return Number(value) - subtrahend_1;
+                if (typeof subtrahend_1 === 'bigint') {
+                    try {
+                        return BigInt(value) - subtrahend_1;
+                    }
+                    catch (_c) {
+                        return BigInt(0) - subtrahend_1;
+                    }
+                }
+                throw new TypeError("Invalid subtrahend ".concat(subtrahend_1));
+            }
             var prefixToReplace = (_a = this.replacePrefix) === null || _a === void 0 ? void 0 : _a[0];
             if (prefixToReplace && typeof value === 'string' && value.startsWith(prefixToReplace)) {
                 return this.replacePrefix[1] + value.substring(prefixToReplace.length);
@@ -2120,6 +2154,12 @@
                     }
                 };
                 return _this.clone().primaryKeys().then(function (keys) {
+                    var criteria = isPlainKeyRange(ctx) &&
+                        ctx.limit === Infinity &&
+                        (typeof changes !== 'function' || changes === deleteCallback) && {
+                        index: ctx.index,
+                        range: ctx.range
+                    };
                     var nextChunk = function (offset) {
                         var count = Math.min(limit, keys.length - offset);
                         return coreTable.getMany({
@@ -2152,12 +2192,6 @@
                                     }
                                 }
                             }
-                            var criteria = isPlainKeyRange(ctx) &&
-                                ctx.limit === Infinity &&
-                                (typeof changes !== 'function' || changes === deleteCallback) && {
-                                index: ctx.index,
-                                range: ctx.range
-                            };
                             return Promise.resolve(addValues.length > 0 &&
                                 coreTable.mutate({ trans: trans, type: 'add', values: addValues })
                                     .then(function (res) {
@@ -2173,13 +2207,15 @@
                                     values: putValues,
                                     criteria: criteria,
                                     changeSpec: typeof changes !== 'function'
-                                        && changes
+                                        && changes,
+                                    isAdditionalChunk: offset > 0
                                 }).then(function (res) { return applyMutateResult(putValues.length, res); }); }).then(function () { return (deleteKeys.length > 0 || (criteria && changes === deleteCallback)) &&
                                 coreTable.mutate({
                                     trans: trans,
                                     type: 'delete',
                                     keys: deleteKeys,
-                                    criteria: criteria
+                                    criteria: criteria,
+                                    isAdditionalChunk: offset > 0
                                 }).then(function (res) { return applyMutateResult(deleteKeys.length, res); }); }).then(function () {
                                 return keys.length > offset + count && nextChunk(offset + limit);
                             });
@@ -5822,6 +5858,14 @@
         });
     }
 
+    function add(value) {
+        return new PropModification({ add: value });
+    }
+
+    function remove(value) {
+        return new PropModification({ remove: value });
+    }
+
     function replacePrefix(a, b) {
         return new PropModification({ replacePrefix: [a, b] });
     }
@@ -5838,6 +5882,8 @@
         PropModSymbol: PropModSymbol,
         PropModification: PropModification,
         replacePrefix: replacePrefix,
+        add: add,
+        remove: remove,
         'default': Dexie$1,
         RangeSet: RangeSet,
         mergeRanges: mergeRanges,