The framework-agnostic upload engine.
npm install @uploadcn/coreEntry points: @uploadcn/core (engine, adapters, validation, utilities),
@uploadcn/core/image (image processing), @uploadcn/core/tus (tus adapter, needs
tus-js-client).
createUploader
function createUploader<TResult>(options: UploaderOptions<TResult>): Uploader<TResult>UploaderOptions
Prop
Type
Uploader
| Method | Description |
|---|---|
add(files, { meta?, start? }) | Validate, transform and enqueue. Resolves with the new items. |
start(selector?) | Queue idle items. |
pause(selector?) / resume(selector?) | Pause queued or resumable uploads. |
cancel(selector?) | Abort and clean up server state. |
retry(selector?) | Retry failed or cancelled items (resets attempts). |
remove(selector?) / clearCompleted() | Remove items. |
update(id, { status?, result?, error?, meta? }) | Drive processing/scanning states from outside. |
getState() / subscribe(listener) | Immutable snapshot + change listener. |
on(event, handler) | Typed events; returns an unsubscribe function. |
getItem(id) / canPause(item) | Helpers. |
restore() | Load persisted uploads (paused). |
setOptions(partial) / getOptions() | Update options at runtime. |
mount() | Attach network listeners; returns a cleanup. |
destroy() | Abort everything and release resources. |
A selector is an id, an array of ids, a predicate, or nothing (all items).
UploadItem
Prop
Type
UploadError
new UploadError(message, { code, retryable?, status?, retryAfter?, details?, cause? })code: network, timeout, http, aborted, offline, validation, rejected, unknown.
Helpers: isUploadError, toUploadError, httpError, isRetryableStatus, parseRetryAfter.
Validation
validateFile, validateFiles, validateFileSync, validateFileCount, matchesAccept,
parseAccept, toAcceptAttribute, getFileType.
Adapters
s3Adapter, r2Adapter, presignedAdapter, multipartAdapter, httpAdapter,
routeAdapter, mockAdapter, and tusAdapter from @uploadcn/core/tus. The default
transport is xhrTransport (XMLHttpRequest, for upload progress).
Persistence & capabilities
createIndexedDBPersistence({ name?, store?, maxAge? }), createMemoryPersistence(),
getBackgroundCapabilities(), requestPersistentStorage().
OCR
ocrEndpoint(url, options?) sends files to your OCR route; tesseractOcr({ load, lang? })
reads them in the browser; ocrProcess(recognize, { required?, filter? }) turns either into
an uploader process step that stores the result on item.meta.ocr. All return or use
OcrResult: { text, pages, confidence?, fields?, markdown?, provider }. See
OCR.
Image (@uploadcn/core/image)
transformImage(file, options), compressImage(file, options), imageTransform(options),
getImageDimensions(file), getRotatedSize, getFitScale, canTransformImage.
Utilities
formatBytes, formatSpeed, formatDuration, getUploadSummary, getPartSize,
createChunks, withRetry, getRetryDelay, sleep, getDroppedFiles,
getClipboardFiles, isFileDrag, getMediaDuration, KiB, MiB, GiB.