@kingjs/immutable.copy

Clone target tree and update its values with a subtree of source tree which have matching paths in the action tree.

Stats

StarsIssuesVersionUpdatedCreatedSize
@kingjs/immutable.copy
1.0.13 years ago3 years agoMinified + gzip package size for @kingjs/immutable.copy in KB

Readme

@kingjs/immutable.copy

Clone target tree and update its values with a subtree of source tree which have matching paths in the action tree.

Usage

Flip a0 and b0 property values from 0 to 1 like this:

var copy = require('@kingjs/immutable.copy');

var target = {
  a0: 0,
  a1: 0,
  a2: 0,
  a3: { b0: 0 },
  a4: { b0: 0, b1: 0, b2: 0 },
  a5: { b0: 0 }
};

var source = { 
  a0: 1,
  a1: 1,
  a3: { b0: 1 },
  a4: { b0: 1, b1: 1 }
};

var action = {
  a0: null,
  a2: null,
  a4: { b0: null, b2: null },
  a5: { b0: null }
};

copy(target, source, action);

result:

{
  a0: 1,
  a1: 0,
  a2: 0,
  a3: { b0: 0 },
  a4: { b0: 1, b1: 0, b2: 0 },
  a5: { b0: 0 }
}

API

declare function augment(
  target: Descriptor,
  source: Descriptor,
  action: Descriptor
): Descriptor

Interfaces

  • Descriptor: see @kingjs/descriptor

    Parameters

  • target: Descriptor tree to which properties from corresponding source paths are copied if a corresponding action path exists. Paths are cloned and created as needed.
  • source: Descriptor tree from which properties are copied to corresponding target paths if a corresponding action path exists.
  • action: Descriptor tree of functions to combine corresponding property values of target and source before being copied to a clone of target.

    Returns

    Returns a clone of target tree with values copied from source tree if those values share paths on action.

    Remarks

    Imagine target, source, and action as directories of values where a directory is a descriptor.

Each value in source is copied to its corresponding directory in target but only if there is also a corresponding value in action.

Intermediate directories are created or cloned as needed.

A value is overwritten if it's undefined or preserved if the source value is undefined. When neither are undefined then, if there is a function at the corresponding action directory, that function is used to create the updated value given the values from this and source. If no function is found at action then the value is overwritten with the source value.

Exceptions are thrown if the following invariants are violated:

  • action contains a value that is not null, undefined, or a function.
  • A directory in action is found to be a value in either this or source.

    Install

    With npm installed, run
    $ npm install @kingjs/immutable.copy
    

    License

    MIT

Analytics

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.