Table.hook('reading')

NOTE: Since Dexie 3.0, there is a new API superior to this hooks API: DBCore. There is NO PLAN for deprecation of this hooks API though, but it in future, we may extract this API to an addon.

Syntax

db.[tableName].hook('reading', function (obj) {
    // You may return another object or modify existing object.
});

Parameters

Return Value

The subscriber must return the resulting object. If not modifying the object, subscriber must return the given obj instance. If modifying or replacing object, return the new object or modified existing object.

To Unsubscribe

db.[tableName].hook('reading').unsubscribe(yourListenerFunction)

Description

This event is called whenever an object is about to be returned from database to the caller of Table.get() or any Collection method that yields database objects, but not methods with a filtering or modification purpose such as Table.filter() or Table.modify(). Specifically, hook('reading') will filter objects returned by:

• Table.get()

• Table.toArray()

• Table.each()

• Collection.toArray()

• Collection.sortBy()

• Collection.each()

• Collection.first()

• Collection.last()

But not for:

• The callback given to Table.filter()

• The callback given to Collection.and()

• The callback given to Collection.modify()

Error Handling

If subscriber throws an exception, the read operation will fail and the caller of the read operation will get the failure as a Promise rejection that may be caught/handled or not. If the caller of the read operation does not catch the exception using Promise.catch(), the transaction will be aborted.

Use Cases of the CRUD events

Dexie CRUD events can be used to implement several addons to Dexie such as:

• Server Synchronization

• Automatic primary key generation

• Full-text search or other custom ways of indexing properties

• Manipulation of returned objects

The add-ons Dexie.Observable.js and Dexie.Syncable.js uses hook('creating'), hook('updating') and hook('deleting') to make the database locally observable as well as syncable with a remote server.

The hook('reading') is used internally by Dexie.js by the methods Table.defineClass() and Table.mapToClass() in order to make all objects retrieved from database inherit a given class using prototypal inheritance.

See Also

Table.hook('creating')

Table.hook('updating')

Table.hook('deleting')

Dexie.Observable.js