Promise

PreviousWhereClause.above()NextPromise.catch()

Promise

Represents an ECMAScript 6 compliant Promise/A+ implementation. All Dexie methods that return a Promise will return a Dexie.Promise rather than native Promise.

Syntax

return new Dexie.Promise(function (resolve, reject) {
    // Do something and call resolve / reject when done.
}).then(function (result) {
    // This code is called if resolve() was called in the Promise constructor
}).catch(function (error) {
    // This code is called if reject() was called in the Promise constructor, or
    // if an exception was thrown in either constructor or previous then() call.
}).finally(function () {
    // This code will be called no matter if an error occurred or not.
});

Description

Implementation of a Promise/A+ documented at .

See also Best Practices - Understand Promises

Why we don't use native Promise

As of May 2018, all modern browsers started supporting Promises withing IndexedDB transactions. So the initial reason for introducing an alternate Promise implemetation is not as accurate as before. At least in the long term as users move away from old browsers. However, we also use Dexie.Promise to interact with native promises in order to maintain transaction zones, so we still need to have Dexie.Promise accomplish that for us.

Interopability

db.cars.where('brand').equals('Volvo').then( function(cars) {
    // Post my cars to the server:
    return jQuery.ajax({
        url: "foobar",
        data: cars,
        type: 'post'
    }); // Another promise is returned
}).then(function(response) {
    // Handle successful ajax response
}).catch(function(error) {
    // Handle error
});

Do the other way around (this time a A+ compliant Promise needed):

new window.Promise(function(resolve, reject) {
    resolve("something");
}).then(function (x) {
    console.log(x);
    return db.cars.where('brand').equals('Volvo');
}).then( function(cars) {
    // Here we get the cars array from Dexie,
    // delivered through the standard Promise implementation.
    console.log(cars.join(JSON.stringify()));
}).catch(function(error) {
    // Handle error standardized
});

...but avoid it within transactions:

db.transaction('rw', db.cars, function () {
    //
    // Transaction block
    //
    db.cars.put({id: 3}).then (function() {
        // Avoid returning other kinds of promises here:
        return new Bluebird(function(resolve, reject){
            resolve();
        });
    }).then(function() {
        // You'll successfully end-up here, but any further call to db
        // will fail with "Transaction Inactive" error.
        return db.cars.get(3); // WILL FAIL WITH TRANSACTION INACTIVE!
    });
});

window.Promise is always safe to use within transactions, as Dexie will patch the global Promise within the transaction zone, but leave it untouched outside the zone.

Methods

catch()

finally()

Static Methods

Promise.newPSD()

Static Properties

PSD

Events

onuncatched

Deprecated. Use window.addEventListener('unhandledrejection')

Promise.on('error')

Deprecated. Use window.addEventListener('unhandledrejection')

Implementation Details

This implementation executes a virtual Micro Task engine when possible, that replaces the need for calling setImmediate (), setTimeout(), etc.. This is needed only when dealing with indexedDB transactions in older browsers where native promises don't cope with indexedDB transactions See issue #317. It does this without sacrificing A+ compliance since the microtick engine can be considered part of the host system and is invisible and undetectable from the user.

PreviousWhereClause.above()NextPromise.catch()