svelte-firekit 0.0.21 → 0.0.22

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

package/dist/storage/storage-list.svelte.js

@@ -1,17 +1,53 @@
+/**
+ * @module FirekitStorageList
+ */
 import { ref, listAll } from "firebase/storage";
 import { browser } from "$app/environment";
 import { firebaseService } from "../firebase.js";
+/**
+ * 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);
+ * ```
+ */
 class FirekitStorageList {
+    /** List of files in directory */
     _items = $state([]);
+    /** List of subdirectories */
     _prefixes = $state([]);
+    /** Loading state */
     _loading = $state(true);
+    /** Error state */
     _error = $state(null);
+    /** Storage reference */
     storageRef = null;
+    /**
+     * Creates a storage directory lister
+     * @param {string} path Storage directory path
+     *
+     * @example
+     * ```typescript
+     * const list = new FirekitStorageList('uploads/2024');
+     * ```
+     */
     constructor(path) {
         if (browser) {
             this.initializeList(path);
         }
     }
+    /**
+     * Initializes directory listing
+     * @private
+     * @param {string} path Storage directory path
+     */
     async initializeList(path) {
         try {
             const storage = firebaseService.getStorageInstance();
@@ -26,18 +62,33 @@ class FirekitStorageList {
             this._loading = false;
         }
     }
+    /** Gets list of files */
     get items() {
         return this._items;
     }
+    /** Gets list of subdirectories */
     get prefixes() {
         return this._prefixes;
     }
+    /** Gets loading state */
     get loading() {
         return this._loading;
     }
+    /** Gets error state */
     get error() {
         return this._error;
     }
+    /**
+     * Refreshes directory listing
+     * Useful when directory contents have changed
+     *
+     * @example
+     * ```typescript
+     * // Refresh after upload
+     * await uploadFile('images/new.jpg');
+     * imagesList.refresh();
+     * ```
+     */
     refresh() {
         if (this.storageRef) {
             this._loading = true;
@@ -46,6 +97,27 @@ class FirekitStorageList {
         }
     }
 }
+/**
+ * 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 function firekitStorageList(path) {
     return new FirekitStorageList(path);
 }

package/dist/storage/upload-task.svelte.d.ts

@@ -1,23 +1,94 @@
+/**
+ * @module FirekitUploadTask
+ */
 import { type UploadTaskSnapshot } from "firebase/storage";
+/**
+ * Manages Firebase Storage upload operations with reactive state and progress tracking
+ * @class
+ *
+ * @example
+ * ```typescript
+ * // Create upload task
+ * const upload = firekitUploadTask('images/photo.jpg', file);
+ *
+ * // Monitor progress
+ * console.log(`Upload progress: ${upload.progress}%`);
+ *
+ * // Control upload
+ * upload.pause();
+ * upload.resume();
+ * upload.cancel();
+ * ```
+ */
 declare class FirekitUploadTask {
+    /** Upload progress percentage */
     private _progress;
+    /** Error state */
     private _error;
+    /** Current upload snapshot */
     private _snapshot;
+    /** Download URL of uploaded file */
     private _downloadURL;
+    /** Upload completion state */
     private _completed;
+    /** Upload task reference */
     private uploadTask;
+    /** Storage reference */
     private storageRef;
+    /** Derived download URL */
     readonly URLdownload: string | null;
+    /**
+     * Creates an upload task
+     * @param {string} path Storage path for upload
+     * @param {File} file File to upload
+     *
+     * @example
+     * ```typescript
+     * const task = new FirekitUploadTask('documents/report.pdf', file);
+     * ```
+     */
     constructor(path: string, file: File);
+    /**
+     * Initializes file upload
+     * @private
+     * @param {string} path Storage path
+     * @param {File} file File to upload
+     */
     private initializeUpload;
+    /** Pauses upload */
     pause(): void;
+    /** Resumes upload */
     resume(): void;
+    /** Cancels upload */
     cancel(): void;
+    /** Gets upload progress percentage */
     get progress(): number;
+    /** Gets error state */
     get error(): Error | null;
+    /** Gets current upload snapshot */
     get snapshot(): UploadTaskSnapshot | null;
+    /** Gets download URL */
     get downloadURL(): string | null;
+    /** Gets completion state */
     get completed(): boolean;
 }
+/**
+ * Creates an upload task
+ * @param {string} path Storage path for upload
+ * @param {File} file File to upload
+ * @returns {FirekitUploadTask} Upload task instance
+ *
+ * @example
+ * ```typescript
+ * const uploadTask = firekitUploadTask('images/profile.jpg', imageFile);
+ *
+ * // Template usage
+ * {#if !uploadTask.completed}
+ *   <progress value={uploadTask.progress} max="100" />
+ * {:else}
+ *   <img src={uploadTask.downloadURL} alt="Uploaded file" />
+ * {/if}
+ * ```
+ */
 export declare function firekitUploadTask(path: string, file: File): FirekitUploadTask;
 export {};