svelte-firekit 0.0.25 → 0.1.1

package/dist/services/document.svelte.d.ts

@@ -0,0 +1,288 @@
+/**
+ * @fileoverview FirekitDoc - Optimized Firestore document management for Svelte
+ * @module FirekitDoc
+ * @version 1.0.0
+ */
+import { type DocumentReference, type DocumentData } from 'firebase/firestore';
+import { type DocumentState, type DocumentOptions, DocumentError } from '../types/document.js';
+/**
+ * Manages real-time Firestore document subscriptions with reactive state.
+ * Uses Svelte 5 runes for optimal reactivity and performance.
+ *
+ * @class FirekitDoc
+ * @template T Document data type
+ *
+ * @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);
+ * }
+ * ```
+ */
+declare class FirekitDoc<T extends DocumentData = DocumentData> {
+    /** Document reference */
+    private docRef;
+    /** Unsubscribe function for real-time listener */
+    private unsubscribe;
+    /** Configuration options */
+    private options;
+    /** Current document data - reactive */
+    private _data;
+    /** Loading state - reactive */
+    private _loading;
+    /** Error state - reactive */
+    private _error;
+    /** Document exists state - reactive */
+    private _exists;
+    /** Computed document state with all reactive properties */
+    private _computedState;
+    /** Derived: Whether document is in a valid state for operations */
+    private _isValid;
+    /** Derived: Whether document can be refreshed */
+    private _canRefresh;
+    /** Derived: Whether document has pending operations */
+    private _hasPendingOperations;
+    /**
+     * 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: string | DocumentReference<T>, startWith?: T, options?: DocumentOptions);
+    /**
+     * Initialize document reference and subscription
+     */
+    private initializeDocument;
+    /**
+     * Set up real-time document listener
+     */
+    private setupRealtimeListener;
+    /**
+     * Fetch document data once (no real-time updates)
+     */
+    private fetchOnce;
+    /**
+     * Process document snapshot and update state
+     */
+    private processSnapshot;
+    /**
+     * Handle and process errors
+     */
+    private handleError;
+    /**
+     * Map Firestore error codes to DocumentErrorCode
+     */
+    private mapFirestoreErrorCode;
+    /**
+     * Reactive method: Automatically retry if error is retryable
+     * @returns Promise that resolves when retry is complete
+     */
+    retryIfNeeded(): Promise<void>;
+    /**
+     * Reactive method: Refresh if data is stale
+     * @param maxAge Maximum age in milliseconds
+     * @returns Promise that resolves when refresh is complete
+     */
+    refreshIfStale(maxAge?: number): Promise<void>;
+    /**
+     * Reactive method: Get fresh data if not ready
+     * @returns Promise resolving to document data
+     */
+    ensureReady(): Promise<T | null>;
+    /**
+     * Update state atomically with partial updates
+     * @param updates Partial state updates
+     */
+    private updateState;
+    /**
+     * Get human-readable status string
+     * @returns Status description
+     */
+    private getStatus;
+    /**
+     * Get current document data
+     * @returns Current document data or null
+     */
+    get data(): T | null;
+    /**
+     * Get document ID
+     * @returns Document ID or empty string if not available
+     */
+    get id(): string;
+    /**
+     * Get loading state
+     * @returns True if document is currently loading
+     */
+    get loading(): boolean;
+    /**
+     * Get error state
+     * @returns Current error or null if no error
+     */
+    get error(): DocumentError | null;
+    /**
+     * Check if document exists
+     * @returns True if document exists in Firestore
+     */
+    get exists(): boolean;
+    /**
+     * Get document reference
+     * @returns Firestore DocumentReference
+     * @throws DocumentError if reference is not available
+     */
+    get ref(): DocumentReference<T>;
+    /**
+     * Get current document state summary
+     * @returns Complete document state object
+     */
+    get state(): DocumentState<T>;
+    /**
+     * Get enhanced computed state
+     * @returns Computed state with additional reactive properties
+     */
+    get computedState(): {
+        data: T | null;
+        loading: boolean;
+        error: DocumentError | null;
+        exists: boolean;
+        id: string;
+        isEmpty: boolean;
+        isReady: boolean;
+        hasData: boolean;
+        canRetry: boolean;
+        isStale: boolean | null;
+        status: string;
+    };
+    /**
+     * Check if document is in valid state for operations
+     * @returns True if document can be operated on
+     */
+    get isValid(): boolean;
+    /**
+     * Check if document can be refreshed
+     * @returns True if refresh operation is available
+     */
+    get canRefresh(): boolean;
+    /**
+     * Check if document has pending operations
+     * @returns True if there are ongoing operations
+     */
+    get hasPendingOperations(): boolean;
+    /**
+     * Manually refresh document data
+     * @returns Promise that resolves when refresh is complete
+     */
+    refresh(): Promise<void>;
+    /**
+     * Get fresh data from server (bypassing cache)
+     * @returns Promise resolving to fresh document data
+     */
+    getFromServer(): Promise<T | null>;
+    /**
+     * Switch between realtime and one-time fetch modes
+     * @param realtime Whether to enable real-time updates
+     */
+    setRealtimeMode(realtime: boolean): void;
+    /**
+     * Check if document data is stale (for cache management)
+     * @param maxAge Maximum age in milliseconds
+     * @returns True if data is considered stale
+     */
+    isStale(maxAge?: number): boolean;
+    /**
+     * Clean up resources and unsubscribe from listeners
+     */
+    dispose(): void;
+}
+/**
+ * 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
+ *
+ * @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();
+ * }
+ * ```
+ */
+export declare function firekitDoc<T extends DocumentData = DocumentData>(ref: string | DocumentReference<T>, startWith?: T, options?: DocumentOptions): FirekitDoc<T>;
+/**
+ * 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');
+ * ```
+ */
+export declare function firekitDocOnce<T extends DocumentData = DocumentData>(ref: string | DocumentReference<T>, startWith?: T): FirekitDoc<T>;
+/**
+ * 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');
+ * ```
+ */
+export declare function firekitDocWithMetadata<T extends DocumentData = DocumentData>(ref: string | DocumentReference<T>, startWith?: T): FirekitDoc<T>;
+export {};