Neglected Pizza Money

    safemap

    0.2.0 • Public • Published

    safemap.js

    Build status

    A tiny, safe, ES3-compliant map/dictionary implementation in JavaScript.

    Tiny?

    4.3 kb, 1 kb minified, 0.5 kb gzipped

    Safe?

    • Internals are private;
    • Sane handling of hasOwnProperty and __proto__;
    • Initial values are cloned rather than passed by reference;
    • Constructor guards against missing new operator;
    • Throwing versions of get, set and remove methods provided for callers that wish to fail fast.

    ES3-compliant?

    Doesn't rely on features from more recent versions of ECMAScript, to enable straightforward usage from legacy browser environments.

    What's not to like?

    To enforce true privacy, the methods are not set on SafeMap.prototype, they are set on each instance by the constructor. If you're creating a large number of instances, there is a chance that you might be concerned about that. It also means that methods may not be sanely applied to other objects.

    The method name remove is used rather than the more idiomatically JavaScripty delete, which is prevalent in other map/dictionary APIs, such as ES5's WeakMap and others.

    What else could I use instead?

    Installation

    Via NPM

    npm install safemap
    

    Via Jam

    jam install safemap
    

    Via Git

    git clone git@github.com:philbooth/safemap.js.git
    

    Usage

    Loading the library

    Both CommonJS (e.g. if you're running on Node.js or in the browser with Browserify) and AMD (e.g. if you're using Require.js) loading styles are supported. If neither system is detected, the library defaults to exporting its interface globally as SafeMap.

    Instantiation

    var safemap = new SafeMap();
    
    var safemap = new SafeMap({
        // Initial values
        foo: 'bar'
        baz: 'qux'
    });
    
    var safemap = Object.create(SafeMap);
    

    Calling the methods

    A number of methods are exported:

    safemap.size ()

    Returns the number of items in the map.

    safemap.get (key [, defaultValue])

    Returns the value associated with key in the map, or defaultValue if the property is unset.

    safemap.set (key, value)

    Sets value to be associated with key in the map.

    safemap.has (key)

    Returns a boolean indicating whether key is in the map.

    safemap.remove (key)

    Removes key from the map.

    safemap.clear ()

    Removes all keys from the map.

    safemap.forEach (callback)

    Iterate over items in the map, calling callback for each item. callback will receive two arguments, key and value.

    safemap.safeGet (key)

    Throwing version of get. No default value may be specified and, if key is not in the map, an error will be thrown.

    safemap.safeSet (key, value)

    Throwing version of set. If key is already in the map, an error will be thrown.

    safemap.safeRemove (key)

    Throwing version of remove. If key is not in the map, an error will be thrown.

    Development

    Dependencies

    The build environment relies on Node.js, NPM, Jake, JSHint, Mocha, Chai and UglifyJS. Assuming that you already have Node.js and NPM set up, you just need to run npm install to install all of the dependencies as listed in package.json.

    Unit tests

    The unit tests are in test/safemap.js. You can run them with the command npm test or jake test. To run the tests in a web browser, open test/safemap.html.

    Keywords

    none

    Install

    npm i safemap

    DownloadsWeekly Downloads

    4

    Version

    0.2.0

    License

    MIT

    Last publish

    Collaborators

    • philbooth