ArrayNFocal

ArrayNFocal

Extends

Members

length

Return the length of Array of constituent lenses (also the length of the result)

Source:

lenses :Array.<Optic>|Object.<string, Optic>

Optics aggregated by this object

Source:
Inherited From:
Type:

Methods

binding(methodName, options) → {function}

DRYly bind a Function to the Object from which it was obtained

Source:
Inherited From:
See:

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.

Examples
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)
Parameters:
Name Type Description
methodName string | symbol
options Object
Properties
Name Type Attributes Default Description
on *

The subject of the Function binding; the result of applying this Optic to the value given becomes this for the result
bindNow boolean <optional>
 false

Whether to apply this Optic to options.on now or when the bound function is invoked
orThrow * <optional>

OptionalThrow if the slot referenced does not contain a Function; has precedence over or
or function <optional>

FallbackBindingResult, a Function to return if the slot referenced does not contain a Function
Returns:

A Function binding the methodName of the target of this Optic to the target of this Optic, or function() {} if no such function found

Type
function

extractor(xformopt) → {Optic~Extractor}

Construct a Function to extract (and possibly transform) the slot value from a subject

Source:
Since:
  • 2.2.0
Inherited From:
Parameters:
Name Type Attributes Description
xform function <optional>

The transformation to apply to the slot's value
Returns:

The resulting extractor

Type
Optic~Extractor

extractor_maybe(xformopt) → {Optic~MaybeExtractor}

Construct a Function to extract (and optionally transform) the slot value from a subject in a Maybe monad

Source:
Since:
  • 2.2.0
Inherited From:

Like extractor, but with more clarity in the result about whether the slot existed or the transform returned undefined through use of the Maybe monad.

Parameters:
Name Type Attributes Description
xform function <optional>

The transformation to apply to the slot's value
Returns:

The resulting extractor

Type
Optic~MaybeExtractor

get(subject, …tail) → {*}

Get the value of this slot within subject data

Source:
Overrides:

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).

Parameters:
Name Type Attributes Description
subject *

The data to query
tail * <repeatable>

Additional subjects for repeated application
Returns:

The value of this slot, or undefined if this slot is not present in subject

Type
*

get_maybe(subject, …tail) → {Maybe.<*>}

Get a combination of present and value of this slot

Source:
Overrides:

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.

Parameters:
Name Type Attributes Description
subject *

The data to query
tail * <repeatable>

Additional subject for repeated application
Returns:

The value of the slot in a Maybe moand (Nothing if the slot is missing in subject)

Type
Maybe.<*>

getIterable(subject) → {Array.<*>}

Get the iterable value of this slot within some subject data

Source:
Overrides:

In this class, this method is synonymous with a call to get with a single parameter.

Parameters:
Name Type Description
subject *

The data to query
Returns:

An Array of values obtained from subject via this.lenses

Type
Array.<*>

getting(subject, branches) → {T}

Conditionally evaluate functions depending on presence of slot

Source:
Inherited From:

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.

If branches.then is called, it is passed the value from this slot in subject.

Parameters:
Name Type Description
subject *

The input structured data
branches Object
Properties
Name Type Attributes Description
then function <optional>

Function evaluated if slot is present in subject
else function <optional>

Function evaluated if slot is absent from subject
Returns:

The value computed by branches.then or branches.else, or undefined

Type
T

present(subject) → {Array.<(number|string)>}

Test which constituent lenses are present in a subject

Source:
Inherited From:

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.

Parameters:
Name Type Description
subject *

The data to test
Returns:

Array of keys to this.lenses where the presence-test result corresponds to this.lenses by key/index

Type
Array.<(number|string)>

setInClone(subject, newVals) → {T}

Clone subject, setting all values corresponding to elements of this multifocal within the clone

Source:
Overrides:
See:

Similar in concept to Lens#setInClone, this method creates a modified clone of subject such that applying this optic to the new value produces a value deep-equal to newVals. Due to the multifocal nature, it is possible that no such result can be created, which results in a StereoscopyError.

It is possible to delete the target of one or more of this.lenses by passing newVals with empty elements or with fewer elements than in this.lenses. The easiest way to accomplish this is to create the Array of new values, then use delete on the indexes whose corresponding slots should be removed from subject.

Parameters:
Name Type Description
subject T

The input structured data
newVals Array.<*>

The new values corresponding to this multifocal's lenses
Throws:

If this object's view of subject cannot become newVals

Type
StereoscopyError
Returns:

A minimally changed clone of subject with newVals distributed via this.lenses

Type
T

thence(…key) → {Lens|OpticArray}

Build a "deeper" lens/optic

Source:
Inherited From:

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.

Parameters:
Name Type Attributes Description
key * <repeatable>

A value to use in an application of subscripting (i.e. square bracket operator)
Returns:

An Optic that fuses this optic with a Lens looking at finer detail

Type
Lens | OpticArray

xformInClone(subject, xformPairs, optsopt) → {T}

Apply transforms to selected slots within this multifocal while making a clone

Source:
Inherited From:

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.

Parameters:
Name Type Attributes Description
subject T

The input structured data
xformPairs Iterable.<AbstractNFocal.TransformSpec>

Iterable of constituent lens key and transform function pairs to apply
opts function | Object <optional>

Options for the constituent optic's xformInClone or a function taking the slot key and returning the options
Returns:

A minimally changed clone of subject with the slots of this multifocal selected by xformPairs transformed according to the corresponding Function

Type
T

xformInClone_maybe(subject, xformPairs) → {T}

Apply transforms to selected slots (using a Maybe monad) within this multifocal while making a clone

Source:
Inherited From:

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.

Parameters:
Name Type Description
subject T

The input structured data
xformPairs Iterable.<AbstractNFocal.TransformSpec>

Iterable of constituent lens key and transform function pairs to apply
Returns:

A minimally changed clone of subject with the slots of this multifocal selected by keys in xformPairs transformed according to the corresponding Function

Type
T

xformIterableInClone(subject, fn, optionsopt) → {T}

Clone the input, transforming the iterable value within this slot with a function

Source:
Inherited From:

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.

Parameters:
Name Type Attributes Description
subject T

The input structured data
fn function

The function that transforms the (iterable) slot value
options Object <optional>
Properties
Name Type Attributes Description
orThrow * <optional>

OptionalThrow if the value of the slot exists but is not iterable
Returns:

A minimally changed clone of subject with the transformed value in this slot

Type
T