Stræm is a minimal wrapper for the Custom Event API.
To use Stræm with npm and/or a bundler such as webpack or rollup, install it via yarn or npm:
yarn add straemjs
# or use npm
npm install straemjs
You can also use it directly in the browser and include it via CDN (or locally, if you like).
<head>
...
<!-- as a local file -->
<script src="./your/path/to/straem.browser.min.js"></script>
<!-- or via CDN -->
<script src="http://unpkg.com/straemjs"></script>
...
</head>
Stræm provides exports for modern import
syntax as well as exports for the require
syntax.
// node require syntax
const { receive, dispatch } = require('straemjs');
// modern es6 style syntax
import { receive, dispatch } from 'straemjs';
In case you included the Stræm file via CDN, the straem
object is globally available.
const { receive, dispatch } = straem;
To receive and listen to custom (or built-in) event, use the receive()
method
import { receive } from 'straemjs';
// Use the receive method to register one or more event names for the listener
const listener = receive('custom-event', 'another-event');
// You can use the 'from' method to set the target of the event
const listener = receive('custom-event').from(window);
// To create the listener(s) and register a callback, use the 'then' method returned by
// either the 'receive' or 'from' method and pass a handler and an optional opinions object.
// The method returns a function to remove the created listener(s).
const dispose = receive('custom-event').then(handler, eventInit);
To dispatch a custom event, use the dispatch()
method.
import { dispatch } from 'straemjs';
// Use the dispatch method to register one ore more event names for dispatching.
// As with the receive method, you can chain the from method to set the target.
const send = dispatch('custom-event').from(window);
// Use the 'with' method to dispatch the event with a given payload.
send.with({ hello: 'world' });
Type: receive(...string: string[]) => { from: Function, then: Function, eventTarget: EventTarget, eventNames: string[] }
The receive method is used to create a custom event listener. Pass any number of strings as argument. The method returns the Receiver
object, containing the from()
, then()
, eventTarget
& eventNames
properties.
Type: dispatch(...string: string[]) => { from: Function, with: Function, eventTarget: EventTarget, eventNames: string[] }
The dispatch method is used to create a custom event dispatcher. Pass any number of strings as argument. The method returns the Dispatcher
object, containing the from()
, with()
, eventTarget
& eventNames
properties.
Type: from(eventTarget: EventTarget) => { this }
The from method is used to set the eventTarget of the receive()
of dispatch()
methods. The method will return the receive of dispatch object, respective of the method that it was called from.
Type: then<T>(action: Action<T>, eventInit?: AddEventListenerOptions) => function
The then method is used to execute the specified handler function when the custom event is received. The method takes a eventInit
object as second parameter, which is equal to the options provided by the Event interface. The method returns a function to remove all created listeners.
Type: with(payload?: any, eventInit?: EventInit) => void
The with method is used to dispatch the created event from the dispatch()
method with a specified payload. The method takes a eventInit
object as second parameter, which is equal to the options provided by the Event interface. The payload will default to undefined
if not specified.
If you would like to contribute, take a look at the contribution guide.
Stræm.js is licensed under the MIT License