Package Exports
- pubchan
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 (pubchan) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
pubchan
Simple yet powerful pub/sub channels for Javascript and Node.js.
Tiny, fast, and reliable pubsub event emitter with promises, optional result aggregation (state), and async/sync controls.
Install
yarn add pubchanor
npm install --save pubchan100% Flow Coverage
Proudly built with 100% Flow Coverage and exported .flow.js files so your flow projects will benefit!
We strongly recommend you look over the types folder. This will give you an idea of how the various pieces of the package work.
Example
Simple
/* @flow */
import createPubChan from 'pubchan';
const chan = createPubChan();
chan
.subscribe({ async: true })
.to('foo')
.do(() => console.log('foo 1!'));
chan
.subscribe()
.to('foo')
.do(() => console.log('foo 2!'));
chan
.emit('foo')
.send()
.then(() => console.log('Finished Emitting foo!'));
/*
// Console Output -->
foo 2!
foo 1!
Finished Emitting foo!
*/More Examples
For more examples you can check out the examples directory
API Reference
Note: This is currently a work in progress. The API is quite simple and can be understood by looking at our types files as this packages has 100% flowtype coverage.
Module Exports
createPubChan (Function) (default)
Our default export, creates an instance of PubChan.
import createPubChan from 'pubchan'
const chan = createPubChan()PubChan (Class)
Generally using the createPubChan function is the recommended method of creating a new channel. However, you can also import the class directly if needed (can be useful for adding as flow type).
import { PubChan } from 'pubchan'
const chan = new PubChan()Subscriber (Class)
This should have no use other than possibly to use for flow-types. A subscriber is useless unless created by an interface which matches the PubChan.
/* @flow */
import type { Subscriber } from 'pubchan'PubChan
Below is a normalized version of the PubChan class which should provide the structure of the instance returned by our createPubChan factory.
declare class PubChan {
pipeline: {
emit: Set<mixed>,
matches: Set<Subscriber>,
with: Array<mixed>,
},
+listeners: Map<mixed, Set<Subscriber>>,
+subscribers: Set<Subscriber>,
// how many total active subscribers do we have?
get length(): number,
get size(): number,
emit: (...args: Array<Array<mixed> | mixed>) => this,
// include args with the event emission
with: (...args: Array<any>) => this,
// send the event and optionally include args to the handlers.
send: (...args: Array<any>) => Promise<null> | Promise<Array<any>>,
close: (...args: Array<any>) => Promise<null> | Promise<Array<any>>,
subscribe: (
options?: $Shape<{|
async: boolean,
|}>,
) => Subscriber,
}Subscriber
Subscriber instances are returned by a call to .subscribe() on our PubChan instance.
declare type PubChan$EmitID = mixed;
type Callback = (
ref: PubChan$Ref,
ids: Set<PubChan$EmitID>,
...args: Array<mixed>
) => Array<mixed> | mixed;
declare type PubChan$Callback = Array<Callback> | Callback;
// called immediately after creating the subscription (not when the
// subscription is cancelled)
declare type PubChan$CompleteCallback = (ref: PubChan$Ref) => mixed;
declare interface PubChan$Ref {
+once?: void | boolean,
+id?: PubChan$EmitID,
+state: { [key: string]: * },
+subscription: Subscriber,
+chan: PubChan,
+callback: PubChan$Callback,
+cancel: () => void,
}
declare class Subscriber {
// total number of active callbacks on the subscriber
get length(): number,
get size(): number,
// all the ids we are subscribed to
get keys(): Array<PubChan$EmitID>,
// subscribe to EmitIDS
to: (...args: Array<PubChan$EmitIDs>) => this,
// add a callback that will happen once then cancel itself
once: (
callback: PubChan$Callback,
onComplete?: PubChan$CompleteCallback,
) => this,
// add a callback when this event occurs
do: (
callback: PubChan$Callback,
onComplete?: PubChan$CompleteCallback,
) => this,
// cancel the entire subscriber
cancel: () => void,
}