edmaxlabs-core 1.3.4 → 1.3.6

package/dist/index.d.cts

@@ -1,7 +1,3 @@
-import * as idb from 'idb';
-import * as _socket_io_component_emitter from '@socket.io/component-emitter';
-import { Socket } from 'socket.io-client';
-
 interface TimestampData {
     seconds: number;
     nanoseconds: number;
@@ -95,6 +91,14 @@ declare class Authentication {
     }>;
 }
 
+declare class DocumentSnapshot {
+    id: string;
+    data: Record<string, any>;
+    private constructor();
+    static fromMap(map: Record<string, any>): DocumentSnapshot;
+    toMap(): Record<string, any>;
+}
+
 declare class ArraySnapshot {
     id?: string;
     data: Record<string, any>;
@@ -105,12 +109,19 @@ declare class ArraySnapshot {
 }
 
 declare class Array {
-    db: EdmaxLabs;
-    collection: string;
-    key: string;
-    docID: string;
-    constructor(db: EdmaxLabs, collection: string, key: string, id: string);
+    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>;
@@ -118,36 +129,59 @@ declare class Array {
     remove(position: number): Promise<ArraySnapshot | null>;
 }
 
-declare class DocumentSnapshot {
-    id: string;
-    data: Record<string, any>;
-    private constructor();
-    static fromMap(map: Record<string, any>): DocumentSnapshot;
-    toMap(): Record<string, any>;
-}
-
 declare class DocumentRef {
-    db: EdmaxLabs;
-    collection: string;
-    id: string;
-    constructor(db: EdmaxLabs, collection: string, id: string);
+    private app;
+    readonly collection: string;
+    readonly id: string;
+    private persistence;
+    private syncEngine;
+    private localStore;
+    constructor(app: EdmaxLabs, collection: string, id: string);
     get(): Promise<DocumentSnapshot | null>;
-    set(data: any): Promise<DocumentSnapshot | null>;
-    update(data: any): Promise<DocumentSnapshot | null>;
-    delete(): 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;
-    /**
-     * Realtime listener for a single document
-     */
-    onSnapshot(callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+    onSnapshot(callback: (snapshot: DocumentSnapshot | null, change: string) => void): () => void;
 }
 
-declare class CollectionRef$1 {
-    db: EdmaxLabs;
-    constructor(db: EdmaxLabs);
-    getIDB: (collection: string) => Promise<idb.IDBPDatabase<unknown>>;
-    syncPendingWrite(id: string, collection?: string): Promise<boolean | undefined>;
-    syncPendingWrites(collection: string): Promise<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;
+/**
+ * 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;
+declare class LocalStore {
+    private documentListeners;
+    private collectionListeners;
+    private docKey;
+    subscribeToDocument(collection: string, id: string, callback: DocListener): () => void;
+    subscribeToCollection(collection: string, callback: CollectionListener): () => void;
+    /**
+     * Notify all listeners for a specific document
+     */
+    emitDocument(collection: string, id: string, snapshot: DocumentSnapshot | null, change: ChangeType): 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;
+    /**
+     * Clear all listeners (useful for testing or when persistence is disabled)
+     */
+    clearAllListeners(): void;
+    /**
+     * Get current listener count (for debugging / dev tools)
+     */
+    get listenerCount(): {
+        documents: number;
+        collections: number;
+    };
 }
 
 type FilterExpression = {
@@ -156,48 +190,53 @@ type FilterExpression = {
     value: any;
 };
 declare class Query {
-    db: EdmaxLabs;
-    collection: string;
+    private app;
+    private collection;
     private filter;
-    constructor(db: EdmaxLabs, collection: string);
-    where(expression: FilterExpression): this;
+    constructor(app: EdmaxLabs, collection: string);
+    where(expression: FilterExpression): Query;
     private buildFilter;
     get(): Promise<DocumentSnapshot[]>;
-    update(): Promise<DocumentSnapshot[]>;
-    onSnapshot(callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+    private refreshFromRemote;
+    update(data: Record<string, any>): Promise<any>;
+    onSnapshot(callback: CollectionListener): () => void;
 }
 
 declare class CollectionRef {
-    db: EdmaxLabs;
-    collection: string;
-    persistence: CollectionRef$1;
-    constructor(db: EdmaxLabs, collection: string);
+    private app;
+    readonly collection: string;
+    private persistence;
+    private syncEngine;
+    private localStore;
+    constructor(app: EdmaxLabs, collection: string);
     doc(id: string): DocumentRef;
     get query(): Query;
     get(): Promise<DocumentSnapshot[]>;
-    add(data: any): Promise<DocumentSnapshot | null>;
-    /**
-     * Realtime listener for entire collection
-     */
-    onSnapshot(callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+    private refreshFromRemote;
+    add(data: Record<string, any>): Promise<DocumentSnapshot | null>;
+    onSnapshot(callback: CollectionListener): () => void;
 }
 
 declare class Batch {
-    app: EdmaxLabs;
-    ops: any[];
+    private app;
+    private ops;
     constructor(app: EdmaxLabs);
-    set(docRef: DocumentRef, data: any): this;
-    update(docRef: DocumentRef, data: any): this;
-    delete(docRef: DocumentRef): this;
+    set(docRef: DocumentRef, data: any): Batch;
+    update(docRef: DocumentRef, data: any): Batch;
+    delete(docRef: DocumentRef): Batch;
     commit(): Promise<any>;
 }
 
 declare class Database {
-    app: EdmaxLabs;
+    private app;
     constructor(app: EdmaxLabs);
     collection(name: string): CollectionRef;
     doc(path: string): DocumentRef;
     batch(): Batch;
+    /**
+     * Server-side transaction (unchanged, but improved error handling)
+     * This remains online-only for now — offline transactions are complex and can be added later as opt-in.
+     */
     runTransaction(transactionFn: (tx: {
         ops: any[];
         get: (docRef: DocumentRef) => Promise<any>;
@@ -205,25 +244,45 @@ declare class Database {
         update: (docRef: DocumentRef, data: any) => void;
         delete: (docRef: DocumentRef) => void;
     }) => Promise<void>): Promise<any>;
+    /**
+     * Returns true if persistence is enabled and we are currently offline
+     */
+    private get shouldUseOffline();
+    /**
+     * Returns the SyncEngine if persistence is enabled
+     */
+    private get syncEngine();
+    /**
+     * Returns the RealtimeBridge if persistence is enabled
+     */
+    private get realtimeBridge();
 }
 
 declare class Realtime {
-    db: EdmaxLabs;
-    socket: Socket | null;
-    events: string[];
-    constructor(db: EdmaxLabs);
-    connect(): Socket<_socket_io_component_emitter.DefaultEventsMap, _socket_io_component_emitter.DefaultEventsMap>;
+    private app;
+    private socket;
+    private readonly events;
+    private subscriptions;
+    constructor(app: EdmaxLabs);
+    private connect;
+    private setupSocketListeners;
     on(event: string, cb: (...args: any[]) => void): void;
     off(event: string, cb?: (...args: any[]) => void): void;
     emit(event: string, data: any): void;
     /**
-     * Realtime listener for entire collection
+     * Low-level collection subscription (used by RealtimeBridge)
      */
-    subscribeToCollection(collection: string, callback: (snapshot: DocumentSnapshot, change: string) => void, filter?: Record<string, any>): () => void;
+    subscribeToCollectionRaw(collection: string, callback: (payload: any, change: string) => void, filter?: Record<string, any>): () => void;
     /**
-     * Realtime listener for a single document
+     * Low-level document subscription (used by RealtimeBridge)
      */
-    subscribeToDocument(collection: string, id: string, callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+    subscribeToDocumentRaw(collection: string, id: string, callback: (payload: any, change: string) => void): () => void;
+    private normalizePayload;
+    private registerSubscription;
+    private resubscribeAll;
+    private cleanupSubscription;
+    disconnect(): void;
+    dispose(): void;
 }
 
 declare class Functions {
@@ -232,10 +291,108 @@ declare class Functions {
     call(functionName: string, data?: Record<string, any>): Promise<any>;
 }
 
-declare class Hosting {
-    app: EdmaxLabs;
-    constructor(app: EdmaxLabs);
-    createSubdomain(name: string): Promise<any>;
+type LocalDocStatus = "synced" | "pending" | "failed";
+interface LocalDoc {
+    key: string;
+    collection: string;
+    id: string;
+    data: Record<string, any>;
+    exists: boolean;
+    pending: number;
+    status: LocalDocStatus;
+    localOnly: boolean;
+    deleted: boolean;
+    updatedAt: number;
+    lastSyncedAt?: number;
+    revision?: string | number;
+}
+
+type MutationType = "create" | "update" | "delete" | "array_push" | "array_update" | "array_insert" | "array_remove";
+type MutationStatus = "pending" | "syncing" | "failed";
+interface MutationRecord {
+    mutationId: string;
+    collection: string;
+    documentId: string;
+    type: MutationType;
+    payload: Record<string, any> | null;
+    status: MutationStatus;
+    createdAt: number;
+    updatedAt: number;
+    retryCount: number;
+    error?: string;
+    baseRevision?: string | number;
+}
+
+declare class Persistence {
+    private dbPromise;
+    constructor();
+    private docKey;
+    private now;
+    private getDb;
+    getDoc(collection: string, id: string): Promise<LocalDoc | null>;
+    getDocSnapshot(collection: string, id: string): Promise<DocumentSnapshot | null>;
+    getCollection(collection: string): Promise<LocalDoc[]>;
+    getCollectionSnapshots(collection: string): Promise<DocumentSnapshot[]>;
+    upsertDoc(input: Omit<LocalDoc, "key" | "updatedAt"> & {
+        updatedAt?: number;
+    }): Promise<LocalDoc>;
+    markDeleted(collection: string, id: string, pending?: number): Promise<LocalDoc>;
+    enqueueMutation(mutation: Omit<MutationRecord, "updatedAt" | "createdAt" | "retryCount" | "status">): Promise<MutationRecord>;
+    getPendingMutations(): Promise<MutationRecord[]>;
+    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>;
+    applyRemoteDoc(collection: string, data: Record<string, any>, revision?: string | number): Promise<LocalDoc | null>;
+    applyRemoteDelete(collection: string, id: string): Promise<LocalDoc | null>;
+    createLocalId(): string;
+    createMutationId(): string;
+    clearAll(): Promise<void>;
+    getStorageUsage(): Promise<number>;
+}
+
+declare class RealtimeBridge {
+    private app;
+    private persistence;
+    private store;
+    private collectionUnsubs;
+    private documentUnsubs;
+    constructor(app: EdmaxLabs, persistence: Persistence, store: LocalStore);
+    private docKey;
+    watchCollection(collection: string, filter?: Record<string, any>): () => 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
+     */
+    onReconnect(): Promise<void>;
+    /**
+     * Clean up all subscriptions (call from EdmaxLabs destructor if needed)
+     */
+    dispose(): void;
+}
+
+declare class SyncEngine {
+    private app;
+    private persistence;
+    private store;
+    private realtimeBridge;
+    private syncing;
+    private retryTimeout;
+    private readonly MAX_RETRIES;
+    private readonly BASE_RETRY_DELAY;
+    constructor(app: EdmaxLabs, persistence: Persistence, store: LocalStore, realtimeBridge?: RealtimeBridge);
+    private onNetworkOnline;
+    flush(): Promise<void>;
+    private syncCreate;
+    private syncUpdate;
+    private syncDelete;
+    private scheduleRetry;
+    forceSync(): Promise<void>;
+    dispose(): void;
 }
 
 declare class StorageSnapshot {
@@ -247,8 +404,8 @@ declare class StorageSnapshot {
 }
 
 declare class StorageRef {
-    db: EdmaxLabs;
-    constructor(db: EdmaxLabs);
+    app: EdmaxLabs;
+    constructor(app: EdmaxLabs);
     get(id: string): Promise<StorageSnapshot | null | undefined>;
     getMeta(id: string): Promise<StorageSnapshot | null | undefined>;
     upload(srcFile: File): Promise<StorageSnapshot | null | undefined>;
@@ -267,31 +424,44 @@ declare class Storage {
 interface EdmaxLabsConfig {
     token: string;
     project: string;
+    persistence?: boolean;
+    default_bucket?: string;
 }
 declare class EdmaxLabs {
     static instance: EdmaxLabs | null;
     private baseUrl;
     private socketUrl;
-    private auth;
     private _db;
+    private _realtime;
     private _hosting;
-    private realtime;
+    private _config;
     private persistence;
-    private persistence_worker;
-    constructor({ token, project }: EdmaxLabsConfig);
-    static allowPersistence(enable: boolean): void;
+    private localStore;
+    private syncEngine;
+    private realtimeBridge;
+    constructor(config: EdmaxLabsConfig);
+    /** Recommended for most React apps (creates fresh instance) */
+    static create(config: EdmaxLabsConfig): EdmaxLabs;
+    /** Firebase-style singleton (kept for backward compatibility) */
     static initialize(config: EdmaxLabsConfig): EdmaxLabs;
-    get getPersistence(): boolean;
-    get getAuth(): Record<string, any>;
-    get getBaseUrl(): string;
-    get getSocketUrl(): string;
-    get database(): Database;
-    get storage(): Storage;
-    get hosting(): Hosting;
-    get functions(): Functions;
-    get rtdb(): Realtime;
-    sync(id: string, collection?: string): Promise<boolean | undefined>;
-    get authentication(): Authentication;
+    get getDatabase(): Database;
+    get getFunctions(): Functions;
+    get getStorage(): Storage;
+    get getAuthentication(): Authentication;
+    /** New clean offline namespace - highly recommended */
+    offline(): {
+        readonly persistence: Persistence | null;
+        readonly localStore: LocalStore | null;
+        readonly syncEngine: SyncEngine | null;
+        readonly realtimeBridge: RealtimeBridge | null;
+        readonly enabled: boolean;
+    };
+    getConfig(): EdmaxLabsConfig;
+    getBaseUrl(): string;
+    getSocketUrl(): string;
+    rtdb(): Realtime;
+    /** Call this when your app unmounts or user logs out */
+    dispose(): void;
 }
 
-export { ArraySnapshot, Authentication, Credentials, DisplayInfo, DocumentSnapshot, StorageSnapshot, Timestamp, EdmaxLabs as default };
+export { ArraySnapshot, Authentication, Credentials, DisplayInfo, DocumentSnapshot, EdmaxLabsConfig, StorageSnapshot, Timestamp, EdmaxLabs as default };