native-promise-pool - npm Package Compare versions

Comparing version 0.0.1 to 1.0.0

HISTORY.md

 # History
 
-## v1.0.0 2015 October 25
-- Some feature
+## v1.0.0 2018 November 14
+- Initial stable release

LICENSE.md

@@ -0,2 +1,23 @@
+<!-- LICENSEFILE/ -->
 
-<!-- LICENSEFILE -->
+<h1>License</h1>
+
+Unless stated otherwise all works are:
+
+<ul><li>Copyright &copy; 2018+ Benjamin Lupton</li></ul>
+
+and licensed under:
+
+<ul><li><a href="http://spdx.org/licenses/MIT.html">MIT License</a></li></ul>
+
+<h2>MIT License</h2>
+
+<pre>
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+</pre>
+
+<!-- /LICENSEFILE -->

package.json

 {
   "name": "native-promise-pool",
-  "version": "0.0.1",
-  "description": "Create a pool of a specified concurrency that accepts promises",
+  "version": "1.0.0",
+  "description": "Create a pool of a specified concurrency that accepts functions that return promises",
   "homepage": "https://github.com/bevry/native-promise-pool",
@@ -50,3 +50,5 @@ "license": "MIT",
   ],
-  "contributors": [],
+  "contributors": [
+    "Benjamin Lupton (http://balupton.com)"
+  ],
   "bugs": {
@@ -60,3 +62,3 @@ "url": "https://github.com/bevry/native-promise-pool/issues"
   "engines": {
-    "node": ">=4"
+    "node": ">=6"
   },
@@ -68,11 +70,11 @@ "editions": [
       "entry": "index.js",
-      "syntaxes": [
+      "engines": {
+        "node": "6 || 8 || 10 || 11",
+        "browsers": false
+      },
+      "tags": [
         "javascript",
         "esnext",
         "require"
-      ],
-      "engines": {
-        "node": true,
-        "browsers": false
-      }
+      ]
     },
@@ -83,29 +85,33 @@ {
       "entry": "index.js",
-      "syntaxes": [
-        "javascript",
-        "require"
-      ],
       "engines": {
         "node": false,
         "browsers": "defaults"
-      }
+      },
+      "tags": [
+        "javascript",
+        "require"
+      ]
     }
   ],
-  "main": "index.js",
+  "main": "source/index.js",
   "browser": "edition-browsers/index.js",
-  "dependencies": {
-    "editions": "^2.0.2"
-  },
+  "dependencies": {},
   "devDependencies": {
+    "@babel/cli": "^7.1.5",
+    "@babel/core": "^7.1.6",
+    "@babel/preset-env": "^7.1.6",
     "assert-helpers": "^4.5.1",
+    "bluebird": "^3.5.3",
     "chalk": "^2.4.1",
-    "documentation": "^8.1.2",
     "eslint": "^5.9.0",
     "joe": "^2.0.2",
     "joe-reporter-console": "^2.0.2",
+    "jsdoc": "^3.5.5",
     "logger-clearable": "^1.0.0",
-    "projectz": "^1.4.0",
+    "minami": "^1.2.3",
+    "projectz": "^1.5.3",
     "surge": "^0.20.1",
     "valid-directory": "^1.0.0"
   },
+  "optionalDependencies": {},
   "scripts": {
@@ -117,3 +123,3 @@ "our:clean": "rm -Rf ./docs ./edition* ./es2015 ./es5 ./out",
     "our:meta": "npm run our:meta:docs && npm run our:meta:projectz",
-    "our:meta:docs": "documentation build -f html -o ./docs -g --shallow ./source/**.js",
+    "our:meta:docs": "rm -Rf ./docs && jsdoc --recurse --pedantic --access all --destination ./docs --package ./package.json --readme ./README.md --template ./node_modules/minami ./source && mv ./docs/$npm_package_name/$npm_package_version/* ./docs/ && rm -Rf ./docs/$npm_package_name/$npm_package_version",
     "our:meta:projectz": "projectz compile",
@@ -131,4 +137,4 @@ "our:release": "npm run our:release:prepare && npm run our:release:check-changelog && npm run our:release:check-dirty && npm run our:release:tag && npm run our:release:push",
     "our:verify:directory": "npx valid-directory",
-    "our:verify:eslint": "eslint --fix ./source",
-    "test": "node --harmony ./test.js --joe-reporter=console"
+    "our:verify:eslint": "eslint --fix ./source/**",
+    "test": "node --harmony ./source/test.js --joe-reporter=console"
   },
@@ -140,3 +146,3 @@ "babel": {
           [
-            "env",
+            "@babel/preset-env",
             {
@@ -143,0 +149,0 @@ "targets": {

README.md

@@ -1,18 +0,176 @@
-<!--TITLE -->
+<!-- TITLE/ -->
 
-<!--BADGES -->
+<h1>native-promise-pool</h1>
 
-<!--DESCRIPTION -->
+<!-- /TITLE -->
 
-<!--INSTALL -->
 
+<!-- BADGES/ -->
+
+<span class="badge-travisci"><a href="http://travis-ci.org/bevry/native-promise-pool" title="Check this project's build status on TravisCI"><img src="https://img.shields.io/travis/bevry/native-promise-pool/master.svg" alt="Travis CI Build Status" /></a></span>
+<span class="badge-npmversion"><a href="https://npmjs.org/package/native-promise-pool" title="View this project on NPM"><img src="https://img.shields.io/npm/v/native-promise-pool.svg" alt="NPM version" /></a></span>
+<span class="badge-npmdownloads"><a href="https://npmjs.org/package/native-promise-pool" title="View this project on NPM"><img src="https://img.shields.io/npm/dm/native-promise-pool.svg" alt="NPM downloads" /></a></span>
+<span class="badge-daviddm"><a href="https://david-dm.org/bevry/native-promise-pool" title="View the status of this project's dependencies on DavidDM"><img src="https://img.shields.io/david/bevry/native-promise-pool.svg" alt="Dependency Status" /></a></span>
+<span class="badge-daviddmdev"><a href="https://david-dm.org/bevry/native-promise-pool#info=devDependencies" title="View the status of this project's development dependencies on DavidDM"><img src="https://img.shields.io/david/dev/bevry/native-promise-pool.svg" alt="Dev Dependency Status" /></a></span>
+<br class="badge-separator" />
+<span class="badge-patreon"><a href="https://patreon.com/bevry" title="Donate to this project using Patreon"><img src="https://img.shields.io/badge/patreon-donate-yellow.svg" alt="Patreon donate button" /></a></span>
+<span class="badge-flattr"><a href="https://flattr.com/profile/balupton" title="Donate to this project using Flattr"><img src="https://img.shields.io/badge/flattr-donate-yellow.svg" alt="Flattr donate button" /></a></span>
+<span class="badge-liberapay"><a href="https://liberapay.com/bevry" title="Donate to this project using Liberapay"><img src="https://img.shields.io/badge/liberapay-donate-yellow.svg" alt="Liberapay donate button" /></a></span>
+<span class="badge-thanksapp"><a href="https://givethanks.app/donate/npm/native-promise-pool" title="Donate to this project using Thanks App"><img src="https://img.shields.io/badge/thanksapp-donate-yellow.svg" alt="Thanks App donate button" /></a></span>
+<span class="badge-boostlab"><a href="https://boost-lab.app/bevry/native-promise-pool" title="Donate to this project using Boost Lab"><img src="https://img.shields.io/badge/boostlab-donate-yellow.svg" alt="Boost Lab donate button" /></a></span>
+<span class="badge-buymeacoffee"><a href="https://buymeacoffee.com/balupton" title="Donate to this project using Buy Me A Coffee"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg" alt="Buy Me A Coffee donate button" /></a></span>
+<span class="badge-opencollective"><a href="https://opencollective.com/bevry" title="Donate to this project using Open Collective"><img src="https://img.shields.io/badge/open%20collective-donate-yellow.svg" alt="Open Collective donate button" /></a></span>
+<span class="badge-crypto"><a href="https://bevry.me/crypto" title="Donate to this project using Cryptocurrency"><img src="https://img.shields.io/badge/crypto-donate-yellow.svg" alt="crypto donate button" /></a></span>
+<span class="badge-paypal"><a href="https://bevry.me/paypal" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate button" /></a></span>
+<span class="badge-wishlist"><a href="https://bevry.me/wishlist" title="Buy an item on our wishlist for us"><img src="https://img.shields.io/badge/wishlist-donate-yellow.svg" alt="Wishlist browse button" /></a></span>
+
+<!-- /BADGES -->
+
+
+<!-- DESCRIPTION/ -->
+
+Create a pool of a specified concurrency that accepts functions that return promises
+
+<!-- /DESCRIPTION -->
+
+
+<!-- INSTALL/ -->
+
+<h2>Install</h2>
+
+<a href="https://npmjs.com" title="npm is a package manager for javascript"><h3>NPM</h3></a><ul>
+<li>Install: <code>npm install --save native-promise-pool</code></li>
+<li>Module: <code>require('native-promise-pool')</code></li></ul>
+
+<a href="http://browserify.org" title="Browserify lets you require('modules') in the browser by bundling up all of your dependencies"><h3>Browserify</h3></a><ul>
+<li>Install: <code>npm install --save native-promise-pool</code></li>
+<li>Module: <code>require('native-promise-pool')</code></li>
+<li>CDN URL: <code>//wzrd.in/bundle/native-promise-pool@1.0.0</code></li></ul>
+
+<a href="http://enderjs.com" title="Ender is a full featured package manager for your browser"><h3>Ender</h3></a><ul>
+<li>Install: <code>ender add native-promise-pool</code></li>
+<li>Module: <code>require('native-promise-pool')</code></li></ul>
+
+<h3><a href="https://github.com/bevry/editions" title="Editions are the best way to produce and consume packages you care about.">Editions</a></h3>
+
+<p>This package is published with the following editions:</p>
+
+<ul><li><code>native-promise-pool</code> aliases <code>native-promise-pool/source/index.js</code></li>
+<li><code>native-promise-pool/source/index.js</code> is esnext source code with require for modules</li>
+<li><code>native-promise-pool/edition-browsers/index.js</code> is esnext compiled for browsers with require for modules</li></ul>
+
+<!-- /INSTALL -->
+
+
 ## Usage
 
-[![asciicast](https://asciinema.org/a/eTF5cUACRMvn3xqSZi8fKemcy.svg)](https://asciinema.org/a/eTF5cUACRMvn3xqSZi8fKemcy)
+[API Documentation.](http://master.native-promise-pool.bevry.surge.sh/docs/)
 
-[API Documentation.](https://master.native-promise-pool.bevry.surge.sh/docs/)
+### Table Example
 
-<!--HISTORY -->
-<!--CONTRIBUTE -->
-<!--BACKERS -->
-<!--LICENSE -->
+[![Table Example Preview.](https://asciinema.org/a/OLI8jWnvaXuqrfXHMVGtKV1KH.svg)](https://asciinema.org/a/OLI8jWnvaXuqrfXHMVGtKV1KH)
+
+[Table Example Source.](https://github.com/bevry/native-promise-pool/blob/master/examples/table.js)
+
+### Simple Example
+
+[![Simple Example Preview.](https://asciinema.org/a/1lbq2PEEezF6zsGuUH09Rgh5w.svg)](https://asciinema.org/a/1lbq2PEEezF6zsGuUH09Rgh5w)
+
+[Simple Example Source.](https://github.com/bevry/native-promise-pool/blob/master/examples/simple.js)
+
+### Await Example
+
+[![Await Example Preview.](https://asciinema.org/a/3uhFqw4AUjMNuifuesQqHW0bd.svg)](https://asciinema.org/a/3uhFqw4AUjMNuifuesQqHW0bd)
+
+[Await Example Source.](https://github.com/bevry/native-promise-pool/blob/master/examples/await.js)
+
+### Finally
+
+This package depends on `Promise.prototype.finally` existing, which it does on Node v10 and above.
+
+On older environments, you can provide compatibility via two methods.
+
+By passing `PromiseClass`:
+
+``` javascript
+const pool = require('native-promise-pool').create({
+    concurrency: 2,
+    PromiseClass: require('bluebird')
+})
+```
+
+Or by adding direct support to the builtin `Promise` class:
+
+``` javascript
+require('promise.prototype.finally').shim()
+const pool = require('native-promise-pool').create({concurrency: 2})
+```
+
+
+<!-- HISTORY/ -->
+
+<h2>History</h2>
+
+<a href="https://github.com/bevry/native-promise-pool/blob/master/HISTORY.md#files">Discover the release history by heading on over to the <code>HISTORY.md</code> file.</a>
+
+<!-- /HISTORY -->
+
+
+<!-- CONTRIBUTE/ -->
+
+<h2>Contribute</h2>
+
+<a href="https://github.com/bevry/native-promise-pool/blob/master/CONTRIBUTING.md#files">Discover how you can contribute by heading on over to the <code>CONTRIBUTING.md</code> file.</a>
+
+<!-- /CONTRIBUTE -->
+
+
+<!-- BACKERS/ -->
+
+<h2>Backers</h2>
+
+<h3>Maintainers</h3>
+
+These amazing people are maintaining this project:
+
+<ul><li>Benjamin Lupton</li></ul>
+
+<h3>Sponsors</h3>
+
+No sponsors yet! Will you be the first?
+
+<span class="badge-patreon"><a href="https://patreon.com/bevry" title="Donate to this project using Patreon"><img src="https://img.shields.io/badge/patreon-donate-yellow.svg" alt="Patreon donate button" /></a></span>
+<span class="badge-flattr"><a href="https://flattr.com/profile/balupton" title="Donate to this project using Flattr"><img src="https://img.shields.io/badge/flattr-donate-yellow.svg" alt="Flattr donate button" /></a></span>
+<span class="badge-liberapay"><a href="https://liberapay.com/bevry" title="Donate to this project using Liberapay"><img src="https://img.shields.io/badge/liberapay-donate-yellow.svg" alt="Liberapay donate button" /></a></span>
+<span class="badge-thanksapp"><a href="https://givethanks.app/donate/npm/native-promise-pool" title="Donate to this project using Thanks App"><img src="https://img.shields.io/badge/thanksapp-donate-yellow.svg" alt="Thanks App donate button" /></a></span>
+<span class="badge-boostlab"><a href="https://boost-lab.app/bevry/native-promise-pool" title="Donate to this project using Boost Lab"><img src="https://img.shields.io/badge/boostlab-donate-yellow.svg" alt="Boost Lab donate button" /></a></span>
+<span class="badge-buymeacoffee"><a href="https://buymeacoffee.com/balupton" title="Donate to this project using Buy Me A Coffee"><img src="https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg" alt="Buy Me A Coffee donate button" /></a></span>
+<span class="badge-opencollective"><a href="https://opencollective.com/bevry" title="Donate to this project using Open Collective"><img src="https://img.shields.io/badge/open%20collective-donate-yellow.svg" alt="Open Collective donate button" /></a></span>
+<span class="badge-crypto"><a href="https://bevry.me/crypto" title="Donate to this project using Cryptocurrency"><img src="https://img.shields.io/badge/crypto-donate-yellow.svg" alt="crypto donate button" /></a></span>
+<span class="badge-paypal"><a href="https://bevry.me/paypal" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate button" /></a></span>
+<span class="badge-wishlist"><a href="https://bevry.me/wishlist" title="Buy an item on our wishlist for us"><img src="https://img.shields.io/badge/wishlist-donate-yellow.svg" alt="Wishlist browse button" /></a></span>
+
+<h3>Contributors</h3>
+
+These amazing people have contributed code to this project:
+
+<ul><li><a href="http://balupton.com">Benjamin Lupton</a> — <a href="https://github.com/bevry/native-promise-pool/commits?author=balupton" title="View the GitHub contributions of Benjamin Lupton on repository bevry/native-promise-pool">view contributions</a></li></ul>
+
+<a href="https://github.com/bevry/native-promise-pool/blob/master/CONTRIBUTING.md#files">Discover how you can contribute by heading on over to the <code>CONTRIBUTING.md</code> file.</a>
+
+<!-- /BACKERS -->
+
+
+<!-- LICENSE/ -->
+
+<h2>License</h2>
+
+Unless stated otherwise all works are:
+
+<ul><li>Copyright &copy; 2018+ Benjamin Lupton</li></ul>
+
+and licensed under:
+
+<ul><li><a href="http://spdx.org/licenses/MIT.html">MIT License</a></li></ul>
+
+<!-- /LICENSE -->

source/index.js

 'use strict'
 
-module.exports = class ArrayPromisePool {
+/**
+ * A function that is fired when the pool is ready for it to execute.
+ * It can return a promise if it is asynchronous, in which case the pool will only start another task once the promise resolves.
+ * @callback Task
+ * @returns {Promise|any}
+ */
+
+/**
+ * Create a PromisePool
+ */
+class PromisePool {
+	/**
+	 * Create a new instance of the class with the specified arguments.
+	 * @param  {...any} args
+	 * @returns {PromisePool}
+	 */
 	static create (...args) {
@@ -8,6 +23,43 @@ return new this(...args)
 
-	constructor (concurrency) {
+	/**
+	 * Instantiate the PromisePool with the desired concurrency.
+	 * @param {Object} opts
+	 * @param {number} opts.concurrency - How many tasks to run at once.
+	 * @param {PromiseConstructor} [opts.PromiseClass=Promise] - The Promise class to use. It must support `Promise.resolve().finally(() => {})`. If you are using Node v10 or above, you don't have to modify this, as the default `Promise` class already supports `.finally`. An alternative to passing in a custom `PromiseClass`, is to polyfill the builtin `Promise` class.
+	 */
+	constructor ({ concurrency, PromiseClass = Promise }) {
+		/**
+		 * How many tasks to run at once.
+		 * @type {number}
+		 * @private
+		 */
 		this.concurrency = concurrency
+
+		/**
+		 * The Promise class to use.
+		 * It must support `Promise.resolve().finally(() => {})`.
+		 * @type {PromiseConstructor}
+		 * @private
+		 */
+		this.PromiseClass = PromiseClass
+
+		/**
+		 * How many tasks are currently running.
+		 * @type {number}
+		 * @private
+		 */
 		this.running = 0
+
+		/**
+		 * How many tasks have been started.
+		 * @type {number}
+		 * @private
+		 */
 		this.started = 0
+
+		/**
+		 * For upcoming tasks, they have a function (a promise resolver) inserted into the queue which starts the task when called.
+		 * @type {Array<Function>}
+		 * @private
+		 */
 		this.queue = []
@@ -17,8 +69,15 @@ }
 	/**
-	 * Add a task to the pool
-	 * @param {Function<Promise>} task
-	 * @return {Promise} promise
+	 * Add a task to the pool.
+	 * @param {Task} task - The task to be executed when the pool permits.
+	 * @return {Promise} Returns a promise that resolves once the task has resolved or rejected. You should `.catch` it in case your task fails.
 	 */
 	open (task) {
+		// Grab the class to use to create our promise,
+		// so that the consumer can ensure `.finally` exists.
+		const Promise = this.PromiseClass
+
+		// Create our promise and push its resolver to the queue.
+		// This has the effect that we can queue its execution for later, instead of right now.
 		const p = new Promise((resolve) => this.queue.push(resolve))
+			// Once the resolver has fired, update the counts accordingly.
 			.finally(() => {
@@ -28,3 +87,5 @@ this.started--
 			})
+			// Fire our our task and store the result.
 			.then(task)
+			// Update our counts accordingly, and start the next queue item if there are any.
 			.finally(() => {
@@ -38,2 +99,3 @@ this.running--
 
+		// If our pool is under capacity, then start the first item in the queue.
 		if ((this.running + this.started) < this.concurrency && this.queue.length) {
@@ -44,4 +106,11 @@ this.started++
 
+		// Return the the promise that wraps the task,
+		// such that it resolves once the task has compelted and our wrappers have completed.
+		// This allows the user to do `Promise.all(Array<Task>.map((task) => pool.open(task)))`,
+		// so that they can queue something for when all their pooled tasks are completed.
+		// It also allows the user to do the mandatory `.catch` handling for task failures.
 		return p
 	}
 }
+
+module.exports = PromisePool

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Unidentified License

License

(Experimental) Something that seems like a license was found, but its contents could not be matched with a known license.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

26256

increased by355.2%

Dependency count

0

decreased by-100%

Number of downloads

168

increased by9.8%

Number of low license alerts

0

decreased by-100%

License quality

100

increased by25%

Lines of code

221

increased by452.5%

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

177

increased by883.33%

Worsened metrics

Dev dependency count

15

increased by50%

Number of medium supply chain risk alerts

2

increased byInfinity%

Dependency changes

• - Removededitions@^2.0.2

• - Removededitions@2.3.1(transitive)

• - Removederrlop@2.2.0(transitive)

• - Removedsemver@6.3.1(transitive)