seraph_model provides some convenient functions for storing and retrieving typed nodes from a neo4j database. It is intended to work with seraph.

var db = require('seraph')('http://localhost:7474')
var model = require('seraph-model');

var User = model(db, 'user');

User.save({ name: 'Jon', city: 'Bergen' }, function(err, saved) {
  if (err) throw err;

  User.findAll(function(err, allUsers) {
    // allUsers -> [{ name: 'Jon', city: 'Bergen', id: 0 }]
  });
  User.where({ city: 'Bergen' }, function(err, usersFromBergen) {
    // usersFromBergen -> all user objects with city == bergen
  });
})

seraph-model 0.5.2 works with Neo4j-2.0.0-M05 and Neo4j-2.0.0-M06.

To check if it works with your version, you should check out the repo, and change the Neo4j version at the start of the tests to the version you're running

• Creating a new Model
• Adding preparers
• Adding validators
• Adding indexes
• beforeSave/afterSave events
• Setting a properties whitelist
• Composition of models
• Setting a unique key or index
• Computed fields
• Schemas

• model.read
• model.exists
• model.save
• model.push
• model.saveComposition
• model.findAll
• model.where
• model.prepare
• model.validate
• model.fields
• model.setUniqueKey
• model.setUniqueIndex
• model.useTimestamps
• model.addComputedField
• model.cypherStart

var db = require('seraph')('http://localhost:7474');
var Beer = require('seraph_model')(db, 'beer');

Beer.save({name: 'Pacific Ale', brewery: 'Stone & Wood'}, function(err, beer) {
  // saved!
});

Preparers can also do validation. If a preparer returns an error, it will be passed to the save callback as if it were a validation error. However, if you just want to do validation and not mutate the object, use a validator instead.

Preparers are called before validators.

You can manually prepare an object by using the model.prepare function.

var prepareFileSize = function(object, callback) {
  fs.stat(object.file, function(err, stat) {
    if (err) return callback('There was an error finding the file size');
    object.filesize = stat.size;
    callback(null, object);
  });
}

model.on('prepare', prepareFileSize);

model.save({file: 'foo.txt'}, function(err, object) {
  // object -> { file: 'foo.txt', filesize: 521, id: 0 }
});

mode.save({file: 'nonexistant.txt'}, function(err, object) {
  // err -> 'There was an error finding the file size'
});

You can manually validate an object by using the model.validate function.

var validateAge = function(person, callback) {
  if (object.age >= 21) {
    callback();
  } else {
    callback('You must be 21 or older to sign up!');
  }
}

model.on('validate', validateAge);

model.save({ name: 'Jon', age: 23 }, function(err, person) {
  // person -> { name: 'Jon', age: 23, id: 0 }
});

model.save({ name: 'Jordan', age: 17 }, function(err, person) {
  // err -> 'You must be 21 or older to sign up!'
});

You can add any number of indexes to add an object to upon saving by using the addIndex function. Objects are only indexed the first time they are saved, but you can manually index an object by calling the index function.

They keys and values passed to addIndex can be computed, but that is optional. If they are computed, you must pass the resultant key or value to a callback, rather than returning it (this gives you the opportunity to do asynchronous calculations at this point).

You also have the option of passing a function to determine weather or not the index is used at all.

With static keys/values

model.addIndex('wobblebangs', 'bangs', 'wobbly');

With computed value

model.addIndex('uniquely_identified_stuff', 'stuff', function(obj, cb) {
  cb(null, createUuid());
});

With computed key and value

model.addIndex('things',
  function(obj, cb) { cb(null, obj.model); },
  function(obj, cb) { cb(null, obj.id); });

With conditional indexing

model.addIndex('some_stuff', 'things', 'cool', function(obj, cb) {
  var isCoolEnough = obj.temperature < 20;
  cb(null, isCoolEnough); //objs with `temperature` >= 20 are not indexed
});

model.on('beforeSave', function(obj) {
  console.log(obj, "is about to be saved");
})

beer.fields = ['name', 'brewery', 'style'];

beer.save({
  name: 'Rye IPA', 
  brewery: 'Lervig', 
  style: 'IPA',
  country: 'Norway'
}, function(err, theBeer) {
  // theBeer -> { name: 'Rye IPA', brewery: 'Lervig', style: 'IPA', id: 0 }
})

var beer = model(db, "Beer");
var hop = model(db, "Hop");

beer.compose(hop, 'hops', 'contains_hop');

var pliny = {
  name: 'Pliny the Elder',
  brewery: 'Russian River',
  hops: [
    { name: 'Columbus', aa: '13.9%' },
    { name: 'Simcoe', aa: '12.3%' },
    { name: 'Centennial', aa: '8.0%' }
  ]
};

// Since objects were listed on the 'hops' key that I specified, they will be 
// saved with the `hop` model, and then related back to my beer.
beer.save(pliny, function(err, saved) {
  // if any of the hops or the beer failed validation with their model, err
  // will be populated and nothing will be saved.
  
  console.log(saved); 
  /* -> { brewery: 'Russian River',
          name: 'Pliny the Elder',
          id: 11,
          hops: 
           [ { name: 'Columbus', aa: '13.9%', id: 12 },
             { name: 'Simcoe', aa: '12.3%', id: 13 },
             { name: 'Centennial', aa: '8.0%', id: 14 } ] }
  */

  db.relationships(saved, function(err, rels) {
    console.log(rels) // -> [ { start: 11, end: 12, type: 'contains_hop', properties: {}, id: 0 },
                      // { start: 11, end: 13, type: 'contains_hop', properties: {}, id: 1 },
                      // { start: 11, end: 14, type: 'contains_hop', properties: {}, id: 2 } ]
  });

  // Read directly with seraph
  db.read(saved, function(err, readPlinyFromDb) {
    console.log(readPliny)
    /* -> { brewery: 'Russian River',
            name: 'Pliny the Elder',
            id: 11 }
    */
  })

  // Read with model, and you get compositions implicitly.
  beer.read(saved, function(err, readPliny) {
    console.log(readPliny)
    /* -> { brewery: 'Russian River',
            name: 'Pliny the Elder',
            id: 11,
            hops: 
             [ { name: 'Columbus', aa: '13.9%', id: 12 },
               { name: 'Simcoe', aa: '12.3%', id: 13 },
               { name: 'Centennial', aa: '8.0%', id: 14 } ] }
    */
  });

  hop.read(14, function(err, hop) {
    console.log(hop); // -> { name: 'Centennial', aa: '8.0%', id: 14 }
  });
});

You can use the regular model.save function to update a model with compositions on it. If the compositions differ from the previous version of the model, the relationships to the previously composed nodes will be deleted but the nodes themselves will not be. If you want to update the base model but don't want the overhead that the compositions involves, you can use model.save with excludeCompositions set to true. See the model.save docs for more info.

A couple of alternatives for updating compositions exist: model.push for pushing a single object to a composition without having to first read the model from the database, and model.saveComposition for updating an entire composition in one go.

Add a composition.

• composedModel — the model which is being composed
• key — the key on an object being saved which will contained the composed models.
• relationshipName — the name of the relationship that is created between a root model and its composed models. These relationships are always outgoing.
• opts - an object with a set of options. possible options are documented below.

• many (default = false) — whether this is a *-to-many relationship. If truthy, the this composition will always be represented as an array on the base object.
• orderBy (default = null) - how this composition should be ordered. This can be set to either the name of a property on the composed node to order with (ascending), or an object with the name of the property value and the order direction. Possible values might include: 'age', {property: 'age', desc: true}, {property: 'age', desc: false}.

Read a single composition from a model.

• objectOrId — an id or an object that contains an id that refers to a model.
• compositionKey – the composition which to retrieve.
• callback — callback for result, format (err, resultingComp). resulingComp will either be an array of composed objects or a single object if there was only one

Example (from the above context)

beer.readComposition(pliny, 'hops', function(err, hops) {
  console.log(hops); 
  /* [ { name: 'Columbus', aa: '13.9%', id: 12 },
      { name: 'Simcoe', aa: '12.3%', id: 13 },
      { name: 'Centennial', aa: '8.0%', id: 14 } ]  */
});

Note that there is one in particular "gotcha" with enforced uniqueness on composed models: in the event that you try to add a new object and there is already an object indexed the same way, an error will be thrown. Unfortunately, due to a bug with neo4j's batch API, and the fact that composed models always save in a batch, this means that a statusCode of 500 will be returned. There is in fact no good way to determine that such an error is, in fact, the result of a conflict, yet.

Specifying a unique key will automatically index your node under a new index, using that key in each saved model. The index is named after your model's type property. For example, a model with model.type = 'car' will be added under the index cars. The index name is automatically pluralized from the model type name.

If you specified the key as model, then each time an object is saved it is indexed (in this example) in the cars index, under the key model, with the value of whatever model was set to.

Setting a unique key also automatically adds a validator checking that the indexed key was set on every object that is saved. An object will not be able to save without that key being set.

For example:

var Car = model(db, 'car');
Car.setUniqueKey('model');
Car.save({make: 'Citroën', model: 'DS4'}, function(err, ds4) {
  // ds4 -> { id: 1, make: 'Citroën', model: 'DS4' }
  // node 1 is now indexed in neo4j under `cars(model="DS4")`
  Car.save({make: 'Toyota', model: 'DS4'}, function(err, otherDs4) {
    // err.statusCode -> 409 (conflict)
  });
});

Car.save({make: 'Subaru'}, function(err, subaru) {
  // err -> 'The `model` key is not set, but is required to save this object'
});

You can also specify that instead of returning a conflict error, that you want to just return the old object when you attempt to save a new one at the same index. For example:

var Tag = model(db, 'tag');
Tag.setUniqueKey('tag');
Tag.save({tag: 'finnish'}, function(err, tag) {
  // tag -> { id: 1, tag: 'finnish' }
  
  // presumably later on, someone wants to save the same tag 
  Tag.save({tag: 'finnish'}, function(err, tag) {
    // instead of saving another tag 'finnish', the first one was returned
    // tag -> { id: 1, tag: 'finnish' }
  });
});

In case you want your unique index to be a little more involved than just using a value from the model, you can define your own unique index. The function you use to do this is model.setUniqueIndex, and it takes similar arguments to model.addIndex.

Here's an example with the Car model shown above, which uses both the make and the model to uniquely index.

var Car = model(db, 'car');
Car.setUniqueIndex('cars', 'make_and_model', function(car, cb) {
  if (!car.make || !car.model) cb("A car should have both a make and a model!");
  else cb(null, car.make + ' ' + car.model);
});

Car.save({make: 'Citroën', model: 'DS4'}, function(err, ds4) {
  db.index.read('cars', 'make_and_model', 'Citroën DS4', function(err, car) { 
    // `ds4` was indexed under 'Citroën DS4'.
    assert.deepEqual(ds4, car);
  });
});

Computed fields are fields on a model that exist transiently (they aren't stored in the database) and can be composed of other fields on the object or external information. You specify the field that you want to be computed, and the function that should be used to compute the value of that field for the model, and it will automatically be computed every time the model is read (and removed from the model just before saving). You can use the addComputedField to add a computed field.

Example:

var Car = model(db, 'car');
Car.addComputedField('name', function(car) {
  return car.make + ' ' + car.model;
});
Car.addComputedField('popularity', function(car, cb) {
  fetchPopularityRating(car.make, car.model, function(err, rating) {
    if (err) return cb(err);
    cb(null, rating.numberOfOwners);
  });
});

Car.save({ make: 'Citroën', model: 'DS4' }, function(err, car) {
  // car.name = 'Citroën DS4'
  // car.popularity = 8599
});

var User = model(db, 'user');
User.schema = {
  name: { type: String, required: true },
  email: { type: String, match: emailRegex, required: true },
  age: { type: Number, min: 16, max: 85 },
  expiry: Date
}

Setting a schema will automatically use the keys of the schema as the model's fields property.

Each of the constraints and their behaviour are explained below.

• type
  • 'date' or Date
  • 'string' or String
  • 'number' or Number
  • 'array' or Array
  • 'boolean' or Boolean
  • Other types
• default
• trim
• lowercase
• uppercase
• required
• match
• enum
• min
• max

Expects a date, and coerces it to a number using Date.getTime. Values will be parsed using Moment.js' date parser.

Examples of coercion:

new Date("2013-02-08T09:30:26")    ->   1360315826000
"2013-02-08T09:30:26"              ->   1360315826000
1360315826000                      ->   1360315826000

[1,2,3]     -> [1,2,3]
'cat'       -> ['cat']

User.schema = {
  name: { default: 'Anonymous User' }
}

1. object is prepared using model.prepare
2. object is validated using model.validate. If validation fails, the callback is called immediately with an error.
3. object is saved using seraph.save
4. object is indexed as this type of model using seraph.index

If excludeCompositions is truthy, any composed models attached to object will not be altered in the database (they will be ignored), and the object which is returned will exclude compositions.

This is a operationally similar to seraph.find, but is restricted to searching for other objects indexed as this kind of model. See the quick example for an example of this in action.

Prepares an object by using the model.preparers array of functions to mutate it. For more information, see Adding preparers

Validates that an object is ready for saving by calling each of the functions in the model.validators array. For more information, see Adding validators

This is an array of property names which acts as a whitelist for property names in objects to be saved. If it is set, any properties in objects to be saved that are not included in this array are stripped. Composited properties are automatically whitelisted. See Setting a properties whitelist for more information and examples.

See the using a unique key section for more information and examples.

See the the using a unique index section for more information and examples, or the indexes section for an explanation of the key/value resolvers and the shouldIndex argument.

By default, timestamps are a unix timestamp. You can change this by altering your model's makeTimestamp function. The function should return a value representing the current time.

Seraph-model provides two of these functions for your convenience by default, accessible on model.timestampFactories. They are:

• epochSeconds: unix timestamp (default)
• epochMilliseconds: unix offset (more accurate unix timestamp using ms)

To use one of these, just assign it yourself like this:

model.makeTimestamp = model.timestampFactories.epochMilliseconds;

Add a computed field to a model.

var beer = model(db, 'Beer');

beer.cypherStart(); // -> 'node:nodes(type = "Beer")'

db.find({type: 'IPA'}, false, beer.cypherStart(), function(err, beers) {
  // beers -> all beers with type == 'IPA'
});