# `Funx.Optics.Prism` Usage Rules ## LLM Functional Programming Foundation **Key Concepts for LLMs:** **Prism**: A partial optic for focusing on branches of data structures - **Partial access**: The focus may or may not be present (unlike Lens which is total) - **Two operations**: `preview/2` (extract, returns Maybe) and `review/2` (reconstruct from focus) - **Lawful**: Must satisfy round-trip laws for preview/review - **Compositional**: Prisms compose via `compose/2` or `compose/1` **Prism vs Lens:** - **Prism**: Partial access, returns Maybe, reconstructs minimal structure - **Lens**: Total access, always succeeds, updates while preserving structure - Use Prism when absence is normal; use Lens when absence is a bug **Key Path Syntax:** - `:atom` - Plain key access (works with maps and structs) - `Module` - Naked struct verification (checks type, no key access) - `{Module, :atom}` - Struct-typed field access (verifies struct type, then accesses key) - Modules are distinguished from keys using `function_exported?(atom, :__struct__, 0)` - Examples: - `path([:user, :profile])` - plain keys only - `path([User, :profile])` - verify root is User, then get :profile - `path([{User, :profile}, Profile])` - typed field access, then verify Profile - `path([Person])` - just verify type (no field access) **Prism Laws:** 1. **Review-Preview**: `preview(review(b, p), p) = Just(b)` (round-trip from value) 2. **Preview-Review**: If `preview(s, p) = Just(a)`, then `preview(review(a, p), p) = Just(a)` (round-trip preserves focus) **Important Constraints:** - Review constructs the *minimal* structure needed for preview, not the original structure. Other fields are lost. - **Cannot review with `nil`**: `review(nil, prism)` raises `ArgumentError` because `Just(nil)` is invalid in the Maybe monad, which would violate prism laws. - Preview treats `nil` values as `Nothing` (absence), not as a present value. ## LLM Decision Guide: When to Use Prisms **✅ Use Prism when:** - Accessing optional/nullable fields (user profile, config value) - Working with variants or sum types (selecting one case from many) - Selecting specific struct types from mixed data - Absence is normal and expected in the domain - Need to compose partial accessors - User says: "optional", "might not have", "only if", "when present", "extract from type" **❌ Use Lens when:** - Field access should always succeed - Need to update values while preserving structure - Absence would indicate a bug - Working with required fields - User says: "update", "set field", "modify in place" **⚡ Prism Strategy Decision:** - **Simple key access**: `Prism.key(:name)` for single map/struct field - **Nested paths**: `Prism.path([:user, :profile, :email])` for plain maps - **Struct-typed paths**: `Prism.path([{User, :profile}, {Profile, :email}])` for typed reconstruction - **Naked struct verification**: `Prism.path([User, :field])` or `Prism.path([:field, User])` to verify types - **Type-only check**: `Prism.path([User])` to just verify struct type with no field access - **Struct variants**: `Prism.struct(User)` for selecting specific struct types - **Composition**: `Prism.compose(p1, p2)` for two, `Prism.compose([p1, p2, p3])` for multiple - **Custom prisms**: `Prism.make/2` for custom preview/review logic **⚙️ Function Choice Guide:** - **Extract value**: `preview/2` returns `Just(value)` or `Nothing` (treats `nil` as `Nothing`) - **Reconstruct**: `review/2` builds minimal structure from focus (raises if value is `nil`) - **Compose prisms**: `compose/2` for two, `compose/1` for multiple - **Custom prisms**: `make/2` with preview and review functions ## LLM Context Clues **User language → Prism patterns:** - "optional user profile" → `Prism.path([{User, :profile}])` - "get email if present" → `Prism.preview(user, Prism.key(:email))` - "verify it's a User struct" → `Prism.path([User])` or `Prism.struct(User)` - "only if profile is Profile struct" → `Prism.path([:profile, Profile])` - "check User then get name" → `Prism.path([User, :name])` - "access nested optional field" → `Prism.path([:data, :config, :timeout])` - "extract from specific struct type" → `Prism.struct(Account)` - "chain optional lookups" → `Prism.compose(outer_prism, inner_prism)` ## Quick Reference - Use `preview/2` to extract - returns `Just(value)` or `Nothing` - Use `review/2` to reconstruct minimal structure from focus - **CRITICAL**: `review(nil, prism)` raises `ArgumentError` - cannot review with `nil` - Preview treats `nil` values as `Nothing` (absence) - Chain prisms with `compose/2` - failures propagate automatically - Plain path: `path([:a, :b, :c])` for maps - Typed path: `path([{User, :profile}, {Profile, :age}])` for structs - Naked struct: `path([User, :field])` or `path([:field, User])` to verify types - Type-only: `path([User])` just verifies struct type - **IMPORTANT**: `{Module, :field}` requires `:field` exists in `Module` for lawfulness - Modules vs keys: Distinguished by `function_exported?(atom, :__struct__, 0)` - Prisms return Maybe - use `Monad.bind/2`, `Monad.map/2`, or pattern match - Review loses data outside focus - this is expected and lawful - Custom logic: Use `make/2` with custom preview and review functions ## Overview `Funx.Optics.Prism` provides lawful partial optics for focusing on branches of data structures. Use Prism for: - Optional fields where absence is normal - Variant selection (choosing one case from many possibilities) - Filtered data access (only process matching values) - Compositional partial access - Situations where failure to find a value is expected **Key insight**: Prisms model *partial* access where the focus may not exist. Unlike Lens (which always succeeds), Prism returns Maybe to represent presence/absence. Review constructs the minimal structure needed for the focus, not the full original structure. ## Constructors ### `key/1` - Focus on Map/Struct Key Creates a prism focusing on a single key: ```elixir alias Funx.Optics.Prism alias Funx.Monad.Maybe p = Prism.key(:name) # Preview extracts if present Prism.preview(%{name: "Alice"}, p) #=> Just("Alice") Prism.preview(%{email: "alice@example.com"}, p) #=> Nothing (key missing) Prism.preview(%{name: nil}, p) #=> Nothing (nil treated as absent) # Review constructs minimal structure Prism.review("Alice", p) #=> %{name: "Alice"} # IMPORTANT: Cannot review with nil Prism.review(nil, p) #=> ** (ArgumentError) Cannot review with nil. Prisms use Maybe, which doesn't allow nil values. ``` ### `path/1` - Focus on Nested Path Creates a prism for nested access with optional struct typing: ```elixir # Plain map path p1 = Prism.path([:user, :profile, :email]) Prism.review("alice@example.com", p1) #=> %{user: %{profile: %{email: "alice@example.com"}}} # Struct-typed path using {Module, :key} syntax defmodule Profile, do: defstruct [:email, :age] defmodule User, do: defstruct [:name, :profile] p2 = Prism.path([{User, :profile}, {Profile, :email}]) Prism.review("alice@example.com", p2) #=> %User{profile: %Profile{email: "alice@example.com", age: nil}, name: nil} # Naked struct at end verifies final type p3 = Prism.path([:profile, Profile]) Prism.preview(%{profile: %Profile{email: "alice@example.com"}}, p3) #=> Just(%Profile{email: "alice@example.com", age: nil}) # Naked struct at beginning verifies root type p4 = Prism.path([User, :name]) Prism.review("Alice", p4) #=> %User{name: "Alice", profile: nil} # Type-only verification (no field access) p5 = Prism.path([User]) Prism.preview(%User{name: "Bob"}, p5) #=> Just(%User{name: "Bob", profile: nil}) # Mix all three forms p6 = Prism.path([{User, :profile}, Profile, :email]) Prism.review("alice@example.com", p6) #=> %User{profile: %Profile{email: "alice@example.com", age: nil}, name: nil} ``` **Syntax:** - `:atom` - Plain key access - `Module` - Naked struct verification (just type check, no field access) - `{Module, :atom}` - Typed field access (struct check + key access) **How it works:** - `:key` → `key(:key)` - `Module` → `struct(Module)` (when Module has `__struct__/0`) - `{Module, :key}` → `compose(struct(Module), key(:key))` **IMPORTANT**: Only use `{Module, :field}` when `:field` exists in `Module`. Using non-existent fields may violate prism laws. ### `struct/1` - Focus on Struct Type Creates a prism that selects a specific struct type: ```elixir defmodule Account, do: defstruct [:id, :balance] p = Prism.struct(Account) # Preview succeeds only for matching struct Prism.preview(%Account{id: 1, balance: 100}, p) #=> Just(%Account{id: 1, balance: 100}) Prism.preview(%{id: 1, balance: 100}, p) #=> Nothing (plain map, not Account struct) # Review promotes map to struct Prism.review(%{id: 2, balance: 200}, p) #=> %Account{id: 2, balance: 200} ``` **Use case**: Modeling sum types - selecting one variant from multiple possibilities. ### `make/2` - Custom Prisms Creates a prism from preview and review functions: ```elixir alias Funx.Monad.Maybe # Prism for positive numbers stored as strings positive_str = Prism.make( fn str when is_binary(str) -> case Integer.parse(str) do {n, ""} when n > 0 -> Maybe.just(n) _ -> Maybe.nothing() end _ -> Maybe.nothing() end, fn n -> Integer.to_string(n) end ) Prism.preview("42", positive_str) #=> Just(42) Prism.preview("-5", positive_str) #=> Nothing Prism.review(100, positive_str) #=> "100" ``` **IMPORTANT**: You are responsible for ensuring preview/review obey prism laws. They must round-trip correctly. ## Core Operations ### `preview/2` - Extract Focus Attempts to extract the focused value, returning Maybe: ```elixir data = %{user: %{profile: %{email: "alice@example.com"}}} p = Prism.path([:user, :profile, :email]) Prism.preview(data, p) #=> Just("alice@example.com") # Fails when path incomplete incomplete = %{user: %{}} Prism.preview(incomplete, p) #=> Nothing ``` **Returns**: `Just(value)` on success, `Nothing` on failure ### `review/2` - Reconstruct Structure Reconstructs the minimal structure needed to contain the focus: ```elixir p = Prism.path([{User, :profile}, {Profile, :age}]) Prism.review(30, p) #=> %User{ # profile: %Profile{age: 30, email: nil}, # name: nil # } ``` **Important**: - Review constructs the *minimal* structure. Other fields get default values. Original data is lost. - **Cannot review with `nil`**: Raises `ArgumentError` because `Just(nil)` is invalid in the Maybe monad, which would violate prism laws. ## Composition ### `compose/2` - Compose Two Prisms Composes two prisms sequentially: ```elixir # Build composed prism user_prism = Prism.struct(User) name_prism = Prism.key(:name) user_name = Prism.compose(user_prism, name_prism) # Preview: outer first, then inner Prism.preview(%User{name: "Alice"}, user_name) #=> Just("Alice") # Review: inner first, then outer (reversed!) Prism.review("Bob", user_name) #=> %User{name: "Bob", profile: nil} ``` **Preview direction**: left to right (outer → inner) **Review direction**: right to left (inner → outer) ### `compose/1` - Compose Multiple Prisms Composes a list of prisms into a single prism: ```elixir # Compose multiple key prisms for nested access prisms = [ Prism.key(:user), Prism.key(:profile), Prism.key(:age) ] composed = Prism.compose(prisms) data = %{user: %{profile: %{age: 25, name: "Alice"}}} Prism.preview(data, composed) #=> Just(25) Prism.preview(%{}, composed) #=> Nothing (missing keys) ``` **Equivalent to**: `compose(compose(p1, p2), p3)` **Note**: `path/1` is syntactic sugar for `compose/1` with key/struct prisms ## Working with Maybe Results Prism operations return Maybe, so use Maybe operations to work with results: ```elixir import Funx.Monad alias Funx.Monad.Maybe user = %{profile: %{email: "alice@example.com"}} p = Prism.path([:profile, :email]) # Extract with default user |> Prism.preview(p) |> Maybe.get_or_else("no-email@example.com") #=> "alice@example.com" # Transform if present user |> Prism.preview(p) |> map(&String.upcase/1) #=> Just("ALICE@EXAMPLE.COM") # Chain with other Maybe operations user |> Prism.preview(p) |> bind(&validate_email/1) # returns Maybe ``` ## Common Patterns ### Optional Field Access ```elixir # Safe access to potentially missing fields config = %{database: %{timeout: 5000}} timeout_prism = Prism.path([:database, :timeout]) Prism.preview(config, timeout_prism) |> Maybe.get_or_else(3000) #=> 5000 ``` ### Struct Type Selection ```elixir # Select specific struct type from mixed data defmodule CreditCard, do: defstruct [:number] defmodule BankAccount, do: defstruct [:routing] cc_prism = Prism.struct(CreditCard) payment = %CreditCard{number: "1234"} Prism.preview(payment, cc_prism) #=> Just(%CreditCard{number: "1234"}) ``` ### Nested Struct Access with Type Safety ```elixir # Build typed paths for reconstruction defmodule Address, do: defstruct [:street, :city] defmodule Company, do: defstruct [:name, :address] city_prism = Prism.path([{Company, :address}, {Address, :city}]) # Reconstruct with proper struct types Prism.review("San Francisco", city_prism) #=> %Company{ # name: nil, # address: %Address{street: nil, city: "San Francisco"} # } ``` ## Anti-Patterns **❌ Don't review with nil:** ```elixir # BAD: Trying to review with nil p = Prism.key(:name) Prism.review(nil, p) # Raises: ArgumentError - Cannot review with nil # GOOD: Use a non-nil value Prism.review("Alice", p) #=> %{name: "Alice"} ``` **❌ Don't use invalid struct fields:** ```elixir # BAD: :nonexistent is not a field in User p = Prism.path([{User, :nonexistent}]) # Violates prism laws - Kernel.struct drops invalid keys ``` **❌ Don't expect review to preserve original data:** ```elixir # BAD: Expecting profile to be preserved user = %User{name: "Alice", profile: %Profile{age: 30}} p = Prism.path([{User, :name}]) Prism.review("Bob", p) # Returns: %User{name: "Bob", profile: nil} # Profile is lost - this is correct prism behavior! ``` **❌ Don't use Prism for total access:** ```elixir # BAD: Use Lens instead when field should always exist required_field_prism = Prism.key(:id) # If :id should always be present, use Lens.key(:id) instead ``` **✅ Do use valid struct fields:** ```elixir # GOOD: :name is a field in User p = Prism.path([{User, :name}]) ``` **✅ Do understand review constructs minimal structure:** ```elixir # GOOD: Expecting only the focus to be preserved p = Prism.path([{User, :name}]) result = Prism.review("Bob", p) # result = %User{name: "Bob", profile: nil} # This is correct - review only preserves the focus ``` **✅ Do use Prism for partial access:** ```elixir # GOOD: Prism for optional fields optional_email = Prism.path([:user, :email]) Prism.preview(data, optional_email) # Returns Maybe - perfect for optional data ``` ## Implementation Note The `path/1` function is syntactic sugar for `compose/1`: ```elixir # These are equivalent: Prism.path([{User, :profile}, {Profile, :age}]) Prism.compose([ Prism.struct(User), Prism.key(:profile), Prism.struct(Profile), Prism.key(:age) ]) ``` This compositionality ensures prism laws are preserved through composition.