optics-dev/Monocle

Monocle is a functional optics library for Scala that provides type-safe, composable lenses, prisms, isos, and traversals for navigating and transforming immutable data structures. It supports Scala 2 and 3 across JVM, JavaScript, and Native platforms, featuring a modern Focus DSL for ergonomic code generation and extensive integration with standard libraries and Cats data types. The system includes comprehensive law-based testing, performance benchmarks, and platform-specific utilities to ensure correctness and reliability.

13 changes.

The project rebranded from Lens to Monocle and established community standards while migrating its build infrastructure to Scala 3 and Docusaurus. Core optics were refactored to introduce a unified hierarchy and prepare for the Scala 3 Focus DSL, accompanied by the deprecation of legacy modules like State and specific collection lenses. Comprehensive test coverage was added for new features, including refined type integration, alongside formal property-based laws and performance benchmarks.

10 changes.

The project reorganized its public API by introducing aggregator objects and deprecating legacy typeclasses to streamline imports for version 3.0.0. This period also focused on expanding standard library optics for Cats data structures and adding comprehensive law-based test suites to ensure correctness across core, function, and standard packages.

16 changes.

This period focused on introducing the Scala 3-specific Focus macro API, enabling ergonomic optics creation through lambda syntax and supporting keywords like 'as', 'each', and 'index'. The work involved implementing corresponding macro generators for Scala 2 and 3, deprecating older unsafe and generic optic utilities, and adding comprehensive test coverage for the new DSL and platform-specific targets.

This change introduces a new \refined\ module that provides Monocle optics (Prisms and At instances) for types validated by the \eu.timepit.refined\ library. Users can now use \lowerCase\ and \upperCase\ Prisms for character refinement, \startsWith\ and \endsWith\ Prisms for string refinement, and \At\ instances to access individual bits in Byte, Char, Int, and Long values constrained by bit-width intervals. The module includes internal support for bitwise operations and comprehensive property-based tests for these new capabilities.

refined · high confidence

The library now supports the 'as' keyword within the Focus DSL for Scala 3 users. This change introduces the parser and code generator for the 'as' feature, allowing users to explicitly cast or view a focus target as a subtype (e.g., \focus(x).as\[SubType\]\). The implementation validates that the target type is a subtype of the source type at compile time, providing a clear error if an invalid downcast is attempted.

core/shared/src/main/scala-3/monocle/internal/focus/features/as · high confidence

A new platform-specific optic for the JVM target allows converting a String to a java.net.URL using a Prism. This addition provides a safe, optional conversion mechanism for URL parsing within the core library's standard optics on JVM platforms.

core/jvm · high confidence

The library now includes Scala 3-specific macro generators and parsers for the \at\, \each\, \index\, \some\, and \withDefault\ focus keywords. This enables users to utilize these specific navigation and transformation operations within the focus DSL when compiling with Scala 3.

(repo-wide) · high confidence

A new \PlatformSpecificStringOptics\ trait has been introduced in the \core/js-native\ module to provide string-related optics tailored for the Scala Native platform, supporting cross-build compatibility.

core/js-native · high confidence

The library now includes internal utilities to safely cast values based on type bounds and to combine optional values using first/last semantics. A new \Bounded\ trait and its instances for primitive types (Boolean, Byte, Char, Int) enable safe casting via \orderingBoundedSafeCast\, which validates that a source value falls within the target type's min/max range before casting. Additionally, \Monoids\ provides \firstOption\ and \lastOption\ monoids for \Option\[A\]\, allowing users to combine optional values by preserving either the first or last non-empty value, along with \any\ and \all\ monoids for Boolean conjunction/disjunction.

core/shared/src/main/scala/monocle/internal · high confidence

Adds a new \Focus\ macro API for Scala 3, enabling users to create lenses, prisms, and other optics using simple lambda syntax (e.g., \Focus\Address\\) and compose them with \.andThen\ or the new \.refocus\ extension. This change introduces the \Focus\ object, associated syntax traits (\AppliedFocusSyntax\, \ComposedFocusSyntax\), and the underlying macro implementation (\FocusImpl\) which parses lambda structures to generate type-safe optic code, along with improved error messages for macro failures.

core/shared/src/main/scala-3 · high confidence

This change introduces the Scala 2-specific macro implementations for monocle's core optics. It adds \GenLens\ for generating lenses from case class fields, \GenIso\ for creating isomorphisms between case classes and their fields (or \Unit\), and \GenPrism\ for subtyping checks. It also includes the \@Lenses\ and \@PLenses\ macro annotations that automatically generate lens definitions for case classes, along with the necessary syntax traits (\AppliedFocusSyntax\, \MacroSyntax\) to enable fluent API usage like \focus\ and \refocus\ on the Scala 2 platform.

macro/src/main/scala-2 · high confidence

The Focus macro now supports selecting individual fields from case classes, single-field case classes, and Scala 3 named tuples. For standard case classes, it generates a Lens to get and set the field. For single-field case classes, it generates an Iso, allowing the value to be treated as the case class itself. For named tuples, it generates a Lens for multi-element tuples and an Iso for single-element tuples, enabling direct access to fields by name.

core/shared/src/main/scala-3/monocle/internal/focus/features/selectfield · high confidence

The Monocle core library now exposes convenient type aliases in the main package for standard optics (such as Lens, Prism, Iso, Optional, Traversal, and Setter) and their applied syntax counterparts (AppliedLens, AppliedPrism, etc.). This change aligns the public API with standard optics naming conventions, allowing users to reference these types more directly without needing to import specific sub-packages.

core/shared/src/main/scala/monocle · high confidence

The \monocle.generic\ module for Scala 2 now exposes deprecated (since 3.0.0-M1) utilities for working with generic representations, including HList operations (such as \hListAt\, \toHList\, \fromHList\, and field accessors), product and tuple transformations (like \productToTuple\ and \tupleReverse\), and coproduct isomorphisms (such as \coProductPrism\ and conversions to \Either\). These changes, implemented in \All.scala\, \CoProduct.scala\, \Generic.scala\, \HList.scala\, \Product.scala\, and \TupleN.scala\, are accompanied by comprehensive property-based tests in \CoproductSpec\, \HListSpec\, and \ProductSpec\ to verify the correctness of these generic optics.

generic · high confidence

The unsafe module now includes deprecated MapTraversal and UnsafeSelect utilities. MapTraversal provides an Iso and Traversal for Map key-value pairs, along with a FilterIndex instance, while UnsafeSelect offers a Prism for filtering. Both are marked for removal in favor of the safer optic.filter(predicate) API.

unsafe · high confidence

The law discipline tests for the legacy collection functions Cons, Cons1, Empty, Possible, Reverse, and Snoc are now marked as deprecated (since 3.0.0-M1) with no replacement, signaling that these specific lens implementations are being phased out. The test suites for At, Each, FilterIndex, and Index remain active and unchanged, ensuring that current, supported collection traversal and access laws continue to be validated.

law/src/main/scala/monocle/law/discipline/function · high confidence

The \monocle.function\ package has been reorganized to prepare for version 3.0.0. Several legacy typeclasses—\Cons\, \Cons1\, \Curry\, \Empty\, \Possible\, \Reverse\, and \Snoc\—are now deprecated with no direct replacement, while \Field1\ through \Field6\ are deprecated in favor of using \Focus\ with tuple selectors. To simplify imports and usage, a new \All\ object has been introduced that aggregates all function optics (including \At\, \Each\, \Index\, \FilterIndex\, \Plated\, and the remaining non-deprecated fields) into a single mixin, allowing users to import all available functions via \import monocle.function.All.\_\.

core/shared/src/main/scala/monocle/function · high confidence

The optic traits (Fold, Getter, Lens, Optional, Prism, Iso) have been restructured to establish a clear inheritance hierarchy where all optics extend Fold, and composition is standardized via the \andThen\ method, deprecating older symbolic operators. This change also introduces the internal Scala 3 \FocusBase\ macro infrastructure, providing the parser and keyword handling logic required for the new \Focus\ DSL, while adding benchmark models to support performance testing of these core structures.

repository · high confidence

The project has rebranded from 'Lens' to 'Monocle', updating the README to display the new logo and direct users to the official documentation website at optics.dev. A Code of Conduct and a contributor Process document have been added to establish community standards and release procedures. Additionally, the build environment is now configured with a Scala Steward configuration for automated dependency updates, a .scalafmt.conf file enforcing specific code formatting rules (including Scala 2.13 dialect support), and a .gitignore file that excludes IDE and Docusaurus build artifacts.

(repo-wide) · high confidence

The Scala 3-specific macro implementations for \GenIso\, \GenLens\, and \GenPrism\ have been updated to align with the library's migration to the \Focus\ API. \GenIso\ now uses \Mirror\ types to generate \Iso\ instances, with \fields\ delegating to \IsoFields\ for multi-field cases, while \GenLens\ and \GenPrism\ are simplified to act as thin wrappers around \Focus\, ensuring consistent behavior with the newer API surface.

macro/src/main/scala-3 · high confidence

The \monocle.std\ package has been reorganized into a single \All.scala\ aggregator that exposes a comprehensive set of standard library optics. This change introduces new typeclass instances and optics for Cats data structures (Chain, NonEmptyChain, NonEmptyList, NonEmptyVector, These, Validated) alongside existing Scala standard types (BigDecimal, BigInt, Byte, Char, Double, Either, Function, Int, List, Long, Map, Option, String, Try, Tuple1). Notable additions include prisms for parsing strings to numeric types and UUIDs/URIs, an \withDefault\ iso for Options, and specific logic to ensure string-to-numeric prisms respect Prism laws by rejecting invalid formats like negative zero.

core/shared/src/main/scala/monocle/std · high confidence

The \monocle.state\ module, which provided syntax to transform Monocle optics (such as Lenses, Optionals, Setters, and Traversals) into Cats \State\ actions, has been deprecated with no replacement. All syntax traits and extension methods in this module (including \StateLensSyntax\, \StateOptionalSyntax\, \StateGetterSyntax\, \StateSetterSyntax\, \StateTraversalSyntax\, and \ReaderGetterSyntax\) are now marked as deprecated since version 3.0.0-M1, signaling that users should migrate away from these state-based operations.

state · high confidence

The logo directory now includes new editable vector source files (Adobe Illustrator .ai) and high-resolution PDF exports for both screen and print use. These assets replace previous versions, providing updated visual branding materials for the website and documentation.

logo · high confidence

The documentation site has been rebuilt using Docusaurus, replacing the previous microsite infrastructure. This change introduces a simplified landing page that highlights the new 'Focus' API for accessing and transforming immutable data, alongside updated installation instructions for Scala 2.13 and 3. The site now features a new visual identity with updated SVG branding assets, a custom footer component, and a reorganized sidebar structure that groups content into 'Optics' and 'Documentation' categories.

website · high confidence

Add JMH benchmarks for Iso, Lens, Prism, and Traversal; Added JVM-specific tests for URL Prisms; Added Scala 2-specific test suite for Monocle optics and generic instances; Added Scala 3 tests for Focus DSL and optic composition; Added Scala 3 tests for named tuple focus operations; Added comprehensive law-based tests for standard library optics; Added comprehensive test suite for Monocle optics; Added example tests for HTTP request and JSON AST manipulation; Added example tests for Monocle function optics; Added example tests for State module syntax; Added platform-specific test instances for Scala Native; Added test coverage for macro-generated optics and syntax features; Added test coverage for monocle function typeclasses; Added tests for UnsafeSelect; Added tests for std Option, These, and Validated optics; Added tests for symbolic optics composition syntax; New discipline test suites for Monocle optics.

The build system has been updated to use Scala 3.9.0 and Scala 2.13.18, alongside upgrading the core Cats library dependency to version 2.13.0. The project now officially supports cross-compilation for JVM, JavaScript, and Native platforms using these versions. Additionally, the documentation infrastructure has migrated to Docusaurus, introducing a new \website\ directory with a \package.json\ that pins Docusaurus version 1.6.2 for generating and publishing the site.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 45 → 57 (+12.7)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 99 (-1.1)
• Architecture 100 (new)
• Maturity 44 → 41 (-3.0)
• Readiness 27 → 58 (+31.0)
• Security 73 → 74 (+1.4)

• Dimension evaluation failed
• LLM evaluation failed
• No artifact signing
• No automated tests
• No exposed public API
• No tests found
• Rotate the exposed credentials — git history can't be un-committed
• Scanner failed to run — not a clean result
• Test reliability not included

• Duplicated block (12 lines × 2) (bench/src/main/scala/monocle/bench/MonocleLensBench.scala)
• Duplicated block (5 lines × 2) (core/shared/src/main/scala-3/monocle/internal/focus/features/selectfield/SelectFieldGenerator.scala)
• Duplicated block (6 lines × 3) (bench/src/main/scala/monocle/bench/StdLensBench.scala)
• Duplicated block (7 lines × 2) (core/shared/src/main/scala/monocle/function/FilterIndex.scala)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 17 more

• 9 commits — 9 feature/other, 0 fixes

• (root) — 3 commits
• project/plugins.sbt — 3 commits
• project/build.properties — 2 commits
• test/shared — 1 commit

• change: Avoid infix syntax
• change: Move Scala 3 to 3.9.0 LTS (#1623)
• change: Pin docusaurusVersion to V1 so the website deploy works again (#1624)
• change: Set tlBaseVersion to 3.4 (#1622)
• change: Update sbt, scripted-plugin to 1.12.15
• change: Update sbt, scripted-plugin to 1.13.0
• change: Update sbt-buildinfo to 0.13.2
• change: Update sbt-mdoc to 2.9.2
• change: Update sbt-scala-native-crossproject, ... to 1.4.0

• Containers 0 added · 0 removed · contexts 1 added · 0 removed · edges 0 added · 0 removed

• repository

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

optics-dev/Monocle was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.