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

4.3 kb, 1 kb minified, 0.5 kb gzipped

• Internals are private;
• Sane handling of hasOwnProperty and __proto__;
• Empty string is valid key;
• Exception thrown on non-string keys (including null and undefined);
• 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.

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

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.

• Plain old JavaScript objects;
• domenic/dict;
• dherman/dictjs;
• fabriziomoscon/node-hash;
• rauschma/strmap.

• ES 6 Map;
• BorisKozo/jsHash (aka npm>hashes);
• doug-martin/ht;
• georgerogers42/hashtbl2;
• WebReflection/es6-collections.

npm install safemap

jam install safemap

git clone [email protected]:philbooth/safemap.js.git

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.

var safemap = new SafeMap();

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

var safemap = Object.create(SafeMap);

A number of methods are exported:

Returns the number of items in the map.

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

Sets value to be associated with key in the map.

Returns a boolean indicating whether key is in the map.

Removes key from the map.

Removes all keys from the map.

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

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

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

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

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.

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.