Introducción

El desafío de la serialización

Cuando se construyen aplicaciones full-stack con SvelteKit, frecuentemente necesitas pasar datos entre el servidor y el cliente. Por defecto, SvelteKit usa devalue para serializar los datos que devuelven las funciones load, las acciones de formulario y las funciones remotas. Si bien devalue maneja muchos tipos más allá de JSON (como Date, Map, Set, BigInt, RegExp e incluso referencias cíclicas), no puede serializar automáticamente instancias de clases personalizadas.

Aquí es donde entra el hook de Transport. Disponible desde SvelteKit 2.11, Transport te permite definir lógica de serialización/deserialización personalizada para tus propias clases, lo que te permite pasar objetos de dominio complejos a través del límite servidor/cliente de forma fluida.

El problema que Transport resuelve

Considera este escenario común:

// ❌ This will throw an error!
// lib/models/User.ts
export class User {
	constructor(
		public id: number,
		public name: string,
		public email: string
	) {}

	greet() {
		return `Hello, ${this.name}!`
	}
}

// routes/+page.server.ts
import { User } from '$lib/models/User'

export async function load() {
	const user = new User(1, 'Alice', 'alice@example.com')

	return {
		user // Error: Cannot stringify arbitrary non-POJOs
	}
}

Sin Transport, SvelteKit no puede serializar la instancia de la clase User. Recibirías un error: "Cannot stringify arbitrary non-POJOs".

Cómo funciona Transport

El hook de Transport se define en src/hooks.js (o src/hooks.ts) y exporta un objeto transport que contiene los transporters para tus tipos personalizados.

Estructura básica

// src/hooks.ts
import type { Transport } from '@sveltejs/kit'

export const transport: Transport = {
	TypeName: {
		encode: (value) => {
			// Return false if value is not an instance of TypeName
			// Otherwise, return a serializable representation
		},
		decode: (data) => {
			// Convert the serialized data back into an instance
		}
	}
}

El patrón encode/decode

encode: Se ejecuta en el servidor. Recibe un valor y debe devolver:
- Un valor no falsy (objeto o arreglo) si el valor es una instancia de tu tipo
- false (o cualquier valor falsy) si no es una instancia de tu tipo
decode: Se ejecuta en el navegador. Recibe los datos codificados y reconstruye la instancia original.

Importante: El valor codificado debe ser serializable por devalue. Esto significa que debe ser un objeto plano, un arreglo, o contener solo tipos serializables (strings, números, Dates, Maps, etc.).

Casos de uso del mundo real

1. Modelos de dominio con métodos

Uno de los casos de uso más comunes es transportar modelos de dominio que tienen tanto datos como comportamiento. En las aplicaciones full-stack tradicionales, frecuentemente se termina con "modelos de dominio anémicos" — objetos planos que pierden sus métodos al ser serializados del servidor al cliente. Esto te obliga a duplicar la lógica en ambos lados o a trabajar con objetos de datos planos que no encapsulan la lógica de negocio.

El problema: Imagina que tienes una clase User con métodos como greet(), getInitials() o hasPermission(). Cuando devuelves esto desde una función load del servidor, se serializa a JSON y el cliente recibe un objeto plano sin ningún método. Necesitarías:

Escribir funciones utilitarias separadas en el cliente (getUserInitials(user), userGreeting(user))
Reconstruir manualmente la instancia de la clase en el cliente
Abandonar el uso de clases por completo

La solución: Con Transport, puedes mantener modelos de dominio ricos con métodos que funcionan de manera idéntica en el servidor y en el cliente. Las instancias de clases se serializan automáticamente en el servidor y se reconstruyen con todos sus métodos intactos en el cliente.

Cuándo usar este patrón:

Perfiles de usuario con propiedades calculadas (iniciales, nombres para mostrar, nombres completos, verificaciones de permisos)
Entidades de negocio con lógica de validación y transformación (validateEmail, formatAddress)
Objetos de dominio que necesitan mantener invariantes (asegurar que un rango de fechas sea válido, mantener precios no negativos)
Modelos que se benefician de la encapsulación y los principios de POO (ocultando detalles de implementación)

Beneficios del mundo real:

Mantén tu código DRY (Don't Repeat Yourself) — escribe la lógica de negocio una sola vez
Seguridad de tipos en toda la pila — TypeScript garantiza consistencia
Pruebas más sencillas — prueba tu lógica de dominio independientemente del código del framework
Mejor experiencia para el desarrollador — el autocompletado del IDE funciona con métodos, no solo con datos

Este enfoque es especialmente poderoso cuando se combina con el sistema de tipos de TypeScript, ya que obtienes verificación en tiempo de compilación que asegura que tu lógica de dominio se use correctamente en ambos lados del límite servidor/cliente.

// lib/models/User.ts
export class User {
  constructor(
    public id: number,
    public name: string,
    public email: string,
    public createdAt: Date
  ) {}

  greet() {
    return `Hello, ${this.name}!`;
  }

  isNew() {
    const oneWeekAgo = new Date();
    oneWeekAgo.setDate(oneWeekAgo.getDate() - 7);
    return this.createdAt > oneWeekAgo;
  }

  getInitials() {
    return this.name
      .split(' ')
      .map(part => part[0])
      .join('')
      .toUpperCase();
  }
}

// src/hooks.ts
import type { Transport } from '@sveltejs/kit';
import { User } from '$lib/models/User';

export const transport: Transport = {
  User: {
    encode: (value) =>
      value instanceof User && {
        id: value.id,
        name: value.name,
        email: value.email,
        createdAt: value.createdAt
      },
    decode: (data) =>
      new User(data.id, data.name, data.email, data.createdAt)
  }
};

// routes/+page.server.ts
export async function load() {
  const user = new User(
    1,
    'Alice Smith',
    'alice@example.com',
    new Date()
  );

  return { user };
}

// routes/+page.svelte
<script lang="ts">
  let { data } = $props();

  // user is automatically decoded back to a User instance!
  // All methods are available
</script>

<h1>{data.user.greet()}</h1>
<p>Initials: {data.user.getInitials()}</p>
<p>New user: {data.user.isNew() ? 'Yes' : 'No'}</p>

2. Tipos matemáticos (vectores, matrices)

Perfecto para juegos, visualización de datos o aplicaciones de computación científica. Los objetos matemáticos como vectores, matrices, cuaterniones y números complejos se benefician enormemente de tener sus operaciones encapsuladas como métodos en lugar de estar dispersas como funciones utilitarias.

El desafío: Al construir experiencias interactivas — ya sea un sistema de partículas, una simulación de física o una visualización de datos — se trabaja con cientos o miles de operaciones matemáticas. Sin una encapsulación adecuada, el código se llena de llamadas a funciones utilitarias que ocultan la lógica real.

Por qué los tipos matemáticos necesitan Transport: Los enfoques tradicionales requieren que realices todos los cálculos en el servidor (limitando la interactividad) o que dupliques toda tu biblioteca matemática en ambos lados. Transport resuelve esto permitiéndote definir tus tipos matemáticos una vez y usarlos en todas partes.

Considera la diferencia en claridad del código:

// With Transport - clean and intuitive
const force = velocity.normalize().multiply(speed)
const distance = positionA.subtract(positionB).magnitude()

// Without Transport - verbose utility functions
const force = multiplyVector(normalizeVector(velocity), speed)
const distance = vectorMagnitude(subtractVectors(positionA, positionB))

Casos de uso comunes:

Motores de juego — Cálculos de física, detección de colisiones, transformaciones espaciales, sistemas de movimiento
Visualización de datos — Transformaciones de coordenadas, proyecciones, cálculos de zoom/paneo
Computación científica — Simulaciones numéricas, operaciones de álgebra lineal, procesamiento de señales
Animación — Interpolación, funciones de easing, cálculos de trayectorias, curvas de Bézier
Gráficos 3D — Matrices de rotación, controles de cámara, transformaciones de malla

Escenario del mundo real: Imagina construir un sistema de partículas en tiempo real donde el servidor calcula las posiciones y velocidades iniciales, pero el cliente maneja la animación. Con Transport, puedes:

Calcular los estados iniciales de las partículas en el servidor usando matemática de vectores
Enviar las partículas al cliente donde automáticamente se convierten en instancias de Vector
Actualizar las posiciones en cada frame usando los mismos métodos de Vector
Nunca duplicar código ni preocuparte por la sincronización

Este patrón es especialmente poderoso cuando se combina con el SSR de SvelteKit — puedes realizar cálculos complejos en el servidor (aprovechando más poder de CPU) y luego continuar esos cálculos sin interrupciones en el navegador.

// lib/math/Vector.ts
export class Vector {
	constructor(
		public x: number,
		public y: number
	) {}

	magnitude() {
		return Math.sqrt(this.x * this.x + this.y * this.y)
	}

	normalize() {
		const mag = this.magnitude()
		return new Vector(this.x / mag, this.y / mag)
	}

	add(other: Vector) {
		return new Vector(this.x + other.x, this.y + other.y)
	}

	dot(other: Vector) {
		return this.x * other.x + this.y * other.y
	}
}

// src/hooks.ts
import type { Transport } from '@sveltejs/kit'
import { Vector } from '$lib/math/Vector'

export const transport: Transport = {
	Vector: {
		encode: (value) => value instanceof Vector && [value.x, value.y],
		decode: ([x, y]) => new Vector(x, y)
	}
}

// routes/simulation/+page.server.ts
export async function load() {
	const particles = [
		{ position: new Vector(10, 20), velocity: new Vector(1, -0.5) },
		{ position: new Vector(50, 30), velocity: new Vector(-0.8, 1.2) }
	]

	return { particles }
}

3. Objetos de dinero/moneda

Esencial para aplicaciones de comercio electrónico donde la precisión importa. Uno de los pecados capitales en el software financiero es usar números de punto flotante para cálculos de moneda. El infame problema de 0.1 + 0.2 !== 0.3 de JavaScript puede llevar a graves errores contables, reclamos de clientes e incluso problemas legales al manejar dinero.

El problema del punto flotante:

// ❌ This is why you need a Money class
let price = 0.1
let tax = 0.2
console.log(price + tax) // 0.30000000000000004

// This compounds with multiple operations
let total = 0
for (let i = 0; i < 10; i++) {
	total += 0.1
}
console.log(total) // 0.9999999999999999

Una clase Money resuelve múltiples problemas críticos:

Precisión: Almacena los montos como enteros (centavos) para evitar completamente los errores de aritmética de punto flotante
Seguridad de moneda: El sistema de tipos previene la suma accidental de USD a EUR, evitando errores costosos
Formato: Visualización consistente y localizada en toda tu aplicación ($1,234.56 vs 1.234,56 €)
Inmutabilidad: Las operaciones con dinero devuelven nuevas instancias, previniendo mutaciones accidentales que podrían corromper datos financieros
Lógica de negocio: Los cálculos de impuestos, reglas de descuento, estrategias de redondeo y conversiones de moneda permanecen encapsulados y testeables

Cuándo necesitas este patrón:

Plataformas de e-commerce — Carritos de compra, precios de productos, cálculos de checkout, totales de pedidos
Aplicaciones financieras — Sistemas contables, facturación, procesamiento de pagos, reportes financieros
Facturación SaaS — Gestión de suscripciones, precios basados en uso, prorrateo, sistemas de crédito
Sistemas de punto de venta — Manejo de transacciones, generación de recibos, gestión de caja
Aplicaciones multimoneda — Mercados internacionales, plataformas de forex, reservas de viajes

Impacto en el mundo real: Sin una clase Money, pasarías números planos y necesitarías:

Recordar redondear correctamente en cada punto de cálculo
Manejar la lógica de formato en cada componente que muestra precios
Escribir pruebas para cada operación aritmética para detectar bugs de precisión
Validar manualmente la compatibilidad de monedas antes de los cálculos
Arriesgarte a problemas regulatorios con cálculos financieros incorrectos

Con Transport, tus objetos Money funcionan de manera idéntica ya sea calculando totales en el servidor o mostrando precios en el navegador. Las mismas reglas de redondeo, las mismas garantías de precisión, el mismo formato — todo mantenido automáticamente a través del límite servidor/cliente.

// lib/types/Money.ts
export class Money {
  // Store cents to avoid floating point issues
  private cents: number;

  constructor(
    amount: number,
    public currency: string = 'USD'
  ) {
    this.cents = Math.round(amount * 100);
  }

  get amount() {
    return this.cents / 100;
  }

  add(other: Money) {
    if (this.currency !== other.currency) {
      throw new Error('Cannot add different currencies');
    }
    return new Money(this.amount + other.amount, this.currency);
  }

  multiply(factor: number) {
    return new Money(this.amount * factor, this.currency);
  }

  format() {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: this.currency
    }).format(this.amount);
  }
}

// src/hooks.ts
import type { Transport } from '@sveltejs/kit';
import { Money } from '$lib/types/Money';

export const transport: Transport = {
  Money: {
    encode: (value) =>
      value instanceof Money && {
        amount: value.amount,
        currency: value.currency
      },
    decode: (data) =>
      new Money(data.amount, data.currency)
  }
};

// routes/checkout/+page.server.ts
export async function load() {
  return {
    cart: {
      items: [
        { name: 'Widget', price: new Money(29.99) },
        { name: 'Gadget', price: new Money(49.99) }
      ],
      shipping: new Money(5.00),
      tax: new Money(6.75)
    }
  };
}

// routes/checkout/+page.svelte
<script lang="ts">
  let { data } = $props();

  const subtotal = data.cart.items.reduce(
    (sum, item) => sum.add(item.price),
    new Money(0)
  );

  const total = subtotal
    .add(data.cart.shipping)
    .add(data.cart.tax);
</script>

<div>
  <p>Subtotal: {subtotal.format()}</p>
  <p>Shipping: {data.cart.shipping.format()}</p>
  <p>Tax: {data.cart.tax.format()}</p>
  <p><strong>Total: {total.format()}</strong></p>
</div>

4. Tipos Result (para manejo de errores)

Implementa manejo de errores funcional con tipos Result. El manejo de errores tradicional con try/catch puede dificultar el seguimiento del flujo del código, oculta los errores en las firmas de tipos y te obliga a manejar errores en el nivel de abstracción incorrecto. El patrón Result, popularizado por Rust y los lenguajes de programación funcional, proporciona un enfoque más explícito y componible para el manejo de errores.

El problema con el manejo de errores tradicional:

// ❌ Errors are invisible in the type signature
async function getUser(id: string): Promise<User> {
	// Might throw DatabaseError, ValidationError, NetworkError...
	// Caller has no idea what errors to handle
}

// Caller is forced to either:
try {
	const user = await getUser('123')
	// Hope for the best...
} catch (error) {
	// What type of error? Who knows! 🤷
}

Por qué los tipos Result son superiores: En lugar de lanzar excepciones que pueden ser capturadas en cualquier lugar (o peor, olvidadas), los tipos Result hacen que el manejo de errores sea explícito en tus firmas de tipo. Una función que devuelve Result<User, DatabaseError> comunica claramente que puede fallar y qué tipo de error esperar.

// ✅ Errors are explicit in the type signature
async function getUser(id: string): Promise<Result<User, DatabaseError>> {
	// Types force you to handle both cases
}

// Caller must handle both success and failure
const result = await getUser('123')
if (result.isSuccess) {
	const user = result.value // Type: User
} else {
	const error = result.error // Type: DatabaseError
}

Beneficios clave:

Manejo de errores explícito: Imposible ignorar los errores — son parte de la firma de tipo
Componibilidad: Encadena operaciones con map, flatMap, andThen y otros combinadores
Sin necesidad de try/catch: Flujo de código más limpio sin el boilerplate del manejo de excepciones en todas partes
Seguridad de tipos: El compilador asegura que manejes tanto los casos de éxito como de fallo
Programación orientada a ferrocarriles: Construye pipelines de datos robustos donde los errores se propagan automáticamente
Mejor refactorización: Los cambios en los tipos de error se detectan en tiempo de compilación, no en tiempo de ejecución

Cuándo usar este patrón:

Respuestas de API — Manejo de errores estructurado y con seguridad de tipos del servidor al cliente
Operaciones de base de datos — Manejo explícito de fallos de consulta, problemas de conexión
Pipelines de validación — Encadenamiento de múltiples pasos de validación con acumulación de errores
Llamadas a servicios externos — Gestión elegante de fallos de APIs de terceros con lógica de reintento
Transformaciones de datos — Procesos de múltiples pasos donde cualquier paso puede fallar
Operaciones de E/S de archivos — Manejo de fallos de lectura/escritura sin excepciones

Escenario del mundo real: Imagina construir un flujo de registro de usuario que valida el email, verifica duplicados, crea la cuenta y envía un email de bienvenida. Cada paso puede fallar de manera diferente:

Result.ok(formData)
	.map(validateEmail) // ValidationError
	.flatMap(checkDuplicate) // DatabaseError
	.flatMap(createAccount) // DatabaseError
	.flatMap(sendWelcome) // EmailError
	.match(
		(user) => console.log('Success:', user),
		(error) => handleError(error) // All error types handled
	)

Con Transport, puedes devolver tipos Result desde las funciones de carga del servidor y que se reconstruyan automáticamente en el navegador con todos sus métodos intactos. Esto mantiene tu estrategia de manejo de errores a lo largo de toda la pila, asegurando una gestión de errores consistente y con seguridad de tipos en todas partes.

// lib/types/Result.ts
export class Result<T, E> {
	constructor(
		private _value?: T,
		private _error?: E,
		public readonly isSuccess: boolean = true
	) {}

	static ok<T, E>(value: T): Result<T, E> {
		return new Result<T, E>(value, undefined, true)
	}

	static err<T, E>(error: E): Result<T, E> {
		return new Result<T, E>(undefined, error, false)
	}

	get value(): T {
		if (!this.isSuccess) throw new Error('Called value on error Result')
		return this._value!
	}

	get error(): E {
		if (this.isSuccess) throw new Error('Called error on success Result')
		return this._error!
	}

	map<U>(fn: (value: T) => U): Result<U, E> {
		if (!this.isSuccess) return Result.err(this.error)
		return Result.ok(fn(this.value))
	}

	unwrapOr(defaultValue: T): T {
		return this.isSuccess ? this.value : defaultValue
	}
}

// src/hooks.ts
import type { Transport } from '@sveltejs/kit'
import { Result } from '$lib/types/Result'

export const transport: Transport = {
	Result: {
		encode: (value) =>
			value instanceof Result && {
				value: value.isSuccess ? value.value : undefined,
				error: value.isSuccess ? undefined : value.error,
				isSuccess: value.isSuccess
			},
		decode: (data) => (data.isSuccess ? Result.ok(data.value) : Result.err(data.error))
	}
}

// routes/api/users/+server.ts
import { Result } from '$lib/types/Result'

export async function GET() {
	try {
		const users = await db.users.findMany()
		return json(Result.ok(users))
	} catch (error) {
		return json(Result.err(error.message))
	}
}

5. Objetos de color

Para sistemas de diseño, tematización o aplicaciones gráficas. Los colores son engañosamente complejos — pueden representarse en múltiples formatos (hex, RGB, HSL, RGBA), necesitan validación para asegurar que los valores estén en rangos válidos, y frecuentemente requieren transformaciones como aclarar, oscurecer o ajustar la opacidad.

El problema del "string soup":

// ❌ Without a Color class - fragile and error-prone
const primary = '#3b82f6'
const lightPrimary = lightenHex(primary, 20) // Custom function needed
const primaryRgba = hexToRgba(primary, 0.5) // Another function
const isAccessible = checkContrast(primary, '#ffffff') // More utilities

// What if someone passes "rgb(59, 130, 246)"?
// What if values go out of range?
// How do you test all these utilities?

Por qué importa una clase Color: Cuando manejas strings de hex, tuplas RGB y valores de opacidad en toda tu base de código, es fácil introducir bugs. ¿Es #fff lo mismo que #ffffff? ¿Debería rgb(300, 50, 50) recortarse o lanzar un error? Una clase Color responde estas preguntas una vez, de forma consistente.

Beneficios clave:

Conversión de formato: Convierte sin problemas entre hex, RGB, RGBA, HSL — sin memorizar fórmulas de conversión
Validación automática: Los valores RGB se recortan automáticamente a 0-255, el alpha a 0-1, previniendo colores inválidos
Transformaciones encadenables: color.lighten(20).withAlpha(0.5) se lee como en inglés
Inmutabilidad: Las operaciones de color devuelven nuevas instancias, previniendo mutaciones accidentales en objetos de tema compartidos
Seguridad de tipos: TypeScript asegura que siempre trabajes con objetos Color válidos, no strings aleatorios
Consistencia: La misma lógica de color en el servidor (generación de temas SSR) y el cliente (selectores de color interactivos)

Cuándo usar este patrón:

Sistemas de diseño — Mantener paletas de colores consistentes, generar tintes/sombras, gestión de colores de marca
Motores de tematización — Cambio dinámico de temas, modo oscuro, temas personalizables por el usuario
Visualización de datos — Escalas de color programáticas (rojo→amarillo→verde), colores de categorías, mapas de calor
Aplicaciones gráficas — Renderizado en canvas, procesamiento de imágenes, generación de filtros CSS
Herramientas de accesibilidad — Verificación de contraste WCAG, simulación de daltonismo, colores de texto legibles
Sistemas CSS-in-JS — Manipulación de colores en tiempo de ejecución para componentes con estilos

Ejemplo del mundo real: Imagina construir un sistema de diseño donde defines un color primario, y el sistema genera automáticamente:

10 tonos de claro a oscuro
Estados hover y activo (ligeramente más oscuros)
Estado deshabilitado (opacidad reducida)
Color de texto que cumple los requisitos de contraste WCAG
Color del anillo de foco (primario con alpha ajustado)

Con una clase Color y Transport, defines estas reglas una vez en el servidor, generas la paleta completa durante el SSR y tienes todos los mismos métodos de manipulación de color disponibles cuando los usuarios interactúan con selectores de color o cambiadores de tema en el navegador.

// lib/types/Color.ts
export class Color {
	constructor(
		public r: number,
		public g: number,
		public b: number,
		public a: number = 1
	) {
		this.r = Math.max(0, Math.min(255, r))
		this.g = Math.max(0, Math.min(255, g))
		this.b = Math.max(0, Math.min(255, b))
		this.a = Math.max(0, Math.min(1, a))
	}

	static fromHex(hex: string) {
		const r = parseInt(hex.slice(1, 3), 16)
		const g = parseInt(hex.slice(3, 5), 16)
		const b = parseInt(hex.slice(5, 7), 16)
		return new Color(r, g, b)
	}

	toHex() {
		const toHex = (n: number) => n.toString(16).padStart(2, '0')
		return `#${toHex(this.r)}${toHex(this.g)}${toHex(this.b)}`
	}

	toRgba() {
		return `rgba(${this.r}, ${this.g}, ${this.b}, ${this.a})`
	}

	lighten(amount: number) {
		return new Color(this.r + amount, this.g + amount, this.b + amount, this.a)
	}

	withAlpha(alpha: number) {
		return new Color(this.r, this.g, this.b, alpha)
	}
}

// src/hooks.ts
import type { Transport } from '@sveltejs/kit'
import { Color } from '$lib/types/Color'

export const transport: Transport = {
	Color: {
		encode: (value) => value instanceof Color && [value.r, value.g, value.b, value.a],
		decode: ([r, g, b, a]) => new Color(r, g, b, a)
	}
}

// routes/theme/+page.server.ts
export async function load() {
	return {
		theme: {
			primary: new Color(59, 130, 246),
			secondary: new Color(139, 92, 246),
			background: new Color(255, 255, 255),
			text: new Color(17, 24, 39)
		}
	}
}

6. Optimización de rendimiento: deduplicación

Para conjuntos de datos grandes con objetos repetidos, puedes optimizar la serialización para reducir dramáticamente el tamaño del payload y el uso de memoria. Este es un caso de uso más avanzado que aborda un problema de rendimiento específico: cuando tienes muchos objetos que comparten referencias a los mismos datos, la serialización ingenua duplicará esos datos, llevando a payloads inflados, cargas de página lentas y potencialmente alcanzar los límites de memoria en entornos serverless.

El problema: duplicación de datos a escala

// ❌ Without optimization - wasteful serialization
const users = [
	{ id: 1, name: 'Alice', org: { id: 'org1', name: 'Acme Corp', plan: 'Enterprise' } },
	{ id: 2, name: 'Bob', org: { id: 'org1', name: 'Acme Corp', plan: 'Enterprise' } },
	{ id: 3, name: 'Carol', org: { id: 'org1', name: 'Acme Corp', plan: 'Enterprise' } }
	// ... 997 more users from 'org1'
]
// The organization data is serialized 1,000 times!

Impacto en el mundo real: Imagina construir una herramienta de gestión de proyectos que carga 1.000 usuarios, donde cada usuario pertenece a una de 10 organizaciones. Sin optimización, serializarías cada objeto de organización aproximadamente 100 veces (una vez por cada usuario que pertenece a ella). Si cada objeto de organización tiene 500 bytes, eso son 50KB de datos redundantes en tu payload HTML. Con relaciones anidadas más complejas (Organizaciones → Equipos → Usuarios → Proyectos → Tareas), este problema crece exponencialmente.

Ejemplo real: El equipo de Cole Crouter alcanzó el límite de memoria de 128MB de Cloudflare Pages al serializar un conjunto de datos grande. Al implementar la deduplicación basada en Transport, redujeron la sobrecarga de serialización y obtuvieron tiempos de carga de página 2-3 veces más rápidos. Lee su excelente publicación en el blog.

Cómo funciona el patrón de deduplicación:

Analizar relaciones: Identifica objetos que se comparten (como Organization o Category)
Agrupar datos: Organiza objetos relacionados juntos (agrupa usuarios por ID de organización)
Codificar eficientemente: Serializa los objetos compartidos una vez, almacena referencias por ID
Reconstruir relaciones: Reconstruye el grafo de objetos en el cliente usando búsquedas por ID

Cuándo importa esta optimización:

Conjuntos de datos grandes: Dashboards de administración que cargan miles de registros (usuarios, productos, transacciones)
Datos jerárquicos: Organizaciones → Departamentos → Equipos → Usuarios → Tareas
Datos normalizados: Relaciones estilo base de datos transportadas al navegador
Restricciones de memoria: Entornos serverless (Cloudflare 128MB, límites de Vercel 250MB)
Optimización de red: Los usuarios de móvil con conexiones lentas necesitan payloads más pequeños
Aplicaciones en tiempo real: Las actualizaciones frecuentes de datos hacen que el tamaño del payload sea crítico

El intercambio: Esta técnica agrega complejidad a tu código de Transport. Úsala solo cuando hayas perfilado e identificado que la duplicación de datos es realmente un cuello de botella. Para la mayoría de las aplicaciones, el patrón estándar de Transport es suficiente. Pero cuando alcanzas límites de memoria o cargas de página lentas debido a conjuntos de datos grandes, este patrón puede ser un salvavidas.

La clave del insight: mientras que devalue maneja la deduplicación para objetos planos automáticamente, los transporters personalizados te dan control total para implementar optimizaciones específicas del dominio para tus estructuras de datos.

// lib/models/App.ts
export class App {
	constructor(
		public id: string,
		public name: string
	) {}
}

export class User {
	constructor(
		public id: string,
		public name: string,
		public app: App
	) {}
}

// src/hooks.ts
import type { Transport } from '@sveltejs/kit'
import { App, User } from '$lib/models'

export const transport: Transport = {
	App: {
		encode: (value) =>
			value instanceof App && {
				id: value.id,
				name: value.name
			},
		decode: (data) => new App(data.id, data.name)
	},

	// Optimize: serialize User[] by grouping by app
	'User[]': {
		encode: (value) => {
			if (!Array.isArray(value) || !value.every((u) => u instanceof User)) {
				return false
			}

			// Group users by app
			const byApp = Object.groupBy(value, (user) => user.app.id)

			return {
				apps: Object.values(byApp).map((users) => users![0].app),
				usersByApp: Object.entries(byApp).map(([appId, users]) => ({
					appId,
					users: users!.map((u) => ({ id: u.id, name: u.name }))
				}))
			}
		},

		decode: (data) => {
			const appsById = new Map(data.apps.map((app: any) => [app.id, new App(app.id, app.name)]))

			return data.usersByApp.flatMap((group: any) =>
				group.users.map((u: any) => new User(u.id, u.name, appsById.get(group.appId)!))
			)
		}
	}
}

7. Objetos de rango de fechas

Común en dashboards de analítica y herramientas de reportes. Los rangos de fechas aparecen en todas partes en las aplicaciones de negocio — filtrar datos, programar eventos, definir períodos de facturación, establecer ventanas de disponibilidad, comparar períodos de tiempo. Si bien podrías representarlos como dos objetos Date separados o pares de timestamps, una clase DateRange proporciona significado semántico, seguridad de tipos y operaciones útiles que previenen bugs.

El problema de las dos fechas:

// ❌ Without DateRange - error-prone and verbose
function getMetrics(startDate: Date, endDate: Date) {
	// Did the caller swap the dates?
	// Are they in the same timezone?
	// Is the range inclusive or exclusive?
	if (startDate > endDate) {
		throw new Error('Invalid date range')
	}

	// Duplicate this validation everywhere...
}

// Using it is confusing:
getMetrics(endDate, startDate) // Oops! Wrong order

Por qué importa DateRange: El manejo de fechas es notoriamente difícil — problemas de zona horaria, años bisiestos, horario de verano, rangos inclusivos vs exclusivos. Al encapsular esta complejidad en una clase, manejas todos los casos límite una vez y ganas confianza en que tu lógica de fechas es correcta en todas partes.

Beneficios clave:

Validación: Asegura que la fecha de inicio sea anterior a la fecha de fin en el momento de la construcción — falla rápido con errores claros
Fábricas de conveniencia: Crea rangos comunes con código legible: DateRange.lastNDays(30), DateRange.thisMonth()
Cálculos: Calcula la duración en días/horas, verifica si una fecha cae dentro del rango, divide rangos
Comparaciones: Verifica si los rangos se superponen (para conflictos de programación), son adyacentes o se contienen entre sí
Inmutabilidad: Los rangos no pueden ser modificados accidentalmente después de su creación, previniendo bugs sutiles
Lógica de negocio: Maneja casos límite como normalización de zona horaria, límites inclusivos/exclusivos, exclusión de fines de semana
Legibilidad: campaign.period.contains(today) vs campaign.start <= today && today <= campaign.end

Casos de uso comunes:

Dashboards de analítica — Selectores de rango de fechas ("Últimos 7 días", "Este trimestre"), filtrado de métricas, análisis comparativo ("Esta semana vs la semana pasada"), escalas de tiempo en gráficos
Sistemas de reservas — Reservas de hotel con check-in/check-out, programación de salas de reuniones, períodos de alquiler de equipos, detección de doble reserva
Herramientas de reportes — Períodos financieros (trimestres, años fiscales), evaluaciones de desempeño, ventanas de auditoría de cumplimiento, rangos de fechas personalizados
Aplicaciones de programación — Calendarios de disponibilidad de empleados, gestión de turnos, seguimiento de vacaciones, períodos bloqueados
Facturación SaaS — Períodos de suscripción, ventanas de prueba, ciclos de facturación basados en uso, cálculos de prorrateo
Gestión de campañas — Períodos promocionales, duraciones de pruebas A/B, ofertas estacionales

Ejemplo del mundo real: Imagina construir un dashboard de analítica donde los usuarios pueden seleccionar "Últimos 7 días", "Últimos 30 días" o un rango personalizado. Con DateRange:

// Server calculates the range based on user selection
const range =
	url.searchParams.get('period') === '7' ? DateRange.lastNDays(7) : DateRange.lastNDays(30)

// Query database with the range
const metrics = await db.getMetrics(range.start, range.end)

// Client receives the DateRange object and can:
// - Display it: "Showing data for Dec 20 - Dec 27"
// - Filter CSV exports based on the same range
// - Check if user's selected date is in range for highlighting
// - Calculate "days remaining" for trial periods

Cuando cargas datos de analítica en el servidor, el objeto DateRange puede pasarse al cliente donde continúa funcionando para el filtrado del lado del cliente, la lógica de visualización y los cálculos de fechas. Esto mantiene tu lógica de manejo de fechas consistente entre entornos y elimina los bugs de zona horaria del tipo "funciona en el servidor pero falla en el navegador".

// lib/types/DateRange.ts
export class DateRange {
	constructor(
		public start: Date,
		public end: Date
	) {
		if (start > end) {
			throw new Error('Start date must be before end date')
		}
	}

	static today() {
		const start = new Date()
		start.setHours(0, 0, 0, 0)
		const end = new Date()
		end.setHours(23, 59, 59, 999)
		return new DateRange(start, end)
	}

	static lastNDays(n: number) {
		const end = new Date()
		const start = new Date()
		start.setDate(start.getDate() - n)
		return new DateRange(start, end)
	}

	get days() {
		const diff = this.end.getTime() - this.start.getTime()
		return Math.ceil(diff / (1000 * 60 * 60 * 24))
	}

	contains(date: Date) {
		return date >= this.start && date <= this.end
	}

	overlaps(other: DateRange) {
		return this.start <= other.end && other.start <= this.end
	}
}

// src/hooks.ts
import type { Transport } from '@sveltejs/kit'
import { DateRange } from '$lib/types/DateRange'

export const transport: Transport = {
	DateRange: {
		encode: (value) => value instanceof DateRange && [value.start, value.end],
		decode: ([start, end]) => new DateRange(start, end)
	}
}

// routes/analytics/+page.server.ts
export async function load({ url }) {
	const period = url.searchParams.get('period') || '30'
	const range = DateRange.lastNDays(parseInt(period))

	const metrics = await db.getMetrics(range.start, range.end)

	return { range, metrics }
}

Patrones Avanzados

Tipos Personalizados Anidados

Transport maneja el anidamiento automáticamente, por lo que los tipos personalizados pueden contener otros tipos personalizados.

// lib/models/Order.ts
export class OrderItem {
	constructor(
		public productId: string,
		public quantity: number,
		public price: Money
	) {}

	get total() {
		return this.price.multiply(this.quantity)
	}
}

export class Order {
	constructor(
		public id: string,
		public items: OrderItem[],
		public createdAt: Date
	) {}

	get total() {
		return this.items.reduce((sum, item) => sum.add(item.total), new Money(0))
	}
}

// src/hooks.ts
export const transport: Transport = {
	Money: {
		/* ... */
	},

	OrderItem: {
		encode: (value) =>
			value instanceof OrderItem && {
				productId: value.productId,
				quantity: value.quantity,
				price: value.price // Money is automatically encoded
			},
		decode: (data) => new OrderItem(data.productId, data.quantity, data.price)
	},

	Order: {
		encode: (value) =>
			value instanceof Order && {
				id: value.id,
				items: value.items, // OrderItem[] is automatically encoded
				createdAt: value.createdAt
			},
		decode: (data) => new Order(data.id, data.items, data.createdAt)
	}
}

Uso con Funciones Remotas

Transport funciona sin inconvenientes con las funciones remotas de SvelteKit (query, command, form).

// lib/server/products.remote.ts
import { query } from '$app/server';
import { Product } from '$lib/models/Product';

export const getProduct = query(
  v.string(),
  async (id) => {
    const data = await db.products.findUnique({ where: { id } });
    return new Product(data.id, data.name, new Money(data.price));
  }
);

// routes/products/[id]/+page.svelte
<script lang="ts">
  import { getProduct } from '$lib/server/products.remote';

  let { data } = $props();

  // Product is automatically decoded with all methods available
  const product = getProduct(data.id);
</script>

{#if product.ready}
  <h1>{product.current.name}</h1>
  <p>{product.current.price.format()}</p>
{/if}

Buenas Prácticas

1. Mantén los Datos Codificados al Mínimo

Solo codifica los datos necesarios para reconstruir el objeto. No codifiques propiedades calculadas.

// ✅ Good - only encode data
encode: (value) =>
	value instanceof User && {
		id: value.id,
		name: value.name
	}

// ❌ Bad - encoding computed values
encode: (value) =>
	value instanceof User && {
		id: value.id,
		name: value.name,
		initials: value.getInitials() // Don't do this!
	}

2. Usa Type Guards en Encode

Siempre verifica si el valor es una instancia de tu tipo antes de codificarlo.

encode: (value) => {
	if (!(value instanceof MyType)) return false

	return {
		// ... encoding logic
	}
}

3. Maneja los Casos Extremos

Considera null, undefined y la validación en tu función decode.

decode: (data) => {
	// Validate the data structure
	if (!data || typeof data.id !== 'number') {
		throw new Error('Invalid User data')
	}

	return new User(data.id, data.name)
}

4. No Codifiques Valores Falsy

La función encode usa los valores falsy como señal de que el valor no es una instancia. Ten cuidado con 0, "", etc.

// ❌ Bad - 0 is falsy!
encode: (value) => value instanceof Counter && value.count

// ✅ Good - wrap in object/array
encode: (value) => value instanceof Counter && [value.count]

Errores Comunes

1. Olvidar la Verificación con instanceof

// ❌ Bad - will encode everything!
encode: (value) => ({ data: value })

// ✅ Good - check type first
encode: (value) => value instanceof MyType && { data: value.data }

2. Codificar Datos No Serializables

// ❌ Bad - Functions can't be serialized
export class Component {
	onClick = () => console.log('clicked')
}

encode: (value) =>
	value instanceof Component && {
		onClick: value.onClick // Won't work!
	}

3. Referencias Circulares en Tipos Personalizados

Aunque devalue maneja las referencias circulares en objetos simples, ten cuidado con los tipos personalizados.

export class Node {
	parent?: Node
	children: Node[] = []
}

// This could cause issues - be explicit
encode: (value) =>
	value instanceof Node && {
		children: value.children
		// Don't encode parent to avoid circularity
	}

Prueba tus Transporters

// lib/types/Money.test.ts
import { describe, it, expect } from 'vitest'
import { Money } from './Money'
import { transport } from '../hooks'

describe('Money transporter', () => {
	it('should encode and decode correctly', () => {
		const original = new Money(99.99, 'USD')

		const encoded = transport.Money.encode(original)
		expect(encoded).toEqual({
			amount: 99.99,
			currency: 'USD'
		})

		const decoded = transport.Money.decode(encoded)
		expect(decoded).toBeInstanceOf(Money)
		expect(decoded.amount).toBe(99.99)
		expect(decoded.currency).toBe('USD')
		expect(decoded.format()).toBe('$99.99')
	})

	it('should return false for non-Money values', () => {
		expect(transport.Money.encode({})).toBe(false)
		expect(transport.Money.encode(null)).toBe(false)
		expect(transport.Money.encode(42)).toBe(false)
	})
})

Conclusión

El hook Transport es una característica poderosa que te permite mantener modelos de dominio ricos a través de la frontera servidor/cliente en SvelteKit. Al definir lógica de serialización personalizada, puedes:

Mantener tu lógica de negocio encapsulada en clases
Conservar la seguridad de tipos en todo el stack
Optimizar la transferencia de datos para conjuntos de datos grandes
Construir aplicaciones más mantenibles y testeables

La clave está en pensar en Transport como un puente entre tus modelos de dominio del lado del servidor y las necesidades del lado del cliente, lo que te permite escribir código más limpio y orientado a objetos mientras SvelteKit maneja la complejidad de serialización por ti.

Introducción

El desafío de la serialización

El problema que Transport resuelve

Cómo funciona Transport

Estructura básica

El patrón encode/decode

Casos de uso del mundo real

1. Modelos de dominio con métodos

2. Tipos matemáticos (vectores, matrices)

3. Objetos de dinero/moneda

4. Tipos Result (para manejo de errores)

5. Objetos de color

6. Optimización de rendimiento: deduplicación

7. Objetos de rango de fechas

Patrones Avanzados

Tipos Personalizados Anidados

Uso con Funciones Remotas

Buenas Prácticas

1. Mantén los Datos Codificados al Mínimo

2. Usa Type Guards en Encode

3. Maneja los Casos Extremos

4. No Codifiques Valores Falsy

Errores Comunes

1. Olvidar la Verificación con instanceof

2. Codificar Datos No Serializables

3. Referencias Circulares en Tipos Personalizados

Prueba tus Transporters

Conclusión

Lectura Adicional