gaia-hash

Hash tables for javascript.

Installation

Node.js

gaia-hash is available on npm.

$ npm install gaia-hash

Component

gaia-hash is available as a component.

$ component install qualiancy/gaia-hash

Usage

Hash (constructor)

• @param {Object} key/value pairs to insert
• @param {Object} options

Creates a new hash given a set of values and options.

var hash = require('gaia-hash')
  , h = hash();

The Hash constructor is also available for extending.

var Hash = require('gaia-hash').Hash
  , inhertis = require('tea-inherits');

function MyHash (data) {
  Hash.call(this, data);
}

inherits(MyHash, Hash);

In this scenarios, any method that returns a new hash (such as .clone()) will return a new instance of MyHash.

.length

• @return {Number} count of keys

Property that returns the the number of keys in the hash.

.keys

• @return {Array} keys

Property that returns an array of all of the keys with defined values in the hash.

.values

• @return {Array} values

Property that return an array of all of the defined values in the hash. Order will be maintained. null is considered a defined value, but undefined is not.

.set(key, value)

• @param {String} key
• @param {Object} value
• @return {this} chainable

Sets the value at a given key.

h.set('hello', 'universe');

.get(key)

• @param {String} key
• @return {Mixed} value

Gets the value of at a specific key.

h.get('hello'); // 'universe'

.has(key)

• @param {String} key
• @return {Boolean} existence

Checks for existence of key in hash.

if (h.has('hello')) {
  // do something cool
}

.del(key, [silent])

• @param {String} key

h.del('hello');

Removes a key from the Hash by setting it's value to undefined. The key will no longer be included in h.keys or h.toArray(). Will be completely removed from internal storage upon the next invocation of h.clean().

.clone()

• @return {Hash} cloned

Returns a copy of the hash.

var h2 = h.clone();

.at(index)

• @param {Number} index
• @return {Object} value at index

Returns the data at a given index, as if the hash as an array. Respects the last .sort() or the order the keys were defined.

var first = h.at(0);

.index(key)

• @param {String} key
• @return {Number} index

Returns the index for a given key, as if the hash was an array. Respects the last .sort() or the order the keys were defined. Returns -1 if the key is not defined.

var pos = h.index('key');

.toArray()

• @return {Array}

Returns the hash as javascript array with each entry being an {Object} of key/value pairs.

var h = hash({ 'hello': 'world' })
  , arr = h.toArray();

// [ { key: 'hello', value: 'world' } ]

.fromArray(arr)

• @return {this} for chaining

Sets values in this Hash from the result of of a sol.toArray call. Array must have entries in the format { key: [key], value: [value] }.

// the long clone
var arr = h1.toArray()
  , h2 = hash();

h2.fromArray(arr);

Any existing values with the same key wil be overwritten. Any keys with the value of undefined will be skipped.

.flush()

• @return {this} for chaining

Remove all key/value pairs from a hash.

h.flush();

.clean()

• @return {this} for chaining

Helper function to remove all keys that have an undefined value. Useful, as del leaves keys in memory.

h.clean();

.each(iterator, [context])

• @param {Function} iterator
• @param {Object} context to apply as this to iterator. Defaults to current hash.
• @return {this} for chaining

Apply a given iteration function to each value in the hash.

h.each(function (value, key, index) {
  console.log(index, key, value);
});

.map(iterator, [context])

• @param {Function} iterator
• @param {Object} content to apply as this to iterator. Defults to current hash.
• @return {Hash} modified new Hash

Map a given function to every value in the Hash. Iterator must return new value. Returns a new Hash.

h.set('hello', 'world');

var h2 = h.map(function (value, key, index) {
  return value.toUpperCase();
});

console.log(h2.get('hello')); // "WORLD"

.reduce(iterator, [context])

• @param {Function} iterator
• @param {Object} context to apply as this to the iterator. Defaults to current hash.
• @return {Mixed} result

h.set('one', 1);
h.set('two', 2);

var sum = h.reduce(function (value, key, index) {
  return value;
});

console.log(sum); // 3

.mapReduce(mapFn, reduceFn)

• @param {Function} map function
• @param {Function} reduce function
• @return {Hash} new Hash of results

Divide and aggregate a hash based on arbitrary criteria.

The mapFunction will be applied to each key/value pair in the original hash. A group key and the value to be added to that key's array may be emitted by by this iterator.

The reduceFunction will be applied to each group key emitted by the mapFunction. This function should return the new value for that key to be used in the final Hash.

This method will return a new Hash with unique keys emitted by the mapFunction with values returned by the reduceFunction.

The following example will return a hash with count of last names that start with a specific letter.

h.set('smith', { first: 'The', 'Doctor' });
h.set('amy', { first: 'Amy', last: 'Williams' });
h.set('rory', { first: 'Rory', last: 'Williams' });

var byLetter = h.mapReduce(
    function map (key, value, emit) {
      var first = value.last.charAt(0).toUpperCase();
      emit(first, 1);
    }
  , function reduce (key, arr) {
      var sum = 0;
      for (var i = 0, i < arr.length; i++) sum += arr[i];
      return sum;
    }
);

byLetter.get('D'); // 1
byLetter.get('W'); // 2

.filter(iterator, [context])

• @param {Function} iterator
• @param {Object} context to apply as this to iterator. Defaults to current hash.
• @return {Hash} new Hash of results

Creates a new hash with all key/values that pass a given iterator test. Iterator should return true or false.

h.set('smith', { first: 'The', 'Doctor' });
h.set('amy', { first: 'Amy', last: 'Williams' });
h.set('rory', { first: 'Rory', last: 'Williams' });

var williams = h.filter(function (value, key) {
  return value.last.toUpperCase() === 'WILLIAMS';
});

williams.length; // 2

.find(query)

• @param {Object} query
• @return {Hash} new Hash of results

Creates a new hash with all elements that pass a given query. Query language is provided by gaia-filter.

h.set('smith', { first: 'The', 'Doctor' });
h.set('amy', { first: 'Amy', last: 'Williams' });
h.set('rory', { first: 'Rory', last: 'Williams' });

var williams = h.find({ 'name': { $eq: 'Williams' }});

williams.length; // 2

If the hash is a storage mechanism for multiple {Object} instances instances (such as database models}, the findRoot option may be defined for the Hash. This option will be transferred to all new result Hashes.

function Model (first, last) {
  this.attributes = { first: first, last: last };
}

var h = hash(null, { findRoot: 'attributes' });

h.set('smith', new Model('Amy', 'Williams'));

// now functions same as above

.sort(iterator)

• @param {String|Function} comparator
• @return {this} for chaining

Creates a new hash sorted with an iterator. Can use one of the provided iterators or provide a custom function.

Comparators:

• 'kasc': key alphabetical (default)
• 'kdesc': key alphabetical descending
• 'asc': value ascending, only if value is not object
• 'desc': value descending, only if value is not object
• {Function}: provide custom iterator

Custom Comparator:

The parameters for each to compare are an object with key and value properties. See the .toArray() method for more information.

hash.sort(function (a, b) {
  var akey = a.key
    , avalue = a.value;
  // etc..
  return 1 || -1 || 0; // choose
});

.sortBy (path, comparator)

• @param {String} path
• @param {String|Function} comparator

Helper for sorting hash of objects by a path.

hash.sortBy('stats.age', 'asc');

Comparators:

• 'asc': value ascending
• 'desc': value descending
• {Function}: custom function to receive the value at path

License

(The MIT License)

Copyright (c) 2012 Jake Luer [email protected] (http://qualiancy.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.