svelte-firekit 0.1.9 → 0.2.0

package/dist/services/collection.svelte.js

@@ -1,16 +1,46 @@
-/**
- * @fileoverview FirekitCollection - Optimized collection management for Svelte applications
- * @module FirekitCollection
- * @version 1.0.0
- */
-import { collection, collectionGroup, query, onSnapshot, getDocs, where, orderBy, limit, startAt, startAfter, endAt, endBefore } from 'firebase/firestore';
+import { collection, collectionGroup, query, getDocs, getDocsFromServer, onSnapshot, orderBy, limit, limitToLast, where, startAt, startAfter, endAt, endBefore, getCountFromServer } from 'firebase/firestore';
 import { firebaseService } from '../firebase.js';
-import { browser } from '$app/environment';
-import { CollectionErrorCode, CollectionError } from '../types/collection.js';
+import { CollectionError, CollectionErrorCode } from '../types/collection.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': CollectionErrorCode.PERMISSION_DENIED,
+        'unauthenticated': CollectionErrorCode.UNAUTHENTICATED,
+        'not-found': CollectionErrorCode.NOT_FOUND,
+        'already-exists': CollectionErrorCode.ALREADY_EXISTS,
+        'unavailable': CollectionErrorCode.UNAVAILABLE,
+        'deadline-exceeded': CollectionErrorCode.DEADLINE_EXCEEDED,
+        'cancelled': CollectionErrorCode.CANCELLED,
+        'internal': CollectionErrorCode.INTERNAL_ERROR,
+        'data-loss': CollectionErrorCode.DATA_LOSS,
+        'failed-precondition': CollectionErrorCode.FAILED_PRECONDITION,
+        'aborted': CollectionErrorCode.ABORTED,
+        'out-of-range': CollectionErrorCode.OUT_OF_RANGE,
+        'unimplemented': CollectionErrorCode.UNIMPLEMENTED,
+        'resource-exhausted': CollectionErrorCode.RESOURCE_EXHAUSTED
+    };
+    const code = codeMap[err.code] ?? CollectionErrorCode.UNKNOWN;
+    return new CollectionError(code, err.message, path, undefined, err);
+}
+// ── Query builder ─────────────────────────────────────────────────────────────
 /**
- * Query builder implementation for type-safe query construction
+ * Fluent query builder — wraps Firestore QueryConstraints.
+ *
+ * @example
+ * ```ts
+ * const constraints = new FirekitQueryBuilder<Post>()
+ *   .where('published', '==', true)
+ *   .orderBy('createdAt', 'desc')
+ *   .limit(20)
+ *   .build();
+ * ```
  */
-class FirekitQueryBuilder {
+export class FirekitQueryBuilder {
     constraints = [];
     where(field, operator, value) {
         this.constraints.push(where(field, operator, value));
@@ -24,6 +54,10 @@ class FirekitQueryBuilder {
         this.constraints.push(limit(count));
         return this;
     }
+    limitToLast(count) {
+        this.constraints.push(limitToLast(count));
+        return this;
+    }
     startAt(...values) {
         this.constraints.push(startAt(...values));
         return this;
@@ -43,754 +77,414 @@ class FirekitQueryBuilder {
     build() {
         return [...this.constraints];
     }
+    /** Convenience — returns the constructed Firestore Query for a given collection ref. */
+    buildQuery(ref) {
+        return query(ref, ...this.constraints);
+    }
 }
+// ── Main class ────────────────────────────────────────────────────────────────
 /**
- * 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}
  * ```
  */
-class FirekitCollection {
-    // Reactive state using Svelte 5 runes
+export class FirekitCollection {
+    // ── Reactive state ────────────────────────────────────────────────────────
     _data = $state([]);
     _loading = $state(true);
-    _initialized = $state(false);
     _error = $state(null);
-    _lastUpdated = $state(null);
-    // Internal state
-    collectionRef = null;
-    queryRef = null;
-    unsubscribe = null;
-    options;
-    stats = this.initializeStats();
-    cache = new Map();
-    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, constraintsOrOptions, ...additionalConstraints) {
-        this.collectionPath = path;
-        // Parse constructor arguments
-        if (Array.isArray(constraintsOrOptions)) {
-            // Old style: path, ...constraints
-            this.options = {};
-            this.initializeCollection([...constraintsOrOptions, ...additionalConstraints]);
-        }
-        else {
-            // New style: path, options, ...constraints
-            this.options = constraintsOrOptions || {};
-            // Only use additionalConstraints since options object doesn't contain constraints
-            this.initializeCollection(additionalConstraints);
-        }
-    }
-    /**
-     * Initialize statistics object
-     */
-    initializeStats() {
-        return {
-            totalDocuments: 0,
-            readCount: 0,
-            writeCount: 0,
-            cacheHitRate: 0,
-            averageQueryTime: 0,
-            lastActivity: new Date(),
-            memoryUsage: 0
+    _size = $state(0);
+    _fromCache = $state(false);
+    _hasPendingWrites = $state(false);
+    // ── Derived ───────────────────────────────────────────────────────────────
+    isEmpty = $derived(!this._loading && this._size === 0);
+    hasData = $derived(this._size > 0);
+    isReady = $derived(!this._loading && this._error === null);
+    // ── Pagination state ──────────────────────────────────────────────────────
+    _pageSize = $state(0); // 0 = pagination disabled
+    _currentPage = $state(1);
+    _hasMore = $state(false);
+    // Cursors are not reactive — they are internal implementation detail
+    _lastVisible = null;
+    _cursorStack = [];
+    // ── Internal ──────────────────────────────────────────────────────────────
+    _unsubscribe = null;
+    _path;
+    _constraints;
+    _options;
+    _isGroup;
+    constructor(path, constraints = [], options = {}, isGroup = false) {
+        this._path = path;
+        this._constraints = constraints;
+        this._isGroup = isGroup;
+        this._options = {
+            realtime: true,
+            includeMetadata: false,
+            transform: (doc) => doc,
+            filter: () => true,
+            ...options
         };
-    }
-    /**
-     * Initialize collection subscription
-     */
-    async initializeCollection(constraints) {
-        if (!browser)
+        this._init();
+    }
+    // ── Public getters ────────────────────────────────────────────────────────
+    get data() { return this._data; }
+    get loading() { return this._loading; }
+    get error() { return this._error; }
+    get size() { return this._size; }
+    get path() { return this._path; }
+    get fromCache() { return this._fromCache; }
+    get hasPendingWrites() { return this._hasPendingWrites; }
+    get pageSize() { return this._pageSize; }
+    get currentPage() { return this._currentPage; }
+    get hasMore() { return this._hasMore; }
+    // ── Initialization ────────────────────────────────────────────────────────
+    _buildQuery() {
+        const db = getDb();
+        const ref = this._isGroup
+            ? collectionGroup(db, this._path)
+            : collection(db, this._path);
+        return query(ref, ...this._constraints);
+    }
+    _init() {
+        if (typeof window === 'undefined') {
+            this._loading = false;
             return;
+        }
         try {
-            const firestore = firebaseService.getDbInstance();
-            if (!firestore) {
-                throw new CollectionError(CollectionErrorCode.COLLECTION_UNAVAILABLE, 'Firestore instance not available', this.collectionPath);
-            }
-            // Check cache first
-            const cacheKey = this.getCacheKey(constraints);
-            if (this.options.cache?.enabled && this.isCacheValid(cacheKey)) {
-                const cached = this.cache.get(cacheKey);
-                this._data = cached.data;
-                this._loading = false;
-                this._initialized = true;
-                this._lastUpdated = cached.timestamp;
-                this.stats.cacheHitRate = (this.stats.cacheHitRate + 1) / 2;
-            }
-            // Create collection reference
-            this.collectionRef = collection(firestore, this.collectionPath);
-            // Create query with constraints
-            this.queryRef =
-                constraints.length > 0 ? query(this.collectionRef, ...constraints) : this.collectionRef;
-            // Set up real-time listener or one-time fetch
-            if (this.options.realtime !== false) {
-                this.setupRealtimeListener();
+            if (this._options.realtime) {
+                this._subscribe();
             }
             else {
-                await this.fetchOnce();
+                this._fetchOnce();
             }
         }
-        catch (error) {
-            this.handleError(error);
+        catch (err) {
+            this._error = new CollectionError(CollectionErrorCode.REFERENCE_UNAVAILABLE, err instanceof Error ? err.message : String(err), this._path);
+            this._loading = false;
         }
     }
-    /**
-     * Set up real-time document listener
-     */
-    setupRealtimeListener() {
-        if (!this.queryRef)
-            return;
-        const options = {
-            includeMetadataChanges: this.options.includeMetadata || false
-        };
-        this.unsubscribe = onSnapshot(this.queryRef, options, (snapshot) => {
-            this.processSnapshot(snapshot);
-        }, (error) => {
-            this.handleError(error);
+    _subscribe() {
+        const q = this._buildQuery();
+        this._unsubscribe = onSnapshot(q, { includeMetadataChanges: this._options.includeMetadata }, (snap) => this._handleSnapshot(snap), (err) => {
+            this._error = mapFirestoreError(err, this._path);
+            this._loading = false;
         });
     }
-    /**
-     * Fetch collection data once (no real-time updates)
-     */
-    async fetchOnce() {
-        if (!this.queryRef)
-            return;
+    async _fetchOnce() {
         try {
-            this._loading = true;
-            const startTime = Date.now();
-            const snapshot = await getDocs(this.queryRef);
-            const queryTime = Date.now() - startTime;
-            this.stats.averageQueryTime = (this.stats.averageQueryTime + queryTime) / 2;
-            this.processSnapshot(snapshot);
+            const snap = await getDocs(this._buildQuery());
+            this._handleSnapshot(snap);
         }
-        catch (error) {
-            this.handleError(error);
-        }
-    }
-    /**
-     * Process query snapshot and update state
-     */
-    processSnapshot(snapshot) {
-        try {
-            const startTime = Date.now();
-            // Extract documents with ID
-            let documents = snapshot.docs.map((doc) => {
-                const data = doc.data();
-                return { id: doc.id, ...data };
-            });
-            // Apply transform function if provided
-            if (this.options.transform) {
-                documents = documents.map(this.options.transform);
-            }
-            // Apply filter function if provided
-            if (this.options.filter) {
-                documents = documents.filter(this.options.filter);
-            }
-            // Apply sort function if provided
-            if (this.options.sort) {
-                documents = documents.sort(this.options.sort);
-            }
-            // Track document changes for events
-            const changes = this.calculateChanges(this._data, documents);
-            // Update reactive state
-            this._data = documents;
+        catch (err) {
+            this._error = mapFirestoreError(err, this._path);
             this._loading = false;
-            this._initialized = true;
-            this._error = null;
-            this._lastUpdated = new Date();
-            // Update statistics
-            this.stats.totalDocuments = documents.length;
-            this.stats.readCount++;
-            this.stats.lastActivity = new Date();
-            this.stats.memoryUsage = this.calculateMemoryUsage(documents);
-            // Update cache if enabled
-            if (this.options.cache?.enabled) {
-                const cacheKey = this.getCacheKey([]);
-                this.cache.set(cacheKey, {
-                    data: documents,
-                    timestamp: new Date()
-                });
-                this.cleanupCache();
-            }
-        }
-        catch (error) {
-            this.handleError(error);
         }
     }
-    /**
-     * Calculate changes between old and new document arrays
-     */
-    calculateChanges(oldDocs, newDocs) {
-        const changes = [];
-        const oldMap = new Map(oldDocs.map((doc, index) => [doc.id, { doc, index }]));
-        const newMap = new Map(newDocs.map((doc, index) => [doc.id, { doc, index }]));
-        // Find added and modified documents
-        newDocs.forEach((newDoc, newIndex) => {
-            const id = newDoc.id;
-            const oldEntry = oldMap.get(id);
-            if (!oldEntry) {
-                // Document was added
-                changes.push({
-                    type: 'added',
-                    doc: newDoc,
-                    oldIndex: -1,
-                    newIndex,
-                    timestamp: new Date()
-                });
-            }
-            else if (JSON.stringify(oldEntry.doc) !== JSON.stringify(newDoc)) {
-                // Document was modified
-                changes.push({
-                    type: 'modified',
-                    doc: newDoc,
-                    oldIndex: oldEntry.index,
-                    newIndex,
-                    timestamp: new Date()
-                });
-            }
+    _handleSnapshot(snap) {
+        const docs = snap.docs.map((d) => {
+            const raw = { id: d.id, ...d.data() };
+            return this._options.transform(raw);
         });
-        // Find removed documents
-        oldDocs.forEach((oldDoc, oldIndex) => {
-            const id = oldDoc.id;
-            if (!newMap.has(id)) {
-                changes.push({
-                    type: 'removed',
-                    doc: oldDoc,
-                    oldIndex,
-                    newIndex: -1,
-                    timestamp: new Date()
-                });
-            }
-        });
-        return changes;
-    }
-    /**
-     * Handle and process errors
-     */
-    handleError(error) {
-        let collectionError;
-        if (error instanceof CollectionError) {
-            collectionError = error;
-        }
-        else {
-            // Map Firestore errors to CollectionError
-            const code = this.mapFirestoreErrorCode(error.code);
-            collectionError = new CollectionError(code, error.message || 'An unknown error occurred', this.collectionPath, [], error);
-        }
-        this._error = collectionError;
+        this._data = this._options.filter ? docs.filter(this._options.filter) : docs;
+        this._size = this._data.length;
+        this._fromCache = snap.metadata.fromCache;
+        this._hasPendingWrites = snap.metadata.hasPendingWrites;
+        this._error = null;
         this._loading = false;
-        console.error('FirekitCollection error:', collectionError);
-    }
-    /**
-     * Map Firestore error codes to CollectionErrorCode
-     */
-    mapFirestoreErrorCode(firestoreCode) {
-        switch (firestoreCode) {
-            case 'permission-denied':
-                return CollectionErrorCode.PERMISSION_DENIED;
-            case 'not-found':
-                return CollectionErrorCode.NOT_FOUND;
-            case 'unavailable':
-                return CollectionErrorCode.UNAVAILABLE;
-            case 'deadline-exceeded':
-                return CollectionErrorCode.DEADLINE_EXCEEDED;
-            case 'unauthenticated':
-                return CollectionErrorCode.UNAUTHENTICATED;
-            case 'resource-exhausted':
-                return CollectionErrorCode.RESOURCE_EXHAUSTED;
-            case 'failed-precondition':
-                return CollectionErrorCode.FAILED_PRECONDITION;
-            case 'aborted':
-                return CollectionErrorCode.ABORTED;
-            case 'out-of-range':
-                return CollectionErrorCode.OUT_OF_RANGE;
-            case 'unimplemented':
-                return CollectionErrorCode.UNIMPLEMENTED;
-            case 'internal':
-                return CollectionErrorCode.INTERNAL_ERROR;
-            case 'data-loss':
-                return CollectionErrorCode.DATA_LOSS;
-            case 'cancelled':
-                return CollectionErrorCode.CANCELLED;
-            default:
-                return CollectionErrorCode.UNKNOWN;
-        }
-    }
-    /**
-     * Generate cache key for query
-     */
-    getCacheKey(constraints) {
-        if (this.options.cache?.customKey) {
-            return this.options.cache.customKey(this.collectionPath, constraints);
-        }
-        // More reliable constraint serialization
-        const constraintString = constraints
-            .map((c) => {
-            try {
-                return JSON.stringify(c);
-            }
-            catch {
-                return c.toString();
-            }
-        })
-            .join('|');
-        return `${this.collectionPath}:${constraintString}`;
-    }
-    /**
-     * Check if cache entry is still valid
-     */
-    isCacheValid(cacheKey) {
-        const cached = this.cache.get(cacheKey);
-        if (!cached)
-            return false;
-        const ttl = this.options.cache?.ttl || 300000; // 5 minutes default
-        return Date.now() - cached.timestamp.getTime() < ttl;
-    }
-    /**
-     * Clean up expired cache entries
-     */
-    cleanupCache() {
-        const maxSize = this.options.cache?.maxSize || 100;
-        const ttl = this.options.cache?.ttl || 300000;
-        const now = Date.now();
-        // Remove expired entries
-        for (const [key, entry] of this.cache.entries()) {
-            if (now - entry.timestamp.getTime() > ttl) {
-                this.cache.delete(key);
-            }
-        }
-        // Remove oldest entries if cache is too large
-        if (this.cache.size > maxSize) {
-            const entries = Array.from(this.cache.entries()).sort((a, b) => a[1].timestamp.getTime() - b[1].timestamp.getTime());
-            const toRemove = entries.slice(0, this.cache.size - maxSize);
-            toRemove.forEach(([key]) => this.cache.delete(key));
+        // Track cursors for pagination
+        if (snap.docs.length > 0) {
+            this._lastVisible = snap.docs[snap.docs.length - 1];
         }
     }
+    // ── Paginated fetch ───────────────────────────────────────────────────────
     /**
-     * Calculate memory usage of documents
+     * 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).
      */
-    calculateMemoryUsage(documents) {
+    async _fetchPage(cursor, append = false) {
+        this._loading = true;
         try {
-            return JSON.stringify(documents).length * 2; // Rough estimate
+            const base = this._buildQuery();
+            const paginatedQuery = cursor
+                ? query(base, startAfter(cursor), limit(this._pageSize + 1))
+                : query(base, limit(this._pageSize + 1));
+            const snap = await getDocs(paginatedQuery);
+            const allDocs = snap.docs;
+            this._hasMore = allDocs.length > this._pageSize;
+            const pageDocs = allDocs.slice(0, this._pageSize);
+            if (pageDocs.length > 0) {
+                this._lastVisible = pageDocs[pageDocs.length - 1];
+            }
+            const mapped = pageDocs.map((d) => {
+                const raw = { id: d.id, ...d.data() };
+                return this._options.transform(raw);
+            });
+            const filtered = this._options.filter ? mapped.filter(this._options.filter) : mapped;
+            this._data = append ? [...this._data, ...filtered] : filtered;
+            this._size = this._data.length;
+            this._fromCache = snap.metadata.fromCache;
+            this._hasPendingWrites = snap.metadata.hasPendingWrites;
+            this._error = null;
         }
-        catch {
-            return 0;
+        catch (err) {
+            this._error = mapFirestoreError(err, this._path);
         }
-    }
-    // ========================================
-    // REACTIVE GETTERS (Public API)
-    // ========================================
-    /**
-     * Get current collection data
-     */
-    get data() {
-        return this._data;
-    }
-    /**
-     * Get loading state
-     */
-    get loading() {
-        return this._loading;
-    }
-    /**
-     * Get initialization state
-     */
-    get initialized() {
-        return this._initialized;
-    }
-    /**
-     * Get error state
-     */
-    get error() {
-        return this._error;
-    }
-    /**
-     * Check if collection is empty
-     */
-    get empty() {
-        return this._data.length === 0;
-    }
-    /**
-     * Get number of documents
-     */
-    get size() {
-        return this._data.length;
-    }
-    /**
-     * Get last update timestamp
-     */
-    get lastUpdated() {
-        return this._lastUpdated;
-    }
-    /**
-     * Get collection reference
-     */
-    get ref() {
-        if (!this.collectionRef) {
-            throw new CollectionError(CollectionErrorCode.REFERENCE_UNAVAILABLE, 'Collection reference not available', this.collectionPath);
-        }
-        return this.collectionRef;
-    }
-    /**
-     * Get query reference
-     */
-    get queryReference() {
-        if (!this.queryRef) {
-            throw new CollectionError(CollectionErrorCode.REFERENCE_UNAVAILABLE, 'Query reference not available', this.collectionPath);
+        finally {
+            this._loading = false;
         }
-        return this.queryRef;
     }
-    /**
-     * Get collection path
-     */
-    get path() {
-        return this.collectionPath;
-    }
-    /**
-     * Get collection state summary
-     */
-    get state() {
-        return {
-            data: this._data,
-            loading: this._loading,
-            initialized: this._initialized,
-            error: this._error,
-            empty: this.empty,
-            size: this.size,
-            lastUpdated: this._lastUpdated
-        };
-    }
-    // ========================================
-    // PUBLIC METHODS
-    // ========================================
-    /**
-     * Manually refresh collection data
-     */
+    // ── Public methods ────────────────────────────────────────────────────────
+    /** Re-fetches from cache or server. */
     async refresh() {
-        if (!this.queryRef) {
-            throw new CollectionError(CollectionErrorCode.REFERENCE_UNAVAILABLE, 'Cannot refresh: query reference not available', this.collectionPath);
-        }
+        this._loading = true;
         try {
-            this._loading = true;
-            const snapshot = await getDocs(this.queryRef);
-            this.processSnapshot(snapshot);
+            const snap = await getDocs(this._buildQuery());
+            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)
-     */
+    /** Forces a fetch directly from the Firestore server (bypasses cache). */
     async getFromServer() {
-        if (!this.queryRef) {
-            throw new CollectionError(CollectionErrorCode.REFERENCE_UNAVAILABLE, 'Cannot fetch: query reference not available', this.collectionPath);
-        }
+        this._loading = true;
         try {
-            const snapshot = await getDocs(this.queryRef);
-            return snapshot.docs.map((doc) => {
-                const data = doc.data();
-                return { id: doc.id, ...data };
-            });
+            const snap = await getDocsFromServer(this._buildQuery());
+            this._handleSnapshot(snap);
         }
-        catch (error) {
-            this.handleError(error);
-            throw error;
+        catch (err) {
+            this._error = mapFirestoreError(err, this._path);
+            this._loading = false;
         }
     }
     /**
-     * Add query constraints to existing query
+     * Returns the server-side document count (uses Firestore aggregation query).
+     * Does not download the documents.
      */
-    addConstraints(...constraints) {
-        if (!this.collectionRef) {
-            throw new CollectionError(CollectionErrorCode.REFERENCE_UNAVAILABLE, 'Cannot add constraints: collection reference not available', this.collectionPath);
-        }
-        const newQuery = query(this.queryRef || this.collectionRef, ...constraints);
-        const newCollection = new FirekitCollection(this.collectionPath, this.options);
-        newCollection.queryRef = newQuery;
-        newCollection.initializeCollection([]);
-        return newCollection;
+    async countFromServer() {
+        const snap = await getCountFromServer(this._buildQuery());
+        return snap.data().count;
     }
     /**
-     * Create a new query builder for this collection
+     * Replaces the current query constraints and re-fetches.
      */
-    createQuery() {
-        return new FirekitQueryBuilder();
+    async setConstraints(constraints) {
+        this._unsubscribe?.();
+        this._unsubscribe = null;
+        this._constraints = constraints;
+        this._loading = true;
+        if (this._options.realtime) {
+            this._subscribe();
+        }
+        else {
+            await this._fetchOnce();
+        }
     }
     /**
-     * Apply new query constraints
+     * Appends additional constraints (e.g. pagination cursor) and re-fetches.
      */
-    withQuery(builder) {
-        return this.addConstraints(...builder.build());
+    async addConstraints(constraints) {
+        return this.setConstraints([...this._constraints, ...constraints]);
     }
-    /**
-     * Filter documents by predicate
-     */
+    /** Switches between real-time and one-time mode. */
+    setRealtimeMode(enabled) {
+        if (enabled === this._options.realtime)
+            return;
+        this._options.realtime = enabled;
+        if (!enabled) {
+            this._unsubscribe?.();
+            this._unsubscribe = null;
+        }
+        else {
+            this._subscribe();
+        }
+    }
+    // ── Client-side convenience ───────────────────────────────────────────────
+    /** Client-side filter (does NOT modify the Firestore query). */
     filter(predicate) {
         return this._data.filter(predicate);
     }
-    /**
-     * Find first document matching predicate
-     */
+    /** Finds the first document matching a predicate. */
     find(predicate) {
         return this._data.find(predicate);
     }
-    /**
-     * Find document by ID
-     */
+    /** Finds a document by its Firestore document ID. */
     findById(id) {
-        return this._data.find((doc) => doc.id === id);
+        return this._data.find((d) => d.id === id);
     }
-    /**
-     * Sort documents by field or custom function
-     */
+    /** Client-side sort (returns a new array, does NOT modify stored data). */
     sort(compareFn) {
         return [...this._data].sort(compareFn);
     }
+    // ── Pagination ────────────────────────────────────────────────────────────
     /**
-     * Get paginated subset of documents
-     */
-    paginate(page, pageSize) {
-        const startIndex = (page - 1) * pageSize;
-        const endIndex = startIndex + pageSize;
-        return this._data.slice(startIndex, endIndex);
-    }
-    /**
-     * Group documents by field value
-     */
-    groupBy(field) {
-        const groups = new Map();
-        this._data.forEach((doc) => {
-            const key = doc[field];
-            if (!groups.has(key)) {
-                groups.set(key, []);
-            }
-            groups.get(key).push(doc);
-        });
-        return groups;
-    }
-    /**
-     * Get unique values for a field
-     */
-    unique(field) {
-        const values = this._data.map((doc) => doc[field]);
-        return Array.from(new Set(values));
-    }
-    /**
-     * Count documents matching predicate
-     */
-    count(predicate) {
-        return predicate ? this._data.filter(predicate).length : this._data.length;
-    }
-    /**
-     * Check if any document matches predicate
-     */
-    some(predicate) {
-        return this._data.some(predicate);
-    }
-    /**
-     * Check if all documents match predicate
-     */
-    every(predicate) {
-        return this._data.every(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
+     * ```
+     */
+    async setPagination(pageSize) {
+        this._unsubscribe?.();
+        this._unsubscribe = null;
+        this._options.realtime = false;
+        this._pageSize = pageSize;
+        this._currentPage = 1;
+        this._lastVisible = null;
+        this._cursorStack = [];
+        await this._fetchPage(null);
+    }
+    /**
+     * Loads the next page, replacing the current data.
+     * Call `setPagination()` first.
+     */
+    async nextPage() {
+        if (this._pageSize === 0 || !this._hasMore || !this._lastVisible)
+            return;
+        this._cursorStack.push(this._lastVisible);
+        await this._fetchPage(this._lastVisible);
+        this._currentPage++;
     }
     /**
-     * Switch between realtime and one-time fetch modes
+     * Loads the previous page, replacing the current data.
      */
-    setRealtimeMode(realtime) {
-        if (this.options.realtime === realtime)
+    async prevPage() {
+        if (this._pageSize === 0 || this._currentPage <= 1)
             return;
-        this.options.realtime = realtime;
-        // Clean up existing listener
-        if (this.unsubscribe) {
-            this.unsubscribe();
-            this.unsubscribe = null;
-        }
-        // Set up new mode
-        if (realtime) {
-            this.setupRealtimeListener();
-        }
+        this._cursorStack.pop(); // remove current-page cursor
+        const prevCursor = this._cursorStack[this._cursorStack.length - 1] ?? null;
+        await this._fetchPage(prevCursor);
+        this._currentPage--;
+        // Always has more going backwards (we came from a later page)
+        this._hasMore = true;
     }
     /**
-     * Clear cache for this collection
+     * Appends the next page to existing data (infinite scroll).
+     * Call `setPagination()` first.
      */
-    clearCache() {
-        const cacheKey = this.getCacheKey([]);
-        this.cache.delete(cacheKey);
+    async loadMore() {
+        if (this._pageSize === 0 || !this._hasMore || !this._lastVisible)
+            return;
+        this._cursorStack.push(this._lastVisible);
+        await this._fetchPage(this._lastVisible, true);
+        this._currentPage++;
     }
     /**
-     * Get collection statistics
+     * Resets pagination back to the first page.
      */
-    getStats() {
-        return { ...this.stats };
+    async resetPagination() {
+        if (this._pageSize === 0)
+            return;
+        this._currentPage = 1;
+        this._lastVisible = null;
+        this._cursorStack = [];
+        await this._fetchPage(null);
     }
+    // ── Reactive path ─────────────────────────────────────────────────────────
     /**
-     * Reset statistics
-     */
-    resetStats() {
-        this.stats = this.initializeStats();
+     * 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');
+     * ```
+     */
+    setPath(newPath) {
+        this._unsubscribe?.();
+        this._unsubscribe = null;
+        this._path = newPath;
+        this._loading = true;
+        this._data = [];
+        this._error = null;
+        this._lastVisible = null;
+        this._cursorStack = [];
+        this._currentPage = 1;
+        this._init();
     }
     /**
-     * Wait for collection to initialize
+     * Resolves when the collection has finished its initial load.
      */
-    async waitForInitialization() {
+    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) => {
-            if (this._initialized) {
-                resolve(this._data);
-                return;
-            }
-            // Poll for initialization since we removed events
-            const checkInterval = setInterval(() => {
-                if (this._initialized) {
-                    clearInterval(checkInterval);
-                    resolve(this._data);
-                }
-            }, 100);
-            // Timeout after 10 seconds
-            setTimeout(() => {
-                clearInterval(checkInterval);
-                resolve(this._data);
-            }, 10000);
+            const stop = $effect.root(() => {
+                $effect(() => {
+                    if (!this._loading) {
+                        stop();
+                        resolve(this._data);
+                    }
+                });
+            });
         });
     }
-    // ========================================
-    // CLEANUP
-    // ========================================
-    /**
-     * Dispose of all resources and cleanup
-     */
+    /** Stops the real-time listener and frees resources. */
     dispose() {
-        // Unsubscribe from real-time updates
-        if (this.unsubscribe) {
-            this.unsubscribe();
-            this.unsubscribe = null;
-        }
-        // Clear cache
-        this.cache.clear();
-        // Reset state
-        this._data = [];
-        this._loading = false;
-        this._initialized = false;
-        this._error = null;
-        this._lastUpdated = null;
+        this._unsubscribe?.();
+        this._unsubscribe = null;
     }
 }
+// ── Collection group ──────────────────────────────────────────────────────────
 /**
- * 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>
+ * ```
  */
-class FirekitCollectionGroup extends FirekitCollection {
-    constructor(collectionId, constraintsOrOptions, ...additionalConstraints) {
-        // Initialize with empty options to avoid parent constructor issues
-        super(`__collection_group__${collectionId}`, {});
-        // Parse constructor arguments properly
-        if (Array.isArray(constraintsOrOptions)) {
-            this.options = {};
-            this.initializeCollectionGroup(collectionId, [
-                ...constraintsOrOptions,
-                ...additionalConstraints
-            ]);
-        }
-        else {
-            this.options = constraintsOrOptions || {};
-            this.initializeCollectionGroup(collectionId, additionalConstraints);
-        }
-    }
-    /**
-     * Initialize collection group subscription
-     */
-    async initializeCollectionGroup(collectionId, constraints) {
-        if (!browser)
-            return;
-        try {
-            const firestore = firebaseService.getDbInstance();
-            if (!firestore) {
-                throw new CollectionError(CollectionErrorCode.COLLECTION_UNAVAILABLE, 'Firestore instance not available', collectionId);
-            }
-            // Create collection group reference
-            const groupRef = collectionGroup(firestore, collectionId);
-            // Create query with constraints
-            this.queryRef =
-                constraints.length > 0
-                    ? query(groupRef, ...constraints)
-                    : groupRef;
-            // Set up real-time listener or one-time fetch
-            if (this.options.realtime !== false) {
-                this.setupRealtimeListener();
-            }
-            else {
-                await this.fetchOnce();
-            }
-        }
-        catch (error) {
-            this.handleError(error);
-        }
+export class FirekitCollectionGroup extends FirekitCollection {
+    constructor(collectionId, constraints = [], options = {}) {
+        super(collectionId, constraints, options, true);
     }
 }
-export function firekitCollection(path, constraintsOrOptions, ...additionalConstraints) {
-    if (Array.isArray(constraintsOrOptions)) {
-        return new FirekitCollection(path, [...constraintsOrOptions, ...additionalConstraints]);
-    }
-    else {
-        return new FirekitCollection(path, constraintsOrOptions, ...additionalConstraints);
-    }
+// ── Factory functions ─────────────────────────────────────────────────────────
+/**
+ * Creates a reactive Firestore collection with real-time updates.
+ *
+ * @example
+ * ```ts
+ * const posts = firekitCollection<Post>('posts', [where('published', '==', true)]);
+ * ```
+ */
+export function firekitCollection(path, constraints = [], options) {
+    return new FirekitCollection(path, constraints, { ...options, realtime: true });
 }
 /**
- * Creates a one-time collection fetch (no real-time updates)
+ * Creates a one-time Firestore collection fetch (no real-time listener).
  */
-export function firekitCollectionOnce(path, ...constraints) {
-    return new FirekitCollection(path, { realtime: false }, ...constraints);
+export function firekitCollectionOnce(path, constraints = [], options) {
+    return new FirekitCollection(path, constraints, { ...options, realtime: false });
 }
-export function firekitCollectionGroup(collectionId, constraintsOrOptions, ...additionalConstraints) {
-    if (Array.isArray(constraintsOrOptions)) {
-        return new FirekitCollectionGroup(collectionId, [
-            ...constraintsOrOptions,
-            ...additionalConstraints
-        ]);
-    }
-    else {
-        return new FirekitCollectionGroup(collectionId, constraintsOrOptions, ...additionalConstraints);
-    }
+/**
+ * Creates a reactive Firestore collection group query with real-time updates.
+ */
+export function firekitCollectionGroup(collectionId, constraints = [], options) {
+    return new FirekitCollectionGroup(collectionId, constraints, { ...options, realtime: true });
 }