Simple lib to use promises with events

Compatibility

check here

Bundle Analyzer

• main
• types

Quick Menu

• how to use
• documentation
• how to contribute
• license

How to use

Install

npm i promise-with-events

#or

yarn add promise-with-events

#or

pnpm add promise-with-events

Simple example

import { createWatchEvent, onResolveEvents } from "promise-with-events";

const promiseExample1 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1000, "example1");
  });
};

createWatchEvent(promiseExample1, {
  eventName: "key1",
  autoStart: true,
});

onResolveEvents(
  (error, resolve1) => {
    console.log(resolve1); //output = "example1"
  },
  ["key1"]
);

Documentation

• watch events
  • single promise
  • multi promises
  • multi events
  • auto start
  • promise method
• start events
• events
  • onStartEvents
  • onResolveEvents
  • onRejectEvents
  • onFinallyEvents
• [advanced]
  • reuse watched events

Watch Events

createWatchEvent receive 2 params:

1. promises: (() => promises)[]
2. key: that is the event name OR config:

type TConfig = {
  eventName: string;
  autoStart?: boolean;
  promiseMethod?: "all" | "allSettled" | "any" | "race";
};

Quick Examples

...
createWatchEvent(promise1, "key1")

...
createWatchEvent(promise1, {
  eventName: "key1",
  autoStart: true,
  promiseMethod: 'race',
})

...
createWatchEvent([promise1, promise2], "key2")

...
createWatchEvent([promise1, promise2], {
  eventName: "key2",
  autoStart: true,
  promiseMethod: 'race',
})

Single Promise

Example

import {
  createWatchEvent,
  startEvents,
  onResolveEvents,
} from "promise-with-events";

const promiseExample1 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1000, "example1");
  });
};

createWatchEvent(promiseExample1, "key1");

startEvents(["key1"]);

onResolveEvents(
  (error, resolve1) => {
    console.log(resolve1); //output = "example1"
  },
  ["key1"]
);

Multi Promises

Example

import {
  createWatchEvent,
  startEvents,
  onResolveEvents,
} from "promise-with-events";

const promiseExample1 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1000, "example1");
  });
};

const promiseExample2 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 2000, "example2");
  });
};

createWatchEvent([promiseExample1, promiseExample2], "key1");

startEvents(["key1"]);

onResolveEvents(
  (error, resolve1) => {
    console.log(resolve1); //output = ["example1", "example2"]
  },
  ["key1"]
);

Multi Events

Example

import {
  createWatchEvent,
  startEvents,
  onResolveEvents,
} from "promise-with-events";

const promiseExample1 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1000, "example1");
  });
};

const promiseExample2 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 2000, "example2");
  });
};

const promiseExample3 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1000, "example3");
  });
};

const promiseExample4 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 2000, "example4");
  });
};

createWatchEvent([promiseExample1, promiseExample2], "key1");

createWatchEvent([promiseExample3, promiseExample4], "key2");

startEvents(["key1", "key2"]);

onResolveEvents(
  (error, resolve1, resolve2) => {
    console.log(resolve1); //output = ["example1", "example2"]
    console.log(resolve2); //output = ["example3", "example4"]
  },
  ["key1", "key2"]
);

Auto Start

Note: startEvents doesn't works with autoStart active Possible values: true | false (default value = true)

Example

import { createWatchEvent, onResolveEvents } from "promise-with-events";

const promiseExample1 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1000, "example1");
  });
};

const promiseExample2 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 2000, "example2");
  });
};

createWatchEvent([promiseExample1, promiseExample2], {
  eventName: "key1",
  autoStart: true,
});

onResolveEvents(
  (error, resolve1) => {
    console.log(resolve1); //output = ["example1", "example2"]
  },
  ["key1"]
);

Promise Method

Note: promiseMethod doesn't works with single promise Possible values: all | allSettled | any | race (default value = all)

Example

import { createWatchEvent, onResolveEvents } from "promise-with-events";

const promiseExample1 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1000, "example1");
  });
};

const promiseExample2 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 2000, "example2");
  });
};

createWatchEvent([promiseExample1, promiseExample2], {
  eventName: "key1",
  autoStart: true,
  promiseMethod: "any",
});

onResolveEvents(
  (error, resolve1) => {
    console.log(resolve1); //output = "example1"
  },
  ["key1"]
);

Start Events

Note: Doesn't works with autoStart: true

Example

import { startEvents } from "promise-with-events";

startEvents(["key1"]);

startEvents(["key1", "key2"]);

Events

All events receive 2 params:

1. callback: returns error, ...responses (response for each key)
2. keys: string[]

Note: error on callback its about code errors

onStartEvents

Calls callback param when all promises are resolved

Note: Doesn't works with autoStart: true

Quick Examples

...
onStartEvents((error) => {
  console.log('ok')
}, ["key1"])

...
onStartEvents((error) => {
  console.log('ok')
}, ["key1", "key2"])

onResolveEvents

Calls callback param when all promises are resolved

Quick Examples

...
onResolveEvents((error, resolve1) => {
  console.log(resolve1)
}, ["key1"])

...
onResolveEvents((error, resolve1, resolve2) => {
  console.log(resolve1)
  console.log(resolve2)
}, ["key1", "key2"])

onRejectEvents

Calls callback param when all promises are rejected

Quick Examples

...
onRejectEvents((error, reject1) => {
  console.log(reject1)
}, ["key1"])

...
onResolveEvents((error, reject1, reject2) => {
  console.log(reject1)
  console.log(reject2)
}, ["key1", "key2"])

onFinallyEvents

Calls callback param when all promises are finished

Quick Examples

...
onFinallyEvents((error, finally1) => {
  console.log(finally1.response) //could be undefined, according promise result
  console.log(finally1.error) //could be undefined, according promise result
}, ["key1"])

...
onFinallyEvents((error, finally1, finally2) => {
  console.log(finally1.response)
  console.log(finally1.error)
  console.log(finally2.response)
  console.log(finally2.rerror)
}, ["key1", "key2"])

Advanced

Reuse Watched Events

Example

import { createWatchEvent, onResolveEvents } from "promise-with-events";

const promiseExample1 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1000, "example1");
  });
};

const promiseExample2 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 2000, "example2");
  });
};

const promiseExample3 = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1000, "example3");
  });
};

const watchedPromise1 = createWatchEvent([promiseExample1, promiseExample2], {
  eventName: "key1",
  autoStart: true,
  promiseMethod: "any",
});

const watchedPromise2 = createWatchEvent([watchedPromise1, promiseExample3], {
  eventName: "key2",
  autoStart: true,
});

createWatchEvent([watchedPromise1, watchedPromise2], {
  eventName: "key3",
  autoStart: true,
  promiseMethod: "all",
});

onResolveEvents(
  (error, resolve1) => {
    console.log(resolve1); //output = "example1"
  },
  ["key1"]
);

onResolveEvents(
  (error, resolve2) => {
    console.log(resolve2); //output = ["example1", "example3"]
  },
  ["key2"]
);

onResolveEvents(
  (error, resolve3) => {
    console.log(resolve3); //output = ["example1", ["example1", "example3"]]
  },
  ["key3"]
);

How to contribute

To contribute, make sure to follow the steps bellow:

1. Create a new branch:

    git checkout -b feat/your-new-feature

2. Make your changes, add unit tests (with jest) and test with npm link

   On promise-with-events project:

    npm link

   On your app/project:

    npm link promise-with-events

   This will create a symlink into your node_modules app, and you can test iteratively. You can check more about npm-link here

3. Before to push your changes to origin, open your pull request and fill all required fields.

   1. Make sure to fill the Release section with what your pull request changes. This section is required to merge pull request.

4. Set a required semver label according to your change:

   1. semver:patch: used when you submit a fix to a bug, enhance performance, etc;
   2. semver:minor: used when you submit a new component, new feature, etc;
   3. semver:major: used when you submit some breaking change, etc;
   4. semver:prerelease: used when you submit a prerelease (ex: 1.0.0-beta.1);
   5. semver:bypass: used to update docs, or something that doesn’t affect the build.

Info: Once you have merged your pull request, with all required fields, GitHub Actions will be responsible to create a new build and publish.

License

MIT License