Package Exports

secure-event-emitter
secure-event-emitter/index.js
secure-event-emitter/react
secure-event-emitter/react/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (secure-event-emitter) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Secure Event Emitter

You can find the full documentation on the https://secure-event-emitter.js.org

secure-event-emitter is a tiny javascript package that uses restrict rules and mechanisms to build safer and protected event-driven architecture. It's similar to nodejs EventEmitter, but dictates stricter rules to prevent misuse.

The Main Features

All event types must be predefined․
Not possible to call the emit() method anywhere without the emitterKey.
Ability to validate emitted values․

Installation

npm install secure-event-emitter

SecureEventEmitter

SecureEventEmitter is the main constructor for creating emitter instances.

Import

import {SecureEventEmitter} from 'secure-event-emitter'

Syntax

`new SecureEventEmitter(eventTypes, emitterKey, validator?)`

eventTypes <string[]>
An non-empty array of all event types.
emitterKey <string> | <symbol>
Any string or symbol value without which we won't be able to call the .emit() method.
validator <Function>
Function to validate the emitted values․ The function receives the emitted values in the argument and returns an error message if something is wrong there.

Usage

import {SecureEventEmitter} from 'secure-event-emitter'

const eventTypes = ['event-1', 'event-2']
const emitterKey = Symbol()

const myEmitter = new SecureEventEmitter(eventTypes, emitterKey)

myEmitter.on('event-1', (a, b) => {
    console.log(a, b)
})

myEmitter.on('event-2', (x) => {
    console.log(x)
})

myEmitter.unlock(emitterKey).emit('event-1', 2021, 2022)
myEmitter.unlock(emitterKey).emit('event-2', 123)

Validator

We can define a validator function to validate the emitted values.

The function receives the emitted values in the argument and returns an error message if something is wrong there.

Example

This example defines a validator function that ensures that the emitter can emit only numbers.

const validator = (x) => {
    if (typeof x !== 'number') {
        return 'Can emit only numbers!' // error message
    }
}

Usage

import {SecureEventEmitter} from 'secure-event-emitter'

const eventTypes = ['event-1']
const emitterKey = Symbol()
const validator = (x) => {
    if (typeof x !== 'number') {
        return 'Can emit only numbers!' // error message
    }
}

const myEmitter = new SecureEventEmitter(eventTypes, emitterKey, validator)

myEmitter.on('event-1', (a) => {
    console.log(a)
})


myEmitter.unlock(emitterKey).emit('event-1', 2021)
myEmitter.unlock(emitterKey).emit('event-1', '2021') // TypeError: Can emit only numbers!

SingularEventEmitter

SingularEventEmitter is a special case of SecureEventEmitter where each emitter is designed to trigger one type of event․

basic usage

import {SingularEventEmitter} from 'secure-event-emitter'

// create emitterKey
const emitterKey = Symbol('My Singular Emitter Key')

// create onFoo instance
const onFoo = new SingularEventEmitter(
    emitterKey      // emitter key is an any Symbol type value
)

// add listeners
onFoo.on((a) => {
    // ...
})
onFoo.on((a) => {
    // ...
})


onFoo.unlock(emitterKey).emit(2021)
onFoo.unlock(emitterKey).emit(2022)

Payload

Payload is a class with which we can create objects that meet certain standards

basic usage

import {Payload} from 'secure-event-emitter'

// first argument is an origin, can be only symbol type and required
const payload_1 = new Payload(Symbol('My Origin 1'), 1, 2, 3)
// {
//     origin: Symbol('My Origin 1'),
//     args: [1, 2, 3],
//     meta: {
//         date: 545125412152,
//         _index: 1
//     }
// }

const payload_2 = new Payload(Symbol('My Origin 2'), 'a', 'b')
// {
//     origin: Symbol('My Origin 2'),
//     args: [1, 2, 3],
//     meta: {
//         date: 54512541999,
//         _index: 1
//     }
// }

Handler

Handler is a decorator function that accepts a function and returns a function that can only accept Payload instances in its argument.

basic usage

import {Handler, Payload} from 'secure-event-emitter'

const myHandler = Handler((payload) => {
    // ...
})

myHandler(new Payload(Symbol('my origin'), 1, 2, 3)) // OK
myHandler(2021) // TypeError('handler argument type must be a [[Payload]] class objects')

useListener

useListener is a helper hook for use emitter in react component

basic usage

import {useListener} from 'secure-event-emitter/react'

// ...
// ...
useListener(emitter, 'event-type', () => {
    // ...
})
// ...
// ...

Authors

Ruben Arushanyan

License

MIT