svelte-firekit 0.0.21 → 0.0.23

package/dist/index.js

@@ -4,12 +4,13 @@ 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';
+export { firekitCollectionGroup } from './firestore/collection-group.svelte.js';
 // realtime services
 export { firekitRealtimeDB } from './realtime/realtime.svelte.js';
 // Storage 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 {};

package/dist/realtime/realtime.svelte.js

@@ -1,18 +1,56 @@
+/**
+ * @module FirekitRealtimeDB
+ */
 import { ref, onValue, push, set, update, remove } from "firebase/database";
 import { firebaseService } from "../firebase.js";
 import { browser } from "$app/environment";
+/**
+ * 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');
+ * ```
+ */
 class FirekitRealtimeDB {
+    /** Current data */
     _data = $state(null);
+    /** Loading state */
     _loading = $state(true);
+    /** Error state */
     _error = $state(null);
+    /** Database reference */
     dbRef = null;
+    /** Subscription cleanup function */
     unsubscribe = null;
+    /**
+     * Creates a Realtime Database subscription
+     * @param {string} path Database path
+     * @param {T} [startWith] Initial data before fetch completes
+     */
     constructor(path, startWith) {
         this._data = startWith ?? null;
         if (browser) {
             this.initializeRealtimeDB(path);
         }
     }
+    /**
+     * Initializes database subscription
+     * @private
+     * @param {string} path Database path
+     */
     initializeRealtimeDB(path) {
         try {
             const database = firebaseService.getDatabaseInstance();
@@ -31,7 +69,20 @@ class FirekitRealtimeDB {
             this._loading = false;
         }
     }
-    // Push new data to the list
+    /**
+     * 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()
+     * });
+     * ```
+     */
     async push(data) {
         if (!this.dbRef)
             return null;
@@ -39,41 +90,76 @@ class FirekitRealtimeDB {
         await set(newRef, data);
         return newRef.key;
     }
-    // Set data at the reference
+    /**
+     * Sets data at reference
+     * @param {T} data Data to set
+     *
+     * @example
+     * ```typescript
+     * await chatRef.set({
+     *   text: 'Updated message',
+     *   userId: '123',
+     *   timestamp: Date.now()
+     * });
+     * ```
+     */
     async set(data) {
         if (!this.dbRef)
             return;
         await set(this.dbRef, data);
     }
-    // Update data at the reference
+    /**
+     * Updates data at reference
+     * @param {Partial<T>} data Data to update
+     *
+     * @example
+     * ```typescript
+     * await chatRef.update({
+     *   text: 'Edited message'
+     * });
+     * ```
+     */
     async update(data) {
         if (!this.dbRef)
             return;
         await update(this.dbRef, data);
     }
-    // Remove data at the reference
+    /**
+     * Removes data at reference
+     *
+     * @example
+     * ```typescript
+     * await chatRef.remove();
+     * ```
+     */
     async remove() {
         if (!this.dbRef)
             return;
         await remove(this.dbRef);
     }
-    // Getters for reactive state
+    /** Gets current data */
     get data() {
         return this._data;
     }
+    /** Gets loading state */
     get loading() {
         return this._loading;
     }
+    /** Gets error state */
     get error() {
         return this._error;
     }
+    /**
+     * Gets database reference
+     * @throws {Error} If reference is not available
+     */
     get ref() {
         if (!this.dbRef) {
             throw new Error("Database reference is not available");
         }
         return this.dbRef;
     }
-    // Cleanup subscription
+    /** Cleanup subscription */
     dispose() {
         if (this.unsubscribe) {
             this.unsubscribe();
@@ -82,22 +168,35 @@ class FirekitRealtimeDB {
 }
 /**
  * Creates a reactive Realtime Database reference
- * @param path Database path
- * @param startWith Optional initial data
- * @returns FirekitRealtimeDB instance
+ * @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 function firekitRealtimeDB(path, startWith) {
     return new FirekitRealtimeDB(path, startWith);
 }
 /**
  * Creates a reactive Realtime Database list reference
- * Automatically converts the data into an array format
- * @param path Database path
- * @param startWith Optional initial array data
- * @returns FirekitRealtimeDB instance with array data
+ * 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 function firekitRealtimeList(path, startWith = []) {
-    // Convert initial array to Record format
     const startWithRecord = startWith.reduce((acc, item, index) => {
         acc[`key${index}`] = item;
         return acc;

package/dist/storage/download-url.svelte.d.ts

@@ -1,14 +1,83 @@
+/**
+ * @module FirekitDownloadUrl
+ */
+/**
+ * Manages Firebase Storage download URL fetching with reactive state
+ * @class
+ *
+ * @example
+ * ```typescript
+ * // Get download URL for image
+ * const imageUrl = firekitDownloadUrl('images/photo.jpg');
+ *
+ * // Access reactive state
+ * if (imageUrl.loading) {
+ *   console.log('Loading URL...');
+ * } else if (imageUrl.url) {
+ *   console.log('Download URL:', imageUrl.url);
+ * }
+ * ```
+ */
 declare class FirekitDownloadUrl {
+    /** Current download URL */
     private _url;
+    /** Loading state */
     private _loading;
+    /** Error state */
     private _error;
+    /** Storage reference */
     private storageRef;
+    /**
+     * Creates a download URL fetcher
+     * @param {string} path Storage path to file
+     *
+     * @example
+     * ```typescript
+     * const url = new FirekitDownloadUrl('documents/file.pdf');
+     * ```
+     */
     constructor(path: string);
+    /**
+     * Initializes download URL fetching
+     * @private
+     * @param {string} path Storage path
+     */
     private initializeDownload;
+    /** Gets current download URL */
     get url(): string | null;
+    /** Gets loading state */
     get loading(): boolean;
+    /** Gets error state */
     get error(): Error | null;
+    /**
+     * Refreshes download URL
+     * Useful when file content has changed
+     *
+     * @example
+     * ```typescript
+     * // Refresh URL after file update
+     * await uploadNewVersion();
+     * imageUrl.refresh();
+     * ```
+     */
     refresh(): void;
 }
+/**
+ * Creates a download URL fetcher
+ * @param {string} path Storage path to file
+ * @returns {FirekitDownloadUrl} Download URL fetcher instance
+ *
+ * @example
+ * ```typescript
+ * const imageUrl = firekitDownloadUrl('images/profile.jpg');
+ *
+ * // Use in template
+ * {#if imageUrl.loading}
+ *   <p>Loading...</p>
+ * {:else if imageUrl.url}
+ *   <img src={imageUrl.url} alt="Profile" />
+ * {/if}
+ * ```
+ */
 export declare function firekitDownloadUrl(path: string): FirekitDownloadUrl;
 export {};

package/dist/storage/download-url.svelte.js

@@ -1,16 +1,54 @@
+/**
+ * @module FirekitDownloadUrl
+ */
 import { ref, getDownloadURL } from "firebase/storage";
 import { browser } from "$app/environment";
 import { firebaseService } from "../firebase.js";
+/**
+ * Manages Firebase Storage download URL fetching with reactive state
+ * @class
+ *
+ * @example
+ * ```typescript
+ * // Get download URL for image
+ * const imageUrl = firekitDownloadUrl('images/photo.jpg');
+ *
+ * // Access reactive state
+ * if (imageUrl.loading) {
+ *   console.log('Loading URL...');
+ * } else if (imageUrl.url) {
+ *   console.log('Download URL:', imageUrl.url);
+ * }
+ * ```
+ */
 class FirekitDownloadUrl {
+    /** Current download URL */
     _url = $state(null);
+    /** Loading state */
     _loading = $state(true);
+    /** Error state */
     _error = $state(null);
+    /** Storage reference */
     storageRef = null;
+    /**
+     * Creates a download URL fetcher
+     * @param {string} path Storage path to file
+     *
+     * @example
+     * ```typescript
+     * const url = new FirekitDownloadUrl('documents/file.pdf');
+     * ```
+     */
     constructor(path) {
         if (browser) {
             this.initializeDownload(path);
         }
     }
+    /**
+     * Initializes download URL fetching
+     * @private
+     * @param {string} path Storage path
+     */
     async initializeDownload(path) {
         try {
             const storage = firebaseService.getStorageInstance();
@@ -23,15 +61,29 @@ class FirekitDownloadUrl {
             this._loading = false;
         }
     }
+    /** Gets current download URL */
     get url() {
         return this._url;
     }
+    /** Gets loading state */
     get loading() {
         return this._loading;
     }
+    /** Gets error state */
     get error() {
         return this._error;
     }
+    /**
+     * Refreshes download URL
+     * Useful when file content has changed
+     *
+     * @example
+     * ```typescript
+     * // Refresh URL after file update
+     * await uploadNewVersion();
+     * imageUrl.refresh();
+     * ```
+     */
     refresh() {
         if (this.storageRef) {
             this._loading = true;
@@ -40,6 +92,23 @@ class FirekitDownloadUrl {
         }
     }
 }
+/**
+ * Creates a download URL fetcher
+ * @param {string} path Storage path to file
+ * @returns {FirekitDownloadUrl} Download URL fetcher instance
+ *
+ * @example
+ * ```typescript
+ * const imageUrl = firekitDownloadUrl('images/profile.jpg');
+ *
+ * // Use in template
+ * {#if imageUrl.loading}
+ *   <p>Loading...</p>
+ * {:else if imageUrl.url}
+ *   <img src={imageUrl.url} alt="Profile" />
+ * {/if}
+ * ```
+ */
 export function firekitDownloadUrl(path) {
     return new FirekitDownloadUrl(path);
 }

package/dist/storage/storage-list.svelte.d.ts

@@ -1,17 +1,89 @@
+/**
+ * @module FirekitStorageList
+ */
 import { type StorageReference } from "firebase/storage";
+/**
+ * Manages Firebase Storage directory listing with reactive state
+ * @class
+ *
+ * @example
+ * ```typescript
+ * // List contents of images directory
+ * const imagesList = firekitStorageList('images');
+ *
+ * // Access items and folders
+ * console.log('Files:', imagesList.items);
+ * console.log('Folders:', imagesList.prefixes);
+ * ```
+ */
 declare class FirekitStorageList {
+    /** List of files in directory */
     private _items;
+    /** List of subdirectories */
     private _prefixes;
+    /** Loading state */
     private _loading;
+    /** Error state */
     private _error;
+    /** Storage reference */
     private storageRef;
+    /**
+     * Creates a storage directory lister
+     * @param {string} path Storage directory path
+     *
+     * @example
+     * ```typescript
+     * const list = new FirekitStorageList('uploads/2024');
+     * ```
+     */
     constructor(path: string);
+    /**
+     * Initializes directory listing
+     * @private
+     * @param {string} path Storage directory path
+     */
     private initializeList;
+    /** Gets list of files */
     get items(): StorageReference[];
+    /** Gets list of subdirectories */
     get prefixes(): StorageReference[];
+    /** Gets loading state */
     get loading(): boolean;
+    /** Gets error state */
     get error(): Error | null;
+    /**
+     * Refreshes directory listing
+     * Useful when directory contents have changed
+     *
+     * @example
+     * ```typescript
+     * // Refresh after upload
+     * await uploadFile('images/new.jpg');
+     * imagesList.refresh();
+     * ```
+     */
     refresh(): void;
 }
+/**
+ * Creates a storage directory lister
+ * @param {string} path Storage directory path
+ * @returns {FirekitStorageList} Storage list instance
+ *
+ * @example
+ * ```typescript
+ * const documents = firekitStorageList('documents');
+ *
+ * // Use in template
+ * {#if documents.loading}
+ *   <p>Loading...</p>
+ * {:else}
+ *   <ul>
+ *     {#each documents.items as item}
+ *       <li>{item.name}</li>
+ *     {/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
 export declare function firekitStorageList(path: string): FirekitStorageList;
 export {};