Tuto Start with ilorm

Vocabulary

Ilorm use different type of Class ;

• Model : The model represent a type of data handle by the ORM.
• Connector : A connector is the system which handle your database, different connector mean different database. For the next example will use the Mongodb connector. The connector is binded with model.
• Schema : The schema defines how the data are stored. Which attribute are in the given model. Schema are binded with model.
• SchemaField : The schemaField represent one field of the schema. It's define how the attribute work in the database and with in the model.
• Query : The query class is used as query builder to make powerfull query and load instance of model.

Init ilorm

Declare plugin

Ilorm is a singleton. You can bind plugin with the orm using ilorm.use(yourPlugin).

const ilorm = require('ilorm');
const ilormPlugin = require('ilorm-plugin');

ilorm.use(ilormPlugin);

Plugin change internal code in ilorm, you need to declare them before done anything with ilorm in your project.

Declare schema

To declare a schema you need to require the Schema class. The Schema class contains factory to every field.

The standard field you can declare ;

• string()
• boolean()
• number()
• date()

More complexe field can be used ;

• reference() : Reference another model (to bind different data together).
• map() : Map field (key:value). Contains a subschema.
• list() : List field ([value, value...]). Contains a subschema.

Example ;

const { Schema } = require('ilorm');

const myUserSchema = new Schema({
  firstName: Schema.string(),
  lastName: Schema.string(),
  gender: Schema.string()
});

Some field could not be supported by specific connector. And connector or plugin can add new field to the Schema.

You can specify rules to your field. Rules can be added by plugin or Connector. But the standard rules you can use on every field are :

• default() : Specify a default value at the creation of the field.
• required() : If the field is not declare, this will throw an error.

const { Schema } = require('ilorm');

const myUserSchema = new Schema({
  firstName: Schema.string().required(),
  lastName: Schema.string().required(),
  gender: Schema.string().default('M').required()
});

Declare connector

Connector are different, you need to instantiate it with a configuration. To handle MongoDB connector ;

  const { MongoClient, } = require('mongodb');
  const ilorm = require('ilorm');
  const ilormMongo = require('ilorm-connector-mongo');

  // Connector are plugin, you need to declare them ;
  ilorm.use(ilormMongo);

  mongoClient = await MongoClient.connect(DB_URL);

  database = await mongoClient.db(DB_NAME);

  // Create a class MongoConnector binded with the good database :
  const MongoConnector = ilormMongo.fromClient(database);

  // This connector handle users ;
  const userMongoConnector = new MongoConnector({
    collectionName: 'users',
  });

Create a model

To create a model, you need to bind a connector, a schema, and give name to your model.

This parameters are given to the modelFactory which create a Class representing internaly your Model, you need to extends this class if you want to add specific functions.

After, you call declareModel to save your model in ilorm (without declareModel you can have some issues).

  const { modelFactory, declareModel } = require('ilorm');

  const MODEL_NAME = 'users';

  const modelFactoryParams = {
    name: MODEL_NAME,
    schema: userSchema,
    connector: userMongoConnector
  };

  class User extends modelFactory(modelFactoryParams) {
    // You can extends your model, with your code there
  }

  declareModel(MODEL_NAME, User);

Manipulate data

Insert data

To insert data, you can use your model. There are two way to bind data with the model ;

• Give an object in parameter of your constructor
• Set the field directly

To save data, you need to call the save method. It will create or update the linked data.

  const firstUser = new User({
    firstName: 'Smith',
    lastName: 'York'
  });
  firstUser.save(); // Create
  firstUser.firstName = 'Cathy';
  firstUser.gender = 'F';
  firstUser.save(); // Update

  // OR
  const secondUser = new User();
  
  secondUser.firstName = 'Watson';
  secondUser.lastName = 'Simpson';

  // secondUser does not exists in database

  secondUser.save();
  // now secondUser exists in database

Play with model

You can load one instance with the .getById static method.

Every instance have two given method ;

• save() : To edit (or create) the instance in the database.
• remove() : To remove instance from the database.

  const user = await User.getById(ID); // You can load instance with it's id

  await user.remove(); // Delete the instance in database.

Complexe query

Every model have a query method which create a Query class linked with the database. With the Query class you can make update or query data. The query know your schema. Per example, to query all male on your database you will write ;

const query = User.query()
  .gender.is('M');

The operator you can apply to your field ;

• is(value) : field equal value
• isNot(value) : field not equal value
• isIn(arrayOfValue) : field is equal of one of the value in array
• isNotIn(arrayOfValue) : field is not equal of every value of array

To number or date, you can apply more query ;

• min(value) : The field is minimum equal or above value
• max(value) : The field is maximum equal or below value
• between(min, max) : The field is between min or max value.

To apply the query you can invoke ;

• find() ; Return an array of every element which match the query
• findOne() : Return one element which match the query
• count() : Count every element which match the query
• remove() : Delete every element which match the query
• removeOne() : Delete one element which match the query
• stream() : Return a stream of element which math the query

const query = User.query()
  .gender.is('M');

const user = await query.findOne(); // Return one user

Update query are similar than query, you can use operator ;

• set(value) ; Change the field by this value.
• add(value) ; Increment the field by value.

And to apply the query you can use ;

• update() : Update every element which match the query
• updateOne() : Update one element which match the query

await User.query()
  .gender.set('M')
  .firstName.is('Smith')
  .update();