jseijas/async-array-loop

a small collection of non-blocking array operation methods

Async-Array-Loop

A small library with non-blocking array methods(map, reduce, filter, foreach)

WARNING: This library uses specific NodeJS api, hence will not work in browsers.

Installation

npm install async-array-loop

Usage

To use one of the methods, simply import it. Each method has a separate version that uses promise instead of callback.

To use the method with promise, import the module name with suffix Promise, for example, const { filterPromise } = require('async-array-loop')

Following you can see some examples on the usage of each method

Filter

const { filter } = require('async-array-loop');

const someNums = [1,2,3,4];

filter(
  someNums,
  // the processing function
  (current, index, array, next) => {

    let isGreaterThanTwo = current > 2;

    // call next once done,
    // first argument is error,
    // second argument is the value to return
    next(null, isGreaterThanTwo);
  },
  // called when complete
  (error, result) => {
    if (error) {
      console.log(error);
      return;
    }

    console.log(result); // => [3,4]
  }
);

Filter(with promise)

const { filterPromise } = require('async-array-loop');

const someNums = [1,2,3,4];

filterPromise(
  someNums,
  // the processing function
  (current, index, array, next) => {

    let isGreaterThanTwo = current > 2;

    // call next once done,
    // first argument is error,
    // second argument is the value to return
    next(null, isGreaterThanTwo);
  }
).then((result) => {
  console.log(result); // => [3,4]
}).catch((error) => {
  if (error) {
    console.log(error);
  }
});

Foreach

const { foreach } = require('async-array-loop');

const someNums = [1,2,3,4];

foreach(
  someNums,
  // the processing function
  (current, index, array, next) => {

    // observe the values at index
    console.log(`value is ${current} at index ${index}`);

    // call next once done,
    // foreach only takes single argument,
    // if an error is passed, loop will halt and return the error in callback
    next(null);
  },
  // callback when complete
  (error) => {

    // if an error occured or passed via the 'next' callback,
    // it'll be available here
    if (error) {
      console.log(error);
      return;
    }

    console.log('done');
  }
);

Foreach(with promise)

const { foreachPromise } = require('async-array-loop');

const someNums = [1,2,3,4];

foreachPromise(
  someNums,
  // the processing function
  (current, index, array, next) => {

    // observe the values at index
    console.log(`value is ${current} at index ${index}`);

    // call next once done,
    // foreach only takes an argument,
    // if error is passed, the loop will halt immediately
    next(null);
  }
).then(() => {
  // foreach does not return any value on completion
  console.log('done');
}).catch((error) => {
  if (error) {
    console.log(error);
  }
});

Reduce

const { reduce } = require('async-array-loop');

const someNums = [1,2,3,4];

reduce(
  someNums,
  // the processing function
  (prevValue, nextValue, next) => {

    let sum = prevValue + nextValue;

    // call next once done,
    // first argument is error,
    // second argument is the value to return
    next(null, sum);
  },
  // called when complete
  (error, result) => {
    if (error) {
      console.log(error);
      return;
    }

    console.log(result); // => 10
  }
);

// it is also possible to pass an initial value
let initialValue = 50;

reduce(
  someNums,
  // the processing function
  (prevValue, nextValue, next) => {

    let sum = prevValue + nextValue;

    // call next once done,
    // first argument is error,
    // second argument is the value to return
    next(null, sum);
  },
  // called when complete
  (error, result) => {
    if (error) {
      console.log(error);
      return;
    }

    console.log(result); // => 60
  },
  initialValue
);

Reduce(with promise)

const { reducePromise } = require('async-array-loop');

const someNums = [1,2,3,4];

reducePromise(
  someNums,
  // the processing function
  (prevValue, nextValue, next) => {
    // double each number
    let sum = prevValue + nextValue;

    // call next once done,
    // first argument is error,
    // second argument is the value to return
    next(null, sum);
  }
).then((result) => {
  console.log(result); // => 10
}).catch((error) => {
  if (error) {
    console.log(error);
  }
});

// it is also possible to pass an initial value
let initialValue = 20;

reducePromise(
  someNums,
  // the processing function
  (prevValue, nextValue, next) => {
    // double each number
    let sum = prevValue + nextValue;

    // call next once done,
    // first argument is error,
    // second argument is the value to return
    next(null, sum);
  },
  initialValue // we pass an initial value
).then((result) => {
  console.log(result); // => 30
}).catch((error) => {
  if (error) {
    console.log(error);
  }
});

Map

const { map } = require('async-array-loop');

const someNums = [1,2,3,4];

map(
  someNums,
  // the processing function
  (current, index, array, next) => {

    let doubleOfCurrent = current * 2;

    // call next once done,
    // first argument is error,
    // second argument is the value to return
    next(null, doubleOfCurrent);
  },
  // called when complete
  (error, result) => {
    if (error) {
      console.log(error);
      return;
    }

    console.log(result); // => [2,4,6,8]
  }
);

Map(with promise)

const { mapPromise } = require('async-array-loop');

const someNums = [1,2,3,4];

mapPromise(
  someNums,
  // the processing function
  (current, index, array, next) => {
    // double each number
    let doubleOfCurrent = current * 2;

    // call next once done,
    // first argument is error,
    // second argument is the value to return
    next(null, doubleOfCurrent);
  }
).then((result) => {
  console.log(result); // => [2,4,6,8]
}).catch((error) => {
  if (error) {
    console.log(error);
  }
});

Tests

To test first run npm install and finally npm run test

Contributing

This library(excluding tests) is written following the XO coding style. All kinds of improvements/suggestions/PRs are welcomed. Please write tests for any changes you want to make and submit a PR. :)

License

This library is released under the MIT license.