@better-s3/react 3.1045.2 → 3.1047.0

package/dist/index.js

@@ -1,48 +1,110 @@
-import { validateFile } from '@better-s3/server';
-export { createS3Api as createPresignApi, createS3Api, validateFile } from '@better-s3/server';
-import { useState, useRef, useCallback } from 'react';
+import { createContext, useContext, useState, useRef, useCallback } from 'react';
+import { jsx } from 'react/jsx-runtime';
 
-// src/helpers.ts
-function parseContentDispositionFilename(header, fallback) {
-  if (!header) return fallback;
-  const starMatch = header.match(/filename\*=UTF-8''([^;,\s]+)/i);
-  if (starMatch) {
-    try {
-      return decodeURIComponent(starMatch[1]);
-    } catch {
-    }
+// src/types/error.ts
+var S3UploadError = class extends Error {
+  constructor(message, code, statusCode, phase) {
+    super(message);
+    this.name = "S3UploadError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.phase = phase;
   }
-  const match = header.match(/filename="([^"]+)"/i);
-  if (match) return match[1];
-  return fallback;
+};
+
+// src/api.ts
+function createS3Client(input) {
+  return input;
 }
-function formatFileSize(bytes) {
-  if (bytes === 0) return "0 B";
-  const units = ["B", "KB", "MB", "GB", "TB"];
-  const i = Math.floor(Math.log(bytes) / Math.log(1024));
-  const size = bytes / Math.pow(1024, i);
-  return `${size.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+var createS3Api = createS3Client;
+var S3Context = createContext(null);
+function S3Provider({
+  client,
+  children
+}) {
+  return /* @__PURE__ */ jsx(S3Context.Provider, { value: client, children });
+}
+function useS3Client() {
+  const ctx = useContext(S3Context);
+  if (!ctx) {
+    throw new Error(
+      "[better-s3] No S3Api client found. Either wrap your app with <S3Provider client={...}> or pass `api` directly to the hook."
+    );
+  }
+  return ctx;
+}
+
+// src/store/local-storage-store.ts
+var STORAGE_PREFIX = "better-s3:upload:";
+function createLocalStorageStore() {
+  return {
+    get(key, fileSize) {
+      try {
+        const raw = localStorage.getItem(STORAGE_PREFIX + key);
+        if (!raw) return null;
+        const stored = JSON.parse(raw);
+        return stored.fileSize === fileSize ? stored : null;
+      } catch {
+        return null;
+      }
+    },
+    set(upload) {
+      try {
+        localStorage.setItem(
+          STORAGE_PREFIX + upload.key,
+          JSON.stringify(upload)
+        );
+      } catch {
+      }
+    },
+    delete(key) {
+      try {
+        localStorage.removeItem(STORAGE_PREFIX + key);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/store/memory-store.ts
+function createMemoryStore() {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    get(key, fileSize) {
+      const stored = map.get(key);
+      if (!stored) return null;
+      return stored.fileSize === fileSize ? stored : null;
+    },
+    set(upload) {
+      map.set(upload.key, upload);
+    },
+    delete(key) {
+      map.delete(key);
+    }
+  };
 }
 
 // src/upload/constants.ts
-var DEFAULT_MULTIPART_THRESHOLD = 30 * 1024 * 1024;
-var DEFAULT_PART_SIZE = 10 * 1024 * 1024;
+var DEFAULT_MULTIPART_THRESHOLD = 50 * 1024 * 1024;
+var DEFAULT_PART_SIZE = 5 * 1024 * 1024;
 var MAX_RETRIES = 3;
 var RETRY_BASE_DELAY = 1e3;
-var DEFAULT_CONCURRENT_PARTS = 3;
+var DEFAULT_CONCURRENT_PARTS = 2;
 var DEFAULT_CONCURRENT_FILES = 2;
 
 // src/upload/retry.ts
-async function withRetry(fn, retries, signal) {
+async function withRetry(fn, retryConfig, signal) {
+  const maxRetries = retryConfig?.maxRetries ?? MAX_RETRIES;
+  const baseDelay = retryConfig?.baseDelay ?? RETRY_BASE_DELAY;
   let lastError;
-  for (let attempt = 0; attempt <= retries; attempt++) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
       return await fn();
     } catch (err) {
       if (err.name === "AbortError") throw err;
       lastError = err;
-      if (attempt < retries) {
-        const delay = RETRY_BASE_DELAY * 2 ** attempt;
+      if (attempt < maxRetries) {
+        const delay = baseDelay * 2 ** attempt;
         await new Promise((r) => setTimeout(r, delay));
         if (signal?.aborted)
           throw new DOMException("Upload aborted", "AbortError");
@@ -177,22 +239,69 @@ function uploadPart(blob, presignedUrl, partLoaded, totalSize, reportProgress, s
 }
 
 // src/upload/multipart.ts
-async function uploadMultipart(api, file, objectKey, partSize, concurrentParts, onProgress, signal, requestOptions) {
+function resolvePartSize(partIndex, totalParts, partSize, fileSize) {
+  return partIndex === totalParts - 1 ? fileSize - partIndex * partSize : partSize;
+}
+async function uploadMultipart(api, file, objectKey, partSize, concurrentParts, onProgress, signal, requestOptions, retryConfig, uploadStore, onPartUpload, onMultipartInit) {
+  const bucket = requestOptions?.bucket;
   const contentType = requestOptions?.contentType ?? file.type;
-  const { uploadId, key } = await api.multipart.init({
-    key: objectKey,
-    contentType,
-    fileSize: file.size,
-    fileName: requestOptions?.fileName !== null ? requestOptions?.fileName ?? file.name : void 0,
-    metadata: requestOptions?.metadata,
-    bucket: requestOptions?.bucket,
-    acl: requestOptions?.acl
-  });
+  const store = uploadStore != null && uploadStore !== false ? uploadStore : null;
+  let uploadId;
+  let key;
+  const completedPartNumbers = /* @__PURE__ */ new Set();
+  const existing = store ? await store.get(objectKey, file.size) : null;
+  if (existing) {
+    try {
+      const { parts: parts2 } = await api.multipart.listParts({
+        key: existing.key,
+        uploadId: existing.uploadId,
+        bucket: bucket ?? existing.bucket
+      });
+      uploadId = existing.uploadId;
+      key = existing.key;
+      for (const p of parts2) completedPartNumbers.add(p.partNumber);
+      onMultipartInit?.(uploadId, key);
+    } catch {
+      await store?.delete(objectKey);
+      const result = await api.multipart.init({
+        key: objectKey,
+        contentType,
+        fileSize: file.size,
+        fileName: requestOptions?.fileName !== null ? requestOptions?.fileName ?? file.name : void 0,
+        metadata: requestOptions?.metadata,
+        bucket,
+        acl: requestOptions?.acl
+      });
+      uploadId = result.uploadId;
+      key = result.key;
+      await store?.set({ uploadId, key, fileSize: file.size, bucket });
+      onMultipartInit?.(uploadId, key);
+    }
+  } else {
+    const result = await api.multipart.init({
+      key: objectKey,
+      contentType,
+      fileSize: file.size,
+      fileName: requestOptions?.fileName !== null ? requestOptions?.fileName ?? file.name : void 0,
+      metadata: requestOptions?.metadata,
+      bucket,
+      acl: requestOptions?.acl
+    });
+    uploadId = result.uploadId;
+    key = result.key;
+    await store?.set({ uploadId, key, fileSize: file.size, bucket });
+    onMultipartInit?.(uploadId, key);
+  }
   const totalParts = Math.ceil(file.size / partSize);
-  const parts = [];
   const partProgress = Array.from(
     { length: totalParts },
-    () => ({ bytes: 0 })
+    (_, i) => ({
+      bytes: completedPartNumbers.has(i + 1) ? resolvePartSize(i, totalParts, partSize, file.size) : 0
+    })
+  );
+  const parts = Array.from(
+    completedPartNumbers,
+    (n) => ({ partNumber: n })
   );
   const reportProgress = () => {
     const loaded = partProgress.reduce((sum, p) => sum + p.bytes, 0);
@@ -202,6 +311,9 @@ async function uploadMultipart(api, file, objectKey, partSize, concurrentParts,
       percent: Math.round(loaded / file.size * 100)
     });
   };
+  if (completedPartNumbers.size > 0) {
+    reportProgress();
+  }
   try {
     for (let batchStart = 0; batchStart < totalParts; batchStart += concurrentParts) {
       if (signal?.aborted) {
@@ -210,10 +322,11 @@ async function uploadMultipart(api, file, objectKey, partSize, concurrentParts,
       const batchEnd = Math.min(batchStart + concurrentParts, totalParts);
       const batch = [];
       for (let i = batchStart; i < batchEnd; i++) {
+        const partNumber = i + 1;
+        if (completedPartNumbers.has(partNumber)) continue;
         const start = i * partSize;
         const end = Math.min(start + partSize, file.size);
         const blob = file.slice(start, end);
-        const partNumber = i + 1;
         batch.push(
           withRetry(
             async () => {
@@ -221,11 +334,8 @@ async function uploadMultipart(api, file, objectKey, partSize, concurrentParts,
                 key,
                 uploadId,
                 partNumber,
-                // Pass the exact byte count so the server binds Content-Length
-                // into the HMAC signature.  S3 will then reject any PUT whose
-                // body size differs from blob.size with SignatureDoesNotMatch.
                 partSize: blob.size,
-                bucket: requestOptions?.bucket
+                bucket
               });
               partProgress[i].bytes = 0;
               await uploadPart(
@@ -236,9 +346,10 @@ async function uploadMultipart(api, file, objectKey, partSize, concurrentParts,
                 reportProgress,
                 signal
               );
+              onPartUpload?.(partNumber, totalParts);
               return { partNumber };
             },
-            MAX_RETRIES,
+            retryConfig,
             signal
           )
         );
@@ -251,13 +362,16 @@ async function uploadMultipart(api, file, objectKey, partSize, concurrentParts,
       key,
       uploadId,
       parts,
-      bucket: requestOptions?.bucket
+      bucket
     });
+    await store?.delete(objectKey);
     onProgress?.({ loaded: file.size, total: file.size, percent: 100 });
     return result.eTag;
   } catch (err) {
-    api.multipart.abort({ key, uploadId, bucket: requestOptions?.bucket }).catch(() => {
-    });
+    if (store === null) {
+      api.multipart.abort({ key, uploadId, bucket }).catch(() => {
+      });
+    }
     throw err;
   }
 }
@@ -267,6 +381,7 @@ async function uploadFile(api, file, objectKey, config = {}, callbacks = {}, sig
   const threshold = config.multipartThreshold ?? DEFAULT_MULTIPART_THRESHOLD;
   const useMultipart = config.multipart === true && file.size >= threshold;
   const concurrentParts = config.concurrentParts ?? DEFAULT_CONCURRENT_PARTS;
+  const partSize = requestOptions?.partSize ?? config.partSize ?? DEFAULT_PART_SIZE;
   const contentType = requestOptions?.contentType ?? file.type;
   let eTag;
   if (useMultipart) {
@@ -275,11 +390,15 @@ async function uploadFile(api, file, objectKey, config = {}, callbacks = {}, sig
       api,
       file,
       objectKey,
-      DEFAULT_PART_SIZE,
+      partSize,
       concurrentParts,
       callbacks.onProgress,
       signal,
-      requestOptions
+      requestOptions,
+      config.retry,
+      config.uploadStore,
+      callbacks.onPartUpload,
+      callbacks.onMultipartInit
     );
   } else {
     await withRetry(
@@ -313,7 +432,7 @@ async function uploadFile(api, file, objectKey, config = {}, callbacks = {}, sig
           );
         }
       },
-      MAX_RETRIES,
+      config.retry,
       signal
     );
     callbacks.onPhaseChange?.("finalizing");
@@ -398,6 +517,143 @@ async function uploadFiles(api, items, config = {}, callbacks = {}, signal, getR
   await Promise.all(workers);
   return results;
 }
+
+// src/helpers/format-file-size.ts
+function formatFileSize(bytes) {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const size = bytes / Math.pow(1024, i);
+  return `${size.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}
+
+// src/helpers/validate-file.ts
+function validateFile(file, options) {
+  if (options.accept?.length) {
+    const allowed = options.accept.some((type) => {
+      if (type.startsWith(".")) {
+        return file.name.toLowerCase().endsWith(type.toLowerCase());
+      }
+      if (type.endsWith("/*")) {
+        return file.type.startsWith(type.replace("/*", "/"));
+      }
+      return file.type === type;
+    });
+    if (!allowed) {
+      const ext = file.name.includes(".") ? file.name.split(".").pop() : null;
+      return `File type "${ext ? `.${ext}` : file.type || "unknown"}" is not allowed`;
+    }
+  }
+  if (file.size === 0) {
+    return "File is empty";
+  }
+  if (options.maxFileSize && file.size > options.maxFileSize) {
+    const maxMB = (options.maxFileSize / (1024 * 1024)).toFixed(1);
+    return `File size exceeds ${maxMB} MB limit`;
+  }
+  return null;
+}
+
+// src/helpers/parse-content-disposition.ts
+function parseContentDispositionFilename(header, fallback) {
+  if (!header) return fallback;
+  const starMatch = header.match(/filename\*=UTF-8''([^;,\s]+)/i);
+  if (starMatch) {
+    try {
+      return decodeURIComponent(starMatch[1]);
+    } catch {
+    }
+  }
+  const match = header.match(/filename="([^"]+)"/i);
+  if (match) return match[1];
+  return fallback;
+}
+
+// src/helpers/format-upload-progress.ts
+function formatUploadProgress(loaded, total, percent) {
+  const loadedStr = formatFileSize(loaded);
+  if (!total) return loadedStr;
+  return `${loadedStr} / ${formatFileSize(total)} (${Math.round(percent)}%)`;
+}
+
+// src/helpers/format-speed.ts
+function formatSpeed(bytesPerSecond) {
+  return `${formatFileSize(bytesPerSecond)}/s`;
+}
+
+// src/helpers/format-eta.ts
+function formatEta(remainingBytes, bytesPerSecond) {
+  if (bytesPerSecond <= 0 || remainingBytes <= 0) return null;
+  const totalSeconds = remainingBytes / bytesPerSecond;
+  if (totalSeconds < 60) return `${Math.ceil(totalSeconds)}s`;
+  const totalMinutes = totalSeconds / 60;
+  if (totalMinutes < 60) return `${Math.ceil(totalMinutes)}m`;
+  const hours = Math.floor(totalMinutes / 60);
+  const mins = Math.ceil(totalMinutes % 60);
+  return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`;
+}
+
+// src/helpers/build-object-key.ts
+function buildObjectKey(...parts) {
+  return parts.map((p) => p.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+}
+
+// src/helpers/get-file-extension.ts
+function getFileExtension(filename) {
+  const dotIndex = filename.lastIndexOf(".");
+  if (dotIndex < 1) return "";
+  return filename.slice(dotIndex + 1).toLowerCase();
+}
+
+// src/helpers/truncate-filename.ts
+function truncateFilename(name, maxChars = 26) {
+  if (name.length <= maxChars) return name;
+  const dotIndex = name.lastIndexOf(".");
+  if (dotIndex <= 0) {
+    return name.slice(0, maxChars - 1) + "\u2026";
+  }
+  const ext = name.slice(dotIndex);
+  const available = maxChars - ext.length - 1;
+  if (available <= 0) {
+    return name.slice(0, maxChars - 1) + "\u2026";
+  }
+  return name.slice(0, available) + "\u2026 " + ext;
+}
+
+// src/helpers/speed-tracker.ts
+function createSpeedTracker(windowMs = 3e3) {
+  const samples = [];
+  return {
+    /**
+     * Record the latest cumulative `loaded` byte count.
+     * Returns the current speed in bytes/second (0 until at least 2 samples exist).
+     */
+    update(loaded) {
+      const now = Date.now();
+      samples.push({ t: now, loaded });
+      const cutoff = now - windowMs;
+      while (samples.length > 1 && samples[0].t < cutoff) {
+        samples.shift();
+      }
+      if (samples.length < 2) return 0;
+      const oldest = samples[0];
+      const newest = samples[samples.length - 1];
+      const deltaMs = newest.t - oldest.t;
+      const deltaBytes = newest.loaded - oldest.loaded;
+      return deltaMs > 0 ? Math.round(deltaBytes / deltaMs * 1e3) : 0;
+    },
+    reset() {
+      samples.length = 0;
+    }
+  };
+}
+function useLiveRef(value) {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+
+// src/hooks/use-upload.ts
 var INITIAL_PROGRESS = { loaded: 0, total: 0, percent: 0 };
 var INITIAL_STATE = {
   phase: "idle",
@@ -409,9 +665,15 @@ var INITIAL_STATE = {
 };
 function useUpload(options) {
   const [state, setState] = useState(INITIAL_STATE);
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
+  const contextApi = useContext(S3Context);
+  const optsRef = useLiveRef(options);
+  const apiRef = useLiveRef(contextApi);
   const abortRef = useRef(null);
+  const activeUploadRef = useRef(null);
+  const detachingRef = useRef(false);
+  const speedTrackerRef = useRef(createSpeedTracker());
+  const lastSpeedRef = useRef(void 0);
+  const lastSpeedUpdateRef = useRef(0);
   const upload = useCallback(
     async (file, objectKey, requestOptions) => {
       setState({
@@ -420,7 +682,12 @@ function useUpload(options) {
         fileName: file.name,
         fileSize: file.size
       });
-      const opts = optionsRef.current;
+      const opts = optsRef.current;
+      const api = opts.api ?? apiRef.current;
+      if (!api)
+        throw new Error(
+          "[better-s3] No S3Api client found. Pass `api` to useUpload or wrap with <S3Provider>."
+        );
       const validationError = validateFile(file, {
         accept: opts.accept,
         maxFileSize: opts.maxFileSize
@@ -442,26 +709,55 @@ function useUpload(options) {
           return;
         }
       }
+      speedTrackerRef.current.reset();
+      lastSpeedRef.current = void 0;
+      lastSpeedUpdateRef.current = 0;
       setState((s) => ({ ...s, phase: "presigning" }));
       opts.onUploadStart?.(file, objectKey);
       const controller = new AbortController();
       abortRef.current = controller;
+      activeUploadRef.current = {
+        file,
+        objectKey,
+        serverKey: objectKey,
+        bucket: requestOptions?.bucket,
+        requestOptions
+      };
       try {
         const result = await uploadFile(
-          opts.api,
+          api,
           file,
           objectKey,
           {
             multipart: opts.multipart,
             multipartThreshold: opts.multipartThreshold,
-            concurrentParts: opts.concurrentParts
+            concurrentParts: opts.concurrentParts,
+            partSize: opts.partSize,
+            retry: opts.retry,
+            uploadStore: opts.uploadStore
           },
           {
             onProgress: (progress) => {
-              setState((s) => ({ ...s, progress }));
-              opts.onProgress?.(file, progress);
+              const rawSpeed = speedTrackerRef.current.update(progress.loaded);
+              const now = Date.now();
+              if (rawSpeed > 0 && now - lastSpeedUpdateRef.current >= 500) {
+                lastSpeedRef.current = rawSpeed;
+                lastSpeedUpdateRef.current = now;
+              }
+              const speed = lastSpeedRef.current;
+              const p = speed ? { ...progress, speed } : progress;
+              setState((s) => ({ ...s, progress: p }));
+              opts.onProgress?.(file, p);
             },
-            onPhaseChange: (phase) => setState((s) => ({ ...s, phase }))
+            onPhaseChange: (phase) => setState((s) => ({ ...s, phase })),
+            onPartUpload: (partNumber, totalParts) => opts.onPartUpload?.(file, partNumber, totalParts),
+            onMultipartInit: (uploadId, serverKey) => {
+              if (activeUploadRef.current) {
+                activeUploadRef.current.uploadId = uploadId;
+                activeUploadRef.current.serverKey = serverKey;
+              }
+              opts.onMultipartInit?.(file, uploadId);
+            }
           },
           controller.signal,
           requestOptions
@@ -475,6 +771,10 @@ function useUpload(options) {
         await opts.onSuccess?.(file, result);
       } catch (err) {
         if (err.name === "AbortError") {
+          if (detachingRef.current) {
+            detachingRef.current = false;
+            return;
+          }
           opts.onCancel?.(file);
           setState(INITIAL_STATE);
           return;
@@ -484,11 +784,34 @@ function useUpload(options) {
         opts.onError?.(file, err, "uploading");
       } finally {
         abortRef.current = null;
+        activeUploadRef.current = null;
       }
     },
     []
   );
   const cancel = useCallback(() => {
+    const opts = optsRef.current;
+    const api = opts.api ?? apiRef.current;
+    const active = activeUploadRef.current;
+    abortRef.current?.abort();
+    if (active && api) {
+      const { objectKey, serverKey, uploadId, bucket } = active;
+      const store = opts.uploadStore;
+      if (store != null && store !== false) {
+        void Promise.resolve(store.delete(objectKey)).catch(() => {
+        });
+      }
+      if (uploadId) {
+        api.multipart.abort({ key: serverKey, uploadId, bucket }).catch(() => {
+        });
+      }
+    }
+    setState(INITIAL_STATE);
+  }, []);
+  const detach = useCallback(() => {
+    const active = activeUploadRef.current;
+    if (!active) return;
+    detachingRef.current = true;
     abortRef.current?.abort();
     setState(INITIAL_STATE);
   }, []);
@@ -496,7 +819,7 @@ function useUpload(options) {
     abortRef.current?.abort();
     setState(INITIAL_STATE);
   }, []);
-  return { ...state, upload, cancel, reset };
+  return { ...state, upload, cancel, detach, reset };
 }
 var INITIAL_PROGRESS2 = { loaded: 0, total: 0, percent: 0 };
 var INITIAL_STATE2 = {
@@ -505,19 +828,31 @@ var INITIAL_STATE2 = {
   totalProgress: INITIAL_PROGRESS2,
   error: null
 };
-var nextId = 0;
 function generateId() {
-  return `file-${++nextId}`;
+  return crypto.randomUUID();
 }
 function useMultiUpload(options) {
   const [state, setState] = useState(INITIAL_STATE2);
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
+  const contextApi = useContext(S3Context);
+  const optsRef = useLiveRef(options);
+  const apiRef = useLiveRef(contextApi);
   const abortRef = useRef(null);
+  const resettingRef = useRef(false);
   const fileMapRef = useRef(/* @__PURE__ */ new Map());
+  const fileSpeedTrackersRef = useRef(/* @__PURE__ */ new Map());
+  const totalSpeedTrackerRef = useRef(createSpeedTracker());
+  const fileLastSpeedRef = useRef(/* @__PURE__ */ new Map());
+  const fileLastSpeedUpdateRef = useRef(/* @__PURE__ */ new Map());
+  const lastTotalSpeedRef = useRef(void 0);
+  const lastTotalSpeedUpdateRef = useRef(0);
   const upload = useCallback(
     async (files, resolveKey) => {
-      const opts = optionsRef.current;
+      const opts = optsRef.current;
+      const api = opts.api ?? apiRef.current;
+      if (!api)
+        throw new Error(
+          "[better-s3] No S3Api client found. Pass `api` to useMultiUpload or wrap with <S3Provider>."
+        );
       const items = [];
       const fileStates = [];
       const fileMap = /* @__PURE__ */ new Map();
@@ -578,28 +913,49 @@ function useMultiUpload(options) {
         error: null
       });
       opts.onUploadStart?.(files);
+      fileSpeedTrackersRef.current.clear();
+      for (const item of items) {
+        fileSpeedTrackersRef.current.set(item.id, createSpeedTracker());
+      }
+      totalSpeedTrackerRef.current.reset();
+      fileLastSpeedRef.current.clear();
+      fileLastSpeedUpdateRef.current.clear();
+      lastTotalSpeedRef.current = void 0;
+      lastTotalSpeedUpdateRef.current = 0;
       const controller = new AbortController();
       abortRef.current = controller;
       try {
         const results = await uploadFiles(
-          opts.api,
+          api,
           items,
           {
             multipart: opts.multipart,
             multipartThreshold: opts.multipartThreshold,
             concurrentParts: opts.concurrentParts,
-            concurrentFiles: opts.concurrentFiles
+            concurrentFiles: opts.concurrentFiles,
+            partSize: opts.partSize,
+            retry: opts.retry,
+            uploadStore: opts.uploadStore
           },
           {
             onFileProgress: (id, progress) => {
+              const tracker = fileSpeedTrackersRef.current.get(id);
+              const rawSpeed = tracker ? tracker.update(progress.loaded) : 0;
+              const now = Date.now();
+              if (rawSpeed > 0 && now - (fileLastSpeedUpdateRef.current.get(id) ?? 0) >= 500) {
+                fileLastSpeedRef.current.set(id, rawSpeed);
+                fileLastSpeedUpdateRef.current.set(id, now);
+              }
+              const speed = fileLastSpeedRef.current.get(id);
+              const p = speed ? { ...progress, speed } : progress;
               setState((s) => ({
                 ...s,
                 files: s.files.map(
-                  (f) => f.id === id ? { ...f, status: "uploading", progress } : f
+                  (f) => f.id === id ? { ...f, status: "uploading", progress: p } : f
                 )
               }));
               const file = fileMap.get(id);
-              if (file) opts.onFileProgress?.(file, progress);
+              if (file) opts.onFileProgress?.(file, p);
             },
             onFileSuccess: (id, result) => {
               setState((s) => ({
@@ -630,8 +986,18 @@ function useMultiUpload(options) {
               if (file) opts.onFileError?.(file, error);
             },
             onTotalProgress: (progress) => {
-              setState((s) => ({ ...s, totalProgress: progress }));
-              opts.onProgress?.(progress);
+              const rawSpeed = totalSpeedTrackerRef.current.update(
+                progress.loaded
+              );
+              const now = Date.now();
+              if (rawSpeed > 0 && now - lastTotalSpeedUpdateRef.current >= 1e3) {
+                lastTotalSpeedRef.current = rawSpeed;
+                lastTotalSpeedUpdateRef.current = now;
+              }
+              const speed = lastTotalSpeedRef.current;
+              const p = speed ? { ...progress, speed } : progress;
+              setState((s) => ({ ...s, totalProgress: p }));
+              opts.onProgress?.(p);
             }
           },
           controller.signal,
@@ -658,7 +1024,8 @@ function useMultiUpload(options) {
         }
       } catch (err) {
         if (err.name === "AbortError") {
-          opts.onCancel?.();
+          if (!resettingRef.current) opts.onCancel?.();
+          resettingRef.current = false;
           setState(INITIAL_STATE2);
           return;
         }
@@ -676,90 +1043,43 @@ function useMultiUpload(options) {
     setState(INITIAL_STATE2);
   }, []);
   const reset = useCallback(() => {
+    resettingRef.current = true;
     abortRef.current?.abort();
     setState(INITIAL_STATE2);
   }, []);
   return { ...state, upload, cancel, reset };
 }
-var INITIAL_PROGRESS3 = { loaded: 0, total: 0, percent: 0 };
 function useUploadControls(options) {
-  const isMulti = (options.maxFiles ?? 1) > 1;
-  const singleOpts = {
-    api: options.api,
-    accept: options.accept,
-    maxFileSize: options.maxFileSize,
-    multipart: options.multipart,
-    multipartThreshold: options.multipartThreshold,
-    concurrentParts: options.concurrentParts,
-    beforeUpload: options.beforeUpload,
-    onUploadStart: options.onUploadStart,
-    onProgress: options.onProgress,
-    onSuccess: options.onSuccess,
-    onError: options.onError,
-    onCancel: options.onCancel
-  };
-  const multiOpts = {
-    api: options.api,
-    accept: options.accept,
-    maxFileSize: options.maxFileSize,
-    maxFiles: options.maxFiles,
-    multipart: options.multipart,
-    multipartThreshold: options.multipartThreshold,
-    concurrentParts: options.concurrentParts,
-    concurrentFiles: options.concurrentFiles,
-    uploadOptions: options.uploadOptions,
-    getUploadOptions: options.getUploadOptions,
-    beforeUpload: options.beforeUpload,
-    onUploadStart: options.onUploadStart,
-    onProgress: options.onProgress,
-    onSuccess: options.onSuccess,
-    onError: options.onError,
-    onCancel: options.onCancel,
-    onFileProgress: options.onFileProgress,
-    onFileSuccess: options.onFileSuccess,
-    onFileError: options.onFileError
-  };
-  const single = useUpload(singleOpts);
-  const multi = useMultiUpload(multiOpts);
+  const single = useUpload(options);
   const inputRef = useRef(null);
   const [fileInfo, setFileInfo] = useState(null);
   const resolveKey = (file) => typeof options.objectKey === "function" ? options.objectKey(file) : options.objectKey;
   const handleFiles = async (files) => {
-    if (isMulti) {
-      if (!files?.length) return;
-      await multi.upload(Array.from(files), resolveKey);
-    } else {
-      const file = files?.[0];
-      if (!file) return;
-      setFileInfo({ name: file.name, size: file.size });
-      await single.upload(file, resolveKey(file), {
-        ...options.uploadOptions,
-        ...options.getUploadOptions?.(file)
-      });
-    }
+    const file = files?.[0];
+    if (!file) return;
+    setFileInfo({ name: file.name, size: file.size });
+    await single.upload(file, resolveKey(file), {
+      ...options.uploadOptions,
+      ...options.getUploadOptions?.(file)
+    });
   };
-  const openFilePicker = () => inputRef.current?.click();
-  const isUploading = isMulti ? multi.phase === "uploading" : single.phase === "uploading";
   return {
-    mode: isMulti ? "multi" : "single",
-    phase: isMulti ? multi.phase : single.phase,
-    fileInfo: isMulti ? null : fileInfo,
-    progress: isMulti ? INITIAL_PROGRESS3 : single.progress,
-    files: isMulti ? multi.files : [],
-    totalProgress: isMulti ? multi.totalProgress : INITIAL_PROGRESS3,
-    error: isMulti ? multi.error : single.error,
-    isUploading,
+    phase: single.phase,
+    fileInfo,
+    progress: single.progress,
+    error: single.error,
+    isUploading: single.phase === "uploading",
     handleFiles,
-    openFilePicker,
-    cancel: isMulti ? multi.cancel : single.cancel,
-    reset: isMulti ? multi.reset : () => {
+    openFilePicker: () => inputRef.current?.click(),
+    cancel: single.cancel,
+    detach: single.detach,
+    reset: () => {
       single.reset();
       setFileInfo(null);
     },
     inputProps: {
       ref: inputRef,
       type: "file",
-      ...isMulti && { multiple: true },
       accept: options.accept?.join(","),
       hidden: true,
       onChange: (e) => {
@@ -775,7 +1095,49 @@ function useUploadControls(options) {
       onDrop: (e) => {
         e.preventDefault();
         e.stopPropagation();
-        if (!isUploading) handleFiles(e.dataTransfer.files);
+        if (single.phase !== "uploading") handleFiles(e.dataTransfer.files);
+      }
+    }
+  };
+}
+function useMultiUploadControls(options) {
+  const multi = useMultiUpload(options);
+  const inputRef = useRef(null);
+  const resolveKey = (file) => typeof options.objectKey === "function" ? options.objectKey(file) : options.objectKey;
+  const handleFiles = async (files) => {
+    if (!files?.length) return;
+    await multi.upload(Array.from(files), resolveKey);
+  };
+  return {
+    phase: multi.phase,
+    files: multi.files,
+    totalProgress: multi.totalProgress,
+    error: multi.error,
+    isUploading: multi.phase === "uploading",
+    handleFiles,
+    openFilePicker: () => inputRef.current?.click(),
+    cancel: multi.cancel,
+    reset: multi.reset,
+    inputProps: {
+      ref: inputRef,
+      type: "file",
+      multiple: true,
+      accept: options.accept?.join(","),
+      hidden: true,
+      onChange: (e) => {
+        handleFiles(e.target.files);
+        e.target.value = "";
+      }
+    },
+    dropHandlers: {
+      onDragOver: (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+      },
+      onDrop: (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        if (multi.phase !== "uploading") handleFiles(e.dataTransfer.files);
       }
     }
   };
@@ -788,13 +1150,19 @@ var INITIAL_STATE3 = {
 };
 function useDownload(options) {
   const [state, setState] = useState(INITIAL_STATE3);
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
+  const contextApi = useContext(S3Context);
+  const optsRef = useLiveRef(options);
+  const apiRef = useLiveRef(contextApi);
   const presign = useCallback(async (key, downloadName) => {
-    const opts = optionsRef.current;
+    const opts = optsRef.current;
+    const api = opts.api ?? apiRef.current;
+    if (!api)
+      throw new Error(
+        "[better-s3] No S3Api client found. Pass `api` to useDownload or wrap with <S3Provider>."
+      );
     setState({ phase: "presigning", error: null, url: null, expiresIn: null });
     try {
-      const result = await opts.api.download(key, {
+      const result = await api.download(key, {
         fileName: downloadName,
         bucket: opts.bucket
       });
@@ -814,7 +1182,7 @@ function useDownload(options) {
   }, []);
   const download = useCallback(
     async (key, downloadName) => {
-      const opts = optionsRef.current;
+      const opts = optsRef.current;
       if (opts.beforeDownload) {
         const allowed = await opts.beforeDownload(key);
         if (!allowed) {
@@ -835,31 +1203,35 @@ function useDownload(options) {
     },
     [presign]
   );
-  const reset = useCallback(() => {
-    setState(INITIAL_STATE3);
-  }, []);
+  const reset = useCallback(() => setState(INITIAL_STATE3), []);
   return { ...state, download, presign, reset };
 }
-var INITIAL_PROGRESS4 = {
-  loaded: 0,
-  total: 0,
-  percent: 0
-};
+var INITIAL_PROGRESS3 = { loaded: 0, total: 0, percent: 0 };
 var INITIAL_STATE4 = {
   phase: "idle",
-  progress: INITIAL_PROGRESS4,
+  progress: INITIAL_PROGRESS3,
   error: null,
   fileName: null,
   fileSize: null
 };
 function useFetchDownload(options) {
   const [state, setState] = useState(INITIAL_STATE4);
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
+  const contextApi = useContext(S3Context);
+  const optsRef = useLiveRef(options);
+  const apiRef = useLiveRef(contextApi);
   const abortRef = useRef(null);
+  const resettingRef = useRef(false);
+  const speedTrackerRef = useRef(createSpeedTracker());
+  const lastSpeedRef = useRef(void 0);
+  const lastSpeedUpdateRef = useRef(0);
   const download = useCallback(async (key, downloadName) => {
     const fallback = key.split("/").pop() ?? key;
-    const opts = optionsRef.current;
+    const opts = optsRef.current;
+    const api = opts.api ?? apiRef.current;
+    if (!api)
+      throw new Error(
+        "[better-s3] No S3Api client found. Pass `api` to useFetchDownload or wrap with <S3Provider>."
+      );
     if (opts.beforeDownload) {
       const allowed = await opts.beforeDownload(key);
       if (!allowed) {
@@ -874,18 +1246,21 @@ function useFetchDownload(options) {
     }
     setState({
       phase: "presigning",
-      progress: INITIAL_PROGRESS4,
+      progress: INITIAL_PROGRESS3,
       error: null,
       fileName: downloadName ?? null,
       fileSize: null
     });
     try {
-      const { url } = await opts.api.download(key, {
+      const { url } = await api.download(key, {
         fileName: downloadName,
         bucket: opts.bucket
       });
       setState((s) => ({ ...s, phase: "downloading" }));
       opts.onDownloadStart?.(key);
+      speedTrackerRef.current.reset();
+      lastSpeedRef.current = void 0;
+      lastSpeedUpdateRef.current = 0;
       const controller = new AbortController();
       abortRef.current = controller;
       const res = await fetch(url, { signal: controller.signal });
@@ -914,10 +1289,18 @@ function useFetchDownload(options) {
         chunks.push(value);
         loaded += value.byteLength;
         const percent = contentLength > 0 ? Math.round(loaded / contentLength * 100) : 0;
+        const rawSpeed = speedTrackerRef.current.update(loaded);
+        const now = Date.now();
+        if (rawSpeed > 0 && now - lastSpeedUpdateRef.current >= 500) {
+          lastSpeedRef.current = rawSpeed;
+          lastSpeedUpdateRef.current = now;
+        }
+        const speed = lastSpeedRef.current;
         const progress = {
           loaded,
           total: contentLength,
-          percent
+          percent,
+          ...speed && { speed }
         };
         setState((s) => ({ ...s, progress }));
         opts.onProgress?.(key, progress);
@@ -938,7 +1321,8 @@ function useFetchDownload(options) {
       await opts.onSuccess?.(key, name ?? fallback);
     } catch (err) {
       if (err.name === "AbortError") {
-        opts.onCancel?.(key);
+        if (!resettingRef.current) opts.onCancel?.(key);
+        resettingRef.current = false;
         setState(INITIAL_STATE4);
         return;
       }
@@ -954,6 +1338,7 @@ function useFetchDownload(options) {
     setState(INITIAL_STATE4);
   }, []);
   const reset = useCallback(() => {
+    resettingRef.current = true;
     abortRef.current?.abort();
     setState(INITIAL_STATE4);
   }, []);
@@ -961,56 +1346,66 @@ function useFetchDownload(options) {
 }
 var INITIAL_STATE5 = {
   phase: "idle",
-  error: null
+  error: null,
+  pendingKey: null
 };
 function useDelete(options) {
   const [state, setState] = useState(INITIAL_STATE5);
-  const [pendingKey, setPendingKey] = useState(null);
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
+  const contextApi = useContext(S3Context);
+  const optsRef = useLiveRef(options);
+  const apiRef = useLiveRef(contextApi);
+  const pendingKeyRef = useRef(null);
   const requestDelete = useCallback((key) => {
-    setPendingKey(key);
-    setState({ phase: "confirming", error: null });
+    pendingKeyRef.current = key;
+    setState({ phase: "confirming", error: null, pendingKey: key });
   }, []);
   const confirmDelete = useCallback(async () => {
-    if (!pendingKey) return;
-    const opts = optionsRef.current;
+    const key = pendingKeyRef.current;
+    if (!key) return;
+    const opts = optsRef.current;
+    const api = opts.api ?? apiRef.current;
+    if (!api)
+      throw new Error(
+        "[better-s3] No S3Api client found. Pass `api` to useDelete or wrap with <S3Provider>."
+      );
     if (opts.beforeDelete) {
-      const allowed = await opts.beforeDelete(pendingKey);
+      const allowed = await opts.beforeDelete(key);
       if (!allowed) {
         setState({
           phase: "error",
-          error: "Delete blocked by beforeDelete hook"
+          error: "Delete blocked by beforeDelete hook",
+          pendingKey: null
         });
-        opts.onError?.(pendingKey, new Error("blocked"), "confirming");
-        setPendingKey(null);
+        opts.onError?.(key, new Error("blocked"), "confirming");
+        pendingKeyRef.current = null;
         return;
       }
     }
-    setState({ phase: "deleting", error: null });
-    opts.onDeleteStart?.(pendingKey);
+    setState((s) => ({ ...s, phase: "deleting", error: null }));
+    opts.onDeleteStart?.(key);
     try {
-      await opts.api.delete(pendingKey, { bucket: opts.bucket });
-      setState({ phase: "success", error: null });
-      await opts.onSuccess?.(pendingKey);
-      setPendingKey(null);
+      await api.delete(key, { bucket: opts.bucket });
+      pendingKeyRef.current = null;
+      setState({ phase: "success", error: null, pendingKey: null });
+      await opts.onSuccess?.(key);
     } catch (err) {
       const message = err instanceof Error ? err.message : "Delete failed";
-      setState({ phase: "error", error: message });
-      opts.onError?.(pendingKey, err, "deleting");
+      setState((s) => ({ ...s, phase: "error", error: message }));
+      opts.onError?.(key, err, "deleting");
     }
-  }, [pendingKey]);
+  }, []);
   const cancelDelete = useCallback(() => {
-    setPendingKey(null);
+    pendingKeyRef.current = null;
     setState(INITIAL_STATE5);
   }, []);
   const reset = useCallback(() => {
-    setPendingKey(null);
+    pendingKeyRef.current = null;
     setState(INITIAL_STATE5);
   }, []);
   return {
-    ...state,
-    pendingKey,
+    phase: state.phase,
+    error: state.error,
+    pendingKey: state.pendingKey,
     requestDelete,
     confirmDelete,
     cancelDelete,
@@ -1018,6 +1413,6 @@ function useDelete(options) {
   };
 }
 
-export { formatFileSize, uploadFile, uploadFiles, useDelete, useDownload, useFetchDownload, useMultiUpload, useUpload, useUploadControls };
+export { S3Context, S3Provider, S3UploadError, buildObjectKey, createLocalStorageStore, createMemoryStore, createS3Api as createPresignApi, createS3Api, createS3Client, createSpeedTracker, formatEta, formatFileSize, formatSpeed, formatUploadProgress, getFileExtension, parseContentDispositionFilename, truncateFilename, uploadFile, uploadFiles, useDelete, useDownload, useFetchDownload, useMultiUpload, useMultiUploadControls, useS3Client, useUpload, useUploadControls, validateFile };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map