new Optic()
- Source:
- Mixes In:
Methods
binding(methodName, options) → {function}
DRYly bind a Function to the Object from which it was obtained
- Source:
- 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
extractor(xformopt) → {Optic~Extractor}
Construct a Function to extract (and possibly transform) the slot value from a subject
- Source:
- Since:
- 2.2.0
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
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:
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
- *
(abstract) get_maybe(subject, …tail) → {Maybe.<*>}
Get a combination of present and value of this slot
- Source:
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, optionsopt) → {Iterable.<*>}
Get the (iterable) value of this slot within some subject data
- Source:
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.
Parameters:
| Name | Type | Attributes | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
subject |
* | The data to query |
|||||||||
options |
Object |
<optional> |
Properties
|
Returns:
An iterable of values from this slot (or an empty Array)
- Type
- Iterable.<*>
getting(subject, branches) → {T}
Conditionally evaluate functions depending on presence of slot
- Source:
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) → {Boolean}
Test for the presence of this slot in subject data
- Source:
Parameters:
| Name | Type | Description |
|---|---|---|
subject |
* | The data to test |
Returns:
Whether this slot is present in subject
- Type
- Boolean
setInClone(subject, newVal) → {T}
Clone subject, assigning the given value to this slot within the clone
- Source:
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.
Parameters:
| Name | Type | Description |
|---|---|---|
subject |
T | The input structured data |
newVal |
* | The new value to inject into the slot identified by this lens within the returned clone |
Returns:
A minimally changed clone of subject with newVal in this slot
- Type
- T
thence(…key) → {Lens|OpticArray}
Build a "deeper" lens/optic
- Source:
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, fn, optsopt) → {T}
Clone the input, transforming the value within this slot with a function
- Source:
If this slot is missing in subject, fn will not be called unless addMissing
is true, in which case fn will be called with undefined.
"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 slot value |
|||||||||
opts |
Object |
<optional> |
Properties
|
Returns:
A minimally changed clone of subject with fn applied to the value in this slot
- Type
- T
xformInClone_maybe(subject, fn) → {T}
Clone the input, transforming or deleting the Maybe value of this slot with a function
- Source:
The concept of this method is of applying some clear algorithm to the content of the slot targeted by this Optic instance (in a Maybe monad, to cover the possibility of the slot itself not existing in subject) with the result returned in a Maybe monad (to allow for potential removal of the slot).
This implements what conceptually could, in Haskell, be described as:
Json -> (Maybe Json -> Maybe Json) -> Json
"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 | Description |
|---|---|---|
subject |
T | The input structured data |
fn |
function | The function transforming the Maybe value of the slot |
Returns:
A minimally changed clone of subject with this slot transformed per fn
- Type
- T
xformIterableInClone(subject, fn, optionsopt) → {T}
Clone the input, transforming the iterable value within this slot with a function
- Source:
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
(inner) Extractor(subject) → {*}
- Source:
- Since:
- 2.2.0
- See:
Parameters:
| Name | Type | Description |
|---|---|---|
subject |
* | The input structured data |
Returns:
The extracted — and possibly transformed — slot value (undefined if slot is missing in subject)
- Type
- *
(inner) MaybeExtractor(subject) → {Maybe.<*>}
- Source:
- Since:
- 2.2.0
- See:
Parameters:
| Name | Type | Description |
|---|---|---|
subject |
* | The input structured data |
Returns:
The extracted — and possibly transformed — slot value in a Maybe monad
- Type
- Maybe.<*>