Extend Object

Path: /src/mod/extend.coffee compiled to /lib/mod/extend.js

Extend an object with another one.

This method will extend a given object with the entries from additional objects. Therefore it will do a deep extend.

Example:

CoffeeScript Code
util = require 'alinex-util'
test = { eins: 1 }
util.extend test, { zwei: 2 }, { eins: 'eins' }, { drei: 3 }

This results to:

CoffeeScript Code
test = { zwei: 2, eins: 'eins', drei: 3 }

But keep in mind that this will change the first object, to the result, too.

exports()

Usage:exports(mode, obj, ext...)

Parameter
  • mode - String optional containing one or multiple keys which have to be separated by space or comma:
    • CLONE - clone object and all extenders before extending, keeps the resulting objects untouched (works only globally)
    • OVERWRITE - allow overwrite of array and object mode in specific elements
    • ARRAY_CONCAT - (default) if no other array-mode set, will concat additional elements
    • ARRAY_REPLACE - for all arrays, replace the previouse array completely instead of extending them
    • ARRAY_OVERWRITE - overwrite the same index instead of extending the array
    • OBJECT_EXTEND - (default) if no other object-mode given, will add/replace properties with the new ones
    • OBJECT_REPLACE - will always replace the object completely with the new one, if the keys are different
  • obj - Object object to be extended
  • ext... - Object optional extenders to be applied to the base one
Return
Object new combined object

The mode may also be changed on any specific element by giving a different mode just for this operation in the extending element itself. Therefore an array should has the mode as first element or an object as an attribute.

Mode Settings

You may set a mode globally or in a specific level like described in the method definition.

See the example below which replaces arrays instead of appending to them (the default).

CoffeeScript Code
test1 = {a: [1, 2, 3], b: [1, 2, 3], c: [1, 2, 3]}
test2 = {a: [4, 5, 6], c: ['a']}
ext = util.extend 'MODE ARRAY_REPLACE', test1, test2
# ext = {a: [4, 5, 6], b: [1, 2, 3], c: ['a']}

And you may also change the mode only for one element addition (here the first array):

CoffeeScript Code
test1 = {a: [1, 2, 3], b: [1, 2, 3], c: [1, 2, 3]}
test2 = {a: ['MODE ARRAY_REPLACE', 4, 5, 6], c: ['a']}
ext = util.extend test1, test2
# ext = {a: [4, 5, 6], b: [1, 2, 3], c: [1, 2, 3, 'a']}

And to set a mode in an object you give it as argument with value true:

CoffeeScript Code
test1 = {t1: {a: 1, b: 2, c: 3}, t2: {d: 4, e: 5, f: 6}}
test2 = {t1: {OBJECT_REPLACE: true, a: 4, b: 5}, t2: {d: 9}}
ext = util.extend test1, test2
# ext = {t1: {a: 4, b: 5}, t2: {d: 9, e: 5, f: 6}}

Debugging

Debugging is possible using environment setting:

DEBUG=util:extend    -> shows each level of cloning

util:extend -> extend { eins: 1 } +0ms
util:extend    by { zwei: 2 } +1ms
util:extend    by { eins: 'eins' } +0ms
util:extend    -> extend 1 +0ms
util:extend       by 'eins' +0ms
util:extend    <- 'eins' +0ms
util:extend    by { drei: 3 } +0ms
util:extend <- { eins: 'eins', zwei: 2, drei: 3 } +0ms