array-keys

array-keys

Very simple library to manage array elements using a key instead of array index position. When dealing with very large sets of data all organized in an object reference, if the object structure is changing a lot you can end up with memory leaks and slow performance. In these cases it's better to keep an array of objects instead of and object of objects. The cost of iterating through the array is cheaper than the lack of garbage collection which can occur in large, changing, object hashes.

environments

Should run in both node.js and browser environments.

basic usage example

var ak = new ArrayKeys({
  identifier: 'key' // defaults to `id`
});

ak.getRecord('myInvalidKey'}); // returns undefined

ak.addRecord({
  key: 'myKey1',
  value: 'hello world!'
}); // returns true

ak.getRecord('myKey1'); // returns { key: 'myKey1', value: 'hello world!' }

ak.addRecord({
  key: 'myKey2',
  value: 'hello space!'
}); // returns true


ak.forEachRecord(function (record) {
  // this function is called once for each record
}).finally(function (count) {
  // function called after the above callback is called for each record
  // count is the total number of records processed
});

ak.getIdentifiers(); // returns ['myKey1', 'myKey2']

events

ArrayKeys also optionally supports emitting events. This functionality must be explicity enabled during object instantiation.

supported events

• add
• remove
• update

example

var ak = new ArrayKeys({
  emitEvents: true
});

ak.events.on('add', function (record) {
  console.log(record.id); // 'foobar'
});

ak.addRecord({
    id: 'foobar',
    here: [ 'is', 'some' ],
    data: true
});

API

constructor

var ak = new ArrayKeys({
  identifier: 'id',
  emitEvents: true
});

addRecord

Add a new record.

ak.addRecord({
  id: 'helloworld123',
  foo: 'bar'
});
ak.addRecord({
  id: 'pizza777',
  blah: [ 1, 2, 3 ]
});

getRecord

Get a record by it's identifier.

var record = ak.getRecord('helloworld123');

getIdentifiers

Get an array of the values of the record identifiers.

var ids = ak.getIdentifiers(); // 'helloworld123', 'pizza777'

exists

Indicates whether a record exists by returning true or false.

if (ak.exists('blahblahblah')) {
  console.log('yes!');
} else {
  console.log('no');
}
// returns false, 'no'

getIndex

Returns the number of the position of the record, specified by identifier.

var position = ak.getIndex('pizza777'); // returns 1

forEachRecord

Calls a callback handler function for each record in the list, asyncronously.

ak.forEachRecord(function (record) {
  // ... do something with record
}).finally(function (count) {
  // ... do something at the end of the operation. First param is the number
  // of items processed.
})

removeRecord

Removes the record specified by identifier.

ak.removeRecord('helloworld123');

removeAll

Removes all records.

ak.removeAll();

events

update

ak.events.on('update', function (record){
  ...
});

add

ak.events.on('add', function (record){
  ...
});

remove

ak.events.on('remove', function (record){
  ...
});

credits

Project developed and maintained by Nick Jennings