Skip to content

Class: AnyDropCore ​

Defined in: core/src/AnyDropCore.ts:141

The headless upload engine: reads dropped and picked files and folders, validates them, builds the folder tree and uploads in chunks, with pause, resume and retry. Configure it with options, methods and events.

Example ​

ts
const core = new AnyDropCore({ url: '/upload', chunking: true });
core.on('queuecomplete', () => console.log(core.getErrors()));
const area = document.querySelector('#upload-area')!;
area.addEventListener('dragover', (e) => e.preventDefault());
area.addEventListener('drop', (e) => { e.preventDefault(); core.drop(e); });

Extends ​

Extended by ​

Constructors ​

Constructor ​

ts
new AnyDropCore(config?): AnyDropCore;

Defined in: core/src/AnyDropCore.ts:262

Creates an instance. Nothing touches window or document until files are added.

Parameters ​

ParameterType
config?AnyDropCoreConfig

Returns ​

AnyDropCore

Overrides ​

Emitter<AnyDropEvents>.constructor

Properties ​

PropertyModifierTypeDefault valueDescriptionDefined in
disabledpublicbooleanfalseSet by disable(), cleared by enable().core/src/AnyDropCore.ts:172
errorsprotected readonlyErrorRegistryundefinedThe error list. Protected so subclasses can read it; do not shadow it.core/src/AnyDropCore.ts:179
filesreadonlyAnyDropFile[][]Every file added and not removed, in add order. Do not modify.core/src/AnyDropCore.ts:170
optionsreadonlyAnyDropOptionsundefinedResolved options (defaults merged with yours). Change them with setOption().core/src/AnyDropCore.ts:168
treeprotected readonlyTreeStore...The folder tree. Protected so subclasses (@vedratech/anydrop-ui) can read it; do not shadow it.core/src/AnyDropCore.ts:177
ACCEPTEDstatic readonly"queued"ACCEPTEDAlias of QUEUED.core/src/AnyDropCore.ts:149
ADDEDstatic readonly"added"ADDEDStatus constant 'added'.core/src/AnyDropCore.ts:145
CANCELEDstatic readonly"canceled"CANCELEDStatus constant 'canceled'.core/src/AnyDropCore.ts:161
ERRORstatic readonly"error"ERRORStatus constant 'error'.core/src/AnyDropCore.ts:159
isValidFilestatic readonly(file, acceptedFiles) => booleanisValidFileWhether a file passes a type list such as 'image/*,.pdf'; an empty MIME type is judged by its extension.core/src/AnyDropCore.ts:163
PAUSEDstatic readonly"paused"PAUSEDStatus constant 'paused'.core/src/AnyDropCore.ts:155
PROCESSINGstatic readonly"uploading"PROCESSINGAlias of UPLOADING.core/src/AnyDropCore.ts:153
QUEUEDstatic readonly"queued"QUEUEDStatus constant 'queued'.core/src/AnyDropCore.ts:147
SUCCESSstatic readonly"success"SUCCESSStatus constant 'success'.core/src/AnyDropCore.ts:157
UPLOADINGstatic readonly"uploading"UPLOADINGStatus constant 'uploading'.core/src/AnyDropCore.ts:151
uuidv4static readonly() => stringuuidv4Creates a UUID version 4.core/src/AnyDropCore.ts:165
versionstatic readonlystringVERSIONLibrary version.core/src/AnyDropCore.ts:143

Accessors ​

isDestroyed ​

Get Signature ​

ts
get isDestroyed(): boolean;

Defined in: core/src/AnyDropCore.ts:1145

Whether destroy() was called.

Returns ​

boolean

Methods ​

_addFormElementData() ​

ts
protected _addFormElementData(formData): void;

Defined in: core/src/AnyDropCore.ts:335

Hook for subclasses (_addFormElementData): adds fields to an upload's form data, after sending and before the file blobs. @vedratech/anydrop-ui adds the inputs of a <form> element.

Parameters ​

ParameterType
formDataFormData

Returns ​

void


_completeExternal() ​

ts
protected _completeExternal(file): void;

Defined in: core/src/AnyDropCore.ts:344

Hook for subclasses: emits complete for a file outside the queue (a displayExistingFile mock file, which is in neither files nor the tree), then re-checks queuecomplete while a run is open, so it can never fire an extra queuecomplete when idle.

Parameters ​

ParameterType
fileAnyDropFile

Returns ​

void


addDataTransfer() ​

ts
addDataTransfer(dataTransfer): Promise<AnyDropFile[]>;

Defined in: core/src/AnyDropCore.ts:402

Adds the contents of a DataTransfer (files and folders) as one batch, without a drop event.

Parameters ​

ParameterType
dataTransferDataTransferLike

Returns ​

Promise<AnyDropFile[]>


addFile() ​

ts
addFile(file, folderPath?): AnyDropFile;

Defined in: core/src/AnyDropCore.ts:424

Adds one file. folderPath places it in a folder ('Photos/2024'); without it, a non-empty webkitRelativePath is used, else the file is loose. Calls in the same tick form one batch. Returns the file with its properties added.

Parameters ​

ParameterType
fileFile
folderPath?string

Returns ​

AnyDropFile


addFiles() ​

ts
addFiles(files): AnyDropFile[];

Defined in: core/src/AnyDropCore.ts:441

Adds several files as one batch (see addFile).

Parameters ​

ParameterType
filesArrayLike<File> | Iterable<File, any, any>

Returns ​

AnyDropFile[]


addFromInput() ​

ts
addFromInput(input): Promise<AnyDropFile[]>;

Defined in: core/src/AnyDropCore.ts:411

Adds the files of a file or folder input (<input type=file>, <input webkitdirectory>), or a FileList, as one batch. Folder paths come from webkitRelativePath.

Parameters ​

ParameterType
input| ArrayLike<File> | { files?: ArrayLike<File> | null; }

Returns ​

Promise<AnyDropFile[]>


cancelFolder() ​

ts
cancelFolder(path): void;

Defined in: core/src/AnyDropCore.ts:633

Cancels every unfinished file under a folder (cancelUpload per file: canceled, complete), then foldercomplete fires. The files keep their tree rows.

Parameters ​

ParameterType
pathstring

Returns ​

void


cancelUpload() ​

ts
cancelUpload(file): void;

Defined in: core/src/AnyDropCore.ts:1023

Cancels a file: aborts its requests, status canceled, then canceled and complete. With uploadMultiple, every file sharing its request is canceled.

Parameters ​

ParameterType
fileAnyDropFile

Returns ​

void


clearErrors() ​

ts
clearErrors(): void;

Defined in: core/src/AnyDropCore.ts:517

Empties the error list. The files stay in error.

Returns ​

void


clearPersistedState() ​

ts
clearPersistedState(): Promise<void>;

Defined in: core/src/AnyDropCore.ts:645

Deletes this persistKey's resume records (a "start over" button), and the claims of the files in the list, so they stop writing records. Does nothing when persistState is false.

Returns ​

Promise<void>


destroy() ​

ts
destroy(): void;

Defined in: core/src/AnyDropCore.ts:1115

Aborts every request, removes every listener and timer. The instance cannot be used again. No removedfile events are emitted.

Returns ​

void


disable() ​

ts
disable(): void;

Defined in: core/src/AnyDropCore.ts:350

Sets disabled and cancels every file. Adding files still works.

Returns ​

void


drop() ​

ts
drop(event): Promise<AnyDropFile[]>;

Defined in: core/src/AnyDropCore.ts:386

Handles a drop event: emits drop, reads files and folders (folders through webkitGetAsEntry), and resolves with the batch's files after addedfiles. Call it synchronously from the event listener: the browser clears the items afterwards.

Parameters ​

ParameterType
event{ dataTransfer?: DataTransferLike | null; }
event.dataTransfer?DataTransferLike | null

Returns ​

Promise<AnyDropFile[]>


emit() ​

ts
emit<K>(event, ...args): this;

Defined in: core/src/events/emitter.ts:61

Emits an event; every listener runs with this set to the instance. Returns the instance.

Type Parameters ​

Type Parameter
K extends keyof AnyDropEvents

Parameters ​

ParameterType
eventK
...argsAnyDropEvents[K]

Returns ​

this

Inherited from ​

Emitter.emit


enable() ​

ts
enable(): void;

Defined in: core/src/AnyDropCore.ts:359

Clears disabled.

Returns ​

void


enqueueFile() ​

ts
enqueueFile(file): void;

Defined in: core/src/AnyDropCore.ts:941

Queues an added, accepted file.

Parameters ​

ParameterType
fileAnyDropFile

Returns ​

void


enqueueFiles() ​

ts
enqueueFiles(files): void;

Defined in: core/src/AnyDropCore.ts:957

Queues several added, accepted files (with autoQueue: false).

Parameters ​

ParameterType
filesAnyDropFile[]

Returns ​

void


exportErrors() ​

ts
exportErrors(format?): string;

Defined in: core/src/AnyDropCore.ts:522

The error list as JSON or CSV (RFC 4180).

Parameters ​

ParameterTypeDefault value
format?"json" | "csv"'json'

Returns ​

string


filesize() ​

ts
filesize(size): string;

Defined in: core/src/AnyDropCore.ts:505

Size text for a byte count: '<strong>1.5</strong> MB'.

Parameters ​

ParameterType
sizenumber

Returns ​

string


getAcceptedFiles() ​

ts
getAcceptedFiles(): AnyDropFile[];

Defined in: core/src/AnyDropCore.ts:463

Files accepted by validation.

Returns ​

AnyDropFile[]


getActiveFiles() ​

ts
getActiveFiles(): AnyDropFile[];

Defined in: core/src/AnyDropCore.ts:498

Files in queued, uploading or paused.

Returns ​

AnyDropFile[]


getAddedFiles() ​

ts
getAddedFiles(): AnyDropFile[];

Defined in: core/src/AnyDropCore.ts:478

Files with status added.

Returns ​

AnyDropFile[]


getConnectionState() ​

ts
getConnectionState(): ConnectionState;

Defined in: core/src/AnyDropCore.ts:737

The connection as seen by the lifecycle code: browser offline, no answer from the server, or fine.

Returns ​

ConnectionState


getErrors() ​

ts
getErrors(): ErrorEntry[];

Defined in: core/src/AnyDropCore.ts:512

A copy of the error list: one entry per file currently in error.

Returns ​

ErrorEntry[]


getFile() ​

ts
getFile(id): AnyDropFile | undefined;

Defined in: core/src/AnyDropCore.ts:458

A file by its id.

Parameters ​

ParameterType
idstring

Returns ​

AnyDropFile | undefined


getFilesWithStatus() ​

ts
getFilesWithStatus(status): AnyDropFile[];

Defined in: core/src/AnyDropCore.ts:473

Files with the given status.

Parameters ​

ParameterType
statusFileStatus

Returns ​

AnyDropFile[]


getFolder() ​

ts
getFolder(path): FolderNode | undefined;

Defined in: core/src/AnyDropCore.ts:453

A folder node by path, for example getFolder('Photos/2024').

Parameters ​

ParameterType
pathstring

Returns ​

FolderNode | undefined


getOption() ​

ts
getOption<K>(name): AnyDropOptions[K];

Defined in: core/src/AnyDropCore.ts:364

Reads the current value of an option.

Type Parameters ​

Type Parameter
K extends keyof AnyDropEvents | keyof AnyDropCoreOptions<AnyDropCore>

Parameters ​

ParameterType
nameK

Returns ​

AnyDropOptions[K]


getPausedFiles() ​

ts
getPausedFiles(): AnyDropFile[];

Defined in: core/src/AnyDropCore.ts:493

Files with status paused.

Returns ​

AnyDropFile[]


getQueuedFiles() ​

ts
getQueuedFiles(): AnyDropFile[];

Defined in: core/src/AnyDropCore.ts:483

Files with status queued.

Returns ​

AnyDropFile[]


getRejectedFiles() ​

ts
getRejectedFiles(): AnyDropFile[];

Defined in: core/src/AnyDropCore.ts:468

Files rejected by validation.

Returns ​

AnyDropFile[]


getTree() ​

ts
getTree(): FolderNode;

Defined in: core/src/AnyDropCore.ts:448

The virtual root folder (path: ''): top-level folders and loose files. Live object.

Returns ​

FolderNode


getUploadingFiles() ​

ts
getUploadingFiles(): AnyDropFile[];

Defined in: core/src/AnyDropCore.ts:488

Files in uploading (paused files are not included).

Returns ​

AnyDropFile[]


hasListeners() ​

ts
hasListeners<K>(event): boolean;

Defined in: core/src/events/emitter.ts:76

Whether anyone listens to event (lets hot paths skip building payloads).

Type Parameters ​

Type Parameter
K extends keyof AnyDropEvents

Parameters ​

ParameterType
eventK

Returns ​

boolean

Inherited from ​

Emitter.hasListeners


off() ​

ts
off<K>(event?, fn?): this;

Defined in: core/src/events/emitter.ts:42

off() removes every listener, off(event) every listener of one event. Also matches once() listeners.

Type Parameters ​

Type Parameter
K extends keyof AnyDropEvents

Parameters ​

ParameterType
event?K
fn?Listener<AnyDropEvents[K]>

Returns ​

this

Inherited from ​

Emitter.off


on() ​

ts
on<K>(event, fn): Unsubscribe<AnyDropCore>;

Defined in: core/src/AnyDropCore.ts:310

Adds a listener; returns a function that removes it (chainable: .on(), .once()). No-op after destroy().

Type Parameters ​

Type Parameter
K extends keyof AnyDropEvents

Parameters ​

ParameterType
eventK
fnListener<AnyDropEvents[K]>

Returns ​

Unsubscribe<AnyDropCore>

Overrides ​

Emitter.on


once() ​

ts
once<K>(event, fn): Unsubscribe<AnyDropCore>;

Defined in: core/src/AnyDropCore.ts:317

Adds a listener that runs once. Returns a function that removes it.

Type Parameters ​

Type Parameter
K extends keyof AnyDropEvents

Parameters ​

ParameterType
eventK
fnListener<AnyDropEvents[K]>

Returns ​

Unsubscribe<AnyDropCore>

Overrides ​

Emitter.once


onListenerError() ​

ts
protected onListenerError(error): void;

Defined in: core/src/events/emitter.ts:82

Called when a listener throws. Overridable (tests).

Parameters ​

ParameterType
errorunknown

Returns ​

void

Inherited from ​

Emitter.onListenerError


paste() ​

ts
paste(event): Promise<AnyDropFile[]>;

Defined in: core/src/AnyDropCore.ts:393

Handles a paste event. Text-only pastes add nothing.

Parameters ​

ParameterType
event{ clipboardData?: DataTransferLike | null; }
event.clipboardData?DataTransferLike | null

Returns ​

Promise<AnyDropFile[]>


pause() ​

ts
pause(): void;

Defined in: core/src/AnyDropCore.ts:580

Pauses every file (paused({ scope: 'all', reason: 'user' })).

Returns ​

void


pauseFile() ​

ts
pauseFile(file): void;

Defined in: core/src/AnyDropCore.ts:612

Pauses one file (the file or its id).

Parameters ​

ParameterType
filestring | AnyDropFile

Returns ​

void


pauseFolder() ​

ts
pauseFolder(path): void;

Defined in: core/src/AnyDropCore.ts:594

Pauses every file under a folder, also files added to it later. Unknown paths are ignored.

Parameters ​

ParameterType
pathstring

Returns ​

void


processFile() ​

ts
processFile(file): void;

Defined in: core/src/AnyDropCore.ts:1005

Starts one queued file now, even beyond parallelUploads.

Parameters ​

ParameterType
fileAnyDropFile

Returns ​

void


processFiles() ​

ts
processFiles(files): void;

Defined in: core/src/AnyDropCore.ts:983

Starts these queued files now, even beyond parallelUploads. Files of a batch that is still open start when it closes. With uploadMultiple, the files of one batch share one request.

Parameters ​

ParameterType
filesAnyDropFile[]

Returns ​

void


processQueue() ​

ts
processQueue(): void;

Defined in: core/src/AnyDropCore.ts:967

Starts queued files until parallelUploads files are uploading. Files start in add order; a batch's manifest is sent before its first file. Without a url, nothing starts. Called while a batch is still being read, it also runs when that batch closes, so its files are included.

Returns ​

void


reconnect() ​

ts
reconnect(): void;

Defined in: core/src/AnyDropCore.ts:750

"Retry now": probes at once while the state is unreachable, and clears an offline pause the browser no longer reports. Does nothing when online. Unlike resume(), user pauses stay.

Returns ​

void


removeAllFiles() ​

ts
removeAllFiles(cancelIfNecessary?): void;

Defined in: core/src/AnyDropCore.ts:1087

Removes every file that is not uploading, or every file when cancelIfNecessary is true. Emits removedfile per file, removedfolder for every folder left without files (also folders dropped empty), then reset.

Parameters ​

ParameterTypeDefault value
cancelIfNecessary?booleanfalse

Returns ​

void


removeFile() ​

ts
removeFile(file): void;

Defined in: core/src/AnyDropCore.ts:1057

Removes a file; cancels it first when it is uploading.

Parameters ​

ParameterType
fileAnyDropFile

Returns ​

void


resolveOption() ​

ts
resolveOption<T>(option, ...args): T;

Defined in: core/src/AnyDropCore.ts:325

Calls a function option with this = the instance, else returns it.

Type Parameters ​

Type Parameter
T

Parameters ​

ParameterType
optionT | ((...args) => T)
...argsunknown[]

Returns ​

T


resume() ​

ts
resume(): void;

Defined in: core/src/AnyDropCore.ts:586

Clears the instance pause and every system reason (offline, hidden). Folder and file pauses stay.

Returns ​

void


resumeFile() ​

ts
resumeFile(file): void;

Defined in: core/src/AnyDropCore.ts:621

Clears a file's own pause (a paused folder or instance still holds it).

Parameters ​

ParameterType
filestring | AnyDropFile

Returns ​

void


resumeFolder() ​

ts
resumeFolder(path): void;

Defined in: core/src/AnyDropCore.ts:603

Clears a folder's own pause. Files stay paused while an ancestor, the instance or the file itself is paused.

Parameters ​

ParameterType
pathstring

Returns ​

void


retryFailedOnly() ​

ts
retryFailedOnly(folderPath?): number;

Defined in: core/src/AnyDropCore.ts:531

Re-queues the files in error (under folderPath, or all) that can be retried: everything but validation rejections. Done chunks are kept; chunkStatusUrl is asked first when set; a failed batch manifest is sent again (same sessionId). Returns the number of files re-queued.

Parameters ​

ParameterType
folderPath?string

Returns ​

number


retryFile() ​

ts
retryFile(file): boolean;

Defined in: core/src/AnyDropCore.ts:559

Re-queues one failed file (the file or its id) like retryFailedOnly. Returns whether it was re-queued.

Parameters ​

ParameterType
filestring | AnyDropFile

Returns ​

boolean


setOption() ​

ts
setOption<K>(name, value): void;

Defined in: core/src/AnyDropCore.ts:290

Changes an option (or an event handler given as an option) at runtime.

Type Parameters ​

Type Parameter
K extends | keyof AnyDropEvents | keyof AnyDropCoreOptions<AnyDropCore> | "_uuid" | "_random"

Parameters ​

ParameterType
nameK
valueAnyDropCoreConfig[K]

Returns ​

void


unsubscribe() ​

ts
protected unsubscribe<K>(event, fn): Unsubscribe<AnyDropCore>;

Defined in: core/src/events/emitter.ts:87

Builds the function returned by on()/once(). Protected for subclasses; do not shadow it.

Type Parameters ​

Type Parameter
K extends keyof AnyDropEvents

Parameters ​

ParameterType
eventK
fnListener<AnyDropEvents[K]>

Returns ​

Unsubscribe<AnyDropCore>

Inherited from ​

Emitter.unsubscribe


uploadFile() ​

ts
uploadFile(file): void;

Defined in: core/src/AnyDropCore.ts:1010

Alias of processFile. Overriding it changes nothing: use transport instead.

Parameters ​

ParameterType
fileAnyDropFile

Returns ​

void


uploadFiles() ​

ts
uploadFiles(files): void;

Defined in: core/src/AnyDropCore.ts:1015

Alias of processFiles.

Parameters ​

ParameterType
filesAnyDropFile[]

Returns ​

void

Released under the MIT License.