assimilate

    0.4.0 • Public • Published

    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.

    stability 3 - stable license - Unlicense Flattr this

    browser support

    Build Status Coverage Status Dependencies

    NPM status

    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

    Learn more about component.

    With bower

    bower install assimilate

    Learn more about bower.

    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.

    Learn more about AMD modules.

    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.

    Install

    npm i assimilate

    DownloadsWeekly Downloads

    3

    Version

    0.4.0

    License

    none

    Last publish

    Collaborators

    • pluma