truth

The only data store that tells the truth about your current state.

truth

Truth allows you to merge different sets of data in to one single source of truth. The data can be manipulated from one central point in your application leading to a better separation of concerns and maintainability of the project.

Changes propagate through all the merged data sets so you know when your data set has changed.

The module is released in the public npm registry and can be installed by running:

npm install --save truth

First of all we need to require the module and create a new Truth instance as shown in the example code blow. This is the bare minimum required bootstrapping code.

'use strict';
 
var Truth = require('truth')
  , truth = new Truth();

While it's certainly possible to create truth instances without any arguments, there are a couple of arguments that can be set:

  1. The first argument can be a string with the name of the store. This will be used when merging stores and can be useful for debugging purposes.
  2. Configuration object where you can set:
  • key The name of the key that should be used to determine duplicates when merging truth instances.

Now that we've constructed our first truth instance we can look at the various of API methods that are available:

Add a new row(s) in to the data set. You can supply as many arguments as you wish as they will all been seen as new rows that should be inserted. Once the insertion has occurred a change event will be triggered. So if you have multiple rows, it makes more sense to supply all at once as arguments instead of doing multiple invocations to truth.add().

truth.add({ another: 'row' }, { more: 'rows'});

There is some small level of duplication detection where it tries to find exactly the same item in the current data set. So the method only trigger's changes when something is actually inserted.

Remove one or more rows from the data set. Please note that this only removes rows who equals those that got added before any modifications.

var row = { foo: 'bar' };
 
truth.add(row);
truth.remove(row);

Test if a certain key->value combination is present in the data store. The first argument is the key of the row you're searching for and the second argument is an optional value to test against.

truth.add({ foo: 'bar' });
 
truth.has('foo', 'bar'); // true 
truth.has('foo', 'baz'); // false 

Find a row in the dataset. Searches are done based on key/value matching.

var row = { foo: 'bar' }
  , found;
 
truth.add(row);
found = truth.find('foo', 'bar');
 
console.log(row === found); // true 

The internal dataset has changed, fetch data from merged data stores, re-apply all data transformations and trigger the change event.

truth.change();

Add additional data transformation methods, these should be existing methods on an Array, so you can use things like map, reduce, sort and what not. There are 3 requirement arguments:

  • The method name as string.
  • The actual function that does the transformation. If you supply a reduce method please assume that no default reduce value is given so you should return that on the first call.
  • Name of the transform method. This allows easy removal of transformations using the undo method.
truth.transform('map', function (row) {
  return {
    foo: row.value
  };
});
 
truth.add({ value: 'awesome' });
truth.get(); // [ { foo: 'awesome' }] 

Undo a transformation on the dataset. This method requires 2 arguments:

  • The method name as string.
  • The name that you supplied as third argument in the transform method.

Merge the data from another truth store, the merging can be done based on a key to prevent duplicate rows. The primary data store will always be preferred over the merged data store.

When a merged truth store changes it data, it will also trigger a change event for your data store so they are always in sync.

var another = new Truth();
 
truth.add({ foo: 'bar', hello: 'world' });
another.add({ foo: 'bar', hello: 'hi' }, { foo: 'baz', hello: 'hi' });
 
truth.merge(another, 'foo');

In the example above we're merging our primary truth store another truth store. We supply the de-duplication key as second argument. So when we truth.get() data from the primary store it will have:

[
  { foo: 'bar', hello: 'world' },
  { foo: 'baz', hello: 'hi' }
]

As rows.

Completely destroy the truth instance. No more methods should be called after this method is called so it can be safely collected by garbage collectors. When it's destroyed, it will emit an destroy method.

truth.destroy();

MIT