This class is used to create a fuly custom promise. Why a new type of promises? Since it supports the usage of events, stacking, children and some other features. It is mostly the same as the original promises with a few differences. The first difference is that the resolver function receives just one argument: the event argument. When you call this argument the first parameter you supply is the name of the event and after that you can supply the remaining parameters you want to pass through. You can also add handlers to the promise using the .on(), .then() and .catch(), each of which is explained in the function descriptions. When an event is created, it is added to the queue and when there is an update each item in the queue will be checked and the matched handlers per item will be called. When a handler returns a promise, which shall be named "child", all handlers added after the child returning handler will be added to the child. It is also important to note that the first tick the promise is locked, meaning no events will be called. This is because this allows for multiple handlers to be added without the first added handler clearing out all the events.
cerus.promise(function(event) {
event("done", "test");
})
.on("done", console.log);
// logs "test"
cerus.promise(function(event) {
event("done", "test");
})
.on("done", function(value) {
return cerus.promise(function(event) {
event("other_event", value);
});
})
.on("other_event", console.log);
// logs "test"
This function updates all the events that are in the queue. It does this by looping through all the events in the queue and matching all the handlers there are listening for every event. Those handlers then get called. If the promise is locked it will return and do nothing. After looping through all the events in queue the queue is cleared.
With this function you can create a handler that responds to all error events. The meaning of a handler is explained in the class description. The error events are: "err", "error", "catch" and "failure".
This function will call the specified event. This function is passed into the promise function, but can also be used to call events from outside of the promise. You can also add arguments by just adding them to function. What events cause what to happen, like "then" and "catch" functions is explained in the class description.
With this function you can create a handler that responds to the specified event. The meaning of a handler is explained in the class description. You can set the event using the event parameter.
This function returns a real promise that will be resolved when the specified handler has resolved. By default the handler that has last been added is promisified. The promise that is returned will allways resolve succesfully even if the handler is catch handler.
let test_promise = cerus.promise(event => event("done", "test"));
console.log(await test_promise.shadow());
// logs "test"
This function is used to stack the promise. Stacking means that you can stack this on top of another promise. By doing this the other promise will receive the same all the events called on this promise, basically passing through the event downwards. Stack a promise on top of another promise using the event function of the promise being stacked on top of.
cerus.promise(function(event1) {
cerus.promise(function(event2) {
event2("done", "test");
})
.stack(event1);
})
.on("done", console.log);
// logs "test"
With this function you can create a handler that responds to all non-error events. The meaning of a handler is explained in the class description. You can also supply the event option which sets if the first argument when the handler is called is the name of the event. By default this is set to false.