Noomman

Class Models

Class Models are the core of noomman. Class Models define the shape of the data you wish to store, as well as validations, privileges, and methods.

Class Models are created by calling new ClassModel() and passing as an argument a schema object. The shape of the schema object is shown below with the types of each property. Only the className property is required, and in general omitting a property leads to the behavior that property represents being disabled.

                    
    {
        className: String (required),
        superClasses: [ ClassModel ],
        abstract: Boolean,
        useSuperClassCollection: Boolean,
        auditable: Boolean,
        attributes: [
            {
                name: String (required), 
                type: String (required), 
                list: Boolean,
                required: Boolean,
                unique: Boolean,
                sensitive: Boolean,
                mutex: String,
                requiredGroup: String,
            },
        ],
        relationships: [
            {
                name: String (required),
                toClass: String (required),
                singular: Boolean (required),
                required: Boolean,
                owns: Boolean,
                mirrorRelationship: String,
                mutex: String,
                requiredGroup: String,
            }
        ],
        privileges: {
            create: Function,
            read: Function,
            update: Function,
            delete: Function,
            sensitive: Function,
        },
        validations: [ Function ],
        indices: [ fieldOrSpec ], 
        staticMethods: {
            methodName: Function,
            methodName: Function,
            ...
        },
        nonStaticMethods: {
            methodName: Function,
            methodName: Function,
            ...
        },
    }
                    
                

The top-level properties of a schema object are the following:

                    
const User = new ClassModel({
    className: 'User',
    attributes: [
        {
            name: 'firstName',
            type: String,
        },
        {
            name: 'lastName',
            type: String,
        },
    ],
    staticMethods: {
        getAdults: async function() {
            return User.find({age: {$gte: 18}});
        },
    },
    nonStaticMethods: {
        fullName: function() {
            return this.firstName + ' ' + this.lastName;
        },
    },
});

...

const adults = await User.getAdults();
console.log('Found these adults: ' + adults.map(user => user.fullName());
                    
                

Instances

The Instance Class in noomman provides a set of methods for working with your data. When creating an Instance, you provide the Class Model for that Instance, and all aspects of that Class Model will be enforced for your Instanes. Any query run on a Class Model will return Instances.

Any Instance you create or get from a query will have methods for editing, comparing, saving, and deleting that Instance. When saving an Instance, all validations and requirements defined on the Class Model for that Instance will be evaluated before save.

Creating Instances

Instances in noomman are created by calling new Instance() and passing as an argument the Class Model for that Instance. The next example assumes that a Class Model has been created called User.

                    
    const noomman = require('noomman');
    const Instance = noomman.Instance;

    const User = require('./path/to/User');

    const newUser = new Instance(User);
                    
                

From here, you can use the assign() method to assign all or some of the attributes and relationships for your instance from an object. Alternatively, you could set the attributes and relationships one at a time.

                    
    newUser.assign({
        userName: 'coolUser1',
        email: 'cool@email.com',
        password: '***************',
    });                  
                    
                

                    
    newUser.userName = 'coolUser1';
    newUser.email = 'cool@email.com';
    newUser.password = '***************';          
                    
                

Instance Properites

All Instances in noomman have share a few properties regardless of Class Model.

All Instances have an id, which is the mongodb ObjectId of the Instance. You can access this property on an instance using '._id'. For convenience, you can also access this id as a String (rather than an ObjectId object) by using '.id'.

                    
const instance = new Instance(SomeClassModel);
const objectId = instance._id; //Returns the id as an ObjectId object.
const idAsString = instance.id; //Returns the id as the hexString representation of the ObjectId object.
                    
                

All Instances have a Class Model, which you can access with the classModel property.

                    
const instance = new Instance(SomeClassModel);
console.log(instance.classModel === SomeClassModel) // logs true
                    
                

Saving Instances

Saving Instances in noomman is as easy as calling save() . Behind the scenes, noomman will validate the properties on the Instance to make sure they conform to the Class Model schema, and throw an error if they do not.

                    
await newUser.save();
                    
                

This instance.save() method is an asynchronous function, so you should use await or use a .then() to wait for the promise to resolve.

instance.save() returns a promise which resolves with the instance that was saved. It is the exact same object as the instance that you called save on, so you don't necessarily have to use the returned instance if you want to make more changes, you could use the one you already had. i.e.

                    
const savedUser = await newUser.save();
// The next statement will print 'true' to the console.
console.log(newUser === savedUser);
                    
                

If there is an error, instance.save() will throw the error for your code to handle. A save error may occur due to your custom validations defined on you ClassModel schema, a missing required attribute or relationship, or a mutex or required group validation. It is up to you to handle these errors. If your code is assuming that your instance should pass all these validations, then you might want to log the error in your application's error log for debugging. If you are taking in potentially bad input from a user, you might want to catch the error and then have your UI prompt the user for better input.

Deleting Instances

Instances can be deleted using the instance.delete() method. Instances can only be deleted if they are already in the database. Attempting to delete an instance which has never been saved, or which has already been deleted will throw an error. The delete method is asynchronous and will resolve if the delete is successful.

                    
await newUser.delete(); 
                    
                

Handling Relationships on Instances

More Helpful Methods

Creating Instance Sets

InstanceSets are created using new InstanceSet() At a minimum, you must supply the InstanceSet constructor with the ClassModel of the instances it is holding. There is second arguemnt, instances, which you can use if you already have instances you would like to add to the set. The second argument must be an iterable object containing instances. All instances added to an InstanceSet (whether during construction or after construction) must be of the same ClassModel of the InstanceSet, or a sub class thereof.

                    
const users = new InstanceSet(User);
                    
                

Adding Instances to Instance Sets

There are 3 ways to add instances to an InstanceSet. The first is during construction. When adding instances using the constructor you must pass in an iterable object (array, set, or InstanceSet) containing instances.

                    
// Adding instances during construction.
const user1 = new Instance(User);
const user2 = new Instance(User);

const users = new InstanceSet(User, [user1, user2]);
                    
                

The next way to add instances to an InstanceSet is using the instanceSet.add() method. When adding instances using the instanceSet.add() method, you pass in a single instance you would like to add as the only argument to the method.

                    
// Adding instances using the instanceSet.add() method.
const user1 = new Instance(User);
const user2 = new Instance(User);

const users = new InstanceSet(User);
users.add(user1);
users.add(user2);
                    
                

The final way to add Instances to an InstanceSet is to use the instanceSet.addInstances() method. instanceSet.addInstances() method. When using the instanceSet.addInstances() method, you must pass in an iterable object (array, set, or InstanceSet) containing instances.

                    
// Adding instances using the instanceSet.addInstances() method.
const user1 = new Instance(User);
const user2 = new Instance(User);

const users = new InstanceSet(User);
users.addInstances([user1, user2]);
                    
                

Removing Instances from Instance Sets

Similar to adding instances to a InstanceSet, instances can be removed from an InstanceSet using the instanceSet.remove() and instanceSet.removeInstances() methods. The instanceSet.remove() method takes a single instance as an argument and the instanceSet.removeInstances() method takes an iterable object (array, set, or InstanceSet) as an argument. The methods determine what Instance to remove from an InstanceSet using the object Ids of the instance, rather than object equallity. Both methods return true if all given instances have been removed from the set. If you try to remove an instance that is not a part of the set, an error will be thrown. (If you're trying to remove some set of instances that may or may not be in an InstanceSet, see Set Math With Instance Sets).

                    
// Removing instance using the instanceSet.remove() method.
users.remove(user1);
                    
                

                    
// Removing instances using the instanceSet.removeInstances() method.
users.removeInstances([user1, user2]);
                    
                

Checking For Instances In An Instance Set

You can easily check if an InstanceSet contains a particular Instance in one of two ways.

If you already have the Instance you're looking for in a variable, you can use the instanceSet.hasInstance() method. This method takes an Instance as an argument and returns true if the InstanceSet contains that instance, and returns false otherwise.

                    
const user = new Instance(User);
const userSet = new InstanceSet(User, [user]);

console.log(userSet.hasInstance(user)); // true
                    
                

If you only have the id of the Instance you are looking for, you can use the instanceSet.hasInstanceWithId() method. This method takes an ObjectId object or a string as a parameter.

                    
const user = new Instance(User);
const userSet = new InstanceSet(User, [user]);

console.log(userSet.hasInstanceWithId(user._id)); // true
console.log(userSet.hasInstanceWithId(user.id)); // true
                    
                

Retrieving Instances from Instance Sets

It is easy to get individual Instances out of an InstanceSet.

If you want to treat the InstanceSet as if it were an array, you can call the instanceSet.instanceAt() method. This method takes a single parameter, index, which should be a positive number. The method will create an Array from the InstanceSet and return to you the Instance at the given index.

                    
const user = new Instance(User);
const userSet = new InstanceSet(User, [user]);

const alsoUser = userSet.instanceAt(0);
console.log(alsoUser === user); // true
                    
                

If you have the id of the Instance you are looking for, you can use the instanceSet.getInstanceWithId() method. This method takes an ObjectId object or a string as a parameter.

                    
const user = new Instance(User);
const userSet = new InstanceSet(User, [user]);

console.log(userSet.getInstanceWithId(user._id) === user); // true
console.log(userSet.getInstanceWithId(user.id) === user); // true
                    
                

Set Math with Instance Sets

The InstanceSet class provides non-static methods for set math on InstanceSets. All of these methods return a new InstanceSet, with the ClassModel of the InstanceSet that the method was called on. These methods do not update the original InstanceSets.

There are four set math methods, union(), difference(), intersection(), symmetricDifference(). These correspond to the basic set math opperations. For information on set math, see this wikipedia page. (Note that another name for difference is relative compliment.)

                    
const user1 = new Instance(User);
const user2 = new Instance(User);
const user3 = new Instance(User);

const users1 = new InstanceSet(User, [user1, user2]);
const users2 = new InstanceSet(User, [user2, user3]);

// union is a new InstanceSet containing user1, user2, user3
const union = users1.union(users2);

// difference is a new InstanceSet containing user1
const difference = users1.difference(users2);

// intersection is a new InstanceSet containing user2
const intersection = users1.intersection(users2);

// symmetricDifference is a new InstanceSet containing user1, user3
const symmetricDifference = users1.symmetricDifference(users2);
                    
                

ForEach, Map, Reduce, and Filter with Instance Sets

InstanceSet has non-static methods for looping, mapping, reducing, and filtering instance sets. These methods each follow the same conventions as the native javascript methods on the Array class. instanceSet.map() and instanceSet.filter() each return an Array, while reduce returns a single value or object (or an Array if you code it that way). instanceSet.forEach() will iterate through all the instances in an InstanceSet and call your callback for each one, passing the instance as an argument. For general information on these functions, see this helpful medium post .

InstanceSet also has versions of map and filter which return a new InstanceSet instead of an Array. These methods are instanceSet.mapToInstanceSet() and instanceSet.filterToInstanceSet(). They take the same arguments and operate the same as the regular map and filter methods, except that they return an InstanceSet with the same ClassModel as the InstanceSet that the method was called on.

                        
const filteredUsers = users.filterToInstanceSet(user => user.userName === "coolUser1");

// The above is the equivalent of the following:
const filteredUsersArray = users.filter(user => user.userName === "coolUser1");
const filteredUsers = new InstanceSet(User, filteredUsersArray);
                        
                    

Querying with Instance Sets (For Future Release)

InstanceSet has a non-static query method, which allows you to filter the InstanceSet using MongoDB style filter objects. This does not make a database call, rather it is just another convenient way to filter an Instance Set. The query method returns a new InstanceSet with the same ClassModel as the original set and does not update the original InstanceSet. This is implemented using the npm package mingo.

                            
const filteredUsers = Users.filterToInstanceSet(User => User.userName === "coolUser1");

// The above is the equivalent of the following:
const filteredUsers = Users.query({ userName: "coolUser1" });
                            
                        

Saving Instance Sets

InstanceSet has non-static method instanceSet.save() which will save all the instances in the set. It is smart enough to only save those instances which you have made changes to or are brand new instances. It also will run the correct validations for each instance in the Instance Set before saving (including custom validations, required, mutex, and required group validations and create and update functions). All of the validations run before any instance is saved. If any of the instances fail any validation or privilege function, none of the instances will be saved and an error will be thrown.

                            
await Users.save();
                            
                        

Deleting Instance Sets

InstanceSet has non-static method instanceSet.delete() which will delete all of the instances in the InstanceSet. It will run the delete function(s) for each instance using the instances ClassModel. If an error is thrown for any instance by a delete function, the error will be thrown by the delete method and none of the instances will be deleted.

                            
await Users.delete();
                            
                        

Find

The find() method is the most basic query method. It will return an InstanceSet with the same ClassModel as the ClassModel that you called find on. The returned InstanceSet will contain all the instances of the ClassModel (and its sub ClassModels) from the database matching your query.

Assuming there is a User saved with the user name 'coolUser1', the following example will return an InstanceSet containing that instance.

                    
const coolUser1InstanceSet = await User.find({ userName: 'coolUser1' });
                    
                

Find One

The findOne() method is similar to the find method, except that it will only return a single instance, rather than an InstanceSet. If multiple instances would match your query, only the first one found will be returned (there is no guarantee which instance would be the 'first one found'). If no instance is found matching the query, null will be returned.

Assuming there is a User saved with the user name 'coolUser1', the following example will return the User instance for that user name.

                    
const coolUser1 = await User.findOne({ userName: 'coolUser1' });
                    
                

Find By Id

The findById() method behaves the same as findOne, except that it accepts an ObjectId as an argument. The object id can either me an ObjectId object or its hex string equivalent. One key difference between findById() and findOne() is that findById() will return null if you don't pass it an object id, while calling findOne with a query { _id: undefined } will return the first instance it evaluates. If no instance is found matching a query, null will be returned.

                    
const coolUser1 = await User.findOne({ userName: 'coolUser1' });
const coolUser1UsingFindById = await User.findById(coolUser1.id);

console.log(coolUser1.equals(coolUser1UsingFindById)); // true
                    
                

Setting Relationships

Setting a relationship on an instance is as easy as setting a property on an object. Singular relationships must be set to an Instance and non-singular relationships must be set to an InstanceSet. Whether singular or non-singular, the Instance or InstanceSet that you set a relationship to must be of the same ClassModel that set as the 'toClass' in the ClassModel schema (or a sub ClassModel there of). Otherwise an error will be thrown.

                    
const noomman = require('noomman');
const Instance = noomman.Instance;

const User = require('./path/to/User');
const Person = require('./path/to/Person');

async function createAccountForJohnny() {
    const johnny = new Instance(Person);
    johnny.assign({
        firstName: 'Johnny',
        lastName: 'Nanners',
        dateOfBirth: new Date('1984-05-16');
    });
    
    const johnnyAccount = new Instance(User);
    johnnyAccount.assign({
        userName: 'johnny84',
        email: 'johnnynanners@email.com',
        password: 'ih8CT',
    });
    
    johnny.user = johnnyAccount;
    
    await johnny.save();
}

createAccountForJohnny().catch(error => console.error(error.message));
                    
                

In the above example, we create two instances: johnny and johnnyAccount. We set the attributes of each, and then we set the 'user' relationship of johnny (a Person) to johnnyAccount (a User). Then we save both instances.

You may be wondering why we did not set the relationship 'person' on johnnyAccount (the User) to johnny (the Person). Noomman will do this automatically for us when we call save. It will see that the one Instance is related to the other, and that the other side of the relationship is not set (the mirrorRelationship). You might also wonder why we only call save on johnny. The reasoning is the same, Noomman knows that johnny is related to johnnyAccount, and that johnnyAccount has changes to it (in this case it never existed in the first place), and so Nooman will implicitly call johnnyAccount.save() as well (only after setting the reverse relationship). This is the magic of Noomman.

Note: If you were to set both sides of the relationship, it would have the same effect. Also if you were to call save on both instances, it would have the same effect, and your second call to save wouldn't actually insert or update any documents in the database, because Noomman will see that there have been no new changes to those instances since the last save. Below see the same code with the extra relationship set and the second call to save.

                    
const noomman = require('noomman');
const Instance = noomman.Instance;

const User = require('./path/to/User');
const Person = require('./path/to/Person');

async function createAccountForJohnny() {
    const johnny = new Instance(Person);
    johnny.assign({
        firstName: 'Johnny',
        lastName: 'Nanners',
        dateOfBirth: new Date('1984-05-16');
    });
    
    const johnnyAccount = new Instance(User);
    johnnyAccount.assign({
        userName: 'johnny84',
        email: 'johnnynanners@email.com',
        password: 'ih8CT',
    });
    
    johnny.user = johnnyAccount;

    // This next line is not necessary, but causes no harm.
    johnnyAccount.person = johnny;
    
    await johnny.save();

    // This next line will not actually 'save' anything, because
    // no changes have been made to the instances since the 
    // last call of save(). It is unnecessary but not harmful.
    await johnnyAccount.save();
}

createAccountForJohnny().catch(error => console.error(error.message));
                    
                

Walking Relationships

In Noomman, we refer to the act of getting the instances referenced in a relationship as 'walking' the relationship. If the relationship was just set within the same transaction (i.e. the relationship is populated) then Noomman will just return to you that Instance or InstanceSet, without making a call to the database. If however, you just had an instance returned from a query (i.e. relationship is not populated), and you walk a relationship from it, then Noomman will do a query for those instances from the database, set the relationship to the returned Instance or InstanceSet (populate the relationship), and then return the Instance or InstanceSet to you. For this reason, walking relationships is always asynchronous, even if a relationship is already populated.

In this example, we create an instance from scratch, set the relationship, and then walk the relationship. In this case no query is executed because the relationship is already populated, though we do have to use await on it anyway.

                    
const noomman = require('noomman');
const Instance = noomman.Instance;

const User = require('./path/to/User');
const Person = require('./path/to/Person');

async function testWalkingRelationship() {
    const johnny = new Instance(Person);
    johnny.assign({
        firstName: 'Johnny',
        lastName: 'Nanners',
        dateOfBirth: new Date('1984-05-16');
    });
    
    const johnnyAccount = new Instance(User);
    johnnyAccount.assign({
        userName: 'johnny84',
        email: 'johnnynanners@email.com',
        password: 'ih8CT',
    });
    
    johnny.user = johnnyAccount;

    // Here we walk the relationship. Because we just 
    // set the relationship, no query is executed. 
    const shouldBeJohnnyAccount = await johnny.user;

    // Next statement prints 'true' to the console.
    console.log(johnnyAccount.equals(shouldBeJohnnyAccount));
}

testWalkingRelationship().catch(error => console.error(error.message));
                    
                

In the next example, we assume johnny and johnnyAccount have been saved to the database already. In this case, walking the relationship does execute a query.

                    
const johnnyAccount = await User.findOne({
    userName: 'johnny84',
});

// Here we walk the relationship. Because we just retrieved
// johnnyAccount from the database using a query, the 'person' 
// relationship is not populated yet, so a query must be executed
// by Noomman.
const johnny = await johnnyAccount.person;

const alsoJohnny = Person.findOne({
    firstName: 'Johnny',
    lastName: 'Nanners',
    dateOfBirth: new Date('1984-05-16'),
});

// This next line will print 'true' to the console.
console.log(johnny.equals(alsoJohnny));


// If we walk the relationship a second time, no query
// is executed, because the relationship was populated
// the first time we walked the relationship.
johnnyOneMoreTime = await johnnyAccount.person;

// This next line will print 'true' to the console. Note 
// we can use a === here because the exact same instance object
// is returned as when we first walked the relationship.
console.log(johnny === johnnyOneMoreTime);