@vobs/upload

File uploads for vobs: FormData encoding over any HTTPClient, concurrency control, reactive progress, and per-task cancel and retry.

Install

npm install @vobs/upload

Quick start

import { createHTTPClient } from '@vobs/http'
import { createUpload } from '@vobs/upload'

const upload = createUpload({
  http: createHTTPClient(),
  url: '/upload',
  fieldName: 'document',
  accept: ['image/*', '.pdf'],
  maxFileSize: 10 * 1024 * 1024,
  concurrency: 3
})

const task = upload.upload(file, { metadata: { tenant: 'acme' } })

task.progress.value // 0-100 while uploading
await task.promise  // mapped response, or null when cancelled or failed
task.error.value    // UploadError when status is 'error'

Files are validated against accept (MIME or extension patterns) and maxFileSize before a task is created; invalid files throw UploadError and never enter the queue. At most concurrency tasks upload at once; the rest wait in line. task.cancel() aborts the underlying HTTP request through its signal. Failed tasks can be re-run with task.retry(), which inherits the task's retry options.

API

| Signature | Description | | --- | --- | | createUpload(options): UploadContext | Requires http and url; options: method, fieldName, metadata, accept, maxFileSize, concurrency, headers, timeout, retry, response. | | upload.upload(file, options?): UploadTask | Create one task; per-task options override metadata, headers, retry settings, and response mapping. | | upload.uploadAll(files, options?): UploadTask[] | Queue a batch through the same concurrency limit. | | upload.tasks | Signal listing every task in creation order. | | upload.clearCompleted() / dispose() | Drop finished tasks; cancel and release everything. | | task.progress / status / error / result | Signals for percent, status (pending to cancelled), error, and mapped response. | | task.promise | Resolves with the mapped result, or null on cancel and failure. | | task.cancel() / task.retry() | Abort the in-flight request; re-run a failed task. | | uploadPlugin(options?) / useUpload() | Provide and inject UPLOAD_KEY; injects HTTP_KEY unless http is passed. | | UploadError | Error with code: INVALID_FILE, FILE_TYPE_UNSUPPORTED, FILE_TOO_LARGE, UPLOAD_FAILED, UPLOAD_CONTEXT_DISPOSED. |

Types

UploadStatus, UploadFile, UploadMetadata, UploadTask, UploadTaskOptions, UploadOptions, UploadContext, UploadPluginOptions, UploadErrorCode