baggie v1.2.2

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

// CommonJS
const Baggie = require('baggie');

// ES6 Module syntax also supported
import { Baggie } from 'baggie';

Or via script tag

<script src="/path/to/Baggie.min.js"></script>

Usage

Basic event handling and storage examples.

Events

'use strict';

// Instantiate a new Baggie instance
const baggie = new Baggie();

// Listen for an event
baggie.on('my-event', function handler(data){
    console.log(data);
});

// Emit an event
baggie.emit('my-event', 'Hello World!');

Storage

'use strict';

const baggie = new Baggie();

// Add a value to storage with key 'foo'
baggie.add('foo', 'bar');

// Retrieve the value of key 'foo'
baggie.get('key'); // 'bar';

// Unset the value of key 'foo'
baggie.remove('foo'); // 'bar';
baggie.get('foo'); // undefined

// Storage keys can be used to create a nested structure
baggie.add('a.b.c', 'foo');
baggie.get('a');     // { b: { c: 'foo' } }
baggie.get('a.b.c'); // 'foo'

Storage Methods

baggie.add(key, value, options) Chainable

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.add('foo', 'bar');

// Create a nested structure
baggie.add('a.b.c', 'baz');

// Equivalent to above
baggie.add('a', {b:{c:'baz'}});

// Add method can be chained
baggie
    .add('foo', 'bar')
    .add('spam', 'eggs')
    .add('stuff', 'things');

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 storage
baggie.add('foo', 'bar');

// Retrieve the value
baggie.get('foo'); // bar

// Add a nested value
baggie.add('a.b', 'baz');

// Retrieve a nested value
baggie.get('a.b'); // '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 value
baggie.add('foo', 'bar');

// Unset and retrieve the value
baggie.unset('foo'); // 'bar'

baggie.get('foo'); // undefined

Event Methods

baggie.on(event, handler) Chainable

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.on('my-event', function(data){
    // Do something with the event data
    console.log(data);
});

baggie.on returns the baggie instance.

baggie.off(event, handler) Chainable

Unregister a handler function. If no handler is provided, all handlers for event are cleared.

Example

function handler(data){
    console.log(data);
}

// Listen for 'my-event'
baggie.on('my-event', handler);

// Unregister a handler
baggie.off('my-event', handler);

// Unregister all handlers for 'my-event'
baggie.off('my-event');

baggie.off returns the baggie instance.

baggie.emit(event, data) Chainable

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.emit('my-event', { foo: 'bar' });

baggie.onGlobal(handler) Chainable

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.onGlobal(function handler(event, data){
    console.log(`Handling event "${ event }"`);
    console.log(data);
});

baggie.onGlobal returns the baggie instance.

baggie.offGlobal(handler) Chainable

Unregister a global handler. If no handler is provided, all global handlers are cleared.

Example

function handler(event, data){
    console.log(`Handling event "${ event }"`);
    console.log(data);
}

// Register a global handler
baggie.onGlobal(handler);

// Unregister global handler
baggie.offGlobal(handler);

// Unregister all global handlers
baggie.offGlobal();

baggie.offGlobal returns the baggie instance.

baggie.history

Returns an array of the events that have been fired, most recent first.

baggie.empty() Chainable

Alias: baggie.reset

Resets the baggie instance to it's default state. Clears all handlers, data, and history.

baggie.empty returns the baggie instance.