dexie 4.0.7 → 4.0.9-alpha.1

package/dist/README.md

@@ -0,0 +1,46 @@
+## Can't find dexie.js?
+Dexie's dist files are no longer checked in to github except temporarily when tagging
+a release version (just so that bower will continue to work). The reason for this is because
+checking in dist files bloats the commit history and makes it error prone to contribute to the
+repo. To support bower though, we have to continue checking in dist files when releasing,
+but that is now handled by the release.sh script, who also removes them directly afterwards.
+
+If you still just want to download dexie.js to include in a test HTML page, go
+to the following download site:
+
+### Download
+[dexie.min.js](https://unpkg.com/dexie/dist/dexie.min.js)
+
+[dexie.min.js.map](https://unpkg.com/dexie/dist/dexie.min.js.map)
+
+### Typings
+[dexie.d.ts](https://unpkg.com/dexie/dist/dexie.d.ts)
+
+### Optional Stuff
+[dexie.js (non-minified version)](https://unpkg.com/dexie/dist/dexie.js)
+
+[dexie.js.map](https://unpkg.com/dexie/dist/dexie.js.map)
+
+[dexie.min.js.gz (Minified and gzipped)](https://unpkg.com/dexie/dist/dexie.min.js.gz)
+
+## Install from NPM
+```
+npm install dexie
+```
+
+## How to build
+1. cd to dexie package
+2. npm install
+3. npm run build
+
+## Contributing to Dexie.js?
+
+Watch:
+```
+npm run watch
+```
+
+Test:
+```
+npm test
+```

package/dist/dexie.d.ts

@@ -4,13 +4,13 @@
  *
  * By David Fahlander, david.fahlander@gmail.com
  *
- * Version 4.0.7, Sun May 26 2024
+ * Version 4.0.9-alpha.1, Fri Aug 23 2024
  *
  * https://dexie.org
  *
  * Apache License Version 2.0, January 2004, http://www.apache.org/licenses/
  */
- // Generated by dts-bundle-generator v5.9.0
+ // Generated by dts-bundle-generator v9.3.1
 
 export interface IndexSpec {
 	name: string;
@@ -20,11 +20,16 @@ export interface IndexSpec {
 	auto: boolean | undefined;
 	compound: boolean | undefined;
 	src: string;
+	type?: string | undefined;
 }
 export interface TableSchema {
 	name: string;
 	primKey: IndexSpec;
 	indexes: IndexSpec[];
+	yProps?: {
+		prop: string;
+		updatesTable: string;
+	}[];
 	mappedClass: Function;
 	idxByName: {
 		[name: string]: IndexSpec;
@@ -359,20 +364,133 @@ export interface PromiseExtended<T = any> extends Promise<T> {
 	finally<U>(onFinally?: () => U | PromiseLike<U>): PromiseExtended<T>;
 	timeout(ms: number, msg?: string): PromiseExtended<T>;
 }
+export interface DucktypedY {
+	Doc: new (options?: {
+		guid?: string;
+		collectionid?: string;
+		gc?: boolean;
+		gcFilter?: any;
+		meta?: any;
+		autoLoad?: boolean;
+		shouldLoad?: boolean;
+	}) => DucktypedYDoc;
+	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 DucktypedYObservable {
+	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;
+}
+/** Dock-typed Y.Doc */
+export interface DucktypedYDoc extends DucktypedYObservable {
+	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>;
+}
+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 YSyncer row with an unsentFrom value set to the a number representing primary key (i)
+ * of updates that has not been sent to server or peer yet. Dexie will spare all updates that occur after the least
+ * unsentFrom value in the updates table from being compressed and garbage collected into the main update.
+*/
+export interface YSyncer {
+	i: string;
+	unsentFrom: 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 DexieYProvider<YDoc = any> {
+	readonly doc: YDoc;
+	awareness?: any;
+	whenLoaded: Promise<any>;
+	whenSynced: Promise<any>;
+	on: DexieEventSet & ((name: string, f: (...args: any[]) => any) => void);
+	off(name: string, f: (...args: any[]) => any): void;
+	destroy(): void;
+	readonly destroyed: boolean;
+}
+export interface YDocCache {
+	readonly size: number;
+	find: (table: string, primaryKey: any, ydocProp: string) => DucktypedYDoc | undefined;
+	add: (doc: DucktypedYDoc) => void;
+	delete: (doc: DucktypedYDoc) => void;
+}
 export type KeyPaths<T> = {
-	[P in keyof T]: P extends string ? T[P] extends Array<infer K> ? K extends object // only drill into the array element if it's an object
+	[P in keyof T]: P extends string ? T[P] extends Array<infer K> ? K extends any[] // Array of arrays (issue #2026)
+	 ? P | `${P}.${number}` | `${P}.${number}.${number}` : K extends object // only drill into the array element if it's an object
 	 ? P | `${P}.${number}` | `${P}.${number}.${KeyPaths<K>}` : P | `${P}.${number}` : T[P] extends (...args: any[]) => any // Method
+	 ? never : T[P] extends DucktypedYDoc // Not valid in update spec or where clause (+ avoid circular reference)
 	 ? never : T[P] extends object ? P | `${P}.${KeyPaths<T[P]>}` : P : never;
 }[keyof T];
-export type KeyPathValue<T, PATH> = PATH extends `${infer R}.${infer S}` ? R extends keyof T ? KeyPathValue<T[R], S> : T extends any[] ? PATH extends `${number}.${infer S}` ? KeyPathValue<T[number], S> : void : void : PATH extends `${number}` ? T extends any[] ? T[number] : void : PATH extends keyof T ? T[PATH] : void;
+export type KeyPathValue<T, PATH> = PATH extends `${infer R}.${infer S}` ? R extends keyof T ? KeyPathValue<T[R], S> : T extends any[] ? PATH extends `${number}.${infer S}` ? KeyPathValue<T[number], S> : void : void : PATH extends `${number}` ? T extends any[] ? T[number] : void : PATH extends keyof T ? T[PATH] : any;
 export declare const PropModSymbol: unique symbol;
 export type PropModSpec = {
 	replacePrefix?: [
 		string,
 		string
 	];
-	add?: number | BigInt | Array<string | number>;
-	remove?: number | BigInt | Array<string | number>;
+	add?: number | bigint | Array<string | number>;
+	remove?: number | bigint | Array<string | number>;
 };
 export class PropModification implements PropModSpec {
 	[PropModSymbol]?: true;
@@ -380,8 +498,8 @@ export class PropModification implements PropModSpec {
 		string,
 		string
 	];
-	add?: number | BigInt | Array<string | number>;
-	remove?: number | BigInt | Array<string | number>;
+	add?: number | bigint | Array<string | number>;
+	remove?: number | bigint | Array<string | number>;
 	execute<T>(value: T): T;
 	constructor(spec: PropModSpec);
 }
@@ -444,13 +562,29 @@ export type IntervalTree = IntervalTreeNode | EmptyRange;
 export interface IntervalTreeNode {
 	from: IndexableType; // lower bound
 	to: IndexableType; // upper bound
-	l: IntervalTreeNode | null; // left
-	r: IntervalTreeNode | null; // right
+	l?: IntervalTreeNode | null; // left
+	r?: IntervalTreeNode | null; // right
 	d: number; // depth
 }
 export interface EmptyRange {
 	d: 0;
 }
+export interface RangeSetPrototype {
+	add(rangeSet: IntervalTree | {
+		from: IndexableType;
+		to: IndexableType;
+	}): RangeSet;
+	addKey(key: IndexableType): RangeSet;
+	addKeys(keys: IndexableType[]): RangeSet;
+	hasKey(key: IndexableType): boolean;
+	[Symbol.iterator](): Iterator<IntervalTreeNode, undefined, IndexableType | undefined>;
+}
+export type RangeSet = RangeSetPrototype & IntervalTree;
+export interface RangeSetConstructor {
+	(tree: IntervalTree): RangeSet;
+	new (): RangeSet;
+	new (from: IndexableType, to?: IndexableType): RangeSet;
+}
 export interface DexieOnReadyEvent {
 	subscribe(fn: (vipDb: Dexie) => any, bSticky: boolean): void;
 	unsubscribe(fn: (vipDb: Dexie) => any): void;
@@ -471,17 +605,26 @@ export interface DexieCloseEvent {
 	unsubscribe(fn: (event: Event) => any): void;
 	fire(event: Event): any;
 }
-export interface DbEvents extends DexieEventSet {
-	(eventName: "ready", subscriber: (vipDb: Dexie) => any, bSticky?: boolean): void;
+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;
 	ready: DexieOnReadyEvent;
 	populate: DexiePopulateEvent;
 	blocked: DexieEvent;
 	versionchange: DexieVersionChangeEvent;
 	close: DexieCloseEvent;
+	y: DexieYEvent;
 }
 /** Set of mutated parts of the database
  */
@@ -737,10 +880,11 @@ export interface Table<T = any, TKey = any, TInsertType = T> {
 	reverse(): Collection<T, TKey, TInsertType>;
 	mapToClass(constructor: Function): Function;
 	add(item: TInsertType, key?: TKey): PromiseExtended<TKey>;
-	update(key: TKey | T, changes: UpdateSpec<TInsertType> | ((obj: T, ctx: {
+	update(key: TKey | T, changes: ((obj: T, ctx: {
 		value: any;
 		primKey: IndexableType;
 	}) => void | boolean)): PromiseExtended<number>;
+	update(key: TKey | T, changes: UpdateSpec<TInsertType>): PromiseExtended<number>;
 	put(item: TInsertType, key?: TKey): PromiseExtended<TKey>;
 	delete(key: TKey): PromiseExtended<void>;
 	clear(): PromiseExtended<void>;
@@ -811,12 +955,14 @@ export interface Dexie {
 	readonly _allTables: {
 		[name: string]: Table<any, IndexableType>;
 	};
+	readonly _options: DexieOptions;
 	readonly core: DBCore;
 	_createTransaction: (this: Dexie, mode: IDBTransactionMode, storeNames: ArrayLike<string>, dbschema: DbSchema, parentTransaction?: Transaction | null) => Transaction;
 	readonly _novip: Dexie;
 	_dbSchema: DbSchema;
 	version(versionNumber: number): Version;
 	on: DbEvents;
+	once: DbEventFns;
 	open(): PromiseExtended<Dexie>;
 	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>;
@@ -845,6 +991,7 @@ 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: {
@@ -1003,6 +1150,7 @@ 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;
@@ -1081,6 +1229,7 @@ export interface DexieOptions {
 	modifyChunkSize?: number;
 	chromeTransactionDurability?: ChromeTransactionDurability;
 	cache?: "immutable" | "cloned" | "disabled";
+	Y?: DucktypedY; // Caller supplies Y from the following: import * as Y from 'yjs';
 }
 export interface DexieConstructor extends DexieExceptionClasses {
 	new (databaseName: string, options?: DexieOptions): Dexie;
@@ -1127,16 +1276,24 @@ export class Entity<TDexieSubClass extends Dexie = Dexie> {
 export type IsStrictlyAny<T> = (T extends never ? true : false) extends false ? false : true;
 /** Extract the union of literal method names in T
  */
-export type MethodProps<T> = {
+export type NonInsertProps<T> = {
 	[P in keyof T]: IsStrictlyAny<T[P]> extends true ? never // Plain property of type any (not method)
 	 : T[P] extends (...args: any[]) => any ? P // a function (method)
+	 : T[P] extends {
+		on: any;
+		subdocs: any;
+		gc: any;
+		isSynced: any;
+		isLoaded: any;
+		shouldLoad: any;
+	} ? P // an YDoc property - should be generated by dexie and not by user
 	 : never;
 }[keyof T];
 /** Default insert type of T is a subset of T where:
  *    * given optional props (such as an auto-generated primary key) are made optional
  *    * methods are omitted
  */
-export type InsertType<T, OptionalProps extends keyof T> = Omit<T, OptionalProps | MethodProps<T>> & {
+export type InsertType<T, OptionalProps extends keyof T> = Omit<T, OptionalProps | NonInsertProps<T>> & {
 	[P in OptionalProps]?: T[P];
 };
 /** IDType extract the actual type of the primary key:
@@ -1146,10 +1303,13 @@ 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>;
 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> {
 }
 export interface _Collection<T, TKey> extends Collection<T, TKey> {
 }
+// Besides being the only exported value, let Dexie also be
+// a namespace for types...
 export declare module Dexie {
 	// The "Dexie.Promise" type.
 	type Promise<T = any> = PromiseExtended<T>; // Because many samples have been Dexie.Promise.
@@ -1163,12 +1323,20 @@ export declare module Dexie {
 export function liveQuery<T>(querier: () => T | Promise<T>): Observable<T>;
 export function mergeRanges(target: IntervalTree, newSet: IntervalTree): void;
 export function rangesOverlap(rangeSet1: IntervalTree, rangeSet2: IntervalTree): boolean;
+declare var RangeSet$1: RangeSetConstructor;
 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;
+export declare var DexieYProvider: {
+	(doc: DucktypedYDoc): DexieYProvider;
+	new (doc: DucktypedYDoc): DexieYProvider;
+	getDocCache: (db: Dexie) => YDocCache;
+};
+
+export {
+	Dexie as default,
+	RangeSet$1 as RangeSet,
+};
 
 export {};