firebase-storage-kit 1.3.0 → 1.4.0

package/dist/chunk-PBO3CMOD.js

@@ -0,0 +1,766 @@
+import { ref, uploadBytesResumable, getDownloadURL, getMetadata, deleteObject } from 'firebase/storage';
+
+// src/core/emitter.ts
+var Emitter = class {
+  listeners = {};
+  /**
+   * @param event The event to listen for.
+   * @param listener The function to call when the event is emitted.
+   * @returns A function to unsubscribe from the event.
+   */
+  on(event, listener) {
+    let listeners = this.listeners[event];
+    if (!listeners) {
+      listeners = /* @__PURE__ */ new Set();
+      this.listeners[event] = listeners;
+    }
+    listeners.add(listener);
+    return () => {
+      this.listeners[event]?.delete(listener);
+    };
+  }
+  /**
+   * @param event The event to emit.
+   * @param payload The payload to emit.
+   */
+  emit(event, payload) {
+    const listeners = this.listeners[event];
+    if (!listeners) {
+      return;
+    }
+    for (const listener of listeners) {
+      listener(payload);
+    }
+  }
+};
+
+// src/core/batch-handle.ts
+var BatchHandle = class extends Emitter {
+  id;
+  uploads;
+  concurrency;
+  continueOnError;
+  startNext;
+  onChange;
+  running = 0;
+  nextIdx = 0;
+  /** Indices that were started via {@link fillSlots} and still hold a concurrency slot. */
+  activeSlots = /* @__PURE__ */ new Set();
+  settledCount = 0;
+  succeededCount = 0;
+  failedCount = 0;
+  failedFast = false;
+  canceled = false;
+  paused = false;
+  terminalEmitted = false;
+  // Stable view of UploadItems; the items themselves mutate in place, but the
+  // array reference never changes, so we allocate it once instead of rebuilding
+  // it on every snapshot.
+  uploadsView;
+  // Running aggregates updated incrementally on each child event so snapshot()
+  // is O(1) instead of O(n) per progress tick.
+  aggregateBytesTransferred = 0;
+  aggregateTotalBytes = 0;
+  lastBytes;
+  lastTotal;
+  constructor(init) {
+    super();
+    this.id = init.id;
+    this.uploads = init.uploads;
+    this.concurrency = Math.max(1, init.options.concurrency ?? 3);
+    this.continueOnError = init.options.continueOnError ?? true;
+    this.startNext = init.startNext;
+    this.onChange = init.onChange;
+    this.uploadsView = init.uploads.map((h) => h.upload);
+    this.lastBytes = Array.from(
+      { length: init.uploads.length },
+      () => 0
+    );
+    this.lastTotal = Array.from(
+      { length: init.uploads.length },
+      () => 0
+    );
+    for (let i = 0; i < this.uploadsView.length; i += 1) {
+      const u = this.uploadsView[i];
+      if (!u) {
+        continue;
+      }
+      this.lastBytes[i] = u.bytesTransferred;
+      this.lastTotal[i] = u.totalBytes;
+      this.aggregateBytesTransferred += u.bytesTransferred;
+      this.aggregateTotalBytes += u.totalBytes;
+    }
+    for (let idx = 0; idx < this.uploads.length; idx += 1) {
+      const child = this.uploads[idx];
+      if (!child) {
+        continue;
+      }
+      child.on("progress", (upload) => {
+        this.handleChildProgress(idx, upload);
+      });
+      child.on("retry", (retryEvent) => {
+        this.handleChildRetry(idx, retryEvent);
+      });
+      child.on("success", (upload) => {
+        this.handleChildSettled(idx, upload, "success");
+      });
+      child.on("error", (upload) => {
+        this.handleChildSettled(idx, upload, "error");
+      });
+      child.on("canceled", (upload) => {
+        this.handleChildSettled(idx, upload, "canceled");
+      });
+    }
+  }
+  /** @internal */
+  _start() {
+    this.fillSlots();
+  }
+  cancel() {
+    if (this.canceled || this.terminalEmitted) {
+      return;
+    }
+    this.canceled = true;
+    for (const h of this.uploads) {
+      const s = h.upload.status;
+      if (s === "queued" || s === "uploading" || s === "retrying" || s === "paused") {
+        h.cancel();
+      }
+    }
+    this.onChange();
+  }
+  pause() {
+    if (this.paused || this.canceled || this.terminalEmitted) {
+      return;
+    }
+    this.paused = true;
+    for (const h of this.uploads) {
+      if (h.upload.status === "uploading" || h.upload.status === "retrying") {
+        h.pause();
+      }
+    }
+    this.onChange();
+  }
+  resume() {
+    if (!this.paused || this.canceled || this.terminalEmitted) {
+      return;
+    }
+    this.paused = false;
+    for (const h of this.uploads) {
+      if (h.upload.status === "paused") {
+        h.resume();
+      }
+    }
+    this.fillSlots();
+    this.onChange();
+  }
+  snapshot() {
+    const totalProgress = this.aggregateTotalBytes > 0 ? this.aggregateBytesTransferred / this.aggregateTotalBytes * 100 : 0;
+    return {
+      completedCount: this.succeededCount,
+      failedCount: this.failedCount,
+      id: this.id,
+      totalProgress,
+      uploads: this.uploadsView
+    };
+  }
+  updateAggregate(idx, u) {
+    const prevBytes = this.lastBytes[idx] ?? 0;
+    const prevTotal = this.lastTotal[idx] ?? 0;
+    this.aggregateBytesTransferred += u.bytesTransferred - prevBytes;
+    this.aggregateTotalBytes += u.totalBytes - prevTotal;
+    this.lastBytes[idx] = u.bytesTransferred;
+    this.lastTotal[idx] = u.totalBytes;
+  }
+  fillSlots() {
+    while (!this.canceled && !this.paused && !this.failedFast && this.running < this.concurrency && this.nextIdx < this.uploads.length) {
+      const idx = this.nextIdx;
+      this.nextIdx += 1;
+      const handle = this.uploads[idx];
+      if (!handle || handle.upload.status !== "queued") {
+        continue;
+      }
+      this.activeSlots.add(idx);
+      this.running += 1;
+      this.startNext(handle);
+    }
+  }
+  handleChildProgress(idx, upload) {
+    this.updateAggregate(idx, upload);
+    const snap = this.snapshot();
+    this.emit("progress", snap);
+    this.emit("change", snap);
+  }
+  handleChildRetry(idx, event) {
+    this.updateAggregate(idx, event.upload);
+    this.emit("uploadRetry", event);
+    const snap = this.snapshot();
+    this.emit("change", snap);
+  }
+  handleChildSettled(idx, upload, kind) {
+    this.updateAggregate(idx, upload);
+    if (this.activeSlots.delete(idx)) {
+      this.running = Math.max(0, this.running - 1);
+    }
+    this.settledCount += 1;
+    if (kind === "success") {
+      this.succeededCount += 1;
+      this.emit("uploadSuccess", upload);
+    } else if (kind === "error") {
+      this.failedCount += 1;
+      this.emit("uploadError", upload);
+    }
+    const snap = this.snapshot();
+    this.emit("change", snap);
+    if (kind === "error" && !this.continueOnError && !this.failedFast && !this.canceled) {
+      this.failedFast = true;
+      for (const h of this.uploads) {
+        if (h.upload.id === upload.id) {
+          continue;
+        }
+        const s = h.upload.status;
+        if (s === "queued" || s === "uploading" || s === "retrying" || s === "paused") {
+          h.cancel();
+        }
+      }
+      this.terminalEmitted = true;
+      this.emit("error", snap);
+      this.onChange();
+      return;
+    }
+    if (this.failedFast || this.canceled) {
+      this.onChange();
+      return;
+    }
+    this.fillSlots();
+    if (this.settledCount >= this.uploads.length && !this.terminalEmitted) {
+      this.terminalEmitted = true;
+      this.emit("success", snap);
+    }
+    this.onChange();
+  }
+};
+
+// src/core/retry.ts
+var DEFAULT_RETRY_OPTIONS = {
+  initialDelayMs: 1e3,
+  jitter: true,
+  maxDelayMs: 3e4,
+  maxRetries: 3
+};
+var NON_RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  "storage/canceled",
+  "storage/unauthorized",
+  "storage/unauthenticated",
+  "storage/quota-exceeded",
+  "storage/invalid-argument",
+  "storage/invalid-argument-count",
+  "storage/invalid-url",
+  "storage/invalid-default-bucket",
+  "storage/no-default-bucket",
+  "storage/bucket-not-found",
+  "storage/project-not-found",
+  "storage/invalid-root-operation",
+  "storage/invalid-event-name",
+  "storage/invalid-format",
+  "storage/no-download-url",
+  "storage/unauthorized-app",
+  "storage/unsupported-environment"
+]);
+var RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  "storage/retry-limit-exceeded",
+  "storage/unknown",
+  "storage/invalid-checksum",
+  "storage/cannot-slice-blob",
+  "storage/server-file-wrong-size"
+]);
+var resolveRetryOptions = (retry) => {
+  if (retry === false) {
+    return null;
+  }
+  return {
+    ...DEFAULT_RETRY_OPTIONS,
+    ...retry
+  };
+};
+var hasStorageErrorCode = (error) => "code" in error && typeof error.code === "string";
+var getStorageErrorCode = (error) => {
+  if (!hasStorageErrorCode(error)) {
+    return void 0;
+  }
+  return error.code;
+};
+var isRetryableStorageError = (error, options) => {
+  if (!options) {
+    return false;
+  }
+  if (options.isRetryable) {
+    return options.isRetryable(error);
+  }
+  const code = getStorageErrorCode(error);
+  if (code !== void 0) {
+    if (NON_RETRYABLE_CODES.has(code)) {
+      return false;
+    }
+    if (RETRYABLE_CODES.has(code)) {
+      return true;
+    }
+    return false;
+  }
+  return true;
+};
+var computeRetryDelay = (failedAttempt, options) => {
+  const base = Math.min(
+    options.maxDelayMs,
+    options.initialDelayMs * 2 ** (failedAttempt - 1)
+  );
+  if (!options.jitter) {
+    return base;
+  }
+  return Math.round(base * (0.5 + Math.random() * 0.5));
+};
+
+// src/core/upload-handle.ts
+var UploadHandle = class extends Emitter {
+  upload;
+  task = null;
+  onChange;
+  terminated = false;
+  controlHooks = null;
+  pausedDuringRetry = false;
+  constructor(upload, onChange) {
+    super();
+    this.upload = upload;
+    this.onChange = onChange;
+  }
+  /** @internal */
+  _attachTask(task) {
+    this.task = task;
+  }
+  /** @internal */
+  _registerControlHooks(hooks) {
+    this.controlHooks = hooks;
+  }
+  /** @internal */
+  _clearControlHooks() {
+    this.controlHooks = null;
+  }
+  /** @internal */
+  _setStatus(status) {
+    if (this.upload.status === status) {
+      return;
+    }
+    this.upload.status = status;
+    this.emit("statusChange", this.upload);
+  }
+  /** @internal */
+  _reportProgress(bytesTransferred, totalBytes) {
+    if (this.terminated) {
+      return;
+    }
+    this.upload.bytesTransferred = bytesTransferred;
+    this.upload.totalBytes = totalBytes;
+    this.upload.progress = totalBytes > 0 ? bytesTransferred / totalBytes * 100 : 0;
+    if (this.upload.status !== "uploading") {
+      this._setStatus("uploading");
+    }
+    this.emit("progress", this.upload);
+    this.onChange();
+  }
+  /** @internal */
+  _prepareRetryAttempt(attempt) {
+    if (this.terminated) {
+      return;
+    }
+    this.upload.retryAttempt = attempt;
+    this.upload.bytesTransferred = 0;
+    this.upload.progress = 0;
+    this.upload.error = void 0;
+    this.pausedDuringRetry = false;
+    this._setStatus("uploading");
+    this.onChange();
+  }
+  /** @internal */
+  _enterRetryBackoff(details) {
+    if (this.terminated) {
+      return;
+    }
+    this.upload.retryAttempt = details.attempt;
+    this.upload.error = details.error;
+    this.task = null;
+    this._setStatus("retrying");
+    this.emit("retry", {
+      attempt: details.attempt,
+      delayMs: details.delayMs,
+      error: details.error,
+      maxAttempts: details.maxAttempts,
+      upload: this.upload
+    });
+    this.onChange();
+  }
+  /** @internal */
+  _reportSuccess(downloadURL) {
+    if (this.terminated) {
+      return;
+    }
+    this.terminated = true;
+    this.upload.downloadURL = downloadURL;
+    this.upload.progress = 100;
+    this._clearControlHooks();
+    this._setStatus("success");
+    this.emit("success", this.upload);
+    this.onChange();
+  }
+  /** @internal */
+  _reportError(error) {
+    if (this.terminated) {
+      return;
+    }
+    this.terminated = true;
+    this.upload.error = error;
+    this._clearControlHooks();
+    this._setStatus("error");
+    this.emit("error", this.upload);
+    this.onChange();
+  }
+  cancel() {
+    if (this.terminated) {
+      return;
+    }
+    this.terminated = true;
+    this.controlHooks?.abort();
+    this.task?.cancel();
+    this._clearControlHooks();
+    this._setStatus("canceled");
+    this.emit("canceled", this.upload);
+    this.onChange();
+  }
+  pause() {
+    if (this.terminated) {
+      return;
+    }
+    if (this.upload.status === "uploading") {
+      this.task?.pause?.();
+      this._setStatus("paused");
+      this.onChange();
+      return;
+    }
+    if (this.upload.status === "retrying") {
+      this.pausedDuringRetry = true;
+      this.controlHooks?.pauseDuringRetry?.();
+      this._setStatus("paused");
+      this.onChange();
+    }
+  }
+  resume() {
+    if (this.terminated) {
+      return;
+    }
+    if (this.upload.status !== "paused") {
+      return;
+    }
+    if (this.pausedDuringRetry) {
+      this.pausedDuringRetry = false;
+      this.controlHooks?.resumeDuringRetry?.();
+      this.onChange();
+      return;
+    }
+    this.task?.resume?.();
+    this._setStatus("uploading");
+    this.onChange();
+  }
+};
+
+// src/core/storage-manager.ts
+var StorageManager = class {
+  provider;
+  uploadHandles = [];
+  batches = [];
+  changeListeners = /* @__PURE__ */ new Set();
+  cachedState = null;
+  uploadOptionsByHandleId = /* @__PURE__ */ new Map();
+  constructor(provider) {
+    this.provider = provider;
+  }
+  /** Current `uploads` and `batches` state. */
+  getState = () => {
+    this.cachedState ??= {
+      batches: this.batches.map((b) => b.snapshot()),
+      uploads: this.uploadHandles.map((h) => h.upload)
+    };
+    return this.cachedState;
+  };
+  /** Runs `listener` after each change; returns a function — call it to unsubscribe. */
+  subscribe = (listener) => {
+    this.changeListeners.add(listener);
+    return () => {
+      this.changeListeners.delete(listener);
+    };
+  };
+  /** Returns `true` if the object exists. Returns `false` only for not-found; other errors are thrown. */
+  async exists(path) {
+    return await this.provider.exists(path);
+  }
+  /** Returns metadata for the object at `path`. Throws if the object does not exist. */
+  async getMetadata(path) {
+    return await this.provider.getMetadata(path);
+  }
+  /** Returns a download URL for the object at `path`. */
+  async getDownloadURL(path) {
+    return await this.provider.getDownloadURL(path);
+  }
+  /** Deletes the object at `path`. */
+  async delete(path) {
+    await this.provider.delete(path);
+  }
+  /** Starts the file upload.`options.path` is the object path in storage (see {@link UploadOptions}).
+   *
+   * @returns An {@link UploadHandle} to control the upload: `pause`, `resume`, `cancel`, and listen for progress with `.on`.
+   */
+  uploadFile(file, options) {
+    const handle = this.createHandle(file, { path: options.path });
+    this.uploadOptionsByHandleId.set(handle.upload.id, options);
+    this.uploadHandles.push(handle);
+    this.notifyChange();
+    this.startUpload(handle, options);
+    return handle;
+  }
+  /**
+   * Upload several files as one batch. The optional third argument sets how many run at once
+   * and what happens when one file fails — see {@link BatchOptions}.
+   *
+   * `optionsFor` picks storage options per file (same as `uploadFile`); index matches `files` order.
+   * If `continueOnError` is `false`, the first failure cancels the other files and the batch fires `error`.
+   * If it stays `true` (default), other files keep going; when every file has finished, the batch fires `success`.
+   *
+   */
+  uploadFiles(files, optionsFor, batchOptions = {}) {
+    const id = crypto.randomUUID();
+    const handles = files.map((file, i) => {
+      const options = optionsFor(file, i);
+      const handle = this.createHandle(file, {
+        batchId: id,
+        path: options.path
+      });
+      this.uploadOptionsByHandleId.set(handle.upload.id, options);
+      return handle;
+    });
+    this.uploadHandles.push(...handles);
+    const batch = new BatchHandle({
+      id,
+      onChange: () => {
+        this.notifyChange();
+      },
+      options: batchOptions,
+      startNext: (handle) => {
+        const options = this.uploadOptionsByHandleId.get(handle.upload.id) ?? {
+          path: handle.upload.path
+        };
+        this.startUpload(handle, options);
+      },
+      uploads: handles
+    });
+    this.batches.push(batch);
+    this.notifyChange();
+    batch._start();
+    return batch;
+  }
+  createHandle(file, options) {
+    const upload = {
+      bytesTransferred: 0,
+      file,
+      id: crypto.randomUUID(),
+      path: options.path,
+      progress: 0,
+      status: "queued",
+      totalBytes: file.size,
+      ...options.batchId === void 0 ? {} : { batchId: options.batchId }
+    };
+    return new UploadHandle(upload, () => {
+      this.notifyChange();
+    });
+  }
+  startUpload(handle, options) {
+    const retryOptions = resolveRetryOptions(options.retry);
+    const maxAttempts = retryOptions ? retryOptions.maxRetries + 1 : 1;
+    let attempt = 0;
+    let retryTimeout = null;
+    let currentTask = null;
+    let aborted = false;
+    let pausedDuringRetry = false;
+    let pendingRetryError = null;
+    const clearRetryTimeout = () => {
+      if (retryTimeout !== null) {
+        clearTimeout(retryTimeout);
+        retryTimeout = null;
+      }
+    };
+    const abort = () => {
+      aborted = true;
+      clearRetryTimeout();
+      currentTask?.cancel();
+      currentTask = null;
+      pendingRetryError = null;
+    };
+    const retryController = {
+      runAttempt: () => {
+        if (aborted) {
+          return;
+        }
+        attempt += 1;
+        handle._prepareRetryAttempt(attempt);
+        currentTask = this.provider.upload(handle.upload.file, options, {
+          onError: (error) => {
+            currentTask = null;
+            if (aborted) {
+              return;
+            }
+            if (attempt < maxAttempts && isRetryableStorageError(error, retryOptions)) {
+              const delayMs = retryOptions ? computeRetryDelay(attempt, retryOptions) : 0;
+              retryController.scheduleRetry(error, delayMs);
+              return;
+            }
+            handle._reportError(error);
+          },
+          onProgress: (bytesTransferred, totalBytes) => {
+            handle._reportProgress(bytesTransferred, totalBytes);
+          },
+          onSuccess: (downloadURL) => {
+            currentTask = null;
+            if (aborted) {
+              return;
+            }
+            handle._reportSuccess(downloadURL);
+          }
+        });
+        handle._attachTask(currentTask);
+      },
+      scheduleRetry: (error, delayMs) => {
+        if (aborted) {
+          return;
+        }
+        pendingRetryError = error;
+        handle._enterRetryBackoff({
+          attempt: attempt + 1,
+          delayMs,
+          error,
+          maxAttempts
+        });
+        retryTimeout = setTimeout(() => {
+          retryTimeout = null;
+          if (aborted || pausedDuringRetry) {
+            return;
+          }
+          pendingRetryError = null;
+          retryController.runAttempt();
+        }, delayMs);
+      }
+    };
+    handle._registerControlHooks({
+      abort,
+      pauseDuringRetry: () => {
+        pausedDuringRetry = true;
+        clearRetryTimeout();
+      },
+      resumeDuringRetry: () => {
+        if (aborted) {
+          return;
+        }
+        pausedDuringRetry = false;
+        if (pendingRetryError) {
+          retryController.scheduleRetry(pendingRetryError, 0);
+        }
+      }
+    });
+    retryController.runAttempt();
+  }
+  notifyChange() {
+    this.cachedState = null;
+    const state = this.getState();
+    for (const listener of this.changeListeners) {
+      listener(state);
+    }
+  }
+};
+var isStorageError = (error) => typeof error === "object" && error !== null && "code" in error && typeof error.code === "string";
+var toError = (error) => error instanceof Error ? error : new Error(String(error));
+var FirebaseStorageProvider = class {
+  storage;
+  constructor(storage) {
+    this.storage = storage;
+  }
+  upload(file, options, callbacks) {
+    const storageRef = ref(this.storage, options.path);
+    const metadata = options.customMetadata ? { customMetadata: options.customMetadata } : void 0;
+    const task = uploadBytesResumable(storageRef, file, metadata);
+    task.on(
+      "state_changed",
+      (snapshot) => {
+        callbacks.onProgress(snapshot.bytesTransferred, snapshot.totalBytes);
+      },
+      (error) => {
+        callbacks.onError(error);
+      },
+      () => {
+        void (async () => {
+          try {
+            const downloadURL = await getDownloadURL(storageRef);
+            callbacks.onSuccess(downloadURL);
+          } catch (error) {
+            callbacks.onError(toError(error));
+          }
+        })();
+      }
+    );
+    return {
+      cancel: () => {
+        task.cancel();
+      },
+      pause: () => {
+        task.pause();
+      },
+      resume: () => {
+        task.resume();
+      }
+    };
+  }
+  async exists(path) {
+    try {
+      await getMetadata(ref(this.storage, path));
+      return true;
+    } catch (error) {
+      if (isStorageError(error) && error.code === "storage/object-not-found") {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async getMetadata(path) {
+    const meta = await getMetadata(ref(this.storage, path));
+    return {
+      contentType: meta.contentType,
+      createdAt: new Date(meta.timeCreated),
+      customMetadata: meta.customMetadata,
+      path,
+      size: meta.size,
+      updatedAt: new Date(meta.updated)
+    };
+  }
+  async getDownloadURL(path) {
+    return await getDownloadURL(ref(this.storage, path));
+  }
+  async delete(path) {
+    await deleteObject(ref(this.storage, path));
+  }
+};
+
+// src/firebase-storage-manager.ts
+var StorageManager2 = class extends StorageManager {
+  constructor(storage) {
+    super(new FirebaseStorageProvider(storage));
+  }
+};
+
+export { BatchHandle, DEFAULT_RETRY_OPTIONS, StorageManager2 as StorageManager, UploadHandle, computeRetryDelay, getStorageErrorCode, isRetryableStorageError, resolveRetryOptions };
+//# sourceMappingURL=chunk-PBO3CMOD.js.map
+//# sourceMappingURL=chunk-PBO3CMOD.js.map