Yl-Upload-Tools

Yl-Upload-Tools js client for Browser env. Support upload file to AliOSS.

Local Development

# soft link with local global
npm link

# local debugging
npm run build:dev

# use in your project
npm link yl-upload-tools

# remove soft link in your project
npm unlink yl-upload-tools

Production Publish

# build
npm run build:prod

# publish
npm login
npm publish

Install

npm install yl-upload-tools --save

Compatibility

> Node.js >= 14.0.0 Required

SDK Usage

• use AliOS SDK Service. reference ali-oss

Basic Usage

export { Upload, uploadMD5 } with yl-upload-tools

• Upload {Function}

  create upload instance with customer need

  parameters:

  • type {String} [default: 'ali'] upload type

    • Upload Class

    parameters:

    • uploadFile {Object} [default: null] upload file type object
    • uploadFileList {Array} [default: []] upload file list

  import { Upload } from 'yl-upload-tools';
  
  // Instantiate OSS
  const upload = Upload({ type: 'ali' });

• uploadMD5(file, onCalcMD5Progress, chunkSize) {Function} uploadMD5 method is used to calc file md5.

  parameters:

  • File [Required] {Function}
  • onError [Optional] {Function}
    • status: 'error' {String}
  • onCancel [Optional] {Function}
    • status: 'cancel' {String}
  • onPause [Optional] {Function}
    • status: 'paused' {String}
  • onSuccess [Optional] {Function}
    • status: 'success' {String}
  • chunkSize [Optional] {Number} default: 2MB

  return md5

  {
      md5: String;
  }

  import { uploadMD5 } from 'yl-upload-tools';
  
  const result = await uploadMD5({
    file,
    onSuccess(){},
    onError(){},
    ...
  });
  
  console.log(result.md5);

Summary

Basic File Type

| Property | Value Type | Value Meaning | | --------------- | :--------: | :-------------------------------------------------: | | id | String | 文件唯一 ID | | isUploading | Boolean | 正在上传状态 | | isError | Boolean | 上传失败状态 | | isUploaded | Boolean | 成功上传状态 | | isPaused | Boolean | 暂停上传状态 | | isCancel | Boolean | 取消上传状态 | | isComputedMD5 | Boolean | 计算 MD5 状态 | | isWaitingUpload | Boolean | 等待上传状态 | | file | File | Input File Object | | md5 | String | File md5 | | percent | Number | File 上传进度 (百分制) | | checkpoint | Object | 阿里云分块节点信息 | | curInitPartSize | Number | File 初始化文件大小(供暂停上传后的速率更新计算使用) | | networkSpeed | Number | File 上传速率 (单位字节) | | startTime | Number | File 上传开始时间 (毫秒) | | OSS | Object | OSS 实例 | | OSSConfig | Object | OSS 实例配置文件 |

Function

• .addFile(file)

  addFile method is used to add single upload file

  parameters:

  • file [Required] {HTMLInputFileElement}

  return

  • file {Object} File Type Object

  const file = e.target.files[0];
  
  await Upload.addFile(file);

• .addFileToList(file)

  addFileToList method is used to add file to upload queue list.

  parameters:

  • file [Required] {HTMLInputFileElement}

  const files = e.target.files;
  
  for (const file of Object.values(files)) {
      await Upload.addFileToList(file);
  }

• .updateFileStatus(id, status, opts)

  updateFileStatus method is used to update file status.

  parameters:

  • id [Required] {String}
  • status: [Required] {Object} File Type Object
  • opts: [Optional] {Object}
    • isSingleFile {Boolean} [default: false] update upload file status with single check

  Upload.updateFileStatus(file.id, {
      isUploading: true,
      isWaitingUpload: false,
      isPaused: false,
      isCancel: false,
      isComputedMD5: false,
      isUploaded: false,
      isError: false,
      ...status,
  });

• .removeFileFromList(file)

  removeFile method is used to remove file from upload file list.

  parameters:

  • file [Required] {Object} File Type Object

  Upload.removeFile(file);

• .pauseUploadFile(file)

  pauseFile method is used to pause file upload in file list with multipartupload.

  parameters:

  • file [Required] {Object} File Type Object

  Upload.pauseUploadFile(file);

• .cancelUploadFile(file)

  cancelUploadFile method is used to cancel file upload in file list with multipartupload.

  parameters:

  • file [Required] {Object} File Type Object

  Upload.cancelUploadFile(file);

• .multipartUpload({config, file, type, uploadOptions, onUploadError, onUploadProgress, onUploadComplete, onUploadCancel, onUploadPause})

  multipartUpload method is used to upload file with large size split to part to AliOSS.

  parameters:

  • config [Required] {Object} AliOSS Config Object
  • file [Required] {Object} File Type Object
  • type [Required] {String} [default: 'upload'] (upload | resume)
  • uploadOptions [Optional] {Object} AliOSS Upload Options Object
  • onUploadError( { error } ) [Optional] {Function}
    • error: {Error}
  • onUploadProgress( { file, checkpoint, res } ) [Optional] {Function}
    • file: {Object}
    • checkpoint: {Object}
    • res: {Object}
  • onUploadComplete({file}) [Optional] {Function}
    • file: {Object}
  • onUploadCancel( { file } ) [Optional] {Function}
    • file: {Object}
  • onUploadPause( { file } ) [Optional] {Function}
    • file: {Object}

  const config = {
    region: 'oss-cn-hangzhou',
    accessKeyId: 'your accessKeyId',
    accessKeySecret: 'your accessKeySecret',
    bucket: 'your bucket',
    stsToken: 'your stsToken',
    endpoint: 'your endpoint',
  };
  
  const uploadOptions = {
    parallel: 5,
    partSize: 1024 * 1024 * 2,
    ...
  };
  
  await Upload.multipartUpload(
    config,
    file,
    onUploadError(err) {
      if (err.code === 'ConnectionTimeoutError') {
        console.log('Woops,Woops ,timeout error!!!');
        // do operation
      }
    },
    onUploadProgress({ file, res }) {
      // do operation
    },
    onUploadCancel({file}) {
      // do operation
    },
    onUploadComplete() {
      // do operation
    },
    onUploadPause({file}){
      // do operation
    }
  )

• .resumeMultipartUploadFile({ file, onUploadProgress, onUploadError, onUploadComplete, onUploadCancel })

  resumeMultipartUploadFile method is used to resume file upload.

  parameters:

  • file [Required] {Object}
  • onUploadError( { error } ) [Optional] {Function}
    • error: {Error}
  • onUploadProgress( { file, checkpoint, res } ) [Optional] {Function}
    • file: {Object}
    • checkpoint: {Object}
    • res: {Object}
  • onUploadComplete({ file }) [Optional] {Function}
    • file: {Object}
  • onUploadCancel( { file } ) [Optional] {Function}
    • file: {Object}

  await Upload.resumeMultipartUploadFile({
      file,
      onUploadError(err) {
          if (err.code === 'ConnectionTimeoutError') {
              console.log('Woops,Woops ,timeout error!!!');
              // do operation
          }
      },
      onUploadProgress({ file, res }) {
          // do operation
      },
      onUploadCancel({ file }) {
          // do operation
      },
      onUploadComplete() {
          // do operation
      },
  });

• .upload

  upload method is used to upload file simply to AliOSS. (not support resume upload and other status like upload percent) reference

  parameters:

  • file [Required] {Object}

  • config [Required] {Object}

  • onUploadError( { error } ) [Optional] {Function}

    • error: {Error}

  • onUploadComplete({ file }) [Optional] {Function}

    • res {Object}
      • name: {String}
      • res: {Object}
        • status {Number} response status
        • headers {Object} response headers
        • size {Number} response size
        • rt {Number} request total use time (ms)
      • url: {String}

  await Upload.upload(
      file,
      onUploadError(err) {
          if (err.code === 'ConnectionTimeoutError') {
              console.log('Woops,Woops ,timeout error!!!');
              // do operation
          }
      },
      onUploadComplete(res) {
          // do operation
      },
  );