Update docs

Author: mbrandonw

Examples/CaseStudies/SwiftUICaseStudies/02-Effects-WebSocket.swift

@@ -206,7 +206,14 @@ struct WebSocketClient {
 }
 
 extension WebSocketClient: DependencyKey {
-  static let liveValue: Self = {
+  static var liveValue: Self {
+    return Self(
+      open: { await WebSocketActor.shared.open(id: $0, url: $1, protocols: $2) },
+      receive: { try await WebSocketActor.shared.receive(id: $0) },
+      send: { try await WebSocketActor.shared.send(id: $0, message: $1) },
+      sendPing: { try await WebSocketActor.shared.sendPing(id: $0) }
+    )
+
     final actor WebSocketActor: GlobalActor {
       final class Delegate: NSObject, URLSessionWebSocketDelegate {
         var continuation: AsyncStream<Action>.Continuation?
@@ -305,14 +312,7 @@ extension WebSocketClient: DependencyKey {
         self.dependencies[id] = nil
       }
     }
-
-    return Self(
-      open: { await WebSocketActor.shared.open(id: $0, url: $1, protocols: $2) },
-      receive: { try await WebSocketActor.shared.receive(id: $0) },
-      send: { try await WebSocketActor.shared.send(id: $0, message: $1) },
-      sendPing: { try await WebSocketActor.shared.sendPing(id: $0) }
-    )
-  }()
+  }
 
   static let testValue = Self(
     open: XCTUnimplemented("\(Self.self).open", placeholder: AsyncStream.never),

Examples/SpeechRecognition/SpeechRecognition/SpeechClient/Client.swift

@@ -19,7 +19,7 @@ struct SpeechClient {
 }
 
 extension SpeechClient: TestDependencyKey {
-  static let previewValue = {
+  static var previewValue: Self {
     let isRecording = ActorIsolated(false)
 
     return Self(
@@ -64,8 +64,8 @@ extension SpeechClient: TestDependencyKey {
         }
       }
     )
-  }()
-
+  }
+ 
   static let testValue = Self(
     finishTask: XCTUnimplemented("\(Self.self).finishTask"),
     requestAuthorization: XCTUnimplemented(

Examples/SpeechRecognition/SpeechRecognition/SpeechClient/Live.swift

@@ -2,7 +2,7 @@ import ComposableArchitecture
 import Speech
 
 extension SpeechClient: DependencyKey {
-  static let liveValue = {
+  static var liveValue: Self {
     let speech = Speech()
     return Self(
       finishTask: {
@@ -20,7 +20,7 @@ extension SpeechClient: DependencyKey {
         return await speech.startTask(request: request)
       }
     )
-  }()
+  }
 }
 
 private actor Speech {

Examples/SpeechRecognition/SpeechRecognition/SpeechRecognition.swift

@@ -152,7 +152,6 @@ struct SpeechRecognitionView_Previews: PreviewProvider {
       store: Store(
         initialState: SpeechRecognition.State(transcribedText: "Test test 123"),
         reducer: SpeechRecognition()
-          .dependency(\.speechClient, .liveValue)
       )
     )
   }

Examples/VoiceMemos/VoiceMemos/AudioRecorderClient/AudioRecorderClient.swift

@@ -11,7 +11,7 @@ struct AudioRecorderClient {
 }
 
 extension AudioRecorderClient: TestDependencyKey {
-  static let previewValue = {
+  static var previewValue: Self {
     let isRecording = ActorIsolated(false)
     let currentTime = ActorIsolated(0.0)
 
@@ -31,7 +31,7 @@ extension AudioRecorderClient: TestDependencyKey {
         await currentTime.setValue(0)
       }
     )
-  }()
+  }
 
   static let testValue = Self(
     currentTime: XCTUnimplemented("\(Self.self).currentTime", placeholder: nil),

Examples/VoiceMemos/VoiceMemos/AudioRecorderClient/LiveAudioRecorderClient.swift

@@ -2,15 +2,15 @@ import AVFoundation
 import ComposableArchitecture  // TODO: Should `UncheckedSendable` live in `Dependencies`?
 
 extension AudioRecorderClient: DependencyKey {
-  static let liveValue: Self = {
+  static var liveValue: Self {
     let audioRecorder = AudioRecorder()
     return Self(
       currentTime: { await audioRecorder.currentTime },
       requestRecordPermission: { await AudioRecorder.requestPermission() },
       startRecording: { url in try await audioRecorder.start(url: url) },
       stopRecording: { await audioRecorder.stop() }
     )
-  }()
+  }
 }
 
 private actor AudioRecorder {

Sources/ComposableArchitecture/Documentation.docc/Articles/DependencyManagement.md

@@ -439,16 +439,6 @@ extension AudioPlayerClient: DependencyKey {
 }
 ```
 
-> Tip: The live, preview and test values provided to the `DependencyKey` conformance should
-typically be `static let`'s, and never computed `static var`'s. If you need to perform some work
-to construct the value, then you can wrap it in a closure that is invoked immediately:
->
-> ```swift
-> static let liveValue = {
->   // …
-> }()
-> ```
-
 If you design your dependencies in this way you can pick which dependency endpoints you need in your
 feature. For example, if you have a feature that needs an audio player to do its job, but it only
 needs the `play` endpoint, and doesn't need to loop, set volume or stop audio, then you can specify

Sources/Dependencies/DependencyKey.swift

@@ -11,6 +11,44 @@ import XCTestDynamicOverlay
 /// ``liveValue`` is accessed while your feature runs in a `TestStore` a test failure will be
 /// triggered.
 ///
+/// To add a `UserClient` dependency that can fetch and save user values can be done like so:
+///
+/// ```swift
+/// // The user client dependency.
+/// struct UserClient {
+///   var fetchUser: (User.ID) async throws -> User
+///   var saveUser: (User) async throws -> Void
+/// }
+/// // Conform to DependencyKey to provide a live implementation of
+/// // the interface.
+/// extension UserClient: DependencyKey {
+///   static let liveValue = Self(
+///     fetchUser: { /* Make request to fetch user */ },
+///     saveUser: { /* Make request to save user */ }
+///   )
+/// }
+/// // Register the dependency within DependencyValues.
+/// extension DependencyValues {
+///   var userClient: UserClient {
+///     get { self[UserClient.self] }
+///     set { self[UserClient.self] = newValue }
+///   }
+/// }
+/// ```
+///
+/// When a dependency is first accessed its value is cached so that it will not be requested again.
+/// This means if your `liveValue` is implemented as a computed property instead of a `static let`,
+/// then it will only be called a single time:
+///
+/// ```swift
+/// extension UserClient: DependencyKey {
+///   static var liveValue: Self {
+///     // Only called once when dependency is first accessed.
+///     return Self(…)
+///   }
+/// }
+/// ```
+///
 /// `DependencyKey` inherits from ``TestDependencyKey``, which has two other overridable
 /// requirements: ``TestDependencyKey/testValue``, which should return a default value for the
 /// purpose of testing, and ``TestDependencyKey/previewValue-8u2sy``, which can return a default