svelte-firekit 0.0.21 → 0.0.23

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

package/dist/firestore/doc.svelte.js

@@ -1,11 +1,51 @@
+/**
+ * @module FirekitDoc
+ */
 import { doc, DocumentReference, onSnapshot } from "firebase/firestore";
 import { firebaseService } from "../firebase.js";
 import { browser } from "$app/environment";
+/**
+ * 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: ''
+ * });
+ * ```
+ */
 class FirekitDoc {
+    /** Current document data */
     _data = $state(null);
+    /** Loading state */
     _loading = $state(true);
+    /** Error state */
     _error = $state(null);
+    /** Document reference */
     docRef = null;
+    /**
+     * 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, startWith) {
         this._data = startWith ?? null;
         if (browser) {
@@ -15,7 +55,6 @@ class FirekitDoc {
                     ? doc(firestore, ref)
                     : ref;
                 onSnapshot(this.docRef, (snapshot) => {
-                    // this._data = (snapshot.data() as T) ?? null;
                     const data = snapshot.data();
                     this._data = data ? { ...data, id: snapshot.id } : null;
                     this._loading = false;
@@ -31,28 +70,62 @@ class FirekitDoc {
             }
         }
     }
+    /** Gets current document data */
     get data() {
         return this._data;
     }
+    /** Gets document ID */
     get id() {
         return this.docRef?.id ?? '';
     }
+    /** Gets loading state */
     get loading() {
         return this._loading;
     }
+    /** Gets error state */
     get error() {
         return this._error;
     }
+    /**
+     * Gets document reference
+     * @throws {Error} If document reference is not available
+     */
     get ref() {
         if (this.docRef === null) {
             throw new Error("Document reference is not available yet.");
         }
         return this.docRef;
     }
+    /** Checks if document exists */
     get exists() {
         return this._data !== null;
     }
 }
+/**
+ * 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 function firekitDoc(ref, startWith) {
     return new FirekitDoc(ref, startWith);
 }

package/dist/firestore/document-mutations.svelte.d.ts

@@ -1,27 +1,164 @@
+/**
+ * @module FirekitDocumentMutations
+ */
 import { type DocumentData, type WithFieldValue, type PartialWithFieldValue } from "firebase/firestore";
+/**
+ * Response structure for document mutations
+ * @interface MutationResponse
+ * @template T Document data type
+ */
 interface MutationResponse<T> {
+    /** Operation success status */
     success: boolean;
+    /** Document data */
     data?: T;
+    /** Document ID */
     id?: string;
+    /** Error details if operation failed */
     error?: {
         code: string;
         message: string;
     };
 }
+/**
+ * Options for document mutations
+ * @interface MutationOptions
+ */
 interface MutationOptions {
+    /** Whether to include timestamp fields */
     timestamps?: boolean;
+    /** Whether to merge data in set operations */
     merge?: boolean;
+    /** Custom document ID for add operations */
     customId?: string;
 }
+/**
+ * Manages Firestore document mutations with automatic timestamps and error handling
+ * @class
+ * @example
+ * ```typescript
+ * // Add a new document
+ * const result = await firekitDocMutations.add('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * });
+ *
+ * // Update a document
+ * await firekitDocMutations.update('users/123', {
+ *   name: 'Jane Doe'
+ * });
+ *
+ * // Delete a document
+ * await firekitDocMutations.delete('users/123');
+ * ```
+ */
 declare class FirekitDocumentMutations {
+    /**
+     * Generates timestamp data for document mutations
+     * @private
+     * @param {boolean} [isNew=true] Whether this is a new document
+     * @returns {Record<string, any>} Timestamp data
+     */
     private getTimestampData;
+    /**
+     * Handles and formats mutation errors
+     * @private
+     * @param {any} error Error object
+     * @returns {MutationResponse<never>} Formatted error response
+     */
     private handleError;
+    /**
+     * Adds a new document to a collection
+     * @template T Document data type
+     * @param {string} collectionPath Collection path
+     * @param {WithFieldValue<T>} data Document data
+     * @param {MutationOptions} [options] Mutation options
+     * @returns {Promise<MutationResponse<T>>} Mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.add('users', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * }, { timestamps: true, customId: 'custom-id' });
+     * ```
+     */
     add<T extends DocumentData>(collectionPath: string, data: WithFieldValue<T>, options?: MutationOptions): Promise<MutationResponse<T>>;
+    /**
+     * Sets document data at specified path
+     * @template T Document data type
+     * @param {string} path Document path
+     * @param {WithFieldValue<T>} data Document data
+     * @param {MutationOptions} [options] Mutation options
+     * @returns {Promise<MutationResponse<T>>} Mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.set('users/123', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * }, { merge: true });
+     * ```
+     */
     set<T extends DocumentData>(path: string, data: WithFieldValue<T>, options?: MutationOptions): Promise<MutationResponse<T>>;
+    /**
+     * Updates a document at specified path
+     * @template T Document data type
+     * @param {string} path Document path
+     * @param {PartialWithFieldValue<T>} data Update data
+     * @param {MutationOptions} [options] Mutation options
+     * @returns {Promise<MutationResponse<Partial<T>>>} Mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.update('users/123', {
+     *   name: 'Jane Doe'
+     * });
+     * ```
+     */
     update<T extends DocumentData>(path: string, data: PartialWithFieldValue<T>, options?: MutationOptions): Promise<MutationResponse<Partial<T>>>;
+    /**
+     * Deletes a document at specified path
+     * @param {string} path Document path
+     * @returns {Promise<MutationResponse<void>>} Mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.delete('users/123');
+     * ```
+     */
     delete(path: string): Promise<MutationResponse<void>>;
+    /**
+     * Checks if a document exists at specified path
+     * @param {string} path Document path
+     * @returns {Promise<boolean>} Whether document exists
+     *
+     * @example
+     * ```typescript
+     * const exists = await firekitDocMutations.exists('users/123');
+     * ```
+     */
     exists(path: string): Promise<boolean>;
+    /**
+     * Gets a document at specified path
+     * @template T Document data type
+     * @param {string} path Document path
+     * @returns {Promise<MutationResponse<T>>} Mutation response with document data
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.getDoc<UserData>('users/123');
+     * if (result.success) {
+     *   console.log(result.data);
+     * }
+     * ```
+     */
     getDoc<T extends DocumentData>(path: string): Promise<MutationResponse<T>>;
 }
+/**
+ * Pre-initialized instance of FirekitDocumentMutations
+ * @const
+ * @type {FirekitDocumentMutations}
+ */
 export declare const firekitDocMutations: FirekitDocumentMutations;
 export {};

package/dist/firestore/document-mutations.svelte.js

@@ -1,7 +1,36 @@
+/**
+ * @module FirekitDocumentMutations
+ */
 import { addDoc, setDoc, updateDoc, deleteDoc, doc, getDoc, collection, serverTimestamp, } from "firebase/firestore";
 import { firebaseService } from "../firebase.js";
 import { firekitUser } from "../auth/user.svelte.js";
+/**
+ * Manages Firestore document mutations with automatic timestamps and error handling
+ * @class
+ * @example
+ * ```typescript
+ * // Add a new document
+ * const result = await firekitDocMutations.add('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * });
+ *
+ * // Update a document
+ * await firekitDocMutations.update('users/123', {
+ *   name: 'Jane Doe'
+ * });
+ *
+ * // Delete a document
+ * await firekitDocMutations.delete('users/123');
+ * ```
+ */
 class FirekitDocumentMutations {
+    /**
+     * Generates timestamp data for document mutations
+     * @private
+     * @param {boolean} [isNew=true] Whether this is a new document
+     * @returns {Record<string, any>} Timestamp data
+     */
     getTimestampData(isNew = true) {
         const timestamps = {
             updatedAt: serverTimestamp(),
@@ -13,6 +42,12 @@ class FirekitDocumentMutations {
         }
         return timestamps;
     }
+    /**
+     * Handles and formats mutation errors
+     * @private
+     * @param {any} error Error object
+     * @returns {MutationResponse<never>} Formatted error response
+     */
     handleError(error) {
         console.error('Firestore mutation error:', error);
         return {
@@ -23,6 +58,22 @@ class FirekitDocumentMutations {
             }
         };
     }
+    /**
+     * Adds a new document to a collection
+     * @template T Document data type
+     * @param {string} collectionPath Collection path
+     * @param {WithFieldValue<T>} data Document data
+     * @param {MutationOptions} [options] Mutation options
+     * @returns {Promise<MutationResponse<T>>} Mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.add('users', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * }, { timestamps: true, customId: 'custom-id' });
+     * ```
+     */
     async add(collectionPath, data, options = { timestamps: true }) {
         try {
             const firestore = firebaseService.getDbInstance();
@@ -34,12 +85,12 @@ class FirekitDocumentMutations {
             let docRef;
             if (options.customId) {
                 docRef = doc(colRef, options.customId);
-                dataToAdd = { ...dataToAdd, id: docRef.id }; // Agregar el id al documento
+                dataToAdd = { ...dataToAdd, id: docRef.id };
                 await setDoc(docRef, dataToAdd);
             }
             else {
                 docRef = await addDoc(colRef, dataToAdd);
-                dataToAdd = { ...dataToAdd, id: docRef.id }; // Agregar el id al documento
+                dataToAdd = { ...dataToAdd, id: docRef.id };
                 await setDoc(docRef, dataToAdd);
             }
             return {
@@ -52,6 +103,22 @@ class FirekitDocumentMutations {
             return this.handleError(error);
         }
     }
+    /**
+     * Sets document data at specified path
+     * @template T Document data type
+     * @param {string} path Document path
+     * @param {WithFieldValue<T>} data Document data
+     * @param {MutationOptions} [options] Mutation options
+     * @returns {Promise<MutationResponse<T>>} Mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.set('users/123', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * }, { merge: true });
+     * ```
+     */
     async set(path, data, options = { merge: false, timestamps: true }) {
         try {
             const firestore = firebaseService.getDbInstance();
@@ -79,6 +146,21 @@ class FirekitDocumentMutations {
             return this.handleError(error);
         }
     }
+    /**
+     * Updates a document at specified path
+     * @template T Document data type
+     * @param {string} path Document path
+     * @param {PartialWithFieldValue<T>} data Update data
+     * @param {MutationOptions} [options] Mutation options
+     * @returns {Promise<MutationResponse<Partial<T>>>} Mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.update('users/123', {
+     *   name: 'Jane Doe'
+     * });
+     * ```
+     */
     async update(path, data, options = { timestamps: true }) {
         try {
             const firestore = firebaseService.getDbInstance();
@@ -98,6 +180,16 @@ class FirekitDocumentMutations {
             return this.handleError(error);
         }
     }
+    /**
+     * Deletes a document at specified path
+     * @param {string} path Document path
+     * @returns {Promise<MutationResponse<void>>} Mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.delete('users/123');
+     * ```
+     */
     async delete(path) {
         try {
             const firestore = firebaseService.getDbInstance();
@@ -112,6 +204,16 @@ class FirekitDocumentMutations {
             return this.handleError(error);
         }
     }
+    /**
+     * Checks if a document exists at specified path
+     * @param {string} path Document path
+     * @returns {Promise<boolean>} Whether document exists
+     *
+     * @example
+     * ```typescript
+     * const exists = await firekitDocMutations.exists('users/123');
+     * ```
+     */
     async exists(path) {
         try {
             const firestore = firebaseService.getDbInstance();
@@ -124,6 +226,20 @@ class FirekitDocumentMutations {
             return false;
         }
     }
+    /**
+     * Gets a document at specified path
+     * @template T Document data type
+     * @param {string} path Document path
+     * @returns {Promise<MutationResponse<T>>} Mutation response with document data
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.getDoc<UserData>('users/123');
+     * if (result.success) {
+     *   console.log(result.data);
+     * }
+     * ```
+     */
     async getDoc(path) {
         try {
             const firestore = firebaseService.getDbInstance();
@@ -149,4 +265,9 @@ class FirekitDocumentMutations {
         }
     }
 }
+/**
+ * Pre-initialized instance of FirekitDocumentMutations
+ * @const
+ * @type {FirekitDocumentMutations}
+ */
 export const firekitDocMutations = new FirekitDocumentMutations();

package/dist/index.d.ts

@@ -2,11 +2,12 @@ export { firebaseConfig } from './config.js';
 export { firebaseService } from './firebase.js';
 export { firekitUser } from './auth/user.svelte.js';
 export { firekitAuth } from './auth/auth.js';
-export { presenceService } from './auth/presence.svelte';
+export { presenceService } from './auth/presence.svelte.js';
 export { firekitAwaitableDoc } from './firestore/awaitable-doc.svelte.js';
-export { firekitDocMutations } from './firestore/document-mutations.svelte';
+export { firekitDocMutations } from './firestore/document-mutations.svelte.js';
 export { firekitCollection } from './firestore/collection.svelte.js';
 export { firekitDoc } from './firestore/doc.svelte.js';
+export { firekitCollectionGroup } from './firestore/collection-group.svelte.js';
 export { firekitRealtimeDB } from './realtime/realtime.svelte.js';
 export { firekitDownloadUrl } from './storage/download-url.svelte.js';
 export { firekitStorageList } from './storage/storage-list.svelte.js';