Netherworld's Pretend Minibar

    baggie

    1.2.2 • Public • Published

    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.

    Install

    npm i baggie

    DownloadsWeekly Downloads

    1

    Version

    1.2.2

    License

    MIT

    Unpacked Size

    39 kB

    Total Files

    8

    Last publish

    Collaborators

    • brycejech