static extend(options, obj, dc) {
        if (typeof options.extend === 'function') {
            try {
                options.extend.call(obj, obj, dc);
            } catch (e) {
                // have to silence errors here;
                // the result of throwing unhandled errors while
                // extending the protocol would be unpredictable.
                Events.unexpected('extend', e);
            }
        }
    }
@event extend
@description
Extends {@link Database} protocol with custom methods and properties.

Override this event to extend the existing access layer with your own functions and
properties best suited for your application.

The extension thus becomes available across all access layers:

- Within the root/default database protocol;
- Inside transactions, including nested ones;
- Inside tasks, including nested ones.

All pre-defined methods and properties are read-only, so you will get an error,
if you try overriding them.

The library will suppress any error thrown by the handler and write it into the console.

@param {object} obj - Protocol object to be extended.

@param {*} dc - Database Context that was used when creating the {@link Database} object.

@see $[pg-promise-demo]

@example

// In the example below we extend the protocol with function `addImage`
// that will insert one binary image and resolve with the new record id.

const initOptions = {

    // pg-promise initialization options...

    extend(obj, dc) {
        // dc = database context;
        obj.addImage = data => {
            // adds a new image and resolves with its record id:
            return obj.one('INSERT INTO images(data) VALUES($1) RETURNING id', data, a => a.id);
        }
    }
};

@example

// It is best to extend the protocol by adding whole entity repositories to it as shown in the following example.
// For a comprehensive example see https://github.com/vitaly-t/pg-promise-demo

class UsersRepository {
    constructor(rep, pgp) {
        this.rep = rep;
        this.pgp = pgp;
    }

    add(name) {
        return this.rep.one('INSERT INTO users(name) VALUES($1) RETURNING id', name, a => a.id);
    }

    remove(id) {
        return this.rep.none('DELETE FROM users WHERE id = $1', id);
    }
}

// Overriding 'extend' event;
const initOptions = {

    // pg-promise initialization options...

    extend(obj, dc) {
        // dc = database context;
        obj.users = new UsersRepository(obj, pgp);
        // You can set different repositories based on `dc`
    }
};

// Usage example:
db.users.add('John', true)
    .then(id => {
        // user added successfully, id = new user's id
    })
    .catch(error => {
        // failed to add the user;
    });