dexie 4.1.0-beta.45 → 4.2.0-alpha.1

package/README.md

@@ -4,28 +4,6 @@
 
 Dexie.js is a wrapper library for indexedDB - the standard database in the browser. https://dexie.org.
 
-
-```
- /$$   /$$                     /$$                   /$$     /$$                          
-| $$  | $$                    | $$                  | $$    | $$                          
-| $$  | $$  /$$$$$$   /$$$$$$$| $$   /$$  /$$$$$$  /$$$$$$  | $$$$$$$   /$$$$$$  /$$$$$$$ 
-| $$$$$$$$ |____  $$ /$$_____/| $$  /$$/ |____  $$|_  $$_/  | $$__  $$ /$$__  $$| $$__  $$
-| $$__  $$  /$$$$$$$| $$      | $$$$$$/   /$$$$$$$  | $$    | $$  \ $$| $$  \ $$| $$  \ $$
-| $$  | $$ /$$__  $$| $$      | $$_  $$  /$$__  $$  | $$ /$$| $$  | $$| $$  | $$| $$  | $$
-| $$  | $$|  $$$$$$$|  $$$$$$$| $$ \  $$|  $$$$$$$  |  $$$$/| $$  | $$|  $$$$$$/| $$  | $$
-|__/  |__/ \_______/ \_______/|__/  \__/ \_______/   \___/  |__/  |__/ \______/ |__/  |__/
-                                                    
-🌟 Welcome to Dexie Global Hackathon 25! 🌟
-📅 Date: February 14 --> April 13, 2025
-🕒 Start coding with Dexie Cloud and win prices!
-
-For more information: dexie.org/hackathon 
-
-Good luck! 🚀
-
-```
-[dexie.org/hackathon](https://dexie.org/hackathon/)
-
 #### Why Dexie.js?
 
 IndexedDB is the portable database for all browser engines. Dexie.js makes it fun and easy to work with.
@@ -36,14 +14,15 @@ But also:
 * 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
+#### Hello World (vanilla JS)
 
 ```html
 <!DOCTYPE html>
 <html>
   <head>
-    <script src="https://unpkg.com/dexie/dist/dexie.js"></script>
-    <script>
+    <script type="module">
+      // Import Dexie
+      import { Dexie } from 'https://unpkg.com/dexie/dist/modern/dexie.mjs';
 
       //
       // Declare Database
@@ -56,17 +35,18 @@ But also:
       //
       // 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}`);
-      });
+      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>
@@ -74,17 +54,14 @@ But also:
 
 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:
+#### Hello World (legacy script tags)
 
 ```html
 <!DOCTYPE html>
 <html>
   <head>
-    <script type="module">
-      // Import Dexie
-      import { Dexie } from 'https://unpkg.com/dexie/dist/modern/dexie.mjs';
+    <script src="https://unpkg.com/dexie/dist/dexie.js"></script>
+    <script>
 
       //
       // Declare Database
@@ -97,18 +74,17 @@ All modern browsers support ES modules and top-level awaits. No transipler neede
       //
       // 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) {
+      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>

package/dist/dexie.d.ts

@@ -4,7 +4,7 @@
  *
  * By David Fahlander, david.fahlander@gmail.com
  *
- * Version 4.1.0-beta.45, Mon Mar 31 2025
+ * Version 4.2.0-alpha.1, Fri Aug 01 2025
  *
  * https://dexie.org
  *
@@ -29,7 +29,7 @@ export interface TableSchema {
 	yProps?: {
 		prop: string;
 		updatesTable: string;
-	}[];
+	}[]; // Available if y-dexie addon is used and schema defines Y.Doc properties.
 	mappedClass: Function;
 	idxByName: {
 		[name: string]: IndexSpec;
@@ -418,12 +418,14 @@ export interface Collection<T = any, TKey = IndexableType, TInsertType = T> {
 	filter(filter: (x: T) => boolean): Collection<T, TKey, TInsertType>;
 	first(): PromiseExtended<T | undefined>;
 	first<R>(thenShortcut: ThenShortcut<T | undefined, R>): PromiseExtended<R>;
+	firstKey(): PromiseExtended<IndexableType | undefined>;
 	keys(): PromiseExtended<IndexableTypeArray>;
 	keys<R>(thenShortcut: ThenShortcut<IndexableTypeArray, R>): PromiseExtended<R>;
 	primaryKeys(): PromiseExtended<TKey[]>;
 	primaryKeys<R>(thenShortcut: ThenShortcut<TKey[], R>): PromiseExtended<R>;
 	last(): PromiseExtended<T | undefined>;
 	last<R>(thenShortcut: ThenShortcut<T | undefined, R>): PromiseExtended<R>;
+	lastKey(): PromiseExtended<IndexableType | undefined>;
 	limit(n: number): Collection<T, TKey, TInsertType>;
 	offset(n: number): Collection<T, TKey, TInsertType>;
 	or(indexOrPrimayKey: string): WhereClause<T, TKey, TInsertType>;
@@ -470,174 +472,6 @@ export interface RangeSetConstructor {
 	new (): RangeSet;
 	new (from: IndexableType, to?: IndexableType): RangeSet;
 }
-// There typings are extracted from https://github.com/tc39/proposal-observable
-declare global {
-	interface SymbolConstructor {
-		readonly observable: symbol;
-	}
-}
-export interface Subscribable<T> {
-	subscribe(observer: Partial<Observer<T>>): Unsubscribable;
-}
-export interface Unsubscribable {
-	unsubscribe(): void;
-}
-export interface Observable<T = any> {
-	subscribe(observerOrNext?: Observer<T> | ((value: T) => void)): Subscription;
-	subscribe(next?: ((value: T) => void) | null, error?: ((error: any) => void) | null, complete?: (() => void) | null): Subscription;
-	getValue?(): T;
-	hasValue?(): boolean;
-	[Symbol.observable]: () => Subscribable<T>;
-}
-export interface Subscription {
-	unsubscribe(): void;
-	readonly closed: boolean;
-}
-export interface Observer<T = any> {
-	start?: (subscription: Subscription) => void;
-	next?: (value: T) => void;
-	error?: (error: any) => void;
-	complete?: () => void;
-}
-export interface YjsLib {
-	Doc: new (options?: {
-		guid?: string;
-		collectionid?: string;
-		gc?: boolean;
-		gcFilter?: any;
-		meta?: any;
-		autoLoad?: boolean;
-		shouldLoad?: boolean;
-	}) => YjsDoc;
-	applyUpdate: Function;
-	applyUpdateV2: Function;
-	encodeStateAsUpdate: Function;
-	encodeStateAsUpdateV2: Function;
-	encodeStateVector: Function;
-	encodeStateVectorFromUpdate: Function;
-	encodeStateVectorFromUpdateV2: Function;
-	mergeUpdates: Function;
-	mergeUpdatesV2: Function;
-	diffUpdate: Function;
-	diffUpdateV2: Function;
-	transact: Function;
-}
-export interface YjsObservable {
-	on(name: string, f: (...args: any[]) => any): void;
-	off(name: string, f: (...args: any[]) => any): void;
-	once(name: string, f: (...args: any[]) => any): void;
-	emit(name: string, args: any[]): void;
-	destroy(): void;
-}
-/** Duck-typed Y.Doc */
-export interface YjsDoc extends YjsObservable {
-	guid?: any;
-	collectionid?: any;
-	collection?: any;
-	whenLoaded: PromiseLike<any>;
-	whenSynced: PromiseLike<any>;
-	isLoaded: any;
-	isSynced: any;
-	transact: any;
-	toJSON: () => any;
-	destroy: () => void;
-	meta?: any;
-	share: Map<any, any>;
-}
-/** Docktyped Awareness */
-export interface YjsAwareness extends YjsObservable {
-	doc: YjsDoc;
-	destroy: () => void;
-	clientID: any;
-	states: any;
-	meta: any;
-	getLocalState: any;
-	setLocalState: any;
-	setLocalStateField: any;
-	getStates: any;
-}
-export interface DexieYDocMeta {
-	db: Dexie;
-	parentTable: string;
-	parentId: any;
-	parentProp: string;
-	updatesTable: string;
-}
-/** Stored in the updates table with auto-incremented number as primary key
- *
- */
-export interface YUpdateRow {
-	/** The primary key in the update-table
-	 *
-	 */
-	i: number;
-	/** The primary key of the row in related table holding the document property.
-	 *
-	 */
-	k: IndexableType;
-	/** The Y update
-	 *
-	 */
-	u: Uint8Array;
-	/** Optional flag
-	 *
-	 * 1 = LOCAL_CHANGE_MAYBE_UNSYNCED
-	 *
-	 */
-	f?: number;
-}
-/** Stored in update tables along with YUpdateRows but with a string representing the syncing enging, as primary key
- * A syncing engine can create an YSyncState row with an unsentFrom or receivedUntil value set to the a number representing primary key (i)
- * of updates that has not been sent to server or peer yet. Dexie will compute the least value of unsentFrom and receivedUntil + 1 and
- * spare all updates with an 'i' of that value or greater in the updates table from being compressed and garbage collected into the main update.
-*/
-export interface YSyncState {
-	i: string;
-	unsentFrom?: number;
-	receivedUntil?: number;
-}
-/** A stamp of the last compressed and garbage collected update in the update table.
- * The garbage collection process will find out which documents have got new updates since the last compressed update
- * and compress them into their corresponding main update.
- *
- * The id of this row is always 0 - which is a reserved id for this purpose.
-*/
-export interface YLastCompressed {
-	i: 0;
-	lastCompressed: number;
-	lastRun?: Date;
-}
-export interface ProviderReleaseOptions {
-	// Optional grace period to optimize for unload/reload scenarios when releasing a document
-	// and refcount reached zero - to avoid destroying the document immediately in case
-	// it's going to be reloaded soon.
-	// If not set, the document will be destroyed immediately when refcount reaches zero.
-	gracePeriod?: number;
-}
-declare class DexieYProvider<YDoc = any> {
-	readonly doc: YDoc;
-	awareness?: YjsAwareness;
-	whenLoaded: Promise<void>;
-	whenSynced: Promise<void>;
-	on: DexieEventSet & ((name: string, f: (...args: any[]) => any) => void);
-	off: (name: string, f: (...args: any[]) => any) => void;
-	addCleanupHandler(cleanupHandler: Unsubscribable | (() => void)): void;
-	destroy(): void;
-	readonly destroyed: boolean;
-	static on: DexieEventSet & ((name: string, f: (...args: any[]) => any) => void);
-	static getOrCreateDocument(db: Dexie, table: string, prop: string, id: any): YjsDoc;
-	static load<YDoc extends YjsDoc>(doc: YDoc): DexieYProvider<YDoc>;
-	static release<YDoc extends YjsDoc>(doc: YDoc, options?: ProviderReleaseOptions): void;
-	static for<YDoc extends YjsDoc>(doc: YDoc): DexieYProvider<YDoc> | undefined;
-	static getDocCache: (db: Dexie) => YDocCache;
-	static currentUpdateRow: YUpdateRow | null;
-}
-export interface YDocCache {
-	readonly size: number;
-	find: (table: string, primaryKey: any, ydocProp: string) => YjsDoc | undefined;
-	add: (doc: YjsDoc) => void;
-	delete: (doc: YjsDoc) => void;
-}
 export interface DexieOnReadyEvent {
 	subscribe(fn: (vipDb: Dexie) => any, bSticky: boolean): void;
 	unsubscribe(fn: (vipDb: Dexie) => any): void;
@@ -658,17 +492,11 @@ export interface DexieCloseEvent {
 	unsubscribe(fn: (event: Event) => any): void;
 	fire(event: Event): any;
 }
-export interface DexieYEvent {
-	subscribe(fn: (provider: DexieYProvider, Y: any) => void): void;
-	unsubscribe(fn: (provider: DexieYProvider, Y: any) => void): void;
-	fire(provider: DexieYProvider, Y: any): void;
-}
 export interface DbEventFns {
 	(eventName: "populate", subscriber: (trans: Transaction) => any): void;
 	(eventName: "blocked", subscriber: (event: IDBVersionChangeEvent) => any): void;
 	(eventName: "versionchange", subscriber: (event: IDBVersionChangeEvent) => any): void;
 	(eventName: "close", subscriber: (event: Event) => any): void;
-	(eventName: "y", subscriber: (provider: DexieYProvider, Y: any) => void): void;
 }
 export interface DbEvents extends DbEventFns, DexieEventSet {
 	(eventName: "ready", subscriber: (vipDb: Dexie) => any, bSticky?: boolean): void;
@@ -677,7 +505,6 @@ export interface DbEvents extends DbEventFns, DexieEventSet {
 	blocked: DexieEvent;
 	versionchange: DexieVersionChangeEvent;
 	close: DexieCloseEvent;
-	y: DexieYEvent;
 }
 /** Set of mutated parts of the database
  */
@@ -965,16 +792,24 @@ export interface Table<T = any, TKey = any, TInsertType = T> {
 	}>): PromiseExtended<number>;
 	bulkDelete(keys: TKey[]): PromiseExtended<void>;
 }
+export type DbSchema = {
+	[tableName: string]: TableSchema;
+};
 export interface Version {
 	stores(schema: {
 		[tableName: string]: string | null;
 	}): Version;
 	upgrade(fn: (trans: Transaction) => PromiseLike<any> | void): Version;
 }
+export interface ExtendableVersion extends Version {
+	db: Dexie;
+	_parseStoresSpec(stores: {
+		[tableName: string]: string | null;
+	}, outSchema: DbSchema): void;
+	_createTableSchema(tableName: string, primKey: IndexSpec, indexes: IndexSpec[]): TableSchema;
+	_parseIndexSyntax(primKeyAndIndexes: string): IndexSpec[];
+}
 export type TransactionMode = "readonly" | "readwrite" | "r" | "r!" | "r?" | "rw" | "rw!" | "rw?";
-export type DbSchema = {
-	[tableName: string]: TableSchema;
-};
 export interface Middleware<TStack extends {
 	stack: string;
 }> {
@@ -1043,7 +878,6 @@ export interface Dexie {
 		stack: keyof DexieStacks;
 		name: string;
 	}): this;
-	gc(): Promise<void>;
 	// Make it possible to touch physical class constructors where they reside - as properties on db instance.
 	// For example, checking if (x instanceof db.Table). Can't do (x instanceof Dexie.Table because it's just a virtual interface)
 	Table: {
@@ -1052,8 +886,8 @@ export interface Dexie {
 	WhereClause: {
 		prototype: WhereClause;
 	};
-	Version: {
-		prototype: Version;
+	Version: Function & {
+		prototype: ExtendableVersion;
 	};
 	Transaction: {
 		prototype: Transaction;
@@ -1202,6 +1036,35 @@ export interface DexieDOMDependencies {
 	indexedDB: IDBFactory;
 	IDBKeyRange: typeof IDBKeyRange;
 }
+// There typings are extracted from https://github.com/tc39/proposal-observable
+declare global {
+	interface SymbolConstructor {
+		readonly observable: symbol;
+	}
+}
+export interface Subscribable<T> {
+	subscribe(observer: Partial<Observer<T>>): Unsubscribable;
+}
+export interface Unsubscribable {
+	unsubscribe(): void;
+}
+export interface Observable<T = any> {
+	subscribe(observerOrNext?: Observer<T> | ((value: T) => void)): Subscription;
+	subscribe(next?: ((value: T) => void) | null, error?: ((error: any) => void) | null, complete?: (() => void) | null): Subscription;
+	getValue?(): T;
+	hasValue?(): boolean;
+	[Symbol.observable]: () => Subscribable<T>;
+}
+export interface Subscription {
+	unsubscribe(): void;
+	readonly closed: boolean;
+}
+export interface Observer<T = any> {
+	start?: (subscription: Subscription) => void;
+	next?: (value: T) => void;
+	error?: (error: any) => void;
+	complete?: () => void;
+}
 export type GlobalQueryCache = {
 	// TODO: Change to parts: {[part: string]: TblQueryCache}
 	//       och unsignaledParts: ObservabilitySet;
@@ -1254,8 +1117,6 @@ export interface DexieOptions {
 	};
 	chromeTransactionDurability?: ChromeTransactionDurability;
 	cache?: "immutable" | "cloned" | "disabled";
-	Y?: YjsLib; // Caller supplies Y from the following: import * as Y from 'yjs';
-	gc?: boolean;
 }
 export interface DexieConstructor extends DexieExceptionClasses {
 	new (databaseName: string, options?: DexieOptions): Dexie;
@@ -1328,38 +1189,6 @@ export type InsertType<T, OptionalProps extends keyof T> = Omit<T, OptionalProps
  */
 export type IDType<T, TKeyPropNameOrKeyType> = IsStrictlyAny<T> extends true ? TKeyPropNameOrKeyType : TKeyPropNameOrKeyType extends string ? TKeyPropNameOrKeyType extends keyof T ? T[TKeyPropNameOrKeyType] : TKeyPropNameOrKeyType : TKeyPropNameOrKeyType;
 export type EntityTable<T, TKeyPropName extends keyof T = never, TInsertType = InsertType<T, TKeyPropName>> = Table<T, IDType<T, TKeyPropName>, TInsertType>;
-declare function getDocCache(db: Dexie): YDocCache;
-export interface ReleaseOptions {
-	gracePeriod?: number;
-}
-declare class DexieYProvider$1<YDoc extends YjsDoc = any> implements DexieYProvider<YDoc> {
-	refCount: number;
-	private stopObserving;
-	private cleanupHandlers;
-	private graceTimer;
-	private graceTimeout;
-	doc: YDoc;
-	awareness?: any;
-	private _error?;
-	private _whenLoaded;
-	private _whenSynced;
-	on: DexieEventSet & ((name: string, f: (...args: any[]) => any) => void);
-	off: (name: string, f: (...args: any[]) => any) => void;
-	destroyed: boolean;
-	static on: DexieEventSet & ((name: string, f: (...args: any[]) => any) => void);
-	static getOrCreateDocument(db: Dexie, table: string, prop: string, id: any): YjsDoc;
-	static load<YDoc extends YjsDoc>(doc: YDoc, options?: ReleaseOptions): DexieYProvider$1<YDoc>;
-	static release<YDoc extends YjsDoc>(doc: YDoc): void;
-	private _release;
-	static for<YDoc extends YjsDoc>(doc: YDoc): DexieYProvider$1<YDoc> | undefined;
-	static getDocCache: typeof getDocCache;
-	static currentUpdateRow: YUpdateRow | null;
-	get whenLoaded(): Promise<void>;
-	get whenSynced(): Promise<void>;
-	constructor(doc: YDoc);
-	destroy(): void;
-	addCleanupHandler(cleanupHandler: (() => void) | Unsubscribable): void;
-}
 export declare var Dexie: DexieConstructor;
 // Alias of Table and Collection in order to be able to refer them from module below...
 export interface _Table<T, TKey, TInsertType> extends Table<T, TKey, TInsertType> {
@@ -1389,7 +1218,6 @@ export function remove(num: number | bigint | any[]): PropModification;
 
 export {
 	Dexie as default,
-	DexieYProvider$1 as DexieYProvider,
 	RangeSet$1 as RangeSet,
 };