aayega is a promises library compliant with promises / a+ spec
git clone https://github.com/rishabhio/aayega.git
npm install
npm test
Aayega is a promises library which is compliant with promises / A+ spec.
- Aayega is meant for educational and learning purposes.
- Aayega means "it will come" in hindi language and it is a good term to represent the result of an async operation.
- Goal is not to learn and implement the specification.
- Code readibility is the primary focus so new comers to A+ spec can use this as reference.
- Use of ES6 features.
It is advised to read the spec at least 5 times if you're like me :)
Following is what I got ater going through the spec for a few times.
By reading the spec a few times, we can easily draw the following inferences >>>
- Promise is nothing but a js object / functions which conforms to certain rules.
- Every promise has a then method
- Then method must return a new Promise
- then method takes 2 arguments
- There's a way called TPRP -> The Promise Resolution Procedure to be followed when resolving
- Every promise starts with a pending state
- Promise can move from pending -> fulfilled or pending -> rejected
- Once fulfilled / rejected, a promise can't change state.
- We need to provide an adapter for the testing to take place.
- We should install
promises-aplus-tests
to run the tests.
Our mission is to document almost every step which we take to make our promises library.
NOTE I'm writing these steps on the go so there can be a little up / down in the sequence , but the idea is to document most of the steps.
npm init
Run the above command and provide all the details.
-
lib
folder to store the code for our library -
tests
folder to store the adapter we write -
index.js
file is the entry point to the package
npm install --save-dev promises-aplus-tests
Create the following file in the tests folder.
aayega-adapter.js
check file aayega-adapter.js
for the relevant code.
// package.json
. . .
"test": "promises-aplus-tests tests/aayega-adapter"
. . .
First time you run npm test
, it will give 'Cannot find Module' error because we've not yet set
up the aayega module. Let's do that next.
aayega.js
// Initialize promise structure as per the spec
// Please read the inline comments in the code itself for better understanding.
In short we've to fill in the following structure :::::
This is how an Aayega
aka Promise looks like.
class Aayega {
constructor(asyncOp) {
const self = this;
this.value = null;
this.state = STATES.PENDING;
this.queue = [];
this.handlers = {
fulfill: null,
reject: null
};
if (asyncOp) {
asyncOp((value) => {
runPRP(self, value);
}, (reason) => {
self.reject(reason);
});
}
}
changeState(state, value) {
}
executeChain() {
}
reject(reason) {
}
fulfill(value) {
}
then(onFulfilled, onRejected) {
}
}
Section 2.3 is all about this. Please read the inline comments in code function
runPrp to get more details on it.
then takes onFulfilled , onRejected an returns a new promise which goes through the PRP via
the executeChain method in order to decide on how actually it needs to resolve.
I've used a quick / dirty hack to ensure the software can be made useful in browser environment as well.
if (typeof module !== 'undefined') {
if (typeof module.exports !== 'undefined') {
module.exports = Aayega;
}
} else {
window.Aayega = Aayega;
}
npm test
npm login
npm publish