svelte-firekit 0.0.21 → 0.0.22

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.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 {};

package/dist/firestore/collection.svelte.js

@@ -1,12 +1,61 @@
+/**
+ * @module FirekitCollection
+ */
 import { collection, query, onSnapshot } from "firebase/firestore";
 import { firebaseService } from "../firebase.js";
 import { browser } from "$app/environment";
+/**
+ * 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
+ * ```
+ */
 class FirekitCollection {
+    /** Current collection data */
     _data = $state([]);
+    /** Loading state */
     _loading = $state(true);
+    /** Error state */
     _error = $state(null);
+    /** Collection reference */
     colRef = null;
+    /** Query reference */
     queryRef = null;
+    /**
+     * 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, ...queryConstraints) {
         if (browser) {
             try {
@@ -31,21 +80,30 @@ class FirekitCollection {
             }
         }
     }
+    /** Gets current collection 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 is empty */
     get empty() {
         return this._data.length === 0;
     }
+    /** Gets number of documents in collection */
     get size() {
         return this._data.length;
     }
+    /**
+     * Gets collection reference
+     * @throws {Error} If collection reference is not available
+     */
     get ref() {
         if (!this.colRef) {
             throw new Error("Collection reference is not available");
@@ -53,6 +111,27 @@ class FirekitCollection {
         return this.colRef;
     }
 }
+/**
+ * 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 function firekitCollection(path, ...queryConstraints) {
     return new FirekitCollection(path, ...queryConstraints);
 }

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

@@ -1,16 +1,90 @@
+/**
+ * @module FirekitDoc
+ */
 import { DocumentReference } from "firebase/firestore";
+/**
+ * Manages real-time Firestore document subscriptions with reactive state
+ * @class
+ * @template T Document data type
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // Create document subscription
+ * const userDoc = firekitDoc<User>('users/123', {
+ *   id: '123',
+ *   name: 'Loading...',
+ *   email: ''
+ * });
+ * ```
+ */
 declare class FirekitDoc<T> {
+    /** Current document data */
     private _data;
+    /** Loading state */
     private _loading;
+    /** Error state */
     private _error;
+    /** Document reference */
     private docRef;
+    /**
+     * Creates a document subscription
+     * @param {string | DocumentReference<T>} ref Document path or reference
+     * @param {T} [startWith] Initial data before fetch completes
+     *
+     * @example
+     * ```typescript
+     * const doc = new FirekitDoc('users/123', defaultUser);
+     * // or
+     * const doc = new FirekitDoc(docRef, defaultUser);
+     * ```
+     */
     constructor(ref: string | DocumentReference<T>, startWith?: T);
+    /** Gets current document data */
     get data(): T | null;
+    /** Gets document ID */
     get id(): string;
+    /** Gets loading state */
     get loading(): boolean;
+    /** Gets error state */
     get error(): Error | null;
-    get ref(): DocumentReference<T, import("@firebase/firestore").DocumentData>;
+    /**
+     * Gets document reference
+     * @throws {Error} If document reference is not available
+     */
+    get ref(): DocumentReference<T>;
+    /** Checks if document exists */
     get exists(): boolean;
 }
+/**
+ * Creates a document subscription
+ * @template T Document data type
+ * @param {string | DocumentReference<T>} ref Document path or reference
+ * @param {T} [startWith] Initial data before fetch completes
+ * @returns {FirekitDoc<T>} Document subscription instance
+ *
+ * @example
+ * ```typescript
+ * const userDoc = firekitDoc<User>('users/123', {
+ *   id: '123',
+ *   name: 'Loading...',
+ *   email: ''
+ * });
+ *
+ * // Access reactive state
+ * if (userDoc.loading) {
+ *   console.log('Loading...');
+ * } else if (userDoc.error) {
+ *   console.error(userDoc.error);
+ * } else if (userDoc.exists) {
+ *   console.log(userDoc.data);
+ * }
+ * ```
+ */
 export declare function firekitDoc<T>(ref: string | DocumentReference<T>, startWith?: T): FirekitDoc<T>;
 export {};