npm package: @scottburch/rxjs-msg-bus
Description: A central message bus implimentation for rxjs.
Latest version: 1.2.1

# Rxjs-msg-bus

A central message bus implimentation for rxjs.  

The central msg bus is implimented as a singleton where you can add listeners and fire events.

### Defining messages

Messages are defined using a `Msg` type.  The first argument in the type is the string by which this event will be known.  The second is the data type for the data sent with the event.

```type MyCustomEvent = Msg<'my-custom-event', {name: string}>```



### Listening for and firing events

Listeners take a message type and pass back a rxjs observable like this.
```typescript
type NameEnteredEvent = Msg<'name-entered-event', string>


eventListener<NameEnteredEvent>('name-entered-event').subscribe(name => console.log(name)); // Johnny Five
fireEvent<NameEnteredEvent('name-entered-event', 'Johnny Five');
```

Events are async, they will be fired in the future.  There are several other listener functions to fit other scenarios that are described below

### Installing

`yarn add @scottburch/rxjs-msg-bus`

`npm install @scottburch/rxjs-msg-bus`



### Logging events

You can log events for easier troubleshooting by listening to the central bus and console logging the messages.

```typescript
getCentralMsgBus().subscribe(console.log);
```



### API

##### `Msg<[msg-type-string], [msg-data-type]>`

Defines a message type

```typescript
type UserLoggedInEvent = Msg<'user-logged-in', {username: string, rememberMe: boolean}>
```



##### `sendEvent<[MsgType]>([msg-type-string], [data]);`

Sends an event of `MsgType`containing `data`
```typescript
type UserLoggedInEvent = Msg<'user-logged-in', {username: string, rememberMe: boolean}>;

eventListener<UserLoggedInEvent('user-logged-in').pipe(
	tap(data => verifyUser(data))
).subscribe();

fireEvent<UserLoggedInEvent('user-logged-in', {username: 'scott', rememberMe: true});
```



###### `eventListener<[MsgType]>([msg-type-string]);`

Listens for an event

```typescript
type UserLoggedInEvent = Msg<'user-logged-in', {username: string, rememberMe: boolean}>;

eventListener<UserLoggedInEvent('user-logged-in').pipe(
	tap(data => verifyUser(data))
).subscribe();

fireEvent<UserLoggedInEvent('user-logged-in', {username: 'scott', rememberMe: true});
```



###### `eventListenerOnce<[MsgType]>([msg-type-string]);`

Same as `eventListener`except it only fires once and then unsubscribes.



###### `eventListenerMatchOnce<[MsgType]>([msg-type-string], data => true/false)`

Same as eventListenerOnce except it takes a matcher function.  If the function returns true, the rest of the code is run and the listener is unsubscribed.
```typescript
type UserReadEvent = Msg<'user-read', UserId>;

eventListenerMatchOnce<UserReadEvent>('user-read', userId => userId === '12345').subscribe(
  // only user 12345 will show up here
)

fireEvent<UserReadEvent>('user-read', '22222')  // will not trigger listener code
fireEvent<UserReadEvent>('user-read', '12345')  // will trigger listener code
```



###### `sendEventPartial<[MsgType]>([msg-type-string]);`

Same as `sendEvent`except it is a curried function where the result is partially applied
```typescript
type UserLoggedInEvent = Msg<'user-logged-in', {username: string}>
type ReadUser = Msg<'read-user', User>

eventListener<UserLoggedInEvent>('user-logged-in').subscribe(sendEventPartial<ReadUser>('read-user'));
```