gaia-hash
v0.1.1
Published
Hash tables for javascript.
Downloads
18
Readme
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.