svelte-firekit 0.0.21 → 0.0.23

package/dist/firestore/awaitable-doc.svelte.d.ts

@@ -1,15 +1,141 @@
+/**
+ * @module FirekitAwaitableDoc
+ */
 import { type DocumentReference, type DocumentData } from "firebase/firestore";
+/**
+ * Provides real-time document subscription with state management.
+ * Automatically handles document data updates, loading states, and error handling.
+ *
+ * @class
+ * @template T Type of document data
+ * @example
+ * ```typescript
+ * interface UserProfile {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // Create document subscription
+ * const userDoc = firekitAwaitableDoc<UserProfile>(
+ *   'users/123',
+ *   { id: '123', name: 'Loading...', email: '' }
+ * );
+ *
+ * // Access reactive state
+ * if (userDoc.loading) {
+ *   console.log('Loading user data...');
+ * } else if (userDoc.error) {
+ *   console.error('Error:', userDoc.error);
+ * } else {
+ *   console.log('User data:', userDoc.data);
+ * }
+ *
+ * // Get fresh data
+ * const freshData = await userDoc.getData();
+ * ```
+ */
 declare class FirekitAwaitableDoc<T> {
+    /**
+     * Current document data.
+     * Uses SvelteKit's $state for reactivity.
+     * @private
+     */
     private _data;
+    /**
+     * Loading state indicator.
+     * Uses SvelteKit's $state for reactivity.
+     * @private
+     */
     private _loading;
+    /**
+     * Error state container.
+     * Uses SvelteKit's $state for reactivity.
+     * @private
+     */
     private _error;
+    /**
+     * Firestore document reference.
+     * @private
+     */
     private docRef;
+    /**
+     * Creates a document subscription.
+     * Initializes document subscription if in browser environment.
+     *
+     * @param {string | DocumentReference<T>} ref - Document path or reference
+     * @param {T} [startWith] - Initial data before fetch completes
+     *
+     * @example
+     * ```typescript
+     * const doc = new FirekitAwaitableDoc('users/123', defaultUser);
+     * ```
+     */
     constructor(ref: string | DocumentReference<T>, startWith?: T);
+    /**
+     * Initializes document subscription.
+     * Sets up real-time updates and handles initial data fetch.
+     *
+     * @private
+     * @param {string | DocumentReference<T>} ref - Document path or reference
+     * @returns {Promise<void>}
+     *
+     * @throws {Error} If document initialization fails
+     */
     private initializeDoc;
+    /**
+     * Fetches fresh document data.
+     * Makes a new request to Firestore instead of using cached data.
+     *
+     * @returns {Promise<T | null>} Document data or null if not found
+     *
+     * @example
+     * ```typescript
+     * const freshData = await doc.getData();
+     * if (freshData) {
+     *   console.log('Fresh data:', freshData);
+     * }
+     * ```
+     */
     getData(): Promise<T | null>;
+    /**
+     * Gets current document data.
+     * @returns {T | null} Current document data or null if not loaded
+     */
     get data(): T | null;
+    /**
+     * Gets current loading state.
+     * @returns {boolean} True if document is loading
+     */
     get loading(): boolean;
+    /**
+     * Gets current error state.
+     * @returns {Error | null} Error object if an error occurred, null otherwise
+     */
     get error(): Error | null;
 }
+/**
+ * Creates a document subscription.
+ * Factory function for creating FirekitAwaitableDoc instances.
+ *
+ * @template T Document data type
+ * @param {string} path Document path
+ * @param {T} [startWith] Initial data before fetch completes
+ * @returns {FirekitAwaitableDoc<T>} Document subscription instance
+ *
+ * @example
+ * ```typescript
+ * interface UserProfile {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const userDoc = firekitAwaitableDoc<UserProfile>(
+ *   'users/123',
+ *   { id: '123', name: 'Loading...', email: '' }
+ * );
+ * ```
+ */
 export declare function firekitAwaitableDoc<T extends DocumentData>(path: string, startWith?: T): FirekitAwaitableDoc<T>;
 export {};

package/dist/firestore/awaitable-doc.svelte.js

@@ -1,17 +1,94 @@
+/**
+ * @module FirekitAwaitableDoc
+ */
 import { doc, getDoc, onSnapshot } from "firebase/firestore";
 import { firebaseService } from "../firebase.js";
 import { browser } from "$app/environment";
+/**
+ * Provides real-time document subscription with state management.
+ * Automatically handles document data updates, loading states, and error handling.
+ *
+ * @class
+ * @template T Type of document data
+ * @example
+ * ```typescript
+ * interface UserProfile {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // Create document subscription
+ * const userDoc = firekitAwaitableDoc<UserProfile>(
+ *   'users/123',
+ *   { id: '123', name: 'Loading...', email: '' }
+ * );
+ *
+ * // Access reactive state
+ * if (userDoc.loading) {
+ *   console.log('Loading user data...');
+ * } else if (userDoc.error) {
+ *   console.error('Error:', userDoc.error);
+ * } else {
+ *   console.log('User data:', userDoc.data);
+ * }
+ *
+ * // Get fresh data
+ * const freshData = await userDoc.getData();
+ * ```
+ */
 class FirekitAwaitableDoc {
+    /**
+     * Current document data.
+     * Uses SvelteKit's $state for reactivity.
+     * @private
+     */
     _data = $state(null);
+    /**
+     * Loading state indicator.
+     * Uses SvelteKit's $state for reactivity.
+     * @private
+     */
     _loading = $state(true);
+    /**
+     * Error state container.
+     * Uses SvelteKit's $state for reactivity.
+     * @private
+     */
     _error = $state(null);
+    /**
+     * Firestore document reference.
+     * @private
+     */
     docRef = null;
+    /**
+     * Creates a document subscription.
+     * Initializes document subscription if in browser environment.
+     *
+     * @param {string | DocumentReference<T>} ref - Document path or reference
+     * @param {T} [startWith] - Initial data before fetch completes
+     *
+     * @example
+     * ```typescript
+     * const doc = new FirekitAwaitableDoc('users/123', defaultUser);
+     * ```
+     */
     constructor(ref, startWith) {
         this._data = startWith ?? null;
         if (browser) {
             this.initializeDoc(ref);
         }
     }
+    /**
+     * Initializes document subscription.
+     * Sets up real-time updates and handles initial data fetch.
+     *
+     * @private
+     * @param {string | DocumentReference<T>} ref - Document path or reference
+     * @returns {Promise<void>}
+     *
+     * @throws {Error} If document initialization fails
+     */
     async initializeDoc(ref) {
         try {
             const firestore = firebaseService.getDbInstance();
@@ -36,22 +113,71 @@ class FirekitAwaitableDoc {
             this._loading = false;
         }
     }
+    /**
+     * Fetches fresh document data.
+     * Makes a new request to Firestore instead of using cached data.
+     *
+     * @returns {Promise<T | null>} Document data or null if not found
+     *
+     * @example
+     * ```typescript
+     * const freshData = await doc.getData();
+     * if (freshData) {
+     *   console.log('Fresh data:', freshData);
+     * }
+     * ```
+     */
     async getData() {
         if (!this.docRef)
             return null;
         const snapshot = await getDoc(this.docRef);
         return snapshot.exists() ? { id: snapshot.id, ...snapshot.data() } : null;
     }
+    /**
+     * Gets current document data.
+     * @returns {T | null} Current document data or null if not loaded
+     */
     get data() {
         return this._data;
     }
+    /**
+     * Gets current loading state.
+     * @returns {boolean} True if document is loading
+     */
     get loading() {
         return this._loading;
     }
+    /**
+     * Gets current error state.
+     * @returns {Error | null} Error object if an error occurred, null otherwise
+     */
     get error() {
         return this._error;
     }
 }
+/**
+ * Creates a document subscription.
+ * Factory function for creating FirekitAwaitableDoc instances.
+ *
+ * @template T Document data type
+ * @param {string} path Document path
+ * @param {T} [startWith] Initial data before fetch completes
+ * @returns {FirekitAwaitableDoc<T>} Document subscription instance
+ *
+ * @example
+ * ```typescript
+ * interface UserProfile {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * const userDoc = firekitAwaitableDoc<UserProfile>(
+ *   'users/123',
+ *   { id: '123', name: 'Loading...', email: '' }
+ * );
+ * ```
+ */
 export function firekitAwaitableDoc(path, startWith) {
     return new FirekitAwaitableDoc(path, startWith);
 }

package/dist/firestore/collection-group.svelte.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @module FirekitCollectionGroup
+ */
+import { type Query, type DocumentData, type QueryConstraint } from "firebase/firestore";
+/**
+ * Manages real-time Firestore collection group subscriptions with reactive state
+ * @class
+ * @template T Collection document type
+ *
+ * @example
+ * ```typescript
+ * interface Task {
+ *   id: string;
+ *   title: string;
+ *   status: string;
+ * }
+ *
+ * // Create collection group subscription
+ * const allTasks = firekitCollectionGroup<Task>('tasks',
+ *   where('status', '==', 'active'),
+ *   orderBy('title')
+ * );
+ * ```
+ */
+declare class FirekitCollectionGroup<T> {
+    /** Current collection group data */
+    private _data;
+    /** Loading state */
+    private _loading;
+    /** Error state */
+    private _error;
+    /** Query reference */
+    private queryRef;
+    /**
+     * Creates a collection group subscription
+     * @param {string} collectionId Collection ID to query across all documents
+     * @param {...QueryConstraint[]} queryConstraints Query constraints (where, orderBy, limit, etc.)
+     */
+    constructor(collectionId: string, ...queryConstraints: QueryConstraint[]);
+    /** Gets current collection group data */
+    get data(): T[];
+    /** Gets loading state */
+    get loading(): boolean;
+    /** Gets error state */
+    get error(): Error | null;
+    /** Checks if collection group is empty */
+    get empty(): boolean;
+    /** Gets number of documents in collection group */
+    get size(): number;
+    /**
+     * Gets query reference
+     * @throws {Error} If query reference is not available
+     */
+    get ref(): Query<T>;
+}
+/**
+ * Creates a collection group subscription
+ * @template T Collection document type
+ * @param {string} collectionId Collection ID to query across all documents
+ * @param {...QueryConstraint[]} queryConstraints Query constraints
+ * @returns {FirekitCollectionGroup<T>} Collection group subscription instance
+ *
+ * @example
+ * ```typescript
+ * interface Comment {
+ *   id: string;
+ *   text: string;
+ *   userId: string;
+ * }
+ *
+ * const allComments = firekitCollectionGroup<Comment>('comments',
+ *   where('userId', '==', currentUserId),
+ *   orderBy('createdAt', 'desc')
+ * );
+ * ```
+ */
+export declare function firekitCollectionGroup<T extends DocumentData>(collectionId: string, ...queryConstraints: QueryConstraint[]): FirekitCollectionGroup<T>;
+export {};

package/dist/firestore/collection-group.svelte.js

@@ -0,0 +1,120 @@
+/**
+ * @module FirekitCollectionGroup
+ */
+import { collectionGroup, query, onSnapshot } from "firebase/firestore";
+import { firebaseService } from "../firebase.js";
+import { browser } from "$app/environment";
+/**
+ * Manages real-time Firestore collection group subscriptions with reactive state
+ * @class
+ * @template T Collection document type
+ *
+ * @example
+ * ```typescript
+ * interface Task {
+ *   id: string;
+ *   title: string;
+ *   status: string;
+ * }
+ *
+ * // Create collection group subscription
+ * const allTasks = firekitCollectionGroup<Task>('tasks',
+ *   where('status', '==', 'active'),
+ *   orderBy('title')
+ * );
+ * ```
+ */
+class FirekitCollectionGroup {
+    /** Current collection group data */
+    _data = $state([]);
+    /** Loading state */
+    _loading = $state(true);
+    /** Error state */
+    _error = $state(null);
+    /** Query reference */
+    queryRef = null;
+    /**
+     * Creates a collection group subscription
+     * @param {string} collectionId Collection ID to query across all documents
+     * @param {...QueryConstraint[]} queryConstraints Query constraints (where, orderBy, limit, etc.)
+     */
+    constructor(collectionId, ...queryConstraints) {
+        if (browser) {
+            try {
+                const firestore = firebaseService.getDbInstance();
+                const groupRef = collectionGroup(firestore, collectionId);
+                this.queryRef = query(groupRef, ...queryConstraints);
+                onSnapshot(this.queryRef, (snapshot) => {
+                    this._data = snapshot.docs.map(doc => ({
+                        id: doc.id,
+                        path: doc.ref.path,
+                        ...doc.data()
+                    }));
+                    this._loading = false;
+                    this._error = null;
+                }, (error) => {
+                    this._error = error;
+                    this._loading = false;
+                });
+            }
+            catch (error) {
+                this._error = error;
+                this._loading = false;
+            }
+        }
+    }
+    /** Gets current collection group data */
+    get data() {
+        return this._data;
+    }
+    /** Gets loading state */
+    get loading() {
+        return this._loading;
+    }
+    /** Gets error state */
+    get error() {
+        return this._error;
+    }
+    /** Checks if collection group is empty */
+    get empty() {
+        return this._data.length === 0;
+    }
+    /** Gets number of documents in collection group */
+    get size() {
+        return this._data.length;
+    }
+    /**
+     * Gets query reference
+     * @throws {Error} If query reference is not available
+     */
+    get ref() {
+        if (!this.queryRef) {
+            throw new Error("Query reference is not available");
+        }
+        return this.queryRef;
+    }
+}
+/**
+ * Creates a collection group subscription
+ * @template T Collection document type
+ * @param {string} collectionId Collection ID to query across all documents
+ * @param {...QueryConstraint[]} queryConstraints Query constraints
+ * @returns {FirekitCollectionGroup<T>} Collection group subscription instance
+ *
+ * @example
+ * ```typescript
+ * interface Comment {
+ *   id: string;
+ *   text: string;
+ *   userId: string;
+ * }
+ *
+ * const allComments = firekitCollectionGroup<Comment>('comments',
+ *   where('userId', '==', currentUserId),
+ *   orderBy('createdAt', 'desc')
+ * );
+ * ```
+ */
+export function firekitCollectionGroup(collectionId, ...queryConstraints) {
+    return new FirekitCollectionGroup(collectionId, ...queryConstraints);
+}

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

@@ -1,17 +1,96 @@
+/**
+ * @module FirekitCollection
+ */
 import { type CollectionReference, type DocumentData, type QueryConstraint } from "firebase/firestore";
+/**
+ * Manages real-time Firestore collection subscriptions with reactive state
+ * @class
+ * @template T Collection document type
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // Create collection subscription
+ * const users = firekitCollection<User>('users',
+ *   where('active', '==', true),
+ *   orderBy('name')
+ * );
+ *
+ * // Access reactive state
+ * console.log(users.data);    // Array of documents
+ * console.log(users.loading); // Loading state
+ * console.log(users.error);   // Error state
+ * console.log(users.empty);   // Whether collection is empty
+ * console.log(users.size);    // Number of documents
+ * ```
+ */
 declare class FirekitCollection<T> {
+    /** Current collection data */
     private _data;
+    /** Loading state */
     private _loading;
+    /** Error state */
     private _error;
+    /** Collection reference */
     private colRef;
+    /** Query reference */
     private queryRef;
+    /**
+     * Creates a collection subscription
+     * @param {string} path Collection path
+     * @param {...QueryConstraint[]} queryConstraints Query constraints (where, orderBy, limit, etc.)
+     *
+     * @example
+     * ```typescript
+     * const collection = new FirekitCollection('users',
+     *   where('age', '>=', 18),
+     *   orderBy('name', 'asc'),
+     *   limit(10)
+     * );
+     * ```
+     */
     constructor(path: string, ...queryConstraints: QueryConstraint[]);
+    /** Gets current collection data */
     get data(): T[];
+    /** Gets loading state */
     get loading(): boolean;
+    /** Gets error state */
     get error(): Error | null;
+    /** Checks if collection is empty */
     get empty(): boolean;
+    /** Gets number of documents in collection */
     get size(): number;
-    get ref(): CollectionReference<T, DocumentData>;
+    /**
+     * Gets collection reference
+     * @throws {Error} If collection reference is not available
+     */
+    get ref(): CollectionReference<T>;
 }
+/**
+ * Creates a collection subscription
+ * @template T Collection document type
+ * @param {string} path Collection path
+ * @param {...QueryConstraint[]} queryConstraints Query constraints
+ * @returns {FirekitCollection<T>} Collection subscription instance
+ *
+ * @example
+ * ```typescript
+ * interface Post {
+ *   id: string;
+ *   title: string;
+ *   authorId: string;
+ * }
+ *
+ * const posts = firekitCollection<Post>('posts',
+ *   where('authorId', '==', currentUserId),
+ *   orderBy('createdAt', 'desc')
+ * );
+ * ```
+ */
 export declare function firekitCollection<T extends DocumentData>(path: string, ...queryConstraints: QueryConstraint[]): FirekitCollection<T>;
 export {};