/optics.ts | fun@v.2.0.0-alpha.11

A collection of algebraic data types, lenses, and schemables based on a light weight higher kinded type implementation. Written for deno.

baetheus/fun

Go to Latest

benchmarks examples scripts

mod.ts (default module)

alt

map

alt

map

Key

alt

map

alt

map

ContravariantFnEither

alt

map

map

One

Two

one

map

map

JsonSchemaDefinitions

map

Out

map

pop

iso

Nil

nil

alt

map

SemigroupNumberProduct

add

lte

mod

Iso

Tag

set

iso

key

map

alt

map

Ord

gte

lte

max

min

dup

map

ContravariantPredicate

and

not

all

map

map

KindUnknownRefinement

and

max

min

map

set

map

put

alt

map

map

map

map

import * as fun from "https://deno.land/x/fun@v.2.0.0-alpha.11/optics.ts";

Optics are a collection of combinators for focusing on specific parts of data within an existing structure. The core operations are view, review, and modify. Optics in the fun library are based on the concept of Kliesli optics as outlined here.

Their uses include (but are not limited to):

Accessing deeply nested data
Mapping related but distinct types without loss of fidelity
Immutably modifying large data structures

At its core, instead of separating the view method into view, preview, and toList of, as is done in many languages and libraries. This implementation uses a single view method that operates as a Kliesli arrow (a -> mb) where the m in this case is limited to the Identity, Option, and Array monads, which can be composed using Natural transformations and flatMap.

In addition to view, there are also implementations of review and modify, which also have composition functions.. but the research for composition is not yet complete for review.

In any case, this implementation of optics is distinct from Laarhoven lenses and profunctor optics, and is much more compact and performant in typescript than those implementations.

Variables

v AffineTag	A runtime tag and type that indicates an Optic has a view function of the form `(s: S) => Option<A>`.
v array	A preconstructed traversal that focuses the values of a ReadonlyArray.
v first	A preconstructed composed lens that focuses on the First value of a Pair.
v FoldTag	A runtime tag and type that indicates an Optic has a view function of the form `(s: S) => ReadonlyArray<A>`.
v left	A preconstructed composed prism that focuses on the Left value of an Either.
v LensTag	A runtime tag and type that indicates an Optic has a view function of the form `(s: S) => Identity<A>`.
v nilable	A preconstructed filter that focuses on the the non-null and non-undefined value of A \| null \| undefined.
v record	A preconstructed traversal that focuses the values of a ReadonlyRecord.
v right	A preconstructed composed prism that focuses on the Right value of an Either.
v second	A preconstructed composed lens that focuses on the Second value of a Pair.
v set	A preconstructed traversal that focuses the values of a ReadonlySet.
v some	A preconstructed composed prism that focuses on the Some value of an Option.
v tree	A preconstructed traversal that focuses the values of a Tree.

Functions

f _unsafeCast	Given a Viewer<U, S, A> and an optic tag V, this function produces a view function that can be used in a Viewer<V, S, A>. However, not all casts are valid. The following are the only supported casts, by their optic tag:
f affineFold	Construct an AffineFold<S, A> from view and modify functions.
f ap	Apply the value returned by a Viewer to a function returned by a Viewer.
f atKey	A composible combinator that focuses on a key in a readonly record. The difference between atKey and key is that the key can be removed from the record by the modify function if the modify function returns None.
f atMap	Construct a composable combinator from an instance of Eq and a key of a map. The combinator can then be composed with an existing optic to access or remove the value in the map.
f compose	Compose two optics, aligning their tag and building the composition using natural transformations and monadic chaining for the view function and using direct composition for the modify function.
f composeReviewer	Compose two reviewer functions, allowing one to create nested Reviewer structures.
f concatAll	Given a Monoid and a function A -> I, collect all values A focused on by an optic into a single value I.
f filter	A composible combinator that can filter or refine the focused value of an existing optic. Care should be taken with this operator as it apples to the modify function as well as the view function. That is to say that if the refinement or predicate returns false for the focused value then that value will not be modified. See the example for clarification.
f fold	Construct a Fold<S, A> from view and modify functions.
f fromPredicate	Construct a Prism<S, A> from a Refinement<S, A>.
f id	Construct an Iso<A, A> from a type level argument. This is the entrypoint to almost all optics as it allows one to start with a type and compose other optics from there.
f imap	An invariant map over an Optic. If a type can be represented isomorphically by another type, one can imap to go back and forth.
f index	A composible combinator that focuses on a value in an array at the given index.
f iso	Construct an Iso<S, A> from view and review functions, with an optional modify function if it is different from
f key	A composible combinator that focuses on a key in a readonly record.
f lens	Construct a Lens<S, A> from view and modify functions.
f map	Map over the Viewer portion of an optic. This effectively uses the map from the Monad associated with the tag of the optic.
f modifier	Construct a Modifier<S, A. from a modify function.
f modify	A pipeable modify function that applies a modification function to a Modifier<S, A> modify function. It will return a function S -> S that applies the modify function according to the type of optic. Note: All Optics are Modifiers.
f of	Construct a Lens Viewer from a raw value A. The view function of this viewer operatates like constant(a).
f optic	Construct an Optic<U, S, A> & Reviewer<S, A> from a tag as well as view, modify, and reivew functions.
f prism	Construct a Prism<S, A> from view and review functions, with an optional modify function that will be defaulted if not provided.
f prop	A composable combinator that focuses on a property P of a struct.
f props	A composible combinator that focuses on a list of properties of a struct.
f refold	Construct a Refold<S, A> from view, review, and modify functions.
f replace	A pipeable replace function, that uses the modify function of an Optic to replace an existing value over the structure S.
f review	A pipeable review function that applies a value A to the the review function of a Reviewer<S, A>. It returns a value S.
f reviewer	Construct a Reviewer<S, A> from a review function.
f traverse	Construct a composable optic from a Traversable instance for a Kind T. This will reduce the values wrapped in the Kind T into a single Array when viewed.
f view	A pipeable view function that applies a value S to a Viewer<S, A>. It will return either a raw value, an option, or a readonlyarray based on the tag of the Viewer. Note: All Optics are Viewers.
f viewer	Construct a Viewer<T, S, A> from a tag T and a view function that matches said tag. This is a raw constructor and is generally only useful if there is a case where a structure can be lensed into but not reconstructed or traversed. However, this is the core composable structure of optics, as they are primarily meant as a way to retrieve data from an existing structure.

Interfaces

I Modifier	The Modifier<S, A> type implements the modify function `(mod: (a: A) => A) => (s: S) => S`. This type is directly composable and from it one can recover set/replace behavior.
I Optic	An Optic<T, S, A> is defined as a Viewer<T, S, A> combined with a Modifier<S, A>. This is the root type for the specific types of Optics defined below.
I Reviewer	The Reviewer<S, A. type implements the review function `(a: A) => S`. This type is directly composable and is used when the S type in Viewer<U, S, A> can be reconstructed from A. Some examples are constructing `Option<number>` from `number`, `Array<number>` from `number`, etc.
I Viewer	A Viewer<T, S, A> implements a view function `(s: S) => T<A>`. This is effectively a Kliesli Arrow. The valid types of T are Identity, Option, and Array. Viewer also includes a runtime tag corresponding to the return type of the view function to aid in composition.

Type Aliases

T AffineFold	AffineFold<S, A> is an alias of Optic<AffineTag, S, A>. This means the view function of an AffineFold returns an Option, `(s: S) => Option<A>`. Some example AffineFolds are accessing a value at an index in an array, accessing the value in an Option, and accessing a key in a Record type. In general, an AffineFold is used for focusing on zero or one value `A` contained in the value `S`.
T AffineTag
T Fold	Fold<S, A> is an alias of Optic<FoldTag, S, A>. This means that the view function of a Fold returns a ReadonlyArray, `(s: S) => ReadonlyArray<A>`. Some example Folds are accessing all of the values in a Record, Tree, Set, etc. In general, a Fold is used for focusing on any number of values `A` contained in the value `S`.
T FoldTag
T Iso	Iso<S, A> is an alias of Lens<S, A> & Reviewer<S, A>. This means that an Iso operates exactly like a Lens with the added ability to go back from A to S.
T Lens	Lens<S, A> is an alias of Optic<LensTag, S, A>. This means that the view function of a Lens returns a pure A value. `(s: S) => A`. Some example lenses are accessing the property of a struct, accessing the first value in a Pair, and the trivial identity Lens. In general, a Lens is used for focusing on exactly one value `A` contained in the value `S`.
T LensTag
T Prism	Prism<S, A> is an alias of AffineFold<S, A> & Reviewer<S, A>. This means that a Prism operates exactly like an AffineFold with the added ability to reconstruct an S from an A. Examples of this are reconstructing an Option from a number, or reconstructing Either<string, number> from a string or a number.
T Refold	Refold<S, A> is an alias of Fold<S, A> & Reviewer<S, A>. This means that a Refold operates exactly like a Fold with the added ability to reconstruct an S from a single value A. Examples of this are reconstructing an Array from a value A, or reconstructing a Tree from a value A.
T Tag	A type union of the supported view tags for a Viewer