✨ Add circe support

.github/workflows/ci.yml

@@ -76,11 +76,11 @@ jobs:
 
       - name: Make target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
-        run: mkdir -p uuid/target scuid/target core/target project/target
+        run: mkdir -p uuid/target scuid/target circe/target core/target project/target
 
       - name: Compress target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
-        run: tar cf targets.tar uuid/target scuid/target core/target project/target
+        run: tar cf targets.tar uuid/target scuid/target circe/target core/target project/target
 
       - name: Upload target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')

README.md

@@ -14,6 +14,7 @@ about it).
 libraryDependencies += "me.wojnowski" %% "humanoid" % "<version>"
 libraryDependencies += "me.wojnowski" %% "humanoid-scuid" % "<version>" // optional, for Cuid2 integration
 libraryDependencies += "me.wojnowski" %% "humanoid-uuid" % "<version>" // optional, for UUID integration
+libraryDependencies += "me.wojnowski" %% "humanoid-circe" % "<version>" // optional, for Circe codecs
 ```
 
 ### Usage
@@ -78,3 +79,13 @@ implicit val myIdGenerator: IdGenerator[MyId] = IdGenerator[F, MyId] {
   def generate: F[MyId] = ???
 }
 ```
+
+### Circe integration
+```scala
+libraryDependencies += "me.wojnowski" %% "humanoid-circe" % "<version>"
+```
+
+```scala
+import me.wojnowski.humanoid.circe.strict._  // require prefix when decoding, encode with prefix
+import me.wojnowski.humanoid.circe.relaxed._ // don't require prefix when decoding, encode with prefix
+```

build.sbt

@@ -1,5 +1,5 @@
 // https://typelevel.org/sbt-typelevel/faq.html#what-is-a-base-version-anyway
-ThisBuild / tlBaseVersion := "0.2" // your current series x.y
+ThisBuild / tlBaseVersion := "0.2"
 
 ThisBuild / organization     := "me.wojnowski"
 ThisBuild / organizationName := "Jakub Wojnowski"
@@ -58,4 +58,17 @@ lazy val scuid =
       )
     )
 
-lazy val root = tlCrossRootProject.aggregate(core, scuid, uuid)
+lazy val circe =
+  project
+    .in(file("circe"))
+    .dependsOn(core)
+    .settings(
+      name := "humanoid-circe",
+      libraryDependencies ++= Seq(
+        "io.circe"      %% "circe-core"   % "0.14.6",
+        "io.circe"      %% "circe-parser" % "0.14.6" % Test,
+        "org.scalameta" %% "munit"        % "0.7.29" % Test
+      )
+    )
+
+lazy val root = tlCrossRootProject.aggregate(core, scuid, uuid, circe)

circe/src/main/scala/me/wojnowski/humanoid/circe/CirceEncoders.scala

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2023 Jakub Wojnowski
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package me.wojnowski.humanoid.circe
+
+import io.circe.Encoder
+import io.circe.KeyEncoder
+import me.wojnowski.humanoid.HumanId
+
+trait CirceEncoders {
+
+  implicit def humanIdEncoder[P <: String, Id]: Encoder[HumanId[P, Id]] =
+    Encoder.encodeString.contramap(_.renderWithPrefix)
+
+  implicit def humanIdKeyEncoder[P <: String, Id]: KeyEncoder[HumanId[P, Id]] =
+    KeyEncoder.instance(_.renderWithPrefix)
+
+}

circe/src/main/scala/me/wojnowski/humanoid/circe/relaxed/RelaxedDecoders.scala

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2023 Jakub Wojnowski
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package me.wojnowski.humanoid.circe.relaxed
+
+import io.circe.Decoder
+import io.circe.KeyDecoder
+import me.wojnowski.humanoid.HumanId
+import me.wojnowski.humanoid.IdConverter
+
+trait RelaxedDecoders {
+  implicit def humanIdDecoder[P <: String, Id](implicit valueOfPrefix: ValueOf[P], idable: IdConverter[Id]): Decoder[HumanId[P, Id]] =
+    Decoder.decodeString.emap(HumanId.parsePrefixOptional[P, Id])
+
+  implicit def humanIdKeyDecoder[P <: String, Id](implicit valueOfPrefix: ValueOf[P], idable: IdConverter[Id]): KeyDecoder[HumanId[P, Id]] =
+    KeyDecoder.instance(HumanId.parsePrefixOptional[P, Id](_).toOption)
+}

circe/src/main/scala/me/wojnowski/humanoid/circe/relaxed/package.scala

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2023 Jakub Wojnowski
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package me.wojnowski.humanoid.circe
+
+package object relaxed extends RelaxedDecoders with CirceEncoders

circe/src/main/scala/me/wojnowski/humanoid/circe/strict/StrictDecoders.scala

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2023 Jakub Wojnowski
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package me.wojnowski.humanoid.circe.strict
+
+import io.circe.Decoder
+import io.circe.KeyDecoder
+import me.wojnowski.humanoid.HumanId
+import me.wojnowski.humanoid.IdConverter
+
+trait StrictDecoders {
+  implicit def humanIdDecoder[P <: String, Id](implicit valueOfPrefix: ValueOf[P], idable: IdConverter[Id]): Decoder[HumanId[P, Id]] =
+    Decoder.decodeString.emap(HumanId.parseRequirePrefix[P][Id])
+
+  implicit def humanIdKeyDecoder[P <: String, Id](implicit valueOfPrefix: ValueOf[P], idable: IdConverter[Id]): KeyDecoder[HumanId[P, Id]] =
+    KeyDecoder.instance(HumanId.parseRequirePrefix[P][Id](_).toOption)
+}

circe/src/main/scala/me/wojnowski/humanoid/circe/strict/package.scala

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2023 Jakub Wojnowski
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package me.wojnowski.humanoid.circe
+
+package object strict extends StrictDecoders with CirceEncoders

circe/src/test/scala/me/wojnowski/humanoid/circe/CodecTest.scala

@@ -0,0 +1,104 @@
+/*
+ * Copyright (c) 2023 Jakub Wojnowski
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package me.wojnowski.humanoid.circe
+
+import io.circe.parser.decode
+import io.circe.syntax.*
+import me.wojnowski.humanoid.HumanId
+import me.wojnowski.humanoid.HumanIdOps
+import me.wojnowski.humanoid.IdConverter
+import munit.FunSuite
+
+import CodecTest.LowercaseString
+
+class CodecTest extends FunSuite {
+
+  val rawId: LowercaseString                   = LowercaseString.fromString("idvalue").toOption.get
+  val humanId: HumanId["pfx", LowercaseString] = HumanIdOps["pfx", LowercaseString].fromId(rawId)
+  val humanIdJsonWithPrefix: String            = "\"pfx_idvalue\""
+  val humanIdJsonWithoutPrefix: String         = "\"idvalue\""
+
+  test("encoder encodes with prefix") {
+    import me.wojnowski.humanoid.circe.strict.*
+
+    val result = humanId.asJson.noSpaces
+
+    assertEquals(result, humanIdJsonWithPrefix)
+  }
+
+  test("relaxed decoder accepts ID without prefix") {
+    import me.wojnowski.humanoid.circe.relaxed.*
+
+    val result = decode[HumanId["pfx", LowercaseString]](humanIdJsonWithoutPrefix)
+
+    assertEquals(result, Right(humanId))
+  }
+
+  test("relaxed decoder accepts ID with wrong prefix if it parses as valid ID") {
+    import me.wojnowski.humanoid.circe.relaxed.*
+
+    val result   = decode[HumanId["other", String]](humanIdJsonWithPrefix)
+    val expected = Right(HumanIdOps["other", String].fromId(humanId.renderWithPrefix))
+
+    assertEquals(result, expected)
+  }
+
+  test("strict decoder accepts ID with correct prefix") {
+    import me.wojnowski.humanoid.circe.strict.*
+
+    val result = decode[HumanId["pfx", LowercaseString]](humanIdJsonWithPrefix)
+
+    assertEquals(result, Right(humanId))
+  }
+
+  test("strict decoder rejects ID with incorrect prefix") {
+    import me.wojnowski.humanoid.circe.strict.*
+
+    val result = decode[HumanId["other", String]](humanIdJsonWithPrefix)
+    assert(result.isLeft)
+  }
+
+  test("strict decoder rejects ID without prefix") {
+    import me.wojnowski.humanoid.circe.strict.*
+
+    val result = decode[HumanId["other", LowercaseString]](humanIdJsonWithoutPrefix)
+    assert(result.isLeft)
+  }
+
+}
+
+object CodecTest {
+  abstract case class LowercaseString private (value: String)
+
+  object LowercaseString {
+    def fromString(value: String): Either[String, LowercaseString] =
+      Either.cond(value.forall(_.isLower), new LowercaseString(value) {}, s"Value [$value] is not lowercase")
+
+    implicit val idConverter: IdConverter[LowercaseString] = new IdConverter[LowercaseString] {
+      override def fromString(raw: String): Either[String, LowercaseString] = LowercaseString.fromString(raw)
+
+      override def renderString(id: LowercaseString): String = id.value
+    }
+
+  }
+
+}