feat(schema): Add Type-Safe Schema Migration System with Nested Support

schema/shared/src/main/scala-3/zio/blocks/schema/migration/FieldSelector.scala

@@ -0,0 +1,159 @@
+/*
+ * Copyright 2024 John A. De Goes and the ZIO Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package zio.blocks.schema.migration
+
+import zio.blocks.schema.DynamicOptic
+
+/**
+ * A type-safe field selector that captures the field name as a singleton string
+ * type.
+ *
+ * This enables compile-time validation of field names in migrations.
+ *
+ * @tparam S
+ *   The source/record type containing the field
+ * @tparam F
+ *   The field's value type
+ * @tparam Name
+ *   The field name as a singleton string type (e.g., "name")
+ *
+ * Example:
+ * {{{
+ * case class Person(name: String, age: Int)
+ *
+ * // Created via macro:
+ * val nameSelector: FieldSelector[Person, String, "name"] = select[Person](_.name)
+ * }}}
+ */
+final class FieldSelector[S, F, Name <: String](
+  val name: Name,
+  val optic: DynamicOptic
+) {
+
+  /**
+   * The runtime field name string.
+   */
+  def fieldName: String = name
+
+  /**
+   * Navigate to a nested field, returning a selector for the nested path.
+   */
+  def /[G, NestedName <: String](nested: FieldSelector[F, G, NestedName]): FieldSelector[S, G, Name] =
+    new FieldSelector[S, G, Name](name, optic(nested.optic))
+
+  override def toString: String = s"FieldSelector($name, $optic)"
+
+  override def equals(obj: Any): Boolean = obj match {
+    case that: FieldSelector[?, ?, ?] => this.name == that.name && this.optic == that.optic
+    case _                            => false
+  }
+
+  override def hashCode: Int = (name, optic).hashCode
+}
+
+object FieldSelector {
+
+  /**
+   * Create a FieldSelector with explicit name (for internal/test use).
+   */
+  def apply[S, F, Name <: String](name: Name, optic: DynamicOptic): FieldSelector[S, F, Name] =
+    new FieldSelector[S, F, Name](name, optic)
+
+  /**
+   * Create a FieldSelector from just a name (optic defaults to single field).
+   */
+  def fromName[S, F, Name <: String](name: Name): FieldSelector[S, F, Name] =
+    new FieldSelector[S, F, Name](name, DynamicOptic(Vector(DynamicOptic.Node.Field(name))))
+
+  /**
+   * Extract the singleton name type from a FieldSelector.
+   */
+  type NameOf[Sel] = Sel match {
+    case FieldSelector[?, ?, name] => name
+  }
+
+  /**
+   * Extract the source type from a FieldSelector.
+   */
+  type SourceOf[Sel] = Sel match {
+    case FieldSelector[s, ?, ?] => s
+  }
+
+  /**
+   * Extract the field type from a FieldSelector.
+   */
+  type FieldTypeOf[Sel] = Sel match {
+    case FieldSelector[?, f, ?] => f
+  }
+}
+
+/**
+ * A path selector for nested field access.
+ *
+ * This tracks the full path from root to a nested field, enabling nested
+ * migrations like `atField(_.address.street)`.
+ *
+ * @tparam S
+ *   The root source type
+ * @tparam F
+ *   The final field type at the end of the path
+ * @tparam Path
+ *   A tuple of field names representing the path
+ */
+final class PathSelector[S, F, Path <: Tuple](
+  val path: Path,
+  val optic: DynamicOptic
+) {
+
+  /**
+   * Get the path as a sequence of strings.
+   */
+  def pathStrings: Seq[String] = {
+    def toSeq(t: Tuple): Seq[String] = t match {
+      case EmptyTuple          => Seq.empty
+      case (h: String) *: tail => h +: toSeq(tail)
+      case _                   => Seq.empty
+    }
+    toSeq(path)
+  }
+
+  override def toString: String = s"PathSelector(${pathStrings.mkString(".")}, $optic)"
+}
+
+object PathSelector {
+
+  /**
+   * Create a PathSelector from a single field.
+   */
+  def single[S, F, Name <: String](selector: FieldSelector[S, F, Name]): PathSelector[S, F, Name *: EmptyTuple] =
+    new PathSelector[S, F, Name *: EmptyTuple](
+      (selector.name *: EmptyTuple).asInstanceOf[Name *: EmptyTuple],
+      selector.optic
+    )
+
+  /**
+   * Create a PathSelector for nested access.
+   */
+  def nested[S, M, F, P <: Tuple, Name <: String](
+    parent: PathSelector[S, M, P],
+    child: FieldSelector[M, F, Name]
+  ): PathSelector[S, F, Tuple.Concat[P, Name *: EmptyTuple]] =
+    new PathSelector[S, F, Tuple.Concat[P, Name *: EmptyTuple]](
+      (parent.path ++ (child.name *: EmptyTuple)).asInstanceOf[Tuple.Concat[P, Name *: EmptyTuple]],
+      parent.optic(child.optic)
+    )
+}

schema/shared/src/main/scala-3/zio/blocks/schema/migration/FieldSet.scala

@@ -0,0 +1,146 @@
+/*
+ * Copyright 2024 John A. De Goes and the ZIO Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package zio.blocks.schema.migration
+
+/**
+ * Type-level operations on field sets represented as tuples of singleton string
+ * types.
+ *
+ * This enables compile-time tracking of which fields have been handled in
+ * migrations, ensuring all source fields are addressed and all target fields
+ * are provided.
+ *
+ * Example:
+ * {{{
+ * type PersonFields = ("name", "age", "email")
+ * type Remaining = FieldSet.Remove[PersonFields, "name"]  // = ("age", "email")
+ * type HasAge = FieldSet.Contains[PersonFields, "age"]    // = true
+ * }}}
+ */
+object FieldSet {
+
+  /**
+   * Remove a field name from a tuple of field names. Returns a new tuple with
+   * the specified name removed.
+   */
+  type Remove[Fields <: Tuple, Name <: String] <: Tuple = Fields match {
+    case EmptyTuple   => EmptyTuple
+    case Name *: tail => tail
+    case head *: tail => head *: Remove[tail, Name]
+  }
+
+  /**
+   * Check if a tuple of field names contains a specific name. Returns true if
+   * the name is found, false otherwise.
+   */
+  type Contains[Fields <: Tuple, Name <: String] <: Boolean = Fields match {
+    case EmptyTuple => false
+    case Name *: _  => true
+    case _ *: tail  => Contains[tail, Name]
+  }
+
+  /**
+   * Check if a tuple is empty.
+   */
+  type IsEmpty[Fields <: Tuple] <: Boolean = Fields match {
+    case EmptyTuple => true
+    case _          => false
+  }
+
+  /**
+   * Add a field name to a tuple of field names.
+   */
+  type Add[Fields <: Tuple, Name <: String] = Name *: Fields
+
+  /**
+   * Compute the intersection of two field sets.
+   */
+  type Intersect[A <: Tuple, B <: Tuple] <: Tuple = A match {
+    case EmptyTuple   => EmptyTuple
+    case head *: tail =>
+      Contains[B, head] match {
+        case true  => head *: Intersect[tail, B]
+        case false => Intersect[tail, B]
+      }
+  }
+
+  /**
+   * Compute the difference of two field sets (A - B).
+   */
+  type Diff[A <: Tuple, B <: Tuple] <: Tuple = A match {
+    case EmptyTuple   => EmptyTuple
+    case head *: tail =>
+      Contains[B, head] match {
+        case true  => Diff[tail, B]
+        case false => head *: Diff[tail, B]
+      }
+  }
+
+  /**
+   * Concatenate two tuples.
+   */
+  type Concat[A <: Tuple, B <: Tuple] <: Tuple = A match {
+    case EmptyTuple   => B
+    case head *: tail => head *: Concat[tail, B]
+  }
+
+  /**
+   * Evidence that a field name is contained in a tuple of field names. Used to
+   * ensure compile-time validation that a field exists.
+   */
+  sealed trait ContainsEvidence[Fields <: Tuple, Name <: String]
+
+  object ContainsEvidence {
+    given containsHead[Name <: String, Tail <: Tuple]: ContainsEvidence[Name *: Tail, Name] =
+      new ContainsEvidence[Name *: Tail, Name] {}
+
+    given containsTail[Head <: String, Tail <: Tuple, Name <: String](using
+      ev: ContainsEvidence[Tail, Name]
+    ): ContainsEvidence[Head *: Tail, Name] =
+      new ContainsEvidence[Head *: Tail, Name] {}
+  }
+
+  /**
+   * Evidence that a tuple is empty. Used to ensure all fields have been
+   * handled.
+   */
+  sealed trait EmptyEvidence[Fields <: Tuple]
+
+  object EmptyEvidence {
+    given emptyTuple: EmptyEvidence[EmptyTuple] = new EmptyEvidence[EmptyTuple] {}
+  }
+
+  /**
+   * Type class to remove a field from a tuple at the type level. Provides the
+   * resulting type after removal.
+   */
+  sealed trait RemoveField[Fields <: Tuple, Name <: String] {
+    type Out <: Tuple
+  }
+
+  object RemoveField {
+    type Aux[Fields <: Tuple, Name <: String, O <: Tuple] = RemoveField[Fields, Name] { type Out = O }
+
+    given removeHead[Name <: String, Tail <: Tuple]: Aux[Name *: Tail, Name, Tail] =
+      new RemoveField[Name *: Tail, Name] { type Out = Tail }
+
+    given removeTail[Head <: String, Tail <: Tuple, Name <: String](using
+      ev: RemoveField[Tail, Name]
+    ): Aux[Head *: Tail, Name, Head *: ev.Out] =
+      new RemoveField[Head *: Tail, Name] { type Out = Head *: ev.Out }
+  }
+}