Generate docs from JSDoc

vladimyr · jb55 · commit 3b6489e949a4 · 2020-02-17T10:17:22.000-08:00
- adding JSDoc annotations for generating documentation using
  documentation.js
- adding `store#remove` example to readme
diff --git a/index.js b/index.js
@@ -5,6 +5,13 @@ var debug = require('debug')('s3-blob-store');
 var mime = require('mime-types');
 var uploadStream = require('s3-stream-upload');
 
+/**
+ * Create S3 blob store
+ * @constructor
+ * @param {Object} opts
+ * @param {S3} opts.client S3 client
+ * @param {String} opts.bucket bucket name
+ */
 function S3BlobStore (opts) {
   if (!(this instanceof S3BlobStore)) return new S3BlobStore(opts);
   opts = opts || {};
@@ -16,6 +23,12 @@ function S3BlobStore (opts) {
   this.s3 = opts.client;
 }
 
+/**
+ * Create read stream
+ * @param {ReadStreamOptions|String} opts options or object key
+ * @returns {ReadableStream}
+ *   readable stream of data for the file in your bucket whose key matches
+ */
 S3BlobStore.prototype.createReadStream = function (opts) {
   if (typeof opts === 'string') opts = { key: opts };
   var config = { client: this.s3, params: this.downloadParams(opts) };
@@ -55,6 +68,12 @@ S3BlobStore.prototype.downloadParams = function (opts) {
   return params;
 };
 
+/**
+ * Create write stream
+ * @param {Options<WriteParams>|String} opts options or object key
+ * @param {function(Error, { key: String })} done callback
+ * @returns {WritableStream} writable stream that you can pipe data to
+ */
 S3BlobStore.prototype.createWriteStream = function (opts, s3opts, done) {
   if (typeof s3opts === 'function') {
     done = s3opts;
@@ -74,12 +93,22 @@ S3BlobStore.prototype.createWriteStream = function (opts, s3opts, done) {
   return out;
 };
 
+/**
+ * Remove object from store
+ * @param {{ key: String }|String} opts options containing object key or just key
+ * @param {function(Error)} done callback
+ */
 S3BlobStore.prototype.remove = function (opts, done) {
   var key = typeof opts === 'string' ? opts : opts.key;
   this.s3.deleteObject({ Bucket: this.bucket, Key: key }, done);
   return this;
 };
 
+/**
+ * Check if object exits
+ * @param {{ key: String }|String} opts options containing object key or just key
+ * @param {function(Error, Boolean)} done callback
+ */
 S3BlobStore.prototype.exists = function (opts, done) {
   if (typeof opts === 'string') opts = { key: opts };
   this.s3.headObject({ Bucket: this.bucket, Key: opts.key }, function (err, res) {
@@ -89,3 +118,43 @@ S3BlobStore.prototype.exists = function (opts, done) {
 };
 
 module.exports = S3BlobStore;
+
+/** @typedef {import('stream').Readable} ReadableStream */
+/** @typedef {import('stream').Writeable} WriteableStream */
+
+/**
+ * @typedef {Object} Options
+ * @property {String} key object key
+ * @property {String} [name] `key` alias
+ * @property {String} [filename] `key` alias
+ * @property {S3Params} [params] additional S3 options
+ * @template S3Params
+ */
+
+/**
+ * [`Options`](#options) including `s3-stream-download` configuration
+ * @typedef {Options<ReadParams> & S3StreamDownloaderOptions} ReadStreamOptions
+ * @name ReadStreamOptions
+ * @see https://github.com/jb55/s3-download-stream#api
+ */
+
+/**
+ * S3 client
+ * @typedef {import('aws-sdk').S3} S3
+ * @name S3
+ * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html
+ */
+
+/**
+ * S3 `getObject` params
+ * @typedef {import('aws-sdk').S3.GetObjectRequest} ReadParams
+ * @name ReadParams
+ * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getObject-property
+ */
+
+/**
+ * S3 `putObject` params
+ * @typedef {import('aws-sdk').S3.PutObjectRequest} WriteParams
+ * @name WriteParams
+ * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property
+ */
diff --git a/package.json b/package.json
@@ -18,6 +18,7 @@
     "index.js"
   ],
   "scripts": {
+    "docs": "documentation readme index.js --section=API",
     "lint": "eslint . --ext .js",
     "test": "node test.js | tap-spec"
   },
@@ -30,6 +31,7 @@
   "devDependencies": {
     "abstract-blob-store": "^3.3.2",
     "aws-sdk": "^2.0.15",
+    "documentation": "^12.1.4",
     "eslint": "^6.8.0",
     "eslint-config-semistandard": "^15.0.0",
     "eslint-config-standard": "^14.1.0",
diff --git a/readme.md b/readme.md
@@ -2,7 +2,6 @@
 
 Amazon S3 [abstract-blob-store](http://npmrepo.com/abstract-blob-store)
 
-
 [![blob-store-compatible](https://raw.githubusercontent.com/maxogden/abstract-blob-store/master/badge.png)](https://github.com/maxogden/abstract-blob-store)
 
 ## Installation
@@ -35,6 +34,11 @@ fs.createReadStream('/tmp/somefile.txt')
 store.createReadStream({ key: 'somefile.txt' })
   .pipe(fs.createWriteStream('/tmp/somefile.txt'));
 
+// remove
+store.remove({ key: 'somefile.txt' }, function (err) {
+   // ...
+});
+
 // exists
 store.exists({ key: 'somefile.txt' }, function (err, exists) {
   // ...
@@ -43,33 +47,115 @@ store.exists({ key: 'somefile.txt' }, function (err, exists) {
 
 ## API
 
-### `var s3 = require('s3-blob-store')(options)`
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+#### Table of Contents
+
+-   [S3BlobStore](#s3blobstore)
+    -   [Parameters](#parameters)
+    -   [createReadStream](#createreadstream)
+        -   [Parameters](#parameters-1)
+    -   [createWriteStream](#createwritestream)
+        -   [Parameters](#parameters-2)
+    -   [remove](#remove)
+        -   [Parameters](#parameters-3)
+    -   [exists](#exists)
+        -   [Parameters](#parameters-4)
+-   [WriteParams](#writeparams)
+-   [Options](#options)
+    -   [Properties](#properties)
+-   [ReadStreamOptions](#readstreamoptions)
+-   [S3](#s3)
+-   [ReadParams](#readparams)
+
+### S3BlobStore
+
+Create S3 blob store
+
+#### Parameters
+
+-   `opts` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
+    -   `opts.client` **[S3](#s3)** S3 client
+    -   `opts.bucket` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** bucket name
+
+#### createReadStream
+
+Create read stream
+
+##### Parameters
+
+-   `opts` **([ReadStreamOptions](#readstreamoptions) \| [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options or object key
+
+Returns **ReadableStream** readable stream of data for the file in your bucket whose key matches
+
+#### createWriteStream
+
+Create write stream
+
+##### Parameters
+
+-   `opts` **([Options](#options)&lt;[WriteParams](#writeparams)> | [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** options or object key
+-   `s3opts`  
+-   `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
+
+Returns **WritableStream** writable stream that you can pipe data to
+
+#### remove
+
+Remove object from store
+
+##### Parameters
+
+-   `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
+-   `done` **function ([Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error))** callback
+
+#### exists
+
+Check if object exits
+
+##### Parameters
+
+-   `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
+-   `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
+
+### 
+
+### WriteParams
+
+-   **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property>**
+
+S3 `putObject` params
+
+### Options
+
+Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
+
+#### Properties
 
-`options` must be an object that has the following properties:
+-   `key` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** object key
+-   `name` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** `key` alias
+-   `filename` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** `key` alias
+-   `params` **S3Params?** additional S3 options
 
-- `client`: an `require('aws-sdk').S3` instance
-- `bucket`: your bucket
+### ReadStreamOptions
 
-### `s3.createWriteStream(opts, cb)`
+-   **See: <https://github.com/jb55/s3-download-stream#api>**
 
-returns a writable stream that you can pipe data to.
+[`Options`](#options) including `s3-stream-download` configuration
 
-`opts` should be an object that has options `key` (will be the filename in
-your bucket)
+### S3
 
-`opts.params` additional [parameters](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property) to pass to S3
+-   **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html>**
 
-`cb` will be called with `(err)` if there is was an error
+S3 client
 
-### `s3.createReadStream(opts)`
+### ReadParams
 
-`opts` should be `{ key: string (usually a hash or path + filename) }`
+-   **See: <https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getObject-property>**
 
-`opts.params` additional [parameters](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getObject-property) to pass to S3
-`opts.concurrency` optional parameter for [s3-download-stream](https://github.com/jb55/s3-download-stream)
-`opts.chunkSize` optional parameter for [s3-download-stream](https://github.com/jb55/s3-download-stream)
+S3 `getObject` params
 
-returns a readable stream of data for the file in your bucket whose key matches
+### 
 
 ## License
 
