Merge pull request #52 from utybo/utybo/issue51

Deprecate scope.factory()

CHANGELOG.md

@@ -19,6 +19,12 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
     - Contributed by [@serras](https://github.com/serras), thank you!
 
+### Deprecated
+
+- `tegral-di-core`
+
+  - Deprecate the old `scope.factory()` syntax. Use `scope()` directly instead.
+    ([#52](https://github.com/utybo/Tegral/pull/52))
 
 ### Fixed
 
@@ -75,11 +81,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - `tegral-featureful`
 
-  - Added `LifecycleHookedFeature`, which allows you to create features that listen to specific "hooks" outside of the regular start-stop cycle. This should be used carefully and are mostly intended for "low-level" operations. ([#10](https://github.com/utybo/Tegral/pull/10))
+  - Added `LifecycleHookedFeature`, which allows you to create features
+    that listen to specific "hooks" outside of the regular start-stop
+    cycle. This should be used carefully and are mostly intended for
+    "low-level" operations.
+    ([#10](https://github.com/utybo/Tegral/pull/10))
 
 - `tegral-logging`
 
-  - Added logging configuration. You can now configure loggers directly in your `tegral.toml` -- Logback will be configured accordingly. ([#10](https://github.com/utybo/Tegral/pull/10))
+  - Added logging configuration. You can now configure loggers directly
+    in your `tegral.toml` -- Logback will be configured accordingly.
+    ([#10](https://github.com/utybo/Tegral/pull/10))
 
   - Added a `putLoggerFactory` function to easily add factories to any
     environment, especially ones that do not have features support.
@@ -89,7 +101,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
   - Initial release ([#32](https://github.com/utybo/Tegral/pull/32))
 
-    - Provides a command line interface for converting `*.openapi.kts` scripts into OpenAPI JSON and YAML files.
+    - Provides a command line interface for converting `*.openapi.kts`
+      scripts into OpenAPI JSON and YAML files.
 
 - `tegral-openapi-dsl`
 
@@ -107,7 +120,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
   - Initial release ([#32](https://github.com/utybo/Tegral/pull/32))
 
-    - Ktor plugin for describing endpoints and serving OpenAPI documents from a Ktor application.
+    - Ktor plugin for describing endpoints and serving OpenAPI documents
+      from a Ktor application.
 
 - `tegral-openapi-ktorui`
 
@@ -133,7 +147,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
     apply Tegral's defaults to your own object mappers.
     ([#17](https://github.com/utybo/Tegral/pull/17))
 
-  - Added an automatic default configuration for logging. This creates a better logging experience out of the box than the Logback defaults. ([#10](https://github.com/utybo/Tegral/pull/10))
+  - Added an automatic default configuration for logging. This creates a
+    better logging experience out of the box than the Logback defaults.
+    ([#10](https://github.com/utybo/Tegral/pull/10))
 
   - Tegral will now stop all services when receiving a shutdown hook from the
     JVM (done via the `ShutdownHookService`).
@@ -143,15 +159,27 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
   - Added `TegralApplication.stop()` ([#19](https://github/utybo/Tegral/pull/19))
 
-  - Added bindings for the new automatic default configuration for logging. You can disable this custom logging by passing an argument in the `tegral` function. ([#10](https://github.com/utybo/Tegral/pull/10))
+  - Added bindings for the new automatic default configuration for
+    logging. You can disable this custom logging by passing an argument
+    in the `tegral` function.
+    ([#10](https://github.com/utybo/Tegral/pull/10))
 
-  - Added the ability to disable AppDefaults. Passing `enableDefaults = false` to the `tegral` will not call AppDefaults' `applyDefaults()` function and will not install the various default features and configurations. ([#10](https://github.com/utybo/Tegral/pull/10))
+  - Added the ability to disable AppDefaults. Passing
+    `enableDefaults = false` to the `tegral` will not call AppDefaults'
+    `applyDefaults()` function and will not install the various default
+    features and configurations.
+    ([#10](https://github.com/utybo/Tegral/pull/10))
 
-  - The `tegral` block will now print more useful information as well as statistics on startup. ([#10](https://github.com/utybo/Tegral/pull/10))
+  - The `tegral` block will now print more useful information as well as
+    statistics on startup.
+    ([#10](https://github.com/utybo/Tegral/pull/10))
 
-  - Added `features` and `lifecycleFeatures` extension properties to `TegralAPplication` ([#10](https://github.com/utybo/Tegral/pull/10))
+  - Added `features` and `lifecycleFeatures` extension properties to
+    `TegralAPplication`
+    ([#10](https://github.com/utybo/Tegral/pull/10))
 
-  - Added calls to the lifecycle hooked features where relevant ([#10](https://github.com/utybo/Tegral/pull/10))
+  - Added calls to the lifecycle hooked features where relevant
+    ([#10](https://github.com/utybo/Tegral/pull/10))
 
 - `tegral-web-apptest`
 
@@ -183,19 +211,24 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   - Bumped Ktor version to version 2.0.3
     ([#17](https://github/utybo/Tegral/pull/17))
 
-  - Bumped Kotlin version to 1.7.10 ([#27](https://github.com/utybo/Tegral/pull/27))
+  - Bumped Kotlin version to 1.7.10
+    ([#27](https://github.com/utybo/Tegral/pull/27))
 
-  - Bumped Gradle version to 7.5 ([#27](https://github.com/utybo/Tegral/pull/27))
+  - Bumped Gradle version to 7.5
+    ([#27](https://github.com/utybo/Tegral/pull/27))
 
-  - Bumped Hoplite version to 2.3.3 ([#10](https://github.com/utybo/Tegral/pull/10))
+  - Bumped Hoplite version to 2.3.3
+    ([#10](https://github.com/utybo/Tegral/pull/10))
 
 - `tegral-di-core`
 
   - **Breaking change:** You no longer need to write `scope.factory()` to
     retrieve elements generated by a factory. You can just use `scope()`
     instead. ([#23](https://github.com/utybo/Tegral/pull/23))
 
-  - Regular, non-extensible injection environments are now also required to implement a `getAllIdentifiers` function. ([#10](https://github.com/utybo/Tegral/pull/10))
+  - Regular, non-extensible injection environments are now also required
+    to implement a `getAllIdentifiers` function.
+    ([#10](https://github.com/utybo/Tegral/pull/10))
 
     - `EagerImmutableMetaEnvironment` has been updated to implement this.
 
@@ -244,9 +277,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
     - `DependencyTrackingInjectionEnvironment` has been updated to provide
       insights on dependencies.
 
-  - Added more tests in `(Extensible)EnvironmentBaseTest` for new resolution behaviors,
-    including aliases and proper parent resolution.
-    ([#23](https://github.com/utybo/Tegral/pull/23))
+  - Added more tests in `(Extensible)EnvironmentBaseTest` for new
+    resolution behaviors, including aliases and proper parent
+    resolution. ([#23](https://github.com/utybo/Tegral/pull/23))
 
 - `tegral-web-appdefaults`
 

docs/docs/modules/core/logging/index.mdx

@@ -31,7 +31,7 @@ Once installed, Tegral Logging will add a Logger factory within the DI environme
 ```kotlin
 class MyClass(scope: InjectionScope) {
     // highlight-start
-    private val logger: Logger by scope.factory()
+    private val logger: Logger by scope()
     // highlight-end
 
     fun printSomething() {
@@ -47,7 +47,7 @@ The name of the logger is automatically determined for the fully qualified name
 @LoggerName("my.class")
 // highlight-end
 class MyClass(scope: InjectionScope) {
-    private val logger: Logger by scope.factory()
+    private val logger: Logger by scope()
 
     // ...
 }

tegral-core/build.gradle

@@ -21,3 +21,4 @@ sourceSets {
 compileKotlin.dependsOn generateKotlin
 checkLicenseMain.dependsOn generateKotlin
 dokkaHtmlPartial.dependsOn generateKotlin
+sourcesJar.dependsOn generateKotlin

tegral-di/tegral-di-core/src/main/kotlin/guru/zoroark/tegral/di/extensions/factory/InjectableFactory.kt

@@ -104,6 +104,8 @@ inline fun <reified T : Any> ContextBuilderDsl.putFactory(noinline block: (Any)
  * DSL for injecting factory-made objects. Usage is `factory from scope`.
  */
 @TegralDsl
+@Suppress("DEPRECATION")
+@Deprecated("scope.factory() is no longer necessary, just use scope() instead.", ReplaceWith("this()"))
 inline fun <R : Any, reified T : Any> InjectionScope.factory(): ReadOnlyProperty<R, T> =
     this<InjectableFactory<T>>(typed<T>()) wrapInWithThisRef { thisRef, value -> value.make(thisRef as Any) }
 
@@ -115,6 +117,8 @@ inline fun <R : Any, reified T : Any> InjectionScope.factory(): ReadOnlyProperty
  *
  * This caches the result -- the `mapper` is executed lazily the first time the property is `get`ed.
  */
+@Deprecated("wrapIn is no longer necessary, use the IdentifierResolver mechanism for advanced injection behavior")
+@Suppress("DEPRECATION")
 inline infix fun <T, V, R : Any> ReadOnlyProperty<T, V>.wrapIn(
     crossinline mapper: (V) -> R
 ): SynchronizedLazyPropertyWrapper<T, R> =
@@ -123,6 +127,10 @@ inline infix fun <T, V, R : Any> ReadOnlyProperty<T, V>.wrapIn(
 /**
  * Identical to [wrapIn], but also gives you access to the object the property is owned by in the [mapper] lambda.
  */
+@Suppress("DeprecatedCallableAddReplaceWith", "DEPRECATION")
+@Deprecated(
+    "wrapInWithThisRef is no longer necessary, use the IdentifierResolver mechanism for advanced injection behavior"
+)
 inline infix fun <T, V, R : Any> ReadOnlyProperty<T, V>.wrapInWithThisRef(
     crossinline mapper: (T, V) -> R
 ): SynchronizedLazyPropertyWrapper<T, R> =
@@ -132,6 +140,7 @@ inline infix fun <T, V, R : Any> ReadOnlyProperty<T, V>.wrapInWithThisRef(
  * Wraps a property and maps its result using the given mapper.
  */
 @Suppress("FunctionName")
+@Deprecated("WrappedReadOnlyProperty is a support class for the wrapIn(WithThisRef) mechanism which is deprecated.")
 inline fun <T, V, R> WrappedReadOnlyProperty(
     original: ReadOnlyProperty<T, V>,
     crossinline mapper: (T, V) -> R
@@ -144,6 +153,9 @@ inline fun <T, V, R> WrappedReadOnlyProperty(
  * Similar to `lazy { }` but uses a property instead of a lambda for building. Inspired by the `SYNCHRONIZED` lazy
  * implementation.
  */
+@Deprecated(
+    "SynchronizedLazyPropertyWrapper is a support class for the wrapIn(WithThisRef) mechanism which is deprecated."
+)
 class SynchronizedLazyPropertyWrapper<T, V : Any>(private val wrappedProperty: ReadOnlyProperty<T, V>) :
     ReadOnlyProperty<T, V> {
     @Volatile

tegral-di/tegral-di-core/src/test/kotlin/guru/zoroark/tegral/di/extensions/FactoryExtensionTest.kt

@@ -24,6 +24,7 @@ import guru.zoroark.tegral.di.environment.InjectionScope
 import guru.zoroark.tegral.di.environment.MixedImmutableEnvironment
 import guru.zoroark.tegral.di.environment.get
 import guru.zoroark.tegral.di.environment.invoke
+import guru.zoroark.tegral.di.extensions.factory.factory
 import guru.zoroark.tegral.di.extensions.factory.putFactory
 import io.mockk.mockk
 import org.junit.jupiter.api.Test
@@ -201,4 +202,18 @@ class FactoryExtensionTest {
         }
         assertTrue(ex.message!!.startsWith("Cannot resolve a factory outside of a component"))
     }
+
+    @Suppress("DEPRECATION")
+    class DeprecatedUser(scope: InjectionScope) {
+        val a: A by scope.factory()
+    }
+
+    @Test
+    fun `Can use a factory using the deprecated syntax`() {
+        val env = tegralDi {
+            putFactory { A("AAA") }
+            put(::DeprecatedUser)
+        }
+        assertEquals("I am AAA's A", env.get<DeprecatedUser>().a.identity)
+    }
 }

tegral-logging/src/main/kotlin/guru/zoroark/tegral/logging/LoggerName.kt

@@ -23,7 +23,7 @@ import kotlin.reflect.full.findAnnotation
  * Note that this only affects loggers retrieved by using:
  *
  * ```kotlin
- * private val logger: Logger by scope.factory()
+ * private val logger: Logger by scope()
  * ```
  *
  * It has no effect when using SLF4J's `LoggerFactory.getLogger(...)`.

tegral-logging/src/main/kotlin/guru/zoroark/tegral/logging/LoggingFeature.kt

@@ -28,7 +28,7 @@ import ch.qos.logback.classic.Logger as LogbackLogger
 import org.slf4j.Logger as Slf4jLogger
 
 /**
- * A feature that adds logging support to the application via the `by scope.factory()` syntax.
+ * A feature that adds logging support to the application via the `by scope()` syntax.
  *
  * I.e., adds a `Logger` factory to the application.
  */