Features

• Support minio, oss and webdav upload methods. ✨

• Support multipart upload. ✨

• Real-time progress return, such as rate, uploaded size, etc.

• Includes up to six file upload status for easy use.

Setup

npm i @linker-design/upload-core

Usages

import Uploader from '@linker-design/upload-core';
import type { Info, Options, Progress, WrapFile } from '@linker-design/upload-core';

// Create upload option
const options: Options = {
  mode: 'minio',
  url: 'http://example.com',
 };

// Initialize upload class
const store = new Uploader(options);

// Select upload files
const files: Array<File | WrapFile> = [...];

// Upload files
// The return value of the `upload` method can be assigned directly to a responsive variable,
// and each element object contains an `uploadProgress` field that can be used to display progress.
const readyFiles = store.upload(file /* file or [file] */);

// Pause upload file
store.pause(file | undefined);

// Resume upload file
store.resume(file | undefined);

// Abort upload file
store.abort(file | undefined);

Note that the parameters passed to the upload API can be a single file or an array of files. When no parameters are passed to the pause, resume, abort API, the default will be to operate on all files that have not been uploaded.

Config

These are the configuration options that can be used when creating an upload class. Only mode, url is required. If no corresponding parameter is specified the default value will be used.

{
    // `mode` is the upload mode that contains optional mode `minio`, `oss`, `webdav`
    mode: 'minio',


    // `url` is the backend service URL that has different roles according to the storage type currently.
    // oss: `url` will be used for `abort` API
    // minio: `url` will be used to do something , such as initializing uplaod envet, generating upload part, etc
    // webdav: `url` will be used a path for `upload` API
    url: 'http://example.com',


    // `storageUrl` is the storage server URL which only used in `oss` mode currently
    storageUrl: 'https://yunlicloud.oss-cn-hangzhou.aliyuncs.com/',


    // `storageOptions` is the specified configuration for storage instance which only used in `oss` mode currently.
    // The following configurations are all fake data from the project !!!
    storageOptions: {
      accessKeyId: 'STS.NTPd9t...nFaA7AKbVse',
      accessKeySecret: 'AhNyu1wzLaYjHuG...666NB49MnTAi9mwdq',
      stsToken: 'CAIS/wF1q6Ft5B2...yYP8ZHGoqZ3a3OsD6BMJZth+pJS96jvtP9Tx5g==',
      region: 'oss-cn-hangzhou',
      bucket: 'yunlicloud',
      // other options...
    }


    // `storePrefix` allows custom the prefix of storage path
    storePrefix: 'example/store/path' | (file: IFile, files: IFile[], options: Options) => {
      // logical code...

      return 'example/store/path'
    },

    // `md5` is the md5 digest of file content
    md5: false,

    // `originFileField` is the key of `File` object 
    originFileField: 'file',


    // `deleteOriginFile` deletemines whether deleting original file
    // on the storage server or not when calling the `abort` API.
    deleteOriginFile: false | (file: IFile, files: IFile[], options: Options) => {
      // logical code...

      return false
    },

    // `temporary` deletemines whether uploading file to temporary bucket.
    // The uploaded files my be deleted by the service at any time, otherwise they can only be deleted by the user.
    temporary: false,


    // `fileParallel` is the parallel count of file upload task
    fileParallel: 1,


    // `partParallel` is the parallel count of file part upload task
    partParallel: 1,


    // `partSize` is the size of part
    // oss storage service default 1MB.
    // minio storage service will have exception if the partition is less than 5MB.
    partSize: 1024 * 1024 * 5,


    // `taskSelector` is used to specify the upload task to be executed first.
    // If `true` is returned, the current file upload task will be executed first, otherwise it will be executed sequentially from the beginning.
    taskSelector: (task: Task) => {
      // logical code...

      return true
    },


    // `headers` is the custom request headers for upload
    headers: { ... } | (file: IFile, files: IFile[], options: Options) => {
      // logical code...

      return { ... }
    },


    // `data` is the custom request data body for upload which only used in `webdav` mode currently
    data: { ... } | (file: IFile, files: IFile[], options: Options) => {
      // logical code...

      return { ... }
    },

    // `beforeUpload` will be invoked before uploading each file
    beforeUpload: (file: IFile, files: IFile[], options: Options) => {
      // logical code...

      // return boolean | promise<boolean>
      // or return { allow: boolean, batch?: boolean } | promise<{ allow: boolean, batch?: boolean }>
    },

    // `exist` verifies if the file exists, and it can be a function that returns a boolean value
    // If `exist` returns truth, the task will be skipped and the file status will be updated to `success`
    exist: false | (file: IFile, files: IFile[], options: Options) => {
      // logical code...

      return false
    },


    // `progress` allows progress events to be handled for uploads
    progress: (progress: Progress, info?: Info) => {
      // Do whatever you want to display upload progress

    },


    // `stat` allows to handle status events for uploads
    // Whenever the status of file changes, the `stat` method will be called to return the overall status statistics object
    stat: (stat: Status, info?: Info) => {
      // Do whatever you want to display upload status
    },


    // `success` allows handling of success events for uploads
    success: (response: any, info?: Info) => {
      // Do whatever you want to handle upload success

    },

    // `complete` allows handling of `complete` events
    // If sum of `ready` and `uploading` is 0, the `complete` will be called
    complete: () => void;
}