Modules

Modules are how SDK capabilities are expanded, while still keeping the core lightweight and flexible.

This extensibility allows for integrating with third-party analytics/logging services, or your own custom backend ones with ease.

Integration use cases#

Modules can be used to support few different use cases:

• Transports: for sending events to various destinations
• Lookups: for reading information on demand in conditions and transforms
• Handlers: for executing custom code via effects
• Persistence: for persisting data across sessions in attributes and effects

Creating a module#

A module is a simple JavaScript object that has a few properties:

• name: unique identifier for the module (required)

and all these optional methods:

• lookup: function that returns a value for a given key
• transport: function that sends an event to a destination
• handle: function that executes custom logic
• readFromStorage: function that reads a value from a storage layer
• writeToStorage: function that writes a value to a storage layer
• removeFromStorage: function that removes a value from a storage layer

If we are sticking to JavaScript SDK, we can define a module like this:

export function createCustomModule() {
  return {
    name: "custom",
    /**
     * Lookup: used in conditions and transforms
     */
    lookup: async ({ key }) => {
      return "some value";
    },
    /**
     * Transport: used in destinations
     */
    transport: async ({ payload, eventName, destinationName }) => {
      // send the payload somewhere here...
    },
    /**
     * Handle: used in effects
     */
    handle: async ({ effectName, effect, step }) => {
      const { params } = step;
      console.log("Custom handler called for effect:", effectName);
    },
    /**
     * Persistence: used in attributes and effects
     */
    readFromStorage: async ({ key }) => {
      return "some value";
    },
    writeToStorage: async ({ key, value }) => {
      // write value to the storage layer here...
    },
    removeFromStorage: async ({ key }) => {
      // remove value from the storage layer here...
    },
  };
}

You are advised to have a function that returns the module object, so that it enables others to customize the module further as needed.

TypeScript usage#

You can make use of the Module type for type safety:

import { Module } from "@eventvisor/sdk";
export function createCustomModule(): Module {
  return {
    name: "custom",
    // ...
  };
}

Module setup#

Now we can register this module when initializing the SDK:

import { createInstance } from "@eventvisor/sdk";
import { createCustomModule } from "./custom";
const eventvisor = createInstance({
  modules: [
    createCustomModule(),
  ],
});

Usage examples#

Lookup#

Lookups can be performed in conditions and transforms:

conditions:
  - lookup: custom.myKey
    operator: equals
    value: myValue

Transport#

Transports can be used in destinations:

# ...
transport: custom

Handler#

Handlers can be used in effects:

# ...
steps:
  - handler: custom
    params:
      key: value

Persist#

Storage modules can be used to persist data across sessions:

# ...
persist: custom

Learn more in persistence page.