edmaxlabs-core 1.3.6 → 1.4.7

package/dist/index.d.cts

@@ -99,36 +99,6 @@ declare class DocumentSnapshot {
     toMap(): Record<string, any>;
 }
 
-declare class ArraySnapshot {
-    id?: string;
-    data: Record<string, any>;
-    dt: Timestamp;
-    private constructor();
-    static fromMap(map: Record<string, any>): ArraySnapshot;
-    toMap(): Record<string, any>;
-}
-
-declare class Array {
-    private app;
-    readonly collection: string;
-    readonly key: string;
-    readonly docID: string;
-    private persistence;
-    private syncEngine;
-    private localStore;
-    constructor(app: EdmaxLabs, collection: string, key: string, id: string);
-    /**
-     * Get current array elements (offline-first: prefers local cache)
-     */
-    show(): Promise<ArraySnapshot[]>;
-    private refreshFromRemote;
-    push(data: any, id?: string): Promise<ArraySnapshot | null>;
-    update(position: number, data: any, id?: string): Promise<ArraySnapshot | null>;
-    insert(position: number, data: any, id?: string): Promise<ArraySnapshot | null>;
-    get(position: number): Promise<ArraySnapshot | null>;
-    remove(position: number): Promise<ArraySnapshot | null>;
-}
-
 declare class DocumentRef {
     private app;
     readonly collection: string;
@@ -138,23 +108,20 @@ declare class DocumentRef {
     private localStore;
     constructor(app: EdmaxLabs, collection: string, id: string);
     get(): Promise<DocumentSnapshot | null>;
-    private refreshFromRemote;
     set(data: Record<string, any>): Promise<DocumentSnapshot | null>;
     update(data: Record<string, any>): Promise<DocumentSnapshot | null>;
     delete(): Promise<boolean>;
-    array(key: string): Array;
     onSnapshot(callback: (snapshot: DocumentSnapshot | null, change: string) => void): () => void;
 }
 
-type ChangeType = "init" | "local_create" | "local_update" | "local_delete" | "remote_create" | "remote_update" | "remote_delete" | "sync" | "error";
-type DocListener = (snapshot: DocumentSnapshot | null, change: ChangeType) => 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: ChangeType, changedDocId?: string) => void;
+type CollectionListener = (snapshots: DocumentSnapshot[], change: string, changedDocId?: string) => void;
 declare class LocalStore {
     private documentListeners;
     private collectionListeners;
@@ -164,13 +131,19 @@ declare class LocalStore {
     /**
      * Notify all listeners for a specific document
      */
-    emitDocument(collection: string, id: string, snapshot: DocumentSnapshot | null, change: ChangeType): 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: ChangeType, changedDocId?: string): void;
+    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)
      */
@@ -182,6 +155,14 @@ declare class LocalStore {
         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)
+     */
+    removeDocumentListeners(collection: string, id: string): void;
 }
 
 type FilterExpression = {
@@ -193,9 +174,13 @@ declare class Query {
     private app;
     private collection;
     private filter;
+    private localStore;
     constructor(app: EdmaxLabs, collection: string);
     where(expression: FilterExpression): Query;
     private buildFilter;
+    private matchesFilter;
+    private filterDocuments;
+    private getLocalFilteredSnapshots;
     get(): Promise<DocumentSnapshot[]>;
     private refreshFromRemote;
     update(data: Record<string, any>): Promise<any>;
@@ -222,6 +207,7 @@ declare class Batch {
     private ops;
     constructor(app: EdmaxLabs);
     set(docRef: DocumentRef, data: any): Batch;
+    create(docRef: DocumentRef, data: any): Batch;
     update(docRef: DocumentRef, data: any): Batch;
     delete(docRef: DocumentRef): Batch;
     commit(): Promise<any>;
@@ -277,7 +263,6 @@ declare class Realtime {
      * Low-level document subscription (used by RealtimeBridge)
      */
     subscribeToDocumentRaw(collection: string, id: string, callback: (payload: any, change: string) => void): () => void;
-    private normalizePayload;
     private registerSubscription;
     private resubscribeAll;
     private cleanupSubscription;
@@ -307,7 +292,7 @@ interface LocalDoc {
     revision?: string | number;
 }
 
-type MutationType = "create" | "update" | "delete" | "array_push" | "array_update" | "array_insert" | "array_remove";
+type MutationType = "insert" | "update" | "delete" | "array_push" | "array_update" | "array_insert" | "array_remove";
 type MutationStatus = "pending" | "syncing" | "failed";
 interface MutationRecord {
     mutationId: string;
@@ -325,7 +310,8 @@ interface MutationRecord {
 
 declare class Persistence {
     private dbPromise;
-    constructor();
+    private appName;
+    constructor(appName?: string);
     private docKey;
     private now;
     private getDb;
@@ -339,6 +325,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[]>;
+    getMutation(mutationId: string): Promise<MutationRecord | null>;
+    resetMutation(mutationId: string): Promise<MutationRecord | null>;
     setMutationStatus(mutationId: string, status: MutationRecord["status"], error?: string): Promise<MutationRecord | null>;
     removeMutation(mutationId: string): Promise<void>;
     replaceDocId(collection: string, oldId: string, newId: string): Promise<LocalDoc | null>;
@@ -392,6 +380,25 @@ declare class SyncEngine {
     private syncDelete;
     private scheduleRetry;
     forceSync(): Promise<void>;
+    /**
+     * Get all failed mutations for error handling/UI
+     * Returns mutations that exceeded MAX_RETRIES
+     */
+    getFailedMutations(): Promise<any[]>;
+    /**
+     * Retry a specific failed mutation by resetting its retry count
+     * Useful for user-initiated recovery after fixing network/server issues
+     */
+    retryMutation(mutationId: string): Promise<boolean>;
+    /**
+     * Retry all failed mutations at once
+     */
+    retryAllFailed(): Promise<number>;
+    /**
+     * Remove a mutation entirely (user acknowledges the failure and wants to discard it)
+     * Be careful: this means the operation will never sync to the server
+     */
+    removeMutation(mutationId: string): Promise<boolean>;
     dispose(): void;
 }
 
@@ -424,6 +431,7 @@ declare class Storage {
 interface EdmaxLabsConfig {
     token: string;
     project: string;
+    app_name?: string;
     persistence?: boolean;
     default_bucket?: string;
 }
@@ -448,6 +456,15 @@ declare class EdmaxLabs {
     get getFunctions(): Functions;
     get getStorage(): Storage;
     get getAuthentication(): Authentication;
+    /** Check if offline features are enabled */
+    get isOfflineEnabled(): boolean;
+    /** Get current storage usage (approximate) */
+    getStorageUsage(): Promise<{
+        used: number;
+        available: number;
+    } | null>;
+    /** Clear all cached data (nuclear option) */
+    clearCache(): Promise<void>;
     /** New clean offline namespace - highly recommended */
     offline(): {
         readonly persistence: Persistence | null;
@@ -455,7 +472,25 @@ declare class EdmaxLabs {
         readonly syncEngine: SyncEngine | null;
         readonly realtimeBridge: RealtimeBridge | null;
         readonly enabled: boolean;
+        readonly clearListeners: () => void | undefined;
+        readonly getListenerCount: () => {
+            documents: number;
+            collections: number;
+        };
     };
+    /**
+     * Manually trigger sync of pending mutations
+     * Useful for progressive sync or after network restoration
+     */
+    sync(): Promise<void>;
+    /**
+     * Get mutations that failed to sync (for error UI)
+     */
+    getFailedMutations(): Promise<any[]>;
+    /**
+     * Retry all failed mutations
+     */
+    retrySync(): Promise<number>;
     getConfig(): EdmaxLabsConfig;
     getBaseUrl(): string;
     getSocketUrl(): string;
@@ -464,4 +499,13 @@ declare class EdmaxLabs {
     dispose(): void;
 }
 
+declare class ArraySnapshot {
+    id?: string;
+    data: Record<string, any>;
+    dt: Timestamp;
+    private constructor();
+    static fromMap(map: Record<string, any>): ArraySnapshot;
+    toMap(): Record<string, any>;
+}
+
 export { ArraySnapshot, Authentication, Credentials, DisplayInfo, DocumentSnapshot, EdmaxLabsConfig, StorageSnapshot, Timestamp, EdmaxLabs as default };

package/dist/index.d.ts

@@ -99,36 +99,6 @@ declare class DocumentSnapshot {
     toMap(): Record<string, any>;
 }
 
-declare class ArraySnapshot {
-    id?: string;
-    data: Record<string, any>;
-    dt: Timestamp;
-    private constructor();
-    static fromMap(map: Record<string, any>): ArraySnapshot;
-    toMap(): Record<string, any>;
-}
-
-declare class Array {
-    private app;
-    readonly collection: string;
-    readonly key: string;
-    readonly docID: string;
-    private persistence;
-    private syncEngine;
-    private localStore;
-    constructor(app: EdmaxLabs, collection: string, key: string, id: string);
-    /**
-     * Get current array elements (offline-first: prefers local cache)
-     */
-    show(): Promise<ArraySnapshot[]>;
-    private refreshFromRemote;
-    push(data: any, id?: string): Promise<ArraySnapshot | null>;
-    update(position: number, data: any, id?: string): Promise<ArraySnapshot | null>;
-    insert(position: number, data: any, id?: string): Promise<ArraySnapshot | null>;
-    get(position: number): Promise<ArraySnapshot | null>;
-    remove(position: number): Promise<ArraySnapshot | null>;
-}
-
 declare class DocumentRef {
     private app;
     readonly collection: string;
@@ -138,23 +108,20 @@ declare class DocumentRef {
     private localStore;
     constructor(app: EdmaxLabs, collection: string, id: string);
     get(): Promise<DocumentSnapshot | null>;
-    private refreshFromRemote;
     set(data: Record<string, any>): Promise<DocumentSnapshot | null>;
     update(data: Record<string, any>): Promise<DocumentSnapshot | null>;
     delete(): Promise<boolean>;
-    array(key: string): Array;
     onSnapshot(callback: (snapshot: DocumentSnapshot | null, change: string) => void): () => void;
 }
 
-type ChangeType = "init" | "local_create" | "local_update" | "local_delete" | "remote_create" | "remote_update" | "remote_delete" | "sync" | "error";
-type DocListener = (snapshot: DocumentSnapshot | null, change: ChangeType) => 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: ChangeType, changedDocId?: string) => void;
+type CollectionListener = (snapshots: DocumentSnapshot[], change: string, changedDocId?: string) => void;
 declare class LocalStore {
     private documentListeners;
     private collectionListeners;
@@ -164,13 +131,19 @@ declare class LocalStore {
     /**
      * Notify all listeners for a specific document
      */
-    emitDocument(collection: string, id: string, snapshot: DocumentSnapshot | null, change: ChangeType): 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: ChangeType, changedDocId?: string): void;
+    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)
      */
@@ -182,6 +155,14 @@ declare class LocalStore {
         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)
+     */
+    removeDocumentListeners(collection: string, id: string): void;
 }
 
 type FilterExpression = {
@@ -193,9 +174,13 @@ declare class Query {
     private app;
     private collection;
     private filter;
+    private localStore;
     constructor(app: EdmaxLabs, collection: string);
     where(expression: FilterExpression): Query;
     private buildFilter;
+    private matchesFilter;
+    private filterDocuments;
+    private getLocalFilteredSnapshots;
     get(): Promise<DocumentSnapshot[]>;
     private refreshFromRemote;
     update(data: Record<string, any>): Promise<any>;
@@ -222,6 +207,7 @@ declare class Batch {
     private ops;
     constructor(app: EdmaxLabs);
     set(docRef: DocumentRef, data: any): Batch;
+    create(docRef: DocumentRef, data: any): Batch;
     update(docRef: DocumentRef, data: any): Batch;
     delete(docRef: DocumentRef): Batch;
     commit(): Promise<any>;
@@ -277,7 +263,6 @@ declare class Realtime {
      * Low-level document subscription (used by RealtimeBridge)
      */
     subscribeToDocumentRaw(collection: string, id: string, callback: (payload: any, change: string) => void): () => void;
-    private normalizePayload;
     private registerSubscription;
     private resubscribeAll;
     private cleanupSubscription;
@@ -307,7 +292,7 @@ interface LocalDoc {
     revision?: string | number;
 }
 
-type MutationType = "create" | "update" | "delete" | "array_push" | "array_update" | "array_insert" | "array_remove";
+type MutationType = "insert" | "update" | "delete" | "array_push" | "array_update" | "array_insert" | "array_remove";
 type MutationStatus = "pending" | "syncing" | "failed";
 interface MutationRecord {
     mutationId: string;
@@ -325,7 +310,8 @@ interface MutationRecord {
 
 declare class Persistence {
     private dbPromise;
-    constructor();
+    private appName;
+    constructor(appName?: string);
     private docKey;
     private now;
     private getDb;
@@ -339,6 +325,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[]>;
+    getMutation(mutationId: string): Promise<MutationRecord | null>;
+    resetMutation(mutationId: string): Promise<MutationRecord | null>;
     setMutationStatus(mutationId: string, status: MutationRecord["status"], error?: string): Promise<MutationRecord | null>;
     removeMutation(mutationId: string): Promise<void>;
     replaceDocId(collection: string, oldId: string, newId: string): Promise<LocalDoc | null>;
@@ -392,6 +380,25 @@ declare class SyncEngine {
     private syncDelete;
     private scheduleRetry;
     forceSync(): Promise<void>;
+    /**
+     * Get all failed mutations for error handling/UI
+     * Returns mutations that exceeded MAX_RETRIES
+     */
+    getFailedMutations(): Promise<any[]>;
+    /**
+     * Retry a specific failed mutation by resetting its retry count
+     * Useful for user-initiated recovery after fixing network/server issues
+     */
+    retryMutation(mutationId: string): Promise<boolean>;
+    /**
+     * Retry all failed mutations at once
+     */
+    retryAllFailed(): Promise<number>;
+    /**
+     * Remove a mutation entirely (user acknowledges the failure and wants to discard it)
+     * Be careful: this means the operation will never sync to the server
+     */
+    removeMutation(mutationId: string): Promise<boolean>;
     dispose(): void;
 }
 
@@ -424,6 +431,7 @@ declare class Storage {
 interface EdmaxLabsConfig {
     token: string;
     project: string;
+    app_name?: string;
     persistence?: boolean;
     default_bucket?: string;
 }
@@ -448,6 +456,15 @@ declare class EdmaxLabs {
     get getFunctions(): Functions;
     get getStorage(): Storage;
     get getAuthentication(): Authentication;
+    /** Check if offline features are enabled */
+    get isOfflineEnabled(): boolean;
+    /** Get current storage usage (approximate) */
+    getStorageUsage(): Promise<{
+        used: number;
+        available: number;
+    } | null>;
+    /** Clear all cached data (nuclear option) */
+    clearCache(): Promise<void>;
     /** New clean offline namespace - highly recommended */
     offline(): {
         readonly persistence: Persistence | null;
@@ -455,7 +472,25 @@ declare class EdmaxLabs {
         readonly syncEngine: SyncEngine | null;
         readonly realtimeBridge: RealtimeBridge | null;
         readonly enabled: boolean;
+        readonly clearListeners: () => void | undefined;
+        readonly getListenerCount: () => {
+            documents: number;
+            collections: number;
+        };
     };
+    /**
+     * Manually trigger sync of pending mutations
+     * Useful for progressive sync or after network restoration
+     */
+    sync(): Promise<void>;
+    /**
+     * Get mutations that failed to sync (for error UI)
+     */
+    getFailedMutations(): Promise<any[]>;
+    /**
+     * Retry all failed mutations
+     */
+    retrySync(): Promise<number>;
     getConfig(): EdmaxLabsConfig;
     getBaseUrl(): string;
     getSocketUrl(): string;
@@ -464,4 +499,13 @@ declare class EdmaxLabs {
     dispose(): void;
 }
 
+declare class ArraySnapshot {
+    id?: string;
+    data: Record<string, any>;
+    dt: Timestamp;
+    private constructor();
+    static fromMap(map: Record<string, any>): ArraySnapshot;
+    toMap(): Record<string, any>;
+}
+
 export { ArraySnapshot, Authentication, Credentials, DisplayInfo, DocumentSnapshot, EdmaxLabsConfig, StorageSnapshot, Timestamp, EdmaxLabs as default };