AWOS-JS: Wrapper For Aliyun OSS And Amazon S3

awos for golang: https://github.com/shimohq/awos

feat

• same usage and methods for aws & oss, pretty convenient!
• add retry strategy
• avoid 404 status code:
  • get(key: string, metaKeys?: string[]): Promise<IGetObjectResponse | null> will return null when object not exist
  • head(key: string): Promise<Map<string, string> | null> will null when object not exist

installing

npm i awos-js --save

how to use

1// for typescript
2import AWOS from 'awos-js'
3
4// for js
5const AWOS = require('awos-js')

for Aliyun OSS

1import { build } from 'awos-js'
2
3// for v3.*.*
4const client = build({
5  storageType: 'oss',
6  accessKeyID: "xxx",
7  accessKeySecret: "xxx",
8  bucket: "my_bucket",
9  endpoint: 'endpoint',
10})
11
12// for v2.*.*
13const client = new AWOS.Client({
14  type: 'oss',
15  ossOptions: {
16    accessKeyId: 'accessKeyId',
17    accessKeySecret: 'accessKeySecret',
18    bucket: 'bucket',
19    endpoint: 'endpoint',
20  }
21})

for AWS-S3 / MINIO

1import { build } from 'awos-js'
2
3// for v3.*.*
4const client = build({
5  storageType: 'aws',
6  accessKeyID: "xxx",
7  accessKeySecret: "xxx",
8  // when use aws s3, endpoint is unnecessary and region must be set
9  endpoint: "https://xxxx.myminio.com",
10  bucket: "my_bucket",
11  // when use minio, S3ForcePathStyle must be set true
12  s3ForcePathStyle: true,
13})
14
15// For v2.*.*
16const client = new AWOS.Client({
17  storageType: 'aws',
18  awsOptions: {
19    accessKeyId: 'accessKeyId',
20    secretAccessKey: 'secretAccessKey',
21    bucket: 'bucket',
22    // when use minio, S3ForcePathStyle must be set true
23    // when use aws, endpoint is unnecessary and region must be set
24    region: "region",
25    endpoint: 'endpoint',
26    s3ForcePathStyle: true,
27  }
28})

the available operation：

1get(key: string, metaKeys?: string[]): Promise<IGetObjectResponse | null>;
2getAsBuffer(key: string, metaKeys: string[]): Promise<IGetBufferedObjectResponse | null>;
3put(key: string, data: string | Buffer, options?: IPutObjectOptions): Promise<void>;
4del(key: string): Promise<void>;
5delMulti(keys: string[]): Promise<string[]>; // return keys not deleted
6head(key: string, options?: IHeadOptions): Promise<Map<string, string> | null>;
7listObject(key: string, options?: IListObjectOptions): Promise<string[]>;
8listDetails(key: string, options?: IListObjectOptions): Promise<IListObjectOutput>;
9signatureUrl(key: string, options?: ISignatureUrlOptions): Promise<string | null>;
10copy(key: string, source: string, options?: ICopyObjectOptions): Promise<void>;

Change Log

• v3.0.0 / 2024-01-18

  • [Breaking] refactor configuration options ⚠️
  • support common prefix configuration

• v2.0.0 / 2020-06-18

  • Breaking
    • conbine parameters meta,contentType,headers of AWOS.put into options
  • add headers option support for put method

• v1.0.4 / 2019-12-26

  • support buffer in get and put operation

• v1.0.3 / 2019-03-28

  • put() support contentType params

• v1.0.2 / 2019-03-26

  • support signatureUrl() operation

• v1.0.1 / 2019-03-19

  • bug fix: oss listObject() should return [] when options.prefix not exist in the bucket; oss listObject() maxKeys not working