fusionjs/README.md

FusionJS is a JS toolkit that provides library/framework agnostic tools

Fusion JS
============

"*One library to bind them all.*"

Fusion JS provides:
 * Data modelling and state management utilities.
 * Work in progress;
   * A workspace boilerplate that enables you to integrate your preferred libraries with ease. 
   * A library of accessible UI components (Planned for future release)

FusionJS is agnostic with regards to the JS framework or library you want to use. And was infact created specifically to enable apps to be written with any library without restriction to include swithcing app development to a different set of frameworks and libraries if required.


### Data modelling and state management utilities

The data modelling and state management utilities consists of two parts; FusionModel and FusionImmutable.


### FusionModel

FusionModel is the M in MVC and provides a means to represent data that your application manages. It provides
one-to-one and one-to-many relationship capabilities

#### Getting started

```javascript
npm install fusionjs
```

Then require it into any module.
```javascript
import {FusionModel} from 'fusionjs';
```


FusionModel is designed as an Abstract class and is not expected to be instantiated. To use it, extend it to create 
your model class. 
Derived classes must contain constructor functions and must call init() after super() as shown.
Fields property must be supplied.

```javascript
import {FusionModel} from 'fusionjs';
export class TestModel extends FusionModel {

	idProperty = 'testModelId';

	fields = [{
		name: 'testModelId',
		type: 'string'
	}];

	constructor(data) {
		super(data);
		this.init();
	}
}
```


#### Nested structures
To represent one-to-one and one-to-many relationships, apply hasMany and hasOne properties as shown;

```javascript
/*
For example, for the following sample data;
let sampleData = { 
	testId: 123,
	testValue: 'one, two, three',
	relOne: {
		testRelId: 1123,
		testRelValue: 'two hundred and something'
	},
	rels: [{
		testRelId: 2123,
		testRelValue: 'two hundred and something odd'
	}, {
		testRelId: 2122,
		testRelValue: 'two hundred and something even'
	}]
}
*/

import {FusionModel} from 'fusionjs';
export class TestRelModel extends FusionModel {

	idProperty = 'testRelId';

	fields = [{
		name: 'testRelId',
		type: 'string'
	}, {
		name: 'testRelValue',
		type: 'string'
	}];

	constructor(data) {
		super(data);
		this.init();
	}
}
export class TestModel extends FusionModel {

	idProperty = 'testId';

	fields = [{
		name: 'testId',
		type: 'string'
	}, {
		name: 'testValue',
		type: 'string'
	}];

	hasOne = [{
        name: 'rel',
        model: TestRelModel
    }];

	hasMany = [{
        name: 'rels',
        model: TestRelModel
    }];

	constructor(data) {
		super(data);
		this.init();
	}
}
```

#### Using your model
```javascript

let testModel = new TestModel(sampleData);
//get model data
testModel.get(); //Will return the top level data 
test.rels();	//returns a store contaning your hasMany data collection
test.rels().get(); //returns a collection (an array) of records representing your "hasMany" data
test.relOne(); //returns a record representing your "hasOne" data

//you can set data after instantiation like so;
let testModel = new TestModel();
testModel.set(sampleData);

//you can set data to a deeply nested record like so;
testModel.rels().get()[0].set({
	testRelId: 45678,
	testRelValue: 'test'
});

//return a JS object of data in your model
testModel.toObject();

//checking equality
testModel.equals(anotherTestModel); //(Value equality checker) will return true if both models contain the same values (check does NOT include nested data)
testModel.deepEquals(anotherTestModel); //(Value equality checker) will return true if both models contain the same values (check includes nested data)
testModel.strictEquals(anotherTestModel); //(Value/Reference equality checker)  will return true if both models contain the same data (check includes nested data) and are the same instance

//To find a deeply nested record
testModel.find(myDeeplyNestedRecord);
```


### FusionImmutable
FusionJS provides immutable state management capability via its FusionImmutable module.


#### Usage


Require it into any module.
```javascript
import {FusionImmutable} from 'fusionjs';
//Where TestModel is a derived FusionModel class
let fusionImmutable = new FusionImmutable(TestModel),
	initialState = fusionImmutable.fromJS({
		id: null,
		rel: {},
		rels: []
	});
```

#### To update with state immutability, use the merge() method
```javascript
import {FusionImmutable} from 'fusionjs';
//Where TestModel is a derived FusionModel class
let fusionImmutable = new FusionImmutable(TestModel),
	state = fusionImmutable.fromJS({
		id: null,
		rel: {},
		rels: []
	});
fusionImmutable.merge(state, newData);
//Or if data is meant to update a deeply nested record within the model, then pass the record as a third argument;
fusionImmutable.merge(state, newData, record);
```

### Known Issues
 * TypeError: Class constructors FusionModel cannot be invoked without 'new'
   - Solution: You will need to use a babel preset that is targeted to your platform

	```javascript
	 npm install babel-preset-es2015-node-auto // (OR specify one, e.g. babel-preset-es2015-node5, babel-preset-es2015-node6)

	 //then configure your loader, for example in webpack config;
	 {
		test: /\.js?$/,
		exclude: /node_modules/,
		loader: 'babel',
		query: {
			presets: ['react', 'es2015-node6', 'stage-0']
		}
	}
	 ```