dexie 4.0.8 → 4.1.0-alpha.12

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.8, Wed Jul 10 2024
+ * Version 4.1.0-alpha.12, Wed Oct 16 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,10 +364,177 @@ export interface PromiseExtended<T = any> extends Promise<T> {
 	finally<U>(onFinally?: () => U | PromiseLike<U>): PromiseExtended<T>;
 	timeout(ms: number, msg?: string): PromiseExtended<T>;
 }
+// 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 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 type KeyPaths<T> = {
 	[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 YjsDoc // 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] : any;
@@ -452,6 +624,22 @@ export interface IntervalTreeNode {
 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;
@@ -472,17 +660,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
  */
@@ -549,7 +746,7 @@ export interface DBCoreMutateResponse {
 		[operationNumber: number]: Error;
 	};
 	lastResult: any;
-	results?: any[]; // Present on AddRequest and PutRequest.
+	results?: any[]; // Always present on responses to AddRequest and PutRequest.
 }
 export interface DBCoreAddRequest {
 	type: "add";
@@ -813,12 +1010,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>;
@@ -847,6 +1046,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: {
@@ -1005,34 +1205,6 @@ export interface DexieDOMDependencies {
 	indexedDB: IDBFactory;
 	IDBKeyRange: typeof IDBKeyRange;
 }
-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;
@@ -1083,6 +1255,8 @@ export interface DexieOptions {
 	modifyChunkSize?: number;
 	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;
@@ -1129,16 +1303,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:
@@ -1147,11 +1329,38 @@ 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> {
+	private refCount;
+	private stopObserving;
+	private cleanupHandlers;
+	doc: YDoc;
+	awareness?: any;
+	whenLoaded: Promise<void>;
+	whenSynced: Promise<void>;
+	on: DexieEventSet & ((name: string, f: (...args: any[]) => any) => void);
+	off: (name: string, f: (...args: any[]) => any) => void;
+	destroyed: boolean;
+	static load<YDoc extends YjsDoc>(doc: YDoc): DexieYProvider$1<YDoc>;
+	static release<YDoc extends YjsDoc>(doc: YDoc, options?: ReleaseOptions): void;
+	static for<YDoc extends YjsDoc>(doc: YDoc): DexieYProvider$1<YDoc> | undefined;
+	static getDocCache: typeof getDocCache;
+	static currentUpdateRow: YUpdateRow | null;
+	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> {
 }
 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.
@@ -1165,12 +1374,16 @@ 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 {
+	Dexie as default,
+	DexieYProvider$1 as DexieYProvider,
+	RangeSet$1 as RangeSet,
+};
 
 export {};