Noomman

Nodejs Object-Oriented MongoDB Manager


Class InstanceSet

Contents

Methods

Methods

constructor(classModel, instances)
Description

Creates an instance of InstanceSet with the given classModel.

Parameters
Name Type Description
classModel ClassModel The classModel for this InstanceSet. All Instances added to this InstanceSet must be of this classModel or one of its sub-ClassModels.
Returns

InstanceSet - The InstanceSet created with the given classModel and instances.

Throws
Error Type Cause
NoommanConstructorError If classModel parameter is missing or not an instance of ClassModel.
NoommanArgumentError If instances is given and is not an Iterable.
NoommanArgumentError If instances is given and contains anything but Instances.
NoommanArgumentError If instances is given and contains any Instance of a different ClassModel.
add(instance)
Description

Adds the given Instance to this InstanceSet.

Parameters
Name Type Description
instance Instance An Instance of the ClassModel for this InstanceSet (or a sub-ClassModel) to add to this InstanceSet.
Throws
Error Type Cause
NoommanArgumentError If instance is given and is not an Instance
NoommanArgumentError If instance is given and is an Instance of a different ClassModel.
addInstances(instances)
Description

Adds the given instances to this InstanceSet.

Parameters
Name Type Description
instances Iterable<Instance> An Iterable containing Instances of the ClassModel for this InstanceSet (or a sub-ClassModel) to add to this InstanceSet.
Throws
Error Type Cause
NoommanArgumentError If instances is given and is not an Iterable.
NoommanArgumentError If instances is given and contains anything but Instances.
NoommanArgumentError If instances is given and contains any Instance of a different ClassModel.
delete(deletePrivilegeMethodParameter)
Description

Deletes all Instances in this InstanceSet from the database.

Parameters
Name Type Description
deletePrivilegeMethodParameter Object An object containing any parameters needed by a deletePrivilege method.
Returns

Promise<Array<Boolean>> - An array containing True for each deleted Instance if all Instances in this InstanceSet are deleted properly.

Throws
Error Type Cause
NoommanDeleteError If any Instance has not yet been saved (i.e. is not in the database).
NoommanDeleteError If deletePrivilegeCheck() throws a NoommanDeleteError.
difference(instanceSet)
Description

Creates a new InstanceSet which is the mathematical set difference of this InstanceSet and the given InstanceSet. Difference is this InstanceSet - given InstanceSet.

Parameters
Name Type Description
instanceSet InstanceSet An InstanceSet to subtract from this InstanceSet.
Returns

InstanceSet - The set difference of this InstanceSet and given InstanceSet.

Throws
Error Type Cause
NoommanArgumentError If instanceSet parameter is not an instance of InstanceSet.
equals(instanceSet)
Description

Determines if this InstanceSet is equal to the given InstanceSet. Two InstanceSets are considered equal if they hold the same Instances (determined by Instance id).

Parameters
Name Type Description
instanceSet InstanceSet An InstanceSet to compare this InstanceSet against.
Returns

Boolean - True if both InstanceSets hold the same Instances, false otherwise.

Throws
Error Type Cause
NoommanArgumentError If instanceSet parameter is not an instance of InstanceSet.
filterForClassModel(classModel)
Description

Creates a new InstanceSet which contains all the Instances from this InstanceSet which are of the given ClassModel (or a sub-ClassModel thereof).

Parameters
Name Type Description
classModel ClassModel A ClassModel to use to filter this InstanceSet.
Returns

InstanceSet - An InstanceSet with the same ClassModel as this InstanceSet, which contains all Instances from the origin InstanceSet which are of the given ClassModel (or a ClassModel thereof).

Throws
Error Type Cause
NoommanArgumentError If the given classModel paramter is omitted or not an instance of ClassModel.
filterForInstancesInThisCollection()
Description

Creates a new InstanceSet which is this InstanceSet filtered for those Instances that are stored in the same collection as the collection for the ClassModel of this InstanceSet.

Returns

InstanceSet - A new InstanceSet with the same ClassModel as this InstanceSet, containing all the Instances from this InstanceSet which share the same collection as this InstanceSet.

filterToInstanceSet(callback)
Description

Similar to the Array.filter() method, except that the results are compiled into an InstanceSet.

Parameters
Name Type Description
callback Function A callback function which will be run on each Instance of this InstanceSet. If this function returns true for an Instance, then the Instance will be added to the return InstanceSet.
Returns

InstanceSet - A new InstanceSet with the same ClassModel as this InstanceSet, and containing all the instances for which the given callback function returns true.

getInstanceIds()
Description

Retrieves the id for each Instance in this InstanceSet as a String and returns them in an array.

Returns

Array<String> - An array containing string representations of each Instance's id.

getInstancesWithIds(ids)
Description

Retrieves all Instances from this InstanceSet with any of the given ids.

Parameters
Name Type Description
id Array<mongodb.ObjectId> An array of ids for the Instances to retrieve.
Returns

InstanceSet - An InstanceSet with the same classModel as this InstanceSet, containing only those Instances with the given ids.

getInstanceWithId(id)
Description

Retrieves an Instance from this InstanceSet with the given id.

Parameters
Name Type Description
id mongodb.ObjectId | String An id for the Instance to retrieve.
Returns

Instance - The Instance from this InstanceSet with the given Id. Null if no Instance in this InstanceSet has the given id.

getObjectIds()
Description

Retrieves the id for each Instance in this InstanceSet and returns them in an Array.

Returns

Array<ObjectId> - An array containing each Instance's id.

hasInstance(instanceToCheck)
Description

Determines if this InstanceSet contains the given Instance. This is determined using only the id of the Instances, so the given Instance does not need to be the exact same object in memory.

Parameters
Name Type Description
instance Instance An instance to check for.
Returns

Boolean - True if this InstanceSet contains the given Instance, false otherwise.

hasInstanceWithId(id)
Description

Determines if this InstanceSet contains an Instance with the given id.

Parameters
Name Type Description
id mongodb.ObjectId | String An id to check for.
Returns

Boolean - True if this InstanceSet contains an Instance with the given id, false otherwise.

instanceAt(index)
Description

Returns the Instance at the given index as though this InstanceSet were an Array.

Parameters
Name Type Description
index Number The index of the Instance you wish to retrieve.
Returns

Instance - The Instance of the given index.

intersection(instanceSet)
Description

Creates a new InstanceSet which is the intersection of this InstanceSet and the given InstanceSet.

Parameters
Name Type Description
instanceSet InstanceSet An InstanceSet to intersect with this InstanceSet.
Returns

InstanceSet - The intersection of this InstanceSet and given InstanceSet.

Throws
Error Type Cause
NoommanArgumentError If instanceSet parameter is not an instance of InstanceSet.
isInstanceOf(classModel)
Description

Determines if this InstanceSet is an InstanceSet of the given classModel or one of its sub-ClassModels.

Parameters
Name Type Description
classModel ClassModel A ClassModel to check if this is an InstanceSet of.
Returns

Boolean - True if this InstanceSet is an InstanceSet of the given classModel or one of its sub-ClassModels. False otherwise.

mapToInstanceSet(callback)
Description

Similar to the native Array.map() method, except that the result is wrapped into a new InstanceSet.

Parameters
Name Type Description
callback Function A function which will be run for each Instance in the set. Whatever this function returns for each instance will be compiled into a new InstanceSet. This function must return an Instance which is of the same ClassModel as this InstanceSet.
Returns

InstanceSet - An InstanceSet with the same ClassModel as this InstanceSet, which contains each result of each call of the callback function.

readPrivilegeFilter(readPrivilegeMethodParameter)
Description

Runs applicable readPrivilege methods for each Instance in this InstanceSet, and filters out any Instances for which any readPrivilege method returns false. Returns a new InstanceSet, does not update this InstanceSet.

Parameters
Name Type Description
readPrivilegeMethodParameter Object An object containing any parameters that the readPrivilege method(s) may need.
Returns

Promise<InstanceSet> - An InstanceSet containing those Instances for which all readPrivilege methods return true.

remove(instance)
Description

Removes the given instance from the set. Any Instance with the same id as the given Instance will be removed from the InstanceSet, it does not have to be the same in memory object.

Parameters
Name Type Description
instance Instance An Instance to remove from this InstanceSet.
removeInstances(instances)
Description

Removes all the given Instances from this InstanceSet. Any Instance with the same id as any of the given Instances will be removed from the InstanceSet.

Parameters
Name Type Description
instances Iterable<Instance>/td> An Iterable containing Instances of the ClassModel for this InstanceSet (or a sub-ClassModel) to remove from this InstanceSet.
Throws
Error Type Cause
NoommanArgumentError If instances parameter is not an Iterable.
save(createPrivilegeMethodParameter, updatePrivilegeMethodParameter)
Description

Saves the current state of each Instance in this InstanceSet to the database in the proper collection according to its ClassModel.

Parameters
Name Type Description
createPrivilegeMethodParameter Object An object containing parameters needed by a createPrivilege method.
updatePrivilegeMethodParameter Object An object containing parameters needed by a updatePrivilege method.
Returns

Promise<Array<Instance>> - An Array containing each Instance in this InstanceSet, if save is successful.

Throws
Error Type Cause
NoommanValidationError If validate() throws a NoommanValidationError.
NoommanSaveError If any unsaved Instance in this InstanceSet fails a createPrivilege method.
NoommanSaveError If any previously saved Instance in this InstanceSet fails a updatePrivilege method.
NoommanSaveError If any Instance in this InstanceSet has been stripped of sensitive attributes.
stripSensitiveAttributes()
Description

Will remove any attributes with property sensitive equal to true from each Instance in this InstanceSet.

symmetricDifference(instanceSet)
Description

Creates a new InstanceSet which is the mathematical symmetricDifference of this InstanceSet and the given InstanceSet.

Parameters
Name Type Description
instanceSet InstanceSet An InstanceSet to calculate the symmetric difference of with this InstanceSet.
Returns

InstanceSet - The symmetric difference of this InstanceSet and given InstanceSet.

Throws
Error Type Cause
NoommanArgumentError If instanceSet parameter is not an instance of InstanceSet.
union(instanceSet)
Description

Creates a new InstanceSet which is the mathematical set union of this InstanceSet and the given InstanceSet.

Parameters
Name Type Description
instanceSet InstanceSet An InstanceSet to union with this InstanceSet.
Returns

InstanceSet - The union of this InstanceSet and given InstanceSet.

Throws
Error Type Cause
NoommanArgumentError If instanceSet parameter is not an instance of InstanceSet.
validate()
Description

Throws an error if any Instance in this InstanceSet is invalid for any reason, including violations of custom validations, required properties, required groups, or mutexes.

Throws
Error Type Cause
NoommanValidationError If Instance.validate() throws a NoommanArgumentError for any Instance in this InstanceSet.
walk(relationshipName)
Description

Walks the relationship with the given relationshipName for every Instance in this InstanceSet, and returns the result in a single InstanceSet. Will populate the relationship on each Instance as well.

Parameters
Name Type Description
relationshipName String The name of a relationship to walk.
Returns

Promise<InstanceSet> - an InstanceSet containing all the Instances related to the Instances in this InstanceSet through the relationship with the given relationshipName.

Throws
Error Type Cause
NoommanArgumentError If no relationshipName is given.
NoommanArgumentError If relationshipName is not a String.
NoommanArgumentError If relationshipName does not match a relationship on the ClassModel for this InstanceSet.
walkPath(path)
Description

Walks a path of multiple relationships from the Instances in this InstanceSet, returning an InstanceSet containing all Instances at the end of the path.

Parameters
Name Type Description
path Array<String> An Array containing the names of the relationships to walk.
Returns

Promise<InstanceSet> - The InstanceSet of Instances related to the Instances in this InstanceSet through the given relationships. If there are no Instances at the end of the path, or path cannot be walked all the way to the end, the returned InstanceSet will be empty.

Throws
Error Type Cause
NoommanArgumentError If path is not an Array.
NoommanArgumentError If path contains any items that are not a string.
NoommanArgumentError If path contains any items that are not a valid relationship for the relavant ClassModel.