svelte-firekit 0.1.8 → 0.2.0

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

@@ -1,273 +1,206 @@
+import { type CollectionReference, type Query, type QueryConstraint, type DocumentData } from 'firebase/firestore';
+import { CollectionError, type FirestoreOperator } from '../types/collection.js';
 /**
- * @fileoverview FirekitCollection - Optimized collection management for Svelte applications
- * @module FirekitCollection
- * @version 1.0.0
+ * Fluent query builder — wraps Firestore QueryConstraints.
+ *
+ * @example
+ * ```ts
+ * const constraints = new FirekitQueryBuilder<Post>()
+ *   .where('published', '==', true)
+ *   .orderBy('createdAt', 'desc')
+ *   .limit(20)
+ *   .build();
+ * ```
  */
-import { type Query, type CollectionReference, type DocumentData, type QueryConstraint } from 'firebase/firestore';
-import { type CollectionState, type CollectionOptions, type CollectionStats, type QueryBuilder, CollectionError } from '../types/collection.js';
+export declare class FirekitQueryBuilder<T = DocumentData> {
+    private constraints;
+    where(field: string, operator: FirestoreOperator, value: unknown): this;
+    orderBy(field: string, direction?: 'asc' | 'desc'): this;
+    limit(count: number): this;
+    limitToLast(count: number): this;
+    startAt(...values: unknown[]): this;
+    startAfter(...values: unknown[]): this;
+    endAt(...values: unknown[]): this;
+    endBefore(...values: unknown[]): this;
+    build(): QueryConstraint[];
+    /** Convenience — returns the constructed Firestore Query for a given collection ref. */
+    buildQuery(ref: CollectionReference<T> | Query<T>): Query<T>;
+}
+export interface FirekitCollectionOptions<T = DocumentData> {
+    /** Subscribe to real-time updates. Default: true */
+    realtime?: boolean;
+    /** Include metadata-only changes in real-time updates. Default: false */
+    includeMetadata?: boolean;
+    /** Optional client-side transform applied to each document. */
+    transform?: (doc: DocumentData & {
+        id: string;
+    }) => T;
+    /** Optional client-side filter applied after fetching. */
+    filter?: (doc: T) => boolean;
+}
 /**
- * Comprehensive Firestore collection management with real-time updates and advanced features.
- * Uses Svelte 5 runes for optimal reactivity and performance.
+ * Reactive Firestore collection subscription.
  *
- * @class FirekitCollection
- * @template T Document data type
+ * Manages a Firestore collection query with reactive state via Svelte 5 runes.
  *
  * @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);
- * }
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitCollection } from 'svelte-firekit';
+ *   const posts = firekitCollection<Post>('posts', [where('published', '==', true)]);
+ * </script>
+ * {#each posts.data as post}...{/each}
  * ```
  */
-declare class FirekitCollection<T extends DocumentData = DocumentData> {
+export declare class FirekitCollection<T = DocumentData> {
     private _data;
     private _loading;
-    private _initialized;
     private _error;
-    private _lastUpdated;
-    private collectionRef;
-    protected queryRef: Query<T> | null;
-    private unsubscribe;
-    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;
-    /**
-     * Get current collection data
-     */
+    private _size;
+    private _fromCache;
+    private _hasPendingWrites;
+    readonly isEmpty: boolean;
+    readonly hasData: boolean;
+    readonly isReady: boolean;
+    private _pageSize;
+    private _currentPage;
+    private _hasMore;
+    private _lastVisible;
+    private _cursorStack;
+    private _unsubscribe;
+    private _path;
+    protected _constraints: QueryConstraint[];
+    private _options;
+    private _isGroup;
+    constructor(path: string, constraints?: QueryConstraint[], options?: FirekitCollectionOptions<T>, isGroup?: boolean);
     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
-     */
+    get fromCache(): boolean;
+    get hasPendingWrites(): boolean;
+    get pageSize(): number;
+    get currentPage(): number;
+    get hasMore(): boolean;
+    protected _buildQuery(): Query<DocumentData>;
+    private _init;
+    private _subscribe;
+    private _fetchOnce;
+    private _handleSnapshot;
+    /**
+     * Fetches a single page. Fetches `pageSize + 1` docs to detect `hasMore`,
+     * then trims the result to `pageSize` for display.
+     * @param cursor  Start after this document. Pass null for the first page.
+     * @param append  If true, appends to existing data instead of replacing it (for loadMore).
+     */
+    private _fetchPage;
+    /** Re-fetches from cache or server. */
     refresh(): Promise<void>;
+    /** Forces a fetch directly from the Firestore server (bypasses cache). */
+    getFromServer(): 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
+     * Returns the server-side document count (uses Firestore aggregation query).
+     * Does not download the documents.
      */
-    createQuery(): QueryBuilder<T>;
+    countFromServer(): Promise<number>;
     /**
-     * Apply new query constraints
+     * Replaces the current query constraints and re-fetches.
      */
-    withQuery(builder: QueryBuilder<T>): FirekitCollection<T>;
+    setConstraints(constraints: QueryConstraint[]): Promise<void>;
     /**
-     * Filter documents by predicate
+     * Appends additional constraints (e.g. pagination cursor) and re-fetches.
      */
+    addConstraints(constraints: QueryConstraint[]): Promise<void>;
+    /** Switches between real-time and one-time mode. */
+    setRealtimeMode(enabled: boolean): void;
+    /** Client-side filter (does NOT modify the Firestore query). */
     filter(predicate: (doc: T) => boolean): T[];
-    /**
-     * Find first document matching predicate
-     */
+    /** Finds the first document matching a predicate. */
     find(predicate: (doc: T) => boolean): T | undefined;
-    /**
-     * Find document by ID
-     */
+    /** Finds a document by its Firestore document ID. */
     findById(id: string): T | undefined;
-    /**
-     * Sort documents by field or custom function
-     */
+    /** Client-side sort (returns a new array, does NOT modify stored data). */
     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
+     * Enables cursor-based pagination and loads the first page.
+     *
+     * Disables the real-time listener — paginated queries use one-time fetches.
+     *
+     * @example
+     * ```ts
+     * const posts = firekitCollection<Post>('posts', [orderBy('createdAt', 'desc')]);
+     * await posts.setPagination(10); // 10 per page
+     * ```
      */
-    every(predicate: (doc: T) => boolean): boolean;
+    setPagination(pageSize: number): Promise<void>;
     /**
-     * Switch between realtime and one-time fetch modes
+     * Loads the next page, replacing the current data.
+     * Call `setPagination()` first.
      */
-    setRealtimeMode(realtime: boolean): void;
+    nextPage(): Promise<void>;
     /**
-     * Clear cache for this collection
+     * Loads the previous page, replacing the current data.
      */
-    clearCache(): void;
+    prevPage(): Promise<void>;
     /**
-     * Get collection statistics
+     * Appends the next page to existing data (infinite scroll).
+     * Call `setPagination()` first.
      */
-    getStats(): CollectionStats;
+    loadMore(): Promise<void>;
     /**
-     * Reset statistics
+     * Resets pagination back to the first page.
      */
-    resetStats(): void;
+    resetPagination(): Promise<void>;
     /**
-     * Wait for collection to initialize
+     * Changes the collection path and re-fetches.
+     * Tears down any existing real-time listener before switching.
+     *
+     * @example
+     * ```ts
+     * const messages = firekitCollection<Message>('rooms/general/messages');
+     * // User switches room:
+     * messages.setPath('rooms/random/messages');
+     * ```
      */
-    waitForInitialization(): Promise<T[]>;
+    setPath(newPath: string): void;
     /**
-     * Dispose of all resources and cleanup
+     * Resolves when the collection has finished its initial load.
      */
+    waitForReady(): Promise<T[]>;
+    /** Stops the real-time listener and frees resources. */
     dispose(): void;
 }
 /**
- * Collection Group implementation for querying across multiple collections
+ * Reactive Firestore collection group query.
+ * Queries across all collections sharing the same name (collectionGroup).
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitCollectionGroup } from 'svelte-firekit';
+ *   // Query 'comments' across all parent documents
+ *   const allComments = firekitCollectionGroup<Comment>('comments');
+ * </script>
+ * ```
  */
-declare class FirekitCollectionGroup<T extends DocumentData = DocumentData> extends FirekitCollection<T> {
-    constructor(collectionId: string, constraintsOrOptions?: QueryConstraint[] | CollectionOptions, ...additionalConstraints: QueryConstraint[]);
-    /**
-     * Initialize collection group subscription
-     */
-    private initializeCollectionGroup;
+export declare class FirekitCollectionGroup<T = DocumentData> extends FirekitCollection<T> {
+    constructor(collectionId: string, constraints?: QueryConstraint[], options?: FirekitCollectionOptions<T>);
 }
 /**
- * Creates a reactive collection subscription
+ * Creates a reactive Firestore collection with real-time updates.
+ *
+ * @example
+ * ```ts
+ * const posts = firekitCollection<Post>('posts', [where('published', '==', true)]);
+ * ```
  */
-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>;
+export declare function firekitCollection<T = DocumentData>(path: string, constraints?: QueryConstraint[], options?: Omit<FirekitCollectionOptions<T>, 'realtime'>): FirekitCollection<T>;
 /**
- * Creates a one-time collection fetch (no real-time updates)
+ * Creates a one-time Firestore collection fetch (no real-time listener).
  */
-export declare function firekitCollectionOnce<T extends DocumentData = DocumentData>(path: string, ...constraints: QueryConstraint[]): FirekitCollection<T>;
+export declare function firekitCollectionOnce<T = DocumentData>(path: string, constraints?: QueryConstraint[], options?: Omit<FirekitCollectionOptions<T>, 'realtime'>): FirekitCollection<T>;
 /**
- * Creates a collection group subscription
+ * Creates a reactive Firestore collection group query with real-time updates.
  */
-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 {};
+export declare function firekitCollectionGroup<T = DocumentData>(collectionId: string, constraints?: QueryConstraint[], options?: Omit<FirekitCollectionOptions<T>, 'realtime'>): FirekitCollectionGroup<T>;