@better-upload/client 0.0.0

package/README.md

@@ -0,0 +1,15 @@
+# Better Upload
+
+Simple and easy file uploads for React. Upload directly to any S3-compatible service with minimal setup.
+
+Documentation is available [here](https://better-upload.com).
+
+## Getting Started
+
+You can have file uploads in your React app in a few minutes with Better Upload. To get started, follow the [quickstart guide](https://better-upload.com/docs/quickstart).
+
+## License
+
+Better Upload is licensed under the MIT License. You are free to do whatever you want with it.
+
+Feel free to contribute to the project.

package/dist/error-DFL8oJkp.js

@@ -0,0 +1,12 @@
+//#region src/types/error.ts
+var ClientUploadErrorClass = class extends Error {
+	type;
+	constructor({ type, message }) {
+		super(message);
+		this.type = type;
+		this.message = message;
+	}
+};
+
+//#endregion
+export { ClientUploadErrorClass as t };

package/dist/helpers/index.d.ts

@@ -0,0 +1,27 @@
+//#region src/helpers/format-bytes.d.ts
+/**
+ * Convert bytes to a human-readable format.
+ *
+ * @example
+ * ```ts
+ * formatBytes(1000) // "1 kB"
+ * formatBytes(1000, { decimalPlaces: 2 }) // "1.00 kB"
+ * formatBytes(1024, { si: false }) // "1 KiB"
+ * ```
+ */
+declare function formatBytes(bytes: number, options?: {
+  /**
+   * Use metric units, aka powers of 1000.
+   *
+   * @default true
+   */
+  si?: boolean;
+  /**
+   * Number of decimal places to show.
+   *
+   * @default 0
+   */
+  decimalPlaces?: number;
+}): string;
+//#endregion
+export { formatBytes };

package/dist/helpers/index.js

@@ -0,0 +1,37 @@
+//#region src/helpers/format-bytes.ts
+/**
+* Convert bytes to a human-readable format.
+*
+* @example
+* ```ts
+* formatBytes(1000) // "1 kB"
+* formatBytes(1000, { decimalPlaces: 2 }) // "1.00 kB"
+* formatBytes(1024, { si: false }) // "1 KiB"
+* ```
+*/
+function formatBytes(bytes, options) {
+	const { si = true, decimalPlaces = 0 } = options || {};
+	const threshold = si ? 1e3 : 1024;
+	const units = si ? [
+		"B",
+		"kB",
+		"MB",
+		"GB",
+		"TB",
+		"PB"
+	] : [
+		"B",
+		"KiB",
+		"MiB",
+		"GiB",
+		"TiB",
+		"PiB"
+	];
+	if (bytes < threshold) return `${bytes} ${units[0]}`;
+	const exponent = Math.floor(Math.log(bytes) / Math.log(threshold));
+	const unit = units[exponent];
+	return `${(bytes / Math.pow(threshold, exponent)).toFixed(decimalPlaces)} ${unit}`;
+}
+
+//#endregion
+export { formatBytes };

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import { a as UploadHookProps, c as FileUploadInfo, l as UploadHookControl, o as UploadHookReturn, r as ServerMetadata, s as ClientUploadError, t as DirectUploadResult, u as UploadStatus } from "./internal-gLVx5GpR.js";
+
+//#region src/hooks/use-upload-file.d.ts
+declare function useUploadFile(props: UploadHookProps<false>): UploadHookReturn<false>;
+//#endregion
+//#region src/hooks/use-upload-files.d.ts
+declare function useUploadFiles({
+  api,
+  route,
+  uploadBatchSize,
+  multipartBatchSize,
+  headers,
+  credentials,
+  signal,
+  retry,
+  retryDelay,
+  onError,
+  onBeforeUpload,
+  onUploadBegin,
+  onUploadComplete,
+  onUploadFail,
+  onUploadProgress,
+  onUploadSettle
+}: UploadHookProps<true>): UploadHookReturn<true>;
+//#endregion
+//#region src/utils/upload.d.ts
+/**
+ * Upload multiple files to S3.
+ *
+ * This will not throw if one of the uploads fails, but will return the files that failed to upload.
+ */
+declare function uploadFiles(params: {
+  api?: string;
+  route: string;
+  files: File[] | FileList;
+  metadata?: ServerMetadata;
+  multipartBatchSize?: number;
+  uploadBatchSize?: number;
+  signal?: AbortSignal;
+  headers?: HeadersInit;
+  credentials?: RequestCredentials;
+  retry?: number;
+  retryDelay?: number;
+  onUploadBegin?: (data: {
+    files: FileUploadInfo<'pending'>[];
+    metadata: ServerMetadata;
+  }) => void;
+  onFileStateChange?: (data: {
+    file: FileUploadInfo<UploadStatus>;
+  }) => void;
+}): Promise<DirectUploadResult<true>>;
+/**
+ * Upload a single file to S3.
+ *
+ * This will throw if the upload fails.
+ */
+declare function uploadFile(params: {
+  api?: string;
+  route: string;
+  file: File;
+  metadata?: ServerMetadata;
+  multipartBatchSize?: number;
+  signal?: AbortSignal;
+  headers?: HeadersInit;
+  credentials?: RequestCredentials;
+  retry?: number;
+  retryDelay?: number;
+  onUploadBegin?: (data: {
+    file: FileUploadInfo<'pending'>;
+    metadata: ServerMetadata;
+  }) => void;
+  onFileStateChange?: (data: {
+    file: FileUploadInfo<UploadStatus>;
+  }) => void;
+}): Promise<DirectUploadResult<false>>;
+//#endregion
+export { ClientUploadError, FileUploadInfo, UploadHookControl, UploadStatus, uploadFile, uploadFiles, useUploadFile, useUploadFiles };

package/dist/index.js

@@ -0,0 +1,589 @@
+import { t as ClientUploadErrorClass } from "./error-DFL8oJkp.js";
+import { useCallback, useMemo, useState } from "react";
+
+//#region src/utils/internal/retry.ts
+async function withRetries(fn, { retry = 0, delay = 0, signal, abortHandler } = {}) {
+	const maxTries = retry + 1;
+	for (let attempt = 0; attempt < maxTries; attempt++) {
+		if (attempt > 0) {
+			if (signal?.aborted) {
+				abortHandler?.();
+				throw new Error("Retries aborted.");
+			}
+			if (delay) {
+				await new Promise((resolve) => {
+					const timeout = setTimeout(() => {
+						signal?.removeEventListener("abort", abort);
+						resolve(void 0);
+					}, delay);
+					const abort = () => {
+						clearTimeout(timeout);
+						signal?.removeEventListener("abort", abort);
+						resolve(void 0);
+					};
+					signal?.addEventListener("abort", abort);
+				});
+				if (signal?.aborted) {
+					abortHandler?.();
+					throw new Error("Retries aborted.");
+				}
+			}
+		}
+		try {
+			return await fn();
+		} catch (e) {
+			if (attempt === maxTries - 1) throw e;
+		}
+	}
+	throw new Error("Unreachable Better Upload code.");
+}
+
+//#endregion
+//#region src/utils/internal/s3-upload.ts
+async function uploadFileToS3(params) {
+	const xhr = new XMLHttpRequest();
+	await withRetries(() => new Promise((resolve, reject) => {
+		const abortHandler = createAbortHandler(xhr, reject);
+		if (params.signal?.aborted) abortHandler();
+		params.signal?.addEventListener("abort", abortHandler);
+		xhr.onloadend = () => {
+			params.signal?.removeEventListener("abort", abortHandler);
+			if (xhr.readyState === 4 && xhr.status === 200) {
+				params.onProgress?.(1);
+				resolve();
+			} else reject(/* @__PURE__ */ new Error("Failed to upload file to S3."));
+		};
+		xhr.upload.onprogress = (event) => {
+			if (event.lengthComputable) params.onProgress?.(Math.min(event.loaded / event.total, .99));
+		};
+		xhr.open("PUT", params.signedUrl, true);
+		xhr.setRequestHeader("Content-Type", params.file.type);
+		if (params.objectCacheControl) xhr.setRequestHeader("Cache-Control", params.objectCacheControl);
+		Object.entries(params.objectMetadata).forEach(([key, value]) => {
+			xhr.setRequestHeader(`x-amz-meta-${key}`, value);
+		});
+		xhr.send(params.file);
+	}), {
+		retry: params.retry,
+		delay: params.retryDelay,
+		signal: params.signal,
+		abortHandler: () => {
+			xhr.abort();
+			throw new Error("Upload aborted.");
+		}
+	});
+}
+async function uploadMultipartFileToS3(params) {
+	const uploadedParts = [];
+	const progresses = {};
+	const uploadPromises = params.parts.map((part) => async () => {
+		const xhr = new XMLHttpRequest();
+		const start = (part.partNumber - 1) * params.partSize;
+		const end = Math.min(start + part.size, params.file.size);
+		const blob = params.file.slice(start, end);
+		await withRetries(() => new Promise((resolve, reject) => {
+			const abortHandler = createAbortHandler(xhr, reject);
+			if (params.signal?.aborted) abortHandler();
+			params.signal?.addEventListener("abort", abortHandler);
+			xhr.onloadend = () => {
+				params.signal?.removeEventListener("abort", abortHandler);
+				if (xhr.readyState === 4 && xhr.status === 200) {
+					uploadedParts.push({
+						etag: xhr.getResponseHeader("ETag").replace(/"/g, ""),
+						number: part.partNumber
+					});
+					resolve();
+				} else reject(/* @__PURE__ */ new Error("Failed to upload part to S3."));
+			};
+			xhr.upload.onprogress = (event) => {
+				if (event.lengthComputable) {
+					progresses[part.partNumber] = event.loaded / event.total;
+					const totalProgress = Object.values(progresses).reduce((acc, curr) => acc + curr, 0) / params.parts.length;
+					params.onProgress?.(Math.min(totalProgress, .99));
+				}
+			};
+			xhr.open("PUT", part.signedUrl, true);
+			xhr.send(blob);
+		}), {
+			retry: params.retry,
+			delay: params.retryDelay,
+			signal: params.signal,
+			abortHandler: () => {
+				xhr.abort();
+				throw new Error("Upload aborted.");
+			}
+		});
+	});
+	const batchSize = params.partsBatchSize || uploadPromises.length;
+	for (let i = 0; i < uploadPromises.length; i += batchSize) await Promise.all(uploadPromises.slice(i, i + batchSize).map((fn) => fn()));
+	const completeXmlBody = `
+<CompleteMultipartUpload>
+  ${uploadedParts.sort((a, b) => a.number - b.number).map((part) => `<Part>
+    <ETag>${part.etag}</ETag>
+    <PartNumber>${part.number}</PartNumber>
+  </Part>`).join("")}
+</CompleteMultipartUpload>
+  `;
+	if (!(await withRetries(() => fetch(params.completeSignedUrl, {
+		method: "POST",
+		body: completeXmlBody,
+		headers: { "Content-Type": "application/xml" },
+		signal: params.signal
+	}), {
+		retry: params.retry,
+		delay: params.retryDelay,
+		signal: params.signal
+	})).ok) throw new Error("Failed to complete multipart upload.");
+	params.onProgress?.(1);
+}
+function createAbortHandler(xhr, reject) {
+	return () => {
+		xhr.abort();
+		reject(/* @__PURE__ */ new Error("Upload aborted."));
+	};
+}
+
+//#endregion
+//#region src/utils/upload.ts
+/**
+* Upload multiple files to S3.
+*
+* This will not throw if one of the uploads fails, but will return the files that failed to upload.
+*/
+async function uploadFiles(params) {
+	const files = Array.from(params.files);
+	if (files.length === 0) throw new ClientUploadErrorClass({
+		type: "no_files",
+		message: "No files to upload."
+	});
+	try {
+		const headers = new Headers(params.headers);
+		headers.set("Content-Type", "application/json");
+		const signedUrlRes = await withRetries(() => fetch(params.api || "/api/upload", {
+			method: "POST",
+			body: JSON.stringify({
+				route: params.route,
+				metadata: params.metadata,
+				files: files.map((file) => ({
+					name: file.name,
+					size: file.size,
+					type: file.type
+				}))
+			}),
+			headers,
+			credentials: params.credentials,
+			signal: params.signal
+		}), {
+			retry: params.retry,
+			delay: params.retryDelay,
+			signal: params.signal
+		});
+		if (!signedUrlRes.ok) {
+			const { error } = await signedUrlRes.json();
+			throw new ClientUploadErrorClass({
+				type: error.type || "unknown",
+				message: error.message || "Failed to obtain pre-signed URLs."
+			});
+		}
+		const payload = await signedUrlRes.json();
+		const signedUrls = "multipart" in payload ? payload.multipart.files : payload.files;
+		const serverMetadata = payload.metadata;
+		const partSize = "multipart" in payload ? payload.multipart.partSize : 0;
+		if (!signedUrls || signedUrls.length === 0) throw new ClientUploadErrorClass({
+			type: "unknown",
+			message: "No pre-signed URLs returned from server. Check your upload router config."
+		});
+		const uploads = new Map(signedUrls.map((url) => [url.file.objectInfo.key, {
+			status: "pending",
+			progress: 0,
+			raw: files.find((file) => file.name === url.file.name && file.size === url.file.size && file.type === url.file.type),
+			...url.file
+		}]));
+		const uploadPromises = files.map((file) => async () => {
+			const url = signedUrls.find((item) => item.file.name === file.name && item.file.size === file.size && item.file.type === file.type);
+			const isMultipart = "parts" in url;
+			try {
+				uploads.set(url.file.objectInfo.key, {
+					...uploads.get(url.file.objectInfo.key),
+					status: "uploading",
+					progress: 0
+				});
+				params.onFileStateChange?.({ file: uploads.get(url.file.objectInfo.key) });
+				if (isMultipart) await uploadMultipartFileToS3({
+					file,
+					parts: url.parts,
+					partSize,
+					uploadId: url.uploadId,
+					completeSignedUrl: url.completeSignedUrl,
+					partsBatchSize: params.multipartBatchSize,
+					signal: params.signal,
+					retry: params.retry,
+					retryDelay: params.retryDelay,
+					onProgress: (progress) => {
+						if (uploads.get(url.file.objectInfo.key).status === "failed") return;
+						uploads.set(url.file.objectInfo.key, {
+							...uploads.get(url.file.objectInfo.key),
+							status: progress === 1 ? "complete" : "uploading",
+							progress
+						});
+						params.onFileStateChange?.({ file: uploads.get(url.file.objectInfo.key) });
+					}
+				});
+				else await uploadFileToS3({
+					file,
+					signedUrl: url.signedUrl,
+					objectMetadata: url.file.objectInfo.metadata,
+					objectCacheControl: url.file.objectInfo.cacheControl,
+					signal: params.signal,
+					retry: params.retry,
+					retryDelay: params.retryDelay,
+					onProgress: (progress) => {
+						uploads.set(url.file.objectInfo.key, {
+							...uploads.get(url.file.objectInfo.key),
+							status: progress === 1 ? "complete" : "uploading",
+							progress
+						});
+						params.onFileStateChange?.({ file: uploads.get(url.file.objectInfo.key) });
+					}
+				});
+			} catch (error) {
+				if (isMultipart) await fetch(url.abortSignedUrl, { method: "DELETE" }).catch(() => {});
+				uploads.set(url.file.objectInfo.key, {
+					...uploads.get(url.file.objectInfo.key),
+					status: "failed",
+					error: {
+						type: params.signal?.aborted ? "aborted" : "s3_upload",
+						message: params.signal?.aborted ? "Upload aborted." : "Failed to upload file to S3."
+					}
+				});
+				params.onFileStateChange?.({ file: uploads.get(url.file.objectInfo.key) });
+			}
+		});
+		params.onUploadBegin?.({
+			files: Array.from(uploads.values()),
+			metadata: serverMetadata
+		});
+		uploads.forEach((file) => {
+			params.onFileStateChange?.({ file });
+		});
+		const batchSize = params.uploadBatchSize || files.length;
+		for (let i = 0; i < uploadPromises.length; i += batchSize) await Promise.all(uploadPromises.slice(i, i + batchSize).map((fn) => fn()));
+		return {
+			files: Array.from(uploads.values()).filter((file) => file.status === "complete"),
+			failedFiles: Array.from(uploads.values()).filter((file) => file.status === "failed"),
+			metadata: serverMetadata
+		};
+	} catch (error) {
+		if (params.signal?.aborted) throw new ClientUploadErrorClass({
+			type: "aborted",
+			message: "Upload aborted."
+		});
+		if (error instanceof ClientUploadErrorClass) throw error;
+		else if (error instanceof Error) throw new ClientUploadErrorClass({
+			type: "unknown",
+			message: error.message
+		});
+		else throw new ClientUploadErrorClass({
+			type: "unknown",
+			message: "Failed to upload files."
+		});
+	}
+}
+/**
+* Upload a single file to S3.
+*
+* This will throw if the upload fails.
+*/
+async function uploadFile(params) {
+	const { files, metadata } = await uploadFiles({
+		api: params.api,
+		route: params.route,
+		files: [params.file],
+		metadata: params.metadata,
+		multipartBatchSize: params.multipartBatchSize,
+		signal: params.signal,
+		headers: params.headers,
+		credentials: params.credentials,
+		retry: params.retry,
+		retryDelay: params.retryDelay,
+		onUploadBegin: (data) => {
+			params.onUploadBegin?.({
+				file: data.files[0],
+				metadata: data.metadata
+			});
+		},
+		onFileStateChange: params.onFileStateChange
+	});
+	const file = files[0];
+	if (!file) throw new ClientUploadErrorClass({
+		type: "unknown",
+		message: "Failed to upload file."
+	});
+	return {
+		file,
+		metadata
+	};
+}
+
+//#endregion
+//#region src/hooks/use-upload-files.ts
+function useUploadFiles({ api, route, uploadBatchSize, multipartBatchSize, headers, credentials, signal, retry, retryDelay, onError, onBeforeUpload, onUploadBegin, onUploadComplete, onUploadFail, onUploadProgress, onUploadSettle }) {
+	const [uploads, setUploads] = useState(() => /* @__PURE__ */ new Map());
+	const [serverMetadata, setServerMetadata] = useState({});
+	const [isPending, setIsPending] = useState(false);
+	const [error, setError] = useState(null);
+	const uploadsArray = useMemo(() => Array.from(uploads.values()), [uploads]);
+	const uploadedFiles = useMemo(() => uploadsArray.filter((file) => file.status === "complete"), [uploadsArray]);
+	const failedFiles = useMemo(() => uploadsArray.filter((file) => file.status === "failed"), [uploadsArray]);
+	const allSucceeded = useMemo(() => uploadsArray.length > 0 && uploadsArray.every((file) => file.status === "complete"), [uploadsArray]);
+	const hasFailedFiles = useMemo(() => uploadsArray.length > 0 && uploadsArray.some((file) => file.status === "failed"), [uploadsArray]);
+	const isSettled = useMemo(() => uploadsArray.length > 0 && uploadsArray.every((file) => file.status === "complete" || file.status === "failed"), [uploadsArray]);
+	const averageProgress = useMemo(() => uploadsArray.length === 0 ? 0 : uploadsArray.reduce((acc, file) => acc + file.progress, 0) / uploadsArray.length, [uploadsArray]);
+	const uploadAsync = useCallback(async (files, { metadata } = {}) => {
+		reset();
+		setIsPending(true);
+		const fileArray = Array.from(files);
+		try {
+			if (fileArray.length === 0) throw new ClientUploadErrorClass({
+				type: "no_files",
+				message: "No files to upload."
+			});
+			let filesToUpload = fileArray;
+			if (onBeforeUpload) {
+				const callbackResult = await onBeforeUpload({ files: fileArray });
+				if (Array.isArray(callbackResult)) {
+					if (callbackResult.length === 0) throw new ClientUploadErrorClass({
+						type: "no_files",
+						message: "No files to upload."
+					});
+					filesToUpload = callbackResult;
+				}
+			}
+			const result = await uploadFiles({
+				api,
+				route,
+				files: filesToUpload,
+				metadata,
+				uploadBatchSize,
+				multipartBatchSize,
+				headers,
+				credentials,
+				signal,
+				retry,
+				retryDelay,
+				onUploadBegin,
+				onFileStateChange: ({ file }) => {
+					setUploads((prev) => new Map(prev).set(file.objectInfo.key, file));
+					onUploadProgress?.({ file });
+				}
+			});
+			if (result.files.length > 0) await onUploadComplete?.(result);
+			if (result.failedFiles.length > 0) await onUploadFail?.({
+				succeededFiles: result.files,
+				failedFiles: result.failedFiles,
+				metadata: result.metadata
+			});
+			setIsPending(false);
+			setServerMetadata(result.metadata);
+			await onUploadSettle?.(result);
+			return result;
+		} catch (error$1) {
+			setIsPending(false);
+			if (error$1 instanceof ClientUploadErrorClass) {
+				onError?.(error$1);
+				setError(error$1);
+				await onUploadSettle?.({
+					files: [],
+					failedFiles: [],
+					metadata: {}
+				});
+				throw error$1;
+			} else if (error$1 instanceof Error) {
+				const _error = new ClientUploadErrorClass({
+					type: "unknown",
+					message: error$1.message
+				});
+				onError?.(_error);
+				setError(_error);
+				await onUploadSettle?.({
+					files: [],
+					failedFiles: [],
+					metadata: {}
+				});
+				throw _error;
+			} else {
+				const _error = new ClientUploadErrorClass({
+					type: "unknown",
+					message: "Failed to upload files."
+				});
+				onError?.(_error);
+				setError(_error);
+				await onUploadSettle?.({
+					files: [],
+					failedFiles: [],
+					metadata: {}
+				});
+				throw _error;
+			}
+		}
+	}, [
+		api,
+		route,
+		uploadBatchSize,
+		multipartBatchSize,
+		headers,
+		credentials,
+		signal,
+		onError,
+		onBeforeUpload,
+		onUploadBegin,
+		onUploadComplete,
+		onUploadFail,
+		onUploadProgress,
+		onUploadSettle
+	]);
+	const upload = useCallback(async (files, options = {}) => {
+		try {
+			return await uploadAsync(files, options);
+		} catch (error$1) {
+			return {
+				files: [],
+				failedFiles: [],
+				metadata: {}
+			};
+		}
+	}, [uploadAsync]);
+	const reset = useCallback(() => {
+		setUploads(/* @__PURE__ */ new Map());
+		setServerMetadata({});
+		setIsPending(false);
+		setError(null);
+	}, []);
+	const control = useMemo(() => ({
+		uploadAsync,
+		upload,
+		reset,
+		progresses: uploadsArray,
+		allSucceeded,
+		hasFailedFiles,
+		uploadedFiles,
+		failedFiles,
+		isSettled,
+		averageProgress,
+		isPending,
+		isError: !!error,
+		isAborted: signal?.aborted ?? false,
+		error,
+		metadata: serverMetadata
+	}), [
+		uploadAsync,
+		upload,
+		reset,
+		uploadsArray,
+		allSucceeded,
+		hasFailedFiles,
+		uploadedFiles,
+		failedFiles,
+		isSettled,
+		averageProgress,
+		isPending,
+		signal?.aborted,
+		error,
+		serverMetadata
+	]);
+	return {
+		...control,
+		control
+	};
+}
+
+//#endregion
+//#region src/hooks/use-upload-file.ts
+function useUploadFile(props) {
+	const { upload, uploadAsync, reset, averageProgress, error, isError, isPending, isSettled, isAborted, allSucceeded, metadata, uploadedFiles } = useUploadFiles({
+		api: props.api,
+		route: props.route,
+		uploadBatchSize: 1,
+		multipartBatchSize: props.multipartBatchSize,
+		headers: props.headers,
+		credentials: props.credentials,
+		signal: props.signal,
+		retry: props.retry,
+		retryDelay: props.retryDelay,
+		onError: props.onError,
+		onUploadProgress: props.onUploadProgress,
+		onBeforeUpload: props.onBeforeUpload ? async ({ files }) => {
+			const result = await props.onBeforeUpload({ file: files[0] });
+			if (result) return [result];
+		} : void 0,
+		onUploadBegin: props.onUploadBegin ? ({ files, metadata: metadata$1 }) => props.onUploadBegin({
+			file: files[0],
+			metadata: metadata$1
+		}) : void 0,
+		onUploadComplete: props.onUploadComplete ? async ({ files, metadata: metadata$1 }) => {
+			await props.onUploadComplete({
+				file: files[0],
+				metadata: metadata$1
+			});
+		} : void 0,
+		onUploadFail: props.onError ? async ({ failedFiles }) => {
+			props.onError?.({
+				type: failedFiles[0].error.type,
+				message: failedFiles[0].error.message
+			});
+		} : void 0,
+		onUploadSettle: props.onUploadSettle ? async ({ files, metadata: metadata$1 }) => {
+			await props.onUploadSettle({
+				file: files[0],
+				metadata: metadata$1
+			});
+		} : void 0
+	});
+	const uploadedFile = uploadedFiles?.[0] ?? null;
+	const control = useMemo(() => ({
+		upload: async (file, options) => {
+			const result = await upload([file], options);
+			return {
+				file: result.files[0],
+				metadata: result.metadata
+			};
+		},
+		uploadAsync: async (file, options) => {
+			const result = await uploadAsync([file], options);
+			return {
+				file: result.files[0],
+				metadata: result.metadata
+			};
+		},
+		reset,
+		progress: averageProgress,
+		error,
+		isError,
+		isPending,
+		isSettled,
+		isSuccess: allSucceeded,
+		isAborted,
+		metadata,
+		uploadedFile
+	}), [
+		upload,
+		uploadAsync,
+		reset,
+		averageProgress,
+		error,
+		isError,
+		isPending,
+		isSettled,
+		allSucceeded,
+		isAborted,
+		metadata,
+		uploadedFile
+	]);
+	return {
+		...control,
+		control
+	};
+}
+
+//#endregion
+export { uploadFile, uploadFiles, useUploadFile, useUploadFiles };

package/dist/internal-export.d.ts

@@ -0,0 +1,15 @@
+import { a as UploadHookProps, i as SignedUrlsSuccessResponse, n as ObjectMetadata, o as UploadHookReturn, r as ServerMetadata, s as ClientUploadError, t as DirectUploadResult } from "./internal-gLVx5GpR.js";
+
+//#region src/types/error.d.ts
+declare class ClientUploadErrorClass extends Error {
+  type: ClientUploadError['type'];
+  constructor({
+    type,
+    message
+  }: {
+    type: ClientUploadError['type'];
+    message: string;
+  });
+}
+//#endregion
+export { ClientUploadErrorClass, DirectUploadResult, ObjectMetadata, ServerMetadata, SignedUrlsSuccessResponse, UploadHookProps, UploadHookReturn };

package/dist/internal-export.js

@@ -0,0 +1,3 @@
+import { t as ClientUploadErrorClass } from "./error-DFL8oJkp.js";
+
+export { ClientUploadErrorClass };

package/dist/internal-gLVx5GpR.d.ts

@@ -0,0 +1,360 @@
+//#region src/types/public.d.ts
+type ClientUploadError = {
+  type: 'unknown' | 'invalid_request' | 'no_files' | 's3_upload' | 'file_too_large' | 'invalid_file_type' | 'rejected' | 'too_many_files' | 'aborted';
+  message: string;
+};
+type UploadStatus = 'pending' | 'uploading' | 'complete' | 'failed';
+type FileUploadInfo<T extends UploadStatus> = {
+  /**
+   * The status of the file being uploaded.
+   *
+   * - `pending` - The file is waiting to be uploaded. The signed URL has already been generated.
+   * - `uploading` - The file is currently being uploaded.
+   * - `complete` - The file has been uploaded successfully.
+   * - `error` - The file failed to upload.
+   */
+  status: T;
+  /**
+   * The progress of the upload, from 0 to 1.
+   *
+   * @example 0.5 // 50%
+   */
+  progress: number;
+  /**
+   * The original raw file that was uploaded.
+   */
+  raw: File;
+  /**
+   * The name of the file.
+   */
+  name: string;
+  /**
+   * The size of the file in bytes.
+   */
+  size: number;
+  /**
+   * The type of the file.
+   */
+  type: string;
+  /**
+   * Information about the S3 object.
+   */
+  objectInfo: {
+    /**
+     * The key of the S3 object.
+     */
+    key: string;
+    /**
+     * The metadata of the S3 object.
+     */
+    metadata: ObjectMetadata;
+    /**
+     * The Cache-Control header of the S3 object.
+     */
+    cacheControl?: string;
+  };
+} & (T extends 'failed' ? {
+  error: ClientUploadError;
+} : {});
+type UploadHookControl<T extends boolean> = {
+  /**
+   * Metadata sent back from the server.
+   */
+  metadata: ServerMetadata;
+  /**
+   * If a critical error occurred during the upload, and no files were able to be uploaded. For example, if your server is unreachable.
+   *
+   * Is also `true` if some input is invalid. For example, if no files were selected.
+   */
+  isError: boolean;
+  /**
+   * The error critical that occurred during the upload.
+   *
+   * @see `isError` for more information.
+   */
+  error: ClientUploadError | null;
+  /**
+   * If the upload is in progress.
+   */
+  isPending: boolean;
+  /**
+   * If the upload progress is complete. Regardless of if all files succeeded or failed to upload.
+   */
+  isSettled: boolean;
+  /**
+   * If the upload was aborted.
+   */
+  isAborted: boolean;
+  /**
+   * Reset the state of the upload.
+   */
+  reset: () => void;
+  /**
+   * Upload files to S3.
+   *
+   * Will throw if critical errors occur.
+   */
+  uploadAsync: (input: T extends true ? File[] | FileList : File, options?: {
+    metadata?: ServerMetadata;
+  }) => Promise<DirectUploadResult<T>>;
+  /**
+   * Upload files to S3.
+   *
+   * Will never throw an error.
+   */
+  upload: (input: T extends true ? File[] | FileList : File, options?: {
+    metadata?: ServerMetadata;
+  }) => Promise<DirectUploadResult<T>>;
+} & (T extends true ? {
+  /**
+   * The progress of all files during the upload process.
+   *
+   * `uploadedFiles` and `failedFiles` derive from this array, use this to get information about **all** files.
+   */
+  progresses: FileUploadInfo<UploadStatus>[];
+  /**
+   * If all files succeeded to upload.
+   */
+  allSucceeded: boolean;
+  /**
+   * If some files failed to upload.
+   */
+  hasFailedFiles: boolean;
+  /**
+   * Files that succeeded to upload.
+   */
+  uploadedFiles: FileUploadInfo<'complete'>[];
+  /**
+   * Files that failed to upload.
+   */
+  failedFiles: FileUploadInfo<'failed'>[];
+  /**
+   * The progress of **all** files during the upload. Goes from 0 to 1.
+   *
+   * If one file is 100% complete, and another is 0% complete, this will be 0.5.
+   *
+   * @example 0.5 // 50%
+   */
+  averageProgress: number;
+} : {
+  /**
+   * The progress of the file during the upload process.
+   */
+  progress: number;
+  /**
+   * The file that was successfully uploaded.
+   */
+  uploadedFile: FileUploadInfo<'complete'> | null;
+  /**
+   * If the file was successfully uploaded.
+   */
+  isSuccess: boolean;
+});
+//#endregion
+//#region src/types/internal.d.ts
+type ObjectMetadata = Record<string, string>;
+type ServerMetadata = Record<string, unknown>;
+type SignedUrlsSuccessResponse = {
+  metadata: ServerMetadata;
+} & ({
+  multipart: {
+    files: {
+      file: {
+        name: string;
+        size: number;
+        type: string;
+        objectInfo: {
+          key: string;
+          metadata: ObjectMetadata;
+          cacheControl?: string;
+        };
+      };
+      parts: {
+        signedUrl: string;
+        partNumber: number;
+        size: number;
+      }[];
+      uploadId: string;
+      completeSignedUrl: string;
+      abortSignedUrl: string;
+    }[];
+    partSize: number;
+  };
+} | {
+  files: {
+    signedUrl: string;
+    file: {
+      name: string;
+      size: number;
+      type: string;
+      objectInfo: {
+        key: string;
+        metadata: ObjectMetadata;
+        cacheControl?: string;
+      };
+    };
+  }[];
+});
+type UploadHookProps<T extends boolean> = {
+  /**
+   * The API endpoint to use for uploading files.
+   *
+   * @default '/api/upload'
+   */
+  api?: string;
+  /**
+   * The route to use to upload the files. Should match the upload route name defined in the server.
+   */
+  route: string;
+  /**
+   * The number of parts that will be uploaded in parallel when uploading a file.
+   *
+   * **Only used in multipart uploads.**
+   *
+   * @default All parts at once.
+   */
+  multipartBatchSize?: number;
+  /**
+   * Callback that is called before requesting the pre-signed URLs. Use this to modify files before uploading them, like resizing or compressing.
+   *
+   * You can also throw an error to reject the file upload.
+   */
+  onBeforeUpload?: (data: T extends true ? {
+    files: File[];
+  } : {
+    file: File;
+  }) => void | (T extends true ? File[] | Promise<void | File[]> : File | Promise<void | File>);
+  /**
+   * Event that is called before the files start being uploaded to S3. This happens after the server responds with the pre-signed URL.
+   */
+  onUploadBegin?: (data: {
+    /**
+     * Metadata sent from the server.
+     */
+    metadata: ServerMetadata;
+  } & (T extends true ? {
+    files: FileUploadInfo<'pending'>[];
+  } : {
+    file: FileUploadInfo<'pending'>;
+  })) => void;
+  /**
+   * Event that is called when a file upload progress changes.
+   */
+  onUploadProgress?: (data: {
+    file: FileUploadInfo<UploadStatus>;
+  }) => void;
+  /**
+   * Event that is called after files are successfully uploaded.
+   *
+   * This event is called even if some files fail to upload, but some succeed. This event is not called if all files fail to upload.
+   */
+  onUploadComplete?: (data: {
+    /**
+     * Metadata sent back from the server.
+     */
+    metadata: ServerMetadata;
+  } & (T extends true ? {
+    files: FileUploadInfo<'complete'>[];
+    failedFiles: FileUploadInfo<'failed'>[];
+  } : {
+    file: FileUploadInfo<'complete'>;
+  })) => void | Promise<void>;
+  /**
+   * Event that is called after the upload settles (either successfully completed or an error occurs).
+   */
+  onUploadSettle?: (data: {
+    /**
+     * Metadata sent back from the server.
+     */
+    metadata: ServerMetadata;
+  } & (T extends true ? {
+    files: FileUploadInfo<'complete'>[];
+    failedFiles: FileUploadInfo<'failed'>[];
+  } : {
+    file: FileUploadInfo<'complete'>;
+  })) => void | Promise<void>;
+  /**
+   * Abort signal to cancel the upload.
+   */
+  signal?: AbortSignal;
+  /**
+   * Headers to send to your server when requesting the pre-signed URLs.
+   */
+  headers?: HeadersInit;
+  /**
+   * Credentials mode when requesting pre-signed URLs from your server.
+   *
+   * Use `include` to send cookies if your server is on a different origin.
+   */
+  credentials?: RequestCredentials;
+  /**
+   * Number of times to retry network requests that fail.
+   *
+   * @default 0
+   */
+  retry?: number;
+  /**
+   * Delay between retries in milliseconds.
+   *
+   * @default 0
+   */
+  retryDelay?: number;
+} & (T extends true ? {
+  /**
+   * The size of the batch to upload files in parallel. Use `1` to upload files sequentially.
+   *
+   * By default, all files are uploaded in parallel.
+   */
+  uploadBatchSize?: number;
+  /**
+   * Event that is called after the entire upload if a file fails to upload.
+   *
+   * This event is called even if some files succeed to upload, but some fail. This event is not called if all files succeed.
+   */
+  onUploadFail?: (data: {
+    /**
+     * Metadata sent back from the server.
+     */
+    metadata: ServerMetadata;
+    succeededFiles: FileUploadInfo<'complete'>[];
+    failedFiles: FileUploadInfo<'failed'>[];
+  }) => void | Promise<void>;
+  /**
+   * Event that is called if a critical error occurs before the upload to S3, and no files were able to be uploaded. For example, if your server is unreachable.
+   *
+   * Is also called some input is invalid. For example, if no files were selected.
+   */
+  onError?: (error: ClientUploadError) => void;
+} : {
+  /**
+   * Event that is called if the upload fails.
+   *
+   * Also called if some input is invalid. For example, if no files were selected.
+   */
+  onError?: (error: ClientUploadError) => void;
+});
+type UploadHookReturn<T extends boolean> = UploadHookControl<T> & {
+  control: UploadHookControl<T>;
+};
+type DirectUploadResult<T extends boolean> = {
+  /**
+   * Metadata sent back from the server.
+   */
+  metadata: ServerMetadata;
+} & (T extends true ? {
+  /**
+   * Files that were successfully uploaded.
+   */
+  files: FileUploadInfo<'complete'>[];
+  /**
+   * Files that failed to upload.
+   */
+  failedFiles: FileUploadInfo<'failed'>[];
+} : {
+  /**
+   * The file that was successfully uploaded.
+   */
+  file: FileUploadInfo<'complete'>;
+});
+//#endregion
+export { UploadHookProps as a, FileUploadInfo as c, SignedUrlsSuccessResponse as i, UploadHookControl as l, ObjectMetadata as n, UploadHookReturn as o, ServerMetadata as r, ClientUploadError as s, DirectUploadResult as t, UploadStatus as u };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@better-upload/client",
+  "description": "The Better Upload client library. Simple and easy file uploads for React.",
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "tsc"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./helpers": {
+      "import": "./dist/helpers/index.js",
+      "types": "./dist/helpers/index.d.ts"
+    },
+    "./internal": {
+      "import": "./dist/internal-export.js",
+      "types": "./dist/internal-export.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": "*"
+  },
+  "devDependencies": {
+    "@repo/tsconfig": "workspace:*",
+    "tsdown": "^0.15.12",
+    "typescript": "^5.9.3",
+    "react": "^19",
+    "@types/react": "^19"
+  },
+  "keywords": [
+    "react",
+    "nextjs",
+    "tanstack",
+    "upload",
+    "files",
+    "multipart"
+  ],
+  "license": "MIT",
+  "homepage": "https://better-upload.com",
+  "bugs": {
+    "url": "https://github.com/Nic13Gamer/better-upload/issues"
+  },
+  "author": "Nicholas",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nic13Gamer/better-upload.git"
+  }
+}