Function clone

  • clone<Tinput, Toptions>(input, options?): GetMapReturn<Tinput, Toptions, null, null>

  • Creates a perfect shallow clone of whatever value is given (and can be perfectly cloned :)

    Works with (m)any kinds of data: Array, object, Map, Set etc.

    See examples in clone-spec.ts & loop-each-map-clone-filter-take.specHandler.ts

    Notes:

    • Iterators & Generators CANNOT be cloned, so it throws an error if you try to

    • class instances will become a POJSO, not an instance of same class! @todo(325): implement a way to clone class instances and receive a proper instance - maybe use class-transformer?

    • Everything else gets a proper clone. For example arguments are cloned to a new arguments object, with the same items.

    You can optionally pass an IloopOptions object as the second parameter, to control which keys / idx are visited (own / inherited / enumerable etc) and more.

    • if options.map already exists on clone(val, myOptions, myMapCb), in will be called (i.e you clone will be a mapped version.

    • Similarly, if options.filter exists, it is applied to the clone. If the input value is an Array, elements will appear on the cloned array at different indexes of the original, like Array.filter / _.filter. Use sparse: true option to get empty elements when they didn't pass the filter.

    Type Parameters

    Parameters

    • input: Tinput

      the value to clone

    • Optionaloptions: Toptions

      an optional object (of type IloopOptions) to control which keys / idx are visited (own / inherited / enumerable etc) and more.

    Returns GetMapReturn<Tinput, Toptions, null, null>

    a new value, with the same type as the input value 99% of time, but with the items mapped over. Objects, Arrays, Maps, Sets etc are copied and returned as new values.

    But Iterators & Generators etc dont make sense to be cloned per se, so these throw. Reason is that these can't be restarted, and it would signal the wrong ida. You can always z.map() over their remaining items, with an z.identity and that's effectivelly a z.clone(), but semantics differ.

    See

    • z.map as z.clone() is just shortcut to z.map(value, options, _.identity), plus some extra sanity checks. In turn z.map() is powered by the mighty z.loop().
    • z.loop() the power hidden behind map() and most other collection functions.