DependencyKey: registrar la dependencia y darle liveValue

Ya tienes la dependencia modelada como un valor. Falta la otra mitad del contrato: que la arquitectura sepa encontrarla. TCA no usa un registro con cadenas ni un grafo de anotaciones; usa un diccionario heterogéneo indexado por tipos, donde cada tipo que conforma DependencyKey es a la vez la llave y el anuncio de qué se guarda bajo ella. Esa elección compra dos cosas a la vez: seguridad de tipos total —jamás sacarás de la casilla algo distinto de lo que declaraste— y un valor por defecto garantizado, de modo que no existe el estado dependencia no registrada. Registrar bien es media lección; la otra media es entender cuándo se lee el valor, porque el contenedor tiene alcance dinámico y eso cambia lo que puedes esperar de él.

El contenedor es un diccionario indexado por tipos

DependencyValues es, en esencia, un almacén cuyo índice no es una cadena sino un tipo. El protocolo que lo hace posible es minúsculo.

public protocol DependencyKey {
  associatedtype Value
  static var liveValue: Value { get }
}

El tipo conformante actúa como nombre y su Value declara qué se guarda. Como el subíndice del contenedor está tipado por esa relación, leer self[ClienteArticulos.self] solo puede devolver un ClienteArticulos: no hay conversión forzada, ni opcional, ni posibilidad de colisión entre dos módulos que casualmente eligieran la misma cadena. Y como liveValue es un requisito estático y no opcional, la pregunta y si nadie la registró simplemente no existe: el defecto está garantizado por el compilador.

Lo más habitual es que el propio cliente sea su llave, porque en el noventa por ciento de los casos hay una sola registración por tipo.

extension ClienteArticulos: DependencyKey {
  static let liveValue = ClienteArticulos(
    cargar: { try await Backend.articulos() },
    buscar: { texto in try await Backend.buscar(texto) },
    guardar: { articulo in try await Backend.enviar(articulo) },
    borrar: { id in try await Backend.borrar(id) }
  )
}

Que el cliente sea su propia llave es cómodo pero conviene ver que son dos papeles distintos superpuestos: el tipo ClienteArticulos funciona a la vez como nombre de la casilla y como tipo de lo que guarda. Mientras haya una sola registración por tipo, la coincidencia es inofensiva y ahorra un enum; en cuanto necesitas dos, los papeles se separan y hay que darle a cada casilla un nombre propio.

Cuando necesites dos registraciones del mismo tipo —dos bases de datos, dos endpoints de una misma API— la llave deja de poder ser el propio tipo y se convierte en un enum vacío que solo existe para nombrar la casilla. Es el mecanismo completo, y el caso frecuente es solo su atajo.

enum BaseDatosPrincipal: DependencyKey {
  static let liveValue = Base(url: .principal)
}
enum BaseDatosAnalitica: DependencyKey {
  static let liveValue = Base(url: .analitica)
}

liveValue: la implementación de verdad, y nada más

La regla es tajante: liveValue es lo que corre en la app que descarga un usuario. Nunca un valor de mentira, nunca datos de muestra, nunca un if que mire si estamos en tests. Si el liveValue miente, todas las garantías del sistema se evaporan, porque el único valor que nadie sobrescribe deja de describir la realidad.

La prohibición del condicional merece énfasis porque la tentación reaparece con disfraces respetables: una comprobación de si estamos en el simulador, una variable de entorno que activa datos falsos, una bandera de compilación para modo demo. Todas comparten el mismo defecto: hacen que el comportamiento de producción dependa de algo que no está en la firma, con lo que dejas de poder razonar sobre el liveValue leyéndolo. Si necesitas un modo demo, es otra dependencia o es una sobrescritura declarada en el punto de entrada, nunca una rama escondida dentro del valor vivo.

Dos matices técnicos importan. Primero, static let en Swift es perezoso y se inicializa a lo sumo una vez, con garantía de ejecución única; eso significa que construir el cliente vivo no cuesta nada hasta que alguien lo pide, y que puedes abrir conexiones o preparar recursos ahí sin penalizar el arranque de los tests, que nunca lo tocarán. Segundo, liveValue no debería depender de otras dependencias leyéndolas en su propia inicialización: si el cliente vivo necesita el reloj o el generador de identificadores, decláralos con @Dependency dentro de las closures, donde se resolverán en el contexto correcto, y no en el cuerpo estático, que se evalúa una sola vez y fuera de todo ámbito sobrescrito.

La ruta de clave: extender DependencyValues

Conformar la llave registra el valor, pero todavía no hay una forma cómoda de pedirlo. Esa forma es una propiedad calculada en una extensión del contenedor, cuyo get y set delegan en el subíndice tipado.

extension DependencyValues {
  var clienteArticulos: ClienteArticulos {
    get { self[ClienteArticulos.self] }
    set { self[ClienteArticulos.self] = newValue }
  }
}

Esa propiedad es lo que hace existir la ruta de clave \.clienteArticulos, y a partir de ella la dependencia se comporta exactamente igual que las que trae la librería.

@Reducer
struct Lista {
  @Dependency(\.clienteArticulos) var cliente

  // dentro de reduce:
  // return .run { send in await send(.recibidos(Result { try await cliente.cargar() })) }
}

Nombra esa propiedad con el mismo criterio con el que nombrarías cualquier API pública, porque eso es: la ruta de clave aparecerá en decenas de reducers y en todos los bloques de sobrescritura de la suite. Un nombre que describa la capacidad envejece bien; uno que describa la implementación te obligará a renombrar el día que cambie el proveedor.

El set no es decorativo: es lo que permite escribir $0.clienteArticulos.cargar = ... en un withDependencies, porque asignar a un campo del valor exige poder volver a guardarlo entero en el contenedor. Sin set, la dependencia sería de solo lectura y perderías toda la sustitución granular que ganaste en la lección anterior.

flowchart TB
A[struct ClienteArticulos] --> B[conforma DependencyKey]
B --> C[liveValue estatico y perezoso]
B --> D[casilla en DependencyValues indexada por el tipo]
D --> E[extension con propiedad calculada]
E --> F[ruta de clave punto clienteArticulos]
F --> G[Dependency dentro del reducer]
style D fill:#89b4fa,color:#11111b
style G fill:#a6e3a1,color:#11111b

Alcance dinámico: dónde vive el valor actual

El contenedor no es un singleton fijo: el valor vigente se guarda en una variable de tarea local, así que una sobrescritura hecha con withDependencies rige para todo lo que ocurra dentro de esa operación, incluidas las tareas hijas que se creen estructuradamente. Eso es alcance dinámico, no léxico: lo que determina qué cliente ves no es dónde está escrito tu código sino bajo qué ámbito se está ejecutando.

De ahí se deducen dos consecuencias prácticas. Una: las sobrescrituras se anidan y la más interna gana, lo que permite que un test global fije el reloj y un caso concreto lo refine sin tocar el resto. Otra: si escapas del árbol de tareas —una closure que se guarda para más tarde, una tarea no estructurada que sobrevive a la operación— pierdes el contexto y vuelves a ver los valores por defecto; para esos casos la librería ofrece withEscapedDependencies, que captura el contexto vigente y lo restaura después.

Para configurar la app entera una sola vez, el sitio correcto es el punto de entrada, con prepareDependencies, que fija valores en el contexto raíz antes de que se construya el primer Store.

Hay un detalle de secuencia que produce errores difíciles de diagnosticar: @Dependency resuelve su valor cuando la propiedad se lee, no cuando se declara el reducer, y por eso leer una dependencia dentro del init de un reducer suele darte el valor equivocado. La regla práctica es simple: consulta las dependencias dentro de reduce o dentro de las closures de los efectos, nunca en la construcción del tipo.