Merge pull request #20 from SystemFw/recursive

Recursive

Author: SystemFw

docs/schema.md

@@ -63,15 +63,11 @@ our schemas.
 
 ## Schema caching
 
-With the exception of recursive schemas, which are treated later, it's
-best to declare schemas as `val`, to allow `Dynosaur` to cache some
-transformations.
+It's best to declare schemas as `val`, to allow `Dynosaur` to cache
+some transformations.
 
 ```scala
 val mySchema: Schema[Thing] = ??? // good
-
-lazy val myRecursiveSchema: Schema[RecursiveThing] = ??? // good
-
 def mySchema: Schema[Thing] = ??? // best avoided if possible, no caching
 ```
 
@@ -845,7 +841,8 @@ Imagine you're dealing with a recursive type, such as:
 case class Department(name: String, subdeps: List[Department] = Nil)
 ```
 
-we will need to define its schema as a `lazy val`, and give it an explicit type:
+We will need to define its schema as a `lazy val`, and give it an
+explicit type:
 
 ```scala mdoc:compile-only
 lazy val wrongDepSchema: Schema[Department] = Schema.record { field =>
@@ -857,11 +854,12 @@ lazy val wrongDepSchema: Schema[Department] = Schema.record { field =>
 
 ```
 
-this code will compile fine, **but result in infinite recursion at runtime**.
+which will compile fine, **but still result in infinite recursion at
+runtime**.
 To make it work, we need to wrap the recursive occurrence of the
 schema in `Schema.defer`, like so:
 
-```scala mdoc:silent
+```scala mdoc:compile-only
 lazy val depSchema: Schema[Department] = Schema.record { field =>
   (
     field("name", _.name),
@@ -871,6 +869,21 @@ lazy val depSchema: Schema[Department] = Schema.record { field =>
 
 ```
 
+You can avoid these intricacies by using the `recursive` method
+instead, which has a similar structure (and type inference behaviour)
+to `Schema.record` and `Schema.oneOf`:
+
+```scala mdoc:silent
+val depSchema: Schema[Department] = Schema.recursive { rec =>
+  Schema.record { field =>
+    (
+     field("name", _.name),
+     field("subdeps", _.subdeps)(rec.asList)
+    ).mapN(Department.apply)
+  }
+}
+```
+
 <details>
 <summary>Click to show the resulting DynamoValue</summary>
 
@@ -893,13 +906,8 @@ depSchema.write(departments)
 ```
 </details>
 
-> So to recap, to define a recursive schema:
->
-> - Declare it as a `lazy val` with an explicit type signature
-> - Pass the recursive schema *explicitly* to the `field`s that need it
-> - Wrap recursive arguments to `field` in `Schema.defer`
-
-The same principles apply to more complex recursive structures such as ADTs:
+`Schema.recursive` can also be used for more complex recursive
+structures such as ADTs:
 
 <details>
 <summary>Click to show ADT example</summary>
@@ -909,21 +917,23 @@ sealed trait Text
 case class Paragraph(text: String) extends Text
 case class Section(title: String, contents: List[Text]) extends Text
 
-lazy val textSchema: Schema[Text] = Schema.oneOf[Text] { alt =>
-  val paragraph = Schema.record[Paragraph] { field =>
-    field("text", _.text).map(Paragraph.apply)
-  }
-   .tag("paragraph")
+val textSchema: Schema[Text] = Schema.recursive { rec =>
+  Schema.oneOf { alt =>
+    val paragraph = Schema.record[Paragraph] { field =>
+      field("text", _.text).map(Paragraph.apply)
+    }
+     .tag("paragraph")
 
-  val section = Schema.record[Section] { field =>
-    (
-      field("title", _.title),
-      field("contents", _.contents)(Schema.defer(textSchema.asList))
-    ).mapN(Section.apply)
-  }
-   .tag("section")
+    val section = Schema.record[Section] { field =>
+      (
+        field("title", _.title),
+        field("contents", _.contents)(rec.asList)
+      ).mapN(Section.apply)
+    }
+     .tag("section")
 
-  alt(section) |+| alt(paragraph)
+    alt(section) |+| alt(paragraph)
+  }
 }
 
 ```
@@ -944,6 +954,8 @@ textSchema.write(text)
 ```
 </details>
 
+> In summary, use `Schema.recursive` to define a recursive schema.
+
 
 ## String Set, Number Set and Binary Set
 

modules/core/src/main/scala/Schema.scala

@@ -160,6 +160,10 @@ object Schema {
     id.imap(_.value)(DynamoValue.apply)
 
   def defer[A](schema: => Schema[A]): Schema[A] = Defer(() => schema)
+  def recursive[A](f: Schema[A] => Schema[A]): Schema[A] = {
+    lazy val schema: Schema[A] = f(defer(schema))
+    schema
+  }
 
   def nullable[A](implicit s: Schema[A]): Schema[Option[A]] = s.nullable
 

modules/core/src/test/scala/SchemaSuite.scala

@@ -374,7 +374,7 @@ class SchemaSuite extends ScalaCheckSuite {
     )
   }
 
-  test("recursive products") {
+  test("recursive products with defer") {
     val departments = Department(
       "STEM",
       List(
@@ -422,6 +422,56 @@ class SchemaSuite extends ScalaCheckSuite {
     check(schema, departments, expected)
   }
 
+  test("recursive products with recursive") {
+    val departments = Department(
+      "STEM",
+      List(
+        Department("CS"),
+        Department(
+          "Maths",
+          List(
+            Department("Applied"),
+            Department("Theoretical")
+          )
+        )
+      )
+    )
+
+    val expected = V.m(
+      "name" -> V.s("STEM"),
+      "subdeps" -> V.l(
+        V.m(
+          "name" -> V.s("CS"),
+          "subdeps" -> V.l()
+        ),
+        V.m(
+          "name" -> V.s("Maths"),
+          "subdeps" -> V.l(
+            V.m(
+              "name" -> V.s("Applied"),
+              "subdeps" -> V.l()
+            ),
+            V.m(
+              "name" -> V.s("Theoretical"),
+              "subdeps" -> V.l()
+            )
+          )
+        )
+      )
+    )
+
+    val schema: Schema[Department] = Schema.recursive { rec =>
+      Schema.record { field =>
+        (
+          field("name", _.name),
+          field("subdeps", _.subdeps)(rec.asList)
+        ).mapN(Department.apply)
+      }
+    }
+
+    check(schema, departments, expected)
+  }
+
   test("products with more than 22 fields") {
     val big = Big(
       "f",
@@ -786,7 +836,7 @@ class SchemaSuite extends ScalaCheckSuite {
     check(schema, successfulUp, expectedSuccessful)
   }
 
-  test("recursive ADTs") {
+  test("recursive ADTs with defer") {
     val text = Section(
       "A",
       List(
@@ -845,6 +895,67 @@ class SchemaSuite extends ScalaCheckSuite {
     check(schema, text, expected)
   }
 
+  test("recursive ADTs with recursive") {
+    val text = Section(
+      "A",
+      List(
+        Paragraph("lorem ipsum"),
+        Section(
+          "A.b",
+          List(Paragraph("dolor sit amet"))
+        )
+      )
+    )
+
+    val expected = V.m(
+      "section" -> V.m(
+        "title" -> V.s("A"),
+        "contents" -> V.l(
+          V.m(
+            "paragraph" -> V.m(
+              "text" -> V.s("lorem ipsum")
+            )
+          ),
+          V.m(
+            "section" -> V.m(
+              "title" -> V.s("A.b"),
+              "contents" -> V.l(
+                V.m(
+                  "paragraph" -> V.m(
+                    "text" -> V.s("dolor sit amet")
+                  )
+                )
+              )
+            )
+          )
+        )
+      )
+    )
+
+    val schema: Schema[Text] = Schema.recursive { rec =>
+      Schema.oneOf { alt =>
+        val paragraph = Schema
+          .record[Paragraph] { field =>
+            field("text", _.text).map(Paragraph.apply)
+          }
+          .tag("paragraph")
+
+        val section = Schema
+          .record[Section] { field =>
+            (
+              field("title", _.title),
+              field("contents", _.contents)(rec.asList)
+            ).mapN(Section.apply)
+          }
+          .tag("section")
+
+        alt(section) |+| alt(paragraph)
+      }
+    }
+
+    check(schema, text, expected)
+  }
+
   val compileTimeInferenceSpec = {
     val userSchema: Schema[User] = Schema.record { field =>
       (