AbstractNFocal

This method is a way to avoid duplicating code referencing an object within options.on when 1) obtaining the reference to the method's function, and 2) binding that method to the object from which it was accessed.

The return value of this method is always a Function; if the slot identified by this optic is not present in options.on or does not host a method named methodName, the trivial function (function () {} or equivalent) will be returned.

By default, the binding is lazy — the target of the lens within on is evaluated when the resulting Function is invoked (though on itself is bound in this call). To bind the resulting Function to its target immediately when this method is called, set options.bindNow to true.

const data = {question: "What is the ultimate answer?"};
const qStarts = lens('question').binding('startsWith', {on: data});
qStarts('What') // => true
data.question = "Why is a raven like a writing desk?";
qStarts('What') // => false
qStarts('Why') // => true

const data = {question: "What is the ultimate answer?"};
const qStarts = lens('question').binding('startsWith', {on: data, bindNow: true});
qStarts('What') // => true
data.question = "Why is a raven like a writing desk?";
qStarts('What') // => true (because qStarts bound to the target of the lens when `binding` was called)

If tail is given, then #get() is called on the result of getting this slot from subject, passing the spread of tail. This eliminates repeated use of .get in code. The chaining fails, returning undefined, if this slot in subject is not a lens-like object (as indicated by a truthy lens.isLens property).

If tail is given and getting this slot from from subject yields a lens-like object (as indicated by a truthy lens.isLens property), then #get_maybe() is called on that lens, passing the spread of tail. If the value of this slot is not a lens, the result is an empty Object.

If the slot does not exist within subject, this method returns an empty Array. If the slot within subject contains a non-iterable value, this method's behavior depends on orThrow. If orThrow is undefined, the behavior is the same as if the slot did not exist: an empty Array is returned. If orThrow is not undefined, orThrow is thrown; if orThrow is an Object, its noniterableValue property will be set to the slot's value before being thrown.

This method differs from Optic#get in that the returned value will always be iterable; thus, the return value of this method may safely be passed into any function expecting an iterable value. One example usage is constructing a Seq from the immutable package.

Strings, though iterable, are considered scalar values; if the targeted slot contains a string, the slot will be treated as non-iterable.

The presence of the slot determines whether branches.then or branches.else is evaluated, with the result being returned from this method. If the indicated property of branches is missing, then undefined is returned.

AbstractNFocals never produce undefined from their implementation of #get; at very least they produce and empty Array or empty Object, both of which are truthy and Objects. More helpfully, this method returns an Array of the keys/indexes in this.lenses where the slot of the corresponding lens is present in subject. This result is also invariably truthy, just like the result of #get is invariably not undefined.

Where Optic#xformInClone_maybe is about applying some algorithmic transformation to the Maybe of this slot value, possibly setting or omitting this slot from the resulting clone, this method is about creating a clone returning the newVal when Optic#get of this instance is applied to it. This base implementation suffices when the xformInClone_maybe accepts as it's transform argument (i.e. second argument) a Function returning a Maybe of the slot value.

"Minimally changed" means that reference-copies are used wherever possible while leaving subject unchanged, and that setting the slot to the strict-equal value it already has results in returning subject.

This method creates a new Optic that looks at finer detail than the Optic on which it was called. It either actually or effectively fuses a new Lens to the right of this optic, as with fuse.

An element of xformPairs that targets a lens not existing in this object is a no-op. Behavior for an xformPairs element targeting a non-existent slot in subject depends on opts.

Transforms are applied in the order in which they occur in xformPairs.

An element of xformPairs that targets a lens not existing in this object is a no-op. Any transform function called will be called with the slot value in a Maybe monad and the result expected to provide the new value in a Maybe monad: the Nothing construction ({}) will be passed if the slot does not exist in subject and return of the Nothing construct will cause the clone to omit the targeted slot.

Transforms are applied in the order in which they occur in xformPairs.

If the slot does not exist within subject, fn is invoked on an empty Array. If the slot within subject contains a non-iterable value, this method's behavior depends on orThrow. If orThrow is undefined, the behavior is the same as if the slot did not exist: an empty Array is passed to fn. If orThrow is not undefined, orThrow is thrown; if orThrow is an Object, its noniterableValue property will be set to the slot's value before being thrown.

The primary differences between this method and Lens#xformInClone are that this method always passes an iterable value to fn and always calls fn even if the slot is missing or does not contain an iterable value (unless orThrow is given).

Strings, though iterable, are considered scalar values; if the targeted slot contains a string, the slot will be treated as non-iterable.

"Minimally changed" means that reference-copies are used wherever possible while leaving subject unchanged, and that setting the slot to the strict- equal value it already has results in returning subject.

Indicates a transform Function and the index/key of the Lens identifying the slot over which to apply the transform.