feat: Support an array of percentiles

Add support for calcualting and array of percentiles in 1 pass, example:

```js
const percentile = require("percentile");
const result = percentile(
  [70, 80, 90], // calculates 70p, 80p and 90p in one pass
  [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
);
console.log(result); // [7, 8, 9]
```

It adds a little bit of overhead because, now percentile needs to
convert a percentile argument to an array and apply validation and
calculation to this array of percentiles, but overall performance is
still in a ball park of original implementation:

```
Small Array – 10 items [old] x 3,024,685 ops/sec ±0.65% (94 runs sampled)
Small Array – 10 items [new] x 2,941,058 ops/sec ±1.04% (95 runs sampled)
Fastest is Small Array – 10 items [old]

Big array 10k values [old] x 5,482 ops/sec ±0.58% (92 runs sampled)
Big array 10k values [new] x 5,381 ops/sec ±0.69% (91 runs sampled)
Fastest is Big array 10k values [old]

Big array 100k values [old] x 395 ops/sec ±1.00% (91 runs sampled)
Big array 100k values [new] x 406 ops/sec ±0.93% (88 runs sampled)
Fastest is Big array 100k values [new]
```

Fixes #101

Author: d4rkr00t

README.md

@@ -35,6 +35,14 @@ const result = percentile(
 );
 console.log(result); // 8
 
+// With array of percentiles
+const percentile = require("percentile");
+const result = percentile(
+  [70, 80, 90], // calculates 70p, 80p and 90p in one pass
+  [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+);
+console.log(result); // [7, 8, 9]
+
 ```
 ## Notes
 

lib/index.js

@@ -1,5 +1,5 @@
 /**
- * Error message for case when percentile is less than 0
+ * Error message for a case when percentile is less than 0.
  *
  * @param {Number} p
  *
@@ -10,7 +10,7 @@ function lessThanZeroError(p) {
 }
 
 /**
- * Error message for case when percentile is greater than 100
+ * Error message for a case when percentile is greater than 100.
  *
  * @param {Number} p
  *
@@ -21,7 +21,7 @@ function greaterThanHundredError(p) {
 }
 
 /**
- * Error message for case when percentile is not a number (NaN)
+ * Error message for a case when percentile is not a number (NaN).
  *
  * @param {Number} p
  *
@@ -32,27 +32,54 @@ function nanError(p) {
 }
 
 /**
- * Calculate percentile for given array of values.
+ * Checks that a list of percentiles are all numbers and they lie in range 0..100.
+ *
+ * @param {Array<Number>} ps - percentiles to calculate
+ *
+ * @return {Array} List of errors
+ */
+function validateInput(ps) {
+  return ps.reduce(function (errors, p) {
+    if (isNaN(Number(p))) {
+      errors.push(nanError(p));
+    } else if (p < 0) {
+      errors.push(lessThanZeroError(p));
+    } else if (p > 100) {
+      errors.push(greaterThanHundredError(p));
+    }
+    return errors;
+  }, []);
+}
+
+/**
+ * Get percentile value from an array.
  *
  * @param {Number} p - percentile
- * @param {Array} list - array of values
- * @param {Function} [fn] - optional function to extract value from array
+ * @param {Array} list - list of values
  *
  * @return {*}
  */
-function percentile(p, list, fn) {
-  if (isNaN(Number(p))) {
-    throw new Error(nanError(p));
-  }
-
-  p = Number(p);
+function getPsValue(p, list) {
+  if (p === 0) return list[0];
+  var kIndex = Math.ceil(list.length * (p / 100)) - 1;
+  return list[kIndex];
+}
 
-  if (p < 0) {
-    throw new Error(lessThanZeroError(p));
-  }
+/**
+ * Calculate percentile for given array of values.
+ *
+ * @param {Number|Array<Number>} pOrPs - percentile or a list of percentiles
+ * @param {Array} list - array of values
+ * @param {Function} [fn] - optional function to extract a value from an array item
+ *
+ * @return {*}
+ */
+function percentile(pOrPs, list, fn) {
+  var ps = Array.isArray(pOrPs) ? pOrPs : [pOrPs];
+  var validationErrors = validateInput(ps);
 
-  if (p > 100) {
-    throw new Error(greaterThanHundredError(p));
+  if (validationErrors.length) {
+    throw new Error(validationErrors.join(' '));
   }
 
   list = list.slice().sort(function (a, b) {
@@ -70,11 +97,13 @@ function percentile(p, list, fn) {
     return 0;
   });
 
-  if (p === 0) return list[0];
-
-  var kIndex = Math.ceil(list.length * (p / 100)) - 1;
+  if (ps.length === 1) {
+    return getPsValue(ps[0], list);
+  }
 
-  return list[kIndex];
+  return ps.map(function (p) {
+    return getPsValue(p, list);
+  });
 }
 
 module.exports = percentile;

package.json

@@ -21,6 +21,7 @@
     "coverage": "nyc --reporter=lcov --reporter=text --reporter=html npm test",
     "coveralls": "npm run coverage && cat ./coverage/lcov.info | coveralls && rm -rf ./coverage",
     "lint": "eslint lib test",
+    "bench": "node ./scripts/bench.js",
     "test": "ava",
     "ci:github-release": "conventional-github-releaser -p angular",
     "pmm:prepare": "npm run lint && npm test",
@@ -39,6 +40,7 @@
   "dependencies": {},
   "devDependencies": {
     "ava": "^0.25.0",
+    "benchmark": "^2.1.4",
     "conventional-github-releaser": "^3.1.3",
     "coveralls": "^3.0.2",
     "cz-conventional-changelog": "^2.1.0",

scripts/bench.js

@@ -0,0 +1,62 @@
+let Benchmark = require('benchmark');
+let percentile = require('../lib');
+let oldpercentile = require('./percentile-baseline');
+
+function generateArray(length, fn) {
+  return Array.apply(null, Array(length)).map(fn);
+}
+
+function generateArraySimple(length) {
+  return generateArray(length, (v, i) => i + 1);
+}
+
+let suite1 = new Benchmark.Suite();
+let suite2 = new Benchmark.Suite();
+let suite3 = new Benchmark.Suite();
+
+let arr10 = generateArraySimple(10);
+let arr10k = generateArraySimple(10000);
+let arr100k = generateArraySimple(100000);
+
+
+suite1.add('Small Array – 10 items [old]', function () {
+  oldpercentile(Math.floor(Math.random() * (100 - 1)), arr10);
+})
+.add('Small Array – 10 items [new]', function () {
+  percentile(Math.floor(Math.random() * (100 - 1)), arr10);
+})
+.on('cycle', function (event) {
+  console.log(String(event.target)); // eslint-disable-line
+})
+.on('complete', function () {
+  console.log('Fastest is ' + this.filter('fastest').map('name')); // eslint-disable-line
+})
+.run();
+
+suite2.add('Big array 10k values [old]', function () {
+  oldpercentile(Math.floor(Math.random() * (100 - 1)), arr10k);
+})
+.add('Big array 10k values [new]', function () {
+  percentile(Math.floor(Math.random() * (100 - 1)), arr10k);
+})
+.on('cycle', function (event) {
+  console.log(String(event.target)); // eslint-disable-line
+})
+.on('complete', function () {
+  console.log('Fastest is ' + this.filter('fastest').map('name')); // eslint-disable-line
+})
+.run();
+
+suite3.add('Big array 100k values [old]', function () {
+  oldpercentile(Math.floor(Math.random() * (100 - 1)), arr100k);
+})
+.add('Big array 100k values [new]', function () {
+  percentile(Math.floor(Math.random() * (100 - 1)), arr100k);
+})
+.on('cycle', function (event) {
+  console.log(String(event.target)); // eslint-disable-line
+})
+.on('complete', function () {
+  console.log('Fastest is ' + this.filter('fastest').map('name')); // eslint-disable-line
+})
+.run();

scripts/percentile-baseline.js

@@ -0,0 +1,80 @@
+/**
+ * Error message for case when percentile is less than 0
+ *
+ * @param {Number} p
+ *
+ * @return {String}
+ */
+function lessThanZeroError(p) {
+  return 'Expect percentile to be >= 0 but given "' + p + '" and its type is "' + (typeof p) + '".';
+}
+
+/**
+ * Error message for case when percentile is greater than 100
+ *
+ * @param {Number} p
+ *
+ * @return {String}
+ */
+function greaterThanHundredError(p) {
+  return 'Expect percentile to be <= 100 but given "' + p + '" and its type is "' + (typeof p) + '".';
+}
+
+/**
+ * Error message for case when percentile is not a number (NaN)
+ *
+ * @param {Number} p
+ *
+ * @return {String}
+ */
+function nanError(p) {
+  return 'Expect percentile to be a number but given "' + p + '" and its type is "' + (typeof p) + '".';
+}
+
+/**
+ * Calculate percentile for given array of values.
+ *
+ * @param {Number} p - percentile
+ * @param {Array} list - array of values
+ * @param {Function} [fn] - optional function to extract value from array
+ *
+ * @return {*}
+ */
+function percentile(p, list, fn) {
+  if (isNaN(Number(p))) {
+    throw new Error(nanError(p));
+  }
+
+  p = Number(p);
+
+  if (p < 0) {
+    throw new Error(lessThanZeroError(p));
+  }
+
+  if (p > 100) {
+    throw new Error(greaterThanHundredError(p));
+  }
+
+  list = list.slice().sort(function (a, b) {
+    if (fn) {
+      a = fn(a);
+      b = fn(b);
+    }
+
+    a = Number.isNaN(a) ? Number.NEGATIVE_INFINITY : a;
+    b = Number.isNaN(b) ? Number.NEGATIVE_INFINITY : b;
+
+    if (a > b) return 1;
+    if (a < b) return -1;
+
+    return 0;
+  });
+
+  if (p === 0) return list[0];
+
+  var kIndex = Math.ceil(list.length * (p / 100)) - 1;
+
+  return list[kIndex];
+}
+
+module.exports = percentile;

test/index.js

@@ -29,6 +29,15 @@ const stubsSimple = [
   { percentile: 75, list: shuffleArray([].concat(generateArraySimple(100), generateArraySimple(30))), result: 68 }
 ];
 
+test('percentile simple values', t => {
+  stubsSimple.forEach(stub => {
+    t.is(
+      percentile(stub.percentile, stub.list),
+      stub.result
+    );
+  });
+});
+
 const stubsObject = [
   { percentile: 0, list: shuffleArray(generateArrayOfObject(100)), result: 1 },
   { percentile: 25, list: shuffleArray(generateArrayOfObject(100)), result: 25 },
@@ -39,15 +48,6 @@ const stubsObject = [
   { percentile: 75, list: shuffleArray([].concat(generateArrayOfObject(100), generateArrayOfObject(30))), result: 68 }
 ];
 
-test('percentile simple values', t => {
-  stubsSimple.forEach(stub => {
-    t.is(
-      percentile(stub.percentile, stub.list),
-      stub.result
-    );
-  });
-});
-
 test('percentile values in object', t => {
   stubsObject.forEach(stub => {
     t.is(
@@ -57,20 +57,34 @@ test('percentile values in object', t => {
   });
 });
 
+test('array of percentiles', t => {
+  t.deepEqual(
+    percentile([0, 25, 50, 75, 100], shuffleArray(generateArraySimple(100))),
+    [1, 25, 50, 75, 100]
+  );
+});
+
+test('array of percentiles when values are objects', t => {
+  t.deepEqual(
+    percentile([0, 25, 50, 75, 100], shuffleArray(generateArrayOfObject(100)), item => item.val).map(p => p.val),
+    [1, 25, 50, 75, 100]
+  );
+});
+
 test('throw an error if NaN', t => {
   t.throws(() => {
-    percentile(undefined) // eslint-disable-line
+    percentile(undefined, []) // eslint-disable-line
   }, Error);
 });
 
 test('throw an error if less than 0', t => {
-  t.throws(() => {
-    percentile(-1) // eslint-disable-line
-  }, Error);
+  t.throws(() => percentile(-1, []), Error);
 });
 
 test('throw an error if grater than 100', t => {
-  t.throws(() => {
-    percentile(101) // eslint-disable-line
-  }, Error);
+  t.throws(() => percentile(101, []), Error);
+});
+
+test('throws a list of errors', t => {
+  t.throws(() => percentile([101, -1, 'a'], []), Error);
 });