2.6.8 • Published 1 year ago

fusion-plugin-universal-events v2.6.8

Weekly downloads
356
License
MIT
Repository
github
Last release
1 year ago

fusion-plugin-universal-events

Build status

The fusion-plugin-universal-events is commonly required by other Fusion.js plugins and is used as an event emitter for data such as statistics and analytics. This plugin captures events emitted from the client, sends them in batches to the server periodically, and allows the server to handle them. Note that due to the batched and fire-and-forget nature of the client-to-server event emission, this library is not suitable for timing-sensitive requests such as error logging or RPC calls.

It's useful for when you want to collect data about user actions or other metrics, and send them in bulk to the server to minimize the number of HTTP requests.

For convenience, this plugin automatically flushes its queue on page unload.

If you need to use the universal event emitter from React, use fusion-plugin-universal-events-react

Differences between UniversalEvents and other event emitter libraries

The UniversalEvents abstraction was designed to allow you to emit and react to events without worrying about whether you are on the server or the browser. It also provides the ability for observers to map event payloads to new ones. For example, you might want to add the some piece of context such as a session id to every event of a certain type.


Table of contents


Installation

yarn add fusion-plugin-universal-events

Usage

export default createPlugin({
  deps: {events: UniversalEventsToken},
  middleware: ({events}) => {
    events.on('some-event', (payload) => {
      console.log(payload)
    });
    events.on('some-scoped-event', (payload, ctx) => {
      console.log(payload)
    });
    events.emit('some-event', {some: 'payload'});
    return (ctx, next) => {
      const scoped = events.from(ctx);
      scoped.on('some-scoped-event', (payload, ctx) => {
        console.log(payload)
      });
      scoped.emit('some-scoped-event', {some: 'scoped-payload'});
    };
  },
});

Setup

// main.js
import React from 'react';
import App from 'fusion-react';
import UniversalEvents, {UniversalEventsToken} from 'fusion-plugin-universal-events';
import {FetchToken} from 'fusion-tokens';

export default function() {
  const app = new App();
  app.register(UniversalEventsToken, UniversalEvents);
  __BROWSER__ && app.register(FetchToken, window.fetch);
  return app;
}

API

Registration API

UniversalEvents
import UniversalEvents from 'fusion-plugin-universal-events';

The plugin. Provides the service API. Typically should be registered to UniversalEventsToken.

Dependencies

FetchToken
import {FetchToken} from 'fusion-tokens';
// ...
__BROWSER__ && app.register(FetchToken, window.fetch);

Required. Browser-only. See https://github.com/fusionjs/fusion-tokens#fetchtoken


Service API

events.on

Registers a callback to be called when an event of a type is emitted. Note that the callback will not be called if the event is emitted before the callback is registered.

events.on(type: string, callback: (payload: Object, ctx: ?Context, type: string) => void)
  • type: string - Required. The type of event to listen on. The type * denotes all events.
  • callback: (mappedPayload: Object, ctx: ?Context) => void - Required. Runs when an event of matching type occurs. Receives the payload after it has been transformed by mapper functions, as well an optional ctx object.

events.emit

events.emit(type:string, payload: Object)
  • type: string - Required. The type of event to emit. The type * denotes all events.
  • payload: Object - Optional. Data to be passed to event handlers

events.map

Mutates the payload. Useful if you need to modify the payload to include metrics or other meta data.

events.map(type: string, callback: (payload: Object, ctx: ?Context, type: string) => Object)
  • type: string - Required. The type of event to listen on. The type * denotes all events.
  • callback: (payload: Object, ctx: ?Context) => Object - Required. Runs when an event of matching type occurs. Should return a modified payload

events.flush

Flushes the data queue to the server immediately. Does not affect flush frequency

events.flush()

events.setFrequency

events.setFrequency(frequency: number)

Sets the frequency at which data is flushed to the server. Resets the interval timer.

  • frequency: number - Required.

events.teardown

events.teardown()

Stops the interval timer, clears the data queue and prevents any further data from being flushed to the server. Useful for testing

events.from

const scoped = events.from(ctx: Context);

Returns a scoped version of the events api.


Other examples

Event transformation

It's possible to transform event data with a mapping function, for example to attach a timestamp to all actions of a type.

events.map('user-action', payload => {
  return {...payload, time: new Date().getTime()};
});

events.on('user-action', payload => {
  console.log(payload); // logs {type: 'click', time: someTimestamp}
});

events.emit('user-action', {type: 'click'});

Accessing ctx

Event mappers and handlers take an optional second parameter ctx. For example:

events.on('type', (payload, ctx) => {
  //...
})

This parameter will be present when events are emitted from the ctx scoped EventsEmitter instance. For example:

app.middleware({events: UniversalEventsToken}, ({events}) => {
  events.on('some-scoped-event', (payload, ctx) => {});
  return (ctx, next) => {
    const scoped = events.from(ctx);
    scoped.emit('some-scoped-event', {some: 'payload'});
  };
});

* event type

* is a special event type which denotes all events. This allows you to add a mapper or handler to all events. For example:

events.map('*', payload => {
  //
});
2.6.8

1 year ago

2.6.5

1 year ago

2.6.7

1 year ago

2.6.6

1 year ago

2.6.1

1 year ago

2.6.0

1 year ago

2.6.3

1 year ago

2.6.2

1 year ago

2.5.2

2 years ago

2.5.3

2 years ago

2.6.4

1 year ago

2.5.1

2 years ago

2.4.1

2 years ago

2.4.0

2 years ago

2.5.0

2 years ago

2.3.6

2 years ago

2.3.5

2 years ago

2.3.2

2 years ago

2.3.4

2 years ago

2.3.3

2 years ago

2.3.1

2 years ago

2.3.0

3 years ago

2.2.0

3 years ago

2.1.12

3 years ago

2.1.11

3 years ago

2.1.10

3 years ago

2.1.9

3 years ago

2.1.8

3 years ago

2.1.7

3 years ago

2.1.6

4 years ago

2.1.5

4 years ago

2.1.4

4 years ago

2.1.3

4 years ago

2.1.2

4 years ago

2.1.1

4 years ago

2.1.0

4 years ago

2.0.10

4 years ago

2.0.9

4 years ago

2.0.8

4 years ago

2.0.7

5 years ago

2.0.6

5 years ago

2.0.5

5 years ago

2.0.4

5 years ago

2.0.3

5 years ago

2.0.2

5 years ago

2.0.1

5 years ago

2.0.0

5 years ago

1.3.4

5 years ago

1.3.4-0

5 years ago

1.3.3

5 years ago

1.3.3-0

5 years ago

1.3.2

5 years ago

1.3.1

5 years ago

1.3.1-1

5 years ago

1.3.1-0

5 years ago

1.3.0

5 years ago

1.3.0-0

5 years ago

1.2.1

5 years ago

1.2.0

6 years ago

1.1.0

6 years ago

1.6.0-0

6 years ago

1.0.5

6 years ago

1.0.4

6 years ago

1.0.3

6 years ago

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago

0.3.4

6 years ago

0.3.3

6 years ago

0.3.2

6 years ago

0.3.1

6 years ago

0.3.0

6 years ago

0.2.0

6 years ago

0.1.13

6 years ago

0.1.12

6 years ago

0.1.11

6 years ago

0.1.10

6 years ago

0.1.9

7 years ago

0.1.8

7 years ago

0.1.4

7 years ago

0.1.3

7 years ago

0.1.2

7 years ago

0.1.1

7 years ago

0.1.0

7 years ago