<commit_before># firebase-mapper
![Build Status](https://travis-ci.org/webduvet/firebase-mapper.svg?branch=master)

Development version, this README is old.., use with care


Simple data mapper for firebase. Encapsulate the Firebase reference and the data model stored under the reference. firebase-mapper as well
can handle the objects containing primary lists and lists from reference objects pointing to other database locations.

## Example

	UserList
		User1: {primary user data}
		user2: {primary user data}
		user3: {primary user data}

	ChatRoom
		chatroomData: {data},
		chatroomAudience:
			User1: true,
			User2: true

Chatroom object contains a list of user references to indicate who is in the chatroom

## Motivation
Storing data in document storage requires certain level of denormalization. Developer very quickly moves away from all the nice tools relational database
offers and swims in deep water of denormalized data.

Model representation.
The document based databases have a great advantage that the documents does not need to follow the rigid structure. Not required fields are just not present.
Firebase behaves in the very same way

	ref.set({prop1: null, prop2, "sample"});

will propagate only `prop2` into DB and subsequently when retrieveing from db the object does not contain `prop1`. Of the property is added in later stage it will cause
to break hidden class and hinders the over performance. 

The Model representation is created from blueprint with all the optional and possible fields, thus the objects shape will never change and can be optimizes 
[see hidden class]https://developers.google.com/v8/design


## Solution
Firebase is document type DBAAS, web or server client interacts with database via Firebase reference where he passes a location to data. 
Any custom logic, more complex objects with relations to other objects and all CRUD operations need to be implemented on client or on server side.
Firebase-mapper creates an object representing the database object and the relation to other object through references. It sets up the shape of the 
javascript object and allows to interact with data just by assigning values to object's property with background or explicit synchronisation with database.

Blueprint and model tool is here define the object shape.  This project aims to create factory method which creates firebase friendly model representation of firebase data.
In the blueprint we define the structure and relations and let the model figure out all the denormalized data.


## Installation
via npm

	npm install firebase-mapper

	var Fm = require('firebase-mapper');


## API 

### Init
ModelFactory needs to be instantiated with valid db reference like
creates the factory with reference and provided blueprint. 

	var factory = new ModelFactory(new Firebase('url'), blueprint);

	var obj = factory.create(ID); // creates new object pointing to location ref/ID using factory's blueprint
	obj.save() // saves all default values to database, if all null the save is cancelled

	obj.on('saved', handler);  // listen when object is saved



### Load object from DB
Model factory can load model from DB location

from database

	var n = list.get(id);
	n.load();

from object other object, it populates only the matching properties and others are ignored

	var n = modelFactory.create(ref);
	n.loadFromObject(object); // TODO - us .load() -if a param is used then do not use DB but provided object


in both cases the event "loaded" is dispatched

n.on('loaded', function(){<commit_msg>revision on README - just few paragraphs in the beginning<commit_after># firebase-mapper
![Build Status](https://travis-ci.org/webduvet/firebase-mapper.svg?branch=master)

Development version, this README is old.., use with care


Simple data mapper for firebase. Encapsulate the Firebase reference and the data model stored under the reference. firebase-mapper as well
can handle the objects containing primary lists and lists from reference objects pointing to other database locations.

## Example

	UserList
		User1: {primary user data}
		user2: {primary user data}
		user3: {primary user data}

	ChatRoom
		chatroomData: {data},
		chatroomAudience:
			User1: true,
			User2: true

Chatroom object contains a list of user references to indicate who is in the chatroom

## Motivation
Storing data in document storage requires certain level of denormalization. Developer very quickly moves away from all the nice tools relational database
offers and swims in deep water of denormalized data.

Model representation.
The document based databases have a great advantage that the documents does not need to follow the rigid structure. Not required fields are just not present.
Firebase behaves in the very same way

	ref.set({prop1: null, prop2, "sample"});

The above will propagate only `prop2` into DB and subsequently when retrieveing from db the object does not contain `prop1`. Of the property is added in later stage it will cause
to break hidden class and hinders the over performance. 

The Model representation is created from blueprint with all the optional and possible fields, thus the objects shape will never change and can be optimizes. Once the model object is created
and instantiated with values from database, even if the database does not contain the entire object it will have the missing properties set to null. The object will be complete with
no further suprises.  
[see hidden class]https://developers.google.com/v8/design
TODO possible option to lock the model so any attempt to extend it would fail - (look into Crockford way of treating objects)


## Solution
Firebase is document type DBAAS, web or server client interacts with database via Firebase reference where he passes a location to data. 
Any custom logic, more complex objects with relations to other objects and all CRUD operations need to be implemented on client or on server side.
Firebase-mapper creates an object representing the database object and the relation to other object through references. It sets up the shape of the 
javascript object and allows to interact with data just by assigning values to object's property with background or explicit synchronisation with database.

Blueprint and model tool is here define the object shape.  This project aims to create factory method which creates firebase friendly model representation of firebase data.
In the blueprint we define the structure and relations and let the model figure out all the denormalized data.


## Installation
via npm

	npm install firebase-mapper

	var Fm = require('firebase-mapper');


## API 

### Init
The Fm singleton is initialized with one database connection and subsequently all objects created by the factories enclosed in Fm namespace
inherit this database connection. 
TODO implement this thoroughly!!!!

Factory:
creates the factory with reference and provided blueprint. 

	var factory = new ModelFactory(new Firebase('url'), blueprint);

	var obj = factory.create(ID); // creates new object pointing to location ref/ID using factory's blueprint
	obj.save() // saves all default values to database, if all null the save is cancelled

	obj.on('saved', handler);  // listen when object is saved



### Load object from DB
Model factory can load model from DB location

from database

	var n = list.get(id);
	n.load();

from object other object, it populates only the matching properties and others are ignored

	var n = modelFactory.create(ref);
	n.loadFromObject(object); // TODO - us .load() -if a param is used then do not use DB but provided object


in both cases the event "loaded" is dispatched

n.on('loaded', function(){
{'fraction_non_alphanumeric': 0.04965373056317784, 'fraction_numerical': 0.0026133542401672546, 'mean_word_length': 4.522366522366522, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3446719', 'n_tokens_mistral': 1922, 'n_tokens_neox': 1823, 'n_words': 1077}