Limit structural schema derivation to JVM only

Author: 987Nabil

docs/reference/structural-schemas.md

@@ -23,9 +23,13 @@ ZIO Blocks extends `Schema[A]` to support structural types through:
 | Feature | Description |
 |---------|-------------|
 | `.structural` | Convert any product schema to its structural equivalent |
-| `Schema.derived[StructuralType]` | Derive schemas directly for structural types |
+| `Schema.derived[StructuralType]` | Derive schemas directly for structural types (JVM only) |
 | Normalized type names | Deterministic, comparable type identifiers |
 
+:::caution JVM Only
+Structural type support requires reflection and is only available on the JVM. Attempting to use structural types on Scala.js or Scala Native will result in a compile-time error.
+:::
+
 ## Converting to Structural Schemas
 
 Any schema for a product type (case class, tuple) can be converted to its structural representation:
@@ -42,10 +46,6 @@ val structuralSchema = nominalSchema.structural
 // Note: fields are alphabetically ordered in the structural type
 ```
 
-:::note JVM Requirement
-The `.structural` method requires JVM because it uses reflection to create the structural type at runtime. For cross-platform code, derive schemas for Selectable/Dynamic types directly instead.
-:::
-
 ### Type Name Normalization
 
 Structural type names are normalized for consistent comparison:
@@ -101,84 +101,24 @@ val structural = Schema.derived[Container].structural
 
 ## Deriving Schemas for Structural Types
 
-You can derive schemas directly for structural types without starting from a nominal type.
-
-### Scala 3: Selectable-Based Types (Cross-Platform)
-
-For cross-platform support, define a base class extending `Selectable`:
-
-```scala
-import scala.Selectable
-
-case class Record(fields: Map[String, Any]) extends Selectable {
-  def selectDynamic(name: String): Any = fields(name)
-}
-
-// Define structural types as refinements
-type PersonLike = Record { def name: String; def age: Int }
-type PointLike = Record { def x: Int; def y: Int }
-
-// Derive schema directly
-val personSchema = Schema.derived[PersonLike]
-val pointSchema = Schema.derived[PointLike]
-```
-
-**Requirements for Selectable types:**
-1. Base class must extend `Selectable`
-2. Must have either:
-   - A constructor taking `Map[String, Any]`, or
-   - A companion `apply(Map[String, Any]): T` method
-
-### Scala 2: Dynamic-Based Types (Cross-Platform)
-
-For Scala 2 cross-platform support, use `scala.Dynamic`:
-
-```scala
-import scala.language.dynamics
-
-class DynamicRecord(val fields: Map[String, Any]) extends Dynamic {
-  def selectDynamic(name: String): Any = fields(name)
-}
-
-object DynamicRecord {
-  def apply(map: Map[String, Any]): DynamicRecord = new DynamicRecord(map)
-}
-
-// Define structural types
-type PersonLike = DynamicRecord { def name: String; def age: Int }
-
-// Derive schema
-val schema = Schema.derived[PersonLike]
-```
-
-### Pure Structural Types (Scala 2: All Platforms, Scala 3: JVM Only)
-
-In Scala 2, you can derive schemas for pure structural types on **all platforms** because the macro generates an anonymous Dynamic class at compile time:
+You can derive schemas directly for structural types. This feature requires JVM because it uses reflection for deconstruction.
 
 ```scala
-// Scala 2 - Works on JVM, JS, and Native!
+// JVM only - uses reflection
 type PersonLike = { def name: String; def age: Int }
 val schema = Schema.derived[PersonLike]
-
-// The macro generates an anonymous Dynamic class, no runtime reflection needed
 ```
 
-In Scala 3, pure structural types without a `Selectable` base only work on JVM:
+:::caution Platform Restriction
+Structural type derivation requires reflection and only works on the JVM. Attempting to derive a schema for a structural type on JS or Native will result in a compile-time error:
 
-```scala
-// Scala 3 JVM only - uses reflection
-type PointLike = { def x: Int; def y: Int }
-val schema = Schema.derived[PointLike]  // Only works on JVM
 ```
+Cannot derive Schema for structural type '...' on JS/Native.
 
-:::caution Platform Restriction
-In Scala 3, pure structural types (without `Selectable`) require reflection and only work on the JVM. Attempting to derive a schema for a pure structural type on JS or Native will result in a compile-time error.
-
-In Scala 2, pure structural types work on all platforms because the macro generates Dynamic classes at compile time.
-:::
+Structural types require reflection which is only available on JVM.
 
-:::note Converting Nominal to Structural
-The `.structural` method on `Schema` (for converting `Schema[CaseClass]` to its structural equivalent) requires JVM on **both** Scala 2 and Scala 3 because it uses reflection to create the structural type.
+Consider using a case class instead.
+```
 :::
 
 ## Sum Types and Union Types
@@ -219,30 +159,7 @@ val schema = Schema.derived[Status]
 
 ### Scala 2: Sum Type Limitation
 
-In Scala 2, sealed traits cannot be converted to structural types because Scala 2 lacks union types. Attempting to call `.structural` on a sealed trait schema will produce a compile-time error:
-
-```scala
-// Scala 2
-sealed trait Status
-case object Active extends Status
-case object Inactive extends Status
-
-val schema = Schema.derived[Status]  // ✅ Works
-val structural = schema.structural   // ❌ Compile error
-```
-
-**Error message:**
-```
-Cannot convert sum type 'Status' to structural type.
-
-Sum types (sealed traits, enums) cannot be represented as structural types in Scala 2
-because Scala 2 does not support union types.
-
-Consider:
-  - Using a case class wrapper instead of a sealed trait
-  - Using the nominal schema directly
-  - Upgrading to Scala 3 for union type support
-```
+In Scala 2, sealed traits cannot be converted to structural types because Scala 2 lacks union types. Attempting to call `.structural` on a sealed trait schema will produce a compile-time error.
 
 ## Platform Compatibility
 
@@ -254,9 +171,7 @@ Consider:
 | Large Products (>22 fields) | ✅ | ✅ | ✅ | ✅ |
 | Sealed Trait `.structural` | ❌ (no unions) | ❌ (no unions) | ✅ | ❌ (needs reflection) |
 | Enum `.structural` | N/A | N/A | ✅ | ❌ (needs reflection) |
-| Pure Structural Derivation | ✅ | ✅ (Dynamic) | ✅ (JVM only) | ❌ |
-| Dynamic-based Derivation | ✅ | ✅ | N/A | N/A |
-| Selectable-based Derivation | N/A | N/A | ✅ | ✅ |
+| Pure Structural Derivation | ✅ | ❌ (needs reflection) | ✅ | ❌ (needs reflection) |
 
 **Key:**
 - **`.structural`** = Converting `Schema[NominalType]` to `Schema[StructuralType]`
@@ -314,16 +229,12 @@ Structural schemas work seamlessly with the `Into` and `As` type classes for sch
 ```scala
 import zio.blocks.schema._
 
-// Define Selectable base for cross-platform support
-case class Record(fields: Map[String, Any]) extends Selectable {
-  def selectDynamic(name: String): Any = fields(name)
-}
-
-type PersonLike = Record { def name: String; def age: Int }
+// JVM only
+type PersonLike = { def name: String; def age: Int }
 
 case class Person(name: String, age: Int)
 
-// Convert between nominal and structural
+// Convert between nominal and structural (JVM only)
 val personToStructural = Into.derived[Person, PersonLike]
 val structuralToPerson = Into.derived[PersonLike, Person]
 
@@ -335,41 +246,19 @@ See [Schema Evolution](schema-evolution.md) for complete documentation on `Into`
 
 ## Complete Example
 
-Here's a complete example demonstrating structural schema features:
+Here's a complete example demonstrating structural schema features (JVM only):
 
 ```scala
 import zio.blocks.schema._
-import scala.Selectable
 
-// === Define a cross-platform Selectable base ===
-case class Record(fields: Map[String, Any]) extends Selectable {
-  def selectDynamic(name: String): Any = fields(name)
-}
-
-// === Define structural types as refinements ===
-type PersonLike = Record { def name: String; def age: Int }
-type AddressLike = Record { def street: String; def city: String }
+// === Define structural types ===
+type PersonLike = { def name: String; def age: Int }
+type AddressLike = { def street: String; def city: String }
 
-// === Derive schemas for structural types ===
+// === Derive schemas for structural types (JVM only) ===
 val personSchema = Schema.derived[PersonLike]
 val addressSchema = Schema.derived[AddressLike]
 
-// === Create instances using the Record constructor ===
-def makePerson(name: String, age: Int): PersonLike =
-  Record(Map("name" -> name, "age" -> age)).asInstanceOf[PersonLike]
-
-val alice = makePerson("Alice", 30)
-
-// Access fields via structural type refinement
-println(alice.name)  // "Alice"
-println(alice.age)   // 30
-
-// === Convert to/from DynamicValue ===
-val dynamic = personSchema.toDynamicValue(alice)
-// DynamicValue.Record(Vector("name" -> Primitive(String("Alice")), "age" -> Primitive(Int(30))))
-
-val restored = personSchema.fromDynamicValue(dynamic)
-// Right(Record(Map("name" -> "Alice", "age" -> 30)))
 
 // === Check structural type name ===
 personSchema.reflect.typeName.name

schema/js/src/test/scala/zio/blocks/schema/into/structural/StructuralTypeCompileErrorSpec.scala

@@ -5,12 +5,12 @@ import zio.test._
 /**
  * Tests for structural type conversions on Scala.js.
  *
- *   - Structural → Product: Requires reflection, fails at compile time on JS
+ *   - Structural types require reflection and fail at compile time on JS
  */
 object StructuralTypeCompileErrorSpec extends ZIOSpecDefault {
 
   def spec = suite("StructuralTypeCompileErrorSpec")(
-    suite("Structural to Product - Compile Error on JS")(
+    suite("Structural types - Compile Error on JS")(
       test("structural type to case class fails to compile") {
         typeCheck {
           """
@@ -24,8 +24,8 @@ object StructuralTypeCompileErrorSpec extends ZIOSpecDefault {
         }.map { result =>
           assertTrue(
             result.isLeft,
-            // Structural type conversions require reflection, not supported on JS
-            result.swap.exists(_.toLowerCase.contains("structural type conversions are not supported on js"))
+            // Structural types require reflection, not supported on JS
+            result.swap.exists(_.toLowerCase.contains("structural types require reflection"))
           )
         }
       },
@@ -42,7 +42,7 @@ object StructuralTypeCompileErrorSpec extends ZIOSpecDefault {
         }.map { result =>
           assertTrue(
             result.isLeft,
-            result.swap.exists(_.toLowerCase.contains("structural type conversions are not supported on js"))
+            result.swap.exists(_.toLowerCase.contains("structural types require reflection"))
           )
         }
       }

schema/jvm/src/test/scala-2/zio/blocks/schema/structural/StructuralTypeSpec.scala

@@ -0,0 +1,68 @@
+package zio.blocks.schema.structural
+
+import zio.blocks.schema._
+import zio.test._
+
+/**
+ * Tests for Scala 2 pure structural type derivation (JVM only).
+ */
+object StructuralTypeSpec extends ZIOSpecDefault {
+
+  type PersonLike = { def name: String; def age: Int }
+  type PointLike  = { def x: Int; def y: Int }
+
+  def spec = suite("StructuralTypeSpec")(
+    test("structural type round-trips through DynamicValue") {
+      val schema  = Schema.derived[PersonLike]
+      val dynamic = DynamicValue.Record(
+        Vector(
+          "name" -> DynamicValue.Primitive(PrimitiveValue.String("Alice")),
+          "age"  -> DynamicValue.Primitive(PrimitiveValue.Int(30))
+        )
+      )
+      val result = schema.fromDynamicValue(dynamic)
+      result match {
+        case Right(person) =>
+          val backToDynamic = schema.toDynamicValue(person)
+          backToDynamic match {
+            case rec: DynamicValue.Record =>
+              val expected = dynamic.asInstanceOf[DynamicValue.Record]
+              assertTrue(
+                rec.fields.toSet == expected.fields.toSet,
+                person.name == "Alice",
+                person.age == 30
+              )
+            case _ => assertTrue(false) ?? "Expected DynamicValue.Record"
+          }
+        case Left(err) =>
+          assertTrue(false) ?? s"fromDynamicValue failed: $err"
+      }
+    },
+    test("structural type with primitives round-trips") {
+      val schema  = Schema.derived[PointLike]
+      val dynamic = DynamicValue.Record(
+        Vector(
+          "x" -> DynamicValue.Primitive(PrimitiveValue.Int(100)),
+          "y" -> DynamicValue.Primitive(PrimitiveValue.Int(200))
+        )
+      )
+      val result = schema.fromDynamicValue(dynamic)
+      result match {
+        case Right(point) =>
+          val backToDynamic = schema.toDynamicValue(point)
+          backToDynamic match {
+            case rec: DynamicValue.Record =>
+              val expected = dynamic.asInstanceOf[DynamicValue.Record]
+              assertTrue(
+                rec.fields.toSet == expected.fields.toSet,
+                point.x == 100,
+                point.y == 200
+              )
+            case _ => assertTrue(false) ?? "Expected DynamicValue.Record"
+          }
+        case Left(err) =>
+          assertTrue(false) ?? s"fromDynamicValue failed: $err"
+      }
+    }
+  )
+}

schema/native/src/test/scala/zio/blocks/schema/into/structural/StructuralTypeCompileErrorSpec.scala

@@ -3,12 +3,12 @@ package zio.blocks.schema.into.structural
 import zio.test._
 
 /**
- * Tests that structural type conversions fail at compile time on Scala Native.
+ * Tests that structural types fail at compile time on Scala Native.
  */
 object StructuralTypeCompileErrorSpec extends ZIOSpecDefault {
 
   def spec = suite("StructuralTypeCompileErrorSpec")(
-    suite("Structural to Product - Compile Error on Native")(
+    suite("Structural types - Compile Error on Native")(
       test("structural type to case class fails to compile") {
         typeCheck {
           """
@@ -22,8 +22,8 @@ object StructuralTypeCompileErrorSpec extends ZIOSpecDefault {
         }.map { result =>
           assertTrue(
             result.isLeft,
-            // Structural type conversions require reflection, not supported on Native
-            result.swap.exists(_.toLowerCase.contains("structural type conversions are not supported on native"))
+            // Structural types require reflection, not supported on Native
+            result.swap.exists(_.toLowerCase.contains("structural types require reflection"))
           )
         }
       },
@@ -40,7 +40,7 @@ object StructuralTypeCompileErrorSpec extends ZIOSpecDefault {
         }.map { result =>
           assertTrue(
             result.isLeft,
-            result.swap.exists(_.toLowerCase.contains("structural type conversions are not supported on native"))
+            result.swap.exists(_.toLowerCase.contains("structural types require reflection"))
           )
         }
       }