Skip to content

Commit 08c3d28

Browse files
vladimyrvladimyr
committed
Refactor internals & update API docs
- extending all public API methods to support passing additional s3 parameters either through `opts` argument or dedicated `s3opts` argument - introducing `store#_s3paramsi(opts, s3opts)` helper used for extracting additional s3 parameters - deprecating undocumented `uploadParams` and `downloadParams` methods to prepare for new major release - updating API documentation
1 parent a1e52be commit 08c3d28

File tree

2 files changed

+101
-59
lines changed

2 files changed

+101
-59
lines changed

‎index.js

Lines changed: 64 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ var downloader = require('s3-download-stream');
44
var debug = require('debug')('s3-blob-store');
55
var mime = require('mime-types');
66
var uploadStream = require('s3-stream-upload');
7+
var util = require('util');
78

89
/**
910
* Create S3 blob store
@@ -17,21 +18,20 @@ function S3BlobStore (opts) {
1718
opts = opts || {};
1819
if (!opts.client) throw Error('S3BlobStore client option required (aws-sdk AWS.S3 instance)');
1920
if (!opts.bucket) throw Error('S3BlobStore bucket option required');
20-
this.accessKey = opts.accessKey;
21-
this.secretKey = opts.secretKey;
2221
this.bucket = opts.bucket;
2322
this.s3 = opts.client;
2423
}
2524

2625
/**
2726
* Create read stream
2827
* @param {ReadStreamOptions|String} opts options or object key
28+
* @param {ReadParams} [s3opts] additional S3 options
2929
* @returns {ReadableStream}
3030
* readable stream of data for the file in your bucket whose key matches
3131
*/
32-
S3BlobStore.prototype.createReadStream = function (opts) {
32+
S3BlobStore.prototype.createReadStream = function (opts, s3opts) {
3333
if (typeof opts === 'string') opts = { key: opts };
34-
var config = { client: this.s3, params: this.downloadParams(opts) };
34+
var config = { client: this.s3, params: this._s3params(opts, s3opts) };
3535
if (opts.concurrency) config.concurrency = opts.concurrency;
3636
if (opts.chunkSize) config.chunkSize = opts.chunkSize;
3737
var stream = downloader(config);
@@ -41,36 +41,10 @@ S3BlobStore.prototype.createReadStream = function (opts) {
4141
return stream;
4242
};
4343

44-
S3BlobStore.prototype.uploadParams = function (opts) {
45-
opts = Object.assign({}, opts, {
46-
params: Object.assign({}, opts.params)
47-
});
48-
49-
var filename = opts.name || opts.filename;
50-
var key = opts.key || filename;
51-
var contentType = opts.contentType;
52-
53-
var params = opts.params;
54-
params.Bucket = params.Bucket || this.bucket;
55-
params.Key = params.Key || key;
56-
57-
if (!contentType) {
58-
contentType = filename ? mime.lookup(filename) : mime.lookup(opts.key);
59-
}
60-
if (contentType) params.ContentType = contentType;
61-
62-
return params;
63-
};
64-
65-
S3BlobStore.prototype.downloadParams = function (opts) {
66-
var params = this.uploadParams(opts);
67-
delete params.ContentType;
68-
return params;
69-
};
70-
7144
/**
7245
* Create write stream
7346
* @param {Options<WriteParams>|String} opts options or object key
47+
* @param {WriteParams} [s3opts] additional S3 options
7448
* @param {function(Error, { key: String })} done callback
7549
* @returns {WritableStream} writable stream that you can pipe data to
7650
*/
@@ -80,7 +54,9 @@ S3BlobStore.prototype.createWriteStream = function (opts, s3opts, done) {
8054
s3opts = {};
8155
}
8256
if (typeof opts === 'string') opts = { key: opts };
83-
var params = this.uploadParams(opts);
57+
var params = this._s3params(opts, s3opts);
58+
var contentType = (opts && opts.contentType) || mime.lookup(params.Key);
59+
if (contentType) params.ContentType = contentType;
8460
var out = uploadStream(this.s3, params);
8561
out.on('error', function (err) {
8662
debug('got err %j', err);
@@ -95,28 +71,63 @@ S3BlobStore.prototype.createWriteStream = function (opts, s3opts, done) {
9571

9672
/**
9773
* Remove object from store
98-
* @param {{ key: String }|String} opts options containing object key or just key
74+
* @param {Options<RemoveParams>|String} opts options or object key
75+
* @param {RemoveParams} [s3opts] additional S3 options
9976
* @param {function(Error)} done callback
10077
*/
101-
S3BlobStore.prototype.remove = function (opts, done) {
102-
var key = typeof opts === 'string' ? opts : opts.key;
103-
this.s3.deleteObject({ Bucket: this.bucket, Key: key }, done);
78+
S3BlobStore.prototype.remove = function (opts, s3opts, done) {
79+
if (typeof s3opts === 'function') {
80+
done = s3opts;
81+
s3opts = {};
82+
}
83+
if (typeof opts === 'string') opts = { key: opts };
84+
var params = this._s3params(opts, s3opts);
85+
this.s3.deleteObject(params, done);
10486
return this;
10587
};
10688

10789
/**
10890
* Check if object exits
109-
* @param {{ key: String }|String} opts options containing object key or just key
91+
* @param {Options<ExistsParams>|String} opts options or object key
92+
* @param {ExistsParams} [s3opts] additional S3 options
11093
* @param {function(Error, Boolean)} done callback
11194
*/
112-
S3BlobStore.prototype.exists = function (opts, done) {
95+
S3BlobStore.prototype.exists = function (opts, s3opts, done) {
96+
if (typeof s3opts === 'function') {
97+
done = s3opts;
98+
s3opts = {};
99+
}
113100
if (typeof opts === 'string') opts = { key: opts };
114-
this.s3.headObject({ Bucket: this.bucket, Key: opts.key }, function (err, res) {
101+
var params = this._s3params(opts, s3opts);
102+
this.s3.headObject(params, function (err, _res) {
115103
if (err && err.statusCode === 404) return done(null, false);
116104
done(err, !err);
117105
});
118106
};
119107

108+
S3BlobStore.prototype._s3params = function (opts, s3opts) {
109+
opts = opts || {};
110+
opts.params = s3opts || opts.params || {};
111+
var key = opts.key || opts.name || opts.filename;
112+
var params = Object.assign({}, opts.params, {
113+
Bucket: opts.params.Bucket || this.bucket,
114+
Key: opts.params.Key || key
115+
});
116+
return params;
117+
};
118+
119+
S3BlobStore.prototype.uploadParams = util.deprecate(function (opts) {
120+
opts = opts || {};
121+
var params = this._s3params(opts);
122+
var contentType = opts.contentType || mime.lookup(params.Key);
123+
if (contentType) params.ContentType = contentType;
124+
return params;
125+
}, 'S3BlobStore#uploadParams(opts) is deprecated and will be removed in upcoming v5!');
126+
127+
S3BlobStore.prototype.downloadParams = util.deprecate(function (opts) {
128+
return this._s3params(opts);
129+
}, 'S3BlobStore#downloadParams(opts) is deprecated and will be removed in upcoming v5!');
130+
120131
module.exports = S3BlobStore;
121132

122133
/** @typedef {import('stream').Readable} ReadableStream */
@@ -158,3 +169,17 @@ module.exports = S3BlobStore;
158169
* @name WriteParams
159170
* @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property
160171
*/
172+
173+
/**
174+
* S3 `deleteObject` params
175+
* @typedef {import('aws-sdk').S3.DeleteObjectRequest} RemoveParams
176+
* @name RemoveParams
177+
* @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#deleteObject-property
178+
*/
179+
180+
/**
181+
* S3 `headObject` params
182+
* @typedef {import('aws-sdk').S3.HeadObjectRequest} ExistsParams
183+
* @name ExistsParams
184+
* @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#headObject-property
185+
*/

‎readme.md

Lines changed: 37 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -61,12 +61,14 @@ store.exists({ key: 'somefile.txt' }, function (err, exists) {
6161
- [Parameters](#parameters-3)
6262
- [exists](#exists)
6363
- [Parameters](#parameters-4)
64-
- [WriteParams](#writeparams)
65-
- [Options](#options)
66-
- [Properties](#properties)
64+
- [ExistsParams](#existsparams)
6765
- [ReadStreamOptions](#readstreamoptions)
6866
- [S3](#s3)
6967
- [ReadParams](#readparams)
68+
- [WriteParams](#writeparams)
69+
- [RemoveParams](#removeparams)
70+
- [Options](#options)
71+
- [Properties](#properties)
7072

7173
### S3BlobStore
7274

@@ -85,6 +87,7 @@ Create read stream
8587
##### Parameters
8688

8789
- `opts` **([ReadStreamOptions](#readstreamoptions) \| [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options or object key
90+
- `s3opts` **[ReadParams](#readparams)?** additional S3 options
8891

8992
Returns **ReadableStream** readable stream of data for the file in your bucket whose key matches
9093

@@ -95,7 +98,7 @@ Create write stream
9598
##### Parameters
9699

97100
- `opts` **([Options](#options)&lt;[WriteParams](#writeparams)> | [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options or object key
98-
- `s3opts`
101+
- `s3opts` **[WriteParams](#writeparams)?** additional S3 options
99102
- `done` **function ([Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error), {key: [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)})** callback
100103

101104
Returns **WritableStream** writable stream that you can pipe data to
@@ -106,7 +109,8 @@ Remove object from store
106109

107110
##### Parameters
108111

109-
- `opts` **({key: [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)} | [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options containing object key or just key
112+
- `opts` **([Options](#options)&lt;[RemoveParams](#removeparams)> | [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options or object key
113+
- `s3opts` **[RemoveParams](#removeparams)?** additional S3 options
110114
- `done` **function ([Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error))** callback
111115

112116
#### exists
@@ -115,27 +119,19 @@ Check if object exits
115119

116120
##### Parameters
117121

118-
- `opts` **({key: [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)} | [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options containing object key or just key
122+
- `opts` **([Options](#options)&lt;[ExistsParams](#existsparams)> | [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options or object key
123+
- `s3opts` **[ExistsParams](#existsparams)?** additional S3 options
119124
- `done` **function ([Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error), [Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean))** callback
120125

121126
###
122127

123-
### WriteParams
124-
125-
- **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property>**
126-
127-
S3 `putObject` params
128-
129-
### Options
128+
###
130129

131-
Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
130+
### ExistsParams
132131

133-
#### Properties
132+
- **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#headObject-property>**
134133

135-
- `key` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** object key
136-
- `name` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** `key` alias
137-
- `filename` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** `key` alias
138-
- `params` **S3Params?** additional S3 options
134+
S3 `headObject` params
139135

140136
### ReadStreamOptions
141137

@@ -155,4 +151,25 @@ S3 client
155151

156152
S3 `getObject` params
157153

158-
###
154+
### WriteParams
155+
156+
- **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property>**
157+
158+
S3 `putObject` params
159+
160+
### RemoveParams
161+
162+
- **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#deleteObject-property>**
163+
164+
S3 `deleteObject` params
165+
166+
### Options
167+
168+
Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
169+
170+
#### Properties
171+
172+
- `key` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** object key
173+
- `name` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** `key` alias
174+
- `filename` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** `key` alias
175+
- `params` **S3Params?** additional S3 options

0 commit comments

Comments
 (0)