La API que Construyes Hoy

Ya hiciste que tu context sea reactivo. Los consumidores ven las actualizaciones cuando el estado cambia. La fontanería funciona. Pero ahora viene un desafío más sutil: ¿cómo debería verse realmente tu API de context?

Considera un carrito de compras. Podrías exponer el array de items sin procesar y dejar que los consumidores hagan push, splice y muten como quieran. O podrías proveer métodos específicos como add(), remove() y updateQuantity(). Ambos enfoques hacen que el carrito funcione, pero llevan a bases de código muy diferentes seis meses después.

El primer enfoque es rápido pero frágil. Cualquier componente puede corromper el estado del carrito. Las reglas de negocio se dispersan por toda la aplicación. Depurar se convierte en arqueología. El segundo enfoque requiere más reflexión inicial pero crea un contrato—un límite claro entre lo que el proveedor gestiona y lo que los consumidores pueden hacer.

Este artículo explora ese espacio de diseño. Aprenderás cuándo exponer datos de solo lectura versus capacidades de lectura-escritura, por qué los métodos de acción superan al acceso directo al estado, y cómo construir APIs de context que permanezcan estables a medida que tu aplicación crece. Al final, tendrás un marco para diseñar context que sea a la vez potente y mantenible.

Dos Filosofías de Estado Compartido

Cuando provees context, estás eligiendo implícitamente cuánto control dar a los consumidores. Esta elección moldea todo lo que viene después.

El Enfoque de Solo Lectura

El context de solo lectura expone datos sin proveer ningún mecanismo para modificarlos. El proveedor mantiene control total sobre todos los cambios de estado:

<!-- UserProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let user = $state(null)
	let loading = $state(true)
	let error = $state(null)

	// Only expose reading capabilities
	setContext('user', {
		get current() {
			return user
		},
		get isLoggedIn() {
			return user !== null
		},
		get displayName() {
			return user?.name ?? 'Guest'
		},
		get isLoading() {
			return loading
		},
		get error() {
			return error
		}
	})

	// Provider controls all updates internally
	async function loadUser() {
		loading = true
		error = null

		try {
			const response = await fetch('/api/user')
			if (!response.ok) throw new Error('Failed to load user')
			user = await response.json()
		} catch (e) {
			error = e.message
			user = null
		} finally {
			loading = false
		}
	}

	loadUser()
</script>

{@render children()}

Los consumidores pueden leer cualquier propiedad expuesta pero no tienen forma de modificar los datos del usuario:

<!-- UserGreeting.svelte -->
<script>
	import { getContext } from 'svelte'

	const userCtx = getContext('user')
</script>

{#if userCtx.isLoading}
	<p>Loading...</p>
{:else if userCtx.error}
	<p class="error">Error: {userCtx.error}</p>
{:else}
	<p>Welcome back, {userCtx.displayName}!</p>
{/if}

El consumidor muestra información del usuario pero no puede modificarla. Si necesitas cerrar la sesión del usuario o actualizar su perfil, esas operaciones viven en el proveedor o en componentes que tienen acceso directo a los métodos internos del proveedor.

Cuándo Tiene Sentido el Solo Lectura

El context de solo lectura funciona bien en varios escenarios. Cuando se trabaja con datos derivados o calculados—valores computados a partir de otras fuentes que los consumidores no deberían manipular directamente. Para configuración que permanece constante durante el ciclo de vida de la aplicación, como feature flags cargados al inicio. Para datos externos obtenidos de APIs donde la fuente de verdad vive en un servidor, no en el navegador. Cuando prevenir cambios accidentales es crítico porque las modificaciones podrían romper invariantes o corromper estado relacionado.

El patrón de solo lectura impone un flujo de datos claro: la información fluye hacia abajo desde el proveedor, y si los consumidores necesitan desencadenar cambios, lo hacen a través de eventos, callbacks u otros mecanismos que el proveedor soporte explícitamente.

El Enfoque de Lectura-Escritura

El context de lectura-escritura provee tanto capacidades de lectura como formas controladas de actualizar el estado:

<!-- ThemeProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { initialTheme = 'light', children } = $props()

	let theme = $state(initialTheme)

	setContext('theme', {
		// Reading
		get current() {
			return theme
		},
		get isDark() {
			return theme === 'dark'
		},
		get isLight() {
			return theme === 'light'
		},

		// Writing (controlled mutations)
		set(value) {
			if (value === 'light' || value === 'dark' || value === 'system') {
				theme = value
			}
		},
		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		},
		reset() {
			theme = initialTheme
		}
	})

	// Sync to document for CSS
	$effect(() => {
		document.documentElement.setAttribute('data-theme', theme)
	})
</script>

{@render children()}

Ahora cualquier consumidor puede leer el tema y desencadenar actualizaciones:

<!-- ThemeControls.svelte -->
<script>
	import { getContext } from 'svelte'

	const theme = getContext('theme')
</script>

<div class="theme-controls">
	<button onclick={theme.toggle}>
		{theme.isDark ? '☀️ Switch to Light' : '🌙 Switch to Dark'}
	</button>

	<select value={theme.current} onchange={(e) => theme.set(e.target.value)}>
		<option value="light">Light</option>
		<option value="dark">Dark</option>
		<option value="system">System</option>
	</select>

	<button onclick={theme.reset}>Reset to Default</button>
</div>

La diferencia crítica respecto a exponer el estado sin procesar es que los consumidores usan los métodos que tú provees. Llaman a theme.set('dark'), no a theme.current = 'dark'. Esta distinción importa enormemente.

El Argumento a Favor de los Métodos de Acción

Uno de los principios de diseño de context más importantes es proveer métodos de acción en lugar de acceso directo al estado. Esta única decisión determina si tu context escala con gracia o se convierte en una carga de mantenimiento.

El Problema de Exponer el Estado Sin Procesar

Considera qué sucede cuando expones el estado subyacente directamente:

<!-- CartProvider.svelte — PROBLEMATIC APPROACH -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let items = $state([])

	// Exposing raw state directly
	setContext('cart', items)
</script>

{@render children()}

Los consumidores reciben el array y pueden hacer cualquier cosa con él:

<!-- SomeConsumer.svelte -->
<script>
	import { getContext } from 'svelte'

	const cart = getContext('cart')

	function addItem(product) {
		// Direct mutation — works, but...
		cart.push({ ...product, quantity: 1 })
	}

	function clearCart() {
		// Another direct mutation
		cart.length = 0
	}

	function doSomethingWeird() {
		// Also possible!
		cart[0] = { id: 'hacked', price: 0 }
		cart.splice(Math.floor(Math.random() * cart.length), 1)
	}
</script>

Cada consumidor puede mutar el array como quiera. No hay validación, no hay imposición de lógica de negocio, no hay garantías de consistencia. Si tu carrito tiene reglas—cantidades máximas, cálculos de precios, verificaciones de inventario—no tienes un lugar central para hacerlas cumplir.

Depurar se vuelve doloroso porque las mutaciones pueden originarse desde cualquier lugar. Cuando el carrito entra en un estado inválido, tienes que buscar en cada archivo que accede al context para encontrar al culpable.

La Solución: Métodos de Acción Controlados

En lugar de exponer el estado sin procesar, expón un objeto con getters para leer y métodos para escribir:

<!-- CartProvider.svelte — BETTER APPROACH -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let items = $state([])

	setContext('cart', {
		// ─── Reading ───────────────────────────────────────
		get items() {
			return items
		},
		get count() {
			return items.reduce((sum, item) => sum + item.quantity, 0)
		},
		get subtotal() {
			return items.reduce((sum, item) => sum + item.price * item.quantity, 0)
		},
		get isEmpty() {
			return items.length === 0
		},

		// ─── Actions ───────────────────────────────────────
		add(product) {
			if (!product?.id || typeof product.price !== 'number') {
				console.warn('Invalid product:', product)
				return false
			}

			const existing = items.find((item) => item.id === product.id)

			if (existing) {
				if (existing.quantity < 99) {
					existing.quantity++
					return true
				}
				return false // Max quantity reached
			}

			items.push({
				id: product.id,
				name: product.name,
				price: product.price,
				quantity: 1
			})
			return true
		},

		remove(productId) {
			const index = items.findIndex((item) => item.id === productId)
			if (index !== -1) {
				items.splice(index, 1)
				return true
			}
			return false
		},

		updateQuantity(productId, quantity) {
			if (typeof quantity !== 'number' || quantity < 0 || quantity > 99) {
				return false
			}

			const item = items.find((i) => i.id === productId)
			if (!item) return false

			if (quantity === 0) {
				return this.remove(productId)
			}

			item.quantity = quantity
			return true
		},

		clear() {
			items.length = 0
		}
	})
</script>

{@render children()}

Ahora los consumidores interactúan a través de la API definida:

<!-- AddToCartButton.svelte -->
<script>
	import { getContext } from 'svelte'

	let { product } = $props()

	const cart = getContext('cart')

	function handleClick() {
		const success = cart.add(product)
		if (!success) {
			alert('Could not add item to cart')
		}
	}
</script>

<button onclick={handleClick}>Add to Cart</button>

<!-- CartSummary.svelte -->
<script>
	import { getContext } from 'svelte'

	const cart = getContext('cart')
</script>

<div class="cart-summary">
	{#if cart.isEmpty}
		<p>Your cart is empty</p>
	{:else}
		<p>{cart.count} items · ${(cart.subtotal / 100).toFixed(2)}</p>

		{#each cart.items as item (item.id)}
			<div class="cart-item">
				<span>{item.name}</span>
				<input
					type="number"
					min="1"
					max="99"
					value={item.quantity}
					onchange={(e) => cart.updateQuantity(item.id, parseInt(e.target.value))}
				/>
				<button onclick={() => cart.remove(item.id)}>Remove</button>
			</div>
		{/each}

		<button onclick={() => cart.clear()}>Clear Cart</button>
	{/if}
</div>

Por Qué Ganan las Acciones

Los beneficios se acumulan a medida que tu aplicación crece.

La validación ocurre en un solo lugar. El método add verifica que los productos tengan IDs y precios válidos. El método updateQuantity impone el rango 0-99. Los consumidores no necesitan recordar estas reglas—están integradas en la API.

La lógica de negocio permanece encapsulada. Si agregar un ítem debería también verificar el inventario, registrar analíticas o sincronizar con un servidor, agregas esa lógica una vez en el proveedor. Cada consumidor se beneficia automáticamente.

Depurar se vuelve manejable. Cuando algo sale mal con el carrito, examinas los métodos de acción. Puedes agregar logging, breakpoints o manejo de errores en una sola ubicación.

Refactorizar se mantiene seguro. Si necesitas cambiar cómo se almacenan los ítems internamente—quizás cambiando de un array a un Map para búsquedas más rápidas—los consumidores no necesitan cambiar. Siguen llamando a cart.add(product), sin conocer los detalles de implementación.

La intención queda documentada. Nombres de métodos como add, remove y clear describen lo que el llamador quiere lograr. Mutaciones directas como items.push() o items.splice(2, 1) describen detalles de implementación que oscurecen la intención.

Diseñando para la Estabilidad

Una vez que publicas una API de context, los consumidores dependen de ella. Cada getter que leen, cada método que llaman, se convierte en parte de tu contrato. Cambiar la API rompe su código.

Elige Nombres que Perduren

Los nombres de propiedades y métodos deben describir conceptos, no implementaciones:

<script>
	// ❌ Too specific — what if you add 'system' or 'auto' themes?
	setContext('theme', {
		get isLight() {
			return theme === 'light'
		},
		get isDark() {
			return theme === 'dark'
		}
	})

	// ✅ More flexible — works with any theme value
	setContext('theme', {
		get current() {
			return theme
		},
		is(value) {
			return theme === value
		}
	})
</script>

La segunda versión maneja futuros valores de tema sin cambios en la API. Los consumidores escriben theme.is('dark') en lugar de theme.isDark, y cuando agregas un tema 'system', el código existente sigue funcionando.

Prefiere Cambios Aditivos

Agregar nuevas propiedades y métodos es seguro—el código existente ignora lo que no usa. Eliminar o renombrar rompe a los consumidores de inmediato.

<script>
	// Version 1.0
	setContext('cart', {
		get items() {
			return items
		},
		add(product) {
			/* ... */
		},
		remove(id) {
			/* ... */
		}
	})

	// Version 1.1 — SAFE: only additions
	setContext('cart', {
		get items() {
			return items
		},
		get count() {
			return items.length
		}, // New
		get isEmpty() {
			return items.length === 0
		}, // New
		add(product) {
			/* ... */
		},
		addMultiple(products) {
			/* ... */
		}, // New
		remove(id) {
			/* ... */
		},
		clear() {
			/* ... */
		} // New
	})

	// Version 2.0 — BREAKING: renamed method
	setContext('cart', {
		get items() {
			return items
		},
		addItem(product) {
			/* ... */
		} // Was 'add' — breaks all callers!
	})
</script>

Si debes hacer cambios disruptivos, considera mantener la API antigua funcionando junto a la nueva, al menos temporalmente:

<script>
	setContext('cart', {
		// New preferred name
		addItem(product) {
			/* ... */
		},

		// Deprecated but still works
		add(product) {
			console.warn('cart.add() is deprecated, use cart.addItem()')
			return this.addItem(product)
		}
	})
</script>

Maneja los Casos Límite Explícitamente

Cada método de acción debería considerar qué sucede con entradas inválidas:

<script>
	setContext('cart', {
		remove(productId) {
			// ❌ Dangerous: splice(-1, 1) removes the LAST item
			const index = items.findIndex((i) => i.id === productId)
			items.splice(index, 1)
		}
	})

	// ✅ Safe: validate before operating
	setContext('cart', {
		remove(productId) {
			const index = items.findIndex((i) => i.id === productId)
			if (index === -1) {
				return false // Item not found
			}
			items.splice(index, 1)
			return true
		}
	})
</script>

La segunda versión maneja el caso de "ítem no encontrado" explícitamente. Los llamadores pueden verificar el valor de retorno si les importa, o ignorarlo si no. De cualquier manera, el estado del carrito permanece consistente.

El Contrato Proveedor-Consumidor

Piensa en el context como un contrato formal entre dos partes con responsabilidades distintas.

┌─────────────────────────────────────────────────────────────┐
│  PROVIDER RESPONSIBILITIES                                  │
│  ─────────────────────────                                  │
│  • Initialize state with sensible defaults                  │
│  • Validate all inputs to action methods                    │
│  • Maintain data consistency and invariants                 │
│  • Handle side effects (persistence, API calls, logging)    │
│  • Define and document the public API                       │
│  • Ensure getters always return current, valid data         │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ Context Object
                              │ (the contract)
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  CONSUMER RESPONSIBILITIES                                  │
│  ─────────────────────────                                  │
│  • Use only the public API (getters and methods)            │
│  • Trust that getters return current, reactive data         │
│  • Call actions for all mutations                           │
│  • Handle potential failures (check return values)          │
│  • Avoid assumptions about internal implementation          │
└─────────────────────────────────────────────────────────────┘

Esta separación crea un límite claro. El proveedor puede cambiar su implementación interna—cambiando estructuras de datos, agregando caché, introduciendo optimizaciones—sin afectar a los consumidores. Los consumidores pueden evolucionar su UI y lógica sin preocuparse por corromper el estado compartido.

Ejemplo Completo: Contexto de Formulario Multi-Paso

Apliquemos estos principios a un escenario realista: un formulario multi-paso con validación, navegación y manejo del envío.

<!-- FormProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { steps, initialData = {}, onSubmit, children } = $props()

	// ─── Internal State ────────────────────────────────────
	// Note: initialData is captured at mount time. This is intentional—
	// forms typically don't need to react to prop changes mid-session.
	// The reset() method uses this captured value to restore initial state.
	const capturedInitialData = { ...initialData }
	let formData = $state({ ...capturedInitialData })
	let currentStepIndex = $state(0)
	let fieldErrors = $state({})
	let formError = $state(null)
	let submitting = $state(false)
	let submitted = $state(false)

	// ─── Derived Values ────────────────────────────────────
	let currentStep = $derived(steps[currentStepIndex])
	let isFirstStep = $derived(currentStepIndex === 0)
	let isLastStep = $derived(currentStepIndex === steps.length - 1)
	let hasErrors = $derived(Object.keys(fieldErrors).length > 0)
	let progress = $derived(((currentStepIndex + 1) / steps.length) * 100)

	// ─── Helper Functions ──────────────────────────────────
	function validateCurrentStep() {
		fieldErrors = {}

		if (currentStep.validate) {
			const errors = currentStep.validate(formData)
			if (errors && Object.keys(errors).length > 0) {
				fieldErrors = errors
				return false
			}
		}
		return true
	}

	// ─── Context API ───────────────────────────────────────
	setContext('form', {
		// Reading: Form Data
		get data() {
			return formData
		},
		getField(name) {
			return formData[name] ?? ''
		},

		// Reading: Navigation State
		get currentStep() {
			return currentStep
		},
		get stepIndex() {
			return currentStepIndex
		},
		get stepCount() {
			return steps.length
		},
		get isFirstStep() {
			return isFirstStep
		},
		get isLastStep() {
			return isLastStep
		},
		get progress() {
			return progress
		},

		// Reading: Validation State
		get errors() {
			return fieldErrors
		},
		get formError() {
			return formError
		},
		get hasErrors() {
			return hasErrors
		},
		getError(name) {
			return fieldErrors[name] ?? null
		},

		// Reading: Submission State
		get isSubmitting() {
			return submitting
		},
		get isSubmitted() {
			return submitted
		},

		// Actions: Update Fields
		setField(name, value) {
			formData[name] = value
			// Clear field error when user edits
			if (fieldErrors[name]) {
				delete fieldErrors[name]
			}
			// Clear form-level error on any edit
			formError = null
		},

		setFields(updates) {
			Object.entries(updates).forEach(([name, value]) => {
				formData[name] = value
				if (fieldErrors[name]) {
					delete fieldErrors[name]
				}
			})
			formError = null
		},

		// Actions: Validation
		setFieldError(name, message) {
			if (message) {
				fieldErrors[name] = message
			} else {
				delete fieldErrors[name]
			}
		},

		setFormError(message) {
			formError = message
		},

		clearErrors() {
			fieldErrors = {}
			formError = null
		},

		validateStep() {
			return validateCurrentStep()
		},

		// Actions: Navigation
		nextStep() {
			if (isLastStep) return false
			if (!validateCurrentStep()) return false

			currentStepIndex++
			return true
		},

		prevStep() {
			if (isFirstStep) return false
			currentStepIndex--
			return true
		},

		goToStep(index) {
			if (index < 0 || index >= steps.length) return false
			if (index > currentStepIndex && !validateCurrentStep()) return false

			currentStepIndex = index
			return true
		},

		// Actions: Submission
		async submit() {
			if (submitting || submitted) return false
			if (!validateCurrentStep()) return false

			submitting = true
			formError = null

			try {
				await onSubmit(formData)
				submitted = true
				return true
			} catch (e) {
				formError = e.message || 'Submission failed'
				return false
			} finally {
				submitting = false
			}
		},

		// Actions: Reset
		reset() {
			formData = { ...capturedInitialData }
			currentStepIndex = 0
			fieldErrors = {}
			formError = null
			submitting = false
			submitted = false
		}
	})
</script>

{@render children()}

Ahora los consumidores tienen una API clara y completa con la que trabajar:

<!-- FormProgress.svelte -->
<script>
	import { getContext } from 'svelte'

	const form = getContext('form')
</script>

<div class="progress-container">
	<div class="progress-bar">
		<div class="progress-fill" style="width: {form.progress}%"></div>
	</div>

	<p class="progress-text">
		Step {form.stepIndex + 1} of {form.stepCount}: {form.currentStep.title}
	</p>
</div>

<style>
	.progress-container {
		margin-bottom: 1.5rem;
	}

	.progress-bar {
		height: 4px;
		background: #e5e7eb;
		border-radius: 2px;
		overflow: hidden;
	}

	.progress-fill {
		height: 100%;
		background: #3b82f6;
		transition: width 0.3s ease;
	}

	.progress-text {
		margin-top: 0.5rem;
		font-size: 0.875rem;
		color: #6b7280;
	}
</style>

<!-- FormField.svelte -->
<script>
	import { getContext } from 'svelte'

	let { name, label, type = 'text', required = false } = $props()

	const form = getContext('form')

	let error = $derived(form.getError(name))
	let value = $derived(form.getField(name))
</script>

<div class="field" class:has-error={error}>
	<label for={name}>
		{label}
		{#if required}<span class="required">*</span>{/if}
	</label>

	<input
		id={name}
		{type}
		{value}
		oninput={(e) => form.setField(name, e.target.value)}
		aria-invalid={error ? 'true' : undefined}
		aria-describedby={error ? `${name}-error` : undefined}
	/>

	{#if error}
		<p id="{name}-error" class="error-message">{error}</p>
	{/if}
</div>

<style>
	.field {
		margin-bottom: 1rem;
	}

	label {
		display: block;
		margin-bottom: 0.25rem;
		font-weight: 500;
		color: #374151;
	}

	.required {
		color: #ef4444;
		margin-left: 0.25rem;
	}

	input {
		width: 100%;
		padding: 0.625rem 0.75rem;
		border: 1px solid #d1d5db;
		border-radius: 6px;
		font-size: 1rem;
		transition:
			border-color 0.15s,
			box-shadow 0.15s;
	}

	input:focus {
		outline: none;
		border-color: #3b82f6;
		box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
	}

	.has-error input {
		border-color: #ef4444;
	}

	.has-error input:focus {
		box-shadow: 0 0 0 3px rgba(239, 68, 68, 0.1);
	}

	.error-message {
		margin-top: 0.25rem;
		font-size: 0.875rem;
		color: #ef4444;
	}
</style>

<!-- FormNavigation.svelte -->
<script>
	import { getContext } from 'svelte'

	const form = getContext('form')
</script>

<div class="navigation">
	{#if !form.isFirstStep}
		<button type="button" onclick={() => form.prevStep()} class="btn-secondary"> ← Back </button>
	{/if}

	<div class="spacer"></div>

	{#if form.isLastStep}
		<button
			type="button"
			onclick={() => form.submit()}
			disabled={form.isSubmitting}
			class="btn-primary"
		>
			{form.isSubmitting ? 'Submitting...' : 'Submit'}
		</button>
	{:else}
		<button type="button" onclick={() => form.nextStep()} class="btn-primary"> Next → </button>
	{/if}
</div>

{#if form.formError}
	<div class="form-error" role="alert">
		<p>{form.formError}</p>
	</div>
{/if}

<style>
	.navigation {
		display: flex;
		gap: 1rem;
		margin-top: 1.5rem;
		padding-top: 1.5rem;
		border-top: 1px solid #e5e7eb;
	}

	.spacer {
		flex: 1;
	}

	button {
		padding: 0.625rem 1.25rem;
		border: none;
		border-radius: 6px;
		font-weight: 500;
		font-size: 0.9375rem;
		cursor: pointer;
		transition: background-color 0.15s;
	}

	button:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}

	.btn-primary {
		background: #3b82f6;
		color: white;
	}

	.btn-primary:hover:not(:disabled) {
		background: #2563eb;
	}

	.btn-secondary {
		background: #f3f4f6;
		color: #374151;
	}

	.btn-secondary:hover:not(:disabled) {
		background: #e5e7eb;
	}

	.form-error {
		margin-top: 1rem;
		padding: 0.75rem 1rem;
		background: #fef2f2;
		border: 1px solid #fecaca;
		border-radius: 6px;
	}

	.form-error p {
		margin: 0;
		color: #dc2626;
		font-size: 0.875rem;
	}
</style>

<!-- FormStepContent.svelte -->
<script>
	import { getContext } from 'svelte'
	import FormField from './FormField.svelte'

	const form = getContext('form')
</script>

{#if form.currentStep.id === 'personal'}
	<FormField name="name" label="Full Name" required />
	<FormField name="email" label="Email Address" type="email" required />
	<FormField name="phone" label="Phone Number" type="tel" />
{:else if form.currentStep.id === 'address'}
	<FormField name="street" label="Street Address" required />
	<FormField name="city" label="City" required />
	<FormField name="state" label="State / Province" />
	<FormField name="zip" label="ZIP / Postal Code" />
{:else if form.currentStep.id === 'review'}
	<div class="review-section">
		<h3>Review Your Information</h3>
		<dl class="review-list">
			<div class="review-item">
				<dt>Name</dt>
				<dd>{form.data.name || '—'}</dd>
			</div>
			<div class="review-item">
				<dt>Email</dt>
				<dd>{form.data.email || '—'}</dd>
			</div>
			<div class="review-item">
				<dt>Phone</dt>
				<dd>{form.data.phone || '—'}</dd>
			</div>
			<div class="review-item">
				<dt>Address</dt>
				<dd>
					{#if form.data.street}
						{form.data.street}<br />
						{form.data.city}{form.data.state ? `, ${form.data.state}` : ''}
						{form.data.zip || ''}
					{:else}
						—
					{/if}
				</dd>
			</div>
		</dl>
	</div>
{/if}

<style>
	.review-section h3 {
		margin: 0 0 1rem;
		font-size: 1.125rem;
		color: #1f2937;
	}

	.review-list {
		margin: 0;
	}

	.review-item {
		display: grid;
		grid-template-columns: 120px 1fr;
		gap: 0.5rem;
		padding: 0.75rem 0;
		border-bottom: 1px solid #e5e7eb;
	}

	.review-item:last-child {
		border-bottom: none;
	}

	dt {
		font-weight: 500;
		color: #6b7280;
	}

	dd {
		margin: 0;
		color: #1f2937;
	}
</style>

Poniendo todo junto:

<!-- src/routes/register/+page.svelte -->
<script>
	import FormProvider from '$lib/components/FormProvider.svelte'
	import FormProgress from '$lib/components/FormProgress.svelte'
	import FormStepContent from '$lib/components/FormStepContent.svelte'
	import FormNavigation from '$lib/components/FormNavigation.svelte'

	const steps = [
		{
			id: 'personal',
			title: 'Personal Information',
			validate(data) {
				const errors = {}
				if (!data.name?.trim()) {
					errors.name = 'Name is required'
				}
				if (!data.email?.trim()) {
					errors.email = 'Email is required'
				} else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
					errors.email = 'Please enter a valid email address'
				}
				return Object.keys(errors).length > 0 ? errors : null
			}
		},
		{
			id: 'address',
			title: 'Address',
			validate(data) {
				const errors = {}
				if (!data.street?.trim()) {
					errors.street = 'Street address is required'
				}
				if (!data.city?.trim()) {
					errors.city = 'City is required'
				}
				return Object.keys(errors).length > 0 ? errors : null
			}
		},
		{
			id: 'review',
			title: 'Review & Submit',
			validate: null
		}
	]

	async function handleSubmit(data) {
		// Simulate API call
		await new Promise((resolve) => setTimeout(resolve, 1500))
		console.log('Registration complete:', data)
	}
</script>

<div class="page">
	<h1>Create Account</h1>

	<FormProvider {steps} onSubmit={handleSubmit}>
		<div class="form-container">
			<FormProgress />
			<FormStepContent />
			<FormNavigation />
		</div>
	</FormProvider>
</div>

<style>
	.page {
		max-width: 500px;
		margin: 2rem auto;
		padding: 0 1rem;
	}

	h1 {
		margin: 0 0 1.5rem;
		font-size: 1.75rem;
		color: #1f2937;
		text-align: center;
	}

	.form-container {
		padding: 1.5rem;
		background: white;
		border-radius: 12px;
		box-shadow:
			0 1px 3px rgba(0, 0, 0, 0.1),
			0 1px 2px rgba(0, 0, 0, 0.06);
	}
</style>

Este ejemplo demuestra cada principio que hemos discutido. El proveedor gestiona todo el estado internamente. Los consumidores usan una API limpia de getters y métodos de acción. La validación ocurre de forma centralizada. La navegación protege contra una progresión inválida. La API es amigable para extensiones y documenta su intención a través de los nombres de los métodos.

Errores Comunes y Cómo Evitarlos

1: Exponer Setters Directos Sin Validación

<script>
	let count = $state(0)

	// ❌ No validation — consumers can set anything
	setContext('counter', {
		get value() {
			return count
		},
		set value(v) {
			count = v
		}
	})
</script>

Los consumidores podrían asignar números negativos, cadenas de texto o undefined. En su lugar, proporciona métodos de acción explícitos:

<script>
	setContext('counter', {
		get value() {
			return count
		},
		increment() {
			count++
		},
		decrement() {
			if (count > 0) count--
		},
		set(v) {
			if (typeof v === 'number' && v >= 0 && Number.isFinite(v)) {
				count = Math.floor(v)
			}
		}
	})
</script>

2: No Manejar Casos Límite en los Métodos de Acción

<script>
	// ❌ Dangerous when item doesn't exist
	setContext('list', {
		remove(id) {
			const index = items.findIndex((i) => i.id === id)
			items.splice(index, 1) // splice(-1, 1) removes last item!
		}
	})
</script>

Siempre valida antes de operar:

<script>
	setContext('list', {
		remove(id) {
			const index = items.findIndex((i) => i.id === id)
			if (index !== -1) {
				items.splice(index, 1)
				return true
			}
			return false
		}
	})
</script>

3: Mezclar Retornos de Solo Lectura y Mutables

<script>
	// ❌ Confusing: items getter returns mutable array
	setContext('cart', {
		get items() {
			return items
		} // Consumers can still mutate!
	})
</script>

Si deseas un comportamiento verdaderamente de solo lectura, devuelve una copia:

<script>
	setContext('cart', {
		get items() {
			return [...items]
		}, // New array each time
		get itemCount() {
			return items.length
		}
	})
</script>

Ten en cuenta que devolver copias tiene implicaciones de rendimiento para arreglos grandes o accesos frecuentes. Elige según tus necesidades específicas.

Consideraciones de Rendimiento y Escalabilidad

El diseño de la API de contexto impacta el rendimiento a medida que tu aplicación escala. Comprender estas compensaciones te ayuda a tomar decisiones informadas.

Frecuencia de Evaluación de Getters

Los getters en tu objeto de contexto se ejecutan cada vez que se accede a ellos. Para retornos de propiedades simples, esta sobrecarga es insignificante. Sin embargo, para cómputos costosos, prefiere valores $derived que cacheen los resultados hasta que cambien las dependencias:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let items = $state([])

	// ❌ Recalculates on every access
	setContext('cart-inefficient', {
		get total() {
			return items.reduce((sum, item) => {
				return sum + calculateComplexTotal(item) // Expensive operation
			}, 0)
		}
	})

	// ✅ Caches result until items change
	let total = $derived(items.reduce((sum, item) => sum + calculateComplexTotal(item), 0))

	setContext('cart-efficient', {
		get total() {
			return total
		}
	})

	function calculateComplexTotal(item) {
		// Simulates expensive calculation
		return item.price * item.quantity * (1 - (item.discount || 0))
	}
</script>

{@render children()}

El primer enfoque recalcula en cada acceso a cart.total. El segundo calcula una vez cuando items cambia, luego devuelve el valor cacheado.

Tamaño del Objeto de Contexto

Los objetos de contexto grandes con muchos métodos no impactan el rendimiento de forma inherente—los objetos de JavaScript son baratos de crear y acceder. Sin embargo, considera estos factores:

El estado reactivo profundamente anidado requiere un rastreo más detallado por parte del sistema de reactividad de Svelte. Mantén las estructuras de estado razonablemente planas cuando sea posible. Un arreglo de objetos con algunas propiedades cada uno está bien; los árboles profundamente anidados de objetos pueden beneficiarse de la normalización.

Si tu contexto tiene docenas de métodos de acción, considera si está haciendo demasiado. Un contexto de formulario con 15 métodos es razonable. Un "contexto dios" con 50 métodos gestionando preocupaciones no relacionadas probablemente debería dividirse en múltiples contextos enfocados.

Efectos Secundarios de los Métodos de Acción

Los métodos de acción que desencadenan solicitudes de red, cómputos pesados o escrituras en localStorage deberían considerar el uso de debouncing o batching. El proveedor de contexto es un lugar excelente para centralizar tales optimizaciones, ya que todas las mutaciones fluyen a través de él:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let preferences = $state({})
	let saveTimeout = null

	function debouncedSave() {
		clearTimeout(saveTimeout)
		saveTimeout = setTimeout(() => {
			localStorage.setItem('preferences', JSON.stringify(preferences))
		}, 500)
	}

	setContext('preferences', {
		get all() {
			return preferences
		},
		set(key, value) {
			preferences[key] = value
			debouncedSave() // Batches rapid changes
		}
	})
</script>

{@render children()}

Los consumidores llaman a preferences.set() libremente sin preocuparse por el rendimiento—el proveedor maneja la optimización de forma transparente.

Cuándo NO Usar Este Patrón

Las APIs de contexto basadas en métodos de acción sobresalen en muchos escenarios, pero no siempre son la elección correcta.

Compartir Valores Simples

Si estás compartiendo un único valor simple que no requiere validación ni lógica de negocio compleja, la ceremonia de los métodos de acción añade complejidad sin un beneficio proporcional:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let locale = $state('en')

	// For a simple locale setting, this might be overkill:
	setContext('locale-verbose', {
		get current() {
			return locale
		},
		setEnglish() {
			locale = 'en'
		},
		setSpanish() {
			locale = 'es'
		},
		setFrench() {
			locale = 'fr'
		},
		set(value) {
			if (['en', 'es', 'fr'].includes(value)) {
				locale = value
			}
		}
	})

	// Sometimes simpler is better:
	setContext('locale-simple', {
		get value() {
			return locale
		},
		set(v) {
			locale = v
		}
	})
</script>

{@render children()}

La versión más simple es más fácil de entender y suficiente para casos de uso sencillos. Reserva el patrón completo de métodos de acción para el estado que genuinamente se beneficia de la encapsulación.

El Prop Drilling en Realidad Está Bien

El contexto resuelve el problema del prop drilling, pero los árboles de componentes poco profundos no necesitan esta solución. Si estás pasando datos a través de dos o tres niveles, las props explícitas suelen ser más claras y más rastreables:

<!-- Passing through 2-3 levels? Props are fine. -->
<Parent>
	<Child {user}>
		<Grandchild {user} />
	</Child>
</Parent>

<!-- Passing through 5+ levels? Consider context. -->

Las props hacen explícito el flujo de datos. Puedes rastrear de dónde vienen los datos leyendo la jerarquía de componentes. El contexto oculta este flujo, lo cual es valioso para el estado profundamente compartido, pero añade sobrecarga cognitiva para casos simples.

Estado Local del Componente

El estado que solo un componente usa no debería vivir en el contexto. El contexto es para el estado genuinamente compartido—datos que múltiples componentes, potencialmente distantes, necesitan coordinar.

El estado abierto/cerrado de un modal, los errores de validación locales de un formulario, el valor de progreso de una animación—estos pertenecen al $state local del componente, no al contexto. Poner todo en el contexto crea acoplamiento innecesario y hace que los componentes sean más difíciles de reutilizar.

Conjuntos de Consumidores Altamente Dinámicos

Si los componentes que consumen tu contexto se montan y desmontan rápidamente (como elementos en una lista virtualizada), asegúrate de que tu API de contexto no cree closures o suscripciones que puedan causar problemas de memoria. El patrón basado en getters descrito en este artículo maneja esto bien, pero sé cauteloso con los patrones que registran callbacks o listeners.

Conclusiones Clave

El diseño de la API de contexto determina cómo evoluciona tu aplicación. Las decisiones que tomes al principio —solo lectura versus lectura y escritura, estado sin procesar versus métodos de acción— se acumulan con el tiempo en una arquitectura mantenible o en una red enredada de dependencias implícitas.

Elige solo lectura cuando sea apropiado. La configuración, los datos derivados y la información proveniente de fuentes externas a menudo no deberían ser modificados por los consumidores. El contexto de solo lectura hace explícito el flujo de datos y previene la corrupción accidental.

Provee acciones, no estado sin procesar. Los métodos de acción como add(), remove() y update() encapsulan validación, lógica de negocio y efectos secundarios. Documentan la intención, simplifican la depuración y permiten la refactorización interna sin romper a los consumidores.

Diseña pensando en la estabilidad desde el principio. Elige nombres que no necesiten cambiar. Prefiere los cambios aditivos sobre las modificaciones. Maneja los casos borde explícitamente en cada método de acción.

Respeta el contrato proveedor-consumidor. Los proveedores inicializan, validan y gestionan el estado. Los consumidores utilizan la API pública. Esta separación crea un límite claro que escala con tu aplicación.

El esfuerzo que inviertes en diseñar tu API de contexto da sus frutos cada vez que un nuevo componente necesita interactuar con el estado compartido. Una API bien diseñada guía a los consumidores hacia un uso correcto y los aleja de errores sutiles. Hace que tu base de código sea más predecible, más fácil de probar y más agradable de trabajar.

Qué Sigue

Con el diseño limpio de API dominado, explora las prácticas profesionales para el contexto en Mejores Prácticas de Contexto, que cubre convenciones de nomenclatura, organización de archivos, estrategias de prueba y consideraciones de rendimiento.

Ver También

Documentación Oficial

Svelte Context — Guía oficial de contexto
$state — Runa de estado reactivo