Copying a module
Every module gets a generated copy<Module> extension function, named after the module, which builds a new module from an existing one.
It takes one parameter per member, each defaulting to the binding the module currently holds for that member, so you only name what you want to override:
val app = AppModule(
config = Binding.value(Config(debug = false)),
repository = Binding.single { SqlRepository(config) },
user = Binding.factory { id -> repository().findUser(id) },
)
val debugApp = app.copyAppModule(
config = Binding.value(Config(debug = true)),
)
The original module is never modified: copyAppModule returns a new module, and app keeps its own bindings.
Calling copyAppModule() without any argument still builds a new module, with its own copy of every binding.
appModule.copyAppModule(/…/) will be deprecated once companion extensions are stable in Kotlin (they are experimental in Kotlin 2.5).
It will then be replaced by AppModule.copy(of = appModule, /…/), which is why a module member may not be named of.
|
Named after the module
A module can also call the copy function of each of its @DIModule ancestors, which builds that ancestor:
@DIModule
interface ServerModule {
val port: Int
}
@DIModule
interface AppModule : ServerModule {
val name: String
}
val copiedApp: AppModule = app.copyAppModule(port = Binding.value(8080)) (1)
val copiedServer: ServerModule = app.copyServerModule(port = Binding.value(8080)) (2)
| 1 | Builds an AppModule, even though only an inherited member is overridden. |
| 2 | Builds a ServerModule, which has no name. |
Because each function carries the name of the module it builds, a call always says which one it builds, and never matches the function of another module.
|
These functions used to all be named |
Copied bindings have their own state
Every binding the new module holds is a copy of the original’s: same recipe, but its own state.
A single, weakSingle or multiplex that is already built in the original starts unbuilt in the copy, and is built there, with the copy as its receiver:
val parent = MyModule(
name = Binding.value("John"),
hello = Binding.single { "Hello, $name" },
)
val child = parent.copyMyModule(
name = Binding.value("Jane"),
)
child.hello // "Hello, Jane" (1)
parent.hello // "Hello, John" (2)
| 1 | The child initializes its own single. |
| 2 | The parent’s single is untouched, and still reads the parent’s name. |
Bindings that do not keep any state, like value, provider and factory, are not duplicated: they always run against the module they are accessed through.
Detached bindings are not duplicated either: a copy keeps them, and so shares their instance.
| A module that implements the interface by hand has no bindings to copy. Its members are read through a delegate, so they keep whatever state that module has. |
To share the original’s state instead, and keep the original from ever seeing your overrides, use shadow<Module>.
|
Default implementations
For a member that has a default implementation, an omitted parameter keeps the member as it was. If it was unbound, its default body keeps being used, and runs against the new module: it therefore observes the members you overrode in the same call.
Such a member additionally accepts an explicit null, which drops its binding and goes back to the interface’s own body:
val module = GreetingModule(
name = Binding.value("World"),
greeting = Binding.provider { "Hi $name" },
)
val restored = module.copyGreetingModule(greeting = null)
restored.greeting // "Hello, World"
Chaining copies
A copy is a module like any other, so it can be copied in turn:
val variant = app
.copyAppModule(config = Binding.value(Config(debug = true)))
.copyAppModule(user = Binding.factory { id -> User.guest(id) })
| Testing shows how copies are used to build test variants of a module. |