white-label-model
A simple ES6 JS data model that emits events on data change. Offers support for collections of models. Models are for object literals and collections are for arrays and maps.
Model and collection events are emitted using Node.js' events module. For more options on how to listen to events please look at the Node.js documentation:
https://nodejs.org/api/events.html
Install
Install the node module:
npm install white-label-model --save
Model Usage
white-label-model supports models and collections, this first example is for models only.
Require
const Model = require('white-label-model').Model;
Instantiate
Create a new empty model:
const modelColor = new Model();
optionally you can also set the model data at instantiation:
const modelColor = new Model({
name: 'red'
});
Extend
extend the Model class for your own needs:
const MyModel = class extends Model {
someGreatFeature() {
console.log('this is great!');
}
};
const myModel = new MyModel();
myModel.someGreatFeature();
Events
Add change listener to the model:
modelColor.on('change', (data) => {
console.log('Model Data Change:', data);
});
Whenever a model changes it will emit a 'change' event.
Set
Save some data in the model:
modelColor.set({
name: 'red'
});
This will emit 'change' and 'set' events. If you do not what the model to emit any events you can pass in the 'silent' argument like so:
modelColor.set({
name: 'red'
}, true);
Get
Retreive the stored model data:
const redColorData = modelColor.get();
Update
Update the stored model data with new data:
modelColor.update({
name: 'blue',
isPrimaryColor: true
});
This extends the existing model data, old properties are overwritten, new properties are added to the model. This will emit 'change' and 'update' events. If you do not what the model to emit any events you can pass in the 'silent' argument like so:
modelColor.update({
name: 'blue',
isPrimaryColor: true
}, true);
Delete
This sets the model data to an empty object:
modelColor.delete();
This will emit 'change' and 'delete' events. If you do not what the model to emit any events you can pass in the 'silent' argument like so:
modelColor.delete(true);
Destroy
Call this when you are done using the model:
modelColor.destroy();
This will delete all the data and remove all listeners for the model.
Collection Usage
Collections can be either arrays or maps. They will default to arrays unless otherwise set. They can hold models or any other data types.
To support maps you will likely need to use a polyfill in your project such as the babel-polyfill:
http://babeljs.io/docs/usage/polyfill/
Require
const Model = require('white-label-model').Model;
const Collection = require('white-label-model').Collection;
Instantiate
Create a couple new models.
const modelColor1 = new Model({
name: 'red'
});
const modelColor2 = new Model({
name: 'green'
});
const modelColor3 = new Model({
name: 'blue'
});
Now create a new collection to hold the models.
If you want your collection to be an array:
const modelColors = new Collection();
or
const modelColors = new Collection(new Array());
If you want your collection to be a map:
const modelColors = new Collection(new Map());
Optionally you can also set the collection data at instantiation:
array
const modelColors = new Collection([
modelColor1,
modelColor2,
modelColor3
]);
map
const modelColors = new Collection(new Map([
['color1', modelColor1],
['color2', modelColor2],
['color3', modelColor3]
]));
Extend
extend the Collection class for your own needs:
const MyCollection = class extends Collection {
someGreatFeature() {
console.log('this is great!');
}
};
const myCollection = new MyCollection();
myCollection.someGreatFeature();
Events
Add change listeners to the models and the collection:
models:
modelColor1.on('change', (data) => {
console.log('Model 1 Data Change:', data);
});
modelColor2.on('change', (data) => {
console.log('Model 2 Data Change:', data);
});
modelColor3.on('change', (data) => {
console.log('Model 3 Data Change:', data);
});
collection:
modelColors.on('change', (data) => {
console.log('Collection Data Change:', data);
});
Whenever these models or this collection change they will emit a 'change' event.
Set
Set the collection contents:
array
modelColor1.set([
modelColor1,
modelColor2,
modelColor3
]);
map
const modelColors = new Collection(new Map([
['color1', modelColor1],
['color2', modelColor2],
['color3', modelColor3]
]));
The data must be in an array or map and this will overwrite any existing array data stored completely.
This will emit 'change' and 'set' events. If you do not what the model to emit any events you can pass in the 'silent' argument like so:
modelColor1.set([
modelColor1,
modelColor2,
modelColor3
], true);
Push
Add single items to the end of the stored collection:
array
modelColors.push(modelColor1);
modelColors.push(modelColor2);
modelColors.push(modelColor3);
map
modelColors.push('color1', modelColor1);
modelColors.push('color2', modelColor2);
modelColors.push('color3', modelColor3);
or add multiple items to the end of the stored collection:
array
modelColor1.push([
modelColor1,
modelColor2,
modelColor3
]);
map
modelColor1.push(new Map([
['color1', modelColor1],
['color2', modelColor2],
['color3', modelColor3]
]));
This will emit 'change' and 'push' events. If you do not what the model to emit any events you can pass in the 'silent' argument like so:
modelColors.push(modelColor1, false, true);
or
modelColors.push('color1', modelColor1, true);
Get
This returns then entire collection data:
const allColors = modelColors.get();
This returns only a single item from the collection at the specified index:
array
const greenData = modelColors.get(1);
map
const greenData = modelColors.get('color2');
Update
This updates a single item in the collection with new object data at the specified index:
array
modelColors.update(1, {
isPrimaryColor: true
});
map
modelColors.update('color2', {
isPrimaryColor: true
});
This extends the existing item object data, old properties are overwritten, new properties are added to the object.
or when the item data type is not an object it will simply overwrite completely the old data with new:
array
modelColors.update(1, true);
map
modelColors.update('color2', true);
This will emit 'change' and 'update' events on the collection and on the item if it is a model.
When you don't pass in an index argument the collection is updated with all new data:
array
modelColors.update([
new Model({
name: 'cyan'
}),
new Model({
name: 'magenta'
}),
new Model({
name: 'yellow'
}),
new Model({
name: 'black'
})
]);
map
modelColors.update([
['color1', new Model({
name: 'cyan'
})],
['color2', new Model({
name: 'magenta'
})],
['color3', new Model({
name: 'yellow'
})],
['color4', new Model({
name: 'black'
})]
]);
The new data must be an array or map. This will emit 'change' and 'update' events only on the collection. If you do not what the model to emit any events you can pass in the 'silent' argument like so:
modelColors.update(1, {
isPrimaryColor: true
}, true);
Delete
This deletes a model from the collection at the specified index:
array
modelColors.delete(2);
map
modelColors.delete('color3');
This sets the collection data to an empty array or map.
modelColors.delete();
It respect the previous data type. For example if it was a map it will set it to an empty map.
This will emit 'change' and 'delete' events. If you do not what the model to emit any events you can pass in the 'silent' argument like so:
modelColors.delete(2, true);
or
modelColors.delete(false, true);
Interacting with an API
The following methods have been subbed out for working with data from a service as a basic structure. They all return an object by default. You would simply redefined them when extending either the model or collection class.
modelColors.serviceGet();
modelColors.servicePatch();
modelColors.servicePost();
modelColors.servicePut();
These return promises by default.