svelte-firekit 0.0.25 → 0.1.0

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

@@ -0,0 +1,286 @@
+/**
+ * @fileoverview FirekitCollection - Optimized collection management for Svelte applications
+ * @module FirekitCollection
+ * @version 1.0.0
+ */
+import { type Query, type CollectionReference, type DocumentData, type QueryConstraint } from 'firebase/firestore';
+import { type CollectionState, type CollectionOptions, type CollectionEventCallback, type CollectionStats, type QueryBuilder, CollectionError } from '../types/collection.js';
+/**
+ * Comprehensive Firestore collection management with real-time updates and advanced features.
+ * Uses Svelte 5 runes for optimal reactivity and performance.
+ *
+ * @class FirekitCollection
+ * @template T Document data type
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ *   active: boolean;
+ * }
+ *
+ * // Simple collection subscription
+ * const users = firekitCollection<User>('users');
+ *
+ * // With query constraints
+ * const activeUsers = firekitCollection<User>('users',
+ *   where('active', '==', true),
+ *   orderBy('name'),
+ *   limit(10)
+ * );
+ *
+ * // With advanced options
+ * const paginatedUsers = firekitCollection<User>('users', {
+ *   pagination: { enabled: true, pageSize: 20 },
+ *   cache: { enabled: true, ttl: 300000 },
+ *   transform: (doc) => ({ ...doc, displayName: doc.name.toUpperCase() })
+ * });
+ *
+ * // Access reactive state
+ * $: if (users.loading) {
+ *   console.log('Loading...');
+ * } else if (users.error) {
+ *   console.error('Error:', users.error);
+ * } else {
+ *   console.log('Users:', users.data);
+ * }
+ * ```
+ */
+declare class FirekitCollection<T extends DocumentData = DocumentData> {
+    private _data;
+    private _loading;
+    private _initialized;
+    private _error;
+    private _lastUpdated;
+    private collectionRef;
+    protected queryRef: Query<T> | null;
+    private unsubscribe;
+    private eventListeners;
+    protected options: CollectionOptions;
+    private stats;
+    private cache;
+    private collectionPath;
+    /**
+     * Creates a collection subscription
+     *
+     * @param path Collection path
+     * @param constraintsOrOptions Query constraints or collection options
+     * @param additionalConstraints Additional constraints if options were provided
+     */
+    constructor(path: string, constraintsOrOptions?: QueryConstraint[] | CollectionOptions, ...additionalConstraints: QueryConstraint[]);
+    /**
+     * Initialize statistics object
+     */
+    private initializeStats;
+    /**
+     * Initialize collection subscription
+     */
+    private initializeCollection;
+    /**
+     * Set up real-time document listener
+     */
+    protected setupRealtimeListener(): void;
+    /**
+     * Fetch collection data once (no real-time updates)
+     */
+    protected fetchOnce(): Promise<void>;
+    /**
+     * Process query snapshot and update state
+     */
+    private processSnapshot;
+    /**
+     * Calculate changes between old and new document arrays
+     */
+    private calculateChanges;
+    /**
+     * Handle and process errors
+     */
+    protected handleError(error: any): void;
+    /**
+     * Map Firestore error codes to CollectionErrorCode
+     */
+    private mapFirestoreErrorCode;
+    /**
+     * Generate cache key for query
+     */
+    private getCacheKey;
+    /**
+     * Check if cache entry is still valid
+     */
+    private isCacheValid;
+    /**
+     * Clean up expired cache entries
+     */
+    private cleanupCache;
+    /**
+     * Calculate memory usage of documents
+     */
+    private calculateMemoryUsage;
+    /**
+     * Emit event to all listeners
+     */
+    private emitEvent;
+    /**
+     * Get current collection data
+     */
+    get data(): T[];
+    /**
+     * Get loading state
+     */
+    get loading(): boolean;
+    /**
+     * Get initialization state
+     */
+    get initialized(): boolean;
+    /**
+     * Get error state
+     */
+    get error(): CollectionError | null;
+    /**
+     * Check if collection is empty
+     */
+    get empty(): boolean;
+    /**
+     * Get number of documents
+     */
+    get size(): number;
+    /**
+     * Get last update timestamp
+     */
+    get lastUpdated(): Date | null;
+    /**
+     * Get collection reference
+     */
+    get ref(): CollectionReference<T>;
+    /**
+     * Get query reference
+     */
+    get queryReference(): Query<T>;
+    /**
+     * Get collection path
+     */
+    get path(): string;
+    /**
+     * Get collection state summary
+     */
+    get state(): CollectionState<T>;
+    /**
+     * Manually refresh collection data
+     */
+    refresh(): Promise<void>;
+    /**
+     * Get fresh data from server (bypassing cache)
+     */
+    getFromServer(): Promise<T[]>;
+    /**
+     * Add query constraints to existing query
+     */
+    addConstraints(...constraints: QueryConstraint[]): FirekitCollection<T>;
+    /**
+     * Create a new query builder for this collection
+     */
+    createQuery(): QueryBuilder<T>;
+    /**
+     * Apply new query constraints
+     */
+    withQuery(builder: QueryBuilder<T>): FirekitCollection<T>;
+    /**
+     * Filter documents by predicate
+     */
+    filter(predicate: (doc: T) => boolean): T[];
+    /**
+     * Find first document matching predicate
+     */
+    find(predicate: (doc: T) => boolean): T | undefined;
+    /**
+     * Find document by ID
+     */
+    findById(id: string): T | undefined;
+    /**
+     * Sort documents by field or custom function
+     */
+    sort(compareFn: (a: T, b: T) => number): T[];
+    /**
+     * Get paginated subset of documents
+     */
+    paginate(page: number, pageSize: number): T[];
+    /**
+     * Group documents by field value
+     */
+    groupBy<K extends keyof T>(field: K): Map<T[K], T[]>;
+    /**
+     * Get unique values for a field
+     */
+    unique<K extends keyof T>(field: K): T[K][];
+    /**
+     * Count documents matching predicate
+     */
+    count(predicate?: (doc: T) => boolean): number;
+    /**
+     * Check if any document matches predicate
+     */
+    some(predicate: (doc: T) => boolean): boolean;
+    /**
+     * Check if all documents match predicate
+     */
+    every(predicate: (doc: T) => boolean): boolean;
+    /**
+     * Switch between realtime and one-time fetch modes
+     */
+    setRealtimeMode(realtime: boolean): void;
+    /**
+     * Clear cache for this collection
+     */
+    clearCache(): void;
+    /**
+     * Get collection statistics
+     */
+    getStats(): CollectionStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Add event listener
+     */
+    addEventListener(callback: CollectionEventCallback<T>): () => void;
+    /**
+     * Remove all event listeners
+     */
+    clearEventListeners(): void;
+    /**
+     * Wait for collection to initialize
+     */
+    waitForInitialization(): Promise<T[]>;
+    /**
+     * Dispose of all resources and cleanup
+     */
+    dispose(): void;
+}
+/**
+ * Collection Group implementation for querying across multiple collections
+ */
+declare class FirekitCollectionGroup<T extends DocumentData = DocumentData> extends FirekitCollection<T> {
+    constructor(collectionId: string, constraintsOrOptions?: QueryConstraint[] | CollectionOptions, ...additionalConstraints: QueryConstraint[]);
+    /**
+     * Initialize collection group subscription
+     */
+    private initializeCollectionGroup;
+}
+/**
+ * Creates a reactive collection subscription
+ */
+export declare function firekitCollection<T extends DocumentData = DocumentData>(path: string, constraintsOrOptions?: QueryConstraint[] | CollectionOptions, ...additionalConstraints: QueryConstraint[]): FirekitCollection<T>;
+export declare function firekitCollection<T extends DocumentData = DocumentData>(path: string, options: CollectionOptions, ...constraints: QueryConstraint[]): FirekitCollection<T>;
+/**
+ * Creates a one-time collection fetch (no real-time updates)
+ */
+export declare function firekitCollectionOnce<T extends DocumentData = DocumentData>(path: string, ...constraints: QueryConstraint[]): FirekitCollection<T>;
+/**
+ * Creates a collection group subscription
+ */
+export declare function firekitCollectionGroup<T extends DocumentData = DocumentData>(collectionId: string, constraintsOrOptions?: QueryConstraint[] | CollectionOptions, ...additionalConstraints: QueryConstraint[]): FirekitCollectionGroup<T>;
+export declare function firekitCollectionGroup<T extends DocumentData = DocumentData>(collectionId: string, options: CollectionOptions, ...constraints: QueryConstraint[]): FirekitCollectionGroup<T>;
+export {};