Promise-based Operations
SpRestLib exclusively utilizes JavaScript ES6 Promises for asynchronous SharePoint operations.
(New) ES6/ES2015 Promises vs (Old) Callbacks
SpRestLib asynchronous methods return Promises, which provide two main benefits:
- No more callback functions
- No more managing async operations
If you're unfamiliar with the new ES6 Promise functionality, you may want to the a moment to read more about them. They really are a game changer for those of us who deal with asynchronous operations.
All major browsers (and Node.js) now fully support ES6 Promises, so keep reading to see them in action.
tl;dr
Promises can be chained using then() or grouped using Promise.all() so callbacks and queue management are a thing of the past.
Async Chaining
- Promises can be chained so they execute in the order shown only after the previous one has completed
Example Logic
- SpRestLib methods return a Promise, meaning the "return sprestlib" calls below cause the subsequent
.then()to wait for that method's REST call to return a result - That's all you need to code to enable chaining of asynchronous operations without any callback functions or queue management!
Example Code
var item = { EmpName: 'Marty McFly', EmpNumb: 1001, HireDate: new Date() }; Promise.resolve() .then(function() { return sprLib.list('Employees').create(item); }) .then(function(item){ return sprLib.list('Employees').update(item); }) .then(function(item){ return sprLib.list('Employees').delete(item); }) .then(function(item){ console.log('Success! An item navigated the entire CRUD chain!'); }); Async Grouping
- Promises can be grouped using
.all()meaning each of them must complete before.then()is executed.
Example Logic
- This example requires that both the user info and user group queries complete before we move on
- The old AJAX callback method model required a lot more code to do this very thing!
Example Code
Promise.all([ sprLib.user().info(), sprLib.user().groups() ]) .then(function(arrResults){ // 'arrResults' holds the return values of both method calls above - in the order they were provided // Therefore, arrResults[0] holds user info() and arrResults[1] holds user groups() console.log( "Current User Info `Title`: " + arrResults[0].Title ); console.log( "Current User Groups count: " + arrResults[1].length ); });