Promise polyfill for Wakanda

The WPromise "custom widget" Polyfill some of the main frontend Wakanda Asynchronous APIs to a Promisified version. It uses the Bluebird custom widget based on the Bluebird Library.

How to Install

You can install the WPromise widget by using the Add-ons Extension.

For more information, refer to the Installing a Custom Widget manual.

How to Use

Drag & drop the WPromise widget on your Wakanda Page. It will automatically Promisify the supported Wakanda Framework APIs.

RPC example

Let say you have an hello RPC CommonJS module on your Wakanda Server that exports a helloWorld() method. From the frontend, WPromise will let you call it this way:

    hello.helloWorld().then(function success(result) {
    	alert(result);
    });

Datasource example

Let say you have an employee datasource on your page. WPromise will let you make a query this way:

    WAF.sources.employee.query('salary > 50000').then(function success(event) {
    	alert(event.dataSource.length);
    });

Properties

This widget has the following properties:

Active: Globally activate/disactivate the Promise polyfills
Rpc: Makes the Wakanda Rpc methods results usable as Promises
Dataprovider: Makes the WakandaDB frontend Data Provider API Promises compliant
Datasource: Makes the WakandaDB frontend DataSource API Promises compliant
Autorun Tests: Automatically run the unit tests if a QUnit widget is on the page

Methods

If you want to check the result of this custom widget, you can manually run the unit tests

runTestSuites(): Manually run the unit tests if a QUnit widget is on the page

You may also choose to not activate the global APIs polyfills but to polyfil manually specific objects/methods only when it makes sense. It can be faster as there is then less initialisation time required. It can be very useful to parallelise or chain existing promise results with Wakanda async API results.

Two methods are then available for that:

promisify(context, methodName[, resultHook]): return a promisified version of the method
thenify(context, methodName[, resultHook]): return a thenified version of the method

thenify() is a safest version of promisify() which instead of returning a real promise, returns the same object as the original method, extended with promise then() and `catch() methods.

promisify() & thenify() Arguments

context: the object to which belongs the method
methodName: the method you want to return a promise
[resultHook]: (optional) a callback to refactor the method result

resultHook is used by WPromise to automatically promisify or thenify async methods of a returned object result

Dataprovider Example

    var polyfill = WAF.widgets.wPromises1;
	var empQuery = polyfill.thenify(ds.Employee, 'query');
	// you can now do
    empQuery('age > :1', {params: [25]}).then(function success(result) {
    	alert('success:' + result);
    }).catch(function (error) {
		alert('error:' + error);
	});

References

Wakanda APIs

Standard

ECMAScript 2015 Promises

Tutorials

Todo

Few things that could be enhanced in this project

larger documentation
larger unit tests coverage
Wakanda Component Widget API (load/remove) Promisification
Wakanda File Upload Widget API Promisification
Wakanda Directory API Promisification

About Wakanda Custom Widgets

For more information about creating a custom widget, refer to the Widgets v2 Creating a Widget manual.

License

This widget is available under the Mozilla Public License v2.0

It allows usage of this widget with either:

a modified BSD license (a bit MIT oriented),
the GNU General Public License, Version 2.0 (GPLv2),
the GNU Lesser General Public License, Version 2.1 (LGPLv2.1),
the GNU Affero General Public License, Version 3.0 (AGPLv3),
or any later versions of those licenses

More informations about the "Mozilla Public License" on Wikipedia

rmello4d/WPromises