natural-lenses

This constant is a key used for querying a method from container objects of type function(*): Maybe.<*>. The value passed to this method will be a key from a Lens -- the kind of value that should be passed for a conceptual "indexing" of the container. For Object, this is a string property name. For Array, this is an integer index, where negative values count backward from the end of the Array. For Map, this uses Map.prototype.has and Map.prototype.get.

This constant is a key used for querying a method from container objects of type function({set: {0: *, 1: *}?, spliceOut: *?}): *. The intent of the method is to clone the container with some kind of alteration -- either a key/index set to the given value in the clone, or a key/index deleted from the clone.

If the operation description passed contains a set property, the value of that property should be an Array where element 0 is a key or index into the container and element 1 is the value to set (cf. arguments to Map.prototype.set).

If the operation description passed contains a spliceOut property, the value of that property should be a key or index to delete from the container. Where possible, the result should be to leave the container in a state where container[at_maybe](key) returns {} (a Nothing). This is specifically a problem for immutable.List, which offers only a dense presentation of elements: every non-negative index less than size is a valid and "contained" entry. The implementation provided by this library for implementing this method on immutable.List sets the value of the entry in the clone to undefined.

In the provided implemenation for Array, negative indexes are interpreted counting backward from the end of the Array, as with Array.prototype.slice.

Symbol.species is honored for determining the constructor used for the clone; Object is a special case that defaults to Object if Symbol.species is not present.

This property is set on every kind of object to be recognized by this library as implementing lens-like behavior. Setting this property to any truthy value on your own objects will cause this library to treat it in many ways like a Lens.

When called on the result of getting a multifocal into a Maybe monad, this function iterates found values (and only the found values), yielding the pair of the value and index for each, like the arguments to the callback of Array.prototype.forEach if it used "rest" syntax, e.g.

values.forEach((...pair) => {
  const [value, index] = pair;
  // do something with index and value
});

When called on the get_maybe-result of an ArrayNFocal, the index 1 value of each yielded Array will be an integer index; with an ObjectNFocal, the index 1 value of each yeilded Array will be a string key.

This function can also be applied to a Maybe monad value obtained from a monofocal optic (e.g. a Lens), in which case it yields either a single element array containing the value if the input holds a just property and does not yield, otherwise. It is more flexible to apply maybeDo or Optic#getting, as these allow separate handling of the Nothing case.

To understand the slot reference of the returned optic, consider the getting model: optics[0] will be applied to the input data, and for all other optics (i > 0), optics[i] will be applied to the result from optics[i - 1]. In other words, each optic gets something within the optic to its left, with the leftmost getting from the input data. Modifications affect the same slot.

If all optics are Lenses, the result will be a Lens. This does not apply for Lens-derived objects (e.g. from Factories) — if such are passed, the result will always be an OpticArray.

This function resembles an if statement around the "Just-ness" of a Maybe value: the then Function gets called if maybe has a just and the orElse Function if not. Because of the usual intent of this conditional situation, maybe.just value is passed to then if then is called.

Whichever of then or orElse is called, its return value becomes the return value of this function call.

Where a standard lens looks at a single slot within a JSONic object, a multifocal lens consists of multiple lenses (standard or multifocal) whose results are aggregated into a single value, which can be a dictionary-like Object or an Array.

Pass an Array of lenses to create a multifocal lens that outputs an Array, where the position of each lens in the input Array corresponds to the output position of the data (when getting with the multifocal lens). When getting in a Maybe context (#get_maybe), the result will always be an Object with a just property, though some elements of the Array may be empty.

Pass an Object with lens values to create a multifocal lens outputting an Object, which will bear the same properties as the input Object and whose values are the values in the data referenced by the corresponding lens (when getting using this multifocal lens).

Be aware that the xformInClone method on these kinds of multifocal lenses works differently from a basic Lens, since multifocals can have a "stereoscopic" view of data. Instead of a single transformation function, xformInClone (and it's _maybe variant) accept an iterable of key/transform pairs (where the key is an integer index in the case of an Array multifocal). This allows full control over the order in which transformations are applied to the input data, resolving the issue of "stereoscopic conflict".

Adds mixin methods for supporting lenses to the given Immutable container type.