almostjs-extend

ALMOsT is an AgiLe MOdel Transformation framework for JavaScript

This repository contains the model extender module. For a whole set of helpers see the whole project ALMOsT

This module gives you a set of tools to easily enreach your models with a set of helpers that make rules implementation faster.

Installation

$ npm install almost-extend

The Model

ALMOsT does not make any assumption on the structure of your your elements or relations between elements. The only assumption is made on the structure of the input model.

It must be an Object with at least two properties elements and relations which are Arrays.

  {
    "elements": [],
    "relations": []
  }

almostjs-extend though makes some more assumptions.

The model itself remains the same, but you are not allowed to add other attributes to it, except to metadata.

  {
    "elements": [], // mandatory
    "relations": [] // mandatory
    "metadata": {} // optional
  }

Elements

In almostjs-extend elements must be structured as follow.

Elements must be Objects with the following attributes:

• id a String uniquely identifing the element
• type a String identifing the type of the element
• attributes an Object containing the attributes of the element (the internal structure is not fixed by this module)
• metadata [Optional] an Object containing data not necessary to describe the element, but useful to enreach its description. (They shouldn't be used inside the rule Activation Expression)

Relations

In almostjs-extend relations must be structured as follow.

Relations must be Objects with the following attributes:

• type a String identifing the type of relation
• all the other attributes must be Strings identifying one element in the elements array

Configuration

With almostjs-extend you can create and Extender a function which takes as input a valid model and generates and enreached version of it, based on a set of configurations.

  var createExtender = require('almost-extend').createExtender;

  var extend = createExtender({
    type: {},
    relation: {}
    custom: {}
  });

  var extended_model1 = extend(model1);
  var extended_model2 = extend(model2);
  // ...
  var extended_modelN = extend(modelN);

Helpers

The extended model will preserve the same elements, relations and metadata attributes of the original model.

It will have a set of helpers:

• toElement(element | id) an helper which maps an id to its element (if an element is passed it will returned as it is)
• toId(element | id) an helper which maps an element to its id (if an id is passed it will returned as it is)
• is[Type](element | id, [default]) a configurable set of helpers which facilitate type identification (if a default value is provided it will be returned in case the element or the id does not exists)
• get[Relative](element | id, [default]) a configurable set of helpers which facilitate relation navigation (if a default value is provided it will be returned in case the element, the id or the relatives does not exist)
• custom(...) a configurable set of custom helpers which can be used for custom checks or graph navigations

Type Checking

isType helpers are generates starting from the type attribute of the configuration object.

The type configuration must be and Object where each attribute can be a String or and Array of Strings.

  {
    "Foo": "my.identifier.for.foo",
    "Bar": "my.identifier.for.bar",
    "Both": ["my.identifier.for.foo", "my.identifier.for.foo"]
  }

This configuration will generate the helpers:

• isFoo which checks if an element (or the element related to an id) is has type "my.identifier.for.foo"
• isBar which checks if an element (or the element related to an id) is has type "my.identifier.for.bar"
• isBoth which checks if an element (or the element related to an id) is has type "my.identifier.for.foo" or "my.identifier.for.bar"

Graph Navigation

getRelative helpers are generates starting from the relation attribute of the configuration object.

The relation configuration must be and Object where each attribute is an Object with the following attributes:

• relation the type of the relation to navigate
• from the name of the reference in the relation objects where is stored the id sorce of this navigation
• to the name of the reference in the relation objects where is stored the id target of this navigation
• single [optional] if set to true the helper is configured for single lookup.

  {
    "Parent": {relation: "hierarchy", from: "child", to: "parent", single: true},
    "Children": {relation: "hierarchy", from: "parent", to: "child"}
  }

This configuration will generate the helpers:

• getParent which returns the parent of an element (accepts an element or an id as input)
• getParentId which returns the id of the parent of an element (accepts an element or an id as input)
• getChildren which returns an Array containing the ids of the children of an element (accepts an element or an id as input)

Custom Helpers

custom helpers are generated starting from the custom attribute of the configuration object.

The relation configuration must be and Object where each attribute is a Function which will be attached to the model object. Inside this helpers the this will always refer to the model.