Introduction

Now that you understood that the reason of why we call js objects "layers" is because we manipulate them as simple layers (even if they are complexe), let's have a look at the deepjs tools provided for those layers manipulations :

var src = { myVar:"hello" };
var target = { myBool:true };
deep.up(src, target);
deep.log(target);

bottom with no collision

up with collision

bottom with collision

This is the main tool that let you apply a layer on top of another one.

deep.aup(src, target)

This method apply the "src" layer by the up side on the "target" layer.

Only the targeted layer is modified. And is now reflecting the merge of the 2 layers :

- the b property was overwritten with the "src" layer value. It is because the "src" layer was applied by the up side and so have the priority in case of collisions.

var obj1 = {
	a:12,
	b:true,
	c:{
		d:"hello"
	}
};
var obj2 = {
	b:false
}
deep.aup(obj2, obj1);

deep.log(obj1);

deep.nodes(obj).up(layer)

This is the chained version of the up method.

var obj1 = {
	a:12,
	b:true,
	c:{
		d:"hello"
	}
};
var obj2 = {
	b:false
}
deep.nodes(obj1).up(obj2).log();

Bottom

This is the main tool that let you apply a layer by the bottom side on another one.

deep.bottom(src, target)

This method apply the "src" layer by the bottom side on the "target" layer.

Only the targeted layer is modified. And is now reflecting the merge of the 2 layers :

- the b property was not overwritten with the "src" layer value. It is because the "src" layer was applied by the bottom side (so like a background) and so the "target" layer has the priority in case of collisions.

var obj1 = {
	a:12,
	b:true,
	c:{
		d:"hello"
	}
};
var obj2 = {
	b:false,
	d:"world"
}
deep.bottom(obj2, obj1);

deep.log(obj1);

deep.nodes(obj).bottom(layer)

This is the chained version of the bottom method.

var obj1 = {
	a:12,
	b:true,
	c:{
		d:"hello"
	}
};
var obj2 = {
	b:false,
	d:"world"
}
deep.nodes(obj1).bottom(obj2).log();

Collisions

Without any collision in the name of properties/methods of the two layers, the up and bottom operations are nothing more than : adding the properties of one layer to another (note that the final order of arguments is different if it's a up or a bottom). But what about if there are collisions?

primitives collisions

For primitives (integer, string, boolean) the default behaviour in case of collision is that the top layer overwrite the value with his own.

If you want a different behaviour than de default overwriting, you need to use a tool called a "collider". As it is a important part of the deepjs core, they have their own section : link to colliders

var obj1 = {
	a:12,
	b:true
};
var obj2 = {
	a:"now a string",
	b:false
}
deep.nodes(obj1).up(obj2).log();

Array merging

The default behaviour in case of collisions is a little more complexe for arrays than primitives. They are not simply overwritten with the top layer values, they are merged.

If your arrays contains single values in it, it merge them. But it didn't duplicate "doublons"

var obj1 = {
	a:[12,"blue"]
};
var obj2 = {
	a:["green", "blue", false]
}
deep.nodes(obj1).up(obj2).log();

But if your arrays contains objects, it looks for an "id" property so it can merge the data of each object present in the array.

You can see in the example that the "obj2" layer add a lastname to one of your array entry, and also add 2 single values in the array

var obj1 = {
	a:[{id:"1", firstname:"John"},{id:"2", firstname:"Chris"}]
};
var obj2 = {
	a:[{id:"1", lastname:"Doe"}, "blue", 15]
}
deep.nodes(obj1).up(obj2).log();

If you want a different behaviour than de default array merging, you need to use a tool called a "collider". As it is a important part of the deepjs core, they have their own section : link to colliders

Functions compositions

the default behaviour in case of collision of two functions is that the top layer overwrite the function with his own.

var obj1 = {
	a:12,
	myMethod : function(){
		deep.log("Hello");
	}
}

var obj2 = {
	a:12,
	myMethod : function(){
		deep.log("Goodbye");
	}
}
deep.nodes(obj1).up(obj2);
obj1.myMethod();

But of course you will want to compose and not overwrite some of your layers methods. There is a complete section dedicated to that : link to compostions

Compile

Compile is a tool that let you compile a set of layers in one operation. It returns the compiled object (so the layers that are present in the set are not modified).

deep.utils.compile(obj1, obj2, obj3, ...)

This method compiles the given layers in one layer.

The order of the arguments sets the priority in case of collisions.

It returns an object that is the result of the compiled layers

var obj1 = {
	a:12,
	b:true,
	c:{
		d:"hello"
	}
};
var obj2 = {
	b:false
};
var obj3 = {
	e:function(){
	    deep.log("Hello");
	}
};
var compiled = deep.utils.compile(obj1, obj2, obj3);

deep.log(compiled);

deep.compile(obj1, obj2, obj3, ....)

This is the chained version of the compile method.

var obj1 = {
	a:12,
	b:true,
	c:{
		d:"hello"
	}
};
var obj2 = {
	b:false
};
var obj3 = {
	e:function(){
	    deep.log("Hello");
	}
};

deep.compile(obj1, obj2, obj3).log();

up & bottom