edmaxlabs-core 2.5.5 → 2.6.6

package/dist/index.d.cts

@@ -114,57 +114,61 @@ declare class DocumentRef {
     set(data: Record<string, any>): Promise<DocumentSnapshot | null>;
     delete(): Promise<boolean>;
     onSnapshot(callback: (snapshot: DocumentSnapshot | null, change: string) => void): () => void;
+    private fetchRemoteSnapshot;
+    private refreshFromRemote;
+}
+
+type SnapshotSource = "initial" | "insert" | "update" | "delete";
+type ChildChangeType = "added" | "modified" | "removed";
+interface ChildChange {
+    type: ChildChangeType;
+    doc: DocumentSnapshot;
+    previousDoc: DocumentSnapshot | null;
+    oldIndex: number;
+    newIndex: number;
+}
+interface CollectionEmission {
+    snapshots: DocumentSnapshot[];
+    source: SnapshotSource;
+    changedDocId?: string;
+    fromCache?: boolean;
+    childChanges?: ChildChange[];
+}
+interface ChildListenerContext {
+    snapshots: DocumentSnapshot[];
+    source: SnapshotSource;
+    changedDocId?: string;
+    fromCache: boolean;
+    oldIndex: number;
+    newIndex: number;
+    previousDoc: DocumentSnapshot | null;
+}
+interface ChildListenerCallbacks {
+    onChildAdded?: (snapshot: DocumentSnapshot, context: ChildListenerContext) => void;
+    onChildUpdated?: (snapshot: DocumentSnapshot, context: ChildListenerContext) => void;
+    onChildRemoved?: (snapshot: DocumentSnapshot, context: ChildListenerContext) => void;
 }
 
 type DocListener = (snapshot: DocumentSnapshot | null, change: string) => void;
-/**
- * For collection listeners we pass:
- * - snapshots: all current documents in the collection
- * - change: what triggered this emission
- * - changedDocId?: which specific document changed (useful for granular updates)
- */
 type CollectionListener = (snapshots: DocumentSnapshot[], change: string, changedDocId?: string) => void;
 declare class LocalStore {
     private documentListeners;
     private collectionListeners;
+    private childListeners;
     private docKey;
     subscribeToDocument(collection: string, id: string, callback: DocListener): () => void;
-    subscribeToCollection(collection: string, callback: CollectionListener): () => void;
-    /**
-     * Notify all listeners for a specific document
-     */
+    subscribeToCollection(targetKey: string, callback: CollectionListener): () => void;
+    subscribeToChildEvents(targetKey: string, callbacks: ChildListenerCallbacks): () => void;
     emitDocument(collection: string, id: string, snapshot: DocumentSnapshot | null, change: string): void;
-    /**
-     * Notify all listeners for a collection.
-     * This is the most important fix — collection listeners now receive the full list.
-     */
-    emitCollection(collection: string, snapshots: DocumentSnapshot[], // ← Changed from single snapshot
-    change: string, changedDocId?: string): void;
-    /**
-     * OPTIMIZED: Notify collection listeners that something changed, without fetching full collection.
-     * Listeners can call getCollectionSnapshots() themselves if they need the full list.
-     * This avoids expensive collection queries after every single mutation.
-     */
-    notifyCollectionChanged(collection: string, changedDocId: string, change: string): void;
-    /**
-     * Clear all listeners (useful for testing or when persistence is disabled)
-     */
+    emitCollection(targetKey: string, emission: CollectionEmission): void;
     clearAllListeners(): void;
-    /**
-     * Get current listener count (for debugging / dev tools)
-     */
     get listenerCount(): {
         documents: number;
         collections: number;
     };
-    /**
-     * Remove all listeners for a specific collection (useful for cleanup)
-     */
-    removeCollectionListeners(collection: string): void;
-    /**
-     * Remove all listeners for a specific document (useful for cleanup)
-     */
+    removeCollectionListeners(targetKey: string): void;
     removeDocumentListeners(collection: string, id: string): void;
+    private dispatchChildEvent;
 }
 
 type FilterExpression = {
@@ -179,14 +183,18 @@ declare class Query {
     private localStore;
     constructor(app: EdmaxLabs, collection: string);
     where(expression: FilterExpression): Query;
+    get(): Promise<DocumentSnapshot[]>;
+    update(data: Record<string, any>): Promise<any>;
+    onSnapshot(callback: CollectionListener): () => void;
+    onChildListener(callbacks: ChildListenerCallbacks): () => void;
     private buildFilter;
     private matchesFilter;
     private filterDocuments;
     private getLocalFilteredSnapshots;
-    get(): Promise<DocumentSnapshot[]>;
     private refreshFromRemote;
-    update(data: Record<string, any>): Promise<any>;
-    onSnapshot(callback: CollectionListener): () => void;
+    private subscribeOnlineSnapshot;
+    private subscribeOnlineChildListener;
+    private emitInitialChildEvents;
 }
 
 declare class CollectionRef {
@@ -199,9 +207,14 @@ declare class CollectionRef {
     doc(id: string): DocumentRef;
     get query(): Query;
     get(): Promise<DocumentSnapshot[]>;
-    private refreshFromRemote;
     add(data: Record<string, any>): Promise<DocumentSnapshot | null>;
     onSnapshot(callback: CollectionListener): () => void;
+    onChildListener(callbacks: ChildListenerCallbacks): () => void;
+    private refreshFromRemote;
+    private fetchRemoteSnapshots;
+    private subscribeOnlineSnapshot;
+    private subscribeOnlineChildListener;
+    private emitInitialChildEvents;
 }
 
 declare class Batch {
@@ -327,6 +340,8 @@ declare class Persistence {
     markDeleted(collection: string, id: string, pending?: number): Promise<LocalDoc>;
     enqueueMutation(mutation: Omit<MutationRecord, "updatedAt" | "createdAt" | "retryCount" | "status">): Promise<MutationRecord>;
     getPendingMutations(): Promise<MutationRecord[]>;
+    getFailedMutations(): Promise<MutationRecord[]>;
+    recoverSyncingMutations(): Promise<number>;
     getMutation(mutationId: string): Promise<MutationRecord | null>;
     resetMutation(mutationId: string): Promise<MutationRecord | null>;
     setMutationStatus(mutationId: string, status: MutationRecord["status"], error?: string): Promise<MutationRecord | null>;
@@ -334,6 +349,7 @@ declare class Persistence {
     replaceDocId(collection: string, oldId: string, newId: string): Promise<LocalDoc | null>;
     applyRemoteDoc(collection: string, data: Record<string, any>, revision?: string | number): Promise<LocalDoc | null>;
     applyRemoteDelete(collection: string, id: string): Promise<LocalDoc | null>;
+    reconcileCollectionFromRemote(collection: string, documents: Record<string, any>[]): Promise<void>;
     createLocalId(): string;
     createMutationId(): string;
     clearAll(): Promise<void>;
@@ -344,25 +360,25 @@ declare class RealtimeBridge {
     private app;
     private persistence;
     private store;
-    private collectionUnsubs;
-    private documentUnsubs;
+    private collectionTargets;
+    private documentTargets;
     constructor(app: EdmaxLabs, persistence: Persistence, store: LocalStore);
     private docKey;
-    watchCollection(collection: string, filter?: Record<string, any>): () => void;
+    watchCollection(collection: string, filter: Record<string, any> | undefined, read: () => Promise<DocumentSnapshot[]>): () => void;
     watchDocument(collection: string, id: string): () => void;
-    private emitCurrentDocument;
-    private emitCurrentCollection;
-    private handleRemoteCreateOrUpdate;
-    private handleRemoteDelete;
-    /**
-     * Call this when Socket.IO reconnects or when going online
-     * Replays pending mutations + refreshes all active subscriptions from cache
-     */
+    emitCurrentCollection(collection: string, filter?: Record<string, any>): Promise<DocumentSnapshot[]>;
+    primeCollectionTarget(collection: string, filter: Record<string, any>, snapshots: DocumentSnapshot[]): void;
+    emitCurrentDocument(collection: string, id: string): Promise<DocumentSnapshot | null>;
+    publishLocalChange(collection: string, id: string, source: SnapshotSource): Promise<void>;
     onReconnect(): Promise<void>;
-    /**
-     * Clean up all subscriptions (call from EdmaxLabs destructor if needed)
-     */
     dispose(): void;
+    private handleRemoteCreateOrUpdate;
+    private handleRemoteDelete;
+    private getCurrentDocumentSnapshot;
+    private refreshCollectionTargets;
+    private refreshCollectionTarget;
+    private releaseCollection;
+    private releaseDocument;
 }
 
 declare class SyncEngine {
@@ -374,6 +390,8 @@ declare class SyncEngine {
     private retryTimeout;
     private readonly MAX_RETRIES;
     private readonly BASE_RETRY_DELAY;
+    private readonly handleOnline;
+    private readonly handleVisibilityChange;
     constructor(app: EdmaxLabs, persistence: Persistence, store: LocalStore, realtimeBridge?: RealtimeBridge);
     private onNetworkOnline;
     flush(): Promise<void>;
@@ -504,4 +522,4 @@ declare class ArraySnapshot {
     toMap(): Record<string, any>;
 }
 
-export { ArraySnapshot, Authentication, Credentials, DisplayInfo, DocumentSnapshot, EdmaxLabsConfig, StorageSnapshot, Timestamp, EdmaxLabs as default };
+export { ArraySnapshot, Authentication, ChildChange, ChildListenerCallbacks, ChildListenerContext, Credentials, DisplayInfo, DocumentSnapshot, EdmaxLabsConfig, StorageSnapshot, Timestamp, EdmaxLabs as default };

package/dist/index.d.ts

@@ -114,57 +114,61 @@ declare class DocumentRef {
     set(data: Record<string, any>): Promise<DocumentSnapshot | null>;
     delete(): Promise<boolean>;
     onSnapshot(callback: (snapshot: DocumentSnapshot | null, change: string) => void): () => void;
+    private fetchRemoteSnapshot;
+    private refreshFromRemote;
+}
+
+type SnapshotSource = "initial" | "insert" | "update" | "delete";
+type ChildChangeType = "added" | "modified" | "removed";
+interface ChildChange {
+    type: ChildChangeType;
+    doc: DocumentSnapshot;
+    previousDoc: DocumentSnapshot | null;
+    oldIndex: number;
+    newIndex: number;
+}
+interface CollectionEmission {
+    snapshots: DocumentSnapshot[];
+    source: SnapshotSource;
+    changedDocId?: string;
+    fromCache?: boolean;
+    childChanges?: ChildChange[];
+}
+interface ChildListenerContext {
+    snapshots: DocumentSnapshot[];
+    source: SnapshotSource;
+    changedDocId?: string;
+    fromCache: boolean;
+    oldIndex: number;
+    newIndex: number;
+    previousDoc: DocumentSnapshot | null;
+}
+interface ChildListenerCallbacks {
+    onChildAdded?: (snapshot: DocumentSnapshot, context: ChildListenerContext) => void;
+    onChildUpdated?: (snapshot: DocumentSnapshot, context: ChildListenerContext) => void;
+    onChildRemoved?: (snapshot: DocumentSnapshot, context: ChildListenerContext) => void;
 }
 
 type DocListener = (snapshot: DocumentSnapshot | null, change: string) => void;
-/**
- * For collection listeners we pass:
- * - snapshots: all current documents in the collection
- * - change: what triggered this emission
- * - changedDocId?: which specific document changed (useful for granular updates)
- */
 type CollectionListener = (snapshots: DocumentSnapshot[], change: string, changedDocId?: string) => void;
 declare class LocalStore {
     private documentListeners;
     private collectionListeners;
+    private childListeners;
     private docKey;
     subscribeToDocument(collection: string, id: string, callback: DocListener): () => void;
-    subscribeToCollection(collection: string, callback: CollectionListener): () => void;
-    /**
-     * Notify all listeners for a specific document
-     */
+    subscribeToCollection(targetKey: string, callback: CollectionListener): () => void;
+    subscribeToChildEvents(targetKey: string, callbacks: ChildListenerCallbacks): () => void;
     emitDocument(collection: string, id: string, snapshot: DocumentSnapshot | null, change: string): void;
-    /**
-     * Notify all listeners for a collection.
-     * This is the most important fix — collection listeners now receive the full list.
-     */
-    emitCollection(collection: string, snapshots: DocumentSnapshot[], // ← Changed from single snapshot
-    change: string, changedDocId?: string): void;
-    /**
-     * OPTIMIZED: Notify collection listeners that something changed, without fetching full collection.
-     * Listeners can call getCollectionSnapshots() themselves if they need the full list.
-     * This avoids expensive collection queries after every single mutation.
-     */
-    notifyCollectionChanged(collection: string, changedDocId: string, change: string): void;
-    /**
-     * Clear all listeners (useful for testing or when persistence is disabled)
-     */
+    emitCollection(targetKey: string, emission: CollectionEmission): void;
     clearAllListeners(): void;
-    /**
-     * Get current listener count (for debugging / dev tools)
-     */
     get listenerCount(): {
         documents: number;
         collections: number;
     };
-    /**
-     * Remove all listeners for a specific collection (useful for cleanup)
-     */
-    removeCollectionListeners(collection: string): void;
-    /**
-     * Remove all listeners for a specific document (useful for cleanup)
-     */
+    removeCollectionListeners(targetKey: string): void;
     removeDocumentListeners(collection: string, id: string): void;
+    private dispatchChildEvent;
 }
 
 type FilterExpression = {
@@ -179,14 +183,18 @@ declare class Query {
     private localStore;
     constructor(app: EdmaxLabs, collection: string);
     where(expression: FilterExpression): Query;
+    get(): Promise<DocumentSnapshot[]>;
+    update(data: Record<string, any>): Promise<any>;
+    onSnapshot(callback: CollectionListener): () => void;
+    onChildListener(callbacks: ChildListenerCallbacks): () => void;
     private buildFilter;
     private matchesFilter;
     private filterDocuments;
     private getLocalFilteredSnapshots;
-    get(): Promise<DocumentSnapshot[]>;
     private refreshFromRemote;
-    update(data: Record<string, any>): Promise<any>;
-    onSnapshot(callback: CollectionListener): () => void;
+    private subscribeOnlineSnapshot;
+    private subscribeOnlineChildListener;
+    private emitInitialChildEvents;
 }
 
 declare class CollectionRef {
@@ -199,9 +207,14 @@ declare class CollectionRef {
     doc(id: string): DocumentRef;
     get query(): Query;
     get(): Promise<DocumentSnapshot[]>;
-    private refreshFromRemote;
     add(data: Record<string, any>): Promise<DocumentSnapshot | null>;
     onSnapshot(callback: CollectionListener): () => void;
+    onChildListener(callbacks: ChildListenerCallbacks): () => void;
+    private refreshFromRemote;
+    private fetchRemoteSnapshots;
+    private subscribeOnlineSnapshot;
+    private subscribeOnlineChildListener;
+    private emitInitialChildEvents;
 }
 
 declare class Batch {
@@ -327,6 +340,8 @@ declare class Persistence {
     markDeleted(collection: string, id: string, pending?: number): Promise<LocalDoc>;
     enqueueMutation(mutation: Omit<MutationRecord, "updatedAt" | "createdAt" | "retryCount" | "status">): Promise<MutationRecord>;
     getPendingMutations(): Promise<MutationRecord[]>;
+    getFailedMutations(): Promise<MutationRecord[]>;
+    recoverSyncingMutations(): Promise<number>;
     getMutation(mutationId: string): Promise<MutationRecord | null>;
     resetMutation(mutationId: string): Promise<MutationRecord | null>;
     setMutationStatus(mutationId: string, status: MutationRecord["status"], error?: string): Promise<MutationRecord | null>;
@@ -334,6 +349,7 @@ declare class Persistence {
     replaceDocId(collection: string, oldId: string, newId: string): Promise<LocalDoc | null>;
     applyRemoteDoc(collection: string, data: Record<string, any>, revision?: string | number): Promise<LocalDoc | null>;
     applyRemoteDelete(collection: string, id: string): Promise<LocalDoc | null>;
+    reconcileCollectionFromRemote(collection: string, documents: Record<string, any>[]): Promise<void>;
     createLocalId(): string;
     createMutationId(): string;
     clearAll(): Promise<void>;
@@ -344,25 +360,25 @@ declare class RealtimeBridge {
     private app;
     private persistence;
     private store;
-    private collectionUnsubs;
-    private documentUnsubs;
+    private collectionTargets;
+    private documentTargets;
     constructor(app: EdmaxLabs, persistence: Persistence, store: LocalStore);
     private docKey;
-    watchCollection(collection: string, filter?: Record<string, any>): () => void;
+    watchCollection(collection: string, filter: Record<string, any> | undefined, read: () => Promise<DocumentSnapshot[]>): () => void;
     watchDocument(collection: string, id: string): () => void;
-    private emitCurrentDocument;
-    private emitCurrentCollection;
-    private handleRemoteCreateOrUpdate;
-    private handleRemoteDelete;
-    /**
-     * Call this when Socket.IO reconnects or when going online
-     * Replays pending mutations + refreshes all active subscriptions from cache
-     */
+    emitCurrentCollection(collection: string, filter?: Record<string, any>): Promise<DocumentSnapshot[]>;
+    primeCollectionTarget(collection: string, filter: Record<string, any>, snapshots: DocumentSnapshot[]): void;
+    emitCurrentDocument(collection: string, id: string): Promise<DocumentSnapshot | null>;
+    publishLocalChange(collection: string, id: string, source: SnapshotSource): Promise<void>;
     onReconnect(): Promise<void>;
-    /**
-     * Clean up all subscriptions (call from EdmaxLabs destructor if needed)
-     */
     dispose(): void;
+    private handleRemoteCreateOrUpdate;
+    private handleRemoteDelete;
+    private getCurrentDocumentSnapshot;
+    private refreshCollectionTargets;
+    private refreshCollectionTarget;
+    private releaseCollection;
+    private releaseDocument;
 }
 
 declare class SyncEngine {
@@ -374,6 +390,8 @@ declare class SyncEngine {
     private retryTimeout;
     private readonly MAX_RETRIES;
     private readonly BASE_RETRY_DELAY;
+    private readonly handleOnline;
+    private readonly handleVisibilityChange;
     constructor(app: EdmaxLabs, persistence: Persistence, store: LocalStore, realtimeBridge?: RealtimeBridge);
     private onNetworkOnline;
     flush(): Promise<void>;
@@ -504,4 +522,4 @@ declare class ArraySnapshot {
     toMap(): Record<string, any>;
 }
 
-export { ArraySnapshot, Authentication, Credentials, DisplayInfo, DocumentSnapshot, EdmaxLabsConfig, StorageSnapshot, Timestamp, EdmaxLabs as default };
+export { ArraySnapshot, Authentication, ChildChange, ChildListenerCallbacks, ChildListenerContext, Credentials, DisplayInfo, DocumentSnapshot, EdmaxLabsConfig, StorageSnapshot, Timestamp, EdmaxLabs as default };