svelte-firekit 0.0.25 → 0.1.1

package/dist/{realtime → services}/realtime.svelte.d.ts

@@ -1,7 +1,9 @@
 /**
+ * @fileoverview FirekitRealtimeDB - Optimized Realtime Database management for Svelte applications
  * @module FirekitRealtimeDB
+ * @version 1.0.0
  */
-import { type DatabaseReference } from "firebase/database";
+import { type DatabaseReference } from 'firebase/database';
 /**
  * Manages real-time Firebase Realtime Database subscriptions with reactive state
  * @class

package/dist/{realtime → services}/realtime.svelte.js

@@ -1,9 +1,11 @@
 /**
+ * @fileoverview FirekitRealtimeDB - Optimized Realtime Database management for Svelte applications
  * @module FirekitRealtimeDB
+ * @version 1.0.0
  */
-import { ref, onValue, push, set, update, remove } from "firebase/database";
-import { firebaseService } from "../firebase.js";
-import { browser } from "$app/environment";
+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
@@ -54,6 +56,9 @@ class FirekitRealtimeDB {
     initializeRealtimeDB(path) {
         try {
             const database = firebaseService.getDatabaseInstance();
+            if (!database) {
+                throw new Error('Database instance not available');
+            }
             this.dbRef = ref(database, path);
             this.unsubscribe = onValue(this.dbRef, (snapshot) => {
                 this._data = snapshot.val();
@@ -155,7 +160,7 @@ class FirekitRealtimeDB {
      */
     get ref() {
         if (!this.dbRef) {
-            throw new Error("Database reference is not available");
+            throw new Error('Database reference is not available');
         }
         return this.dbRef;
     }
@@ -163,6 +168,7 @@ class FirekitRealtimeDB {
     dispose() {
         if (this.unsubscribe) {
             this.unsubscribe();
+            this.unsubscribe = null;
         }
     }
 }
@@ -201,15 +207,15 @@ export function firekitRealtimeList(path, startWith = []) {
         acc[`key${index}`] = item;
         return acc;
     }, {});
-    return new class extends FirekitRealtimeDB {
+    return new (class extends FirekitRealtimeDB {
         _list = $derived(this.data
             ? Object.entries(this.data).map(([key, value]) => ({
                 id: key,
-                ...value,
+                ...value
             }))
             : []);
         get list() {
             return this._list;
         }
-    }(path, startWithRecord);
+    })(path, startWithRecord);
 }

package/dist/services/storage.svelte.d.ts

@@ -0,0 +1,257 @@
+/**
+ * @fileoverview FirekitStorage - Optimized Firebase Storage management for Svelte applications
+ * @module FirekitStorage
+ * @version 1.0.0
+ */
+import { type StorageReference, type UploadTaskSnapshot } from 'firebase/storage';
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+    /**
+     * 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 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;
+/**
+ * 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;
+/**
+ * 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 {};

package/dist/services/storage.svelte.js

@@ -0,0 +1,374 @@
+/**
+ * @fileoverview FirekitStorage - Optimized Firebase Storage management for Svelte applications
+ * @module FirekitStorage
+ * @version 1.0.0
+ */
+import { ref, getDownloadURL, listAll, uploadBytesResumable } 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();
+            if (!storage) {
+                throw new Error('Storage instance not available');
+            }
+            this.storageRef = ref(storage, path);
+            this._url = await getDownloadURL(this.storageRef);
+            this._loading = false;
+        }
+        catch (error) {
+            this._error = error;
+            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;
+            this._error = null;
+            this.initializeDownload(this.storageRef.fullPath);
+        }
+    }
+}
+/**
+ * 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();
+            if (!storage) {
+                throw new Error('Storage instance not available');
+            }
+            this.storageRef = ref(storage, path);
+            const result = await listAll(this.storageRef);
+            this._items = result.items;
+            this._prefixes = result.prefixes;
+            this._loading = false;
+        }
+        catch (error) {
+            this._error = error;
+            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;
+            this._error = null;
+            this.initializeList(this.storageRef.fullPath);
+        }
+    }
+}
+/**
+ * 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();
+ * ```
+ */
+class FirekitUploadTask {
+    /** Upload progress percentage */
+    _progress = $state(0);
+    /** Error state */
+    _error = $state(null);
+    /** Current upload snapshot */
+    _snapshot = $state(null);
+    /** Download URL of uploaded file */
+    _downloadURL = $state(null);
+    /** Upload completion state */
+    _completed = $state(false);
+    /** Upload task reference */
+    uploadTask = null;
+    /** Storage reference */
+    storageRef = 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, file) {
+        if (browser) {
+            this.initializeUpload(path, file);
+        }
+    }
+    /**
+     * Initializes file upload
+     * @private
+     * @param {string} path Storage path
+     * @param {File} file File to upload
+     */
+    initializeUpload(path, file) {
+        try {
+            const storage = firebaseService.getStorageInstance();
+            if (!storage) {
+                throw new Error('Storage instance not available');
+            }
+            this.storageRef = ref(storage, path);
+            this.uploadTask = uploadBytesResumable(this.storageRef, file);
+            this.uploadTask.on('state_changed', (snapshot) => {
+                this._snapshot = snapshot;
+                this._progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100;
+            }, (error) => {
+                this._error = error;
+            }, async () => {
+                if (this.storageRef) {
+                    this._downloadURL = await getDownloadURL(this.storageRef);
+                    this._completed = true;
+                }
+            });
+        }
+        catch (error) {
+            this._error = error;
+        }
+    }
+    /** Pauses upload */
+    pause() {
+        this.uploadTask?.pause();
+    }
+    /** Resumes upload */
+    resume() {
+        this.uploadTask?.resume();
+    }
+    /** Cancels upload */
+    cancel() {
+        this.uploadTask?.cancel();
+    }
+    /** Gets upload progress percentage */
+    get progress() {
+        return this._progress;
+    }
+    /** Gets error state */
+    get error() {
+        return this._error;
+    }
+    /** Gets current upload snapshot */
+    get snapshot() {
+        return this._snapshot;
+    }
+    /** Gets download URL */
+    get downloadURL() {
+        return this._downloadURL;
+    }
+    /** Gets completion state */
+    get completed() {
+        return this._completed;
+    }
+}
+// ========================================
+// FACTORY FUNCTIONS
+// ========================================
+/**
+ * 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);
+}
+/**
+ * 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);
+}
+/**
+ * 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 function firekitUploadTask(path, file) {
+    return new FirekitUploadTask(path, file);
+}