meari

The library which will be able to handle promises as various ways

Usage no npm install needed!

<script type="module">
  import meari from 'https://cdn.skypack.dev/meari';
</script>

README

meari

npm npm bundle size npm NPM

The library which will be able to handle promises as various ways

Concept

This library because it is based only a promise constructor so is not need a browsers of higher version supporting Promise.all or Promise.allSettled functions

For examples seq and seqAll functions will be able to replaces Promise.all and Promise.allSettled functions

In addition, it is supporting various functions like map and retry that in the native is not supports for can using in a multiple situations

Install

npm i meari

Support Platforms

Most of modern browsers(chrome, edge, firefox ...) that supporting Promise, NodeJS

How to Use

Execution order-based apis

These features are based execution order like a Promise.all and Promise.race of a native api

import {
  seq,
  seqAll,
  map,
  mapAll,
  race,
  raceAll,
  retry,
  retryAll,
  assert,
  assertAll,
} from 'meari';

let p1, p2, p3;

p1 = Promise.resolve(1);
p2 = Promise.resolve(2);
p3 = Promise.resolve(3);

seq([p1, p2, p3])
  .then(values => {
    console.log(values);
    /*
    [
      { status: 'fulfilled', value: 1, index: 0 },
      { status: 'fulfilled', value: 2, index: 1 },
      { status: 'fulfilled', value: 3, index: 2 }
    ]
     */
  })
  .catch(v => {
    console.log(v);
  })
  .finally(() => {
    console.log('finally');
  });

p1 = Promise.resolve(1);
p2 = Promise.reject(new Error());
p3 = Promise.resolve(3);

seqAll([p1, p2, p3])
  .then(values => {
    console.log(values);
    /*
    [
      { status: 'fulfilled', value: 1, index: 0 },
      {
        status: 'rejected',
        value: Error:
          at Object.<anonymous> (/Users/user/htdocs/mohwa/async-trainer/examples/index.js:27:27)
          ...
        index: 1
      },
      { status: 'fulfilled', value: 3, index: 2 }
    ]
     */
  })
  .finally(() => {
    console.log('finally');
  });

p1 = Promise.resolve(1);
p2 = Promise.resolve(2);
p3 = Promise.resolve(3);

map([p1, p2, p3], ({ value }) => `TEST_${value}`)
  .then(values => {
    console.log(values); // [ 'TEST_1', 'TEST_2', 'TEST_3' ]
  })
  .catch(e => {
    console.dir(e);
  })
  .finally(() => {
    console.log('finally');
  });

p1 = Promise.resolve(1);
p2 = Promise.reject(new Error());
p3 = Promise.resolve(3);

mapAll([p1, p2, p3], ({ status, value }) => {
  if (status !== 'rejected') {
    return `TEST_${value}`;
  } else {
    return value;
  }
})
  .then(values => {
    console.log(values);
    /*
      [
        'TEST_1',
        Error:
            at Object.<anonymous> (/Users/user/htdocs/mohwa/async-trainer/examples/index.js:68:27)
            ...
        'TEST_3'
      ]    
     */
  })
  .finally(() => {
    console.log('finally');
  });

p1 = Promise.resolve(1);
p2 = Promise.resolve(2);
p3 = Promise.resolve(3);

race([p1, p2, p3])
  .then(values => {
    console.log(values);
    /*
    [
      { status: 'fulfilled', value: 1, index: 0 },
      { status: 'fulfilled', value: 2, index: 1 },
      { status: 'fulfilled', value: 3, index: 2 }
    ]    
     */
  })
  .catch(e => {
    console.dir(e);
  })
  .finally(() => {
    console.log('finally');
  });

p1 = Promise.resolve(1);
p2 = Promise.reject(new Error());
p3 = Promise.resolve(3);

raceAll([p1, p2, p3])
  .then(values => {
    console.log(values);
    /*
    [
      { status: 'fulfilled', value: 1, index: 0 },
      { status: 'fulfilled', value: 3, index: 2 },
      {
        status: 'rejected',
        value: Error:
            at Object.<anonymous> (/Users/user/htdocs/mohwa/async-trainer/examples/index.js:117:27)
            ...
        index: 1
      }
    ]    
     */
  })
  .finally(() => {
    console.log('finally 1');
  });

p1 = () => Promise.resolve(1);
p2 = () => Promise.resolve(2);
p3 = () => Promise.resolve(3);

retry([p1, p2, p3], 3, 1000)
  .then(values => {
    console.log(values);
    /*
    [
      { status: 'fulfilled', value: 1, index: 0 },
      { status: 'fulfilled', value: 2, index: 1 },
      { status: 'fulfilled', value: 3, index: 2 }
    ]
     */
  })
  .catch(value => {
    console.log(value);
  });

p1 = () => Promise.resolve(1);
p2 = () => Promise.reject(new Error());
p3 = () => Promise.resolve(3);

retryAll([p1, p2, p3], 3, 1000).then(values => {
  console.log(values);
  /*
  [
    { status: 'fulfilled', value: 1, index: 0 },
    {
      status: 'rejected',
      value: Error:
          at callback (/Users/user/htdocs/mohwa/async-trainer/examples/index.js:161:33)
          ...
      index: 1
    },
    { status: 'fulfilled', value: 3, index: 2 }
  ]  
   */
});

let cb1, cb2, cb3;

cb1 = () => true;
cb2 = () => true;
cb3 = () => true;

assert([cb1, cb2, cb3], 3, 1000)
  .then(values => {
    console.log(values);
    /*
    [
      { status: 'truly', value: true, index: 0 },
      { status: 'truly', value: true, index: 1 },
      { status: 'truly', value: true, index: 2 }
    ]    
     */
  })
  .catch(value => {
    console.log(value);
  });

cb1 = () => true;
cb2 = () => false;
cb3 = () => true;

assertAll([cb1, cb2, cb3], 3, 1000)
  .then(values => {
    console.log(values);
    /*
    [
      { status: 'truly', value: true, index: 0 },
      { status: 'falsely', value: false, index: 1 },
      { status: 'truly', value: true, index: 2 }
    ]    
     */
  });

Main apis

These features are can use more easily and simply sometimes in certain situation

import {
  once,
  delay,
  every,
  some,
  toSync
} from 'meari';

once(() => { console.log('once'); }, 1000)(); // once

delay(1000).then(() => { console.log('start'); }); // start

let p1, p2, p3;

p1 = Promise.resolve(1);
p2 = Promise.resolve(2);
p3 = Promise.resolve(3);

every([p1, p2, p3]).then(v => {
  console.log(v); // true
});

p1 = Promise.reject(1);
p2 = Promise.reject(2);
p3 = Promise.resolve(3);

some([p1, p2, p3]).then(v => {
  console.log(v); // true
});

p1 = () => {
  return new Promise((resolve) => {
    setTimeout(() => resolve(1), 300);
  });
};

p2 = () => {
  return new Promise((resolve) => {
    setTimeout(() => resolve(2), 100);
  });
};

toSync(p1()).then(v => console.log(v));
toSync(p2()).then(v => console.log(v));

// 1
// 2

Functions

once([callback], [delayTime]) ⇒ function

This function calls callback function only once as the async after given delayTime(created timerId will be automatically dispose after performed it)

delay([delayTime]) ⇒ Promise

This function will delay code execution for given delayTime

seq(promises) ⇒ Promise

This function returns an array which containing every results performed in order of a promises if haven't been rejected

seqAll(promises) ⇒ Promise

This function returns an array which containing every results performed in order of a promises

map(promises, callback, context) ⇒ Promise

This function returns an array which containing every results performed in order of a promises if haven't been rejected

mapAll(promises, callback, context) ⇒ Promise

This function returns an array which containing every results performed in order of a promises

race(promises) ⇒ Promise

This function returns an array which containing every results in order a promise performed if haven't been rejected

raceAll(promises) ⇒ Promise

This function returns an array which containing every results in order a promise performed

retry(callbacks, [retryCount], [delayTime]) ⇒ Promise

This function retry a callback function as much as given retryCount to until fulfilled each a promise if haven't been rejected

retryAll(callbacks, [retryCount], [delayTime]) ⇒ Promise

This function retry a callback function as much as given retryCount to until fulfilled each a promise

assert(callbacks, [retryCount], [delayTime]) ⇒ Promise

This function retry a callback function as much as given retryCount to until each callback function returns true if haven't been rejected

assertAll(callbacks, [retryCount], [delayTime]) ⇒ Promise

This function retry a callback function as much as given retryCount to until each callback function returns true

every(promises) ⇒ Promise

This function returns true when succeed every promises otherwise returns false

some(promises) ⇒ Promise

This function returns true when succeed to promise at least one otherwise returns false

toSync(promise) ⇒ Promise

This function performs synchronously a promise

once([callback], [delayTime]) ⇒ function

This function calls callback function only once as the async after given delayTime(created timerId will be automatically dispose after performed it)

Kind: global function
Returns: function - executor

Param Type Default
[callback] function function(){}
[delayTime] number 0

Example

once(() => {}, 1000)();

delay([delayTime]) ⇒ Promise

This function will delay code execution for given delayTime

Kind: global function

Param Type Default
[delayTime] number 0

Example

delay(1000).then(() => {});

seq(promises) ⇒ Promise

This function returns an array which containing every results performed in order of a promises if haven't been rejected

Kind: global function

Param Type Description
promises Array An array which containing a promise or any value

Example

seq([Promise.resolve(), Promise.resolve()]).then(values => {}).catch(value => {});

seqAll(promises) ⇒ Promise

This function returns an array which containing every results performed in order of a promises

Kind: global function

Param Type Description
promises Array An array which containing a promise or any value

Example

seqAll([Promise.resolve(), Promise.resolve()]).then(values => {});

map(promises, callback, context) ⇒ Promise

This function returns an array which containing every results performed in order of a promises if haven't been rejected

Kind: global function

Param Type Description
promises Array An array which containing a promise or any value
callback function A function which will be call on every promises
context * A value which will be use as context(this) when performed callback function

Example

map([Promise.resolve(), Promise.resolve()], (value) => value).then(values => {}).catch(value => {});

mapAll(promises, callback, context) ⇒ Promise

This function returns an array which containing every results performed in order of a promises

Kind: global function

Param Type Description
promises Array An array which containing a promise or any value
callback function A function which will be call on every promises
context * A value which will be use as context(this) when performed callback function

Example

mapAll([Promise.resolve(), Promise.resolve()], (value) => value).then(values => {});

race(promises) ⇒ Promise

This function returns an array which containing every results in order a promise performed if haven't been rejected

Kind: global function

Param Type Description
promises Array An array which containing a promise or any value

Example

race([Promise.resolve(), Promise.resolve()]).then(values => {}).catch(value => {});

raceAll(promises) ⇒ Promise

This function returns an array which containing every results in order a promise performed

Kind: global function

Param Type Description
promises Array An array which containing a promise or any value

Example

raceAll([Promise.resolve(), Promise.resolve()]).then(values => {});

retry(callbacks, [retryCount], [delayTime]) ⇒ Promise

This function retry a callback function as much as given retryCount to until fulfilled each a promise if haven't been rejected

Kind: global function

Param Type Default Description
callbacks function | Array A function or array which returns the promise or any value
[retryCount] number 0
[delayTime] number 0

Example

retry([Promise.resolve(), Promise.resolve()], 3, 1000).then(values => {}).catch(value => {});

retryAll(callbacks, [retryCount], [delayTime]) ⇒ Promise

This function retry a callback function as much as given retryCount to until fulfilled each a promise

Kind: global function

Param Type Default Description
callbacks function | Array A function or array which returns the promise or any value
[retryCount] number 0
[delayTime] number 0

Example

retryAll([Promise.resolve(), Promise.resolve()], 3, 1000).then(values => {});

assert(callbacks, [retryCount], [delayTime]) ⇒ Promise

This function retry a callback function as much as given retryCount to until each callback function returns true if haven't been rejected

Kind: global function

Param Type Default Description
callbacks function | Array A function or array which returns the boolean value
[retryCount] number 0
[delayTime] number 0

Example

assert([Promise.resolve(), Promise.resolve()], 3, 1000).then(values => {}).catch(value => {});

assertAll(callbacks, [retryCount], [delayTime]) ⇒ Promise

This function retry a callback function as much as given retryCount to until each callback function returns true

Kind: global function

Param Type Default Description
callbacks function | Array A function or array which returns the boolean value
[retryCount] number 0
[delayTime] number 0

Example

assertAll([Promise.resolve(), Promise.resolve()], 3, 1000).then(values => {});

every(promises) ⇒ Promise

This function returns true when succeed every promises otherwise returns false

Kind: global function

Param Type Description
promises Array An array which containing a promise or any value

Example

every([Promise.resolve(), Promise.resolve()]).then(v => v);

some(promises) ⇒ Promise

This function returns true when succeed to promise at least one otherwise returns false

Kind: global function

Param Type Description
promises Array An array which containing a promise or any value

Example

some([Promise.resolve(), Promise.reject()]).then(v => v);

toSync(promise) ⇒ Promise

This function performs synchronously a promise

Kind: global function

Param Type Description
promise Promise A promise which will be perform synchronously

Example

toSync(Promise.resolve(1)).then(v => console.log(v));