A fast and simple Promise/A+ implementation capable of Node.js or browser-based
execution. Fidelity adheres to both the Promise/A+ specspecification, and the
ES6 Promise API in its entirety.
When used in the browser, a FidelityPromise object is created in the
global scope.
Usage
A fidelity promise behaves according to the
Promises/A+ specification. If you haven't read it,
it's worth your time and will probably make all of the fidelity documentation clearer.
You can create promises using the exported constructor.
You call the constructor function with an executor function as the only parameter. Typically this
function will perform some asynchronous task, and when that task has completed it will
resolve or reject the promise depending on whether or not the task completed successfully.
The executor function takes two function parameters: resolve and reject. These functions are
used to resolve or reject the promise as needed.
Suppose we have a function, someAsyncFunction() that takes some time to complete asynchronously.
We can call this function using a promise.
const Fidelity = require('fidelity');new Fidelity( (resolve, reject) => { someAsyncFunction((result, err) => { if (err) { reject(err); // The function produced an error. Reject the promise } else { resolve(result); // Fulfill the promise with the result } });}).then( (val) => { // This code executes after a promise has been fulfilled // Do something with the result.}).catch( (err) => { // This code executes if the promise was rejected});
Promise states
A promise will only ever be in one of three states. Fidelity.PENDING,
Fidelity.FULFILLED or Fidelity.REJECTED.
The fidelity module exports a constructor function for a Fidelity promise.
const Fidelity = require('fidelity');
new Fidelity(func)
A constructor function that creates and returns a promise. The func parameter is a function
that accepts a resolve and reject function.
Fidelity#then(onFulfilled, onRejected)
The 'then' function takes two function arguments. The first, onFulfilled,
is called with the return value (if any) of the promise function if it is
successfully fulfilled. The second function, onRejected is called in the
event of an error. A promise is returned in either case.
A static utility function which returns a promise that resolves when all
of the promises in the iterable argument have resolved, or rejects with
the reason of the first passed promise that rejects.
A static utility function which returns a promise that resolves or rejects as
soon as one of the promises in the iterable resolves or rejects, with the value
or reason from that promise.
A static utility function that Creates and returns a deferred object.
Deferred objects contain a promise which may
be resolved or rejected at some point in the future.
This module passes all of the tests in the
Promises/A+ Compliance Test Suite.
To run the full suite of the Promises/A+ spec, just npm test from the command line.
Benchmarks
It's pretty fast. Benchmarks are notoriously
a lot like statistics
so take this with a grain of salt. Results from a simplified, non-scientific benchmark
performed on a Macbook Pro on a random Friday afternoon. Your results may vary.
~/s/fidelity git:master ❯❯❯ npm run benchmark ✭ ✱> fidelity@4.0.0 benchmark /Users/lanceball/src/fidelity> node benchmark/benchmark.jsPID 48492benchmarking /Users/lanceball/src/fidelity/benchmark/benchmark.jsPlease be patient.{ http_parser: '2.7.0', node: '6.4.0', v8: '5.0.71.60', uv: '1.9.1', zlib: '1.2.8', ares: '1.10.1-DEV', icu: '57.1', modules: '48', openssl: '1.0.2h' }Scores: (bigger is better)new PromiseModule()Raw:> 2329.3943028485755> 2412.2008995502247> 2452.446776611694> 2293.376311844078> 2340.5667166416792> 2113.481259370315> 2416.1349325337333> 2405.9220389805096> 2391.76011994003> 2410.938530734633Average (mean) 2356.6221889055473new Fidelity PromiseRaw:> 1871.0824587706147> 1871.6251874062968> 1865.5232383808095> 1839.664167916042> 1796.8215892053972> 1675.2503748125937> 1740.119940029985> 1897.5412293853074> 1881.6611694152923> 1901.6221889055473Average (mean) 1834.0911544227888new Bluebird PromiseRaw:> 1632.1019490254873> 1551.352323838081> 1595.5382308845578> 1578.6686656671664> 1454.9025487256372> 1525.3313343328336> 1560.8305847076463> 1597.0914542728635> 1604.014992503748> 1622.920539730135Average (mean) 1572.2752623688157new native PromiseRaw:> 1212.9355322338831> 1245.9130434782608> 1228.9895052473762> 1222.1799100449775> 1224.9655172413793> 1092.1379310344828> 1216.5247376311845> 1252.335832083958> 1256.0899550224888> 1268.6986506746628Average (mean) 1222.0770614692656new QPromiseRaw:> 346.02998500749624> 344.01799100449773> 349.18440779610194> 350.70764617691157> 342.23306772908364> 315.39130434782606> 346.0569715142429> 354.5691462805791> 360.11094452773614> 350.7316341829085Average (mean) 345.9033098567384Winner: new PromiseModule()Compared with next highest (new Fidelity Promise), it's:22.17% faster1.28 times as fast0.11 order(s) of magnitude fasterA LITTLE FASTERCompared with the slowest (new QPromise), it's:85.32% faster6.81 times as fast0.83 order(s) of magnitude faster
Contributing
We encourage community contributions! Please read the
contributing guide if you would like to contribute to
this project.