@stack-upload-orchestrator/core

Core upload logic — queue management, file validation, retry with exponential backoff, progress tracking, and the StorageAdapter interface.

Installation

npm install @stack-upload-orchestrator/core

Quick start

import { UploadQueue } from '@stack-upload-orchestrator/core';

const queue = new UploadQueue({
  concurrency: 3,
  uploader: async (info, signal, onProgress) => {
    // your upload logic here
    return { url: '...', fileId: '...', name: info.name, size: info.size, type: info.type };
  },
  validation: {
    maxFileSize: '10MB',
    allowedTypes: ['image/*', 'application/pdf'],
  },
  retry: { maxAttempts: 3 },
});

queue.addMany(fileList);

API

UploadQueue

new UploadQueue(options?: QueueOptions)

| Option | Type | Default | Description | |---|---|---|---| | uploader | Uploader | — | Function called for each file | | concurrency | number | 3 | Max simultaneous uploads | | autoStart | boolean | true | Begin processing on add | | validation | ValidationOptions | — | File validation rules | | retry | RetryOptions | — | Retry configuration |

Methods

| Method | Description | |---|---| | add(file, options?) | Add a single file | | addMany(files, options?) | Add a FileList or File[] | | cancel(taskId?) | Cancel one task or all | | pause(taskId?) | Pause one task or the whole queue | | resume(taskId?) | Resume one task or the whole queue | | retry(taskId?) | Retry failed task(s) | | remove(taskId) | Remove a task from the queue | | clear() | Remove all tasks | | getTasks() | Returns current UploadTask[] snapshot |

Events: add, remove, start, progress, completed, error, cancelled, empty

FileValidator

import { FileValidator } from '@stack-upload-orchestrator/core';

const validator = new FileValidator({
  maxFileSize: '5MB',
  allowedTypes: ['image/*'],
  allowedExtensions: ['.jpg', '.png'],
  maxFiles: 10,
});

const result = validator.validate({ name: 'photo.jpg', size: 1024 * 1024, type: 'image/jpeg' });
// { valid: true, errors: [] }

ValidationOptions:

| Option | Type | Description | |---|---|---| | maxFileSize | number \| string | e.g. "10MB", 5242880 | | minFileSize | number \| string | Minimum size | | allowedTypes | string[] | MIME types, supports wildcards: ["image/*"] | | allowedExtensions | string[] | e.g. [".jpg", ".pdf"] | | maxFiles | number | Max files in one batch |

RetryManager

import { RetryManager } from '@stack-upload-orchestrator/core';

const retry = new RetryManager({
  maxAttempts: 5,
  initialDelay: 500,
  maxDelay: 15000,
  backoffFactor: 2,
  onRetry: (attempt, error) => console.log(`Retry ${attempt}:`, error.message),
});

ProgressTracker

import { ProgressTracker } from '@stack-upload-orchestrator/core';

const tracker = new ProgressTracker();
tracker.update(taskId, loaded, total);
console.log(tracker.percent); // 0–100

StorageAdapter interface

Implement this to create a custom client-side storage adapter:

import type { StorageAdapter } from '@stack-upload-orchestrator/core';

const myAdapter: StorageAdapter = {
  async upload(file, signal, onProgress) {
    // ...
    return { url, fileId, name, size, type };
  },
  async delete(fileId) { /* optional */ },
  async getSignedUrl(fileId, expiresIn) { /* optional */ },
};

createUploader

Wraps a StorageAdapter into an Uploader function compatible with UploadQueue:

import { createUploader } from '@stack-upload-orchestrator/core';

const uploader = createUploader(myAdapter);
const queue = new UploadQueue({ uploader });

Types

type UploadStatus = 'pending' | 'uploading' | 'paused' | 'completed' | 'failed' | 'cancelled';

interface UploadResult {
  url: string;
  fileId: string;
  name: string;
  size: number;
  type: string;
  metadata?: Record<string, unknown>;
}

License

MIT