queue-async - npm Package Compare versions

Comparing version 1.1.1 to 1.2.0

build/bundle.js

@@ -1,1 +0,1 @@
-import queue from "../index"; queue.version = "1.1.1"; export default queue;
+import queue from "../index"; queue.version = "1.2.0"; export default queue;

build/queue.js

@@ -11,3 +11,3 @@ (function (global, factory) {
 
-  var running = {};
+  var noabort = {};
   var success = [null];
@@ -19,2 +19,3 @@ function newQueue(parallelism) {
         tasks = [],
+        results = [],
         waiting = 0,
@@ -35,5 +36,4 @@ active = 0,
             c = t[j];
-        tasks[i] = running, --waiting, ++active;
         t[j] = end(i);
-        c.apply(null, t);
+        --waiting, ++active, tasks[i] = c.apply(null, t) || noabort;
       }
@@ -44,11 +44,9 @@ }
       return function(e, r) {
-        if (tasks[i] !== running) throw new Error; // detect multiple callbacks
-        tasks[i] = null, --active, ++ended;
+        if (!tasks[i]) throw new Error; // detect multiple callbacks
+        --active, ++ended, tasks[i] = null;
         if (error != null) return; // only report the first error
         if (e != null) {
-          error = e; // ignore new tasks and squelch active callbacks
-          waiting = NaN; // stop queued tasks from starting
-          notify();
+          abort(e);
         } else {
-          tasks[i] = r;
+          results[i] = r;
           if (waiting) start();
@@ -60,6 +58,12 @@ else if (!active) notify();
 
+    function abort(e) {
+      error = e; // ignore new tasks and squelch active callbacks
+      waiting = NaN; // stop queued tasks from starting
+      notify();
+    }
+
     function notify() {
       if (error != null) callback(error);
-      else if (callbackAll) callback(null, tasks);
-      else callback.apply(null, success.concat(tasks));
+      else if (callbackAll) callback(null, results);
+      else callback.apply(null, success.concat(results));
     }
@@ -72,6 +76,14 @@
         t.push(f);
-        tasks.push(t), ++waiting;
+        ++waiting, tasks.push(t);
         start();
         return q;
       },
+      abort: function() {
+        if (error == null) {
+          var i = ended + active, t;
+          while (--i >= 0) (t = tasks[i]) && t.abort && t.abort();
+          abort(new Error("abort"));
+        }
+        return q;
+      },
       await: function(f) {
@@ -96,3 +108,3 @@ if (callback !== noop) throw new Error;
 
-  queue.version = "1.1.1";
+  queue.version = "1.2.0";
 
@@ -99,0 +111,0 @@ return queue;

build/queue.min.js

@@ -1,1 +0,1 @@
-!function(n,r){"object"==typeof exports&&"undefined"!=typeof module?module.exports=r():"function"==typeof define&&define.amd?define("queue",r):n.queue=r()}(this,function(){"use strict";function n(){}function r(r){function e(){if(!c)for(;c=p&&r>s;){var n=h+s,e=w[n],t=e.length-1,o=e[t];w[n]=u,--p,++s,e[t]=i(n),o.apply(null,e)}}function i(n){return function(r,t){if(w[n]!==u)throw new Error;w[n]=null,--s,++h,null==a&&(null!=r?(a=r,p=NaN,f()):(w[n]=t,p?e():s||f()))}}function f(){null!=a?d(a):m?d(null,w):d.apply(null,o.concat(w))}if(!(r>=1))throw new Error;var l,c,a,w=[],p=0,s=0,h=0,d=n,m=!0;return l={defer:function(r){if(d!==n)throw new Error;var u=t.call(arguments,1);return u.push(r),w.push(u),++p,e(),l},await:function(r){if(d!==n)throw new Error;return d=r,m=!1,p||s||f(),l},awaitAll:function(r){if(d!==n)throw new Error;return d=r,m=!0,p||s||f(),l}}}function e(n){return r(arguments.length?+n:1/0)}var t=[].slice,u={},o=[null];return e.version="1.1.1",e});
+!function(n,r){"object"==typeof exports&&"undefined"!=typeof module?module.exports=r():"function"==typeof define&&define.amd?define("queue",r):n.queue=r()}(this,function(){"use strict";function n(){}function r(r){function t(){if(!c)for(;c=h&&r>d;){var n=v+d,t=p[n],u=t.length-1,o=t[u];t[u]=f(n),--h,++d,p[n]=o.apply(null,t)||e}}function f(n){return function(r,u){if(!p[n])throw new Error;--d,++v,p[n]=null,null==w&&(null!=r?i(r):(s[n]=u,h?t():d||l()))}}function i(n){w=n,h=NaN,l()}function l(){null!=w?E(w):b?E(null,s):E.apply(null,o.concat(s))}if(!(r>=1))throw new Error;var a,c,w,p=[],s=[],h=0,d=0,v=0,E=n,b=!0;return a={defer:function(r){if(E!==n)throw new Error;var e=u.call(arguments,1);return e.push(r),++h,p.push(e),t(),a},abort:function(){if(null==w){for(var n,r=v+d;--r>=0;)(n=p[r])&&n.abort&&n.abort();i(new Error("abort"))}return a},await:function(r){if(E!==n)throw new Error;return E=r,b=!1,h||d||l(),a},awaitAll:function(r){if(E!==n)throw new Error;return E=r,b=!0,h||d||l(),a}}}function t(n){return r(arguments.length?+n:1/0)}var u=[].slice,e={},o=[null];return t.version="1.2.0",t});

package.json

 {
   "name": "queue-async",
-  "version": "1.1.1",
-  "description": "A little helper for asynchronous JavaScript.",
+  "version": "1.2.0",
+  "description": "A minimalist library for escaping callback hell.",
   "keywords": [
@@ -6,0 +6,0 @@ "asynchronous",

README.md

@@ -1,54 +0,122 @@
-# Queue
+# Queue.js
 
-**Queue.js** is yet another asynchronous helper library for JavaScript. Think of Queue as a minimalist version of [Async.js](https://github.com/caolan/async) that allows fine-tuning over parallelism. Or, think of it as a version of [TameJs](https://github.com/maxtaco/tamejs/) that does not use code generation.
+**Queue.js** is a minimalist library for escaping callback hell in asynchronous JavaScript. As of release 1.2, Queue is 560 bytes gzipped. (Compare that to [Async.js](https://github.com/caolan/async), which is 4,300!)
 
-For example, if you wanted to stat two files in parallel:
+A queue evaluates zero or more asynchronous tasks with tunable parallelism. Each task is a function that takes a callback as its last argument. For example, here’s a task that says hello after a short delay:
 
 ```js
-queue()
-    .defer(fs.stat, __dirname + "/../Makefile")
-    .defer(fs.stat, __dirname + "/../package.json")
-    .await(function(error, file1, file2) { console.log(file1, file2); });
+function delayedHello(callback) {
+  setTimeout(function() {
+    console.log("Hello!");
+    callback(null);
+  }, 250);
+}
 ```
 
-Or, if you wanted to run a bazillion asynchronous tasks (here represented as an array of closures) serially:
+When a task completes, it must call the provided callback. The first argument to the callback should be null if the task is successfull, or the error if the task failed. The optional second argument to the callback is the return value of the task. (To return multiple values from a single callback, wrap the results in an object or array.)
 
+To run multiple tasks in parallel, create a queue, *defer* your tasks, and then register an *await* callback to be called when all of the tasks complete (or an error occurs):
+
 ```js
-var q = queue(1);
-tasks.forEach(function(t) { q.defer(t); });
-q.awaitAll(function(error, results) { console.log("all done!"); });
+var q = queue();
+q.defer(delayedHello);
+q.defer(delayedHello);
+q.await(function(error) {
+  if (error) throw error;
+  console.log("Goodbye!");
+});
 ```
 
-Queue can be run inside Node.js or in a browser.
+Of course, you can also use a `for` loop to defer many tasks:
 
-## Installation
+```js
+var q = queue();
 
-In a browser, you can use the official hosted copy on [d3js.org](http://d3js.org):
+for (var i = 0; i < 1000; ++i) {
+  q.defer(delayedHello);
+}
 
-```html
-<script src="https://d3js.org/queue.v1.min.js"></script>
+q.awaitAll(function(error) {
+  if (error) throw error;
+  console.log("Goodbye!");
+});
 ```
 
-Queue supports the [universal module definition](https://github.com/umdjs/umd) API. For example, with [RequireJS](http://requirejs.org/):
+Tasks can take optional arguments. For example, here’s how to configure the delay before hello and provide a name:
 
 ```js
-require.config({
-  paths: {
-    queue: "https://d3js.org/queue.v1.min"
-  }
-});
+function delayedHello(name, delay, callback) {
+  setTimeout(function() {
+    console.log("Hello, " + name + "!");
+    callback(null);
+  }, delay);
+}
+```
 
-require(["queue"], function(queue) {
-  console.log(queue.version);
-});
+Any additional arguments provided to [*queue*.defer](#queue_defer) are automatically passed along to the task function before the callback argument. You can also use method chaining for conciseness, avoiding the need for a local variable:
+
+```js
+queue()
+    .defer(delayedHello, "Alice", 250)
+    .defer(delayedHello, "Bob", 500)
+    .defer(delayedHello, "Carol", 750)
+    .await(function(error) {
+      if (error) throw error;
+      console.log("Goodbye!");
+    });
 ```
 
-In Node, use [NPM](http://npmjs.org) to install:
+The [asynchronous callback pattern](https://github.com/maxogden/art-of-node#callbacks) is very common in Node.js, so Queue works directly with many Node APIs. For example, to [stat two files](https://nodejs.org/dist/latest/docs/api/fs.html#fs_fs_stat_path_callback) in parallel:
 
-```bash
-npm install queue-async
+```js
+queue()
+    .defer(fs.stat, __dirname + "/../Makefile")
+    .defer(fs.stat, __dirname + "/../package.json")
+    .await(function(error, file1, file2) {
+      if (error) throw error;
+      console.log(file1, file2);
+    });
 ```
 
-And then `require("queue-async")`. (The package name is [queue-async](https://npmjs.org/package/queue-async) because the name “queue” was already taken.)
+You can also make abortable tasks: these tasks return an object with an *abort* method which terminates the task. So, if a task calls [setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setTimeout) on start, it can call [clearTimeout](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/clearTimeout) on abort. For example:
 
+```js
+function delayedHello(name, delay, callback) {
+  var id = setTimeout(function() {
+    console.log("Hello, " + name + "!");
+    callback(null);
+  }, delay);
+  return {
+    abort: function() {
+      clearTimeout(id);
+    }
+  };
+}
+```
+
+When you call [*queue*.abort](#queue_abort), any in-progress tasks will be immediately aborted; in addition, any pending (not-yet-started) tasks not be started. Note that you can also use *queue*.abort *without* abortable tasks, in which case pending tasks will be cancelled, though active tasks will continue to run. Conveniently, the [d3-request](https://github.com/d3/d3-request) library implements abort atop XMLHttpRequest. For example:
+
+```js
+var q = queue()
+    .defer(d3.request, "http://www.google.com:81")
+    .defer(d3.request, "http://www.google.com:81")
+    .defer(d3.request, "http://www.google.com:81")
+    .awaitAll(function(error, results) {
+      if (error) throw error;
+      console.log(results);
+    });
+```
+
+To abort these requests, call `q.abort()`.
+
+## Installation
+
+If you use NPM, `npm install queue-async`. Otherwise, download the [latest release](https://github.com/mbostock/queue/releases/latest). The released bundle supports AMD, CommonJS, and vanilla environments. You can also load directly from [d3js.org](https://d3js.org):
+
+```html
+<script src="https://d3js.org/queue.v1.min.js"></script>
+```
+
+In a vanilla environment, a `queue` global function is exported. [Try queue in your browser.](https://tonicdev.com/npm/queue-async)
+
 ## API Reference
@@ -62,4 +130,6 @@
 
-Adds the specified asynchronous *task* callback to the queue, with any optional *arguments*. The *task* will be called with the specified optional arguments and an additional callback argument; the callback must then be invoked by the task when it has finished. The task must invoke the callback with two arguments: the error, if any, and the result of the task. For example:
+Adds the specified asynchronous *task* callback to the queue, with any optional *arguments*. The *task* will be called with the specified optional arguments and an additional callback argument; the callback must then be invoked by the task when it has finished. The task must invoke the callback with two arguments: the error, if any, and the result of the task. To return multiple results from a single callback, wrap the results in an object or array.
 
+For example, here’s a task which computes the answer to the ultimate question of life, the universe, and everything after a short delay:
+
 ```js
@@ -73,4 +143,2 @@ function simpleTask(callback) {
 
-To return multiple results from a single callback, wrap those results in an object or array.
-
 If the task calls back with an error, any tasks that were scheduled *but not yet started* will not run. For a serial queue (of *parallelism* 1), this means that a task will only run if all previous tasks succeed. For a queue with higher parallelism, only the first error that occurs is reported to the await callback, and tasks that were started before the error occurred will continue to run; note, however, that their results will not be reported to the await callback.
@@ -80,2 +148,6 @@
 
+<a href="#queue_abort" name="queue_abort">#</a> <i>queue</i>.<b>abort</b>()
+
+Aborts any active tasks, invoking each active task’s *task*.abort function, if any. Also prevents any new tasks from starting, and invokes the [*queue*.await](#queue_await) or [*queue*.awaitAll](#queue_awaitAll) callback with an error indicating that the queue was aborted. See the [introduction](#queuejs) for an example implementation of an abortable task.
+
 <a href="#queue_await" name="queue_await">#</a> <i>queue</i>.<b>await</b>(<i>callback</i>)
@@ -82,0 +154,0 @@

src/queue.js

 import {slice} from "./array";
 import noop from "./noop";
 
-var running = {},
+var noabort = {},
     success = [null];
@@ -12,2 +12,3 @@
       tasks = [],
+      results = [],
       waiting = 0,
@@ -28,5 +29,4 @@ active = 0,
           c = t[j];
-      tasks[i] = running, --waiting, ++active;
       t[j] = end(i);
-      c.apply(null, t);
+      --waiting, ++active, tasks[i] = c.apply(null, t) || noabort;
     }
@@ -37,11 +37,9 @@ }
     return function(e, r) {
-      if (tasks[i] !== running) throw new Error; // detect multiple callbacks
-      tasks[i] = null, --active, ++ended;
+      if (!tasks[i]) throw new Error; // detect multiple callbacks
+      --active, ++ended, tasks[i] = null;
       if (error != null) return; // only report the first error
       if (e != null) {
-        error = e; // ignore new tasks and squelch active callbacks
-        waiting = NaN; // stop queued tasks from starting
-        notify();
+        abort(e);
       } else {
-        tasks[i] = r;
+        results[i] = r;
         if (waiting) start();
@@ -53,6 +51,12 @@ else if (!active) notify();
 
+  function abort(e) {
+    error = e; // ignore new tasks and squelch active callbacks
+    waiting = NaN; // stop queued tasks from starting
+    notify();
+  }
+
   function notify() {
     if (error != null) callback(error);
-    else if (callbackAll) callback(null, tasks);
-    else callback.apply(null, success.concat(tasks));
+    else if (callbackAll) callback(null, results);
+    else callback.apply(null, success.concat(results));
   }
@@ -65,6 +69,14 @@
       t.push(f);
-      tasks.push(t), ++waiting;
+      ++waiting, tasks.push(t);
       start();
       return q;
     },
+    abort: function() {
+      if (error == null) {
+        var i = ended + active, t;
+        while (--i >= 0) (t = tasks[i]) && t.abort && t.abort();
+        abort(new Error("abort"));
+      }
+      return q;
+    },
     await: function(f) {
@@ -71,0 +83,0 @@ if (callback !== noop) throw new Error;

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

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

Improved metrics

Total package byte prevSize

18109

increased by30.77%

Lines of code

181

increased by13.84%

Number of lines in readme file

175

increased by69.9%

No dependency changes