partial.lenses

Optics provide a way to decouple the operation you want to perform on data from the logic required to select specific elements and the logic required to maintain the integrity (invariants) of the data structure.

By using optics, you can express selection algorithms and data structure invariant maintenance as a composition of optics. This allows you to reuse those optics across many different operations, leading to more robust and concise code compared to writing manual getter/setter functions for every specific data shape.

Partial Lenses are an abstraction used to simultaneously specify operations to update and query immutable data structures.

This library provides a collection of optics, which include:

• Isomorphisms: Mapping between different data representations.
• Lenses: Focusing on specific parts of a data structure.
• Traversals: Navigating through multiple parts of a structure.

Partial Lenses specifically allow you to:

• View optional data.
• Insert new data.
• Update existing data.
• Remove existing data.
• Provide defaults and maintain required parts of a data structure.

While optimized for JSON, you can write new optics for non-JSON objects, such as Immutable.js collections.

Unlike standard functional programming approaches (like Ramda's R.map or R.filter) which create intermediate arrays at every step of a composition, partial.lenses traversals do not materialize intermediate aggregates. This makes them highly efficient for processing large datasets.

Example Comparison:

Using standard composition:

// Creates intermediate arrays for flatten, map, and filter
const sumPositiveXs = R.pipe(R.flatten, R.map(R.prop('x')), R.filter(R.lt(0)), R.sum)

Using partial.lenses traversals:

// No intermediate arrays are created
L.sum([L.flatten, 'x', L.when(R.lt(0))], sampleXs)

The library provides various ways to compose and transform data using optics. The following table summarizes the available forms and their mathematical semantics:

Partial lenses are designed to handle missing data gracefully. If L.find fails to locate an element, the lens can behave as an instruction to append a new element. You can use L.valueOr(defaultValue) to ensure that querying non-existent data returns a specific default instead of undefined or null.

// If 'fi' doesn't exist, L.valueOr ensures we get the default value
L.get(textIn('fi'), sampleTitles) // returns ''

// Works even if the source object is undefined
L.get(textIn('fi'), undefined) // returns ''

The library provides abstractions known as optics. These are used to focus on parts of data structures.

Core Abstractions:

• Traversals: Can target any number of elements.
• Lenses: A restriction of traversals that target exactly one element.
• Isomorphisms: A restriction of lenses that includes an inverse.

Key Design Principle: Partiality Unlike 'total' functions that must be defined for all inputs, these optics are partial. If an input does not match the expectation of an optic, the input is treated as undefined.

• Reading: Returns undefined if the path doesn't exist.
• Writing: Replaces the focus with the written value (effectively performing an insertion if the path was missing).

This partiality allows optics to seamlessly support both insertion and removal and makes compositions more concise.

An isomorphism is a lens that maps between two different data structures (e.g., a flat object and a nested object) such that the mapping is reversible.

In this library, there is no strict type distinction between partial lenses and isomorphisms, meaning combinators like L.pick can create isomorphisms. However, note that some optic composition patterns (like adapting or querying) may not work as expected on inverted isomorphisms.

To view through an isomorphism in the inverse direction, use L.getInverse.

// L.getInverse(iso, data) is equivalent to L.set(iso, data, undefined)

const expect = (p, f) => x => (p(x) ? f(x) : undefined)
const offBy1 = L.iso(expect(R.is(Number), R.inc), expect(R.is(Number), R.dec))

L.getInverse(offBy1, 1)
// 0

// Using getInverse with a partial lens to construct a minimal structure:
L.getInverse('meaning', 42)
// { meaning: 42 }

Partial Lenses is a high-performance optics library for JavaScript designed to manipulate JSON data structures. Unlike 'total' lens libraries (like older versions of Ramda) which might throw errors when accessing non-existent paths, Partial Lenses are designed to be partial.

This means optics can seamlessly:

• View existing elements.
• Insert new elements.
• Replace elements with different types.
• Remove elements.

By making all optics partial, the library provides full CRUD (Create, Read, Update, Delete) semantics within a compositional framework. It uses undefined to represent nothingness, which avoids the ambiguity of null in JSON data.

Lenses act as a DSL for querying and manipulating data. You can compose paths using L.compose(...lenses) (or the shorthand array syntax [...]) to focus on a specific element. Once focused, you can use L.get to retrieve the value or L.set to update it. All operations treat the data as immutable, returning a new object with the changes applied.

// Focus on the first element of the 'titles' array
const firstTitleLens = L.compose(
  L.prop('titles'),
  L.index(0)
)

// Get the value
L.get(firstTitleLens, sampleTitles)

// Set the value (returns a new object)
L.set(firstTitleLens, 'New title', sampleTitles)