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
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
Emitter<AnyDropEvents>
Extended by
Constructors
Constructor
new AnyDropCore(config?): AnyDropCore;Defined in: core/src/AnyDropCore.ts:262
Creates an instance. Nothing touches window or document until files are added.
Parameters
| Parameter | Type |
|---|---|
config? | AnyDropCoreConfig |
Returns
AnyDropCore
Overrides
Emitter<AnyDropEvents>.constructor
Properties
| Property | Modifier | Type | Default value | Description | Defined in |
|---|---|---|---|---|---|
disabled | public | boolean | false | Set by disable(), cleared by enable(). | core/src/AnyDropCore.ts:172 |
errors | protected readonly | ErrorRegistry | undefined | The error list. Protected so subclasses can read it; do not shadow it. | core/src/AnyDropCore.ts:179 |
files | readonly | AnyDropFile[] | [] | Every file added and not removed, in add order. Do not modify. | core/src/AnyDropCore.ts:170 |
options | readonly | AnyDropOptions | undefined | Resolved options (defaults merged with yours). Change them with setOption(). | core/src/AnyDropCore.ts:168 |
tree | protected readonly | TreeStore | ... | The folder tree. Protected so subclasses (@vedratech/anydrop-ui) can read it; do not shadow it. | core/src/AnyDropCore.ts:177 |
ACCEPTED | static readonly | "queued" | ACCEPTED | Alias of QUEUED. | core/src/AnyDropCore.ts:149 |
ADDED | static readonly | "added" | ADDED | Status constant 'added'. | core/src/AnyDropCore.ts:145 |
CANCELED | static readonly | "canceled" | CANCELED | Status constant 'canceled'. | core/src/AnyDropCore.ts:161 |
ERROR | static readonly | "error" | ERROR | Status constant 'error'. | core/src/AnyDropCore.ts:159 |
isValidFile | static readonly | (file, acceptedFiles) => boolean | isValidFile | Whether a file passes a type list such as 'image/*,.pdf'; an empty MIME type is judged by its extension. | core/src/AnyDropCore.ts:163 |
PAUSED | static readonly | "paused" | PAUSED | Status constant 'paused'. | core/src/AnyDropCore.ts:155 |
PROCESSING | static readonly | "uploading" | PROCESSING | Alias of UPLOADING. | core/src/AnyDropCore.ts:153 |
QUEUED | static readonly | "queued" | QUEUED | Status constant 'queued'. | core/src/AnyDropCore.ts:147 |
SUCCESS | static readonly | "success" | SUCCESS | Status constant 'success'. | core/src/AnyDropCore.ts:157 |
UPLOADING | static readonly | "uploading" | UPLOADING | Status constant 'uploading'. | core/src/AnyDropCore.ts:151 |
uuidv4 | static readonly | () => string | uuidv4 | Creates a UUID version 4. | core/src/AnyDropCore.ts:165 |
version | static readonly | string | VERSION | Library version. | core/src/AnyDropCore.ts:143 |
Accessors
isDestroyed
Get Signature
get isDestroyed(): boolean;Defined in: core/src/AnyDropCore.ts:1145
Whether destroy() was called.
Returns
boolean
Methods
_addFormElementData()
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
| Parameter | Type |
|---|---|
formData | FormData |
Returns
void
_completeExternal()
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
| Parameter | Type |
|---|---|
file | AnyDropFile |
Returns
void
addDataTransfer()
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
| Parameter | Type |
|---|---|
dataTransfer | DataTransferLike |
Returns
Promise<AnyDropFile[]>
addFile()
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
| Parameter | Type |
|---|---|
file | File |
folderPath? | string |
Returns
addFiles()
addFiles(files): AnyDropFile[];Defined in: core/src/AnyDropCore.ts:441
Adds several files as one batch (see addFile).
Parameters
| Parameter | Type |
|---|---|
files | ArrayLike<File> | Iterable<File, any, any> |
Returns
addFromInput()
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
| Parameter | Type |
|---|---|
input | | ArrayLike<File> | { files?: ArrayLike<File> | null; } |
Returns
Promise<AnyDropFile[]>
cancelFolder()
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
| Parameter | Type |
|---|---|
path | string |
Returns
void
cancelUpload()
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
| Parameter | Type |
|---|---|
file | AnyDropFile |
Returns
void
clearErrors()
clearErrors(): void;Defined in: core/src/AnyDropCore.ts:517
Empties the error list. The files stay in error.
Returns
void
clearPersistedState()
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()
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()
disable(): void;Defined in: core/src/AnyDropCore.ts:350
Sets disabled and cancels every file. Adding files still works.
Returns
void
drop()
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
| Parameter | Type |
|---|---|
event | { dataTransfer?: DataTransferLike | null; } |
event.dataTransfer? | DataTransferLike | null |
Returns
Promise<AnyDropFile[]>
emit()
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
| Parameter | Type |
|---|---|
event | K |
...args | AnyDropEvents[K] |
Returns
this
Inherited from
Emitter.emit
enable()
enable(): void;Defined in: core/src/AnyDropCore.ts:359
Clears disabled.
Returns
void
enqueueFile()
enqueueFile(file): void;Defined in: core/src/AnyDropCore.ts:941
Queues an added, accepted file.
Parameters
| Parameter | Type |
|---|---|
file | AnyDropFile |
Returns
void
enqueueFiles()
enqueueFiles(files): void;Defined in: core/src/AnyDropCore.ts:957
Queues several added, accepted files (with autoQueue: false).
Parameters
| Parameter | Type |
|---|---|
files | AnyDropFile[] |
Returns
void
exportErrors()
exportErrors(format?): string;Defined in: core/src/AnyDropCore.ts:522
The error list as JSON or CSV (RFC 4180).
Parameters
| Parameter | Type | Default value |
|---|---|---|
format? | "json" | "csv" | 'json' |
Returns
string
filesize()
filesize(size): string;Defined in: core/src/AnyDropCore.ts:505
Size text for a byte count: '<strong>1.5</strong> MB'.
Parameters
| Parameter | Type |
|---|---|
size | number |
Returns
string
getAcceptedFiles()
getAcceptedFiles(): AnyDropFile[];Defined in: core/src/AnyDropCore.ts:463
Files accepted by validation.
Returns
getActiveFiles()
getActiveFiles(): AnyDropFile[];Defined in: core/src/AnyDropCore.ts:498
Files in queued, uploading or paused.
Returns
getAddedFiles()
getAddedFiles(): AnyDropFile[];Defined in: core/src/AnyDropCore.ts:478
Files with status added.
Returns
getConnectionState()
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
getErrors()
getErrors(): ErrorEntry[];Defined in: core/src/AnyDropCore.ts:512
A copy of the error list: one entry per file currently in error.
Returns
getFile()
getFile(id): AnyDropFile | undefined;Defined in: core/src/AnyDropCore.ts:458
A file by its id.
Parameters
| Parameter | Type |
|---|---|
id | string |
Returns
AnyDropFile | undefined
getFilesWithStatus()
getFilesWithStatus(status): AnyDropFile[];Defined in: core/src/AnyDropCore.ts:473
Files with the given status.
Parameters
| Parameter | Type |
|---|---|
status | FileStatus |
Returns
getFolder()
getFolder(path): FolderNode | undefined;Defined in: core/src/AnyDropCore.ts:453
A folder node by path, for example getFolder('Photos/2024').
Parameters
| Parameter | Type |
|---|---|
path | string |
Returns
FolderNode | undefined
getOption()
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
| Parameter | Type |
|---|---|
name | K |
Returns
getPausedFiles()
getPausedFiles(): AnyDropFile[];Defined in: core/src/AnyDropCore.ts:493
Files with status paused.
Returns
getQueuedFiles()
getQueuedFiles(): AnyDropFile[];Defined in: core/src/AnyDropCore.ts:483
Files with status queued.
Returns
getRejectedFiles()
getRejectedFiles(): AnyDropFile[];Defined in: core/src/AnyDropCore.ts:468
Files rejected by validation.
Returns
getTree()
getTree(): FolderNode;Defined in: core/src/AnyDropCore.ts:448
The virtual root folder (path: ''): top-level folders and loose files. Live object.
Returns
getUploadingFiles()
getUploadingFiles(): AnyDropFile[];Defined in: core/src/AnyDropCore.ts:488
Files in uploading (paused files are not included).
Returns
hasListeners()
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
| Parameter | Type |
|---|---|
event | K |
Returns
boolean
Inherited from
Emitter.hasListeners
off()
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
| Parameter | Type |
|---|---|
event? | K |
fn? | Listener<AnyDropEvents[K]> |
Returns
this
Inherited from
Emitter.off
on()
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
| Parameter | Type |
|---|---|
event | K |
fn | Listener<AnyDropEvents[K]> |
Returns
Unsubscribe<AnyDropCore>
Overrides
Emitter.on
once()
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
| Parameter | Type |
|---|---|
event | K |
fn | Listener<AnyDropEvents[K]> |
Returns
Unsubscribe<AnyDropCore>
Overrides
Emitter.once
onListenerError()
protected onListenerError(error): void;Defined in: core/src/events/emitter.ts:82
Called when a listener throws. Overridable (tests).
Parameters
| Parameter | Type |
|---|---|
error | unknown |
Returns
void
Inherited from
Emitter.onListenerError
paste()
paste(event): Promise<AnyDropFile[]>;Defined in: core/src/AnyDropCore.ts:393
Handles a paste event. Text-only pastes add nothing.
Parameters
| Parameter | Type |
|---|---|
event | { clipboardData?: DataTransferLike | null; } |
event.clipboardData? | DataTransferLike | null |
Returns
Promise<AnyDropFile[]>
pause()
pause(): void;Defined in: core/src/AnyDropCore.ts:580
Pauses every file (paused({ scope: 'all', reason: 'user' })).
Returns
void
pauseFile()
pauseFile(file): void;Defined in: core/src/AnyDropCore.ts:612
Pauses one file (the file or its id).
Parameters
| Parameter | Type |
|---|---|
file | string | AnyDropFile |
Returns
void
pauseFolder()
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
| Parameter | Type |
|---|---|
path | string |
Returns
void
processFile()
processFile(file): void;Defined in: core/src/AnyDropCore.ts:1005
Starts one queued file now, even beyond parallelUploads.
Parameters
| Parameter | Type |
|---|---|
file | AnyDropFile |
Returns
void
processFiles()
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
| Parameter | Type |
|---|---|
files | AnyDropFile[] |
Returns
void
processQueue()
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()
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()
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
| Parameter | Type | Default value |
|---|---|---|
cancelIfNecessary? | boolean | false |
Returns
void
removeFile()
removeFile(file): void;Defined in: core/src/AnyDropCore.ts:1057
Removes a file; cancels it first when it is uploading.
Parameters
| Parameter | Type |
|---|---|
file | AnyDropFile |
Returns
void
resolveOption()
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
| Parameter | Type |
|---|---|
option | T | ((...args) => T) |
...args | unknown[] |
Returns
T
resume()
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()
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
| Parameter | Type |
|---|---|
file | string | AnyDropFile |
Returns
void
resumeFolder()
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
| Parameter | Type |
|---|---|
path | string |
Returns
void
retryFailedOnly()
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
| Parameter | Type |
|---|---|
folderPath? | string |
Returns
number
retryFile()
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
| Parameter | Type |
|---|---|
file | string | AnyDropFile |
Returns
boolean
setOption()
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
| Parameter | Type |
|---|---|
name | K |
value | AnyDropCoreConfig[K] |
Returns
void
unsubscribe()
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
| Parameter | Type |
|---|---|
event | K |
fn | Listener<AnyDropEvents[K]> |
Returns
Unsubscribe<AnyDropCore>
Inherited from
Emitter.unsubscribe
uploadFile()
uploadFile(file): void;Defined in: core/src/AnyDropCore.ts:1010
Alias of processFile. Overriding it changes nothing: use transport instead.
Parameters
| Parameter | Type |
|---|---|
file | AnyDropFile |
Returns
void
uploadFiles()
uploadFiles(files): void;Defined in: core/src/AnyDropCore.ts:1015
Alias of processFiles.
Parameters
| Parameter | Type |
|---|---|
files | AnyDropFile[] |
Returns
void