svelte-firekit 0.0.21 → 0.0.22

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,9 +2,9 @@ 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 { firekitRealtimeDB } from './realtime/realtime.svelte.js';

package/dist/index.js

@@ -4,10 +4,10 @@ export { firebaseService } from './firebase.js';
 // auth services
 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';
 // firestore services
 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';
 // realtime services

package/dist/realtime/realtime.svelte.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @module FirekitRealtimeDB
+ */
+import { type DatabaseReference } from "firebase/database";
+/**
+ * Manages real-time Firebase Realtime Database subscriptions with reactive state
+ * @class
+ * @template T Data type
+ *
+ * @example
+ * ```typescript
+ * interface ChatMessage {
+ *   text: string;
+ *   userId: string;
+ *   timestamp: number;
+ * }
+ *
+ * // Create regular reference
+ * const chatRef = firekitRealtimeDB<ChatMessage>('chats/123');
+ *
+ * // Create list reference
+ * const messagesList = firekitRealtimeList<ChatMessage>('messages');
+ * ```
+ */
+declare class FirekitRealtimeDB<T> {
+    /** Current data */
+    private _data;
+    /** Loading state */
+    private _loading;
+    /** Error state */
+    private _error;
+    /** Database reference */
+    private dbRef;
+    /** Subscription cleanup function */
+    private unsubscribe;
+    /**
+     * Creates a Realtime Database subscription
+     * @param {string} path Database path
+     * @param {T} [startWith] Initial data before fetch completes
+     */
+    constructor(path: string, startWith?: T);
+    /**
+     * Initializes database subscription
+     * @private
+     * @param {string} path Database path
+     */
+    private initializeRealtimeDB;
+    /**
+     * Pushes new data to list
+     * @param {T} data Data to push
+     * @returns {Promise<string | null>} New item key or null if failed
+     *
+     * @example
+     * ```typescript
+     * const key = await chatRef.push({
+     *   text: 'Hello',
+     *   userId: '123',
+     *   timestamp: Date.now()
+     * });
+     * ```
+     */
+    push(data: T): Promise<string | null>;
+    /**
+     * Sets data at reference
+     * @param {T} data Data to set
+     *
+     * @example
+     * ```typescript
+     * await chatRef.set({
+     *   text: 'Updated message',
+     *   userId: '123',
+     *   timestamp: Date.now()
+     * });
+     * ```
+     */
+    set(data: T): Promise<void>;
+    /**
+     * Updates data at reference
+     * @param {Partial<T>} data Data to update
+     *
+     * @example
+     * ```typescript
+     * await chatRef.update({
+     *   text: 'Edited message'
+     * });
+     * ```
+     */
+    update(data: Partial<T>): Promise<void>;
+    /**
+     * Removes data at reference
+     *
+     * @example
+     * ```typescript
+     * await chatRef.remove();
+     * ```
+     */
+    remove(): Promise<void>;
+    /** Gets current data */
+    get data(): T | null;
+    /** Gets loading state */
+    get loading(): boolean;
+    /** Gets error state */
+    get error(): Error | null;
+    /**
+     * Gets database reference
+     * @throws {Error} If reference is not available
+     */
+    get ref(): DatabaseReference;
+    /** Cleanup subscription */
+    dispose(): void;
+}
+/**
+ * Creates a reactive Realtime Database reference
+ * @template T Data type
+ * @param {string} path Database path
+ * @param {T} [startWith] Initial data
+ * @returns {FirekitRealtimeDB<T>} Database subscription instance
+ *
+ * @example
+ * ```typescript
+ * const chatRef = firekitRealtimeDB<ChatMessage>('chats/123');
+ * ```
+ */
+export declare function firekitRealtimeDB<T>(path: string, startWith?: T): FirekitRealtimeDB<T>;
+/**
+ * Creates a reactive Realtime Database list reference
+ * Automatically converts data to array format with IDs
+ *
+ * @template T List item type
+ * @param {string} path Database path
+ * @param {T[]} [startWith=[]] Initial array data
+ * @returns {FirekitRealtimeDB} Database subscription instance with array support
+ *
+ * @example
+ * ```typescript
+ * const messagesList = firekitRealtimeList<ChatMessage>('messages');
+ * console.log(messagesList.list); // Array of messages with IDs
+ * ```
+ */
+export declare function firekitRealtimeList<T>(path: string, startWith?: T[]): FirekitRealtimeDB<Record<string, T>> & {
+    list: Array<T & {
+        id: string;
+    }>;
+};
+export {};