Extends
Members
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') // => trueconst 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
|
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
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() → {Array}
Get an empty Array
- Source:
- Overrides:
Because an ObjectNFocal always gets an Object, there is no way to create an iterable value from the "virtual slot" it accesses. Therefore, the result of the inherited implementation would always yield an empty Array and just returning that value is more efficient.
Returns:
An empty array
- 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.
Parameters:
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
subject |
* | The input structured data |
||||||||||||
branches |
Object |
Properties
|
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.
The slot corresponding to any constituent lens whose name is left out of newVals will be deleted from the clone of subject.
Parameters:
| Name | Type | Description |
|---|---|---|
subject |
T | The input structured data |
newVals |
Object.<string, *> | 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 |
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
|
Returns:
A minimally changed clone of subject with the transformed value in this slot
- Type
- T