swift-factory-di

Files (4)

• SKILL.md
• api-reference.md · references/
• migration-guide.md · references/
• testing-patterns.md · references/

SKILL.md (first lines)

# Factory DI — Reference & Optimization Guide

> Based on [Factory](https://github.com/hmlongco/Factory) **2.5.3** by [Michael Long (hmlongco)](https://github.com/hmlongco) — a compile-time safe, container-based dependency injection framework for Swift.
>
> This skill is an unofficial community resource. Factory is licensed under the MIT License.

Factory is under 1000 lines of executable code, yet provides containers, scopes, contexts, decorators, parameter injection, and full SwiftUI integration. It requires no code generation, build scripts, or runtime reflection.

As of 2.5.0, the recommended import is `import FactoryKit` (not `import Factory`) to avoid SPM naming conflicts.

---

## Core Patterns

### Defining a Factory

Factories are computed properties on container extensions. Each returns a `Factory<T>` that wraps a closure producing the dependency:

```swift
extension Container {
    var networkService: Factory<NetworkServiceType> {
        self { URLSessionNetworkService() }
    }
}
```

The `self { ... }` syntax is shorthand for `Factory(self) { ... }`. The closure is `@Sendable`.

### Resolving Dependencies

```swift
// Direct resolution
let service = Container.shared.networkService()

// Property wrapper (uses Container.shared implicitly)
@Injected(\.networkService) var service

// From a custom container
@Injected(\MyContainer.networkService) var service
```

### Constructor Injection (Preferred)

Wire dependencies through the container itself — this keeps the dependency graph visible:

```swift
extension Container {
    var repository: Factory<UserRepository> {
        self { UserRepository(network: self.networkService()) }
    }
}
```

### Protocol-Based Registration

Always register against protocols for testability:

```swift
var networkService: Factory<NetworkServiceType> {  // protocol, not concrete
    self { URLSessionNetworkService() }
}
```

### Custom Containers

For modular apps, define separate containers per feature or module:

```swift
final class AuthContainer: SharedContainer {
    static let shared = AuthContainer()
    let manager = ContainerManager()

    var authService: Factory<AuthServiceType> {
        self { KeychainAuthService() }
    }
}
```

---

## Property Wrapper Selection Guide

Choosing the right wrapper matters for performance, correctness, and lifecycle:

| Wrapper | Resolves | Re-resolves | Holds | Use when |
|---------|----------|-------------|-------|----------|
| `@Injected` | At init | Never | Strong | Default choice. Dependency is needed immediately and won't change. |
| `@LazyInjected` | First access | Never | Strong | Resolution is expensive or has side effects; delay until actually needed. |
| `@WeakLazyInjected` | First access | If released | Weak | Breaking retain cycles or shared-scope dependencies you don't want to own. |
| `@DynamicInjected` | Every access | Every access | None | Dependency may change at runtime (e.g., after re-registration). Rare. |
| `@InjectedObject` | At init | Never | Strong (StateObject) | SwiftUI views needing an `ObservableObject` view model. Owns the instance. |
| `@InjectedObservable` | At init | Never | Strong (State) | SwiftUI views with iOS 17+ `@Observable` types. |

**Rules of thumb:**
- Start with `@Injected` unless you have a reason not to.
- In SwiftUI views, use `@InjectedObject` (pre-iOS 17) or `@InjectedObservable` (iOS 17+) instead of manually wrapping in `@StateObject`/`@State`.
- `@DynamicInjected` has a resolution cost on every property access — only use it when the registration genuinely changes at runtime.

### LazyInjected Extras

`@LazyInjected` exposes helpers through its projected value (`$`):

```swift
@LazyInjected(\.heavyService) var service

// Check if resolved yet
if let resolved = $service.resolvedOrNil() { ... }

// Force resolution
$service.resolve()
```

---

## Scope Selection Guide

Scopes control how long a resolved instance lives. The default is `.unique` (new instance every time).

```

From guillevc/skills, MIT.

More from guillevc/skills