Introdução

O Desafio da Serialização

Ao criar aplicações full-stack com SvelteKit, você frequentemente precisa passar dados entre o servidor e o cliente. Por padrão, o SvelteKit usa o devalue para serializar dados retornados de funções load, ações de formulário e funções remotas. Embora o devalue lide com muitos tipos além do JSON (como Date, Map, Set, BigInt, RegExp e até referências cíclicas), ele não consegue serializar automaticamente instâncias de classes personalizadas.

É aqui que o hook Transport entra em cena. Disponível desde o SvelteKit 2.11, o Transport permite que você defina lógica personalizada de serialização/desserialização para suas próprias classes, possibilitando que você passe objetos de domínio complexos através da fronteira servidor/cliente de forma transparente.

O Problema que o Transport Resolve

Considere este cenário comum:

// ❌ 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
	}
}

Sem o Transport, o SvelteKit não consegue serializar a instância da classe User. Você receberia um erro: "Cannot stringify arbitrary non-POJOs".

Como o Transport Funciona

O hook Transport é definido em src/hooks.js (ou src/hooks.ts) e exporta um objeto transport contendo transportadores para seus tipos personalizados.

Estrutura 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
		}
	}
}

O Padrão Encode/Decode

encode: Executa no servidor. Recebe um valor e deve retornar:
- Um valor não falso (objeto ou array) se o valor for uma instância do seu tipo
- false (ou qualquer valor falso) se não for uma instância do seu tipo
decode: Executa no navegador. Recebe os dados codificados e reconstrói a instância original.

Importante: O valor codificado deve ser serializável pelo devalue. Isso significa que deve ser um objeto simples, array, ou conter apenas tipos serializáveis (strings, números, Dates, Maps, etc.).

Casos de Uso do Mundo Real

1. Modelos de Domínio com Métodos

Um dos casos de uso mais comuns é transportar modelos de domínio que possuem tanto dados quanto comportamento. Em aplicações full-stack tradicionais, você frequentemente acaba com "modelos de domínio anêmicos" - objetos simples que perdem seus métodos quando serializados do servidor para o cliente. Isso te força a duplicar a lógica em ambos os lados ou a trabalhar com objetos de dados simples que não encapsulam a lógica de negócio.

O Problema: Imagine que você tem uma classe User com métodos como greet(), getInitials() ou hasPermission(). Quando você retorna isso de uma função load do servidor, ela é serializada para JSON, e o cliente recebe um objeto simples sem nenhum método. Você precisaria:

Escrever funções utilitárias separadas no cliente (getUserInitials(user), userGreeting(user))
Reconstruir manualmente a instância da classe no cliente
Abrir mão do uso de classes completamente

A Solução: Com o Transport, você pode manter modelos de domínio ricos com métodos que funcionam de forma idêntica tanto no servidor quanto no cliente. As instâncias de classe são automaticamente serializadas no servidor e reconstruídas com todos os seus métodos intactos no cliente.

Quando Usar Este Padrão:

Perfis de usuário com propriedades computadas (iniciais, nomes de exibição, nomes completos, verificações de permissão)
Entidades de negócio com lógica de validação e transformação (validateEmail, formatAddress)
Objetos de domínio que precisam manter invariantes (garantir que um intervalo de datas é válido, manter preços não negativos)
Modelos que se beneficiam do encapsulamento e dos princípios de POO (ocultando detalhes de implementação)

Benefícios no Mundo Real:

Mantenha seu código DRY (Don't Repeat Yourself) - escreva a lógica de negócio uma única vez
Segurança de tipos em toda a stack - TypeScript garante consistência
Testes mais fáceis - teste sua lógica de domínio independentemente do código do framework
Melhor experiência de desenvolvimento - o autocomplete da IDE funciona com métodos, não apenas com dados

Essa abordagem é especialmente poderosa quando combinada com o sistema de tipos do TypeScript, pois você obtém verificação em tempo de compilação que garante que sua lógica de domínio seja usada corretamente em ambos os lados da fronteira 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 (Vetores, Matrizes)

Perfeito para jogos, visualização de dados ou aplicações de computação científica. Objetos matemáticos como vetores, matrizes, quaternions e números complexos se beneficiam enormemente por ter suas operações encapsuladas como métodos em vez de dispersas como funções utilitárias.

O Desafio: Ao criar experiências interativas — seja um sistema de partículas, uma simulação física ou uma visualização de dados — você lida com centenas ou milhares de operações matemáticas. Sem o encapsulamento adequado, seu código fica cheio de chamadas a funções utilitárias que obscurecem a lógica real.

Por que Tipos Matemáticos Precisam do Transport: As abordagens tradicionais exigem que você realize todos os cálculos no servidor (limitando a interatividade) ou duplique toda a sua biblioteca matemática em ambos os lados. O Transport resolve isso permitindo que você defina seus tipos matemáticos uma vez e os use em todo lugar.

Considere a diferença na clareza do 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 Comuns:

Engines de jogos - Cálculos físicos, detecção de colisão, transformações espaciais, sistemas de movimento
Visualização de dados - Transformações de coordenadas, projeções, cálculos de zoom/pan
Computação científica - Simulações numéricas, operações de álgebra linear, processamento de sinais
Animação - Interpolação, funções de easing, cálculos de trajetória, curvas de Bézier
Gráficos 3D - Matrizes de rotação, controles de câmera, transformações de malha

Cenário do Mundo Real: Imagine construir um sistema de partículas em tempo real onde o servidor calcula posições e velocidades iniciais, mas o cliente gerencia a animação. Com o Transport, você pode:

Calcular os estados iniciais das partículas no servidor usando matemática vetorial
Enviar as partículas ao cliente onde elas automaticamente se tornam instâncias de Vector
Atualizar posições a cada frame usando os mesmos métodos de Vector
Nunca duplicar código ou se preocupar com sincronização

Esse padrão é especialmente poderoso quando combinado com o SSR do SvelteKit — você pode realizar cálculos complexos no servidor (aproveitando mais poder de CPU) e então continuar esses cálculos de forma transparente no 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 Dinheiro/Moeda

Essencial para aplicações de e-commerce onde a precisão é importante. Um dos pecados capitais em software financeiro é usar números de ponto flutuante para cálculos de moeda. O famoso problema do 0.1 + 0.2 !== 0.3 do JavaScript pode levar a erros sérios de contabilidade, reclamações de clientes e até problemas legais ao lidar com dinheiro.

O Problema do Ponto Flutuante:

// ❌ 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

Uma classe Money resolve múltiplos problemas críticos:

Precisão: Armazene valores como inteiros (centavos) para evitar completamente erros de aritmética de ponto flutuante
Segurança de moeda: O sistema de tipos previne adicionar acidentalmente USD a EUR, evitando erros custosos
Formatação: Exibição consistente e localizada em toda a sua aplicação ($1.234,56 vs 1.234,56 €)
Imutabilidade: Operações com Money retornam novas instâncias, prevenindo mutações acidentais que poderiam corromper dados financeiros
Lógica de negócio: Cálculos de impostos, regras de desconto, estratégias de arredondamento e conversões de moeda ficam encapsulados e testáveis

Quando Você Precisa Deste Padrão:

Plataformas de e-commerce - Carrinhos de compra, precificação de produtos, cálculos de checkout, totais de pedidos
Aplicações financeiras - Sistemas de contabilidade, faturamento, processamento de pagamentos, relatórios financeiros
Cobrança SaaS - Gerenciamento de assinaturas, precificação baseada em uso, rateio, sistemas de crédito
Sistemas de ponto de venda - Processamento de transações, geração de recibos, gerenciamento de caixa
Aplicações multicambial - Marketplaces internacionais, plataformas de câmbio, reservas de viagens

Impacto no Mundo Real: Sem uma classe Money, você passaria números simples e precisaria:

Lembrar de arredondar corretamente em cada ponto de cálculo
Lidar com lógica de formatação em cada componente que exibe preços
Escrever testes para cada operação aritmética para capturar bugs de precisão
Validar manualmente a compatibilidade de moedas antes dos cálculos
Arriscar problemas regulatórios com cálculos financeiros incorretos

Com o Transport, seus objetos Money funcionam de forma idêntica, seja calculando totais no servidor ou exibindo preços no navegador. As mesmas regras de arredondamento, as mesmas garantias de precisão, a mesma formatação — tudo mantido automaticamente através da fronteira 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 Tratamento de Erros)

Implemente tratamento de erros funcional com tipos Result. O tratamento de erros tradicional com try/catch pode tornar o fluxo do código difícil de seguir, oculta erros nas assinaturas de tipo e te força a lidar com erros no nível de abstração errado. O padrão Result, popularizado pelo Rust e pelas linguagens de programação funcional, fornece uma abordagem mais explícita e componível para o tratamento de erros.

O Problema com o Tratamento de Erros 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 que Tipos Result São Superiores: Em vez de lançar exceções que podem ser capturadas em qualquer lugar (ou pior, esquecidas), os tipos Result tornam o tratamento de erros explícito nas suas assinaturas de tipo. Uma função que retorna Result<User, DatabaseError> comunica claramente que pode falhar e que tipo de erro 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
}

Principais Benefícios:

Tratamento de erros explícito: Impossível ignorar erros — eles fazem parte da assinatura de tipo
Componibilidade: Encadeie operações com map, flatMap, andThen e outros combinadores
Sem necessidade de try/catch: Fluxo de código mais limpo sem boilerplate de tratamento de exceções em todo lugar
Segurança de tipos: O compilador garante que você trate tanto os casos de sucesso quanto de falha
Programação orientada a trilhos: Construa pipelines de dados robustos onde erros se propagam automaticamente
Melhor refatoração: Mudanças nos tipos de erro são capturadas em tempo de compilação, não em runtime

Quando Usar Este Padrão:

Respostas de API - Tratamento de erros estruturado e type-safe do servidor ao cliente
Operações de banco de dados - Tratamento explícito de falhas de consulta e problemas de conexão
Pipelines de validação - Encadeamento de múltiplos passos de validação com acumulação de erros
Chamadas a serviços externos - Gerenciando falhas de APIs de terceiros graciosamente com lógica de retry
Transformações de dados - Processos de múltiplas etapas onde qualquer etapa pode falhar
Operações de I/O de arquivos - Tratando falhas de leitura/escrita sem exceções

Cenário do Mundo Real: Imagine construir um fluxo de registro de usuário que valida o e-mail, verifica duplicatas, cria a conta e envia um e-mail de boas-vindas. Cada etapa pode falhar de forma 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
	)

Com o Transport, você pode retornar tipos Result de funções load do servidor e tê-los automaticamente reconstruídos no navegador com todos os seus métodos intactos. Isso mantém sua estratégia de tratamento de erros em toda a stack, garantindo gerenciamento de erros consistente e type-safe em todo lugar.

// 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 Cor

Para sistemas de design, temas ou aplicações gráficas. Cores são surpreendentemente complexas — podem ser representadas em múltiplos formatos (hex, RGB, HSL, RGBA), precisam de validação para garantir que os valores estejam em intervalos válidos, e frequentemente requerem transformações como clarear, escurecer ou ajustar a opacidade.

O Problema da Sopa de Strings:

// ❌ 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 que uma Classe Color Importa: Quando você está manipulando strings hex, tuplas RGB e valores de opacidade em toda a sua base de código, é fácil introduzir bugs. #fff é o mesmo que #ffffff? rgb(300, 50, 50) deve ser limitado ou lançar um erro? Uma classe Color responde a essas perguntas uma vez, de forma consistente.

Principais Benefícios:

Conversão de formato: Converta facilmente entre hex, RGB, RGBA, HSL — sem memorizar fórmulas de conversão
Validação automática: Valores RGB automaticamente limitados a 0-255, alfa a 0-1, prevenindo cores inválidas
Transformações encadeáveis: color.lighten(20).withAlpha(0.5) lê como inglês natural
Imutabilidade: Operações de cor retornam novas instâncias, prevenindo mutações acidentais em objetos de tema compartilhados
Segurança de tipos: TypeScript garante que você sempre trabalhe com objetos Color válidos, não strings aleatórias
Consistência: Mesma lógica de cores no servidor (geração de tema SSR) e no cliente (seletores de cores interativos)

Quando Usar Este Padrão:

Sistemas de design - Manutenção de paletas de cores consistentes, geração de tons/sombras, gerenciamento de cores de marca
Engines de temas - Troca dinâmica de tema, modo escuro, temas personalizáveis pelo usuário
Visualização de dados - Escalas de cores programáticas (vermelho→amarelo→verde), cores de categorias, mapas de calor
Aplicações gráficas - Renderização em canvas, processamento de imagens, geração de filtros CSS
Ferramentas de acessibilidade - Verificação de contraste WCAG, simulação de daltonismo, cores de texto legíveis
Sistemas CSS-in-JS - Manipulação de cores em runtime para componentes estilizados

Exemplo do Mundo Real: Imagine construir um sistema de design onde você define uma cor primária, e o sistema gera automaticamente:

10 tons do claro ao escuro
Estados de hover e active (ligeiramente mais escuros)
Estado desabilitado (opacidade reduzida)
Cor de texto que atende aos requisitos de contraste WCAG
Cor do anel de foco (primária com alfa ajustado)

Com uma classe Color e o Transport, você define essas regras uma vez no servidor, gera a paleta completa durante o SSR, e tem todos os mesmos métodos de manipulação de cores disponíveis quando os usuários interagem com seletores de cores ou alternadores de tema no 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. Otimização de Performance: Deduplicação

Para grandes conjuntos de dados com objetos repetidos, você pode otimizar a serialização para reduzir drasticamente o tamanho do payload e o uso de memória. Este é um caso de uso mais avançado que aborda um problema específico de performance: quando você tem muitos objetos que compartilham referências aos mesmos dados, a serialização ingênua irá duplicar esses dados, levando a payloads inflados, carregamentos lentos de página e potencialmente atingindo limites de memória em ambientes serverless.

O Problema: Duplicação de Dados em 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 no Mundo Real: Imagine construir uma ferramenta de gerenciamento de projetos que carrega 1.000 usuários, onde cada usuário pertence a uma das 10 organizações. Sem otimização, você serializaria cada objeto de organização aproximadamente 100 vezes (uma vez por usuário que pertence a ela). Se cada objeto de organização tiver 500 bytes, isso é 50KB de dados redundantes no seu payload HTML. Com relacionamentos aninhados mais complexos (Organizações → Times → Usuários → Projetos → Tarefas), esse problema se agrava exponencialmente.

Exemplo Real: A equipe de Cole Crouter atingiu o limite de memória de 128MB do Cloudflare Pages ao serializar um grande conjunto de dados. Ao implementar a deduplicação baseada em Transport, eles reduziram a sobrecarga de serialização e obtiveram carregamentos de página 2-3x mais rápidos. Leia o excelente post do blog dele.

Como o Padrão de Deduplicação Funciona:

Analise os relacionamentos: Identifique objetos que são compartilhados (como Organization ou Category)
Agrupe os dados: Organize objetos relacionados juntos (agrupe usuários por ID de organização)
Codifique eficientemente: Serialize objetos compartilhados uma vez, armazene referências por ID
Reconstrua os relacionamentos: Recrie o grafo de objetos no cliente usando buscas por ID

Quando Esta Otimização Importa:

Grandes conjuntos de dados: Painéis administrativos carregando milhares de registros (usuários, produtos, transações)
Dados hierárquicos: Organizações → Departamentos → Times → Usuários → Tarefas
Dados normalizados: Relacionamentos no estilo banco de dados transportados ao navegador
Restrições de memória: Ambientes serverless (limites de 128MB do Cloudflare, 250MB da Vercel)
Otimização de rede: Usuários mobile em conexões lentas precisam de payloads menores
Aplicações em tempo real: Atualizações frequentes de dados tornam o tamanho do payload crítico

A Troca: Esta técnica adiciona complexidade ao seu código de Transport. Use-a apenas quando você tiver perfilado e identificado que a duplicação de dados é realmente um gargalo. Para a maioria das aplicações, o padrão Transport padrão é suficiente. Mas quando você atinge limites de memória ou carregamentos lentos de página devido a grandes conjuntos de dados, esse padrão pode ser um salva-vidas.

A percepção fundamental: enquanto o devalue lida com a deduplicação de objetos simples automaticamente, os transportadores personalizados lhe dão controle total para implementar otimizações específicas de domínio para suas estruturas de dados.

// 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 Intervalo de Datas

Comuns em painéis de análise e ferramentas de relatório. Intervalos de datas aparecem em todo lugar em aplicações de negócio — filtrando dados, agendando eventos, definindo períodos de cobrança, configurando janelas de disponibilidade, comparando períodos de tempo. Embora você pudesse representá-los como dois objetos Date separados ou pares de timestamps, uma classe DateRange fornece significado semântico, segurança de tipos e operações úteis que previnem bugs.

O Problema das Duas Datas:

// ❌ 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 que DateRange Importa: O manuseio de datas é notoriamente difícil — problemas de fuso horário, anos bissextos, horário de verão, intervalos inclusivos vs exclusivos. Ao encapsular essa complexidade em uma classe, você lida com todos os casos extremos uma vez e ganha confiança de que sua lógica de datas está correta em todo lugar.

Principais Benefícios:

Validação: Garanta que a data de início é anterior à data de fim no momento da construção — falhe rapidamente com erros claros
Fábricas de conveniência: Crie intervalos comuns com código legível: DateRange.lastNDays(30), DateRange.thisMonth()
Cálculos: Compute duração em dias/horas, verifique se uma data cai dentro do intervalo, divida intervalos
Comparações: Verifique se intervalos se sobrepõem (para conflitos de agendamento), são adjacentes, ou um contém o outro
Imutabilidade: Intervalos não podem ser modificados acidentalmente após a criação, prevenindo bugs sutis
Lógica de negócio: Trate casos extremos como normalização de fuso horário, limites inclusivos/exclusivos, exclusão de fins de semana
Legibilidade: campaign.period.contains(today) vs campaign.start <= today && today <= campaign.end

Casos de Uso Comuns:

Painéis de análise - Seletores de intervalo de datas ("Últimos 7 dias", "Este trimestre"), filtragem de métricas, análise comparativa ("Esta semana vs semana passada"), escalas de tempo de gráficos
Sistemas de reservas - Reservas de hotel com check-in/check-out, agendamento de salas de reunião, períodos de aluguel de equipamentos, detecção de reservas duplicadas
Ferramentas de relatório - Períodos financeiros (trimestres, anos fiscais), avaliações de desempenho, janelas de auditoria de conformidade, intervalos de datas personalizados
Aplicações de agendamento - Calendários de disponibilidade de funcionários, gerenciamento de turnos, rastreamento de férias, períodos de bloqueio
Cobrança SaaS - Períodos de assinatura, janelas de teste, ciclos de cobrança baseada em uso, cálculos de rateio
Gerenciamento de campanhas - Períodos promocionais, durações de testes A/B, ofertas sazonais

Exemplo do Mundo Real: Imagine construir um painel de análise onde os usuários podem selecionar "Últimos 7 dias", "Últimos 30 dias" ou um intervalo personalizado. Com 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

Quando você carrega dados de análise no servidor, o objeto DateRange pode ser passado ao cliente onde continua funcionando para filtragem no lado do cliente, lógica de exibição e cálculos de data. Isso mantém sua lógica de tratamento de datas consistente entre os ambientes e elimina os bugs de fuso horário do tipo "funciona no servidor mas quebra no 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 }
}

Padrões Avançados

Tipos Personalizados Aninhados

O Transport lida automaticamente com aninhamentos, portanto tipos personalizados podem conter outros 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 com Funções Remotas

O Transport funciona perfeitamente com as funções remotas do 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}

Boas Práticas

1. Mantenha os Dados Codificados no Mínimo

Codifique apenas os dados necessários para reconstruir o objeto. Não codifique propriedades computadas.

// ✅ 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. Use Type Guards no Encode

Sempre verifique se o valor é uma instância do seu tipo antes de codificá-lo.

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

	return {
		// ... encoding logic
	}
}

3. Trate Casos Extremos

Considere null, undefined e validação na sua função 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. Não Codifique Valores Falsy

A função encode usa valores falsy como sinal de que o valor não é uma instância. Tenha cuidado com 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]

Armadilhas Comuns

1. Esquecer a Verificação instanceof

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

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

2. Codificando Dados Não Serializáveis

// ❌ 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. Referências Circulares em Tipos Personalizados

Embora o devalue lide com referências circulares em objetos simples, tenha cuidado com 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
	}

Testando Seus 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)
	})
})

Conclusão

O hook Transport é um recurso poderoso que permite manter modelos de domínio ricos através da fronteira servidor/cliente no SvelteKit. Ao definir lógica de serialização personalizada, você pode:

Manter sua lógica de negócio encapsulada em classes
Manter a segurança de tipos em toda a stack
Otimizar a transferência de dados para grandes conjuntos de dados
Construir aplicações mais fáceis de manter e testar

A chave é pensar no Transport como uma ponte entre seus modelos de domínio no lado do servidor e as necessidades do lado do cliente, permitindo que você escreva código mais limpo e orientado a objetos enquanto o SvelteKit cuida da complexidade de serialização para você.

Introdução

O Desafio da Serialização

O Problema que o Transport Resolve

Como o Transport Funciona

Estrutura Básica

O Padrão Encode/Decode

Casos de Uso do Mundo Real

1. Modelos de Domínio com Métodos

2. Tipos Matemáticos (Vetores, Matrizes)

3. Objetos de Dinheiro/Moeda

4. Tipos Result (para Tratamento de Erros)

5. Objetos de Cor

6. Otimização de Performance: Deduplicação

7. Objetos de Intervalo de Datas

Padrões Avançados

Tipos Personalizados Aninhados

Uso com Funções Remotas

Boas Práticas

1. Mantenha os Dados Codificados no Mínimo

2. Use Type Guards no Encode

3. Trate Casos Extremos

4. Não Codifique Valores Falsy

Armadilhas Comuns

1. Esquecer a Verificação instanceof

2. Codificando Dados Não Serializáveis

3. Referências Circulares em Tipos Personalizados

Testando Seus Transporters

Conclusão

Leitura Adicional