svelte-firekit 0.1.9 → 0.2.0

package/dist/services/document.svelte.js

@@ -1,555 +1,254 @@
-/**
- * @fileoverview FirekitDoc - Optimized Firestore document management for Svelte
- * @module FirekitDoc
- * @version 1.0.0
- */
-import { doc, getDoc, onSnapshot } from 'firebase/firestore';
+import { doc, getDoc, getDocFromServer, onSnapshot } from 'firebase/firestore';
 import { firebaseService } from '../firebase.js';
-import { browser } from '$app/environment';
-import { DocumentErrorCode, DocumentError } from '../types/document.js';
+import { DocumentError, DocumentErrorCode } from '../types/document.js';
+function getDb() {
+    const db = firebaseService.getDbInstance();
+    if (!db)
+        throw new Error('Firestore is not initialized.');
+    return db;
+}
+function mapFirestoreError(err, path) {
+    const codeMap = {
+        'permission-denied': DocumentErrorCode.PERMISSION_DENIED,
+        'unauthenticated': DocumentErrorCode.UNAUTHENTICATED,
+        'not-found': DocumentErrorCode.NOT_FOUND,
+        'already-exists': DocumentErrorCode.ALREADY_EXISTS,
+        'unavailable': DocumentErrorCode.UNAVAILABLE,
+        'deadline-exceeded': DocumentErrorCode.TIMEOUT,
+        'cancelled': DocumentErrorCode.CANCELLED,
+        'internal': DocumentErrorCode.INTERNAL_ERROR,
+        'data-loss': DocumentErrorCode.DATA_LOSS,
+        'failed-precondition': DocumentErrorCode.FAILED_PRECONDITION,
+        'aborted': DocumentErrorCode.ABORTED,
+        'out-of-range': DocumentErrorCode.OUT_OF_RANGE,
+        'unimplemented': DocumentErrorCode.UNIMPLEMENTED,
+        'resource-exhausted': DocumentErrorCode.UNAVAILABLE
+    };
+    const code = codeMap[err.code] ?? DocumentErrorCode.UNKNOWN;
+    return new DocumentError(code, err.message, err, { path });
+}
 /**
- * Manages real-time Firestore document subscriptions with reactive state.
- * Uses Svelte 5 runes for optimal reactivity and performance.
+ * Reactive Firestore document subscription.
  *
- * @class FirekitDoc
- * @template T Document data type
+ * Manages a single Firestore document with reactive state via Svelte 5 runes.
+ * Automatically subscribes to real-time updates (or fetches once) when constructed.
  *
  * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   name: string;
- *   email: string;
- * }
- *
- * // Create document subscription
- * const userDoc = firekitDoc<User>('users/123', {
- *   id: '123',
- *   name: 'Loading...',
- *   email: ''
- * });
- *
- * // Access reactive state in Svelte component
- * $: if (userDoc.loading) {
- *   console.log('Loading user...');
- * } else if (userDoc.error) {
- *   console.error('Error:', userDoc.error);
- * } else if (userDoc.exists) {
- *   console.log('User data:', userDoc.data);
- * }
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitDoc } from 'svelte-firekit';
+ *   const user = firekitDoc<User>('users/uid123');
+ * </script>
+ * {#if user.loading}Loading...{/if}
+ * {#if user.data}{user.data.name}{/if}
  * ```
  */
-class FirekitDoc {
-    /** Document reference */
-    docRef = null;
-    /** Unsubscribe function for real-time listener */
-    unsubscribe = null;
-    /** Configuration options */
-    options;
-    // ========================================
-    // REACTIVE STATE (Svelte 5 Runes)
-    // ========================================
-    /** Current document data - reactive */
+export class FirekitDoc {
+    // ── Reactive state ────────────────────────────────────────────────────────
     _data = $state(null);
-    /** Loading state - reactive */
     _loading = $state(true);
-    /** Error state - reactive */
     _error = $state(null);
-    /** Document exists state - reactive */
     _exists = $state(false);
-    // ========================================
-    // ENHANCED DERIVED STATE
-    // ========================================
-    /** Computed document state with all reactive properties */
-    _computedState = $derived({
-        data: this._data,
-        loading: this._loading,
-        error: this._error,
-        exists: this._exists,
-        id: this.docRef?.id ?? '',
-        isEmpty: !this._data && !this._loading && !this._error,
-        isReady: !this._loading && !this._error,
-        hasData: !!this._data,
-        canRetry: this._error?.isRetryable() ?? false,
-        isStale: this._data && this.isStale(300000), // 5 minutes default
-        status: this.getStatus()
-    });
-    /** Derived: Whether document is in a valid state for operations */
-    _isValid = $derived(this.docRef !== null && !this._loading && !this._error);
-    /** Derived: Whether document can be refreshed */
-    _canRefresh = $derived(this.docRef !== null && !this._loading);
-    /** Derived: Whether document has pending operations */
-    _hasPendingOperations = $derived(this._loading || (this._error ? this._error.isRetryable() : false));
-    /**
-     * Creates a document subscription with real-time updates
-     *
-     * @param ref Document path or DocumentReference
-     * @param startWith Initial data to show while loading
-     * @param options Configuration options
-     */
-    constructor(ref, startWith, options = {}) {
-        this.options = {
-            realtime: true,
-            includeMetadata: false,
-            source: 'default',
-            ...options
-        };
-        // Set initial data if provided
-        if (startWith) {
-            this.updateState({
-                data: startWith,
-                exists: true,
-                loading: false,
-                error: null
-            });
-        }
-        // Only initialize in browser environment
-        if (browser) {
-            this.initializeDocument(ref);
+    _id = $state('');
+    _fromCache = $state(false);
+    _hasPendingWrites = $state(false);
+    // ── Derived ───────────────────────────────────────────────────────────────
+    hasData = $derived(this._data !== null && this._exists);
+    isReady = $derived(!this._loading && this._exists && this._data !== null);
+    isEmpty = $derived(!this._loading && !this._exists);
+    canRetry = $derived(this._error !== null && (this._error.isRetryable?.() ?? false));
+    // ── Internal ──────────────────────────────────────────────────────────────
+    _ref = null;
+    _unsubscribe = null;
+    _path;
+    _options;
+    constructor(path, options = {}) {
+        this._path = path;
+        this._options = { realtime: true, includeMetadata: false, ...options };
+        this._init();
+    }
+    // ── Public getters ────────────────────────────────────────────────────────
+    get data() { return this._data; }
+    get loading() { return this._loading; }
+    get error() { return this._error; }
+    get exists() { return this._exists; }
+    get id() { return this._id; }
+    get path() { return this._path; }
+    get fromCache() { return this._fromCache; }
+    get hasPendingWrites() { return this._hasPendingWrites; }
+    get ref() { return this._ref; }
+    // ── Initialization ────────────────────────────────────────────────────────
+    _init() {
+        if (typeof window === 'undefined') {
+            this._loading = false;
+            return;
         }
-    }
-    /**
-     * Initialize document reference and subscription
-     */
-    async initializeDocument(ref) {
         try {
-            const firestore = firebaseService.getDbInstance();
-            if (!firestore) {
-                throw new DocumentError(DocumentErrorCode.FIRESTORE_UNAVAILABLE, 'Firestore instance not available');
-            }
-            // Create document reference
-            this.docRef = typeof ref === 'string' ? doc(firestore, ref) : ref;
-            // Set up real-time listener or one-time fetch
-            if (this.options.realtime) {
-                this.setupRealtimeListener();
+            const db = getDb();
+            this._ref = doc(db, this._path);
+            this._id = this._ref.id;
+            if (this._options.realtime) {
+                this._subscribe();
             }
             else {
-                await this.fetchOnce();
+                this._fetchOnce();
             }
         }
-        catch (error) {
-            this.handleError(error);
+        catch (err) {
+            this._error = new DocumentError(DocumentErrorCode.REFERENCE_UNAVAILABLE, err instanceof Error ? err.message : String(err), err);
+            this._loading = false;
         }
     }
-    /**
-     * Set up real-time document listener
-     */
-    setupRealtimeListener() {
-        if (!this.docRef)
+    _subscribe() {
+        if (!this._ref)
             return;
-        const options = {
-            includeMetadataChanges: this.options.includeMetadata
+        const listenOptions = {
+            includeMetadataChanges: this._options.includeMetadata
         };
-        this.unsubscribe = onSnapshot(this.docRef, options, (snapshot) => {
-            this.processSnapshot(snapshot);
-        }, (error) => {
-            this.handleError(error);
+        this._unsubscribe = onSnapshot(this._ref, listenOptions, (snap) => this._handleSnapshot(snap), (err) => {
+            this._error = mapFirestoreError(err, this._path);
+            this._loading = false;
         });
     }
-    /**
-     * Fetch document data once (no real-time updates)
-     */
-    async fetchOnce() {
-        if (!this.docRef)
+    async _fetchOnce() {
+        if (!this._ref)
             return;
         try {
-            this.updateState({ loading: true });
-            const snapshot = await getDoc(this.docRef);
-            this.processSnapshot(snapshot);
-        }
-        catch (error) {
-            this.handleError(error);
-        }
-    }
-    /**
-     * Process document snapshot and update state
-     */
-    processSnapshot(snapshot) {
-        try {
-            const exists = snapshot.exists();
-            const data = exists ? snapshot.data() : null;
-            // Add document ID to data if it exists
-            const processedData = data
-                ? {
-                    ...data,
-                    id: snapshot.id
-                }
-                : null;
-            // Update reactive state atomically
-            this.updateState({
-                data: processedData,
-                exists,
-                loading: false,
-                error: null
-            });
-        }
-        catch (error) {
-            this.handleError(error);
-        }
-    }
-    /**
-     * Handle and process errors
-     */
-    handleError(error) {
-        let documentError;
-        if (error instanceof DocumentError) {
-            documentError = error;
-        }
-        else {
-            // Map Firestore errors to DocumentError
-            const code = this.mapFirestoreErrorCode(error.code);
-            documentError = new DocumentError(code, error.message, error);
-        }
-        this.updateState({
-            error: documentError,
-            loading: false
-        });
-        console.error('FirekitDoc error:', documentError);
-    }
-    /**
-     * Map Firestore error codes to DocumentErrorCode
-     */
-    mapFirestoreErrorCode(firestoreCode) {
-        switch (firestoreCode) {
-            case 'permission-denied':
-                return DocumentErrorCode.PERMISSION_DENIED;
-            case 'not-found':
-                return DocumentErrorCode.NOT_FOUND;
-            case 'unavailable':
-                return DocumentErrorCode.UNAVAILABLE;
-            case 'deadline-exceeded':
-                return DocumentErrorCode.TIMEOUT;
-            case 'cancelled':
-                return DocumentErrorCode.CANCELLED;
-            default:
-                return DocumentErrorCode.UNKNOWN;
-        }
-    }
-    // ========================================
-    // REACTIVE METHODS
-    // ========================================
-    /**
-     * Reactive method: Automatically retry if error is retryable
-     * @returns Promise that resolves when retry is complete
-     */
-    async retryIfNeeded() {
-        if (this._computedState.canRetry) {
-            await this.refresh();
-        }
-    }
-    /**
-     * Reactive method: Refresh if data is stale
-     * @param maxAge Maximum age in milliseconds
-     * @returns Promise that resolves when refresh is complete
-     */
-    async refreshIfStale(maxAge = 300000) {
-        if (this._computedState.isStale) {
-            await this.refresh();
-        }
-    }
-    /**
-     * Reactive method: Get fresh data if not ready
-     * @returns Promise resolving to document data
-     */
-    async ensureReady() {
-        if (!this._computedState.isReady) {
-            await this.refresh();
-        }
-        return this._data;
-    }
-    // ========================================
-    // STATE MANAGEMENT
-    // ========================================
-    /**
-     * Update state atomically with partial updates
-     * @param updates Partial state updates
-     */
-    updateState(updates) {
-        if (updates.data !== undefined)
-            this._data = updates.data;
-        if (updates.loading !== undefined)
-            this._loading = updates.loading;
-        if (updates.error !== undefined)
-            this._error = updates.error;
-        if (updates.exists !== undefined)
-            this._exists = updates.exists;
-    }
-    /**
-     * Get human-readable status string
-     * @returns Status description
-     */
-    getStatus() {
-        if (this._loading)
-            return 'loading';
-        if (this._error)
-            return 'error';
-        if (this._exists)
-            return 'exists';
-        return 'not-found';
-    }
-    // ========================================
-    // PUBLIC GETTERS (Reactive State)
-    // ========================================
-    /**
-     * Get current document data
-     * @returns Current document data or null
-     */
-    get data() {
-        return this._data;
-    }
-    /**
-     * Get document ID
-     * @returns Document ID or empty string if not available
-     */
-    get id() {
-        return this.docRef?.id ?? '';
-    }
-    /**
-     * Get loading state
-     * @returns True if document is currently loading
-     */
-    get loading() {
-        return this._loading;
-    }
-    /**
-     * Get error state
-     * @returns Current error or null if no error
-     */
-    get error() {
-        return this._error;
-    }
-    /**
-     * Check if document exists
-     * @returns True if document exists in Firestore
-     */
-    get exists() {
-        return this._exists;
-    }
-    /**
-     * Get document reference
-     * @returns Firestore DocumentReference
-     * @throws DocumentError if reference is not available
-     */
-    get ref() {
-        if (!this.docRef) {
-            throw new DocumentError(DocumentErrorCode.REFERENCE_UNAVAILABLE, 'Document reference is not available');
-        }
-        return this.docRef;
-    }
-    /**
-     * Get current document state summary
-     * @returns Complete document state object
-     */
-    get state() {
-        return {
-            data: this._data,
-            exists: this._exists,
-            loading: this._loading,
-            error: this._error,
-            id: this.id
-        };
-    }
-    /**
-     * Get enhanced computed state
-     * @returns Computed state with additional reactive properties
-     */
-    get computedState() {
-        return this._computedState;
-    }
-    /**
-     * Check if document is in valid state for operations
-     * @returns True if document can be operated on
-     */
-    get isValid() {
-        return this._isValid;
-    }
-    /**
-     * Check if document can be refreshed
-     * @returns True if refresh operation is available
-     */
-    get canRefresh() {
-        return this._canRefresh;
-    }
-    /**
-     * Check if document has pending operations
-     * @returns True if there are ongoing operations
-     */
-    get hasPendingOperations() {
-        return this._hasPendingOperations;
-    }
-    // ========================================
-    // PUBLIC METHODS
-    // ========================================
-    /**
-     * Manually refresh document data
-     * @returns Promise that resolves when refresh is complete
-     */
+            const snap = await getDoc(this._ref);
+            this._handleSnapshot(snap);
+        }
+        catch (err) {
+            const fsErr = err;
+            this._error = mapFirestoreError(fsErr, this._path);
+            this._loading = false;
+        }
+    }
+    _handleSnapshot(snap) {
+        this._exists = snap.exists();
+        this._data = snap.exists() ? snap.data() : null;
+        this._id = snap.id;
+        this._fromCache = snap.metadata.fromCache;
+        this._hasPendingWrites = snap.metadata.hasPendingWrites;
+        this._error = null;
+        this._loading = false;
+    }
+    // ── Public methods ────────────────────────────────────────────────────────
+    /** Re-fetches the document from the local cache / server. */
     async refresh() {
-        if (!this.docRef) {
-            throw new DocumentError(DocumentErrorCode.REFERENCE_UNAVAILABLE, 'Cannot refresh: document reference not available');
-        }
+        if (!this._ref)
+            return;
+        this._loading = true;
         try {
-            this.updateState({ loading: true });
-            const snapshot = await getDoc(this.docRef);
-            this.processSnapshot(snapshot);
+            const snap = await getDoc(this._ref);
+            this._handleSnapshot(snap);
         }
-        catch (error) {
-            this.handleError(error);
-            throw error;
+        catch (err) {
+            this._error = mapFirestoreError(err, this._path);
+            this._loading = false;
         }
     }
-    /**
-     * Get fresh data from server (bypassing cache)
-     * @returns Promise resolving to fresh document data
-     */
+    /** Forces a fetch directly from the Firestore server (bypasses cache). */
     async getFromServer() {
-        if (!this.docRef) {
-            throw new DocumentError(DocumentErrorCode.REFERENCE_UNAVAILABLE, 'Cannot fetch: document reference not available');
-        }
+        if (!this._ref)
+            return;
+        this._loading = true;
         try {
-            const snapshot = await getDoc(this.docRef);
-            const data = snapshot.exists() ? snapshot.data() : null;
-            return data ? { ...data, id: snapshot.id } : null;
+            const snap = await getDocFromServer(this._ref);
+            this._handleSnapshot(snap);
         }
-        catch (error) {
-            this.handleError(error);
-            throw error;
+        catch (err) {
+            this._error = mapFirestoreError(err, this._path);
+            this._loading = false;
         }
     }
     /**
-     * Switch between realtime and one-time fetch modes
-     * @param realtime Whether to enable real-time updates
+     * Switches between real-time and one-time fetch mode.
+     * Unsubscribes existing listener if disabling real-time.
      */
-    setRealtimeMode(realtime) {
-        if (this.options.realtime === realtime)
+    setRealtimeMode(enabled) {
+        if (enabled === this._options.realtime)
             return;
-        this.options.realtime = realtime;
-        // Clean up existing listener
-        if (this.unsubscribe) {
-            this.unsubscribe();
-            this.unsubscribe = null;
+        this._options.realtime = enabled;
+        if (!enabled) {
+            this._unsubscribe?.();
+            this._unsubscribe = null;
         }
-        // Set up new mode
-        if (realtime) {
-            this.setupRealtimeListener();
+        else {
+            this._subscribe();
         }
     }
     /**
-     * Check if document data is stale (for cache management)
-     * @param maxAge Maximum age in milliseconds
-     * @returns True if data is considered stale
-     */
-    isStale(maxAge = 300000) {
-        // 5 minutes default
-        if (!this._data || !('updatedAt' in this._data))
-            return false;
-        const updatedAt = this._data.updatedAt;
-        if (!updatedAt?.toDate)
-            return false;
-        const now = new Date().getTime();
-        const dataTime = updatedAt.toDate().getTime();
-        return now - dataTime > maxAge;
+     * Changes the document path and re-subscribes (or re-fetches).
+     * Tears down any existing real-time listener before switching.
+     *
+     * @example
+     * ```ts
+     * const userDoc = firekitDoc<User>('users/alice');
+     * // User switches account:
+     * userDoc.setPath('users/bob');
+     * ```
+     */
+    setPath(newPath) {
+        this._unsubscribe?.();
+        this._unsubscribe = null;
+        this._path = newPath;
+        this._loading = true;
+        this._data = null;
+        this._exists = false;
+        this._error = null;
+        this._init();
+    }
+    /**
+     * Resolves when the document has finished its initial load.
+     * Useful for SSR / data-loading patterns.
+     */
+    waitForReady() {
+        if (!this._loading)
+            return Promise.resolve(this._data);
+        // $effect.root creates a reactive scope outside of component initialization,
+        // so this works safely whether called inside or outside a Svelte component.
+        return new Promise((resolve) => {
+            const stop = $effect.root(() => {
+                $effect(() => {
+                    if (!this._loading) {
+                        stop();
+                        resolve(this._data);
+                    }
+                });
+            });
+        });
     }
-    /**
-     * Clean up resources and unsubscribe from listeners
-     */
+    /** Stops the real-time listener and frees resources. */
     dispose() {
-        if (this.unsubscribe) {
-            this.unsubscribe();
-            this.unsubscribe = null;
-        }
-        // Reset state
-        this.updateState({
-            data: null,
-            loading: false,
-            error: null,
-            exists: false
-        });
-        this.docRef = null;
+        this._unsubscribe?.();
+        this._unsubscribe = null;
     }
 }
-// ========================================
-// FACTORY FUNCTIONS
-// ========================================
+// ── Factory functions ─────────────────────────────────────────────────────────
 /**
- * Creates a reactive document subscription with real-time updates
- *
- * @template T Document data type
- * @param ref Document path or DocumentReference
- * @param startWith Initial data to show while loading
- * @param options Configuration options
- * @returns FirekitDoc instance with reactive state
+ * Creates a reactive Firestore document with real-time updates.
  *
  * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   name: string;
- *   email: string;
- * }
- *
- * // Real-time document subscription
- * const userDoc = firekitDoc<User>('users/123', {
- *   id: '123',
- *   name: 'Loading...',
- *   email: ''
- * });
- *
- * // One-time fetch
- * const userDoc = firekitDoc<User>('users/123', undefined, {
- *   realtime: false
- * });
- *
- * // In Svelte component
- * $: if (userDoc.loading) {
- *   // Show loading state
- * } else if (userDoc.error) {
- *   // Handle error
- * } else if (userDoc.exists) {
- *   // Use userDoc.data
- * }
- *
- * // Use reactive methods
- * $: if (userDoc.computedState.canRetry) {
- *   userDoc.retryIfNeeded();
- * }
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitDoc } from 'svelte-firekit';
+ *   const post = firekitDoc<Post>('posts/abc123');
+ * </script>
  * ```
  */
-export function firekitDoc(ref, startWith, options) {
-    return new FirekitDoc(ref, startWith, options);
+export function firekitDoc(path, options) {
+    return new FirekitDoc(path, { ...options, realtime: true });
 }
 /**
- * Creates a one-time document fetch (no real-time updates)
- *
- * @template T Document data type
- * @param ref Document path or DocumentReference
- * @param startWith Initial data to show while loading
- * @returns FirekitDoc instance configured for one-time fetch
- *
- * @example
- * ```typescript
- * const userDoc = firekitDocOnce<User>('users/123');
- * ```
+ * Creates a one-time Firestore document fetch (no real-time listener).
  */
-export function firekitDocOnce(ref, startWith) {
-    return new FirekitDoc(ref, startWith, { realtime: false });
+export function firekitDocOnce(path, options) {
+    return new FirekitDoc(path, { ...options, realtime: false });
 }
 /**
- * Creates a document subscription with metadata changes included
- *
- * @template T Document data type
- * @param ref Document path or DocumentReference
- * @param startWith Initial data to show while loading
- * @returns FirekitDoc instance with metadata tracking
- *
- * @example
- * ```typescript
- * const userDoc = firekitDocWithMetadata<User>('users/123');
- * ```
+ * Creates a reactive Firestore document that also exposes metadata
+ * (fromCache, hasPendingWrites).
  */
-export function firekitDocWithMetadata(ref, startWith) {
-    return new FirekitDoc(ref, startWith, {
-        realtime: true,
-        includeMetadata: true
-    });
+export function firekitDocWithMetadata(path) {
+    return new FirekitDoc(path, { realtime: true, includeMetadata: true });
 }