optics

🔍 Optics

Functional optics for composable data access and manipulation in Go.

📖 Overview

Optics are first-class, composable references to parts of data structures. They provide a uniform interface for reading, writing, and transforming nested immutable data without verbose boilerplate code.

✨ Why Use Optics?

Optics bring powerful benefits to your Go code:

• 🎯 Composability: Optics naturally compose with each other and with monadic operations, enabling elegant data transformations through function composition
• 🔒 Immutability: Work with immutable data structures without manual copying and updating
• 🧩 Type Safety: Leverage Go's type system to catch errors at compile time
• 📦 Reusability: Define data access patterns once and reuse them throughout your codebase
• 🎨 Expressiveness: Write declarative code that clearly expresses intent
• 🔄 Bidirectionality: Read and write through the same abstraction
• 🚀 Productivity: Eliminate boilerplate for nested data access and updates
• 🧪 Testability: Optics are pure functions, making them easy to test and reason about

🔗 Composition with Monadic Operations

One of the most powerful features of optics is their natural composition with monadic operations. Optics integrate seamlessly with fp-go's monadic types like Option, Either, Result, and IO, allowing you to:

• Chain optional field access with Option monads
• Handle errors gracefully with Either or Result monads
• Perform side effects with IO monads
• Combine multiple optics in a single pipeline using Pipe

This composability enables you to build complex data transformations from simple, reusable building blocks.

🚀 Quick Start

import (
    "github.com/IBM/fp-go/v2/optics/lens"
    F "github.com/IBM/fp-go/v2/function"
)

type Person struct {
    Name string
    Age  int
}

// Create a lens for the Name field
nameLens := lens.MakeLens(
    func(p Person) string { return p.Name },
    func(p Person, name string) Person {
        p.Name = name
        return p
    },
)

person := Person{Name: "Alice", Age: 30}

// Get the name
name := nameLens.Get(person) // "Alice"

// Set a new name (returns a new Person)
updated := nameLens.Set("Bob")(person)
// person.Name is still "Alice", updated.Name is "Bob"

🛠️ Core Optics Types

🔎 Lens - Product Types (Structs)

Focus on a single field within a struct. Provides get and set operations.

Use when: Working with struct fields that always exist.

ageLens := lens.MakeLens(
    func(p Person) int { return p.Age },
    func(p Person, age int) Person {
        p.Age = age
        return p
    },
)

🔀 Prism - Sum Types (Variants)

Focus on one variant of a sum type. Provides optional get and definite set.

Use when: Working with Either, Result, or custom sum types.

💡 Important Use Case - Generalized Constructors for Do Notation:

Prisms act as generalized constructors, making them invaluable for Do notation workflows. The prism's ReverseGet function serves as a constructor that creates a value of the sum type from a specific variant. This is particularly useful when building up complex data structures step-by-step in monadic contexts:

import "github.com/IBM/fp-go/v2/optics/prism"

// Prism for the Success variant
successPrism := prism.MakePrism(
    func(r Result) option.Option[int] {
        if s, ok := r.(Success); ok {
            return option.Some(s.Value)
        }
        return option.None[int]()
    },
    func(v int) Result { return Success{Value: v} }, // Constructor!
)

// Use in Do notation to construct values
result := F.Pipe2(
    computeValue(),
    option.Map(func(v int) int { return v * 2 }),
    option.Map(successPrism.ReverseGet), // Construct Result from int
)

🔄 Iso - Isomorphisms

Bidirectional transformation between equivalent types with no information loss.

Use when: Converting between equivalent representations (e.g., Celsius ↔ Fahrenheit).

import "github.com/IBM/fp-go/v2/optics/iso"

celsiusToFahrenheit := iso.MakeIso(
    func(c float64) float64 { return c*9/5 + 32 },
    func(f float64) float64 { return (f - 32) * 5 / 9 },
)

❓ Optional - Maybe Values

Focus on a value that may or may not exist.

Use when: Working with nullable fields or values that may be absent.

import "github.com/IBM/fp-go/v2/optics/optional"

timeoutOptional := optional.MakeOptional(
    func(c Config) option.Option[*int] {
        return option.FromNillable(c.Timeout)
    },
    func(c Config, t *int) Config {
        c.Timeout = t
        return c
    },
)

🔢 Traversal - Multiple Values

Focus on multiple values simultaneously, allowing batch operations.

Use when: Working with collections or updating multiple fields at once.

import (
    "github.com/IBM/fp-go/v2/optics/traversal"
    TA "github.com/IBM/fp-go/v2/optics/traversal/array"
)

numbers := []int{1, 2, 3, 4, 5}

// Double all elements
doubled := F.Pipe2(
    numbers,
    TA.Traversal[int](),
    traversal.Modify[[]int, int](N.Mul(2)),
)
// Result: [2, 4, 6, 8, 10]

🔗 Composition

The real power of optics comes from composition:

type Company struct {
    Name    string
    Address Address
}

type Address struct {
    Street string
    City   string
}

// Individual lenses
addressLens := lens.MakeLens(
    func(c Company) Address { return c.Address },
    func(c Company, a Address) Company {
        c.Address = a
        return c
    },
)

cityLens := lens.MakeLens(
    func(a Address) string { return a.City },
    func(a Address, city string) Address {
        a.City = city
        return a
    },
)

// Compose to access city directly from company
companyCityLens := F.Pipe1(
    addressLens,
    lens.Compose[Company](cityLens),
)

company := Company{
    Name: "Acme Corp",
    Address: Address{Street: "Main St", City: "NYC"},
}

city := companyCityLens.Get(company)           // "NYC"
updated := companyCityLens.Set("Boston")(company)

⚙️ Auto-Generation with go generate

Lenses can be automatically generated using the fp-go CLI tool and a simple annotation. This eliminates boilerplate and ensures consistency.

📝 How to Use

1. Annotate your struct with the fp-go:Lens comment:

//go:generate go run github.com/IBM/fp-go/v2/main.go lens --dir . --filename gen_lens.go

// fp-go:Lens
type Person struct {
    Name  string
    Age   int
    Email string
    Phone *string  // Optional field
}

1. Run go generate:

go generate ./...

1. Use the generated lenses:

// Generated code creates PersonLenses, PersonRefLenses, and PersonPrisms
lenses := MakePersonLenses()

person := Person{Name: "Alice", Age: 30, Email: "alice@example.com"}

// Use the generated lenses
updatedPerson := lenses.Age.Set(31)(person)
name := lenses.Name.Get(person)

// Optional lenses for zero-value handling
personWithEmail := lenses.EmailO.Set(option.Some("new@example.com"))(person)

🎁 What Gets Generated

For each annotated struct, the generator creates:

• StructNameLenses: Lenses for value types with optional variants (LensO) for comparable fields
• StructNameRefLenses: Lenses for pointer types with prisms for constructing values
• StructNamePrisms: Prisms for all fields, useful for partial construction
• Constructor functions: MakeStructNameLenses(), MakeStructNameRefLenses(), MakeStructNamePrisms()

The generator supports:

• ✅ Generic types with type parameters
• ✅ Embedded structs (fields are promoted)
• ✅ Optional fields (pointers and omitempty tags)
• ✅ Custom package imports

See samples/lens for complete examples.

📊 Optics Hierarchy

[Iso](https://pkg.go.dev/github.com/IBM/fp-go/v2/optics/iso)[S, A]
    ↓
[Lens](https://pkg.go.dev/github.com/IBM/fp-go/v2/optics/lens)[S, A]
    ↓
[Optional](https://pkg.go.dev/github.com/IBM/fp-go/v2/optics/optional)[S, A]
    ↓
[Traversal](https://pkg.go.dev/github.com/IBM/fp-go/v2/optics/traversal)[S, A]

[Prism](https://pkg.go.dev/github.com/IBM/fp-go/v2/optics/prism)[S, A]
    ↓
[Optional](https://pkg.go.dev/github.com/IBM/fp-go/v2/optics/optional)[S, A]
    ↓
[Traversal](https://pkg.go.dev/github.com/IBM/fp-go/v2/optics/traversal)[S, A]

More specific optics can be converted to more general ones.

📦 Package Structure

• optics/lens: Lenses for product types (structs)
• optics/prism: Prisms for sum types (Either, Result, etc.)
• optics/iso: Isomorphisms for equivalent types
• optics/optional: Optional optics for maybe values
• optics/traversal: Traversals for multiple values

Each package includes specialized sub-packages for common patterns:

• array: Optics for arrays/slices
• either: Optics for Either types
• option: Optics for Option types
• record: Optics for maps

📚 Documentation

For detailed documentation on each optic type, see:

• Main Package Documentation
• Lens Documentation
• Prism Documentation
• Iso Documentation
• Optional Documentation
• Traversal Documentation

🌐 Further Reading

Haskell Lens Library

The concepts in this library are inspired by the powerful Haskell lens library, which pioneered many of these abstractions.

Articles and Resources

• Introduction to optics: lenses and prisms by Giulio Canti - Excellent introduction to optics concepts
• Lenses in Functional Programming - Tutorial on lens fundamentals
• Profunctor Optics: The Categorical View by Bartosz Milewski - Deep dive into the theory
• Why Optics? - Discussion of benefits and use cases

Why Functional Optics?

Functional optics solve real problems in software development:

• Nested Updates: Eliminate deeply nested field access patterns
• Immutability: Make working with immutable data practical and ergonomic
• Abstraction: Separate data access patterns from business logic
• Composition: Build complex operations from simple, reusable pieces
• Type Safety: Catch errors at compile time rather than runtime

💡 Examples

See the samples/lens directory for complete working examples, including:

• Basic lens usage
• Lens composition
• Auto-generated lenses
• Prism usage for sum types
• Integration with monadic operations

📄 License

Apache License 2.0 - See LICENSE file for details.