Enable injecting optional properties that are only fulfilled when available (#168)

It can be really useful to share an `@Instantiable` across boundaries
where only some of their properties exist

Author: dfed

Documentation/Manual.md

@@ -243,7 +243,7 @@ Here we have an example of a `UserManager` type that is received as a `UserVendo
 
 ```swift
 public struct User {
-    ... // User information.  
+    ... // User information.
 }
 
 public protocol UserVendor {
@@ -274,8 +274,8 @@ public struct LoggedInView: View, Instantiable {
     public var body: some View {
         ... // A logged in user experience
     }
-    
-    @Forwarded private let userManager: UserManager 
+
+    @Forwarded private let userManager: UserManager
 
     @Instantiated private let profileViewBuilder: Instantiator<ProfileView>
 }
@@ -310,6 +310,62 @@ public struct EditProfileView: View, Instantiable {
 }
 ```
 
+#### Conditionally receiving dependencies
+
+It is possible to receive an optional dependency only when that dependency has been `@Instantiated` or `@Forwarded` by an object higher up in the dependency tree with the `@Received(onlyIfAvailable: true)` macro. This functionality is particularly useful when `@Instantiable` types are created by multiple `@Instantiable` parents with different available dependencies.
+
+Here’s an example of a feed view in a social app that optionally receives a `user` object:
+
+```swift
+public struct User {
+    ... // User information.
+}
+
+import SwiftUI
+
+@Instantiable
+public struct LoggedOutView: View, Instantiable {
+    public init(feedViewBuilder: Instantiator<FeedView>) {
+        self.feedViewBuilder = feedViewBuilder
+    }
+
+    public var body: some View {
+        ... // A logged out user experience that shows a feed
+    }
+
+    @Instantiated private let feedViewBuilder: Instantiator<FeedView>
+}
+
+@Instantiable
+public struct LoggedInView: View, Instantiable {
+    public init(user: User, feedViewBuilder: Instantiator<FeedView>) {
+        self.user = user
+        self.feedViewBuilder = feedViewBuilder
+    }
+
+    public var body: some View {
+        ... // A logged in user experience that shows a feed customized for this user
+    }
+
+    @Forwarded private let user: User
+
+    @Instantiated private let feedViewBuilder: Instantiator<FeedView>
+}
+
+@Instantiable
+public struct FeedView: View, Instantiable {
+    public init(user: User?) {
+        self.user = user
+    }
+
+    public var body: some View {
+        ... // A feed experience that is customized when a user is present.
+    }
+
+    @Received(onlyIfAvailable: true) private let user: User?
+}
+```
+
 ## Delayed instantiation
 
 When you want to instantiate a dependency after `init(…)`, you need to declare an `Instantiator<Dependency>`-typed property as `@Instantiated` or `@Received`. Deferred instantiation is useful in situations where a dependency is expensive to create or only required under certain conditions (e.g., creating a detailed view for a selected item in a list).

Examples/ExampleCocoaPodsIntegration/safeditool.sh

@@ -2,7 +2,7 @@
 
 set -e
 
-VERSION='1.1.0'
+VERSION='1.2.2'
 SAFEDI_LOCATION="$BUILD_DIR/SafeDITool-Release/$VERSION/safeditool"
 
 # Download the tool from Github releases.

Plugins/Shared.swift

@@ -29,7 +29,7 @@ import PackagePlugin
 			// As of Xcode 15.0, Xcode command plugins have no way to read the package manifest, therefore we must hardcode the version number.
 			// It is okay for this number to be behind the most current release if the inputs and outputs to SafeDITool have not changed.
 			// Unlike SPM plugins, Xcode plugins can not determine the current version number, so we must hardcode it.
-			"1.2.3"
+			"1.3.0"
 		}
 
 		var safeDIOrigin: URL {

SafeDI.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name     = 'SafeDI'
-  s.version  = '1.2.2'
+  s.version  = '1.3.0'
   s.summary  = 'Compile-time-safe dependency injection'
   s.homepage = 'https://github.com/dfed/SafeDI'
   s.license  = 'MIT'

Sources/SafeDI/Decorators/Received.swift

@@ -25,8 +25,11 @@
 ///     @Received private let dependency: DependencyType
 ///
 /// Note that the access level of the dependency in the above example does not affect the dependency tree – a `private` dependency can still be `@Received` by `@Instantiable`-decorated types further down the dependency tree.
+///
+/// - Parameters:
+///   - onlyIfAvailable: Whether to allow the dependency to be received only when a parent has made it available.
 @attached(peer)
-public macro Received() = #externalMacro(module: "SafeDIMacros", type: "InjectableMacro")
+public macro Received(onlyIfAvailable: Bool = false) = #externalMacro(module: "SafeDIMacros", type: "InjectableMacro")
 
 /// Marks a SafeDI dependency that is instantiated or forwarded by an `@Instantiable` instance higher up in the dependency tree whose name and/or type is being changed from the dependency‘s initial declaration.
 ///
@@ -44,11 +47,13 @@ public macro Received() = #externalMacro(module: "SafeDIMacros", type: "Injectab
 ///   - fulfilledByDependencyNamed: The name of the property belonging to an `@Instantiable` instance higher up in the dependency tree whose name and/or type is being changed from the dependency‘s initial declaration.
 ///   - concreteType: The type of the property belonging to an `@Instantiable` instance higher up in the dependency tree whose name and/or type is being changed from the dependency‘s initial declaration.
 ///   - erasedToConcreteExistential: Whether the concrete type is being erased to a concrete existential type – a type that encapsulates a value conforming to a protocol without revealing the underlying type. Set this parameter to `true` to encapsulate the renamed or retyped instance of `concreteType` in a no-label initializer of the property’s type (e.g. `AnyDependencyType(dependency)`).
+///   - onlyIfAvailable: Whether to allow the dependency to be received only when a parent has made it available.
 ///
 ///  - SeeAlso: [The Swift Programming Lanaguage’s explanation of existential types](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/opaquetypes/#Boxed-Protocol-Types)
 @attached(peer)
 public macro Received<T>(
 	fulfilledByDependencyNamed: StaticString,
 	ofType concreteType: T.Type,
-	erasedToConcreteExistential: Bool = false
+	erasedToConcreteExistential: Bool = false,
+	onlyIfAvailable: Bool = false
 ) = #externalMacro(module: "SafeDIMacros", type: "InjectableMacro")

Sources/SafeDICore/Errors/FixableInjectableError.swift

@@ -22,11 +22,14 @@ import SwiftDiagnostics
 
 public enum FixableInjectableError: DiagnosticError {
 	case unexpectedMutable
+	case onlyIfAvailableNotOptionalSpelledWithQuestionMark
 
 	public var description: String {
 		switch self {
 		case .unexpectedMutable:
 			"Dependency can not be mutable unless it is decorated with a property wrapper. Mutations to a dependency are not propagated through the dependency tree."
+		case .onlyIfAvailableNotOptionalSpelledWithQuestionMark:
+			"The type of a dependency decorated with `onlyIfAvailable: true` must be marked as optional utilizing the `?` spelling"
 		}
 	}
 
@@ -44,7 +47,8 @@ public enum FixableInjectableError: DiagnosticError {
 		init(error: FixableInjectableError) {
 			diagnosticID = MessageID(domain: "\(Self.self)", id: error.description)
 			severity = switch error {
-			case .unexpectedMutable:
+			case .unexpectedMutable,
+			     .onlyIfAvailableNotOptionalSpelledWithQuestionMark:
 				.error
 			}
 			message = error.description
@@ -62,6 +66,8 @@ public enum FixableInjectableError: DiagnosticError {
 			message = switch error {
 			case .unexpectedMutable:
 				"Replace `var` with `let`"
+			case .onlyIfAvailableNotOptionalSpelledWithQuestionMark:
+				"Mark the type as optional using `?`"
 			}
 			fixItID = MessageID(domain: "\(Self.self)", id: error.description)
 		}

Sources/SafeDICore/Extensions/AttributeSyntaxExtensions.swift

@@ -123,6 +123,19 @@ extension AttributeSyntax {
 		return erasedToConcreteExistentialLabeledExpression.expression
 	}
 
+	public var onlyIfAvailable: ExprSyntax? {
+		guard let arguments,
+		      let labeledExpressionList = LabeledExprListSyntax(arguments),
+		      let erasedToConcreteExistentialLabeledExpression = labeledExpressionList.reversed().first(where: {
+		      	$0.label?.text == "onlyIfAvailable"
+		      })
+		else {
+			return nil
+		}
+
+		return erasedToConcreteExistentialLabeledExpression.expression
+	}
+
 	public var fulfillingTypeDescription: TypeDescription? {
 		if let expression = fulfilledByType,
 		   let stringLiteral = StringLiteralExprSyntax(expression),
@@ -134,7 +147,7 @@ extension AttributeSyntax {
 		}
 	}
 
-	public var erasedToConcreteExistentialType: Bool {
+	public var erasedToConcreteExistentialValue: Bool {
 		guard let erasedToConcreteExistential,
 		      let erasedToConcreteExistentialType = BooleanLiteralExprSyntax(erasedToConcreteExistential)
 		else {
@@ -143,4 +156,14 @@ extension AttributeSyntax {
 		}
 		return erasedToConcreteExistentialType.literal.text == "true"
 	}
+
+	public var onlyIfAvailableValue: Bool {
+		guard let onlyIfAvailable,
+		      let onlyIfAvailable = BooleanLiteralExprSyntax(onlyIfAvailable)
+		else {
+			// Default value for the `onlyIfAvailable` parameter is `false`.
+			return false
+		}
+		return onlyIfAvailable.literal.text == "true"
+	}
 }

Sources/SafeDICore/Generators/DependencyTreeGenerator.swift

@@ -99,12 +99,26 @@ public actor DependencyTreeGenerator {
 			case let .unfulfillableProperties(unfulfillableProperties):
 				"""
 				\(unfulfillableProperties.map {
-					"""
-					@\(Dependency.Source.receivedRawValue) property `\($0.property.asSource)` is not @\(Dependency.Source.instantiatedRawValue) or @\(Dependency.Source.forwardedRawValue) in chain:\n\t\(([$0.instantiable.concreteInstantiable] + $0.parentStack)
-						.reversed()
-						.map(\.asSource)
-						.joined(separator: " -> "))\($0.suggestedAlternatives.isEmpty ? "" : "\n\nDid you mean one of the following available properties?\n\($0.suggestedAlternatives.map { "\t`\($0.asSource)`" }.joined(separator: "\n"))")
-					"""
+					if $0.property.typeDescription.isOptional,
+					   let nonOptionalAlternative = $0.suggestedAlternatives.first(where: { [unfulfilledProperty = $0.property] alternative in
+					   	alternative.label == unfulfilledProperty.label
+					   		&& alternative.typeDescription == unfulfilledProperty.typeDescription.unwrapped
+					   })
+					{
+						"""
+						@\(Dependency.Source.receivedRawValue) property `\($0.property.asSource)` is not @\(Dependency.Source.instantiatedRawValue) or @\(Dependency.Source.forwardedRawValue) in chain:\n\t\(([$0.instantiable.concreteInstantiable] + $0.parentStack)
+							.reversed()
+							.map(\.asSource)
+							.joined(separator: " -> "))\($0.suggestedAlternatives.isEmpty ? "" : "\n\nThe non-optional `\(nonOptionalAlternative.asSource)` is available in chain. Did you mean to decorate this property with `@\(Dependency.Source.receivedRawValue)(onlyIfAvailable: true)`?")
+						"""
+					} else {
+						"""
+						@\(Dependency.Source.receivedRawValue) property `\($0.property.asSource)` is not @\(Dependency.Source.instantiatedRawValue) or @\(Dependency.Source.forwardedRawValue) in chain:\n\t\(([$0.instantiable.concreteInstantiable] + $0.parentStack)
+							.reversed()
+							.map(\.asSource)
+							.joined(separator: " -> "))\($0.suggestedAlternatives.isEmpty ? "" : "\n\nDid you mean one of the following available properties?\n\($0.suggestedAlternatives.map { "\t`\($0.asSource)`" }.joined(separator: "\n"))")
+						"""
+					}
 				}
 				.sorted()
 				.joined(separator: "\n\n"))
@@ -163,6 +177,7 @@ public actor DependencyTreeGenerator {
 						try typeDescriptionToScopeMap[$0]?.createScopeGenerator(
 							for: nil,
 							propertyStack: [],
+							receivableProperties: [],
 							erasedToConcreteExistential: false
 						)
 					}
@@ -279,11 +294,12 @@ public actor DependencyTreeGenerator {
 							erasedToConcreteExistential: erasedToConcreteExistential
 						))
 					}
-				case let .aliased(fulfillingProperty, erasedToConcreteExistential):
+				case let .aliased(fulfillingProperty, erasedToConcreteExistential, onlyIfAvailable):
 					scope.propertiesToGenerate.append(.aliased(
 						dependency.property,
 						fulfilledBy: fulfillingProperty,
-						erasedToConcreteExistential: erasedToConcreteExistential
+						erasedToConcreteExistential: erasedToConcreteExistential,
+						onlyIfAvailable: onlyIfAvailable
 					))
 				case .forwarded, .received:
 					continue
@@ -302,30 +318,12 @@ public actor DependencyTreeGenerator {
 			propertyStack: OrderedSet<Property>,
 			root: TypeDescription
 		) throws {
-			let createdProperties = Set(
-				scope
-					.instantiable
-					.dependencies
-					.filter {
-						switch $0.source {
-						case .instantiated, .forwarded:
-							// The source is being injected into the dependency tree.
-							true
-						case .aliased:
-							// This property is being re-injected into the dependency tree under a new alias.
-							true
-						case .received:
-							false
-						}
-					}
-					.map(\.property)
-			)
 			if let property {
 				func validateNoCycleInReceivedProperties(
 					scope: Scope,
 					receivedPropertyStack: OrderedSet<Property>
 				) throws {
-					for childProperty in scope.receivedProperties {
+					for childProperty in scope.requiredReceivedProperties {
 						guard childProperty != property else {
 							throw DependencyTreeGeneratorError.receivedConstantCycleDetected(
 								instantiated: property,
@@ -352,9 +350,9 @@ public actor DependencyTreeGenerator {
 				)
 			}
 
-			for receivedProperty in scope.receivedProperties {
+			for receivedProperty in scope.requiredReceivedProperties {
 				let parentContainsProperty = receivableProperties.contains(receivedProperty)
-				let propertyIsCreatedAtThisScope = createdProperties.contains(receivedProperty)
+				let propertyIsCreatedAtThisScope = scope.createdProperties.contains(receivedProperty)
 				if !parentContainsProperty, !propertyIsCreatedAtThisScope {
 					if property != nil {
 						// This property is in a dependency tree and is unfulfillable. Record the problem.
@@ -484,9 +482,21 @@ extension TypeDescription {
 		switch self {
 		case let .nested(name, _, generics):
 			.simple(name: name, generics: generics)
-		case let .any(typeDescription), let .implicitlyUnwrappedOptional(typeDescription), let .optional(typeDescription), let .some(typeDescription):
+		case let .any(typeDescription),
+		     let .implicitlyUnwrappedOptional(typeDescription),
+		     let .optional(typeDescription),
+		     let .some(typeDescription):
 			typeDescription.leastQualifiedTypeDescription
-		case .array, .attributed, .closure, .composition, .dictionary, .metatype, .simple, .tuple, .unknown, .void:
+		case .array,
+		     .attributed,
+		     .closure,
+		     .composition,
+		     .dictionary,
+		     .metatype,
+		     .simple,
+		     .tuple,
+		     .unknown,
+		     .void:
 			self
 		}
 	}