Skip to content

Commit 7d2bea0

Browse files
vladimyrvladimyr
committed
Refactor & generate docs from JSDoc
- backward compatible refactoring of public API to support passing optional `s3opts` param - adding JSDoc annotations used for generating documentation
1 parent 2757817 commit 7d2bea0

File tree

3 files changed

+242
-54
lines changed

3 files changed

+242
-54
lines changed

‎index.js‎

Lines changed: 125 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,32 @@ var debug = require('debug')('s3-blob-store');
55
var mime = require('mime-types');
66
var uploadStream = require('s3-stream-upload');
77

8+
/**
9+
* Create S3 blob store
10+
* @constructor
11+
* @param {Object} opts
12+
* @param {S3} opts.client S3 client
13+
* @param {String} opts.bucket bucket name
14+
*/
815
function S3BlobStore (opts) {
916
if (!(this instanceof S3BlobStore)) return new S3BlobStore(opts);
1017
opts = opts || {};
1118
if (!opts.client) throw Error('S3BlobStore client option required (aws-sdk AWS.S3 instance)');
1219
if (!opts.bucket) throw Error('S3BlobStore bucket option required');
13-
this.accessKey = opts.accessKey;
14-
this.secretKey = opts.secretKey;
1520
this.bucket = opts.bucket;
1621
this.s3 = opts.client;
1722
}
1823

19-
S3BlobStore.prototype.createReadStream = function (opts) {
24+
/**
25+
* Create read stream
26+
* @param {ReadStreamOptions|String} opts options or object key
27+
* @param {ReadParams} [s3opts] additional S3 options
28+
* @returns {ReadableStream}
29+
* readable stream of data for the file in your bucket whose key matches
30+
*/
31+
S3BlobStore.prototype.createReadStream = function (opts, s3opts) {
2032
if (typeof opts === 'string') opts = { key: opts };
21-
var config = { client: this.s3, params: this.downloadParams(opts) };
33+
var config = { client: this.s3, params: this._s3params(opts, s3opts) };
2234
if (opts.concurrency) config.concurrency = opts.concurrency;
2335
if (opts.chunkSize) config.chunkSize = opts.chunkSize;
2436
var stream = downloader(config);
@@ -28,40 +40,20 @@ S3BlobStore.prototype.createReadStream = function (opts) {
2840
return stream;
2941
};
3042

31-
S3BlobStore.prototype.uploadParams = function (opts) {
32-
opts = Object.assign({}, opts, {
33-
params: Object.assign({}, opts.params)
34-
});
35-
36-
var filename = opts.name || opts.filename;
37-
var key = opts.key || filename;
38-
var contentType = opts.contentType;
39-
40-
var params = opts.params;
41-
params.Bucket = params.Bucket || this.bucket;
42-
params.Key = params.Key || key;
43-
44-
if (!contentType) {
45-
contentType = filename ? mime.lookup(filename) : mime.lookup(opts.key);
46-
}
47-
if (contentType) params.ContentType = contentType;
48-
49-
return params;
50-
};
51-
52-
S3BlobStore.prototype.downloadParams = function (opts) {
53-
var params = this.uploadParams(opts);
54-
delete params.ContentType;
55-
return params;
56-
};
57-
43+
/**
44+
* Create write stream
45+
* @param {Options<WriteParams>|String} opts options or object key
46+
* @param {WriteParams} [s3opts] additional S3 options
47+
* @param {function(Error, { key: String })} done callback
48+
* @returns {WritableStream} writable stream that you can pipe data to
49+
*/
5850
S3BlobStore.prototype.createWriteStream = function (opts, s3opts, done) {
5951
if (typeof s3opts === 'function') {
6052
done = s3opts;
6153
s3opts = {};
6254
}
6355
if (typeof opts === 'string') opts = { key: opts };
64-
var params = this.uploadParams(opts);
56+
var params = this.uploadParams(opts, s3opts);
6557
var out = uploadStream(this.s3, params);
6658
out.on('error', function (err) {
6759
debug('got err %j', err);
@@ -74,18 +66,114 @@ S3BlobStore.prototype.createWriteStream = function (opts, s3opts, done) {
7466
return out;
7567
};
7668

77-
S3BlobStore.prototype.remove = function (opts, done) {
78-
var key = typeof opts === 'string' ? opts : opts.key;
79-
this.s3.deleteObject({ Bucket: this.bucket, Key: key }, done);
69+
/**
70+
* Remove object from store
71+
* @param {Options<RemoveParams>|String} opts options or object key
72+
* @param {RemoveParams} [s3opts] additional S3 options
73+
* @param {function(Error)} done callback
74+
*/
75+
S3BlobStore.prototype.remove = function (opts, s3opts, done) {
76+
if (typeof s3opts === 'function') {
77+
done = s3opts;
78+
s3opts = {};
79+
}
80+
if (typeof opts === 'string') opts = { key: opts };
81+
var params = this._s3params(opts, s3opts);
82+
this.s3.deleteObject(params, done);
8083
return this;
8184
};
8285

83-
S3BlobStore.prototype.exists = function (opts, done) {
86+
/**
87+
* Check if object exits
88+
* @param {Options<ExistsParams>|String} opts options or object key
89+
* @param {ExistsParams} [s3opts] additional S3 options
90+
* @param {function(Error, Boolean)} done callback
91+
*/
92+
S3BlobStore.prototype.exists = function (opts, s3opts, done) {
93+
if (typeof s3opts === 'function') {
94+
done = s3opts;
95+
s3opts = {};
96+
}
8497
if (typeof opts === 'string') opts = { key: opts };
85-
this.s3.headObject({ Bucket: this.bucket, Key: opts.key }, function (err, res) {
98+
var params = this._s3params(opts, s3opts);
99+
this.s3.headObject(params, function (err, _res) {
86100
if (err && err.statusCode === 404) return done(null, false);
87101
done(err, !err);
88102
});
89103
};
90104

105+
S3BlobStore.prototype.uploadParams = function (opts, s3opts) {
106+
opts = opts || {};
107+
var key = opts.key || opts.name || opts.filename;
108+
var params = this._s3params(opts, s3opts);
109+
var contentType = opts.contentType || mime.lookup(key);
110+
if (contentType) params.ContentType = contentType;
111+
return params;
112+
};
113+
114+
S3BlobStore.prototype._s3params = function (opts, s3opts) {
115+
opts = opts || {};
116+
opts.params = s3opts || opts.params || {};
117+
var key = opts.key || opts.name || opts.filename;
118+
var params = Object.assign({}, opts.params, {
119+
Bucket: opts.params.Bucket || this.bucket,
120+
Key: opts.params.Key || key
121+
});
122+
return params;
123+
};
124+
91125
module.exports = S3BlobStore;
126+
127+
/** @typedef {import('stream').Readable} ReadableStream */
128+
/** @typedef {import('stream').Writeable} WriteableStream */
129+
130+
/**
131+
* @typedef {Object} Options
132+
* @property {String} key object key
133+
* @property {String} [name] `key` alias
134+
* @property {String} [filename] `key` alias
135+
* @property {T} [params] additional S3 options
136+
* @template T
137+
*/
138+
139+
/**
140+
* [`Options`](#options) including `s3-stream-download` configuration
141+
* @typedef {Options<ReadParams> & S3StreamDownloaderOptions} ReadStreamOptions
142+
* @name ReadStreamOptions
143+
* @see https://github.com/jb55/s3-download-stream#api
144+
*/
145+
146+
/**
147+
* S3 client
148+
* @typedef {import('aws-sdk').S3} S3
149+
* @name S3
150+
* @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html
151+
*/
152+
153+
/**
154+
* S3 `getObject` params
155+
* @typedef {import('aws-sdk').S3.GetObjectRequest} ReadParams
156+
* @name ReadParams
157+
* @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getObject-property
158+
*/
159+
160+
/**
161+
* S3 `putObject` params
162+
* @typedef {import('aws-sdk').S3.PutObjectRequest} WriteParams
163+
* @name WriteParams
164+
* @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property
165+
*/
166+
167+
/**
168+
* S3 `deleteObject` params
169+
* @typedef {import('aws-sdk').S3.DeleteObjectRequest} RemoveParams
170+
* @name RemoveParams
171+
* @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#deleteObject-property
172+
*/
173+
174+
/**
175+
* S3 `headObject` params
176+
* @typedef {import('aws-sdk').S3.HeadObjectRequest} ExistsParams
177+
* @name ExistsParams
178+
* @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#headObject-property
179+
*/

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
"index.js"
1919
],
2020
"scripts": {
21+
"docs": "documentation readme index.js --section=API",
2122
"lint": "eslint . --ext .js",
2223
"test": "node test.js | tap-spec"
2324
},
@@ -30,6 +31,7 @@
3031
"devDependencies": {
3132
"abstract-blob-store": "^3.3.2",
3233
"aws-sdk": "^2.0.15",
34+
"documentation": "^12.1.4",
3335
"eslint": "^6.8.0",
3436
"eslint-config-semistandard": "^15.0.0",
3537
"eslint-config-standard": "^14.1.0",

‎readme.md‎

Lines changed: 115 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22

33
Amazon S3 [abstract-blob-store](http://npmrepo.com/abstract-blob-store)
44

5-
65
[![blob-store-compatible](https://raw.githubusercontent.com/maxogden/abstract-blob-store/master/badge.png)](https://github.com/maxogden/abstract-blob-store)
76

87
## Installation
@@ -43,33 +42,132 @@ store.exists({ key: 'somefile.txt' }, function (err, exists) {
4342

4443
## API
4544

46-
### `var s3 = require('s3-blob-store')(options)`
45+
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
46+
47+
#### Table of Contents
48+
49+
- [S3BlobStore](#s3blobstore)
50+
- [Parameters](#parameters)
51+
- [createReadStream](#createreadstream)
52+
- [Parameters](#parameters-1)
53+
- [createWriteStream](#createwritestream)
54+
- [Parameters](#parameters-2)
55+
- [remove](#remove)
56+
- [Parameters](#parameters-3)
57+
- [exists](#exists)
58+
- [Parameters](#parameters-4)
59+
- [ExistsParams](#existsparams)
60+
- [ReadStreamOptions](#readstreamoptions)
61+
- [S3](#s3)
62+
- [ReadParams](#readparams)
63+
- [WriteParams](#writeparams)
64+
- [RemoveParams](#removeparams)
65+
- [Options](#options)
66+
- [Properties](#properties)
67+
68+
### S3BlobStore
69+
70+
Create S3 blob store
71+
72+
#### Parameters
73+
74+
- `opts` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**
75+
- `opts.client` **[S3](#s3)** S3 client
76+
- `opts.bucket` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** bucket name
77+
78+
#### createReadStream
79+
80+
Create read stream
81+
82+
##### Parameters
83+
84+
- `opts` **([ReadStreamOptions](#readstreamoptions) \| [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options or object key
85+
- `s3opts` **[ReadParams](#readparams)?** additional S3 options
86+
87+
Returns **ReadableStream** readable stream of data for the file in your bucket whose key matches
88+
89+
#### createWriteStream
90+
91+
Create write stream
92+
93+
##### Parameters
94+
95+
- `opts` **([Options](#options)&lt;[WriteParams](#writeparams)> | [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options or object key
96+
- `s3opts` **[WriteParams](#writeparams)?** additional S3 options
97+
- `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
98+
99+
Returns **WritableStream** writable stream that you can pipe data to
100+
101+
#### remove
102+
103+
Remove object from store
104+
105+
##### Parameters
106+
107+
- `opts` **([Options](#options)&lt;[RemoveParams](#removeparams)> | [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options or object key
108+
- `s3opts` **[RemoveParams](#removeparams)?** additional S3 options
109+
- `done` **function ([Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error))** callback
110+
111+
#### exists
112+
113+
Check if object exits
114+
115+
##### Parameters
116+
117+
- `opts` **([Options](#options)&lt;[ExistsParams](#existsparams)> | [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options or object key
118+
- `s3opts` **[ExistsParams](#existsparams)?** additional S3 options
119+
- `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
120+
121+
###
122+
123+
###
124+
125+
### ExistsParams
126+
127+
- **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#headObject-property>**
128+
129+
S3 `headObject` params
130+
131+
### ReadStreamOptions
132+
133+
- **See: <https://github.com/jb55/s3-download-stream#api>**
134+
135+
[`Options`](#options) including `s3-stream-download` configuration
136+
137+
### S3
138+
139+
- **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html>**
140+
141+
S3 client
142+
143+
### ReadParams
144+
145+
- **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getObject-property>**
47146

48-
`options` must be an object that has the following properties:
147+
S3 `getObject` params
49148

50-
- `client`: an `require('aws-sdk').S3` instance
51-
- `bucket`: your bucket
149+
### WriteParams
52150

53-
### `s3.createWriteStream(opts, cb)`
151+
- **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property>**
54152

55-
returns a writable stream that you can pipe data to.
153+
S3 `putObject` params
56154

57-
`opts` should be an object that has options `key` (will be the filename in
58-
your bucket)
155+
### RemoveParams
59156

60-
`opts.params` additional [parameters](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property) to pass to S3
157+
- **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#deleteObject-property>**
61158

62-
`cb` will be called with `(err)` if there is was an error
159+
S3 `deleteObject` params
63160

64-
### `s3.createReadStream(opts)`
161+
### Options
65162

66-
`opts` should be `{ key: string (usually a hash or path + filename) }`
163+
Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
67164

68-
`opts.params` additional [parameters](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getObject-property) to pass to S3
69-
`opts.concurrency` optional parameter for [s3-download-stream](https://github.com/jb55/s3-download-stream)
70-
`opts.chunkSize` optional parameter for [s3-download-stream](https://github.com/jb55/s3-download-stream)
165+
#### Properties
71166

72-
returns a readable stream of data for the file in your bucket whose key matches
167+
- `key` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** object key
168+
- `name` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** `key` alias
169+
- `filename` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** `key` alias
170+
- `params` **T?** additional S3 options
73171

74172
## License
75173

0 commit comments

Comments
 (0)