Security News
The Risks of Misguided Research in Supply Chain Security
Snyk's use of malicious npm packages for research raises ethical concerns, highlighting risks in public deployment, data exfiltration, and unauthorized testing.
partial.lenses
Advanced tools
[ Examples | Reference | Background ]
This library provides a collection of Ramda compatible partial lenses. While an ordinary lens can be used to view and update an existing part of a data structure, a partial lens can view optional data, insert new data, update existing data and delete existing data.
In Javascript, optional data can be mapped to undefined
, which is what partial
lenses also do. When the viewed part of a data structure is missing, the result
is undefined
. When a part of a data structure is set to undefined
, the part
is deleted. Partial lenses are defined in such a way that operations compose
and one can conveniently and robustly operate on deeply nested data structures.
Let's work with the following sample JSON object:
const data = { contents: [ { language: "en", text: "Title" },
{ language: "sv", text: "Rubrik" } ] }
First we define a parameterized lens for accessing texts:
const textIn = language =>
L("contents",
L.required([]),
L.normalize(R.sortBy(R.prop("language"))),
L.find(c => c.language === language),
L.default({language}),
"text",
L.default(""))
Like with ordinary lenses, we can now use the partial lens to view or query texts:
> L.view(textIn("sv"), data)
"Rubrik"
> L.view(textIn("en"), data)
"Title"
If we query a text that does not exist, we get the default:
> L.view(textIn("fi"), data)
""
With the partial lens we defined, we get the default even if we query from
undefined
:
> L.view(textIn("fi"), undefined)
""
With partial lenses, undefined
is the equivalent of empty or non-existent.
As with ordinary lenses, we can use the same lens to update texts:
> L.set(textIn("en"), "The title", data)
{ contents: [ { language: "en", text: "The title" },
{ language: "sv", text: "Rubrik" } ] }
The same partial lens also allows us to insert new texts:
> L.set(textIn("fi"), "Otsikko", data)
{ contents: [ { language: "en", text: "Title" },
{ language: "fi", text: "Otsikko" },
{ language: "sv", text: "Rubrik" } ] }
Note the position into which the new text was inserted.
Finally, we can use the same partial lens to delete texts:
> L.set(textIn("sv"), undefined, data)
{ contents: [ { language: "en", text: "Title" } ] }
If we delete all of the texts, we get the required value:
> R.pipe(L.set(textIn("sv"), undefined),
L.set(textIn("en"), undefined))(data)
{ contents: [] }
Note that unless required and default values are explicitly specified as part of the lens, they will both be undefined.
The lenses and operations on lenses are accessed via the default import:
import L from "partial.lenses"
You can access basic operations on lenses via the default import L
:
L(l1, ..., ln)
and L.compose(l1, ..., ln)
both are the same as
R.compose(lift(l1), ..., lift(lN))
(see
compose).L.lens(get, set)
is the same as R.lens(get, set)
(see
lens).L.over(l, x2x, s)
is the same as R.over(lift(l), x2x, s)
(see
over).L.set(l, x, s)
is the same as R.set(lift(l), x, s)
(see
set).L.view(l, s)
is the same as R.view(lift(l), s)
(see
view).The lift
operation is defined as
const lift = l => {
switch (typeof l) {
case "string": return L.prop(l)
case "number": return L.index(l)
default: return l
}
}
and is available as a non-default export.
For convenience, there is also a shorthand for delete:
L.delete(l, s)
is the same as R.set(lift(l), undefined, s)
.L.firstOf(l1, ..., lN)
returns a partial lens that acts like the first of the
given lenses whose view is not undefined on the given target. When the views of
all of the given lenses are undefined, the returned lens acts like the first of
the given lenses.
Note that L.firstOf
is an associative operation, but there is no identity
element.
L.prop(string)
or L(string)
is similar to R.lensProp(string)
(see
lensProp), but acts as a partial
lens:
L.index(integer)
or L(integer)
is similar to R.lensIndex(integer)
(see
lensIndex), but acts as a partial
lens:
L.find(predicate)
operates on arrays like L.index
, but the index to be
viewed is determined by finding the first element from the input array that
matches the given unary predicate. When no matching element is found the effect
is same as with R.index
with the index set to the length of the array.
L.normalize(transform)
maps the value with same given transform
when viewed
and set and implicitly maps undefined to undefined. More specifically,
L.normalize(transform)
is equivalent to R.lens(toPartial(transform), toPartial(transform))
where
const toPartial = transform => x => undefined === x ? x : transform(x)
The use case for normalize
is to make it easy to determine whether, after a
change, the data has actually changed. By keeping the data normalized, a simple
R.equals
comparison will do.
L.replace(inn, out)
, when viewed, replaces the value inn
with out
and vice
versa when set. Values are compared using R.equals
(see
equals).
The use case for replace
is to handle optional and required properties and
elements. In most cases, rather than using replace
, you will make selective
use of required
and default
:
L.default(out)
is the same as L.replace(undefined, out)
.
L.required(inn)
is the same as L.replace(inn, undefined)
.
L.define(value)
is the same as L(L.required(value), L.default(value))
.
Consider the following REPL session using Ramda 0.19.1:
> R.set(R.lensPath(["x", "y"]), 1, {})
{ x: { y: 1 } }
> R.set(R.compose(R.lensProp("x"), R.lensProp("y")), 1, {})
TypeError: Cannot read property 'y' of undefined
> R.view(R.lensPath(["x", "y"]), {})
undefined
> R.view(R.compose(R.lensProp("x"), R.lensProp("y")), {})
TypeError: Cannot read property 'y' of undefined
> R.set(R.lensPath(["x", "y"]), undefined, {x: {y: 1}})
{ x: { y: undefined } }
> R.set(R.compose(R.lensProp("x"), R.lensProp("y")), undefined, {x: {y: 1}})
{ x: { y: undefined } }
One might assume that R.lensPath([p1, ..., pN])
is equivalent to
R.compose(R.lensProp(p1), ..., R.lensProp(pN))
, but that is not the case.
With partial lenses you can robustly compose a path lens from prop lenses
R.compose(L.prop(p1), ..., L.prop(pN))
or just use the shorthand notation
L(p1, ..., pN)
.
To illustrate the idea we could give lenses the naive type definition
type Lens s a = (s -> a, a -> s -> s)
defining a lens as a pair of a getter and a setter. The type of a partial lens would then be
type PartialLens s a = (s -> Maybe a, Maybe a -> s -> s)
which we can simplify to
type PartialLens s a = Lens s (Maybe a)
This means that partial lenses can be composed, viewed, mapped over and set using the same operations as with ordinary lenses. However, primitive partial lenses (e.g. L.prop) are not necessarily the same as primitive ordinary lenses (e.g. Ramda's lensProp).
FAQs
Partial lenses is a comprehensive, high-performance optics library for JavaScript
The npm package partial.lenses receives a total of 3,578 weekly downloads. As such, partial.lenses popularity was classified as popular.
We found that partial.lenses demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Snyk's use of malicious npm packages for research raises ethical concerns, highlighting risks in public deployment, data exfiltration, and unauthorized testing.
Research
Security News
Socket researchers found several malicious npm packages typosquatting Chalk and Chokidar, targeting Node.js developers with kill switches and data theft.
Security News
pnpm 10 blocks lifecycle scripts by default to improve security, addressing supply chain attack risks but sparking debate over compatibility and workflow changes.