-
Notifications
You must be signed in to change notification settings - Fork 5
Store
The Store object is the entry point to node-ravendb, it configures and returns Session objects with connection and convention options applied and ready to use.
To get started using node-ravendb you need to require it - var raven = require('./node-ravendb');. This entry point has a few separate properties, one of those is the Store property - this provides us with a new DocumentStore instance.
Contents
To create a new Store we need to pass in a configuration object (a JavaScript object literal). As of version 0.2.0 the only properties required are:
- host - the host address of the RavenDB endpoint
- port - the port number the RavenDB endpoint resides on
- database - the name of the database your application is to use.
Future releases will include authentication and more properties will be optional, but for now host, port and database are all that is required.
var raven = require('./node-ravendb');
var store = new raven.Store({
host: '1.1.1.1',
port: 1234,
database: 'Foo'
});These connection properties cannot be changed after the store has been created.
The client api offers a range of configurable conventions that affect the way documents are generated inside RavenDB. We don't have strict types in JavaScript, so FindTypeTagName is not implemented, and as of version 0.1.0 FindIdentityProperty is not supported. The naming of these conventions differ slightly to their C# counterparts but provide the same functionality.
The two global conventions supported are:
- idGenerationStrategy - Allows you to control the generation of keys for new entities.
- idSeperator - A string that allows you to customize the separator used in of the document key generation.
Both conventions are accessible via the Store.conventions property.
store.conventions.idGenerationStrategy = 'guid';
store.conventions.idSeperator = '-';Note 1: There is currently no support for HiLo key generation so the only value accepted by idGenerationStrategy is 'guid' - surprisingly this tells RavenDB to generate a GUID key when documents are stored. There are various conditions that alter the strategy used here - more information on the key generation strategies used in node-ravendb can be found here.
Note 2: idSeperator accepts any string value as a separator but certain characters will be rejected by RavenDB - more information on the key generation strategies used in node-ravendb can be found here.
We can also set global options that get passed down to our session. Most of these options are those found under Session.Advanced in the C# client api.
The only option currently supported is:
- useOptimisticConcurrency - more information can be found here
All options are accessible via the Store.options property.
store.options.useOptimisticConcurrency = true;Note: These options can be overridden on a by Session basis.
Like the RavenDB client api, you need to initialize your store before you can open sessions from it. Initializing locks in the conventions and any changes to them after initialization will not be reflected in opened sessions.
store.conventions.idGenerationStrategy = 'guid';
store.initialize();The initialize function returns the store object, so if you have no conventions to set you can chain initialize on the end of the new Store call.
var raven = require('./node-ravendb');
var store = new raven.Store({ host: '1.1.1.1', port: 1234, database: 'Foo' }).initialize();Sessions provide the functionality to perform operations against the specified document store, they track objects and are the sole point of contact with your data. More information on the Session object can be found here.
To receive a new session, use the openSession function on your store instance.
var session = store.openSession();
session.load(...);You can add global error handlers that will catch errors passed to callbacks, and then use that global handler to return errors to your user. Errors are still passed to callbacks, so if you set a global handler and handle errors in your callback you will be handling it twice.
Global error handlers are designed to provide Raven specific error handling for HTTP errors. For example, if you get conflict errors when using etags Raven returns the HTTP 409 status code. Rather than have to handle that kind of error in every session operation you perform's callback function, you can add a global handler that will be fired instead.
To add global handlers, set them on your store object in the same way you add event listeners using the node.js EventEmitter, using the 'on' function. The on function accepts a handler id (either error, or a HTTP status code) and a function, unlike the EventEmitter only one handler can be added to each handle id. The function accepts one parameter, an Error object.
Note: The handler name 'error' is a global handler and if added will catch all errors. More specific error handlers (named by HTTP status) will fire instead of the 'error' handler.
Like conventions and options, error handlers cannot be changed after calling initialize.
var raven = require('./node-ravendb');
var store = new raven.Store({ host: '1.1.1.1', port: 1234, database: 'Foo' });
store.on('error', function (error) {
// notify my GUI
console.log(error.statusCode + ': ' + error.message);
});To catch HTTP 409 conflict errors we would do the following
var raven = require('./node-ravendb');
var store = new raven.Store({ host: '1.1.1.1', port: 1234, database: 'Foo' });
store.on('409', function (error) {
// notify my GUI using the 409 html page
console.log(error.statusCode + ': ' + error.message);
});Like the client api, you only need one Store per application. We don't have any IoC in JavaScript, but using the node.js module system we can have one store implementation and require it for each .js file that needs it.
store.js
var raven = require('./node-ravendb');
var store = new raven.Store({
host: '1.1.1.1',
port: 1234,
database: 'Foo'
});
store.initialize();
module.exports = store;dogs.js
var session = require('./store').openSession();
session.load('dogs/1', function(err, dog) {
if (err) handle(...);
else log(dog.name);
});