# [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#) [Partial Lenses](#partial-lenses) · [![Gitter](https://img.shields.io/gitter/room/calmm-js/chat.js.svg)](https://gitter.im/calmm-js/chat) [![GitHub stars](https://img.shields.io/github/stars/calmm-js/partial.lenses.svg?style=social)](https://github.com/calmm-js/partial.lenses) [![npm](https://img.shields.io/npm/dm/partial.lenses.svg)](https://www.npmjs.com/package/partial.lenses) Lenses are basically an abstraction for simultaneously specifying operations to [update](#l-modify) and [query](#l-get) [immutable](#on-immutability) data structures. Lenses are [highly composable](#on-composability) and can be [efficient](#benchmarks). This library provides a [rich collection](#on-bundle-size-and-minification) of [partial](#on-partiality) [isomorphisms](#isomorphisms), [lenses](#lenses), and [traversals](#traversals), collectively known as [optics](#optics), for manipulating [JSON](http://json.org/) and users [can](#l-tofunction) [write](#l-iso) [new](#l-lens) [optics](#l-branch) for manipulating non-JSON objects, such as [Immutable.js](#interfacing) collections. A partial lens can *view* optional data, *insert* new data, *update* existing data and *remove* existing data and can, for example, provide *defaults* and maintain *required* data structure parts. [Try Lenses!](https://calmm-js.github.io/partial.lenses/playground.html) [![npm version](https://badge.fury.io/js/partial.lenses.svg)](http://badge.fury.io/js/partial.lenses) [![Bower version](https://badge.fury.io/bo/partial.lenses.svg)](https://badge.fury.io/bo/partial.lenses) [![Build Status](https://travis-ci.org/calmm-js/partial.lenses.svg?branch=master)](https://travis-ci.org/calmm-js/partial.lenses) [![Code Coverage](https://img.shields.io/codecov/c/github/calmm-js/partial.lenses/master.svg)](https://codecov.io/github/calmm-js/partial.lenses?branch=master) [![](https://david-dm.org/calmm-js/partial.lenses.svg)](https://david-dm.org/calmm-js/partial.lenses) [![](https://david-dm.org/calmm-js/partial.lenses/dev-status.svg)](https://david-dm.org/calmm-js/partial.lenses?type=dev) ## [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#contents) [Contents](#contents) * [Tutorial](#tutorial) * [Getting started](#getting-started) * [A partial lens to access title texts](#a-partial-lens-to-access-titles) * [Querying data](#querying-data) * [Missing data can be expected](#missing-data-can-be-expected) * [Updating data](#updating-data) * [Inserting data](#inserting-data) * [Removing data](#removing-data) * [Exercises](#exercises) * [Shorthands](#shorthands) * [Systematic decomposition](#systematic-decomposition) * [Manipulating multiple items](#manipulating-multiple-items) * [Next steps](#next-steps) * [The why of optics](#the-why-of-optics) * [Reference](#reference) * [Stable subset](#stable-subset) * [Additional libraries](#additional-libraries) * [Optics](#optics) * [On partiality](#on-partiality) * [On indexing](#on-indexing) * [On immutability](#on-immutability) * [On composability](#on-composability) * [On lens laws](#on-lens-laws) * [Myth: Partial Lenses are not lawful](#myth-partial-lenses-are-not-lawful) * [Operations on optics](#operations-on-optics) * [`L.assign(optic, object, maybeData) ~> maybeData`](#l-assign "L.assign: PLens s {p1: a1, ...ps, ...o} -> {p1: a1, ...ps} -> Maybe s -> Maybe s") ^v11.13.0 * [`L.disperse(optic, [...maybeValues], maybeData) ~> maybeData`](#l-disperse "L.disperse: POptic s a -> Maybe [Maybe a] -> Maybe s -> Maybe s") ^v14.6.0 * [`L.modify(optic, (maybeValue, index) => maybeValue, maybeData) ~> maybeData`](#l-modify "L.modify: POptic s a -> ((Maybe a, Index) -> Maybe a) -> Maybe s -> Maybe s") ^v2.2.0 * [`L.modifyAsync(optic, (maybeValue, index) => maybeValuePromise, maybeData) ~> maybeDataPromise`](#l-modifyasync "L.modifyAsync: POptic s a -> ((Maybe a, Index) -> Promise (Maybe a)) -> Maybe s -> Promise (Maybe s)") ^v13.12.0 * [`L.remove(optic, maybeData) ~> maybeData`](#l-remove "L.remove: POptic s a -> Maybe s -> Maybe s") ^v2.0.0 * [`L.set(optic, maybeValue, maybeData) ~> maybeData`](#l-set "L.set: POptic s a -> Maybe a -> Maybe s -> Maybe s") ^v1.0.0 * [`L.traverse(algebra, (maybeValue, index) => operation, optic, maybeData) ~> operation`](#l-traverse "L.traverse: (Functor|Applicative|Monad) c -> ((Maybe a, Index) -> c b) -> POptic s t a b -> Maybe s -> c t") ^v10.0.0 * [Nesting](#nesting) * [`L.compose(...optics) ~> optic`](#l-compose "L.compose: (POptic s s1, ...POptic sN a) -> POptic s a") or `[...optics]` ^v1.0.0 * [`L.flat(...optics) ~> optic`](#l-flat "L.flat: (POptic s [...s1...], ...POptic sN [...a...]) -> POptic [...s...] a") ^v13.6.0 * [Recursing](#recursing) * [`L.lazy(optic => optic) ~> optic`](#l-lazy "L.lazy: (POptic s a -> POptic s a) -> POptic s a") ^v5.1.0 * [Adapting](#adapting) * [`L.choices(optic, ...optics) ~> optic`](#l-choices "L.choices: (POptic s a, ...POptic s a) -> POptic s a") ^v11.10.0 * [`L.choose((maybeValue, index) => optic) ~> optic`](#l-choose "L.choose: ((Maybe s, Index) -> POptic s a) -> POptic s a") ^v1.0.0 * L.cond(...[(maybeValue, index) => testable, consequentOptic][, [alternativeOptic]]) ~> optic ^v13.1.0 * L.condOf(traversal, ...[(maybeValue, index) => testable, consequentOptic][, [alternativeOptic]]) ~> optic ^v13.5.0 * [`L.ifElse((maybeValue, index) => testable, optic, optic) ~> optic`](#l-ifelse "L.ifElse: ((Maybe s, Index) -> Boolean) -> POptic s a -> POptic s a -> POptic s a") ^v13.1.0 * [`L.orElse(backupOptic, primaryOptic) ~> optic`](#l-orelse "L.orElse: (POptic s a, POptic s a) -> POptic s a") ^v2.1.0 * [Indices](#indices) * [`L.joinIx(optic) ~> optic`](#l-joinix "L.joinIx: POptic s a -> POptic s a") ^v13.15.0 * [`L.mapIx((index, maybeValue) => index) ~> optic`](#l-mapix "L.mapIx: ((Index, Maybe a) -> Index) -> POptic a a") ^v13.15.0 * [`L.reIx(optic) ~> optic`](#l-reix "L.reIx: POptic s a -> POptic s a") ^v14.10.0 * [`L.setIx(index) ~> optic`](#l-setix "L.setIx: Index -> POptic a a") ^v13.15.0 * [`L.skipIx(optic) ~> optic`](#l-skipix "L.skipIx: POptic s a -> POptic s a") ^v13.15.0 * [`L.tieIx((innerIndex, outerIndex) => index, optic) ~> optic`](#l-tieix "L.tieIx: ((Index, Index) => Index) -> POptic s a -> POptic s a") ^v13.15.0 * [Debugging](#debugging) * [`L.getLog(lens, maybeData) ~> maybeValue`](#l-getlog "L.getLog: PLens s a -> Maybe s -> Maybe a") ^v13.14.0 * [`L.log(...labels) ~> optic`](#l-log "L.log: (...Any) -> POptic s s") ^v3.2.0 * [Internals](#internals) * [`L.Identity ~> Monad`](#l-identity-monad "L.Identity: Monad") ^v13.7.0 * [`L.IdentityAsync ~> Monadish`](#l-identityasync "L.IdentityAsync: Monadish") ^v13.12.0 * [`L.Select ~> Applicative`](#l-select-applicative "L.Select: Applicative") ^v14.0.0 * [`L.toFunction(optic) ~> optic`](#l-tofunction "L.toFunction: POptic s t a b -> (Maybe s, Index, (Functor|Applicative|Monad) c, (Maybe a, Index) -> c b) -> c t") ^v7.0.0 * [Transforms](#transforms) * [Operations on transforms](#operations-on-transforms) * [`L.transform(optic, maybeData) ~> maybeData`](#l-transform "L.transform: POptic s a -> Maybe s -> Maybe s") ^v11.7.0 * [`L.transformAsync(optic, maybeData) ~> maybeDataPromise`](#l-transformasync "L.transformAsync: POptic s a -> Maybe s -> Promise (Maybe s)") ^v13.12.0 * [Sequencing](#sequencing) * [`L.seq(...transforms) ~> transform`](#l-seq "L.seq: (...PTransform s a) -> PTransform s a") ^v9.4.0 * [Transforming](#transforming) * [`L.appendOp(value) ~> traversal`](#l-appendop "L.appendOp: a -> PTraversal [a] a") ^v14.14.0 * [`L.assignOp(object) ~> traversal`](#l-assignop "L.assignOp: {p1: a1, ...ps} -> PTraversal {p1: a1, ...ps, ...o} {p1: a1, ...ps}") ^v11.13.0 * [`L.modifyOp((maybeValue, index) => maybeValue) ~> traversal`](#l-modifyop "L.modifyOp: ((Maybe a, Index) -> Maybe a) -> PTraversal a a") ^v11.7.0 * [`L.prependOp(value) ~> traversal`](#l-prependop "L.prependOp: a -> PTraversal [a] a") ^v14.14.0 * [`L.removeOp ~> traversal`](#l-removeop "L.removeOp: PTraversal a a") ^v11.7.0 * [`L.setOp(maybeValue) ~> traversal`](#l-setop "L.setOp: Maybe a -> PTraversal a a") ^v11.7.0 * [Traversals](#traversals) * [Creating new traversals](#creating-new-traversals) * [`L.branch({prop: traversal, ...props}) ~> traversal`](#l-branch "L.branch: {p1: PTraversal p1 a, ...pts} -> PTraversal {p1: p1, ...ps} a") ^v5.1.0 * [`L.branchOr(traversal, {prop: traversal, ...props}) ~> traversal`](#l-branchor "L.branchOr: PTraversal p a -> {p1: PTraversal p1 a, ...pts} -> PTraversal {p1: p1, ...ps} a") ^v13.2.0 * [`L.branches(...propNames) ~> traversal`](#l-branches "L.branches: (p1: PTraversal p1 a, ...pts) -> PTraversal {p1: p1, ...ps} a") ^v13.5.0 * [Traversals and combinators](#traversals-and-combinators) * [`L.children ~> traversal`](#l-children "L.children: PTraversal ([a] | {p: a, ...ps}) a") ^v13.3.0 * [`L.elems ~> traversal`](#l-elems "L.elems: PTraversal [a] a") ^v7.3.0 * [`L.elemsTotal ~> traversal`](#l-elemstotal "L.elemsTotal: PTraversal [a] a") ^v13.11.0 * [`L.entries ~> traversal`](#l-entries "L.entries: PTraversal {p: a, ...ps} [String, a]") ^v11.21.0 * [`L.flatten ~> traversal`](#l-flatten "L.flatten: PTraversal [...[a]...] a") ^v11.16.0 * [`L.keys ~> traversal`](#l-keys "L.keys: PTraversal {p: a, ...ps} String") ^v11.21.0 * [`L.keysEverywhere ~> traversal`](#l-keyseverywhere "L.keysEverywhere: PTraversal JSON String") ^v14.12.0 * [`L.leafs ~> traversal`](#l-leafs "L.leafs: PTraversal JSON (String|Number|Boolean|null|~JSON)") ^v13.3.0 * [`L.limit(count, traversal) ~> traversal`](#l-limit "L.limit: Integer -> PTraversal s a -> PTraversal s a") ^v14.10.0 * [`L.matches(/.../g) ~> traversal`](#l-matches-g "L.matches: RegExp -> PTraversal String String") ^v10.4.0 * [`L.offset(count, traversal) ~> traversal`](#l-offset "L.offset: Integer -> PTraversal s a -> PTraversal s a") ^v14.10.0 * [`L.query(...traversals) ~> traversal`](#l-query "L.query: (PTraversal s1 s2, ...PTraversal sN a) ~> PTraversal JSON a") ^v13.6.0 * [`L.satisfying((maybeValue, index) => testable) ~> traversal`](#l-satisfying "L.satisfying: ((Maybe s, Index) -> Boolean) -> PTraversal JSON a") ^v13.3.0 * [`L.subseq(begin, end, traversal) ~> traversal`](#l-subseq "L.subseq: Integer -> Integer -> PTraversal s a -> PTraversal s a") ^v14.10.0 * [`L.values ~> traversal`](#l-values "L.values: PTraversal {p: a, ...ps} a") ^v7.3.0 * [`L.whereEq({prop: value, ...props}) ~> traversal`](#l-whereeq "L.whereEq: {p1: p1, ...ps} -> PTraversal JSON {p1: p1, ...ps}") ^v14.16.0 * [Querying](#querying) * [`L.chain((value, index) => optic, optic) ~> traversal`](#l-chain "L.chain: ((a, Index) -> POptic s b) -> POptic s a -> PTraversal s b") ^v3.1.0 * [`L.choice(...optics) ~> traversal`](#l-choice "L.choice: (...POptic s a) -> PTraversal s a") ^v2.1.0 * [`L.optional ~> traversal`](#l-optional "L.optional: PTraversal a a") ^v3.7.0 * [`L.unless((maybeValue, index) => testable) ~> traversal`](#l-unless "L.unless: ((Maybe a, Index) -> Boolean) -> PTraversal a a") ^v12.1.0 * [`L.when((maybeValue, index) => testable) ~> traversal`](#l-when "L.when: ((Maybe a, Index) -> Boolean) -> PTraversal a a") ^v5.2.0 * [`L.zero ~> traversal`](#l-zero "L.zero: PTraversal s a") ^v6.0.0 * [Folds over traversals](#folds-over-traversals) * [`L.all((maybeValue, index) => testable, traversal, maybeData) ~> boolean`](#l-all "L.all: ((Maybe a, Index) -> Boolean) -> PTraversal s a -> Boolean") ^v9.6.0 * [`L.all1((maybeValue, index) => testable, traversal, maybeData) ~> boolean`](#l-all1 "L.all1: ((Maybe a, Index) -> Boolean) -> PTraversal s a -> Boolean") ^v14.4.0 * [`L.and(traversal, maybeData) ~> boolean`](#l-and "L.and: PTraversal s Boolean -> Boolean") ^v9.6.0 * [`L.and1(traversal, maybeData) ~> boolean`](#l-and1 "L.and1: PTraversal s Boolean -> Boolean") ^v14.4.0 * [`L.any((maybeValue, index) => testable, traversal, maybeData) ~> boolean`](#l-any "L.any: ((Maybe a, Index) -> Boolean) -> PTraversal s a -> Boolean") ^v9.6.0 * [`L.collect(traversal, maybeData) ~> [...values]`](#l-collect "L.collect: PTraversal s a -> Maybe s -> [a]") ^v3.6.0 * [`L.collectAs((maybeValue, index) => maybeValue, traversal, maybeData) ~> [...values]`](#l-collectas "L.collectAs: ((Maybe a, Index) -> Maybe b) -> PTraversal s a -> Maybe s -> [b]") ^v7.2.0 * [`L.collectTotal(traversal, maybeData) ~> [...maybeValues]`](#l-collecttotal "L.collectTotal: PTraversal s a -> Maybe s -> [Maybe a]") ^v14.6.0 * [`L.collectTotalAs((maybeValue, index) => maybeValue, traversal, maybeData) ~> [...maybeValues]`](#l-collecttotalas "L.collectTotalAs: ((Maybe a, Index) -> Maybe b) -> PTraversal s a -> Maybe s -> [Maybe b]") ^v14.6.0 * [`L.concat(monoid, traversal, maybeData) ~> value`](#l-concat "L.concat: Monoid a -> (PTraversal s a -> Maybe s -> a)") ^v7.2.0 * [`L.concatAs((maybeValue, index) => value, monoid, traversal, maybeData) ~> value`](#l-concatas "L.concatAs: ((Maybe a, Index) -> r) -> Monoid r -> (PTraversal s a -> Maybe s -> r)") ^v7.2.0 * [`L.count(traversal, maybeData) ~> number`](#l-count "L.count: PTraversal s a -> Number") ^v9.7.0 * [`L.countIf((maybeValue, index) => testable, traversal, maybeData) ~> number`](#l-countif "L.countIf: ((Maybe a, Index) -> Boolean) -> PTraversal s a -> Number") ^v11.2.0 * [`L.counts(traversal, maybeData) ~> map`](#l-counts "L.counts: PTraversal s a -> Map Any Number") ^v11.21.0 * [`L.countsAs((maybeValue, index) => any, traversal, maybeData) ~> map`](#l-countsas "L.countsAs: ((Maybe a, Index) -> Any) -> PTraversal s a -> Map Any Number") ^v11.21.0 * [`L.foldl((value, maybeValue, index) => value, value, traversal, maybeData) ~> value`](#l-foldl "L.foldl: ((r, Maybe a, Index) -> r) -> r -> PTraversal s a -> Maybe s -> r") ^v7.2.0 * [`L.foldr((value, maybeValue, index) => value, value, traversal, maybeData) ~> value`](#l-foldr "L.foldr: ((r, Maybe a, Index) -> r) -> r -> PTraversal s a -> Maybe s -> r") ^v7.2.0 * [`L.forEach((maybeValue, index) => undefined, traversal, maybeData) ~> undefined`](#l-foreach "L.forEach: ((Maybe a, Index) -> Undefined) -> PTraversal s a -> Maybe s -> Undefined") ^v11.20.0 * [`L.forEachWith(() => context, (context, maybeValue, index) => undefined, traversal, maybeData) ~> context`](#l-foreachwith "L.forEachWith: (() -> c) -> ((c, Maybe a, Index) -> Undefined) -> PTraversal s a -> Maybe s -> c") ^v13.4.0 * [`L.get(traversal, maybeData) ~> maybeValue`](#l-get "L.get: PTraversal s a -> Maybe s -> Maybe a") ^v2.2.0 * [`L.getAs((maybeValue, index) => maybeValue, traversal, maybeData) ~> maybeValue`](#l-getas "L.getAs: ((Maybe a, Index) -> Maybe b) -> PTraversal s a -> Maybe s -> Maybe b") ^v14.0.0 * [`L.isDefined(traversal, maybeData) ~> boolean`](#l-isdefined "L.isDefined: PTraversal s a -> Maybe s -> Boolean") ^v11.8.0 * [`L.isEmpty(traversal, maybeData) ~> boolean`](#l-isempty "L.isEmpty: PTraversal s a -> Maybe s -> Boolean") ^v11.5.0 * [`L.join(string, traversal, maybeData) ~> string`](#l-join "L.join: String -> PTraversal s a -> Maybe s -> String") ^v11.2.0 * [`L.joinAs((maybeValue, index) => maybeString, string, traversal, maybeData) ~> string`](#l-joinas "L.joinAs: ((Maybe a, Index) -> Maybe String) -> String -> PTraversal s a -> Maybe s -> String") ^v11.2.0 * [`L.maximum(traversal, maybeData) ~> maybeValue`](#l-maximum "L.maximum: Ord a => PTraversal s a -> Maybe s -> Maybe a") ^v7.2.0 * [`L.maximumBy(keyLens, traversal, maybeData) ~> maybeValue`](#l-maximumby "L.maximumBy: Ord k => (PLens a k -> PTraversal s a -> Maybe s -> Maybe a") ^v11.2.0 * [`L.mean(traversal, maybeData) ~> number`](#l-mean "L.mean: PTraversal s Number -> Maybe s -> Number") ^v11.17.0 * [`L.meanAs((maybeValue, index) => maybeNumber, traversal, maybeData) ~> number`](#l-meanas "L.meanAs: ((Maybe a, Index) -> Maybe Number) -> PTraversal s a -> Maybe s -> Number") ^v11.17.0 * [`L.minimum(traversal, maybeData) ~> maybeValue`](#l-minimum "L.minimum: Ord a => PTraversal s a -> Maybe s -> Maybe a") ^v7.2.0 * [`L.minimumBy(keyLens, traversal, maybeData) ~> maybeValue`](#l-minimumby "L.minimumBy: Ord k => (PLens a k -> PTraversal s a -> Maybe s -> Maybe a") ^v11.2.0 * [`L.none((maybeValue, index) => testable, traversal, maybeData) ~> boolean`](#l-none "L.none: ((Maybe a, Index) -> Boolean) -> PTraversal s a -> Boolean") ^v11.6.0 * [`L.or(traversal, maybeData) ~> boolean`](#l-or "L.or: PTraversal s Boolean -> Boolean") ^v9.6.0 * [`L.product(traversal, maybeData) ~> number`](#l-product "L.product: PTraversal s Number -> Maybe s -> Number") ^v7.2.0 * [`L.productAs((maybeValue, index) => number, traversal, maybeData) ~> number`](#l-productas "L.productAs: ((Maybe a, Index) -> Number) -> PTraversal s a -> Maybe s -> Number") ^v11.2.0 * ~~[`L.select(traversal, maybeData) ~> maybeValue`](#l-select "L.select: PTraversal s a -> Maybe s -> Maybe a") ^v9.8.0~~ * ~~[`L.selectAs((maybeValue, index) => maybeValue, traversal, maybeData) ~> maybeValue`](#l-selectas "L.selectAs: ((Maybe a, Index) -> Maybe b) -> PTraversal s a -> Maybe s -> Maybe b") ^v9.8.0~~ * [`L.sum(traversal, maybeData) ~> number`](#l-sum "L.sum: PTraversal s Number -> Maybe s -> Number") ^v7.2.0 * [`L.sumAs((maybeValue, index) => number, traversal, maybeData) ~> number`](#l-sumas "L.sumAs: ((Maybe a, Index) -> Number) -> PTraversal s a -> Maybe s -> Number") ^v11.2.0 * [Lenses](#lenses) * [Creating new lenses](#creating-new-lenses) * [`L.foldTraversalLens((traversal, maybeData) => maybeValue, traversal) ~> lens`](#l-foldtraversallens "L.foldTraversalLens: (PTraversal s a -> Maybe s -> Maybe a) -> PTraversal s a -> PLens s a") ^v11.5.0 * [`L.getter((maybeData, index) => maybeValue) ~> lens`](#l-getter "L.getter: ((Maybe s, Index) -> Maybe a) -> PLens s a") ^v13.16.0 * [`L.lens((maybeData, index) => maybeValue, (maybeValue, maybeData, index) => maybeData) ~> lens`](#l-lens "L.lens: ((Maybe s, Index) -> Maybe a) -> ((Maybe a, Maybe s, Index) -> Maybe s) -> PLens s a") ^v1.0.0 * [`L.partsOf(traversal, ...traversals) ~> lens`](#l-partsof "L.partsOf: ((PTraversal s s1, ...PTraversal sN a) -> PLens s [Maybe a]") ^v14.6.0 * [`L.setter((maybeValue, maybeData, index) => maybeData) ~> lens`](#l-setter "L.setter: ((Maybe a, Maybe s, Index) -> Maybe s) -> PLens s a") ^v10.3.0 * [Enforcing invariants](#enforcing-invariants) * [`L.defaults(valueIn) ~> lens`](#l-defaults "L.defaults: s -> PLens s s") ^v2.0.0 * [`L.define(value) ~> lens`](#l-define "L.define: s -> PLens s s") ^v1.0.0 * [`L.normalize((value, index) => maybeValue) ~> lens`](#l-normalize "L.normalize: ((s, Index) -> Maybe s) -> PLens s s") ^v1.0.0 * [`L.required(valueOut) ~> lens`](#l-required "L.required: s -> PLens s s") ^v1.0.0 * [`L.reread((valueIn, index) => maybeValueIn) ~> lens`](#l-reread "L.reread: ((s, Index) -> Maybe s) -> PLens s s") ^v11.21.0 * [`L.rewrite((valueOut, index) => maybeValueOut) ~> lens`](#l-rewrite "L.rewrite: ((s, Index) -> Maybe s) -> PLens s s") ^v5.1.0 * [Lensing array-like objects](#array-like) * ~~[`L.append ~> lens`](#l-append "L.append: PLens [a] a") ^v1.0.0~~ * [`L.cross([...lenses]) ~> lens`](#l-cross "L.cross: [PLens s1 a1, ...PLens sN aN] -> PLens [s1, ...sN] [a1, ...aN]") ^v14.3.0 * [`L.filter((maybeValue, index) => testable) ~> lens`](#l-filter "L.filter: ((Maybe a, Index) -> Boolean) -> PLens [a] [a]") ^v1.0.0 * [`L.find((maybeValue, index, {hint: index}) => testable[, {hint: index}]) ~> lens`](#l-find "L.find: ((Maybe a, Index, {hint: Index}) -> Boolean[, {hint: Index}]) -> PLens [a] a") ^v1.0.0 * [`L.findWith(optic[, {hint: index}]) ~> optic`](#l-findwith "L.findWith: (POptic s a[, {hint: Index}]) -> POptic [s] a") ^v1.0.0 * [`L.first ~> lens`](#l-first "L.first: PLens [a] a") ^v13.1.0 * [`L.index(elemIndex) ~> lens`](#l-index "L.index: Integer -> PLens [a] a") or `elemIndex` ^v1.0.0 * [`L.last ~> lens`](#l-last "L.last: PLens [a] a") ^v9.8.0 * [`L.prefix(maybeEnd) ~> lens`](#l-prefix "L.prefix: Maybe Number -> PLens [a] [a]") ^v11.12.0 * [`L.slice(maybeBegin, maybeEnd) ~> lens`](#l-slice "L.slice: Maybe Number -> Maybe Number -> PLens [a] [a]") ^v8.1.0 * [`L.suffix(maybeBegin) ~> lens`](#l-suffix "L.suffix: Maybe Number -> PLens [a] [a]") ^v11.12.0 * [Lensing objects](#lensing-objects) * [`L.pickIn({prop: lens, ...props}) ~> lens`](#l-pickin "L.pickIn: {p1: PLens s1 a1, ...pls} -> PLens {p1: s1, ...pls} {p1: a1, ...pls}") ^v11.11.0 * [`L.prop(propName) ~> lens`](#l-prop "L.prop: (p: a) -> PLens {p: a, ...ps} a") or `propName` ^v1.0.0 * [`L.props(...propNames) ~> lens`](#l-props "L.props: (p1: a1, ...ps) -> PLens {p1: a1, ...ps, ...o} {p1: a1, ...ps}") ^v1.4.0 * [`L.propsExcept(...propNames) ~> lens`](#l-propsexcept "L.propsExcept: (p1: a1, ...ps) -> PLens {p1: a1, ...ps, ...o} {...o}") ^v14.11.0 * ~~[`L.propsOf(object) ~> lens`](#l-propsof "L.propsOf: {p1: a1, ...ps} -> PLens {p1: a1, ...ps, ...o} {p1: a1, ...ps}") ^v11.13.0~~ * [`L.removable(...propNames) ~> lens`](#l-removable "L.removable: (p1: a1, ...ps) -> PLens {p1: a1, ...ps, ...o} {p1: a1, ...ps, ...o}") ^v9.2.0 * [Lensing strings](#lensing-strings) * [`L.matches(/.../) ~> lens`](#l-matches "L.matches: RegExp -> PLens String String") ^v10.4.0 * [Providing defaults](#providing-defaults) * [`L.valueOr(valueOut) ~> lens`](#l-valueor "L.valueOr: s -> PLens s s") ^v3.5.0 * [Transforming data](#transforming-data) * [`L.pick({prop: lens, ...props}) ~> lens`](#l-pick "L.pick: {p1: PLens s a1, ...pls} -> PLens s {p1: a1, ...pls}") ^v1.2.0 * [`L.replace(maybeValueIn, maybeValueOut) ~> lens`](#l-replace "L.replace: Maybe s -> Maybe s -> PLens s s") ^v1.0.0 * [Inserters](#inserters) * [`L.appendTo ~> lens`](#l-appendto "L.appendTo: PLens [a] a") ^v14.14.0 * [`L.assignTo ~> lens`](#l-assignto "L.assignTo: PLens {...} {...}") ^v14.14.0 * [`L.prependTo ~> lens`](#l-prependto "L.prependTo: PLens [a] a") ^v14.14.0 * [Isomorphisms](#isomorphisms) * [Operations on isomorphisms](#operations-on-isomorphisms) * [`L.getInverse(isomorphism, maybeData) ~> maybeData`](#l-getinverse "L.getInverse: PIso a b -> Maybe b -> Maybe a") ^v5.0.0 * [Creating new isomorphisms](#creating-new-isomorphisms) * [`L.iso(maybeData => maybeValue, maybeValue => maybeData) ~> isomorphism`](#l-iso "L.iso: (Maybe s -> Maybe a) -> (Maybe a -> Maybe s) -> PIso s a") ^v5.3.0 * [`L.mapping([patternFwd, patternBwd] | (...variables) => [patternFwd, patternBwd]) ~> isomorphism`](#l-mapping "L.mapping: ([Pattern s, Pattern a] | (...Variable) -> [Pattern s, Pattern a]) -> PIso s a") ^v14.8.0 * [`L._ ~> pattern`](#l-_ "L._: Pattern a") ^v14.8.0 * [`L.mappings([...[patternFwd, patternBwd]] | (...variables) => [...[patternFwd, patternBwd]]) ~> isomorphism`](#l-mappings "L.mappings: ([[Pattern s, Pattern a]] | (...Variable) -> [[Pattern s, Pattern a]]) -> PIso s a") ^v14.8.0 * [`L.pattern(pattern | (...variables) => pattern) ~> isomorphism`](#l-pattern "L.pattern: (Pattern s | (...Variable) -> Pattern s) -> PIso s s") ^v14.13.0 * [`L.patterns([...patterns] | (...variables) => [...patterns]) ~> isomorphism`](#l-patterns "L.patterns: ([Pattern s] | (...Variable) -> [Pattern s]) -> PIso s s") ^v14.13.0 * [Isomorphism combinators](#isomorphism-combinators) * [`L.alternatives(isomorphism, ...isomorphisms) ~> isomorphism`](#l-alternatives "L.alternatives: (PIso s a, ...PIso s a) -> PIso s a") ^v14.7.0 * [`L.applyAt(elementsOptic, isomorphism) ~> isomorphism`](#l-applyat "L.applyAt: (POptic s a, PIso a a) -> PIso s s") ^v14.9.0 * [`L.attemptEveryDown(isomorphism) ~> isomorphism`](#l-attempteverydown "L.attemptEveryDown: (POptic a b) -> PIso s t") ^v14.13.0 * [`L.attemptEveryUp(isomorphism) ~> isomorphism`](#l-attempteveryup "L.attemptEveryUp: (POptic a b) -> PIso s t") ^v14.13.0 * [`L.attemptSomeDown(isomorphism) ~> isomorphism`](#l-attemptsomedown "L.attemptSomeDoen: (POptic a b) -> PIso s t") ^v14.13.0 * [`L.conjugate(contextIsomorphism, isomorphism) ~> isomorphism`](#l-conjugate "L.conjugate: PIso s a -> PIso a a -> PIso s s") ^v14.9.0 * [`L.fold(isomorphism) ~> isomorphism`](#l-fold "L.fold: PIso [s, x] s -> PIso [s, xs] s") ^v14.13.0 * [`L.inverse(isomorphism) ~> isomorphism`](#l-inverse "L.inverse: PIso a b -> PIso b a") ^v4.1.0 * [`L.iterate(isomorphism) ~> isomorphism`](#l-iterate "L.iterate: PIso a a -> PIso a a") ^v14.3.0 * [`L.orAlternatively(backupIsomorphism, primaryIsomorphism) ~> isomorphism`](#l-oralternatively "L.orAlternatively: (PIso s a, PIso s a) -> PIso s a") ^v14.7.0 * [`L.unfold(isomorphism) ~> isomorphism`](#l-unfold "L.fold: PIso s [s, x] -> PIso s [s, xs]") ^v14.13.0 * [Basic isomorphisms](#basic-isomorphisms) * [`L.complement ~> isomorphism`](#l-complement "L.complement: PIso Boolean Boolean") ^v9.7.0 * [`L.identity ~> isomorphism`](#l-identity "L.identity: PIso s s") ^v1.3.0 * [`L.is(value) ~> isomorphism`](#l-is "L.is: v -> PIso v Boolean") ^v11.1.0 * [`L.subset(maybeValue => testable) ~> isomorphism`](#l-subset "L.subset: (Maybe a -> Boolean) -> PIso a a") ^v14.3.0 * [Array isomorphisms](#array-isomorphisms) * [`L.array(isomorphism) ~> isomorphism`](#l-array "L.array: PIso a b -> PIso [a] [b]") ^v11.19.0 * [`L.arrays(isomorphism) ~> isomorphism`](#l-arrays "L.arrays: PIso a b -> PIso [a] [b]") ^v14.13.0 * [`L.groupBy(keyLens) ~> isomorphism`](#l-groupby "L.groupBy: PLens a k -> PIso [a] [[a]]") ^v14.13.0 * [`L.indexed ~> isomorphism`](#l-indexed "L.indexed: PIso [a] [[Integer, a]]") ^v11.21.0 * [`L.reverse ~> isomorphism`](#l-reverse "L.reverse: PIso [a] [a]") ^v11.22.0 * [`L.singleton ~> isomorphism`](#l-singleton "L.singleton: PIso [a] a") ^v11.18.0 * [`L.ungroupBy(keyLens) ~> isomorphism`](#l-ungroupby "L.ungroupBy: PLens a k -> PIso [[a]] [a]") ^v14.13.0 * [`L.unzipWith1(isomorphism) ~> isomorphism`](#l-unzipwith1 "L.unzipWith1: PIso c [a, b] -> PIso [c] [a, [b]]") ^v14.13.0 * [`L.zipWith1(isomorphism) ~> isomorphism`](#l-zipwith1 "L.zipWith1: PIso [a, b] c -> PIso [a, [b]] [c]") ^v14.13.0 * [Object isomorphisms](#object-isomorphisms) * [`L.disjoint(propName => propName) ~> isomorphism`](#l-disjoint "L.disjoint: (String k -> String g) -> PIso {[k]: a} {[g]: {[k]: a}}") ^v13.13.0 * [`L.keyed ~> isomorphism`](#l-keyed "L.keyed: PIso {p: a, ...ps} [[String, a]]") ^v11.21.0 * [`L.multikeyed ~> isomorphism`](#l-multikeyed "L.multikeyed: PIso {p: a|[a], ...ps} [[String, a]]") ^v14.1.0 * [Standard isomorphisms](#standard-isomorphisms) * [`L.json({reviver, replacer, space}) ~> isomorphism`](#l-json "L.json: {reviver, replacer, space} -> PIso String JSON") ^v11.3.0 * [`L.uri ~> isomorphism`](#l-uri "L.uri: PIso String String") ^v11.3.0 * [`L.uriComponent ~> isomorphism`](#l-uricomponent "L.uriComponent: PIso String (Boolean|Number|String)") ^v11.3.0 * [Standardish isomorphisms](#standardish-isomorphisms) * [`L.querystring ~> isomorphism`](#l-querystring "L.querystring: PIso String {p: Boolean|Number|String|[Boolean|Number|String], ...ps}") ^v14.2.0 * [String isomorphisms](#string-isomorphisms) * [`L.dropPrefix(prefix) ~> isomorphism`](#l-dropprefix "L.dropPrefix: String -> PIso String String") ^v13.8.0 * [`L.dropSuffix(suffix) ~> isomorphism`](#l-dropsuffix "L.dropSuffix: String -> PIso String String") ^v13.8.0 * [`L.replaces(substringIn, substringOut) ~> isomorphism`](#l-replaces "L.replaces: String -> String -> PIso String String") ^v13.8.0 * [`L.split(separator[, separatorRegExp]) ~> isomorphism`](#l-split "L.split: (String[, String | RegExp]) -> PIso String [String]") ^v13.8.0 * [`L.uncouple(separator[, separatorRegExp]) ~> isomorphism`](#l-uncouple "L.uncouple: (String[, String | RegExp]) -> PIso String [String, String]") ^v13.8.0 * [Arithmetic isomorphisms](#arithmetic-isomorphisms) * [`L.add(number) ~> isomorphism`](#l-add "L.add: Number -> PIso Number Number") ^v13.9.0 * [`L.divide(number) ~> isomorphism`](#l-divide "L.divide: Number -> PIso Number Number") ^v13.9.0 * [`L.multiply(number) ~> isomorphism`](#l-multiply "L.multiply: Number -> PIso Number Number") ^v13.9.0 * [`L.negate ~> isomorphism`](#l-negate "L.negate: PIso Number Number") ^v13.9.0 * [`L.subtract(number) ~> isomorphism`](#l-subtract "L.subtract: Number -> PIso Number Number") ^v13.9.0 * [Interop](#interop) * [Fantasy Land](#fantasy-land) * [`L.FantasyFunctor ~> Functor`](#l-fantasyfunctor "L.FantasyFunctor: Functor") ^v14.5.0 * [`L.fromFantasy(TypeRep) ~> Functor|Applicative|Monad`](#l-fromfantasy "L.fromFantasy: TypeRep -> Functor|Applicative|Monad") ^v14.5.0 * [`L.fromFantasyApplicative(TypeRep) ~> Applicative`](#l-fromfantasyapplicative "L.fromFantasy: TypeRep -> Applicative") ^v14.5.0 * [`L.fromFantasyMonad(TypeRep) ~> Monad`](#l-fromfantasy "L.fromFantasyMonad: TypeRep -> Monad") ^v14.5.0 * [JSON Pointer](#json-pointer) * [`L.pointer(jsonPointer) ~> lens`](#l-pointer "L.pointer: JSONPointer s a -> PLens s a") ^v11.21.0 * [Auxiliary](#auxiliary) * [`L.seemsArrayLike(anything) ~> boolean`](#l-seemsarraylike "L.seemsArrayLike: any -> Boolean") ^v11.4.0 * [Examples](#examples) * [An array of ids as boolean flags](#an-array-of-ids-as-boolean-flags) * [Dependent fields](#dependent-fields) * [Collection toggle](#collection-toggle) * [BST as a lens](#bst-as-a-lens) * [BST traversal](#bst-traversal) * [Interfacing with Immutable.js](#interfacing) * [`List` indexing](#list-indexing) * [Interfacing traversals](#interfacing-traversals) * [Deepening topics](#deepening-topics) * [Understanding `L.filter`, `L.find`, `L.get`, and `L.when`](#understanding-filter-find-get-and-when) * [Advanced topics](#advanced-topics) * [Performance tips](#performance-tips) * [Nesting traversals does not create intermediate aggregates](#nesting-traversals-does-not-create-intermediate-aggregates) * [Avoid reallocating optics in `L.choose`](#avoid-reallocating-optics-in-l-choose) * [On bundle size and minification](#on-bundle-size-and-minification) * [Background](#background) * [Motivation](#motivation) * [Design choices](#design-choices) * [Partiality](#partiality) * [Focus on JSON](#focus-on-json) * [Use of `undefined`](#use-of-undefined) * [Allowing strings and integers as optics](#allowing-strings-and-integers-as-optics) * [Treating an array of optics as a composition of optics](#treating-an-array-of-optics-as-a-composition-of-optics) * [Applicatives](#applicatives) * [Combinators for creating new optics](#combinators-for-creating-new-optics) * [Indexing](#indexing) * [Static Land](#static-land) * [Performance](#performance) * [Benchmarks](#benchmarks) * [Lenses all the way](#lenses-all-the-way) * [Related work](#related-work) * [Papers and other introductory material](#papers-and-other-introductory-material) * [JavaScript / TypeScript / Flow libraries](#javascript-typescript-flow-libraries) * [Libraries for other languages](#libraries-for-other-languages) * [Contributing](#contributing) * [Building](#building) * [Testing](#testing) * [Documentation](#documentation) ## [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#tutorial) [Tutorial](#tutorial) Let's look at an example that is based on an actual early use case that lead to the development of this library. What we have is an external HTTP API that both produces and consumes JSON objects that include, among many other properties, a `titles` property: ```js const sampleTitles = { titles: [ {language: 'en', text: 'Title'}, {language: 'sv', text: 'Rubrik'} ] } ``` We ultimately want to present the user with a rich enough editor, with features such as [undo-redo](https://github.com/calmm-js/partial.lenses.history) and [validation](https://github.com/calmm-js/partial.lenses.validation), for manipulating the content represented by those JSON objects. The `titles` property is really just one tiny part of the data model, but, in this tutorial, we only look at it, because it is sufficient for introducing most of the basic ideas. So, what we'd like to have is a way to access the `text` of titles in a given language. Given a language, we want to be able to * get the corresponding text, * update the corresponding text, * insert a new text and the immediately surrounding object in a new language, and * remove an existing text and the immediately surrounding object. Furthermore, when updating, inserting, and removing texts, we'd like the operations to treat the JSON as [immutable](#on-immutability) and create new JSON objects with the changes rather than mutate existing JSON objects, because this makes it trivial to support features such as undo-redo and can also help to avoid bugs associated with mutable state. Operations like these are what lenses are good at. Lenses can be seen as a simple embedded [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) for specifying data manipulation and querying functions. Lenses allow you to focus on an element in a data structure by specifying a path from the root of the data structure to the desired element. Given a lens, one can then perform operations, like [`get`](#l-get) and [`set`](#l-set), on the element that the lens focuses on. ### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#getting-started) [Getting started](#getting-started) Let's first import the libraries ```jsx import * as L from 'partial.lenses' import * as R from 'ramda' ``` and [▶ play](https://calmm-js.github.io/partial.lenses/index.html#getting-started) just a bit with lenses. > Note that links with the [▶ > play](https://calmm-js.github.io/partial.lenses/index.html#getting-started) symbol, take > you to an interactive version of this page where almost all of the code > snippets are editable and evaluated in the browser. There is also a separate > [playground page](https://calmm-js.github.io/partial.lenses/playground.html) > that allows you to quickly try out lenses. As mentioned earlier, with lenses we can specify a path to focus on an element. To specify such a path we use primitive lenses like [`L.prop(propName)`](#l-prop), to access a named property of an object, and [`L.index(elemIndex)`](#l-index), to access an element at a given index in an array, and compose the path using [`L.compose(...lenses)`](#l-compose). So, to just [get](#l-get) at the `titles` array of the `sampleTitles` we can use the lens [`L.prop('titles')`](#l-prop): ```js L.get(L.prop('titles'), sampleTitles) // [{ language: 'en', text: 'Title' }, // { language: 'sv', text: 'Rubrik' }] ``` To focus on the first element of the `titles` array, we compose with the [`L.index(0)`](#l-index) lens: ```js L.get(L.compose(L.prop('titles'), L.index(0)), sampleTitles) // { language: 'en', text: 'Title' } ``` Then, to focus on the `text`, we compose with [`L.prop('text')`](#l-prop): ```js L.get(L.compose(L.prop('titles'), L.index(0), L.prop('text')), sampleTitles) // 'Title' ``` We can then use the same composed lens to also [set](#l-set) the `text`: ```js L.set( L.compose(L.prop('titles'), L.index(0), L.prop('text')), 'New title', sampleTitles ) // { titles: [{ language: 'en', text: 'New title' }, // { language: 'sv', text: 'Rubrik' }] } ``` In practise, specifying ad hoc lenses like this is not very useful. We'd like to access a text in a given language, so we want a lens parameterized by a given language. To create a parameterized lens, we can write a function that returns a lens. Such a lens should then [find](#l-find) the title in the desired language. Furthermore, while a simple path lens like above allows one to get and set an existing text, it doesn't know enough about the data structure to be able to properly insert new and remove existing texts. So, we will also need to specify such details along with the path to focus on. ### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#a-partial-lens-to-access-titles) [A partial lens to access title texts](#a-partial-lens-to-access-titles) Let's then just [compose](#l-compose) a parameterized lens for accessing the `text` of titles: ```js const textIn = language => L.compose( L.prop('titles'), L.normalize(R.sortBy(L.get('language'))), L.find(R.whereEq({language})), L.valueOr({language, text: ''}), L.removable('text'), L.prop('text') ) ``` Take a moment to read through the above definition line by line. Each part either specifies a step in the path to select the desired element or a way in which the data structure must be treated at that point. The [`L.prop(...)`](#l-prop) parts are already familiar. The other parts we will mention below. #### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#querying-data) [Querying data](#querying-data) Thanks to the parameterized search part, [`L.find(R.whereEq({language}))`](#l-find), of the lens composition, we can use it to query titles: ```js L.get(textIn('sv'), sampleTitles) // 'Rubrik' ``` The [`L.find`](#l-find) lens is given a predicate that it then uses to find an element from an array to focus on. In this case the predicate is specified with the help of Ramda's [`R.whereEq`](http://ramdajs.com/docs/#whereEq) function that creates an equality predicate from a given template object. ##### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#missing-data-can-be-expected) [Missing data can be expected](#missing-data-can-be-expected) Partial lenses can generally deal with missing data. In this case, when [`L.find`](#l-find) doesn't find an element, it instead works like a lens to [append](#l-appendto) a new element into an array. So, if we use the partial lens to query a title that does not exist, we get the default: ```js L.get(textIn('fi'), sampleTitles) // '' ``` We get this value, rather than `undefined`, thanks to the [`L.valueOr({language, text: ''})`](#l-valueor) part of our lens composition, which ensures that we get the specified value rather than `null` or `undefined`. We get the default even if we query from `undefined`: ```js L.get(textIn('fi'), undefined) // '' ``` With partial lenses, [`undefined` is the equivalent of non-existent](#use-of-undefined). #### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#updating-data) [Updating data](#updating-data) As with ordinary lenses, we can use the same lens to update titles: ```js L.set(textIn('en'), 'The title', sampleTitles) // { titles: [ { language: 'en', text: 'The title' }, // { language: 'sv', text: 'Rubrik' } ] } ``` #### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#inserting-data) [Inserting data](#inserting-data) The same partial lens also allows us to insert new titles: ```js L.set(textIn('fi'), 'Otsikko', sampleTitles) // { titles: [ { language: 'en', text: 'Title' }, // { language: 'fi', text: 'Otsikko' }, // { language: 'sv', text: 'Rubrik' } ] } ``` There are a couple of things here that require attention. The reason that the newly inserted object not only has the `text` property, but also the `language` property is due to the [`L.valueOr({language, text: ''})`](#l-valueor) part that we used to provide a default. Also note the position into which the new title was inserted. The array of titles is kept sorted thanks to the [`L.normalize(R.sortBy(L.get('language')))`](#l-normalize) part of our lens. The [`L.normalize`](#l-normalize) lens transforms the data when either read or written with the given function. In this case we used Ramda's [`R.sortBy`](http://ramdajs.com/docs/#sortBy) to specify that we want the titles to be kept sorted by language. #### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#removing-data) [Removing data](#removing-data) Finally, we can use the same partial lens to remove titles: ```js L.set(textIn('sv'), undefined, sampleTitles) // { titles: [ { language: 'en', text: 'Title' } ] } ``` Note that a single title `text` is actually a part of an object. The key to having the whole object vanish, rather than just the `text` property, is the [`L.removable('text')`](#l-removable) part of our lens composition. It makes it so that when the `text` property is set to `undefined`, the result will be `undefined` rather than merely an object without the `text` property. If we remove all of the titles, we get an empty array: ```js L.set(L.seq(textIn('sv'), textIn('en')), undefined, sampleTitles) // { titles: [] } ``` Above we use [`L.seq`](#l-seq) to run the [`L.set`](#l-set) operation over both of the focused titles. #### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#exercises) [Exercises](#exercises) Take out one (or more) [`L.normalize(...)`](#l-normalize), [`L.valueOr(...)`](#l-valueor) or [`L.removable(...)`](#l-removable) part(s) from the lens composition and try to predict what happens when you rerun the examples with the modified lens composition. Verify your reasoning by actually rerunning the examples. ### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#shorthands) [Shorthands](#shorthands) For clarity, the previous code snippets avoided some of the shorthands that this library supports. In particular, * [`L.compose(...)`](#l-compose) can be abbreviated as an array [`[...]`](#l-compose), * [`L.prop(propName)`](#l-prop) can be abbreviated as [`propName`](#l-prop), and * [`L.set(l, undefined, s)`](#l-set) can be abbreviated as [`L.remove(l, s)`](#l-remove). ### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#systematic-decomposition) [Systematic decomposition](#systematic-decomposition) It is also typical to compose lenses out of short paths following the schema of the JSON data being manipulated. Recall the lens from the start of the example: ```jsx L.compose( L.prop('titles'), L.normalize(R.sortBy(L.get('language'))), L.find(R.whereEq({language})), L.valueOr({language, text: ''}), L.removable('text'), L.prop('text') ) ``` Following the structure or schema of the JSON, we could break this into three separate lenses: * a lens for accessing the titles of a model object, * a parameterized lens for querying a title object from titles, and * a lens for accessing the text of a title object. Furthermore, we could organize the lenses to reflect the structure of the JSON model: ```js const Title = { text: [L.removable('text'), 'text'] } const Titles = { titleIn: language => [ L.find(R.whereEq({language})), L.valueOr({language, text: ''}) ] } const Model = { titles: ['titles', L.normalize(R.sortBy(L.get('language')))], textIn: language => [Model.titles, Titles.titleIn(language), Title.text] } ``` We can now say: ```js L.get(Model.textIn('sv'), sampleTitles) // 'Rubrik' ``` This style of organizing lenses is overkill for our toy example. In a more realistic case the `sampleTitles` object would contain many more properties. Also, rather than composing a lens, like `Model.textIn` above, to access a leaf property from the root of our object, we might actually compose lenses incrementally as we inspect the model structure. ### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#manipulating-multiple-items) [Manipulating multiple items](#manipulating-multiple-items) So far we have used a lens to manipulate individual items. This library also supports [traversals](#traversals) that compose with lenses and can target multiple items. Continuing on the tutorial example, let's define a traversal that targets all the texts: ```js const texts = [Model.titles, L.elems, Title.text] ``` What makes the above a traversal is the [`L.elems`](#l-elems) part. The result of composing a traversal with a lens is a traversal. The other parts of the above composition should already be familiar from previous examples. Note how we were able to use the previously defined `Model.titles` and `Title.text` lenses. Now, we can use the above traversal to [`collect`](#l-collect) all the texts: ```js L.collect(texts, sampleTitles) // [ 'Title', 'Rubrik' ] ``` More generally, we can [map and fold](#l-concatas) over texts. For example, we could use [`L.maximumBy`](#l-maximumby) to find a title with the maximum length: ```js L.maximumBy(R.length, texts, sampleTitles) // 'Rubrik' ``` Of course, we can also modify texts. For example, we could uppercase all the titles: ```js L.modify(texts, R.toUpper, sampleTitles) // { titles: [ { language: 'en', text: 'TITLE' }, // { language: 'sv', text: 'RUBRIK' } ] } ``` We can also manipulate texts selectively. For example, we could remove all the texts that are longer than 5 characters: ```js L.remove([texts, L.when(t => t.length > 5)], sampleTitles) // { titles: [ { language: 'en', text: 'Title' } ] } ``` ### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#next-steps) [Next steps](#next-steps) This concludes the tutorial. The reference documentation contains lots of tiny examples and a few [more involved examples](#l-lazy). The [examples](#examples) section describes a couple of lens compositions we've found practical as well as examples that may help to see [possibilities beyond the immediately obvious](#bst-as-a-lens). The [wiki](https://github.com/calmm-js/partial.lenses/wiki) contains further examples and playground links. There is also a document that describes [a simplified implementation of optics](IMPLEMENTATION.md) in a similar style as the implementation of this library. Last, but perhaps not least, there is also a page of [Partial Lenses Exercises](https://calmm-js.github.io/partial.lenses/exercises.html) to solve. ## [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#the-why-of-optics) [The why of optics](#the-why-of-optics) Optics provide a way to decouple the operation to perform on an element or elements of a data structure from the details of selecting the element or elements and the details of maintaining the integrity of the data structure. In other words, a selection algorithm and data structure invariant maintenance can be expressed as a composition of optics and used with many different operations. Consider how one might approach the [tutorial](#tutorial) problem without optics. One could, for example, write a collection of operations like `getText`, `setText`, `addText`, and `remText`: ```js const getEntry = R.curry( (language, data) => data.titles.find(R.whereEq({language})) ) const hasText = R.pipe(getEntry, Boolean) const getText = R.pipe(getEntry, R.defaultTo({}), R.prop('text')) const mapProp = R.curry( (fn, prop, obj) => R.assoc(prop, fn(R.prop(prop, obj)), obj) ) const mapText = R.curry( (language, fn, data) => mapProp( R.map(R.ifElse(R.whereEq({language}), mapProp(fn, 'text'), R.identity)), 'titles', data ) ) const remText = R.curry( (language, data) => mapProp( R.filter(R.complement(R.whereEq({language}))), 'titles' ) ) const addText = R.curry( (language, text, data) => mapProp(R.append({language, text}), 'titles', data) ) const setText = R.curry( (language, text, data) => mapText(language, R.always(text), data) ) ``` You can definitely make the above operations both cleaner and more robust. For example, consider maintaining the ordering of texts and the handling of cases such as using `addText` when there already is a text in the specified language and `setText` when there isn't. With partial optics, however, you separate the selection and data structure invariant maintenance from the operations as illustrated in the [tutorial](#tutorial) and due to the separation of concerns that tends to give you a lot of robust functionality in [a small amount of code](#a-partial-lens-to-access-titles). ## [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#reference) [Reference](#reference) The [combinators](https://wiki.haskell.org/Combinator) provided by this library are available as named imports. Typically one just imports the library as: ```jsx import * as L from 'partial.lenses' ``` ### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#stable-subset) [Stable subset](#stable-subset) This library has historically been developed in a fairly aggressive manner so that features have been marked as obsolete and removed in subsequent major versions. This can be particularly burdensome for developers of libraries that depend on partial lenses. To help the development of such libraries, this section specifies a tiny subset of this library as *stable*. While it is possible that the stable subset is later extended, nothing in the stable subset will ever be changed in a backwards incompatible manner. The following operations, with the below mentioned limitations, constitute the stable subset: * [`L.compose(...optics) ~> optic`](#l-compose) is stable with the exception that one must not depend on being able to compose optics with ordinary functions. Also, the use of arrays to denote composition is not part of the stable subset. Note that [`L.compose()`](#l-compose) is guaranteed to be equivalent to the [`L.identity`](#l-identity) optic. * [`L.get(lens, maybeData) ~> maybeValue`](#l-get) is stable without limitations. * [`L.lens(maybeData => maybeValue, (maybeValue, maybeData) => maybeData) ~> lens`](#l-lens) is stable with the exception that one must not depend on the user specified getter and setter functions being passed more than 1 and 2 arguments, respectively, and one must make no assumptions about any extra parameters being passed. * [`L.modify(optic, maybeValue => maybeValue, maybeData) ~> maybeData`](#l-modify) is stable with the exception that one must not depend on the user specified function being passed more than 1 argument and one must make no assumptions about any extra parameters being passed. * [`L.remove(optic, maybeData) ~> maybeData`](#l-remove) is stable without limitations. * [`L.set(optic, maybeValue, maybeData) ~> maybeData`](#l-set) is stable without limitations. The main intention behind the stable subset is to enable a dependent library to make basic use of lenses created by client code using the dependent library. In retrospect, the stable subset has existed since version 2.2.0. ### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#additional-libraries) [Additional libraries](#additional-libraries) The main Partial Lenses library aims to provide robust general purpose combinators for dealing with plain JavaScript data. Combinators that are more experimental or specialized in purpose or would require additional dependencies aside from the [Infestines](https://github.com/polytypic/infestines) library, which is mainly used for the currying helpers it provides, are not provided. Currently the following additional Partial Lenses libraries exist: * [Partial Lenses History](https://github.com/calmm-js/partial.lenses.history) * [Partial Lenses Validation](https://github.com/calmm-js/partial.lenses.validation) ### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#optics) [Optics](#optics) The abstractions, [traversals](#traversals), [lenses](#lenses), and [isomorphisms](#isomorphisms), provided by this library are collectively known as *optics*. Traversals can target any number of elements. Lenses are a restriction of traversals that target a single element. Isomorphisms are a restriction of lenses with an [inverse](#l-inverse). In addition to basic bidirectional optics, this library also supports more arbitrary [transforms](#transforms) using optics with [sequencing](#l-seq) and [transform ops](#transforming). Transforms allow operations, such as modifying a part of data structure multiple times or even in a loop, that are not possible with basic optics. Some optics libraries provide many more abstractions, such as "optionals", "prisms" and "folds", to name a few, forming a DAG. Aside from being conceptually important, many of those abstractions are not only useful but required in a statically typed setting where data structures have precise constraints on their shapes, so to speak, and operations on data structures must respect those constraints at *all* times. On the other hand, in a dynamically typed language like JavaScript, the shapes of run-time objects are naturally *malleable*. Nothing immediately breaks if a new object is created as a copy of another object by adding or removing a property, for example. We can exploit this to our advantage by considering all optics as *partial* and manage with a smaller amount of distinct classes of optics. #### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#on-partiality) [On partiality](#on-partiality) By [definition](https://en.wikipedia.org/wiki/Partial_function), a *total function*, or just a *function*, is defined for all possible inputs. A *partial function*, on the other hand, may not be defined for all inputs. As an example, consider an operation to return the first element of an array. Such an operation cannot be total unless the input is restricted to arrays that have at least one element. One might think that the operation could be made total by returning a special value in case the input array is empty, but that is no longer the same operation—the special value is not the first element of the array. Now, in partial lenses, the idea is that in case the input does not match the expectation of an optic, then the [input is treated as being `undefined`, which is the equivalent of non-existent](#use-of-undefined): reading through the optic gives `undefined` and writing through the optic replaces the focus with the written value. This makes the optics in this library partial and allows specific partial optics, such as the simple [`L.prop`](#l-prop) lens, to be used in a wider range of situations than corresponding total optics. Making all optics partial has a number of consequences. For one thing, it can potentially hide bugs: an incorrectly specified optic treats the input as `undefined` and may seem to work without raising an error. We have not found this to be a major source of bugs in practice. However, partiality also has a number of benefits. In particular, it allows optics to seamlessly support both insertion and removal. It also allows to reduce the number of necessary abstractions and it tends to make compositions of optics more concise with fewer required parts, which both help to avoid bugs. #### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#on-indexing) [On indexing](#on-indexing) Optics in this library support a simple unnested form of indexing. When focusing on an array element or an object property, the index of the array element or the key of the object property is passed as the index to user defined functions operating on that focus. For example: ```js L.get( [L.find(R.equals('bar')), (value, index) => ({value, index})], ['foo', 'bar', 'baz'] ) // {value: 'bar', index: 1} ``` ```js L.modify(L.values, (value, key) => ({key, value}), {x: 1, y: 2}) // {x: {key: 'x', value: 1}, y: {key: 'y', value: 2}} ``` Only optics directly operating on array elements and object properties produce indices. Most optics do not have an index of their own and they pass the index given by the preceding optic as their index. For example, [`L.when`](#l-when) doesn't have an index by itself, but it passes through the index provided by the preceding optic: ```js L.collectAs( (value, index) => ({value, index}), [L.elems, L.when(x => x > 2)], [3, 1, 4, 1] ) // [{value: 3, index: 0}, {value: 4, index: 2}] ``` ```js L.collectAs( (value, key) => ({value, key}), [L.values, L.when(x => x > 2)], {x: 3, y: 1, z: 4, w: 1} ) // [{value: 3, key: 'x'}, {value: 4, key: 'z'}] ``` When accessing a focus deep inside a data structure, the indices along the path to the focus are not collected into a path. However, it is possible to use [index manipulating combinators](#indices) to construct paths of indices and more. For example: ```js L.collectAs( (value, path) => [L.collect(L.flatten, path), value], L.lazy(rec => L.ifElse(R.is(Object), [L.joinIx(L.children), rec], [])), {a: {b: {c: 'abc'}}, x: [{y: [{z: 'xyz'}]}]} ) // [ [ [ "a", "b", "c", ], "abc", ], // [ [ "x", 0, "y", 0, "z", ], "xyz", ] ] ``` The reason for not collecting paths by default is that doing so would be relatively expensive due to the additional allocations. The [`L.choose`](#l-choose) combinator can also be useful in cases where there is a need to access some index or context along the path to a focus. #### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#on-immutability) [On immutability](#on-immutability) Starting with version [10.0.0](./CHANGELOG.md#1000), to strongly guide away from mutating data structures, optics call [`Object.freeze`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) on any new objects they create when `NODE_ENV` is not `production`. Why only non-`production` builds? Because `Object.freeze` can be quite expensive and the main benefit is in catching potential bugs early during development. Also note that optics do not implicitly "deep freeze" data structures given to them or freeze data returned by user defined functions. Only objects newly created by optic functions themselves are frozen. Starting with version [13.10.0](./CHANGELOG.md#13100), the possibility that optics do not unnecessarily clone input data structures is explicitly acknowledged. In case all elements of an array or object produced by an optic operation would be the same, as determined by [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is), then it is allowed, but not guaranteed, for the optic operation to return the input as is. #### [≡](#contents) [▶](https://calmm-js.github.io/partial.lenses/index.html#on-composability) [On composability](#on-composability) A lot of libraries these days claim to be [composable](https://en.wikipedia.org/wiki/Composability). Is any collection of functions composable? In the opinion of the author of this library, in order for something to be called "composable", a couple of conditions must be fulfilled: 1. There must be an operation or operations that perform composition. 2. There must be simple laws on how compositions behave. Conversely, if there is no operation to perform composition or there are no useful simplifying laws on how compositions behave, then one sho

	Stars	Issues	Version	Updated	Created
lodash	59,616	102	4.17.21	4 years ago	12 years ago
partial.lenses	911	22	14.17.0	6 years ago	9 years ago
ramda	23,752	146	0.30.1	3 months ago	10 years ago
rxjs	30,617	263	7.8.1	a year ago	13 years ago

lodash vs partial.lenses vs ramda vs rxjs

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Sick of boring JavaScript newsletters?

Downloads in past