Key Map

1. Index Manipulation
2. Store
3. Streams
4. Traversing
5. Filtering
6. Atomic
7. Compactation
8. Events

Index manipulation

key_map.addIndex (name, [options, ] transform_function, callback)

Adds an index to key_map.

• name: the name of the index. You will be able to refer to the index as key_map.<name> or key_map[name] after this.

• transform_function (record): a javascript function that takes a record as sole argument and returns the indexed value.

  Returned values here should be basic types (comparable with <, >, ==, etc.).

  This function should not used variables outside of the scope. The reason for this is that the function will be serialized so it will be available on app restart.

• callback (err): called when there is an error or the index is added to the key map.
• options:
  • ordered: true the index should be ordered. Defaults to true.

Example:

var Alfred = require('alfred');
Alfred.open('path/to/database/dir', function(err, db) {
  if (err) { throw err; }
  db.ensureKeyMapAttached('users', function(err, users) {
    if (err) { throw err; }
    var age_index_function = function(user) {
      return user.age;
    };
    users.addIndex('age', age_index_function, function(err) {
      if (err) { throw err; }
      // Now you can use the users.age index
    });
  })
});

key_map.ensureIndex (name, [options, ] transform_function, callback)

If not created, creates this index.

If an index with this name already exists, it does nothing. If you need to change the options on this index, you must remove and then add.

key_map.dropIndex (name, callback)

Removes the index with name from the key map.

• name: the name of the index
• callback (error): called when there is an error or the index is removed.

Store

key_map.put (key, value, callback)

Stores a value later retrievable by key_map.get (key, ...).

• key: a string or a number
• value: a basic type or an object that is serializable / deserializable to and from JSON. Arrays with these objects, objects containing these objects or simple values (numbers, strings, booleans, dates, null)
• callback (err): a function that will be called when there is an error or the put is successful.

key_map.get (key, callback)

Tries to retrieve a value based on a fiven key.

• key: a string or a number
• callback (err, value): a function that will be called when there is an error (err is not null) or the object is retrieved or the object has not been found (value is null).

key_map.destroy (key, callback)

Alias to key_map.put (key, null, callback).

key_map.count (callback)

Gets the number of objects on the key_map

• callback (err, count): Called when there is an error or counting is done

Streams

key_map.startStream (filter_function, callback)

Starts a filter stream based on the given filter function. For every future put that matches the filter_function, callback is invoked.

• filter_function (record): A function that returns true if the record is to be selected.
• callback (err, record): Called when there is an error or a record was selected.

returns: a stream handle that you can use to stop the stream.

key_map.stopStream (stream_handle, callback)

Stops a filter stream.

• stream_handle: A stream handle previously returned by key_map.startStream().
• callback (err, record): Called when there is an error or a record was selected.

Traversing

key_map.scan (callback [, nullOnEnd])

Cycles through all records.

• callback (err, key, value): Called when there is an error or a record is found.
• nullOnEnd: Pass through if you want callback to be called when the last record is fetched. In this case, the first (err) and second (key) arguments on callback will be null.

Filtering

key_map.range(index, start, end, callback)

(only available on ordered indexes)

Get a callback for every record which index value on specified index is greater or equal to start and lesser than or equal to end.

• index: the name of the index or the index object itself.
• start: the starting value (or null to start from the first one).
• end: the ending value (or null to end on the last one).
• callback (err, key, value): called when there is an error or one record is retrieved

key_map.countFilter(index, filter_function, callback)

Count the number of records for which the filter_function, when applied the indexed value returns true.

• index: the name of the index or the index object itself.
• filter_function (index_value): a filter function that accepts the indexed value as sole argument and returns true if the value should be selected.
• callback (err, count): called when there is an error or the count has been reached.

key_map.indexMatch(index, value, callback)

Calls callback for every element on the index == value.

• index: the name of the index or the index object itself.
• value: the value the index will be matched against.
• callback (err, key, valye): called when there is an error or there is a match.

Atomic

key_map.atomic (key, callback, result_callback)

Do an atomic operation on a record.

• key: the key for the object you are looking for.
• callback (err, value): a callback called when there is an error or the record was found or not found. On this function you get the value of the record and return the new value of the record.
• result (err): called when the saving of the record finishes. If an error occurred saving the object the first argument will contain that error.

Example:

// grab account with key 100 and add 5 to it's balance
account_key_map.atomic(100, function(err, account) {
    if (err) { throw err; }
    account.balance += 5;
    return account;
  }, function(err) {
    if (err) { throw err; }
    // account balance was atomically increased of 5
  }
);

Compactation

key_map.compact (callback)

Compacts a key map, loosing all past history.

Events

Regsiter ro receive events like this:

db.users.on('put', function(key, value) {
  console.log('key ' + key + ' was put on users key map');
});

Supported events are:

'before_flush'

Emitted right before flushing starts.

callback ()

'after_flush'

Emitted right after flushing ends.

callback ()

'put'

Emitted when a put is made.

callback (key, value)