Deeply
A toolkit for deep structure manipulations, provides deep merge/clone functionality out of the box, and exposes hooks and custom adapters for more control and greater flexibility.
compression | size |
---|---|
deeply.js | 16.35 kB |
deeply.min.js | 5.36 kB |
deeply.min.js.gz | 1.63 kB |
Table of Contents
- Install
- Examples
- Want to Know More?
- License
Install
$ npm install deeply --save
Examples
By default it provides interface for immutable operations,
also available via explicit require require('deeply/immutable')
or require('deeply').immutable
property.
Merging
Deeply merges two or more objects.
var merge = ; var result = ; assert;
Security concerns
Due to Prototype Pollution security vulnerability concerns, default behavior of when merging objects is to skip unsafe keys, like __proto__
, please refer to the test/compatability.js file for code examples.
If there is a use case where such behavior is desired, pass allowDangerousObjectKeys
flag to the context to skip keys safety checks.
var merge = ;var result; var context = allowDangerousObjectKeys: mergebehaviorsallowDangerousObjectKeys ; result = merge;// end of the world, cats live with dogs...
Cloning
As degenerated case of merging one object on itself, it's possible to use deeply as deep clone function.
var merge = ;var clone = merge; var x = a: b: c: 1;var y = ; yabc = 2; assert;
Arrays Custom Merging
By default array treated as primitive values and being replaced upon conflict, for more meaningful array merge strategy, provide one of the pre-built array merge helpers or a custom reduce function within invocation context.
Default Behavior
var merge = ;var result = ; assert;
Combining Arrays
var merge = ;var result; var context = useCustomAdapters: mergebehaviorsuseCustomAdapters 'array' : mergeadaptersarraysCombine; // it might be useful when you have array of objectsresult = merge;assert;
Appending Arrays
var merge = ; var context = useCustomAdapters: mergebehaviorsuseCustomAdapters 'array' : mergeadaptersarraysAppend; var result = merge; assert;
Appending Arrays and Keeping Unique Elements Only
var merge = ; var context = useCustomAdapters: mergebehaviorsuseCustomAdapters 'array' : mergeadaptersarraysAppendUnique; var result = merge; assert;
Custom Merge Function
For example we need to have merging arrays to be appended, with only unique elements and sort the result array.
var merge = ; var context = useCustomAdapters: mergebehaviorsuseCustomAdapters 'array' : appendUniqueAndSort; var result = merge; assert; // Custom array adapter{ // append only if new element isn't present yet from; // and sort return to;}
Cloning Functions
By default, functions copied as is to the result object, basically being treated as primitive values.
You can use functionsClone
adapter to clone functions,
creating new function object with the same signature as original.
var clone = ; { return a + b + 10;} subjcustomProp = 13; subjprototypeA = 1; subjprototypeB = isB: 'true'; var context = useCustomAdapters: clonebehaviorsuseCustomAdapters 'function' : cloneadaptersfunctionsClone; var result = clone; // cloned object function named subjassert; // same signatureassert;assert; assert; // separate objectssubjisOriginal = true;resultabisCopy = true; assert;assert; assert;assert; // same outputassert;
Cloning Prototype Chain
It will also clone prototype objects, so use this option with caution.
var clone = ; { thisboom = 'Zap!';} SubjprototypeA = 1; SubjprototypeB = isB: 'true'; var context = useCustomAdapters: clonebehaviorsuseCustomAdapters 'function' : cloneadaptersfunctionsClone; var result = clone; // cloned object function named Subjassert; // has prototype propertiesassert;assert; // prototypes are decoupledSubjprototypeC = 2;assert;assert; // instancesvar s1 = ;var s2 = ; assert;assert; assert;assert; assert; // but reported instanceof isn't the sameassert;assert;
Extend Original Function Prototype
When having proper instanceof
results matters,
you can use functionsExtend
helper instead.
var clone = ; { thisboom = 'Zap!'; return thisboom;} SubjcustomProp = 13; SubjprototypeA = 1; SubjprototypeB = isB: 'true'; var context = useCustomAdapters: clonebehaviorsuseCustomAdapters 'function' : cloneadaptersfunctionsExtend; var result = clone; // cloned object function named Subjassert; // same signatureassert;assert; assert; // separate objectsSubjisOriginal = true;resultclassisCopy = true; assert;assert; assert;assert; // same outputassert; // has prototype propertiesassert;assert; // prototypes are extendedSubjprototypeX = 67;assert;assert; // instancesvar s1 = ;var s2 = ; assert;assert; assert; // but reported instanceof isn't the sameassert;assert;
Custom flags and hooks
allowDangerousObjectKeys
As shown in (Security Concerns)[#security-concerns] section,
you can skip safety checks for unsafe object keys (e.g. __proto__
) by passing allowDangerousObjectKeys
flag to the context.
merge;
useCustomAdapters
As shown in Custom Merge Function example, you can add custom adapters for any data type that supported by precise-typeof.
For this example we will combine arrays of number, by performing addition operation on array elements.
var merge = ; var context = useCustomAdapters: mergebehaviorsuseCustomAdapters 'array' : mergeadaptersarraysCombine 'number' : addNumbers; var result = merge; assert; // Custom number adapter{ return to || 0 + from;}
useCustomTypeOf
In some cases you might need to have more control over type detection, for that you can supply your own type detection function.
In following example we'd use same precise-typeof
library,
but with pojoOnly: true
flag:
var merge = ;var typeOf = ;var moment = ; var context = useCustomTypeOf: mergebehaviorsuseCustomTypeOf ; var result = merge; assert;
In the above example, it would treat moment
object as atomic,
and won't mix it's properties with other properties.
Mutable Operations
Mutable interface supports all the described operations,
and available via explicit require require('deeply/mutable')
or require('deeply').mutable
property.
var merge = ;var myObj = a: a1: 1 a2: 2 b: b1: 11 b2: 12; ; assert;
Ludicrous Mode
Also as shortcut and a homage to Tesla, ludicrous mode is available, that will clone functions and it's prototype objects by default. :) Details could be found in Cloning Functions examples.
var ludicrous = ;var scopeVar = 6; { return a + b + scopeVar;} var cloned = ; // cloned object function named subjassert; // same signatureassert;assert; // separate objectsoriginalisOriginal = true;clonedfuncisCopy = true; assert;assert; assert;assert; // same outputassert;
Note: ludicrous
isn't included into the main deeply
package, so it won't be automatically pulled in,
if you're bundling using browserify deeply/index.js
, to use ludicrous in the browser you'd need to explicitly
require it in your modules or specify direct path in your bundler config.
Want to Know More?
More examples can be found in test/compatability.js.
Or open an issue with questions and/or suggestions.
License
Deeply is released under the MIT license.