Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/leviysoft/Visor
.NET optics library
https://github.com/leviysoft/Visor
dotnet lens optics records
Last synced: about 2 months ago
JSON representation
.NET optics library
- Host: GitHub
- URL: https://github.com/leviysoft/Visor
- Owner: leviysoft
- License: apache-2.0
- Created: 2023-08-31T14:45:00.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2023-11-20T18:16:48.000Z (10 months ago)
- Last Synced: 2024-05-16T00:17:07.471Z (4 months ago)
- Topics: dotnet, lens, optics, records
- Language: C#
- Homepage:
- Size: 55.7 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Codeowners: CODEOWNERS
Awesome Lists containing this project
- csharp-source-generators - Visor -   C# optics library with incremental code generator (maintained fork of [suspended Tinkoff project](https://github.com/Tinkoff/Visor)) (Source Generators / Functional Programming)
README
# Visor
LeviySoft.Visor is an optics library for .NET
## Rationale
C# 9 introduced record types, which are a first-class implementation of immutable data types.
While records are very useful for domain modeling, it can be pretty akward to modify deeply nested structures:
```csharp
record InnerItem(int Id, string Name);
record ItemWrapper(InnerItem Item, ...);
record Warehouse(ItemWrapper Main, ...);
var warehouse = new WareHouse(..); //We want to modify Id of InnerItem here
var warehouse2 = warehouse with {
Main = warehouse.Main with {
Item = warehouse.Main.Item with {
Id = 42 //Here is our new Id
}
}
}
```
This problem becomes more annoying with every new level of nesting,
and here optics come on the scene. The overall concept of optics
is to abstract accessing (and modifying) immutable data from
the data itself. Let's generate `Lens` optic for the case above and see,
how can we re-write our modification:
```csharp
[Optics] partial record InnerItem(int Id, string Name);
[Optics(withNested: true)] partial record ItemWrapper(InnerItem Item, ...);
[Optics(withNested: true)] partial record Warehouse(ItemWrapper Main, ...);
var warehouse = new WareHouse(..);
var warehouse2 = Warehouse.FocusMain.FocusItem.IdLens.Set(42)(warehouse);
```
`withNested` controls "chained" Lens generation.
`Lens` is not the only optic on the table, with `Prism` for example you can
abstract over subtyping, with `Traverse` over enumerable structures etc.
## How-to
- install `LeviySoft.Visor` and `LeviySoft.Visor.Gen`
- add `[Optics]` attribute on your record and make your record partial
```csharp
[Optics]
partial record Sample(int Id, string Description);
```
- now you can use `Sample` static class containing optics:
```csharp
var id = Sample.IdLens.Get(...);
Sample.DescriptionLens.Set("replaced")(...);
```
## Dealing with immutable collections & nullable properties
`Visor` comes with a useful set of optics for manipulating values at nullable anr/or collection properties.
Although `System.Collections.Immutable` is supported I strongly recommend using language-ext's immutable collections
because standart ones breaks value equality of records.
Here is a brief example of using build-in optics:
```csharp
[Optics] internal partial record InnerItem(int Id, string Name);
[Optics] internal partial record Aux(string Comment, IImmutableList Tags);
[Optics(withNested: true)] internal partial record ItemWrapper(InnerItem Item, Aux? Aux);
[Optics(withNested: true)] internal partial record Warehouse(ItemWrapper Main);
var warehouse = new Warehouse(new ItemWrapper(new InnerItem(1, "Default"), new Aux("test", ImmutableList.Create("tag1", "tag2"))));
var telescope = Warehouse.FocusMain.AuxLens.NotNull().Compose(Aux.TagsLens).Compose(Property.IImmutableList.First());
var warehouse2 = telescope.Set("updated_tag")(warehouse); //Now warehouse2.Main.Aux?.Tags is ("updated_tag", "tag2")
```
## Coming soon
- Prism
- Traverse
- Fold
- Iso
## Other notes
LeviySoft.Visor is an independently maintained fork of Tinkoff.Visor and is not related to Tinkoff in any kind.