mimir-orm

Mimir

Mimir is an ORM for client-side JavaScript applications. Mimir wraps LokiJS for lightning fast queries on client-side data. Mimir is designed for scenarios in which you are looking to store structured, relational data, such as a complex offline-first application.

Mimir is in very early development, so it should not be used for any production systems yet. In the long-run, Mimir also hopes to utilize it's model definition system to integrate with popular server side ORMs like Mongoose and Sequelize.

---

Example Usage

To begin using Mimir, first create a database then define a collection on that database. Use the Collection methods to create and find your objects within the Collection.

var database = new Mimir('my-family');
var People = database.define('person',{
  name: 'string',
  age: 'integer'
});
People.create({
  name: 'Steve',
  age: 37
});
People.create({
  name: 'Susan',
  age: 29
});

var results = People.find({
where: {
	age: 29
}
});

console.log(results);
// Outputs [{age: 29, name:'Susan'}]

Creating a Database

The Mimir class contains all of your collections and is what you will use to define new ones. Think of it like a 'root' class for your database.

To start your database off, just create a new Mimir instance like this :

var database = new Mimir('database-name');

The database name is optional and will default to 'Mimir' if not specified.

Creating Collections

Collections are where your data gets stored, similar to tables in a SQL database or collections in MongoDB.

Collections are created for each model that you define on your database. To define a model just call the Database.define function like this :

var People = database.define('people',{
  name: 'string',
  age: 'integer'
});

This will create a new database collection called 'people' and will allow you to create new objects defined in this collection with the name and age attributes that we defined.

Model Definition

As seen in the previous example, we can create a new model by using the Database.define function and providing it with a name and an argument property.

In that example, we provided 2 attributes (name and age) and gave them values of string and integer. This means that this model will not store any objects that do not contain both a name in string format and an age that must be an integer.

We can also provide other values for our model attribute definitions by giving a property and object value instead of a string value.

For example :

var People = database.define('people',{
  name: 'string',
  age: {
    type: 'integer',
    min: 18
  },
  city: {
    type: 'string',
    allowNull: true
  }
});

What we have done now is defined the same model as before, only now we have added some additional restrictions on age and the new attribute "city".

By specifying a 'min' property on the age object, we have set the minimum value that is acceptable for this field, in this case 18. We could also specify a 'max' property that would set a maximum acceptable value for the field.

On our new attribute, city, we defined it as a string, just like name. On city, however, we also set a new property of 'allowNull' to be true. Unlike name, which is required, you can now create a new Person and have a null value for their city.

Querying

To query from a collection, you will want to use the find or findOne methods on your collection object. Both methods accept the same parameter of options with the only difference being that find will return all matching values or a blank array and findOne will return the first matching value or null.

Options must be passed in the form of an object and, for now, can contain 2 properties, where and order.

The where property must be an object containing key-value pairs of attribute values to look for.

The order property must be either a string or an object. If a string, the result will be sorted in descending order based on the attribute specified in the string. If an object is used, the object must contain the property 'attribute' which will serve as the attribute name to sort by, and the property 'desc' which must be a boolean value specifiying if the order should be descending (False would make the results be listed in ascending order).

Example :

People.find({
  where: {
    age: 29
  },
  order: 'name'
});

This function will return all People who are age 29 and will order them, in alphabetical order by the name attribute.