dexie 4.0.9-alpha.1 → 4.1.0-alpha.3

package/dist/dexie.d.ts

@@ -4,7 +4,7 @@
  *
  * By David Fahlander, david.fahlander@gmail.com
  *
- * Version 4.0.9-alpha.1, Fri Aug 23 2024
+ * Version 4.1.0-alpha.3, Fri Oct 11 2024
  *
  * https://dexie.org
  *
@@ -364,7 +364,36 @@ 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 {
+// 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;
@@ -373,7 +402,7 @@ export interface DucktypedY {
 		meta?: any;
 		autoLoad?: boolean;
 		shouldLoad?: boolean;
-	}) => DucktypedYDoc;
+	}) => YjsDoc;
 	applyUpdate: Function;
 	applyUpdateV2: Function;
 	encodeStateAsUpdate: Function;
@@ -387,15 +416,15 @@ export interface DucktypedY {
 	diffUpdateV2: Function;
 	transact: Function;
 }
-export interface DucktypedYObservable {
+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;
 }
-/** Dock-typed Y.Doc */
-export interface DucktypedYDoc extends DucktypedYObservable {
+/** Duck-typed Y.Doc */
+export interface YjsDoc extends YjsObservable {
 	guid?: any;
 	collectionid?: any;
 	collection?: any;
@@ -409,6 +438,18 @@ export interface DucktypedYDoc extends DucktypedYObservable {
 	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;
@@ -440,13 +481,14 @@ export interface YUpdateRow {
 	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.
+ * 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 YSyncer {
+export interface YSyncState {
 	i: string;
-	unsentFrom: number;
+	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
@@ -459,27 +501,40 @@ export interface YLastCompressed {
 	lastCompressed: number;
 	lastRun?: Date;
 }
-export interface DexieYProvider<YDoc = any> {
+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?: any;
-	whenLoaded: Promise<any>;
-	whenSynced: Promise<any>;
+	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;
+	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) => DucktypedYDoc | undefined;
-	add: (doc: DucktypedYDoc) => void;
-	delete: (doc: DucktypedYDoc) => void;
+	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 DucktypedYDoc // Not valid in update spec or where clause (+ avoid circular reference)
+	 ? 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;
@@ -1150,35 +1205,6 @@ 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;
@@ -1229,7 +1255,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';
+	Y?: YjsLib; // Caller supplies Y from the following: import * as Y from 'yjs';
 }
 export interface DexieConstructor extends DexieExceptionClasses {
 	new (databaseName: string, options?: DexieOptions): Dexie;
@@ -1302,6 +1328,30 @@ 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> {
@@ -1328,14 +1378,10 @@ 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;
-export declare var DexieYProvider: {
-	(doc: DucktypedYDoc): DexieYProvider;
-	new (doc: DucktypedYDoc): DexieYProvider;
-	getDocCache: (db: Dexie) => YDocCache;
-};
 
 export {
 	Dexie as default,
+	DexieYProvider$1 as DexieYProvider,
 	RangeSet$1 as RangeSet,
 };