Subcontext: add unsafeModify. Open SubcontextImpl class. Rename SubcontextImpl .empty->.initial (#2225)

* Subcontext: add `modify` and `flatAp` methods

open SubcontextImpl class
rename SubcontextImpl `.empty`->`.initial`

* Remove `flatAp`. Rename `modify`->`unsafeModify`. Add documentation as to why it's unsafe.

* wip

Author: neko-kai

distage/distage-core-api/src/main/scala/izumi/distage/Subcontext.scala

@@ -3,6 +3,7 @@ package izumi.distage
 import izumi.distage.model.definition.Identifier
 import izumi.functional.lifecycle.Lifecycle
 import izumi.distage.model.plan.Plan
+import izumi.distage.model.providers.Functoid
 import izumi.functional.quasi.QuasiIO
 import izumi.fundamentals.platform.functional.Identity
 import izumi.fundamentals.platform.language.CodePositionMaterializer
@@ -19,12 +20,63 @@ trait Subcontext[A] {
     *       Use `produce` if you need to extend the lifetime of the Subcontext's resources.
     */
   def produceRun[F[_]: QuasiIO: TagK, B](f: A => F[B]): F[B]
-  final def produceRun[B](f: A => B): B = produceRun[Identity, B](f)
+
+  final def produceRunSimple[B](f: A => B): B = produceRun[Identity, B](f)
 
   def provide[T: Tag](value: T)(implicit pos: CodePositionMaterializer): Subcontext[A]
   def provide[T: Tag](name: Identifier)(value: T)(implicit pos: CodePositionMaterializer): Subcontext[A]
 
   def plan: Plan
 
-  def map[B: Tag](f: A => B): Subcontext[B]
+  final def map[B: Tag](f: A => B): Subcontext[B] = unsafeModify(_.map(f))
+
+  /**
+    * Unsafely substitute the Functoid that extracts the root component.
+    *
+    * Note, because the `plan` has been calculated ahead of time with `A`
+    * as the root, it's not possible to request additional components
+    * via Functoid that weren't already in the graph as dependencies of `A`
+    * – everything that `A` doesn't depend is not in the plan.
+    *
+    * Example:
+    *
+    * {{{
+    * val submodule = new ModuleDef {
+    *   make[Int].fromValue(3)
+    *   make[Int].named("five").from((_: Int) + 2)
+    *   make[String].fromValue("x")
+    * }
+    *
+    * makeSubcontext[Int].named("five").withSubmodule(submodule)
+    *
+    * ...
+    *
+    * (subcontext: Subcontext[Int])
+    *   .unsafeModify(_ => Functoid.identity[String])
+    *   .produceRun(println(_))
+    *   // error: `String` is not available
+    * }}}
+    *
+    * A binding for `String` is defined in the submodule, but is not referenced by `Int @Id("five")` binding.
+    * Therefore it was removed by garbage collection and cannot be extracted with this Subcontext. You'd have to create
+    * another `Subcontext[String]` with the same submodule to create `String`:
+    *
+    * {{{
+    * makeSubcontext[String](submodule)
+    *
+    * ...
+    *
+    * (subcontext: Subcontext[String])
+    *   .produceRun(println(_))
+    *   // x
+    * }}}
+    *
+    * If you DO need dynamic replanning, you'll need to use
+    * [[https://izumi.7mind.io/distage/advanced-features.html#depending-on-locator nested injection]]
+    * directly.
+    */
+  def unsafeModify[B](f: Functoid[A] => Functoid[B]): Subcontext[B]
+
+  @deprecated("Renamed to produceRunSimple", "1.2.17")
+  final def produceRun[B](f: A => B): B = produceRunSimple[B](f)
 }

distage/distage-core/src/main/scala/izumi/distage/SubcontextImpl.scala

@@ -13,13 +13,13 @@ import izumi.functional.quasi.QuasiIO
 import izumi.fundamentals.platform.language.CodePositionMaterializer
 import izumi.reflect.{Tag, TagK}
 
-final class SubcontextImpl[A] private (
-  externalKeys: Set[DIKey],
-  parent: LocatorRef,
+open class SubcontextImpl[A](
+  val externalKeys: Set[DIKey],
+  val parent: LocatorRef,
   val plan: Plan,
-  functoid: Functoid[A],
-  providedExternals: Map[DIKey, AnyRef],
-  selfKey: DIKey,
+  val functoid: Functoid[A],
+  val providedExternals: Map[DIKey, AnyRef],
+  val selfKey: DIKey,
 ) extends Subcontext[A] {
 
   def provide[T: Tag](value: T)(implicit pos: CodePositionMaterializer): Subcontext[A] = {
@@ -50,8 +50,8 @@ final class SubcontextImpl[A] private (
     produce().use(f)
   }
 
-  override def map[B: Tag](f: A => B): Subcontext[B] = {
-    new SubcontextImpl(externalKeys, parent, plan, functoid.map[B](f), providedExternals, selfKey)
+  override def unsafeModify[B](f: Functoid[A] => Functoid[B]): Subcontext[B] = {
+    new SubcontextImpl(externalKeys, parent, plan, f(functoid), providedExternals, selfKey)
   }
 
   private def doAdd(value: AnyRef, pos: CodePositionMaterializer, key: DIKey): SubcontextImpl[A] = {
@@ -72,6 +72,12 @@ final class SubcontextImpl[A] private (
 }
 
 object SubcontextImpl {
-  def empty[A](externalKeys: Set[DIKey], locatorRef: LocatorRef, subplan: Plan, impl: Functoid[A], selfKey: DIKey) =
-    new SubcontextImpl[A](externalKeys, locatorRef, subplan, impl, Map.empty, selfKey)
+  def initial[A](externalKeys: Set[DIKey], parent: LocatorRef, subplan: Plan, functoid: Functoid[A], selfKey: DIKey): SubcontextImpl[A] = {
+    new SubcontextImpl[A](externalKeys, parent, subplan, functoid, Map.empty, selfKey)
+  }
+
+  @deprecated("Renamed to initial", "1.2.17")
+  def empty[A](externalKeys: Set[DIKey], locatorRef: LocatorRef, subplan: Plan, impl: Functoid[A], selfKey: DIKey): SubcontextImpl[A] = {
+    initial(externalKeys, locatorRef, subplan, impl, selfKey)
+  }
 }

distage/distage-core/src/main/scala/izumi/distage/provisioning/strategies/SubcontextStrategyDefaultImpl.scala

@@ -23,7 +23,7 @@ class SubcontextStrategyDefaultImpl extends SubcontextStrategy {
         val locatorRef = value.asInstanceOf[LocatorRef]
         val provider = op.wiring.provider
         val subplan = op.wiring.subplan
-        val ctx = SubcontextImpl.empty[Any](op.wiring.externalKeys, locatorRef, subplan, Functoid(provider), op.target)
+        val ctx = SubcontextImpl.initial[Any](op.wiring.externalKeys, locatorRef, subplan, Functoid(provider), op.target)
         F.pure(Right(Seq(NewObjectOp.UseInstance(op.target, ctx))))
 
       case None =>

doc/microsite/src/main/tut/distage/basics.md

@@ -1397,6 +1397,17 @@ Injector()
 
 ## Subcontexts
 
+Subcontext seems to do most of this - it inherits from global scope by default. You can use include inside subcontext's module to spread out definitions into multiple modules. It is limited to a target dependency, but the target dependency itself is not limited - you can make a tuple or a case class binding to aggregate multiple components in a tuple or even add LocatorRef to extract arbitrary components (but they would have to be dependencies of other components in the tuple).
+
+It wouldn't make a lot of sense to make Subcontexts fully unrestricted wrt the target dependency - because Subcontexts are actually an optimization of nested injection pattern, where the target dependency is known ahead of time. This allows the subcontext to be pre-planned in advance, so when you create an instance of the subgraph there is no injector overhead - the constructors are just called with local dependencies according to the pre-calculated plan. Since values of local dependencies can't influence the shape of the graph there is no reason to recalculate it.
+
+Now, if you actually need to be able to make different subgraphs out of a module at runtime, you can manually use nested injection - that way you have full flexibility with regards to everything, you can even do another classpath scan for Plugins and construct the module from that at runtime.
+
+However, for efficiency, you'd probably want to use pre-calculated subcontexts, because people rarely make dynamically extensible applications especially in Scala. It would be easier to just make multiple subcontexts for each different component - they can even use the same module, it doesn't matter, only real dependencies of the target dependency will be created, modules can safely contain unused bindings:
+
+
+Note also that Subcontexts are generalized Factories. A subcontext with just one binding is exactly the same as a Factory.
+
 Sometimes multiple components depend on the same piece of data that appears locally, after all the components were already wired.
 This data may need to be passed around repeatedly, possibly across the entire application. To do this, we may have to add an argument
 to most methods of an application, or have to use a Reader monad everywhere.