meari

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)

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));