svelte-firekit 0.1.9 → 0.2.0

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

@@ -1,288 +1,107 @@
+import { type DocumentReference } from 'firebase/firestore';
+import { DocumentError } from '../types/document.js';
 /**
- * @fileoverview FirekitDoc - Optimized Firestore document management for Svelte
- * @module FirekitDoc
- * @version 1.0.0
+ * Options for FirekitDoc.
  */
-import { type DocumentReference, type DocumentData } from 'firebase/firestore';
-import { type DocumentState, type DocumentOptions, DocumentError } from '../types/document.js';
+export interface FirekitDocOptions {
+    /** Subscribe to real-time updates. Default: true */
+    realtime?: boolean;
+    /** Include metadata-only changes in real-time updates. Default: false */
+    includeMetadata?: boolean;
+}
 /**
- * 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}
  * ```
  */
-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 */
+export declare class FirekitDoc<T = Record<string, unknown>> {
     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
-     */
+    private _id;
+    private _fromCache;
+    private _hasPendingWrites;
+    readonly hasData: boolean;
+    readonly isReady: boolean;
+    readonly isEmpty: boolean;
+    readonly canRetry: boolean;
+    private _ref;
+    private _unsubscribe;
+    private _path;
+    private _options;
+    constructor(path: string, options?: FirekitDocOptions);
     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
-     */
+    get id(): string;
+    get path(): string;
+    get fromCache(): boolean;
+    get hasPendingWrites(): boolean;
+    get ref(): DocumentReference | null;
+    private _init;
+    private _subscribe;
+    private _fetchOnce;
+    private _handleSnapshot;
+    /** Re-fetches the document from the local cache / server. */
     refresh(): Promise<void>;
+    /** Forces a fetch directly from the Firestore server (bypasses cache). */
+    getFromServer(): 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
+     * Switches between real-time and one-time fetch mode.
+     * Unsubscribes existing listener if disabling real-time.
      */
-    setRealtimeMode(realtime: boolean): void;
+    setRealtimeMode(enabled: boolean): void;
     /**
-     * Check if document data is stale (for cache management)
-     * @param maxAge Maximum age in milliseconds
-     * @returns True if data is considered stale
+     * 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');
+     * ```
      */
-    isStale(maxAge?: number): boolean;
+    setPath(newPath: string): void;
     /**
-     * Clean up resources and unsubscribe from listeners
+     * Resolves when the document has finished its initial load.
+     * Useful for SSR / data-loading patterns.
      */
+    waitForReady(): Promise<T | null>;
+    /** Stops the real-time listener and frees resources. */
     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
+ * 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 declare function firekitDoc<T extends DocumentData = DocumentData>(ref: string | DocumentReference<T>, startWith?: T, options?: DocumentOptions): FirekitDoc<T>;
+export declare function firekitDoc<T = Record<string, unknown>>(path: string, options?: Omit<FirekitDocOptions, 'realtime'>): 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');
- * ```
+ * Creates a one-time Firestore document fetch (no real-time listener).
  */
-export declare function firekitDocOnce<T extends DocumentData = DocumentData>(ref: string | DocumentReference<T>, startWith?: T): FirekitDoc<T>;
+export declare function firekitDocOnce<T = Record<string, unknown>>(path: string, options?: Omit<FirekitDocOptions, 'realtime'>): 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');
- * ```
+ * Creates a reactive Firestore document that also exposes metadata
+ * (fromCache, hasPendingWrites).
  */
-export declare function firekitDocWithMetadata<T extends DocumentData = DocumentData>(ref: string | DocumentReference<T>, startWith?: T): FirekitDoc<T>;
-export {};
+export declare function firekitDocWithMetadata<T = Record<string, unknown>>(path: string): FirekitDoc<T>;