Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/akheron/optics-ts
Type-safe, ergonomic, polymorphic optics for TypeScript
https://github.com/akheron/optics-ts
functional-programming immutable isomorphism lens optics prism traversal typescript
Last synced: 7 days ago
JSON representation
Type-safe, ergonomic, polymorphic optics for TypeScript
- Host: GitHub
- URL: https://github.com/akheron/optics-ts
- Owner: akheron
- License: mit
- Created: 2020-01-09T19:30:35.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-12-04T19:55:51.000Z (20 days ago)
- Last Synced: 2024-12-11T17:16:56.254Z (14 days ago)
- Topics: functional-programming, immutable, isomorphism, lens, optics, prism, traversal, typescript
- Language: TypeScript
- Homepage:
- Size: 1.84 MB
- Stars: 795
- Watchers: 12
- Forks: 9
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.old.md
- License: LICENSE
Awesome Lists containing this project
README
# optics-ts
[](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_().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().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
$ 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.