Add TransformedNamesComparison.CamelSnakeCaseEquality (closes scalalandio#831)

Adds a built-in snake_case <-> camelCase name-matching strategy so users
no longer have to hand-roll one, plus tests and documentation.

Also fixes assorted typos in cookbook.md/supported-transformations.md and
corrects the indentation of the `!!! example` code fences in the Cats
section (3 -> 4 spaces).

The cookbook.md changes no longer de-indent the `Scala 2`/`Scala 3` labels
inside the first `!!! example` admonition, which would have broken its
rendering.

Co-authored-by: Mateusz Kubuszok <mateusz.kubuszok@gmail.com>

Author: ajozwik

chimney/src/main/scala/io/scalaland/chimney/dsl/TransformedNamesComparison.scala

@@ -1,6 +1,6 @@
 package io.scalaland.chimney.dsl
 
-/** Provides a way of customizing how fields/subtypes shoud get matched betwen source value and target value.
+/** Provides a way of customizing how fields/subtypes should get matched between source value and target value.
   *
   * @see
   *   [[https://chimney.readthedocs.io/supported-transformations/#defining-custom-name-matching-predicate]] for more
@@ -49,6 +49,33 @@ object TransformedNamesComparison {
     def namesMatch(fromName: String, toName: String): Boolean = fromName.equalsIgnoreCase(toName)
   }
 
+  case object CamelSnakeCaseEquality extends TransformedNamesComparison {
+
+    private def snakeToCamel(snake: String): (String, Boolean) =
+      snake.split('_') match {
+        case Array(part) => (part, false)
+        case parts       =>
+          val camel = parts
+            .filter(_.nonEmpty) // Remove empty parts from consecutive underscores
+            .zipWithIndex
+            .map { case (part, idx) =>
+              if (idx == 0) part.toLowerCase
+              else part.toLowerCase.capitalize
+            }
+            .mkString
+          (camel, true)
+      }
+
+    def namesMatch(fromName: String, toName: String): Boolean = {
+      val (from, fromWasCamelCase) = snakeToCamel(fromName)
+      val (to, toWasCamelCase) = snakeToCamel(toName)
+      if (fromWasCamelCase == toWasCamelCase)
+        fromName == toName
+      else
+        from == to
+    }
+  }
+
   type FieldDefault = BeanAware.type
   val FieldDefault: FieldDefault = BeanAware
 

chimney/src/test/scala/io/scalaland/chimney/IssuesSpec.scala

@@ -912,4 +912,24 @@ class IssuesSpec extends ChimneySpec {
         Some(None)
     }
   }
+
+  test("fix issue #831") {
+    case class UserDAO(userId: Int, createdAt: String)
+    case class UserDTO(user_id: Int, created_at: String)
+    val userId = 123
+    val createdAt = "2024-12-03T12:00:00"
+    UserDAO(userId, createdAt)
+      .into[UserDTO]
+      .enableCustomFieldNameComparison(
+        TransformedNamesComparison.CamelSnakeCaseEquality
+      )
+      .transform ==> UserDTO(userId, createdAt)
+
+    UserDTO(userId, createdAt)
+      .into[UserDAO]
+      .enableCustomFieldNameComparison(
+        TransformedNamesComparison.CamelSnakeCaseEquality
+      )
+      .transform ==> UserDAO(userId, createdAt)
+  }
 }

chimney/src/test/scala/io/scalaland/chimney/TransformedNamesComparisonSpec.scala

@@ -79,4 +79,35 @@ class TransformedNamesComparisonSpec extends ChimneySpec {
       TransformedNamesComparison.CaseInsensitiveEquality.namesMatch("SOME_FIELD", "someField") ==> false
     }
   }
+
+  group("TransformedNamesComparison.CamelSnakeCaseEquality") {
+
+    def namesMatches(from: String, to: String): Boolean =
+      TransformedNamesComparison.CamelSnakeCaseEquality.namesMatch(
+        from,
+        to
+      ) && TransformedNamesComparison.CamelSnakeCaseEquality.namesMatch(to, from)
+
+    test("should match identical names") {
+      TransformedNamesComparison.CamelSnakeCaseEquality.namesMatch("_", "_") ==> true
+      TransformedNamesComparison.CamelSnakeCaseEquality.namesMatch("someField", "someField") ==> true
+    }
+
+    test("should match conversion") {
+      namesMatches("some_Field", "someField") ==> true
+      namesMatches("some_field", "someField") ==> true
+      namesMatches("some_field_123", "someField123") ==> true
+      namesMatches("some__field", "someField") ==> true
+      namesMatches("_some__field", "someField") ==> true
+      namesMatches("SOME_FIELD", "someField") ==> true
+    }
+
+    test("should not match conversion") {
+      TransformedNamesComparison.CamelSnakeCaseEquality.namesMatch("_", "__") ==> false
+      TransformedNamesComparison.CamelSnakeCaseEquality.namesMatch("somefield", "some_field") ==> false
+      TransformedNamesComparison.CamelSnakeCaseEquality.namesMatch("some_field", "some_Field") ==> false
+      TransformedNamesComparison.CamelSnakeCaseEquality.namesMatch("someField", "somefield") ==> false
+    }
+
+  }
 }

docs/docs/cookbook.md

@@ -233,9 +233,9 @@ Similarly `Patcher` has `.withPatchedValueFlag(pathFromPatchedValue)`:
 
 ## Checking for unused source fields/unmatched target subtypes
 
-While most of the time Chimney is picked for generating mapping between 2 data types wit as little hassle as possible,
+While most of the time Chimney is picked for generating mapping between 2 data types with as little hassle as possible,
 some people use type mapping tools to express mapping as a declarative description of the transformation. As a Part of
-that requirement is making it explicit, that some field in the source value was dropped, or that matching between 2
+that requirement is making it explicit that some field in the source value was dropped, or that matching between 2
 `sealed` hierarchies didn't use one target subtype.
 
 These can be enabled with `UnusedFieldPolicy`:
@@ -302,7 +302,7 @@ These can be enabled with `UnusedFieldPolicy`:
 
 and `UnmatchedSubtypePolicy`:
 
-!!! example "Subptype has to be explicitly ignored to compile"
+!!! example "Subtype has to be explicitly ignored to compile"
 
     ```scala
     //> using dep io.scalaland::chimney::{{ chimney_version() }}
@@ -500,7 +500,7 @@ Since Chimney 1.6.0 we are able to [scope the flag to a particular field](#const
 
 If the particular flag we want to use in limited scope is `.enableDefaultValues`, we might also consider
 [`.enableDefaultValueOfType[A]`](supported-transformations.md#allowing-fallback-to-the-constructors-default-values)
-available since Chimney 1.2.0 (but scoped flag would work as well!).
+available since Chimney 1.2.0 (but a scoped flag would work as well!).
 
 !!! example "Enabling default values only for 1 type"
 
@@ -664,7 +664,7 @@ Many users are not aware that Chimney can transform one Scala collection into an
     // List(Bar(a = 10))
     ```
 
-even though transforming all values of a collection (and even the type of a collection!) was supported since Chimney 0.2.0:
+even though transforming all values of a collection (and even the type of collection!) was supported since Chimney 0.2.0:
 
 !!! example
 
@@ -1327,7 +1327,7 @@ collection), then you can:
 
 !!! example "Converting from Cats collections"
 
-   ```scala
+    ```scala
     //> using dep org.typelevel::cats-core::{{ libraries.cats }}
     //> using dep io.scalaland::chimney-cats::{{ chimney_version() }}
     //> using dep com.lihaoyi::pprint::{{ libraries.pprint }}
@@ -1403,7 +1403,7 @@ collection), then you can:
 
 !!! example "Converting between Cats collections of the same type"
 
-   ```scala
+    ```scala
     //> using dep org.typelevel::cats-core::{{ libraries.cats }}
     //> using dep io.scalaland::chimney-cats::{{ chimney_version() }}
     //> using dep com.lihaoyi::pprint::{{ libraries.pprint }}
@@ -1435,7 +1435,7 @@ collection), then you can:
 
 !!! example "Converting using implicit ~> (FunctionK)"
 
-   ```scala
+    ```scala
     //> using dep org.typelevel::cats-core::{{ libraries.cats }}
     //> using dep io.scalaland::chimney-cats::{{ chimney_version() }}
     //> using dep com.lihaoyi::pprint::{{ libraries.pprint }}

docs/docs/supported-transformations.md

@@ -6225,8 +6225,10 @@ Arguments taken by both `.enableCustomFieldNameComparison` and `.enableCustomSub
 
  - `TransformedNamesComparison.CaseInsensitiveEquality` - 2 names are considered equal if `equalsIgnoreCase` returns
   `true`
+ - `TransformedNamesComparison.CamelSnakeCaseEquality` - 2 names are considered equal if they are identical `String`s OR if they are
+   identical after you convert them from snake to camel case (e.g. `snake_case` -> `snakeCase`, `camelCase` -> `camelCase`)
 
-However, these 3 do not exhaust all possible comparisons and you might need to provide one yourself. 
+However, these 4 do not exhaust all possible comparisons, and you might need to provide one yourself. 
 
 !!! warning