dev.constructive.eo

Gate typeclasses keyed by carrier: Accessor (total read), PartialAccessor (read that may miss), ReverseAccessor (build back from the write side). Signatures that take an Optic[…, F] plus one of these on F must list the optic '''first''' in the same using clause — left-to-right resolution pins F before the gate is searched.

Cross-representation optics bridging native Scala types and their Apache Avro on-the-wire form.

The entry point is AvroPrism.codecPrism (read-aloud API parallel to dev.constructive.eo.circe.codecPrism):

 import dev.constructive.eo.avro.{AvroCodec, codecPrism}
 import hearth.kindlings.avroderivation.AvroEncoder.derived
 import hearth.kindlings.avroderivation.AvroDecoder.derived
 import hearth.kindlings.avroderivation.AvroSchemaFor.derived

 case class Person(name: String, age: Int)
 // `given AvroCodec[Person]` falls out automatically from kindlings'
 // derived `AvroEncoder[Person]`, `AvroDecoder[Person]`, `AvroSchemaFor[Person]`.

 val personPrism: AvroPrism[Person]   = codecPrism[Person]
 val namePrism:   AvroPrism[String]   = personPrism.field(_.name)
 namePrism.modify(_.toUpperCase)(payloadBytes)
 // → the same Array[Byte] payload, with `name` upper-cased in
 //   place — no Person (nor any root record) ever materialised.
 namePrism.record.modify(_.toUpperCase)(record)
 // → the IndexedRecord-carried face, with Ior diagnostics.

The default carrier is the binary wire form itself (Array[Byte], mirroring dev.constructive.eo.jsoniter.JsoniterPrism); the record-carried face behind .record follows dev.constructive.eo.circe's architecture decisions on Json: IndexedRecord plays the role of Json, AvroCodec plays the role of (io.circe.Encoder[A], io.circe.Decoder[A]), and AvroFailure plays the role of JsonFailure.

'''Carrier note.''' Both AvroRecordPrism and eo-circe's JsonPrism are Affine-carried — lawful Optionals whose composed / upcast writes preserve siblings. A drilled focus is an Optional, so the carrier widens to Affine (via the Composer on composition) rather than pretending to be a Prism; the two record faces stay in step.

'''Deliberate duplication.''' PathStep is duplicated, not shared with eo-circe — the UnionBranch case is Avro-only and forcing it into eo-circe would pollute that module. See PathStep's class doc.

Cross-representation optics bridging native Scala types and their circe-serialised form.

The entry point is JsonPrism.apply (aliased as codecPrism for the read-aloud API):

 val personPrism: JsonPrism[Person] = codecPrism[Person]
 val streetPrism: JsonPrism[String] =
   personPrism.field(_.address).field(_.street)
 streetPrism.modify(_.toUpperCase)(personJson)
 // → Ior.Right of the same Json, with .address.street upper-cased —
 //   no Person ever materialised.

From a root prism the whole surface lights up: .field (and its Dynamic sugar) drills deeper, .at(i) indexes into an array, .each widens to a JsonTraversal over every element, .fields(_.a, _.b) focuses a bundle of case fields as a Scala 3 NamedTuple. Independent of the path-walkers, platedJson makes Json a recursive self-traversal for whole-document rewrites.

Every operation comes in two tiers: the default methods return Ior[Chain[JsonFailure], _] — Ior.Both is partial success, every skip documented in the chain — and the *Unsafe siblings are the silent pass-through hot path.

Coming from circe-optics JsonPath or raw cursors: this is the compile-time-checked equivalent — codecPrism[Person].address.street ≈ root.address.street.string ≈ an hcursor.downField chain, with typed per-step codecs instead of stringly paths.

The composition seam: AssociativeFunctor powers the generic Optic.andThen (threading an inner carrier through an outer one), Composer names the carrier-pair-specific fusions, Morph re-expresses an optic over a different carrier so cross-carrier andThen can pick a direction, and ReadCompose routes read-only collapses (getter ∘ getter and friends) without building intermediate structure.

Carriers — the F[_, _] shapes an optics.Optic's to / from run through: Direct (plain focus, no leftover), Either (prism miss), Affine (miss '''or''' hit-with-context), Forget / opaque ForgetK (read-only collapse), ModifyF (effectful write), MultiFocus / opaque MultiFocusK (many foci), plus the perf substrate (PSVec and the array builders). Each carrier's companion hosts its typeclass instances, so composition resolves with no imports.

Weakened functor hierarchy for carriers that cannot honour full map: ForgetfulFunctor, ForgetfulFold, ForgetfulApplicative and ForgetfulTraverse let read-only carriers (Forget, Direct-collapsed reads) participate in the generic composition machinery by "mapping" in ways that may legally discard or refuse the function.

Auto-derivation entry points for EO optics — Scala 3 quoted macros for Lens / Prism / Plated. Scaffolds on Mateusz Kubuszok's hearth macro-commons library.

Derived setters call the primary constructor directly (new S(...), never .copy) — uniform across case classes and enum cases, but the emitted call carries no outer accessor, so derive only for '''top-level''' ADTs, not types nested inside a class.

Byte-level JSON optics over jsoniter-scala: JsoniterPrism and JsoniterTraversal focus a JSONPath '''directly in the encoded byte buffer''' — scanning for the span, decoding only the focused slice, and splicing writes back — so reads and writes never materialise the full document AST.

The typed entry point is JsoniterPrism[A] — the root Prism[Array[Byte], A]:

 val streetP: JsoniterPrism[String] =
   JsoniterPrism[Person].field(_.address).field(_.street)
 streetP.modify(_.toUpperCase)(personBytes)
 // → Array[Byte] with .address.street upper-cased —
 //   no Person ever materialised, only the String leaf decoded.

Law definitions for every optic family — one trait per shape (LensLaws, PrismLaws, IsoLaws, OptionalLaws, TraversalLaws, FoldLaws, GetterLaws, ModifyLaws, MultiFocusLaws, PlatedLaws, UnfoldLaws, SeamLaws, …), each method one equation. Reusable by downstream projects; the ScalaCheck/specs2 bundles live in laws.discipline, with eo-internal seam laws under laws.eo, carrier laws under laws.data and typeclass laws under laws.typeclass.

This module ships law equations and rule-sets ONLY — no Arbitrary, Cogen, or Eq instances. Your suite supplies the generators for its own S / A types (and, for SeamLaws, the structural equality — see below).

'''Codec-backed optics''' (Avro records, serialised JSON, …) are lawful only ''up to canonical re-encoding'': the family laws compare with raw == (mirroring Monocle), which a decode-then-re-encode round-trip can fail for representation-sensitive equality (e.g. Avro's schema-instance-sensitive GenericData.Record.equals) even when the values are structurally equal. Run those laws on canonical fixtures — sources round-tripped through the codec once — or on a full-cover face whose rebuild goes through the same codec instance; SeamLaws instead takes an INJECTED equality for exactly this reason. AvroPrismLawsSpec in the avro module is the worked reference.

The concrete optic zoo: Optic (the one existential base trait) and its named shapes — Lens, Prism, Iso, Optional, Traversal, Getter, Fold, AffineFold, Review, Modify, Unfold, Plated — each a thin class over a carrier from data with fused andThen overloads so hot compositions skip the generic seam. Construct and compose here; consume through the capability traits in dev.constructive.eo.

Recursion schemes as composable optics: Schemes.cata (fold), Schemes.ana (unfold) and Schemes.hylo (refold) over any type with a Plated instance — stack-safe, expressed as eo optics so they cross-compose with the rest of the library (ana(…).cross(cata(…)) '''is''' hylo).