Baggie
Baggie is a lightweight event emitter and storage mechanism used for building modern event-driven applications. Baggie is compatible in both browser and server environments.
Installation
Baggie can be installed with your favorite package manager (npm, yarn, etc) or simply included on your page with a <script></script>
tag.
Install with NPM
npm i -s baggie
// CommonJSconst Baggie = ; // ES6 Module syntax also supported;
Or via script tag
Usage
Basic event handling and storage examples.
Events
'use strict'; // Instantiate a new Baggie instanceconst baggie = ; // Listen for an eventbaggie; // Emit an eventbaggie;
Storage
'use strict'; const baggie = ; // Add a value to storage with key 'foo'baggie; // Retrieve the value of key 'foo'baggie; // 'bar'; // Unset the value of key 'foo'baggie; // 'bar';baggie; // undefined // Storage keys can be used to create a nested structurebaggie;baggie; // { b: { c: 'foo' } }baggie; // 'foo'
Storage Methods
Chainable
baggie.add(key, value[, options]) Alias: baggie.set
Adds a value
to storage that can be retrieved with key
.
key
argument must be a string or array of strings, value
can be anything.
If key
argument contains a .
character (or some other character specified with options.delimiter
), baggie will create a nested structure.
Example
// Store the value 'bar' with key 'foo'baggie; // Create a nested structurebaggie; // Equivalent to abovebaggie; // Add method can be chainedbaggie ;
Note: By default, baggie.add
will not overwrite primitive values. To override this behavior set options.force
to true
;
baggie.set
returns the baggie instance.
baggie.get(key[, options])
Gets a value from storage. If key
is a string delimited by a .
then baggie will attempt to get a nested value. options.delimiter
will override the default delimiter of .
.
// Add a value to storagebaggie; // Retrieve the valuebaggie; // bar // Add a nested valuebaggie; // Retrieve a nested valuebaggie; // 'baz'
baggie.get
returns the value if found, otherwise undefined
baggie.remove(key)
Alias: baggie.unset
Sets the value found at key
to undefined
and returns the value that was unset.
Example
// Set a valuebaggie; // Unset and retrieve the valuebaggie; // 'bar' baggie; // undefined
Event Methods
Chainable
baggie.on(event, handler) Register a handler
function to be called when event
is emitted. Handlers are called in the order in which they are registered. Global handlers are called before event handlers.
Handler function should accept a single argument that will be populated with any data attached to the event being emitted.
Example
baggie;
baggie.on
returns the baggie instance.
Chainable
baggie.off(event, handler) Unregister a handler
function. If no handler is provided, all handlers for event
are cleared.
Example
{ console;} // Listen for 'my-event'baggie; // Unregister a handlerbaggie; // Unregister all handlers for 'my-event'baggie;
baggie.off
returns the baggie instance.
Chainable
baggie.emit(event[, data]) Emit an event with optional data.
This will fire all handlers in the order in which they were registered (global handlers first). Handlers for the specific event being fired are passed the data
argument. Global handlers are passed the event
and data
arguments respectively.
baggie.emit
returns the baggie instance.
Example
baggie;
Chainable
baggie.onGlobal(handler) Register a handler for all events (global handler). Global handlers are called before other event-specific handlers. Global handlers are also called in the order in which they are registered.
Handler should accept 2 arguments, the first argument is the event name and the second is the event data.
Example
baggie;
baggie.onGlobal
returns the baggie instance.
Chainable
baggie.offGlobal(handler) Unregister a global handler. If no handler is provided, all global handlers are cleared.
Example
{ console; console;} // Register a global handlerbaggie; // Unregister global handlerbaggie; // Unregister all global handlersbaggie;
baggie.offGlobal
returns the baggie instance.
baggie.history
Returns an array of the events that have been fired, most recent first.
Chainable
baggie.empty() Alias: baggie.reset
Resets the baggie instance to it's default state. Clears all handlers, data, and history.
baggie.empty
returns the baggie instance.