From 5825bbcee4a0a28339b2f9bc37948e3a8e27a724 Mon Sep 17 00:00:00 2001
From: Iltotore <rafbodaha@gmail.com>
Date: Sat, 30 Dec 2023 10:32:37 +0100
Subject: [PATCH] docs: Add documentation for uPickle module

---
 README.md                     |  1 +
 build.sc                      |  8 +++--
 docs/_docs/modules/index.md   |  1 +
 docs/_docs/modules/upickle.md | 60 +++++++++++++++++++++++++++++++++++
 docs/sidebar.yml              |  1 +
 5 files changed, 68 insertions(+), 3 deletions(-)
 create mode 100644 docs/_docs/modules/upickle.md

diff --git a/README.md b/README.md
index 5797a759..73e06f86 100644
--- a/README.md
+++ b/README.md
@@ -101,6 +101,7 @@ ivy"io.github.iltotore::iron:version"
 | iron-jsoniter   | ✔️  | ✔️ | ✔️     |
 | iron-scalacheck | ✔️  | ✔️ | ❌     |
 | iron-skunk      | ✔️  | ✔️ | ✔️     |
+| iron-upickle    | ✔️  | ✔️ | ✔️     |
 | iron-zio        | ✔️  | ✔️ | ❌     |
 | iron-zio-json   | ✔️  | ✔️ | ❌     |
 
diff --git a/build.sc b/build.sc
index 61f54f23..71e76188 100644
--- a/build.sc
+++ b/build.sc
@@ -77,7 +77,8 @@ object docs extends BaseModule {
 
   def artifactName = "iron-docs"
 
-  val modules: Seq[ScalaModule] = Seq(main, cats, circe, decline, doobie, upickle, ciris, jsoniter, scalacheck, skunk, zio, zioJson)
+  val modules: Seq[ScalaModule] =
+    Seq(main, cats, circe, decline, doobie, upickle, ciris, jsoniter, scalacheck, skunk, upickle, zio, zioJson)
 
   def docSources = T.sources {
     T.traverse(modules)(_.docSources)().flatten
@@ -130,7 +131,7 @@ object docs extends BaseModule {
     else "main"
   }
 
-  def externalMappings = Map(
+  def externalMappings = Seq(
     ".*cats.*" -> ("scaladoc3", "https://javadoc.io/doc/org.typelevel/cats-docs_3/latest/"),
     ".*io.circe.*" -> ("scaladoc2", "https://circe.github.io/circe/api/"),
     ".*ciris.*" -> ("scaladoc2", "https://cir.is/api/"),
@@ -138,8 +139,9 @@ object docs extends BaseModule {
     ".*doobie.*" -> ("scaladoc3", "https://www.javadoc.io/doc/org.tpolecat/doobie-core_3/latest/"),
     ".*com.github.plokhotnyuk.jsoniter_scala.core.*" -> ("scaladoc3", "https://www.javadoc.io/doc/com.github.plokhotnyuk.jsoniter-scala/jsoniter-scala-core_3/latest/"),
     ".*org.scalacheck.*" -> ("scaladoc3", "https://javadoc.io/doc/org.scalacheck/scalacheck_3/latest/"),
-    ".*org.scalacheck.*" -> ("scaladoc3", "https://javadoc.io/doc/org.scalacheck/scalacheck_3/latest/"),
     ".*skunk.*" -> ("scaladoc3", "https://javadoc.io/doc/org.tpolecat/skunk-docs_3/latest/"),
+    ".*upickle.core.*" -> ("scaladoc3", "https://javadoc.io/doc/com.lihaoyi/upickle-core_3/latest/"),
+    ".*upickle[^\\.core].*" -> ("scaladoc3", "https://javadoc.io/doc/com.lihaoyi/upickle_3/latest/"),
     ".*zio.json.*" -> ("scaladoc3", "https://javadoc.io/doc/dev.zio/zio-json_3/latest/"),
     ".*zio.prelude.*" -> ("scaladoc3", "https://javadoc.io/doc/dev.zio/zio-prelude-docs_3/latest/"),
     ".*zio[^\\.json].*" -> ("scaladoc3", "https://javadoc.io/doc/dev.zio/zio_3/latest/")
diff --git a/docs/_docs/modules/index.md b/docs/_docs/modules/index.md
index b7c71b5b..6d63e845 100644
--- a/docs/_docs/modules/index.md
+++ b/docs/_docs/modules/index.md
@@ -16,6 +16,7 @@ These modules are mostly "support"/"interoperability" modules to provide out of
 - [Doobie](doobie.md): Typeclass instances for refinement types.
 - [Jsoniter](jsoniter.md): Typeclass instances for refinement types.
 - [ScalaCheck](scalacheck.md): Typeclass instances for refinement types.
+- [uPickle](upickle.md): Typeclass instances for refinement types.
 - [ZIO](zio.md): Accumulative refinement method.
 - [ZIO-Json](zio-json.md): Typeclass instances for refinement types.
 
diff --git a/docs/_docs/modules/upickle.md b/docs/_docs/modules/upickle.md
new file mode 100644
index 00000000..b20587eb
--- /dev/null
+++ b/docs/_docs/modules/upickle.md
@@ -0,0 +1,60 @@
+---
+title: "uPickle Support"
+---
+
+# uPickle Support
+
+This module provides refined types Writer/Reader instances for [uPickle](https://com-lihaoyi.github.io/upickle/).
+
+## Dependency
+
+SBT:
+
+```scala 
+libraryDependencies += "io.github.iltotore" %% "iron-upickle" % "version"
+```
+
+Mill:
+
+```scala 
+ivy"io.github.iltotore::iron-upickle:version"
+```
+
+### Following examples' dependencies
+
+SBT:
+
+```scala 
+libraryDependencies += "com.lihaoyi" %% "upickle" % "3.1.3"
+```
+
+Mill:
+
+```scala 
+ivy"com.lihaoyi::upickle:3.1.3"
+```
+
+## Writer/Reader instances
+
+You can serialize and deserialize refined values using Iron's Writer/Reader instances for refined types.
+
+```scala 
+import upickle.default._
+import io.github.iltotore.iron.*
+import io.github.iltotore.iron.constraint.all.*
+import io.github.iltotore.iron.upickle.given
+
+opaque type Username = String :| Alphanumeric
+object Username extends RefinedTypeOps[String, Alphanumeric, Username]
+
+opaque type Age = Int :| Positive
+object Age extends RefinedTypeOps[Int, Positive, Age]
+
+case class User(name: Username, age: Age) derives ReadWriter
+
+write(User("Iltotore", 19)) //{"name":"Iltotore","age":19}
+
+read[User]("""{"name":"Iltotore","age":19}""") //User("Iltotore", 19)
+read[User]("""{"name":"Iltotore","age":-19}""") //AbortException: Should be strictly positive
+read[User]("""{"name":"Il_totore","age":19}""") //AbortException: Should be alphanumeric
+```
\ No newline at end of file
diff --git a/docs/sidebar.yml b/docs/sidebar.yml
index 904ff056..4b89789b 100644
--- a/docs/sidebar.yml
+++ b/docs/sidebar.yml
@@ -26,5 +26,6 @@ subsection:
       - page: modules/jsoniter.md
       - page: modules/skunk.md
       - page: modules/scalacheck.md
+      - page: modules/upickle.md
       - page: modules/zio.md
       - page: modules/zio-json.md