# optics-ts

> Type-safe, ergonomic, polymorphic optics for TypeScript

Latest version **2.4.1** (published 2023-07-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install optics-ts
pnpm add optics-ts
yarn add optics-ts
bun add optics-ts
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.4.1 |
| Published | 2023-07-10 |
| First published | 2020-01-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 133.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 906 |
| Author | Petri Lehtinen |
| Maintainers | akheron |
| Keywords | optics, lens, prism, traveral, isomorphism, immutable, functional-programming |

## Links

- npm: https://www.npmjs.com/package/optics-ts
- Repository: https://github.com/akheron/optics-ts
- npm.io page: https://npm.io/package/optics-ts

## Alternatives

- [@lexical/table](https://npm.io/package/@lexical/table.md) — 3.0M weekly downloads
- [mantine-datatable](https://npm.io/package/mantine-datatable.md) — 98.2K weekly downloads
- [react-native-collapsible-tab-view](https://npm.io/package/react-native-collapsible-tab-view.md) — 70.6K weekly downloads
- [@handsontable/vue3](https://npm.io/package/@handsontable/vue3.md) — 16.1K weekly downloads
- [vuewordcloud](https://npm.io/package/vuewordcloud.md) — 7.2K weekly downloads

## Recent versions

- 2.4.1 (latest) — 2023-07-10
- 2.2.0-pre.0 (next) — 2021-09-07
- 2.4.0 — 2022-11-03
- 2.3.0 — 2021-12-23
- 2.2.2 — 2021-10-22
- 2.2.1 — 2021-10-22
- 2.2.0 — 2021-09-07
- 2.1.0 — 2021-03-27
- 2.0.0 — 2020-12-01
- 1.2.0 — 2020-10-30
- 1.1.0 — 2020-05-05
- 1.1.0-pre.3 — 2020-05-02
- 1.1.0-pre.2 — 2020-05-02
- 1.1.0-pre.1 — 2020-04-29
- 1.0.0 — 2020-04-23
- … 2 more at https://npm.io/package/optics-ts/versions

## README

# optics-ts

[![Build](https://github.com/akheron/optics-ts/workflows/tests/badge.svg)](https://github.com/akheron/optics-ts/actions/workflows/tests.yml)

`optics-ts` provides type-safe, ergonomic, polymorphic optics for TypeScript:

- **Optics** allow you to read or modify values from deeply nested data
  structures, while keeping all data immutable.
- **Ergonomic**: Optics are composed with method chaining, making it easy and
  fun!
- **Polymorphic**: When writing through the optics, you can change the data
  types in the nested structure.
- **Type-safe**: The compiler will type check all operations you do. No `any`,
  ever.

➡ [Documentation](https://akheron.github.io/optics-ts) ⬅

## Features

`optics-ts` supports lenses, prisms, traversals, removing items from containers,
and much more!

Since optics-ts v2.2.0, there are two syntaxes for defining optics: method
chaining (the default) and standalone optics (experimental). See
[the docs](https://akheron.github.io/optics-ts) for more info!

## Getting started

Installation:

```
npm install optics-ts
```

or

```
yarn add optics-ts
```

Here's a simple example demonstrating how lenses can be used to drill into a
nested data structure:

```typescript
import * as O from 'optics-ts'

type Book = {
  title: string
  isbn: string
  author: {
    name: string
  }
}

// Create a lens that focuses on author.name
const optic = O.optic_<Book>().prop('author').prop('name')

// This is the input data
const input: Book = {
  title: "The Hitchhiker's Guide to the Galaxy",
  isbn: '978-0345391803',
  author: {
    name: 'Douglas Adams',
  },
}

// Read through the optic
O.get(optic)(input)
// "Douglas Adams"

// Write through the optic
O.set(optic)('Arthur Dent')(input)
// {
//   title: "The Hitchhiker’s Guide to the Galaxy"
//   isbn: "978-0345391803",
//   author: {
//     name: "Arthur Dent"
//   }
// }

// Update the existing value through the optic, while also changing the data type
O.modify(optic)((str) => str.length + 29)(input)
// {
//   title: "The Hitchhiker’s Guide to the Galaxy"
//   isbn: "978-0345391803",
//   author: {
//     name: 42
//   }
// }
```

Another example that converts all words longer than 5 characters to upper case:

```typescript
import * as O from 'optics-ts/standalone'

const optic = O.optic<string>().words().when(s => s.length >= 5)

const input = 'This is a string with some shorter and some longer words'
O.modify(optic)((s) => s.toUpperCase()(input)
// "This is a STRING with some SHORTER and some LONGER WORDS"
```

See the [documentation](https://akheron.github.io/optics-ts) for a tutorial and
a detailed reference of all supported optics.

## Development

Run `yarn` to install dependencies.

### Running the test suite

Run `yarn test`.

For compiling and running the tests when files change, run these commands in
separate terminals:

```
yarn build:test --watch
yarn jest dist-test/ --watchAll
```

### Documentation

You need Python 3 to build the docs.

```
python3 -m venv venv
./venv/bin/pip install mkdocs-material
```

Run a live reloading server for the documentation:

```
./venv/bin/mkdocs serve
```

Open http://localhost:8000/ in the browser.

### Releasing

```
$ yarn version --new-version <major|minor|patch>
$ yarn publish
$ git push origin main --tags
```

Open https://github.com/akheron/optics-ts/releases, edit the draft release,
select the newest version tag, adjust the description as needed.

---
_Source: https://npm.io/package/optics-ts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._