npm package: @linker-design-plus/upload-core
Description: The core logical of file upload for linker design.
Author: Linker Design Team
Latest version: 0.3.22

<h1 align="center">
   <b>
        @linker-design/upload-core
    </b>
</h1>

<p align="center"><strong>Base storage service for the browser and node.js</strong></p>

# Features

- <strong> Support `minio`, `oss`, `webdav` and `default` upload methods. </strong> ✨

- <strong> Support multipart upload. </strong> ✨

- <strong> Real-time progress return, such as rate, uploaded size, etc. </strong>

- <strong> Includes up to six file upload status for easy use. </strong>

- <strong> Support automatic image compression when uploading images. </strong> ✨

# Setup

```ts
npm i @linker-design/upload-core
```

# Usages

```ts
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.

```ts
{
    // `mode` is the upload mode that contains optional mode `minio`, `oss`, `webdav`, `default`
    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
    // default: `url` will be used to directly upload file to backend service
    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,


    // `imageCompress` is the image compression configuration
    // If enabled, images will be automatically compressed when their width or height exceeds the specified dimension
    // The long side will be resized to `maxDimension`, and the short side will be scaled proportionally
    imageCompress: {
      // `enabled` determines whether to enable image compression, default is `false`
      enabled: false,
      // `maxDimension` is the maximum dimension (in pixels) for images
      // If the width or height of an image exceeds this value, the long side will be resized to this value
      // and the short side will be scaled proportionally, default is `640`
      maxDimension: 640
    }
}
```