Events

Events are the key part of Feathers real-time functionality. All events in Feathers are provided through the NodeJS EventEmitter interface. This section describes

Important: For more information on how to send real-time events to clients, see the Channels chapter.

EventEmitters

Once registered, any service gets turned into a standard NodeJS EventEmitter and can be used accordingly.

const messages = app.service('messages');

// Listen to a normal service event
messages.on('patched', message => console.log('message patched', message));

// Only listen to an event once
messsages.once('removed', message =>
  console.log('First time a message has been removed', message)
);

// A reference to a handler
const onCreatedListener = message => console.log('New message created', message);

// Listen `created` with a handler reference
messages.on('created', onCreatedListener);

// Unbind the `created` event listener
messages.removeListener('created', onCreatedListener);

// Send a custom event
messages.emit('customEvent', {
  type: 'customEvent',
  data: 'can be anything'
});

Service Events

Any service automaticaly emits created, updated, patched and removed events when the respective service method returns successfully. This works on the client as well as on the server. When the client is using Socket.io or Primus, events will be pushed automatically from the server to all connected client. This is essentially how Feathers does real-time.

ProTip: Events are not fired until all of your hooks have executed.

Important: For information on how those events are published for real-time updates to connected clients, see the channel chapter.

Additionally to the event data, all events also get the hook context from their method call passed as the second parameter.

created

The created event will fire with the result data when a service create returns successfully.

const feathers = require('@feathersjs/feathers');
const app = feathers();

app.use('/messages', {
  create(data, params) {
    return Promise.resolve(data);
  }
});

// Retrieve the wrapped service object which will be an event emitter
const messages = app.service('messages');

messages.on('created', (message, context) => console.log('created', message));

messages.create({
  text: 'We have to do something!'
});

updated, patched

The updated and patched events will fire with the callback data when a service update or patch method calls back successfully.

const feathers = require('@feathersjs/feathers');
const app = feathers();

app.use('/my/messages/', {
  update(id, data) {
    return Promise.resolve(data);
  },

  patch(id, data) {
    return Promise.resolve(data);
  }
});

const messages = app.service('my/messages');

messages.on('updated', (message, context) => console.log('updated', message));
messages.on('patched', message => console.log('patched', message));

messages.update(0, {
  text: 'updated message'
});

messages.patch(0, {
  text: 'patched message'
});

removed

The removed event will fire with the callback data when a service remove calls back successfully.

const feathers = require('@feathersjs/feathers');
const app = feathers();

app.use('/messages', {
  remove(id, params) {
    return Promise.resolve({ id });
  }
});

const messages = app.service('messages');

messages.on('removed', (message, context) => console.log('removed', message));
messages.remove(1);

Custom events

By default, real-time clients will only receive the standard events. However, it is possible to define a list of custom events on a service as service.events that should also be passed. The context for custom events won't be a full hook context but just an object containing { app, service, path, result }.

Important: The database adapters also take a list of custom events as an initialization option.

Important: Custom events can only be sent from the server to the client, not the other way (client to server). Learn more

For example, a payment service that sends status events to the client while processing a payment could look like this:

class PaymentService {
  constructor() {
    this.events = ['status'];
  },

  create(data, params) {
    createStripeCustomer(params.user).then(customer => {
      this.emit('status', { status: 'created' });
      return createPayment(data).then(result => {
        this.emit('status', { status: 'completed' });
      });
    });
  }
}

Now clients can listen to the <servicepath> status event. Custom events can be published just like standard events.

Is anything wrong, unclear, missing? Leave a comment or edit this page.

results matching ""

    No results matching ""