npm package: @osmium/events
Description: Events library
Author: Vasiliy Isaichkin
Latest version: 0.11.3

# Osmium Events - Async event dispatcher (readme in progress)

## About

`@osmium/events` - is a TypeScript/JS library of universal event dispatcher with support for asynchrony, middlewares,
event mapping between different library instances and many other things. Support nodejs & browser (has bundled js.min version with all depends).

This project is released under MIT license.

## How to use?

...

```
// Example here
```

## Events handlers and emitters

...

```
// Example here
```

## Middlewares

...

```
// Example here
```

## Event mappings

...

```
// Example here
```

## API

### Classes

#### new Events

`Events<EventNameType = string | number | symbol, MiddlewareMetadataType extends Record<string, unknown>>(config: Events.ConfigOptionable = {}, mapEmitOnce: Events<EventNameType> | null = null)`

Creates an event dispatcher instance.

`<EventNameType>` - defines the type of event names used. Any types can be used (actually the event name is the key in `Map<EventNameType,...>`).
By default is `string | number | symbol`

`config` - Instance configuration

##### Events.ConfigOptionable

```
{
	metadata?        : MiddlewareMetadata; //      
	defaultChain?    : boolean;            //
	instanceIdPrefix?: string;             //
	instanceIdMask?  : string;             //
	eventIdPrefix?   : string;             //
	eventIdPrefixMW? : string;             //
	eventIdMask?     : string;             //
}
```

`mapEmitOnce` - ...

### API - Event handlers

#### on

`on<ArgsType extends any[] = any[], ReturnType = any, ThisExtType extends object = {}>(name: Events.EventName<EventNameType>, cb: Events.EventCallback<EventNameType, ArgsType, ReturnType, ThisExtType>): Events.EventId`

Register event handler

```
	// Example here
```

#### once

`once<ArgsType extends any[] = any[], ReturnType = any, ThisExtType extends object = {}>(name: Events.EventName<EventNameType>, cb: Events.EventCallback<EventNameType, ArgsType, ReturnType, ThisExtType>): Events.EventId`

Register event and self-remove after first call

```
	// Example here
```

#### wait

`wait<ReturnType extends [] = []>(name: Events.EventName<EventNameType>, timeout: number = -1): Promise<ReturnType | null>`

Await event emit

```
	// Example here
```

#### offById

`offById(targetId: Events.EventId | Events.EventIds): Events.AffectedEventId | Events.AffectedEventIds`

Remove event by EventId or array of EventId

```
	// Example here
```

#### off

`off(name: Events.EventName<EventNameType>): Events.AffectedEventIds | null`

Remove event by EventName

```
	// Example here
```

### API - Event emits

#### emit

`async emit<ArgsType extends any[] = any[], ReturnType = unknown>(name: Events.EventName<EventNameType>, ...args: ArgsType): Promise<Events.EmitResult<ReturnType>>`

Event emit (call)

```
	// Example here
```

#### emitParallel

`async emitParallel<ArgsType extends any[] = any[], ReturnType = unknown>(name: Events.EventName<EventNameType>, ...args: ArgsType): Promise<Events.EmitResult<ReturnType>>`

Event emit (call) as parallel (via `Promise.all`)

```
	// Example here
```

#### emitChain

`async emitChain<ArgsType extends any[] = any[], ReturnType = unknown>(name: Events.EventName<EventNameType>, ...args: ArgsType): Promise<Events.EmitResult<ReturnType>>`

Event emit (call) as chain (one by one)

```
	// Example here
```

#### emitOnce

`async emitOnce<ArgsType extends any[] = any[], ReturnType = unknown>(name: Events.EventName<EventNameType>, ...args: ArgsType): Promise<ReturnType | undefined>`

Event emit (call) and return first value

```
	// Example here
```

#### emitEx

`async emitEx<ArgsType extends any[] = any[], ReturnType = unknown>`

Advanced event emit

```
	// Example here
```

### API - Tools/others

#### clear

`clear(): void`

Clear all events

```
new e = new Events();
e.on('test',()=>{
	console.log('Test called');
});

e.emit('test');  // 'Test called' in console
e.clear();
e.emit('test');  // Nope
```

#### reset

`reset(): void`

Reset all (events, mappings, middlewares), like new Events().

```
	// Example here
```

#### getEvents

`getEvents(findStr: string | RegExp | null = null): Events.EventNames<EventNameType>`

Get events names by RegExp pattern.

Will try to cast the event name to a `string` type (so that RegExp can work) using `?.toString()`, if that doesn't work, it will skip that event name for out list.

```
	// Example here
```

#### exists

`exists(what: Events.EventName<EventNameType> | RegExp, inMappingsToo: boolean = false): boolean`

Check event exists

```
	// Example here
```

### API - Middlewares

#### useBefore

`useBefore(handler: Events.MiddlewareBeforeCallback<EventNameType>, position: number | null = null): number`

Add 'before' middleware

```
	// Example here
```

#### unUseBefore

`unUseBefore(handlerPosition: number): void`

Remove 'before' middleware by MiddlewareBefore position

```
	// Example here
```

#### useAfter

`useAfter(handler: Events.MiddlewareAfterCallback<EventNameType>, position: number | null = null): number`

Add 'after' middleware

```
	// Example here
```

#### unUseAfter

unUseAfter(handlerPosition: number): void

Remove 'after' middleware by MiddlewareAfter id

```
	// Example here
```

### API - Event mapping

#### mapEventsBefore

`mapEventsBefore(target: Events<EventNameType>, list: Events.EventNames<EventNameType> | null = null): void`

Map events 'before' by list, or all if not defined

```
	// Example here
```

#### unMapEventsBefore

`unMapEventsBefore(target: Events<EventNameType>, list: Events.EventNames<EventNameType> | null = null): void`

Remove 'before' event mapper by list, or all if not defined

```
	// Example here
```

#### mapEventsAfter

`mapEventsAfter(target: Events<EventNameType>, list: Events.EventNames<EventNameType> | null = null): void`

Map events 'after' by list, or all if not defined

```
	// Example here
```

#### unMapEventsAfter

`unMapEventsAfter(target: Events<EventNameType>, list: Events.EventNames<EventNameType> | null = null): void`

Remove 'after' event mapper by list, or all if not defined

```
	// Example here
```