Upload

​

How does upload work?

1. You pick a transport — a small object with one method, upload(file, { onProgress, signal }). createXhrUploadTransport() is the reference implementation. You can write your own for anything else (a provider SDK, a test double, a more advanced resumable protocol).
2. You pass that transport to useMediaDrop({ transport, ... }) — the exact same option regardless of which transport it is.
3. Only then do uploadFile/uploadAll/cancelUpload/ cancelAllUploads/retryUpload exist on the returned object — without transport, they are absent, and TypeScript will not let you call them. This mirrors Core’s own restraint: no feature exists halfway.
4. Every file’s upload progress lives on the MediaDropFile itself (uploadStatus, progress, uploadError, uploadResult, uploadAttempts) — you read it the same way you already read status/errors, via files.

​

Where does retry and concurrency logic live?

​

The shared retry engine

type RetryOptions = {
	retries?: number; // retries after the first attempt. Default 0.
	retryDelays?: number[]; // backoff per retry; last value repeats if exhausted.
	shouldRetry?: (error: unknown, attemptNumber: number) => boolean; // default: defaultShouldRetry
	jitter?: number; // 0–1, randomizes each delay by up to this fraction. Default 0.
};

​

What upload fields does MediaDropFile have?

type MediaDropFile = {
	// ...status, errors, etc. — unchanged from Core...
	uploadStatus?: "queued" | "uploading" | "done" | "error" | "canceled";
	progress?: { loaded: number; total: number | null };
	uploadError?: MediaDropError; // code: "upload-error", present after a failed attempt
	uploadResult?: unknown; // whatever the transport resolved with — opaque to the engine
	uploadAttempts?: number; // 1-indexed, for the current/last upload run
};

​

status and uploadStatus stay separate

• getAcceptedFiles()/getRejectedFiles() behave identically whether or not any upload has started, finished, or failed.
• maxFiles counting (based on status) is unaffected by upload progress — a file finishing its upload does not free up a maxFiles slot.

​

How do I configure concurrency, retry, and cancel?

useMediaDrop({
	transport,
	concurrency: 3, // max uploads in flight at once. Default 1 (sequential).
	retries: 2, // retries *after* the first attempt, shared for every file. Default 0.
	retryDelays: [1000, 2000, 4000], // backoff per retry; last value repeats if exhausted.
	cancelGraceMs: 5000, // force-free a slot this long after cancel if the transport never settles. Default 5000.
});

• uploadFile(id) — queues a file (or restarts it, even if it already finished/failed/was canceled). No-op if the file isn’t status: "accepted" or is already in flight.
• uploadAll() — queues every currently status: "accepted" file.
• cancelUpload(id) — aborts it if it’s uploading (via AbortSignal, standard web API), or drops it if it’s merely queued. Ends in uploadStatus: "canceled", not "error".
• cancelAllUploads() — cancels every queued and in-flight file.
• retryUpload(id) — re-enqueues a file, but only if its last attempt ended in uploadStatus: "error" — a no-op otherwise. This is a manual retry after automatic retries were exhausted, distinct from the automatic retries config above.

​

What’s the transport contract?

type UploadTransport = {
	upload(
		file: MediaDropFile,
		context: {
			onProgress: (progress: { loaded: number; total: number | null }) => void;
			signal: AbortSignal;
		},
	): Promise<{ response?: unknown }>;
};

​

What are the session-persistence utilities for?

type MediaDropUploadSessionStore = {
	get(key: string): Promise<unknown | null>;
	set(key: string, value: unknown): Promise<void>;
	remove(key: string): Promise<void>;
};

createMemoryUploadSessionStore(); // in-process only — gone on reload, gone between tabs
createBrowserUploadSessionStore({ prefix? }); // localStorage-backed, SSR-safe (no-op without `window`)

createFileFingerprint(file: File): string; // name+size+type+lastModified+webkitRelativePath, not file contents