svelte-firekit 0.1.9 → 0.2.0

package/dist/services/storage.svelte.js

@@ -1,374 +1,259 @@
-/**
- * @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 { ref, getDownloadURL, listAll, uploadBytesResumable, deleteObject, getMetadata, updateMetadata } from 'firebase/storage';
 import { firebaseService } from '../firebase.js';
+function getStorage() {
+    const storage = firebaseService.getStorageInstance();
+    if (!storage)
+        throw new Error('Firebase Storage is not initialized.');
+    return storage;
+}
+// ── Download URL ──────────────────────────────────────────────────────────────
 /**
- * Manages Firebase Storage download URL fetching with reactive state
- * @class
+ * Fetches and exposes a Firebase Storage download URL reactively.
  *
  * @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);
- * }
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitDownloadUrl } from 'svelte-firekit';
+ *   const img = firekitDownloadUrl('images/avatar.jpg');
+ * </script>
+ * {#if img.url}<img src={img.url} alt="avatar" />{/if}
  * ```
  */
-class FirekitDownloadUrl {
-    /** Current download URL */
+export class FirekitDownloadUrl {
     _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');
-     * ```
-     */
+    _storageRef = null;
+    _path;
     constructor(path) {
-        if (browser) {
-            this.initializeDownload(path);
-        }
+        this._path = path;
+        this._init();
     }
-    /**
-     * 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);
+    get url() { return this._url; }
+    get loading() { return this._loading; }
+    get error() { return this._error; }
+    async _init() {
+        if (typeof window === 'undefined') {
             this._loading = false;
+            return;
+        }
+        try {
+            const storage = getStorage();
+            this._storageRef = ref(storage, this._path);
+            this._url = await getDownloadURL(this._storageRef);
+            this._error = null;
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
         }
-        catch (error) {
-            this._error = error;
+        finally {
             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);
+    /** Re-fetches the download URL (useful after replacing a file). */
+    async refresh() {
+        if (!this._storageRef)
+            return;
+        this._loading = true;
+        this._error = null;
+        try {
+            this._url = await getDownloadURL(this._storageRef);
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+        }
+        finally {
+            this._loading = false;
         }
     }
 }
+// ── Storage list ──────────────────────────────────────────────────────────────
 /**
- * Manages Firebase Storage directory listing with reactive state
- * @class
+ * Lists files and sub-folders at a Storage path reactively.
  *
  * @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);
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitStorageList } from 'svelte-firekit';
+ *   const dir = firekitStorageList('uploads/2024');
+ * </script>
+ * {#each dir.items as item}<p>{item.name}</p>{/each}
  * ```
  */
-class FirekitStorageList {
-    /** List of files in directory */
+export class FirekitStorageList {
     _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');
-     * ```
-     */
+    _storageRef = null;
+    _path;
     constructor(path) {
-        if (browser) {
-            this.initializeList(path);
-        }
+        this._path = path;
+        this._init();
     }
-    /**
-     * Initializes directory listing
-     * @private
-     * @param {string} path Storage directory path
-     */
-    async initializeList(path) {
+    get items() { return this._items; }
+    get prefixes() { return this._prefixes; }
+    get loading() { return this._loading; }
+    get error() { return this._error; }
+    async _init() {
+        if (typeof window === 'undefined') {
+            this._loading = false;
+            return;
+        }
         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);
+            const storage = getStorage();
+            this._storageRef = ref(storage, this._path);
+            const result = await listAll(this._storageRef);
             this._items = result.items;
             this._prefixes = result.prefixes;
-            this._loading = false;
+            this._error = null;
         }
-        catch (error) {
-            this._error = error;
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+        }
+        finally {
             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);
+    /** Re-lists the directory (useful after uploads/deletes). */
+    async refresh() {
+        if (!this._storageRef)
+            return;
+        this._loading = true;
+        this._error = null;
+        try {
+            const result = await listAll(this._storageRef);
+            this._items = result.items;
+            this._prefixes = result.prefixes;
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+        }
+        finally {
+            this._loading = false;
         }
     }
 }
 /**
- * Manages Firebase Storage upload operations with reactive state and progress tracking
- * @class
+ * Manages a resumable Firebase Storage upload with reactive progress.
  *
  * @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();
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitUploadTask } from 'svelte-firekit';
+ *   let file: File;
+ *   $: task = file ? firekitUploadTask('uploads/' + file.name, file) : null;
+ * </script>
+ * {#if task}
+ *   <progress value={task.progress} max={100} />
+ *   {#if task.downloadURL}<img src={task.downloadURL} />{/if}
+ * {/if}
  * ```
  */
-class FirekitUploadTask {
-    /** Upload progress percentage */
+export class FirekitUploadTask {
     _progress = $state(0);
-    /** Error state */
+    _downloadURL = $state(null);
     _error = $state(null);
-    /** Current upload snapshot */
+    _state = $state('idle');
+    _bytesTransferred = $state(0);
+    _totalBytes = $state(0);
     _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);
-        }
+    completed = $derived(this._state === 'success');
+    canceled = $derived(this._state === 'canceled');
+    failed = $derived(this._state === 'error');
+    active = $derived(this._state === 'running' || this._state === 'paused');
+    _task = null;
+    _storageRef = null;
+    constructor(path, file, metadata) {
+        this._init(path, file, metadata);
     }
-    /**
-     * Initializes file upload
-     * @private
-     * @param {string} path Storage path
-     * @param {File} file File to upload
-     */
-    initializeUpload(path, file) {
+    get progress() { return this._progress; }
+    get downloadURL() { return this._downloadURL; }
+    get error() { return this._error; }
+    get state() { return this._state; }
+    get bytesTransferred() { return this._bytesTransferred; }
+    get totalBytes() { return this._totalBytes; }
+    get snapshot() { return this._snapshot; }
+    _init(path, file, metadata) {
+        if (typeof window === 'undefined')
+            return;
         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;
+            const storage = getStorage();
+            this._storageRef = ref(storage, path);
+            this._task = uploadBytesResumable(this._storageRef, file, metadata);
+            this._state = 'running';
+            this._task.on('state_changed', (snap) => {
+                this._snapshot = snap;
+                this._bytesTransferred = snap.bytesTransferred;
+                this._totalBytes = snap.totalBytes;
+                this._progress = snap.totalBytes > 0
+                    ? (snap.bytesTransferred / snap.totalBytes) * 100
+                    : 0;
+                this._state = snap.state;
+            }, (err) => {
+                this._error = err;
+                this._state = 'error';
             }, async () => {
-                if (this.storageRef) {
-                    this._downloadURL = await getDownloadURL(this.storageRef);
-                    this._completed = true;
+                if (this._storageRef) {
+                    this._downloadURL = await getDownloadURL(this._storageRef);
                 }
+                this._state = 'success';
+                this._progress = 100;
             });
         }
-        catch (error) {
-            this._error = error;
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+            this._state = '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;
-    }
+    /** Pauses the upload. */
+    pause() { this._task?.pause(); }
+    /** Resumes a paused upload. */
+    resume() { this._task?.resume(); }
+    /** Cancels the upload. */
+    cancel() { this._task?.cancel(); }
 }
-// ========================================
-// FACTORY FUNCTIONS
-// ========================================
+// ── One-shot helpers ──────────────────────────────────────────────────────────
 /**
- * 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}
- * ```
+ * Deletes a file from Firebase Storage.
  */
-export function firekitDownloadUrl(path) {
-    return new FirekitDownloadUrl(path);
+export async function deleteFile(path) {
+    const storage = getStorage();
+    await deleteObject(ref(storage, 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}
- * ```
+ * Fetches metadata for a file in Firebase Storage.
  */
-export function firekitStorageList(path) {
-    return new FirekitStorageList(path);
+export async function getFileMetadata(path) {
+    const storage = getStorage();
+    return getMetadata(ref(storage, path));
 }
 /**
- * Creates an upload task
- * @param {string} path Storage path for upload
- * @param {File} file File to upload
- * @returns {FirekitUploadTask} Upload task instance
+ * Updates metadata for a file in Firebase Storage.
+ * Only fields provided in `metadata` are changed; omitted fields are left as-is.
  *
  * @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}
+ * ```ts
+ * await updateFileMetadata('images/avatar.jpg', {
+ *   contentType: 'image/webp',
+ *   customMetadata: { uploadedBy: 'uid123' }
+ * });
  * ```
  */
-export function firekitUploadTask(path, file) {
-    return new FirekitUploadTask(path, file);
+export async function updateFileMetadata(path, metadata) {
+    const storage = getStorage();
+    return updateMetadata(ref(storage, path), metadata);
+}
+// ── Factory functions ─────────────────────────────────────────────────────────
+/** Creates a reactive download URL fetcher. */
+export function firekitDownloadUrl(path) {
+    return new FirekitDownloadUrl(path);
+}
+/** Creates a reactive Storage directory listing. */
+export function firekitStorageList(path) {
+    return new FirekitStorageList(path);
+}
+/** Creates a reactive resumable upload task. */
+export function firekitUploadTask(path, file, metadata) {
+    return new FirekitUploadTask(path, file, metadata);
 }