agentsclimarketplace

Swift dependency injection

Skill wei18/apple-dev-skills/apple-dev-skills/skills/swift-dependency-injection

Testable seam design via protocol injection, SwiftUI environment, and task-local overrides; Swift 6 Sendable rules for dependencies; mentions pointfreeco/swift-dependencies and Factory as library options. Invoke when designing a new service seam, asking "how do I inject CloudKit/network/clock", setting up a composition root, or making code testable.From its SKILL.md

Install
npx -y skills add wei18/apple-dev-skills --skill swift-dependency-injection

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 18 stars18 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

7.9 KB, ~1.7k tokens by cl100k_base, as published. Nobody here has run it

Swift Dependency Injection

When to invoke

  • Designing a new service boundary (CloudKit, networking, clock, RNG, notifications).
  • Asking "how do I make this testable", "how do I inject X", or "should I use a singleton here".
  • Establishing a composition root for a new app target or module.
  • Reviewing code that reaches out to global state, URLSession.shared, Date(), or UUID().
  • Choosing between constructor injection and SwiftUI environment injection.

Core principle: one composition root

All concrete implementations are wired in a single place — typically makeApp(...) or a DependencyContainer struct built in the @main entry point. Every layer below receives its dependencies through initialiser parameters, not by reaching up to a global. This makes the entire wiring visible in one screen of code and means tests can substitute any dependency without touching production paths.

// App entry point — the only place that knows about live implementations
@main struct MyApp: App {
    let root = makeApp()  // returns a pure value/struct carrying live deps
    var body: some Scene { ... }
}

func makeApp() -> AppRoot {
    AppRoot(
        storage: LiveStorage(),
        clock: ContinuousClock(),
        rng: SystemRandomNumberGenerator()
    )
}

No layer below makeApp imports LiveStorage or any other concrete type.

Protocol-witness vs protocol-existential

Both are idiomatic Swift; the choice is a matter of callsite ergonomics:

  • Protocol existential (any ServiceProtocol): clear intent, straightforward generics. Works well for most app-layer seams. Requires the protocol to be Sendable if passed across actors.
  • Struct protocol witness (struct ServiceClient { var fetch: @Sendable () async throws -> [Item] }): eliminates dynamic dispatch, composes without any, easier to construct partial fakes. Favoured by pointfreeco/swift-dependencies. Good when a service has a small, stable API surface.

Either is fine. Pick the one that reads naturally; don't mix both styles for the same seam.

SwiftUI environment injection

SwiftUI's @Environment and EnvironmentValues let you propagate dependencies down a view tree without threading them through every intermediate View:

// Define a key
struct StorageKey: EnvironmentKey {
    static let defaultValue: any StorageProtocol = NoopStorage()
}
extension EnvironmentValues {
    var storage: any StorageProtocol {
        get { self[StorageKey.self] }
        set { self[StorageKey.self] = newValue }
    }
}

// Inject at the root
ContentView()
    .environment(\.storage, LiveStorage())

// Consume deep in the tree — no init threading required
struct DetailView: View {
    @Environment(\.storage) var storage
}

Trade-off vs constructor injection: environment injection reduces boilerplate for deeply nested trees but makes the dependency implicit — a reader of DetailView must look up the environment key to understand what it needs. Constructor injection is explicit and compiler-enforced. For logic-heavy types (view-models, service objects), prefer constructor injection; reserve environment for cross-cutting concerns (theme, locale, feature flags, testable clocks).

In tests, inject the test double the same way:

DetailView()
    .environment(\.storage, FakeStorage())

Test doubles: fakes over mocks

Prefer fakes (lightweight in-memory implementations) and stubs (hardcoded return values) over mock frameworks. Mocks couple tests to implementation details (call order, argument matching); fakes couple tests only to the contract.

struct FakeStorage: StorageProtocol {
    var items: [Item] = []
    func save(_ item: Item) async throws { items.append(item) }
    func loadAll() async throws -> [Item] { items }
}

Injecting a controllable clock eliminates time-dependent flakiness:

// Production
let clock: any Clock<Duration> = ContinuousClock()

// Test
let clock = TestClock<Duration>()  // advance manually
await clock.advance(by: .seconds(5))

Injecting a seeded RNG makes random behaviour deterministic:

// SplitMix64 or any var rng: RandomNumberGenerator
var rng: any RandomNumberGenerator = SystemRandomNumberGenerator()
// In tests:
var rng: any RandomNumberGenerator = SeededGenerator(seed: 42)

@TaskLocal overrides

@TaskLocal is a lightweight alternative when you need to override a dependency for the duration of an async call tree without restructuring the call sites — useful for request-scoped values like loggers, trace IDs, or feature-flag snapshots:

enum Current {
    @TaskLocal static var clock: any Clock<Duration> = ContinuousClock()
}

// In test
await Current.$clock.withValue(TestClock()) {
    await systemUnderTest.run()
}

Avoid @TaskLocal for dependencies that should be visible in the public interface of a type; reserve it for cross-cutting infrastructure that every caller in the task tree shares implicitly.

Swift 6 concurrency rules for dependencies

  • Any type passed across actor boundaries — including a dependency — must conform to Sendable.
  • Protocol requirements that are called from concurrent contexts must be async (or the protocol itself must be @MainActor-isolated).
  • Closures stored in a struct client must be @Sendable:
struct AnalyticsClient: Sendable {
    var track: @Sendable (Event) async -> Void
}
  • Avoid global var singletons with mutable state; they require either an actor wrapper or @unchecked Sendable with manual synchronisation. Neither is free.
  • For third-party dependencies that predate Swift 6 strict concurrency, use @preconcurrency import ThirdPartyKit at the import site to suppress errors during transition; file an issue or switch packages if the lag is long-lived.

Library options

  • pointfreeco/swift-dependencies (MIT) — implements the struct-witness / environment / @TaskLocal pattern described above with a macro-driven @Dependency property wrapper. Provides withDependencies { ... } for scoped test overrides. Worth adopting when the team wants a shared convention rather than hand-rolling keys.
  • Factory (MIT, by Michael Long) — registration-based container closer to traditional IoC. Useful when the codebase already organises dependencies as registered services rather than value-type structs.

Both are valid; they solve the same problem with different ergonomics. Evaluate against the existing codebase shape before adding a new dependency.

Verification checklist

  • No layer below the composition root imports a concrete implementation type (Live*, URLSession.shared, Date(), UUID()).
  • All protocol types (or struct clients) used across actor boundaries declare Sendable.
  • Async protocol requirements are async throws; synchronous fakes return immediately (no Task.sleep in a fake).
  • Each test constructs its own fake/stub — no shared mutable test state at module level.
  • The composition root (makeApp(...)) is the only call site that knows about live implementations.
  • A controllable clock / seeded RNG is injected wherever production code calls Date(), UUID(), or random(in:).

Related skills

  • swiftpm-modularization: put each seam (protocol + fake) in its own target so test targets can import the fake without importing the live implementation.
  • swift6-concurrency: Sendable requirements, @preconcurrency, and actor-isolated types that affect dependency design.
  • swift-testing-baseline: shared fake targets (<Module>Testing), protocol injection for CloudKit / Game Center, and why integration tests never touch real networks.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.