NOTE: This package is no longer being maintained. If you are interested in taking over as maintainer or are interested in the npm package name, get in touch by creating an issue.
Synopsis
assimilate adds the biological and technological distinctiveness of other objects to its own perfection.
In other words, it extends an object with the properties of other objects. In place.
Another one?
I admit the idea is hardly novel, but it's amazingly hard to find a library that does just this one thing but works both on npm and with component, has no silly dependencies and follows good practices (like semantic versioning). This may be a case of NIH, but apparently there are many ways to get this simple thing wrong.
Also, as of version 0.3.0, assimilate comes with a strategy for copying property descriptors, which is useful if you're not stuck in IE8 and want to use modern language features. If you are stuck in IE8, all the other strategies should work just fine.
Seriously?
Yes.
Install
Node.js
With NPM
npm install assimilate
From source
git clone https://github.com/pluma/assimilate.git
cd assimilate
npm install
make dist && make
Browser
With component
component install pluma/assimilate
With bower
bower install assimilate
With a CommonJS module loader
Download the latest minified CommonJS release and add it to your project.
Learn more about CommonJS modules.
With an AMD module loader
Download the latest minified AMD release and add it to your project.
As a standalone library
Download the latest minified standalone release and add it to your project.
<script src="/your/js/path/assimilate.globals.min.js"></script>
This makes the assimilate
module available in the global namespace.
Basic usage example
var assimilate = require('assimilate');
var obj = {a: 1};
assimilate(obj, {b: 2}, {c: 3});
console.log(obj);
// {a: 1, b: 2, c: 3}
Deep copying example
var deepAssimilate = require('assimilate').withStrategy('deep');
var obj = {a: {b: {c: {d: 1}}}};
deepAssimilate(obj, {a: {b: {c: {e: 2}}}});
console.log(obj);
// {a: {b: {c: {d: 1, e: 2}}}}
Property descriptor example
var properAssimilate = require('assimilate').withStrategy('proper');
var obj = {b: 1};
properAssimilate(obj, {get a() {return 2;}});
console.log(obj);
// {b: 1, a: [Getter]}
API
assimilate(target, sources…):Object
Extends the target object by applying all properties of each source object in succession, then returns the modified target object.
If target
is null or undefined, a new object will be used instead. If any of the sources are null or undefined, they will be skipped.
This function is the equivalent of assimilate.withStrategy('default')
.
assimilate.withStrategy(strategy):Function
Returns a variant of assimilate
that uses the given strategy for copying/merging properties.
If strategy
is set to a string, it must be a case-insensitive match against a strategy in assimilate.strategies
(see below). Otherwise it must be an object with a method keysFn
that accepts an object and returns an array of property names, and a method copyFn
that accepts a target
, key
and source
value and performs a copy or merge on the target
object.
assimilate.strategies
Contains the built-in copy/merge strategies. These will be performed on the target
, source
and key
for each property key
in each source
object.
DEFAULT
Copies the values of all properties of the source to the target, except for inherited properties.
PROPER
Defines all of the source's own properties on the target object using the source's property descriptors.
This can be used to copy the source's getters and setters rather than their current values.
INHERITED
Copies the values of all properties of the source to the target, including inherited properties.
DEEP
Copies the values of all properties of the source to the target, except for inherited properties. If the property already exists and both values are objects, the object's properties will be merged recursively.
STRICT
Copies the values of all properties of the source to the target, except for inherited properties. If the source property's value is undefined
, it will be skipped.
FALLBACK
Copies the values of all properties of the source that do not already exist or are set to undefined
on the target, except inherited properties.
This can be useful for merging a configuration object with its defaults.
Unlicense
This is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.