Skip to content

Latest commit

 

History

History
155 lines (124 loc) · 6.01 KB

replicate.md

File metadata and controls

155 lines (124 loc) · 6.01 KB
Raw

@micosmo/core/replicate

A set of functions for assigning, copying and cloning Javascript objects at both a descriptor and value level. The services are also integrated with the private properties mechanism provided by @micosmo/core/private[./private.md], allowing copy and clone operations to be extended to the private properties.

Note that the replication services will accept any javascript data type. Types that cannot be copied or cloned are returned asis. Arrays are supported.

API

IMPORTING

const replicate = require('@micosmo/core/replicate');

or

const { copy, clone, ... } = require('@micosmo/core/replicate');

EXPORTS

Function Description
assign(from[, to]) Descriptor level assignment from the from object to the to object. If not provided a to object will be created. Returns the to object.
openAssign(from[, to]) As for assign except that the descriptors are set to configurable.
closedAssign(from[, to]) As for assign except that the descriptors are set to not configurable.
assignValues(from[, to]) Equivalent to Object.assign, except that a to object will be created if not provided. Returns the to object.
copy(from[, to]) Descriptor level copy of the from object. A target to object can be provided. Includes private properties. Returns the to object.
openCopy(from[, to]) As for copy except that the descriptors are set to configurable.
closedCopy(from[, to]) As for copy except that the descriptors are set to not configurable anf the target object is sealed.
copyValues(from[, to]) Similar to assignValues except the function call would normally create the to object. Returns the to object.
reverseCopy(from) Returns a reverse copy of an array. If from is any other data type then request is passed to copy.
clone(from[, to]) Descriptor level clone of the from object. A target to object can be provided. Includes private properties. Returns the to object. The clone process is effectively a deep copy, with circular or duplicate references mapped to a single cloned value. Returns the to object.
openClone(from[, to]) As for clone except that the descriptors are set to configurable.
closedClone(from[, to]) As for clone except that the descriptors are set to not configurable and the target object is sealed.
cloneValues(from[, to]) As for clone except the deep copy is based on the values only.

NOTES

MICOPY & MICLONE

Object values may inject their own behaviour for copying and cloning by defining a micopy or miclone method. The replication process will pass control to micopy or miclone to complete the operation for the given object. They must return a value that represents the copied or cloned version of the object. Any value can be returned including the original object.

The micopy and myclone methods are passed a context object that defines the replication process that has been requested. The context contains two properties that are of interest to the target object:

Property Description
replicate(from[, to]) A function that calls the context's replication processor to replicate the from value. A target to object can also be provided if the from value is an object.
copyContext miclone context parameter only. The alternate matching context for copying values instead of cloning.
cloneContext micopy context parameter only. The alternate matching contect for cloning values instead of copying.
Example: No replication
  {
    ...
    micopy() { return this },
    miclone() { return this },
    ...
  }
Example: Copy must clone
  {
    ...
    micopy(ctxt) { return ctxt.cloneContext.replicate(this) },
    ...
  }
Example: Partial copy
  {
    foo: 1,
    bar: 2,
    _temp: ...,
    micopy(ctxt) { 
      return {
        foo: this.foo,
        bar: this.bar        
      };
    }
  }
Example: Partial clone
  {
    foo: { ... },
    bar: { ... },
    _temp: ...,
    miclone(ctxt) { 
      return {
        foo: ctxt.replicate(this.foo),
        bar: ctxt.replicate(this.bar)
      };
    }
  }

PUBLIC ONLY REPLICATION

The copy and clone group of functions can also perform public level only copy or clone operations, via a public function that is a property of the required copy or clone function . In this case any private properties are not replicated. See example below.

const fPrivate = require('@micosmo/core/private').newPrivateSpace();
const foo = {
  a: 1,
  b: 2
};
fPrivate.setObject(foo, {
  x: 11,
  y: 12
});
const fooCopy = copy(foo); // Both public and private properties of 'foo' are replicated.
const fooPublicCopy = copy.public(foo); // Only the public properties of 'foo' are replicated.

console.log(fooCopy, Private(fooCopy));
/*
  {
    a: 1,
    b: 2
  }
  { 
    x: 11,
    y: 12
  }
*/
console.log(fooPublicCopy, Private(fooPublicCopy))
/*
  {
    a: 1,
    b: 2
  }
  { }
*/

HISTORY

Version 0.1.1

  • Replicate context table was assigned the incorrect alternate context for public only replication contexts.

LICENSE

ISC - Internet Systems Consortium

Copyright 2019 Micosmo (www.micosmo.com)

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.