repl.txt (4098B)
1 2 {{alias}}( target, ...source ) 3 Merges objects into a target object. 4 5 The target object is mutated. 6 7 Only plain objects are merged and extended. Other values/types are either 8 deep copied or assigned. 9 10 Support for deep merging class instances is inherently fragile. 11 12 `Number`, `String`, and `Boolean` objects are merged as primitives. 13 14 Functions are not deep copied. 15 16 Parameters 17 ---------- 18 target: Object 19 Target object. 20 21 source: ...Object 22 Source objects (i.e., objects to be merged into the target object). 23 24 Returns 25 ------- 26 out: Object 27 Merged (target) object. 28 29 Examples 30 -------- 31 > var target = { 'a': 'beep' }; 32 > var source = { 'a': 'boop', 'b': 'bap' }; 33 > var out = {{alias}}( target, source ) 34 { 'a': 'boop', 'b': 'bap' } 35 > var bool = ( out === target ) 36 true 37 38 39 {{alias}}.factory( options ) 40 Returns a function for merging and extending objects. 41 42 Parameters 43 ---------- 44 options: Object 45 Options. 46 47 options.level: integer (optional) 48 Merge level. Default: Infinity. 49 50 options.copy: boolean (optional) 51 Boolean indicating whether to deep copy merged values. Deep copying 52 prevents shared references and source object mutation. Default: true. 53 54 options.override: boolean|Function (optional) 55 Defines the merge strategy. If `true`, source object values will always 56 override target object values. If `false`, source values never override 57 target values (useful for adding, but not overwriting, properties). To 58 define a custom merge strategy, provide a function. Default: true. 59 60 options.extend: boolean (optional) 61 Boolean indicating whether new properties can be added to the target 62 object. If `false`, only shared properties are merged. Default: true. 63 64 Returns 65 ------- 66 fcn: Function 67 Function which can be used to merge objects. 68 69 Examples 70 -------- 71 > var opts = { 72 ... 'level': 100, 73 ... 'copy': true, 74 ... 'override': true, 75 ... 'extend': true 76 ... }; 77 > var merge = {{alias}}.factory( opts ) 78 <Function> 79 80 // Set the `level` option to limit the merge depth: 81 > merge = {{alias}}.factory( { 'level': 2 } ); 82 > var target = { 83 ... '1': { 'a': 'beep', '2': { '3': null, 'b': [ 5, 6, 7 ] } } 84 ... }; 85 > var source = { 86 ... '1': { 'b': 'boop', '2': { '3': [ 1, 2, 3 ] } } 87 ... }; 88 > var out = merge( target, source ) 89 { '1': { 'a': 'beep', 'b': 'boop', '2': { '3': [ 1, 2, 3 ] } } } 90 91 // Set the `copy` option to `false` to allow shared references: 92 > merge = {{alias}}.factory( { 'copy': false } ); 93 > target = {}; 94 > source = { 'a': [ 1, 2, 3 ] }; 95 > out = merge( target, source ); 96 > var bool = ( out.a === source.a ) 97 true 98 99 // Set the `override` option to `false` to preserve existing properties: 100 > merge = {{alias}}.factory( { 'override': false } ); 101 > target = { 'a': 'beep', 'b': 'boop' }; 102 > source = { 'a': null, 'c': 'bop' }; 103 > out = merge( target, source ) 104 { 'a': 'beep', 'b': 'boop', 'c': 'bop' } 105 106 // Define a custom merge strategy: 107 > function strategy( a, b, key ) { 108 ... // a => target value 109 ... // b => source value 110 ... // key => object key 111 ... if ( key === 'a' ) { 112 ... return b; 113 ... } 114 ... if ( key === 'b' ) { 115 ... return a; 116 ... } 117 ... return 'bebop'; 118 ... }; 119 > merge = {{alias}}.factory( { 'override': strategy } ); 120 > target = { 'a': 'beep', 'b': 'boop', 'c': 1234 }; 121 > source = { 'a': null, 'b': {}, 'c': 'bop' }; 122 > out = merge( target, source ) 123 { 'a': null, 'b': 'boop', 'c': 'bebop' } 124 125 // Prevent non-existent properties from being added to the target object: 126 > merge = {{alias}}.factory( { 'extend': false } ); 127 > target = { 'a': 'beep', 'b': 'boop' }; 128 > source = { 'b': 'hello', 'c': 'world' }; 129 > out = merge( target, source ) 130 { 'a': 'beep', 'b': 'hello' } 131 132 See Also 133 -------- 134