mikroevent
Version:
Ultra-lightweight, Node-native way to handle events, both in-process (as EventEmitter events) or across systems via HTTP(S).
102 lines (99 loc) • 4.14 kB
text/typescript
import { MikroEventOptions, Target, TargetUpdate, EmitResult } from './interfaces/index.mjs';
/**
* @description MikroEvent is an ultra-lightweight, Node-native
* way to handle events, both in-process (as EventEmitter events)
* or across systems via HTTP(S) using Fetch.
*
* @example
* const events = new MikroEvent();
*
* events.addTarget({ name: 'internal', events: ['user.created'] });
* events.addTarget({ name: 'external', url: 'https://api.mydomain.com', events: ['user.created'] });
*
* const handler = () => { console.log('This runs in response to the user.created event') };
* events.on('user.created', handler);
*
* await events.emit('user.created', { id: '123', name: 'Test User' });
*/
declare class MikroEvent {
private emitter;
private targets;
private options;
constructor(options?: MikroEventOptions);
/**
* @description Add one or more Targets for events.
* @example
* // Add single Target that is triggered on all events
* events.addTarget({ name: 'my-internal-api', events: ['*'] });
* // Add single Target using HTTPS fetch
* events.addTarget({ name: 'my-external-api', url: 'https://api.mydomain.com', events: ['*'] });
* // Add multiple Targets, responding to multiple events (single Target shown)
* events.addTarget([{ name: 'my-interla-api', events: ['user.added', 'user.updated'] }]);
* @returns Boolean that expresses if all Targets were successfully added.
*/
addTarget(target: Target | Target[]): boolean;
/**
* @description Update an existing Target.
* @example
* events.updateTarget('system_a', { url: 'http://localhost:8000', events: ['user.updated'] };
* @returns Boolean that expresses if the Target was successfully added.
*/
updateTarget(name: string, update: TargetUpdate): boolean;
/**
* @description Remove a Target.
* @example
* events.removeTarget('system_a');
* @returns Boolean that expresses if the Target was successfully removed.
*/
removeTarget(name: string): boolean;
/**
* @description Add one or more events to an existing Target.
* @example
* events.addEventToTarget('system_a', ['user.updated', 'user.deleted']);
* @returns Boolean that expresses if all events were successfully added.
*/
addEventToTarget(name: string, events: string | string[]): boolean;
/**
* @description Register an event handler for internal events.
*/
on<T = any>(eventName: string, handler: (data: T) => void | Promise<void>): this;
/**
* @description Remove an event handler.
*/
off<T = any>(eventName: string, handler: (data: T) => void | Promise<void>): this;
/**
* @description Register a one-time event handler.
*/
once<T = any>(eventName: string, handler: (data: T) => void | Promise<void>): this;
/**
* @description Emit an event locally and to its bound Targets.
* @example
* await events.emit('user.added', { id: 'abc123', name: 'Sam Person' });
* @return Returns a result object with success status and any errors.
*/
emit<T = any>(eventName: string, data: T): Promise<EmitResult>;
/**
* @description Handle an incoming event arriving over HTTP.
* Used for server integrations, when you want to manually handle
* the incoming event payload.
*
* The processing will be async using `process.nextTick()`
* and running in a non-blocking fashion.
* @example
* await mikroEvent.handleIncomingEvent({
* eventName: 'user.created',
* data: { id: '123', name: 'Test User' }
* });
*/
handleIncomingEvent(body: string | object): Promise<void>;
/**
* @description Create middleware for Express-style servers, i.e.
* using `req` and `res` objects. This is an approach that replaces
* using `handleIncomingEvent()` manually.
* @example
* const middleware = mikroEvent.createMiddleware();
* await middleware(req, res, next);
*/
createMiddleware(): (req: any, res: any, next?: Function) => Promise<void>;
}
export { MikroEvent };