Ali-oss-extra NPM

Install

npm install -S ali-oss-extra

yarn add ali-oss-extra

Extra methods

Usage

Use as a drop-in replacement of ali-oss:

import OSS from 'ali-oss-extra'

const store = new OSS({
  accessKeyId: 'your access key',
  accessKeySecret: 'your access secret',
  bucket: 'your bucket name',
  region: 'region of your bucket'
})

All methods from ali-oss are available. But every method returns a promise, which could be used in async/await:

// List top 10 buckets
const result = await store.listBuckets({ 'max-keys': 10 })

Return:

{ buckets:
   [ { name: 'my-bucket',
       region: 'oss-us-west-1',
       creationDate: '2016-05-29T12:13:03.000Z' },
     { name: 'my-data',
       region: 'oss-cn-shenzhen',
       creationDate: '2016-05-14T08:02:46.000Z' },
     { name: 'my-data-bj-dev',
       region: 'oss-cn-beijing',
       creationDate: '2016-05-24T15:17:53.000Z' },
     { name: 'my-data-dev2',
       region: 'oss-cn-shenzhen',
       creationDate: '2016-05-14T08:02:19.000Z' },
   ...

listDir (prefix, projection = [])

List all files under a prefix. Not limited to 1000 files.

// List all files in a prefix
const result = await store.listDir('user_data')

Return:

[ { name: 'user_data/web/f44dc4cd8976c254362c251a5bc3cfc3.txt',
    url: 'http://my-bucket.oss-us-west-1.aliyuncs.com/user_data/web/f44dc4cd8976c254362c251a5bc3cfc3.txt',
    lastModified: '2016-05-29T12:14:15.000Z',
    etag: '"A81DD21E0322B643AB6F6782B5C96012"',
    type: 'Normal',
    size: 443,
    storageClass: 'Standard',
    owner: { id: '1400663040702136', displayName: '1400663040702136' } },
  { name: 'user_data/web/f460cb792b6c7fd5e21a2f311faaa3b0.ab.png',
    url: 'http://my-bucket.oss-us-west-1.aliyuncs.com/user_data/web/f460cb792b6c7fd5e21a2f311faaa3b0.ab.png',
    lastModified: '2016-05-29T12:14:16.000Z',
    etag: '"26D3700FCF7421B723A7AE2F794DC361"',
    type: 'Normal',
    size: 230547,
    storageClass: 'Standard',
    owner: { id: '1400663040702136', displayName: '1400663040702136' } },
...]

syncDir (directory, prefix, options)

Options

remove - Remove file on OSS if it is not appeared in local directory
ignoreList - Array of directories to be ignored (relative path without trailing slash, e.g. 'editor', 'cp', 'sfm' )
defaultHeader - Default header for all files
headersMap - Custom headers (which override default header) for specific files
retryLimit - Number of times to retry after timeout
thread - Number of concurrent threads to upload small files
timeout - Timeout (in milliseconds)
ulimit - Maximum number of open files
verbose - Print debug log

Synchronize a local directory to OSS recursively. Support uploading directory with large number of small or big files.

If a file of the same name exists and its last modified time is not older than the local one, then it will not be uploaded.

const result = await store.syncDir('./localDir', 'a_dir')

Return:

{
  "put": [
    {
      "name": "a_dir/fileA1.txt",
      "url": "http://my-bucket.oss-us-west-1.aliyuncs.com/a_dir/fileA1.txt",
      "res": {
        "status": 200,
        "statusCode": 200,
        "headers": {
          "server": "AliyunOSS",
          "date": "Mon, 30 May 2016 08:10:37 GMT",
          "content-length": "0",
          "connection": "keep-alive",
          "x-oss-request-id": "574BF57D16FDA15402D9D84C",
          "x-oss-bucket-storage-type": "standard",
          "etag": "\"7EED2CD60D1E86FE16B0F7AB89C89D0E\"",
          "x-oss-server-time": "4"
        },
        "size": 0,
        "aborted": false,
        "rt": 176,
        "keepAliveSocket": true,
        "data": {
          "type": "Buffer",
          "data": []
        },
        "requestUrls": [
          "http://my-bucket.oss-us-west-1.aliyuncs.com/a_dir/fileA1.txt"
        ]
      }
    },
    ...
  ],
  "delete": []
}

syncDirDown (prefix, directory, options)

Options

remove - Remove any local file if it does not exist in the OSS
thread - Number of concurrent threads to download files
timeout - Timeout (in milliseconds)
ulimit - Maximum number of open files
verbose - Print debug log

Synchronize from a OSS prefix to a local directory recursively.

If a local file of the same name exists and its last modified time is older than the OSS one, then it will not be downloaded.

const result = await store.syncDirDown('a_dir', './localDir')

Return:

{
  "get": [
    'localDir/DJI_0081.JPG',
    'localDir/DJI_0082.JPG',
    'localDir/DJI_0083.JPG',
    'localDir/DJI_0084.JPG',
    'localDir/DJI_0085.JPG',
    'localDir/DJI_0086.JPG',
    'localDir/DJI_0087.JPG',
    'localDir/DJI_0088.JPG',
    ...
  ],
  "delete": []
}

deleteDir (prefix, options)

Options

retryLimit - Number of times to retry after timeout

Delete a directory recursively. Not limited to 1000 files.

const result = await store.deleteDir('a_dir')

Returns:

[
  'a_dir/b/c/d/fileD1.txt',
  'a_dir/b/c/d/fileD2.txt',
  'a_dir/b/c/d/fileD3.txt',
  'a_dir/b/c/fileC1.txt',
  'a_dir/b/c/fileC2.txt',
  'a_dir/fileA1.txt',
  'a_dir/fileA2.txt',
  ...
]

putList (fileList, options)

fileList

Array of object of the following:
src - Local path of file
dst - OSS path
size - File size (in byte) of file

Options

thread - Number of concurrent threads to upload small files
defaultHeader - Default header for all files
headersMap - Custom headers (which override default header) for specific files
bigFile - Thresold (in byte) of determining wheather a file is big or small
partSize - Size (in byte) of each multipart
timeout - Timeout (in milliseconds)
ulimit - Maximum number of open files

Upload a list of files to OSS. Not limited to 1000 files.

const result = await store.putList([
  {
    src: './a/data1.txt',
    dst: 'a/data1.txt',
    size: 100
  },
  {
    src: './a/data2.txt',
    dst: 'a/data2.txt',
    size: 200
  }
], { thread: 10 })

Returns:

[
  {
    "name": "a/data1.txt",
    "url": "http://my-bucket.oss-us-west-1.aliyuncs.com/a/data1.txt",
    "res": {
      "status": 200,
      "statusCode": 200,
      "headers": {
        "server": "AliyunOSS",
        "date": "Tue, 31 May 2016 09:50:22 GMT",
        "content-length": "0",
        "connection": "keep-alive",
        "x-oss-request-id": "574D5E5E7F5DBA946A0F5CF9",
        "x-oss-bucket-storage-type": "standard",
        "etag": "\"654345A9C87BE1E0AE1ACA461609CD3A\"",
        "x-oss-server-time": "27"
      },
      "size": 0,
      "aborted": false,
      "rt": 198,
      "keepAliveSocket": true,
      "data": {
        "type": "Buffer",
        "data": []
      },
      "requestUrls": [
        "http://my-bucket.oss-us-west-1.aliyuncs.com/a/data1.txt"
      ]
    }
  },
  ...
]

deleteList (fileList, options)

fileList

Array of object of the following:
name - OSS path

Options

thread - Number of concurrent threads to delete

Delete a list of files in OSS. Not limited to 1000 files.

const result = await store.deleteList([
  {
    name: 'a/data1.txt'
  },
  {
    name: 'a/data2.txt'
  }
], { thread: 25 })

Returns:

[
  {
    "res": {
      "status": 204,
      "statusCode": 204,
      "headers": {
        "server": "AliyunOSS",
        "date": "Tue, 31 May 2016 09:58:28 GMT",
        "content-length": "0",
        "connection": "keep-alive",
        "x-oss-request-id": "574D60440DA824296F114761",
        "x-oss-bucket-storage-type": "standard",
        "x-oss-server-time": "2"
      },
      "size": 0,
      "aborted": false,
      "rt": 162,
      "keepAliveSocket": true,
      "data": {
        "type": "Buffer",
        "data": []
      },
      "requestUrls": [
        "http://my-bucket.oss-us-west-1.aliyuncs.com/a/data1.txt"
      ]
    }
  },
  ...
]

setDownloadName (file, downloadName)

Set the attachment name in content-disposition header. Only support file smaller than 5GB.

const result = await store.setDownloadName('a_dir/abcdefg', 'data.txt')

Returns:

{ data:
   { etag: '"9D8606B3FB15EA4687402D4FD7C391B3-2"',
     lastModified: '2016-05-31T10:07:26.000Z' },
  res:
   { status: 200,
     statusCode: 200,
     headers:
      { server: 'AliyunOSS',
        date: 'Tue, 31 May 2016 10:07:26 GMT',
        'content-type': 'application/xml',
        'content-length': '186',
        connection: 'keep-alive',
        'x-oss-request-id': '574D625E0DA824296F11A15A',
        'x-oss-bucket-storage-type': 'standard',
        etag: '"9D8606B3FB15EA4687402D4FD7C391B3-2"',
        'x-oss-server-time': '5' },
     size: 186,
     aborted: false,
     rt: 176,
     keepAliveSocket: true,
     data: <Buffer ... >,
     requestUrls: [ 'http://my-bucket.oss-us-west-1.aliyuncs.com/a_dir/abcdefg' ] } }