xyjax-events v1.0.47

About

xyjax-events is the standalone and lightweight system which provides events registering and emitting with custom arguments and custom event types. This package was originally developed for Xyjax NPM package.

Methods

There are three methods you can import:

1. register(eventType, targetId, handler)

Registers new targets for your custom event.

Arguments description:

• eventType is the string with your custom event type
• targetId is the string with registered target identifier
• handler is the unary function which takes eventArgs you pass when event is launched

2. unregister(eventType, targetId)

Unregisters targets from your custom event.

Arguments description:

• eventType is the string representation of your custom event type
• targetId is the string with registered target identifier

3. launch(eventType, targetId, eventArgs)

Launches given method for given target with given eventArgs payload.

Arguments description:

• eventType is the string representation of your custom event type
• targetId is the string with registered target identifier
• eventArgs is the object will be passed in handler

Usage example

Click here to take a look at RunKit + NPM embed example.

import { register, unregister, launch } from 'xyjax-events'

const testHandler = (eventArgs) => { console.log(JSON.stringify(eventArgs)) }
const testEventArgs = () => { return { eventArgField: Math.random() } }
const pathEventArgs = (path) => { return { currentPath: path } }

//registering test events
register('custom-event', 'target-1', testHandler)
register('custom-event', 'target-2', testHandler)
register('custom-event', 'starts-with...', testHandler)
register('custom-event', '...ends-with', testHandler)
register('custom-event', '...contains...', testHandler)

//launching test events
launch('custom-event', 'target-1', testEventArgs())
launch('custom-event', 'target-2', testEventArgs())
launch('custom-event', 'starts-with-1', pathEventArgs('starts-with-1'))
launch('custom-event', '1-ends-with', pathEventArgs('1-ends-with'))
launch('custom-event', '1-contains-2', pathEventArgs('1-contains-2'))

//example of unregistering
unregister('custom-event', 'target-1')

EventType, TargetIdentifier, Handler and EventArgs concepts

EventType is the type of current event you want to register/launch. Every type of event can be listened by any count of targets with given identifiers. When you register an event you also need handler in addition to EventType and TargetIdentifier. Handler is a function with one argument (which is EventArgs) that will be fired every time event of given type will be launched for given TargetIdentifier. When you launch an event you need to pass EventArgs which is any object.

Variating TargetIdentifiers

As you could see in example there is a possibility of having varied TargetIdentifier by adding triple dot at the beginning, at the end of the TargetIdentifier or both. There are four types of targetIds thereby:

• Exact
  • 'target-1' e.g.
  • Only given identifier will be observed
• Left-side varied
  • '...ends-with' e.g.
  • Every identifier which ends with given value will be observed
• Right-side varied
  • 'starts-with...' e.g.
  • Every identifier which starts with given value will be observed
• Both-sides varied
  • '...contains...' e.g.
  • Every identifier which contains given value as substring will be observed