Provide integration points for SpeziNotifications, Swift 6 and silence some warnings

Sources/Spezi/Dependencies/DependencyManager.swift

@@ -59,12 +59,12 @@ public class DependencyManager: Sendable {
     /// Resolves the dependency order.
     ///
     /// After calling `resolve()` you can safely access `initializedModules`.
-    func resolve() {
+    func resolve() throws(DependencyManagerError) {
         while let nextModule = modulesWithDependencies.first {
-            push(nextModule)
+            try push(nextModule)
         }
 
-        injectDependencies()
+        try injectDependencies()
         assert(searchStacks.isEmpty, "`searchStacks` are not getting cleaned up!")
         assert(currentPushedModule == nil, "`currentPushedModule` is never reset!")
         assert(modulesWithDependencies.isEmpty, "modulesWithDependencies has remaining entries \(modulesWithDependencies)")
@@ -109,26 +109,26 @@ public class DependencyManager: Sendable {
         return order
     }
 
-    private func injectDependencies() {
+    private func injectDependencies() throws(DependencyManagerError) {
         // We inject dependencies into existingModules as well as a new dependency might be an optional dependency from a existing module
         // that wasn't previously injected.
         for module in initializedModules + existingModules {
             for dependency in module.dependencyDeclarations {
-                dependency.inject(from: self, for: module)
+                try dependency.inject(from: self, for: module)
             }
         }
     }
 
     /// Push a module on the search stack and resolve dependency information.
-    private func push(_ module: any Module) {
+    private func push(_ module: any Module) throws(DependencyManagerError) {
         assert(currentPushedModule == nil, "Module already pushed. Did the algorithm turn into an recursive one by accident?")
 
         currentPushedModule = ModuleReference(module)
         searchStacks[ModuleReference(module), default: []]
             .append(type(of: module))
 
         for dependency in module.dependencyDeclarations {
-            dependency.collect(into: self) // leads to calls to `require(_:defaultValue:)`
+            try dependency.collect(into: self) // leads to calls to `require(_:defaultValue:)`
         }
 
         finishSearch(for: module)
@@ -138,8 +138,8 @@ public class DependencyManager: Sendable {
     /// - Parameters:
     ///   - dependency: The type of the dependency that should be resolved.
     ///   - defaultValue: A default instance of the dependency that is used when the `dependencyType` is not present in the `initializedModules` or `modulesWithDependencies`.
-    func require<M: Module>(_ dependency: M.Type, type dependencyType: DependencyType, defaultValue: (() -> M)?) {
-        testForSearchStackCycles(M.self)
+    func require<M: Module>(_ dependency: M.Type, type dependencyType: DependencyType, defaultValue: (() -> M)?) throws(DependencyManagerError) {
+        try testForSearchStackCycles(M.self)
 
         // 1. Check if it is actively requested to load this module.
         if case .load = dependencyType {
@@ -177,18 +177,13 @@ public class DependencyManager: Sendable {
     ///   - module: The ``Module`` type to return.
     ///   - optional: Flag indicating if it is a optional return.
     /// - Returns: Returns the Module instance. Only optional, if `optional` is set to `true` and no Module was found.
-    func retrieve<M: Module>(module: M.Type, type dependencyType: DependencyType, for owner: any Module) -> M? {
+    func retrieve<M: Module>(module: M.Type, type dependencyType: DependencyType, for owner: any Module) throws(DependencyManagerError) -> M? {
         guard let candidate = existingModules.first(where: { type(of: $0) == M.self })
                 ?? initializedModules.first(where: { type(of: $0) == M.self }),
               let module = candidate as? M else {
-            precondition(
-                dependencyType.isOptional,
-                """
-                '\(type(of: owner)) requires dependency of type '\(M.self)' which wasn't configured.
-                Please make sure this module is configured by including it in the configuration of your `SpeziAppDelegate` or following \
-                Module-specific instructions.
-                """
-            )
+            if !dependencyType.isOptional {
+                throw DependencyManagerError.missingRequiredModule(module: "\(type(of: owner))", requiredModule: "\(M.self)")
+            }
             return nil
         }
 
@@ -231,20 +226,16 @@ public class DependencyManager: Sendable {
         searchStacks[ModuleReference(module)] = searchStack
     }
 
-    private func testForSearchStackCycles<M>(_ module: M.Type) {
+    private func testForSearchStackCycles<M>(_ module: M.Type) throws(DependencyManagerError) {
         if let currentPushedModule {
             let searchStack = searchStacks[currentPushedModule, default: []]
 
-            precondition(
-                !searchStack.contains(where: { $0 == M.self }),
-                """
-                The `DependencyManager` has detected a dependency cycle of your Spezi modules.
-                The current dependency chain is: \(searchStack.map { String(describing: $0) }.joined(separator: ", ")). \
-                The module '\(searchStack.last.unsafelyUnwrapped)' required '\(M.self)' which is contained in its own dependency chain.
-
-                Please ensure that the modules you use or develop can not trigger a dependency cycle.
-                """
-            )
+            if searchStack.contains(where: { $0 == M.self }) {
+                let module = "\(searchStack.last.unsafelyUnwrapped)"
+                let dependencyChain = searchStack
+                    .map { String(describing: $0) }
+                throw DependencyManagerError.searchStackCycle(module: module, requestedModule: "\(M.self)", dependencyChain: dependencyChain)
+            }
         }
     }
 }

Sources/Spezi/Dependencies/DependencyManagerError.swift

@@ -0,0 +1,35 @@
+//
+// This source file is part of the Stanford Spezi open-source project
+//
+// SPDX-FileCopyrightText: 2024 Stanford University and the project authors (see CONTRIBUTORS.md)
+//
+// SPDX-License-Identifier: MIT
+//
+
+
+enum DependencyManagerError: Error {
+    case searchStackCycle(module: String, requestedModule: String, dependencyChain: [String])
+    case missingRequiredModule(module: String, requiredModule: String)
+}
+
+
+extension DependencyManagerError: CustomStringConvertible {
+    var description: String {
+        switch self {
+        case let .searchStackCycle(module, requestedModule, dependencyChain):
+            """
+            The `DependencyManager` has detected a dependency cycle of your Spezi modules.
+            The current dependency chain is: \(dependencyChain.joined(separator: ", ")). \
+            The module '\(module)' required '\(requestedModule)' which is contained in its own dependency chain.
+
+            Please ensure that the modules you use or develop can not trigger a dependency cycle.
+            """
+        case let .missingRequiredModule(module, requiredModule):
+            """
+            '\(module) requires dependency of type '\(requiredModule)' which wasn't configured.
+            Please make sure this module is configured by including it in the configuration of your `SpeziAppDelegate` or following \
+            Module-specific instructions.
+            """
+        }
+    }
+}

Sources/Spezi/Dependencies/Property/DependencyCollection.swift

@@ -127,15 +127,15 @@ extension DependencyCollection: DependencyDeclaration {
     }
 
 
-    func collect(into dependencyManager: DependencyManager) {
+    func collect(into dependencyManager: DependencyManager) throws(DependencyManagerError) {
         for entry in entries {
-            entry.collect(into: dependencyManager)
+            try entry.collect(into: dependencyManager)
         }
     }
 
-    func inject(from dependencyManager: DependencyManager, for module: any Module) {
+    func inject(from dependencyManager: DependencyManager, for module: any Module) throws(DependencyManagerError) {
         for entry in entries {
-            entry.inject(from: dependencyManager, for: module)
+            try entry.inject(from: dependencyManager, for: module)
         }
     }
 

Sources/Spezi/Dependencies/Property/DependencyContext.swift

@@ -92,12 +92,12 @@ class DependencyContext<Dependency: Module>: AnyDependencyContext {
         }
     }
 
-    func collect(into dependencyManager: DependencyManager) {
-        dependencyManager.require(Dependency.self, type: type, defaultValue: defaultValue)
+    func collect(into dependencyManager: DependencyManager) throws(DependencyManagerError) {
+        try dependencyManager.require(Dependency.self, type: type, defaultValue: defaultValue)
     }
 
-    func inject(from dependencyManager: DependencyManager, for module: any Module) {
-        guard let dependency = dependencyManager.retrieve(module: Dependency.self, type: type, for: module) else {
+    func inject(from dependencyManager: DependencyManager, for module: any Module) throws(DependencyManagerError) {
+        guard let dependency = try dependencyManager.retrieve(module: Dependency.self, type: type, for: module) else {
             injectedDependency = nil
             return
         }

Sources/Spezi/Dependencies/Property/DependencyDeclaration.swift

@@ -28,13 +28,13 @@ protocol DependencyDeclaration {
 
     /// Request from the ``DependencyManager`` to collect all dependencies. Mark required by calling `DependencyManager/require(_:defaultValue:)`.
     @MainActor
-    func collect(into dependencyManager: DependencyManager)
+    func collect(into dependencyManager: DependencyManager) throws(DependencyManagerError)
     /// Inject the dependency instance from the ``DependencyManager``. Use `DependencyManager/retrieve(module:)`.
     /// - Parameters:
     ///   - dependencyManager: The dependency manager to inject the dependencies from.
     ///   - module: The module where the dependency declaration is located at.
     @MainActor
-    func inject(from dependencyManager: DependencyManager, for module: any Module)
+    func inject(from dependencyManager: DependencyManager, for module: any Module) throws(DependencyManagerError)
 
     @MainActor
     func inject(spezi: Spezi)

Sources/Spezi/Dependencies/Property/DependencyPropertyWrapper.swift

@@ -118,12 +118,12 @@ extension _DependencyPropertyWrapper: DependencyDeclaration {
         dependencies.dependencyRelation(to: module)
     }
 
-    func collect(into dependencyManager: DependencyManager) {
-        dependencies.collect(into: dependencyManager)
+    func collect(into dependencyManager: DependencyManager) throws(DependencyManagerError) {
+        try dependencies.collect(into: dependencyManager)
     }
 
-    func inject(from dependencyManager: DependencyManager, for module: any Module) {
-        dependencies.inject(from: dependencyManager, for: module)
+    func inject(from dependencyManager: DependencyManager, for module: any Module) throws(DependencyManagerError) {
+        try dependencies.inject(from: dependencyManager, for: module)
     }
 
     func uninjectDependencies(notifying spezi: Spezi) {

Sources/Spezi/Spezi/Spezi.swift

@@ -227,7 +227,11 @@
         let existingModules = self.modules
 
         let dependencyManager = DependencyManager(modules, existing: existingModules)
-        dependencyManager.resolve()
+        do {
+            try dependencyManager.resolve()
+        } catch {
+            preconditionFailure(error.description)
+        }
 
         implicitlyCreatedModules.formUnion(dependencyManager.implicitlyCreatedModules)
 
@@ -296,7 +300,11 @@
         // re-injecting all dependencies ensures that the unloaded module is cleared from optional Dependencies from
         // pre-existing Modules.
         let dependencyManager = DependencyManager([], existing: modules)
-        dependencyManager.resolve()
+        do {
+            try dependencyManager.resolve()
+        } catch {
+            preconditionFailure("Internal inconsistency. Repeated dependency resolve resulted in error: \(error)")
+        }
 
         module.clear() // automatically removes @Provide values and recursively unloads implicitly created modules
     }

Sources/Spezi/Standard/StandardPropertyWrapper.swift

@@ -41,6 +41,7 @@
     func inject(spezi: Spezi) {
         guard let standard = spezi.standard as? Constraint else {
             let standardType = type(of: spezi.standard)
+            // TODO: allow this to get throwing!
             preconditionFailure(
                 """
                 The `Standard` defined in the `Configuration` does not conform to \(String(describing: Constraint.self)).

Tests/SpeziTests/DependenciesTests/DependencyBuilderTests.swift

@@ -61,7 +61,7 @@ final class DependencyBuilderTests: XCTestCase {
         let module = ExampleDependencyModule {
             ExampleDependentModule()
         }
-        let initializedModules = DependencyManager.resolve([module])
+        let initializedModules = DependencyManager.resolveWithoutErrors([module])
         XCTAssertEqual(initializedModules.count, 2)
         _ = try XCTUnwrap(initializedModules[0] as? ExampleDependentModule)
         _ = try XCTUnwrap(initializedModules[1] as? ExampleDependencyModule)

Tests/SpeziTests/DependenciesTests/DependencyManager+OneShot.swift

@@ -7,12 +7,19 @@
 //
 
 @testable import Spezi
+import XCTest
 
 
 extension DependencyManager {
-    static func resolve(_ modules: [any Module]) -> [any Module] {
+    static func resolve(_ modules: [any Module]) throws -> [any Module] {
         let dependencyManager = DependencyManager(modules)
-        dependencyManager.resolve()
+        try dependencyManager.resolve()
+        return dependencyManager.initializedModules
+    }
+
+    static func resolveWithoutErrors(_ modules: [any Module], file: StaticString = #filePath, line: UInt = #line) -> [any Module] {
+        let dependencyManager = DependencyManager(modules)
+        XCTAssertNoThrow(try dependencyManager.resolve(), file: file, line: line)
         return dependencyManager.initializedModules
     }
 }