Quando Objetos Simples Ficam Limitados

Você aprendeu a tornar o contexto reativo com objetos $state e funções getter. Viu como $derived lida com valores computados e $effect gerencia efeitos colaterais. Esses padrões funcionam muito bem—até que seu contexto cresce o suficiente para que organizá-lo se torne o desafio.

Quando um contexto tem uma dúzia de campos de estado, múltiplas propriedades computadas, vários métodos de ação e lógica de inicialização que depende de parâmetros, a abordagem de objeto simples começa a mostrar suas limitações. Peças relacionadas se dispersam. Fica confuso quais métodos modificam qual estado. Adicionar novos recursos significa vasculhar código espalhado para encontrar onde as coisas pertencem.

Classes TypeScript oferecem uma solução. Uma classe agrupa naturalmente estado e comportamento relacionados. Os campos ficam no topo, os métodos vêm a seguir, e a relação entre eles é explícita. Mais importante ainda, as classes oferecem recursos que objetos simples não conseguem igualar: campos verdadeiramente privados que o TypeScript impõe, inicialização por construtor com validação, herança para comportamento compartilhado e suporte rico a IDE que compreende a estrutura do seu código.

A melhor parte? As runes do Svelte 5 funcionam perfeitamente dentro de classes. Você usa $state, $derived e $effect exatamente como faria em qualquer outro lugar—a classe apenas fornece organização e encapsulamento.

Este artigo aborda o contexto baseado em classes, desde o básico prático até padrões avançados. Você aprenderá quando as classes ajudam, como estruturá-las efetivamente e como evitar as armadilhas que atrapalham desenvolvedores que estão começando com essa abordagem.

O Espaço do Problema

Antes de adicionar classes, vamos entender quando elas realmente ajudam. Nem todo contexto precisa de uma classe—mas alguns claramente se beneficiam.

Quando Objetos se Tornam Difíceis de Gerenciar

Considere um contexto de preferências do usuário que cresceu ao longo do tempo:

// preferences-context.svelte.ts
export function createPreferencesContext() {
	// State scattered across multiple declarations
	let theme = $state<'light' | 'dark' | 'system'>('system')
	let fontSize = $state(16)
	let language = $state('en')
	let reducedMotion = $state(false)
	let notifications = $state(true)
	let emailDigest = $state<'daily' | 'weekly' | 'never'>('weekly')
	let timezone = $state(Intl.DateTimeFormat().resolvedOptions().timeZone)
	let dateFormat = $state<'mdy' | 'dmy' | 'ymd'>('mdy')
	let measurementUnit = $state<'metric' | 'imperial'>('metric')

	// Derived values somewhere in the middle
	let effectiveTheme = $derived(
		theme === 'system'
			? window.matchMedia('(prefers-color-scheme: dark)').matches
				? 'dark'
				: 'light'
			: theme
	)

	let localeSettings = $derived({
		language,
		timezone,
		dateFormat,
		measurementUnit
	})

	// Effects for persistence scattered around
	$effect(() => {
		localStorage.setItem(
			'preferences',
			JSON.stringify({
				theme,
				fontSize,
				language,
				reducedMotion,
				notifications,
				emailDigest,
				timezone,
				dateFormat,
				measurementUnit
			})
		)
	})

	$effect(() => {
		document.documentElement.setAttribute('data-theme', effectiveTheme)
	})

	// Methods at the end
	return {
		get theme() {
			return theme
		},
		get fontSize() {
			return fontSize
		},
		get language() {
			return language
		},
		// ... 15 more getters

		setTheme(value: 'light' | 'dark' | 'system') {
			theme = value
		},
		setFontSize(value: number) {
			fontSize = Math.max(12, Math.min(24, value))
		},
		setLanguage(value: string) {
			language = value
		},
		// ... 10 more setters

		resetToDefaults() {
			theme = 'system'
			fontSize = 16
			language = 'en'
			// ... reset all 9 fields
		}
	}
}

Isso funciona, mas está ficando difícil de navegar. As declarações de estado estão no topo, os valores derivados em algum lugar no meio, os efeitos espalhados por todo o lado, e o objeto retornado no final. Quando você precisa adicionar uma nova preferência, precisa modificar quatro lugares diferentes.

O Que as Classes Oferecem

Uma versão em classe do mesmo contexto:

// PreferencesContext.svelte.ts
export class PreferencesContext {
	// All state together at the top
	theme = $state<'light' | 'dark' | 'system'>('system')
	fontSize = $state(16)
	language = $state('en')
	reducedMotion = $state(false)
	notifications = $state(true)
	emailDigest = $state<'daily' | 'weekly' | 'never'>('weekly')
	timezone = $state(Intl.DateTimeFormat().resolvedOptions().timeZone)
	dateFormat = $state<'mdy' | 'dmy' | 'ymd'>('mdy')
	measurementUnit = $state<'metric' | 'imperial'>('metric')

	// Computed properties clearly marked
	get effectiveTheme() {
		return this.theme === 'system'
			? window.matchMedia('(prefers-color-scheme: dark)').matches
				? 'dark'
				: 'light'
			: this.theme
	}

	get localeSettings() {
		return {
			language: this.language,
			timezone: this.timezone,
			dateFormat: this.dateFormat,
			measurementUnit: this.measurementUnit
		}
	}

	// Methods grouped logically
	setTheme(value: 'light' | 'dark' | 'system') {
		this.theme = value
	}

	setFontSize(value: number) {
		this.fontSize = Math.max(12, Math.min(24, value))
	}

	resetToDefaults() {
		this.theme = 'system'
		this.fontSize = 16
		this.language = 'en'
		this.reducedMotion = false
		this.notifications = true
		this.emailDigest = 'weekly'
		this.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
		this.dateFormat = 'mdy'
		this.measurementUnit = 'metric'
	}

	// Lifecycle setup in constructor
	constructor() {
		// Load from localStorage
		this.loadFromStorage()

		// Set up persistence
		$effect(() => {
			this.saveToStorage()
		})

		// Apply theme to document
		$effect(() => {
			document.documentElement.setAttribute('data-theme', this.effectiveTheme)
		})
	}

	private loadFromStorage() {
		try {
			const stored = localStorage.getItem('preferences')
			if (stored) {
				const data = JSON.parse(stored)
				Object.assign(this, data)
			}
		} catch {
			// Use defaults on error
		}
	}

	private saveToStorage() {
		localStorage.setItem(
			'preferences',
			JSON.stringify({
				theme: this.theme,
				fontSize: this.fontSize,
				language: this.language,
				reducedMotion: this.reducedMotion,
				notifications: this.notifications,
				emailDigest: this.emailDigest,
				timezone: this.timezone,
				dateFormat: this.dateFormat,
				measurementUnit: this.measurementUnit
			})
		)
	}
}

A versão em classe é mais fácil de navegar: estado no topo, propriedades computadas em seguida, métodos públicos, construtor e depois os auxiliares privados. Quando você precisa adicionar uma nova preferência, a estrutura indica exatamente onde cada peça vai.

O Modelo Mental do Svelte 5

As runes do Svelte 5 funcionam dentro de classes porque runes são transformações em tempo de compilação, não recursos de tempo de execução. Quando o Svelte vê $state, $derived ou $effect, ele transforma esse código durante a compilação. Não importa se o código está dentro de uma função, de um método de objeto ou de uma classe—a transformação é aplicada da mesma forma.

Runes em Campos de Classe

Campos de classe com $state se tornam reativos:

class Counter {
	// This field is reactive
	count = $state(0)

	// Methods can read and mutate the reactive field
	increment() {
		this.count++ // Svelte tracks this mutation
	}
}

Quando o Svelte compila isso, ele transforma o campo count em algo que o sistema de reatividade do Svelte pode rastrear. A transformação é invisível para você—você apenas escreve código de classe com aparência normal.

Valores Derivados como Getters

Para valores computados em classes, use getters nativos do JavaScript:

class Counter {
	count = $state(0)

	// Getter computes fresh each time it's accessed
	get doubled() {
		return this.count * 2
	}

	// Getter can derive from other getters
	get quadrupled() {
		return this.doubled * 2
	}
}

Getters funcionam como $derived—eles calculam seu valor cada vez que são acessados, e o Svelte rastreia quais valores reativos eles leem.

Em classes, getters JavaScript servem ao mesmo propósito que $derived. Ambos calculam valores de forma reativa. Getters são a escolha idiomática para classes porque se integram naturalmente com a sintaxe de classes e com a inferência de tipos do TypeScript.

Efeitos em Construtores

Coloque chamadas $effect no construtor para configurar efeitos colaterais quando a classe é instanciada:

class Timer {
	seconds = $state(0)
	running = $state(false)

	constructor() {
		$effect(() => {
			if (this.running) {
				const interval = setInterval(() => {
					this.seconds++
				}, 1000)

				// Cleanup when effect re-runs or component unmounts
				return () => clearInterval(interval)
			}
		})
	}

	start() {
		this.running = true
	}

	stop() {
		this.running = false
	}
}

O efeito é executado durante a inicialização do componente (quando a classe é instanciada no <script> de um componente) e é limpo adequadamente.

Implementação

Vamos construir o contexto baseado em classes progressivamente, começando simples e adicionando complexidade.

Passo 1: Classe Básica com $state

O contexto mais simples baseado em classes agrupa estado e métodos relacionados:

// counter.svelte.ts
import { setContext, getContext } from 'svelte'

const COUNTER_KEY = Symbol('counter')

export class CounterContext {
	count = $state(0)

	increment() {
		this.count++
	}

	decrement() {
		this.count--
	}

	reset() {
		this.count = 0
	}
}

export function setCounterContext() {
	return setContext(COUNTER_KEY, new CounterContext())
}

export function getCounterContext(): CounterContext {
	return getContext(COUNTER_KEY)
}

Usando-o:

<!-- Provider.svelte -->
<script>
	import { setCounterContext } from './counter.svelte'
	import type { Snippet } from 'svelte'

	let { children }: { children: Snippet } = $props()

	setCounterContext()
</script>

{@render children()}

<!-- Consumer.svelte -->
<script>
	import { getCounterContext } from './counter.svelte'

	const counter = getCounterContext()
</script>

<p>Count: {counter.count}</p>
<button onclick={() => counter.increment()}>+</button>
<button onclick={() => counter.decrement()}>-</button>
<button onclick={() => counter.reset()}>Reset</button>

Passo 2: Adicionando Propriedades Computadas

Adicione getters para valores derivados:

// counter.svelte.ts
export class CounterContext {
	count = $state(0)
	step = $state(1)

	// Computed properties via getters
	get isPositive() {
		return this.count > 0
	}

	get isNegative() {
		return this.count < 0
	}

	get isZero() {
		return this.count === 0
	}

	get displayValue() {
		const sign = this.count >= 0 ? '' : '-'
		return `${sign}${Math.abs(this.count).toLocaleString()}`
	}

	increment() {
		this.count += this.step
	}

	decrement() {
		this.count -= this.step
	}

	setStep(value: number) {
		this.step = Math.max(1, value)
	}

	reset() {
		this.count = 0
	}
}

Os consumidores acessam propriedades computadas como propriedades regulares:

<script>
	const counter = getCounterContext()
</script>

<p class:positive={counter.isPositive} class:negative={counter.isNegative}>
	{counter.displayValue}
</p>

Passo 3: Parâmetros do Construtor

Use construtores para configurar instâncias de classe:

// counter.svelte.ts
export interface CounterOptions {
	initial?: number
	min?: number
	max?: number
	step?: number
}

export class CounterContext {
	count: number
	readonly min: number
	readonly max: number
	step: number

	constructor(options: CounterOptions = {}) {
		const { initial = 0, min = -Infinity, max = Infinity, step = 1 } = options

		this.count = $state(Math.max(min, Math.min(max, initial)))
		this.min = min
		this.max = max
		this.step = $state(step)
	}

	get canIncrement() {
		return this.count + this.step <= this.max
	}

	get canDecrement() {
		return this.count - this.step >= this.min
	}

	increment() {
		if (this.canIncrement) {
			this.count += this.step
		}
	}

	decrement() {
		if (this.canDecrement) {
			this.count -= this.step
		}
	}

	set(value: number) {
		this.count = Math.max(this.min, Math.min(this.max, value))
	}
}

export function setCounterContext(options?: CounterOptions) {
	return setContext(COUNTER_KEY, new CounterContext(options))
}

Provider com configuração:

<script>
	import { setCounterContext } from './counter.svelte'
	import type { Snippet } from 'svelte'

	let { children }: { children: Snippet } = $props()

	// Counter that starts at 50, can't go below 0 or above 100
	setCounterContext({ initial: 50, min: 0, max: 100, step: 5 })
</script>

{@render children()}

Passo 4: Campos Privados para Encapsulamento

Os campos privados do TypeScript impedem que os consumidores acessem diretamente o estado interno:

// user-session.svelte.ts
export class UserSessionContext {
	// Private fields - inaccessible outside the class
	#user = $state<User | null>(null)
	#token = $state<string | null>(null)
	#refreshTimer: ReturnType<typeof setTimeout> | null = null

	// Public getters provide controlled access
	get isAuthenticated() {
		return this.#user !== null && this.#token !== null
	}

	get user() {
		return this.#user
	}

	get userId() {
		return this.#user?.id ?? null
	}

	get username() {
		return this.#user?.username ?? null
	}

	// Token is never exposed - only used internally

	constructor() {
		// Attempt to restore session on creation
		this.#restoreSession()
	}

	async login(credentials: { email: string; password: string }) {
		const response = await fetch('/api/auth/login', {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify(credentials)
		})

		if (!response.ok) {
			throw new Error('Login failed')
		}

		const data = await response.json()
		this.#user = data.user
		this.#token = data.token

		// Store for session restoration
		sessionStorage.setItem('auth_token', data.token)

		// Set up automatic token refresh
		this.#scheduleTokenRefresh()
	}

	logout() {
		this.#user = null
		this.#token = null
		sessionStorage.removeItem('auth_token')

		if (this.#refreshTimer) {
			clearTimeout(this.#refreshTimer)
			this.#refreshTimer = null
		}
	}

	// Private helper methods
	#restoreSession() {
		const token = sessionStorage.getItem('auth_token')
		if (token) {
			this.#token = token
			this.#fetchCurrentUser()
		}
	}

	async #fetchCurrentUser() {
		if (!this.#token) return

		try {
			const response = await fetch('/api/auth/me', {
				headers: { Authorization: `Bearer ${this.#token}` }
			})

			if (response.ok) {
				this.#user = await response.json()
				this.#scheduleTokenRefresh()
			} else {
				this.logout()
			}
		} catch {
			this.logout()
		}
	}

	#scheduleTokenRefresh() {
		// Refresh token 5 minutes before expiry
		this.#refreshTimer = setTimeout(
			() => {
				this.#refreshToken()
			},
			55 * 60 * 1000
		) // 55 minutes
	}

	async #refreshToken() {
		if (!this.#token) return

		try {
			const response = await fetch('/api/auth/refresh', {
				method: 'POST',
				headers: { Authorization: `Bearer ${this.#token}` }
			})

			if (response.ok) {
				const data = await response.json()
				this.#token = data.token
				sessionStorage.setItem('auth_token', data.token)
				this.#scheduleTokenRefresh()
			} else {
				this.logout()
			}
		} catch {
			this.logout()
		}
	}
}

Com campos privados, os consumidores não conseguem acessar o token diretamente, seja acidentalmente ou intencionalmente:

<script>
	const session = getUserSessionContext()

	// ✅ These work
	console.log(session.isAuthenticated)
	console.log(session.username)

	// ❌ TypeScript error: Property '#token' is not accessible
	// console.log(session.#token)
</script>

Passo 5: Efeitos para Gerenciamento de Ciclo de Vida

Adicione $effect no construtor para efeitos colaterais:

// theme.svelte.ts
export class ThemeContext {
	#mode = $state<'light' | 'dark' | 'system'>('system')
	#systemPreference = $state<'light' | 'dark'>('light')

	get mode() {
		return this.#mode
	}

	get effectiveTheme(): 'light' | 'dark' {
		if (this.#mode === 'system') {
			return this.#systemPreference
		}
		return this.#mode
	}

	get isDark() {
		return this.effectiveTheme === 'dark'
	}

	constructor() {
		// Load saved preference
		const saved = localStorage.getItem('theme-mode')
		if (saved === 'light' || saved === 'dark' || saved === 'system') {
			this.#mode = saved
		}

		// Track system preference
		if (typeof window !== 'undefined') {
			const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
			this.#systemPreference = mediaQuery.matches ? 'dark' : 'light'

			// Effect to listen for system preference changes
			$effect(() => {
				const handler = (e: MediaQueryListEvent) => {
					this.#systemPreference = e.matches ? 'dark' : 'light'
				}

				mediaQuery.addEventListener('change', handler)
				return () => mediaQuery.removeEventListener('change', handler)
			})
		}

		// Effect to persist mode changes
		$effect(() => {
			localStorage.setItem('theme-mode', this.#mode)
		})

		// Effect to apply theme to document
		$effect(() => {
			document.documentElement.setAttribute('data-theme', this.effectiveTheme)
			document.documentElement.classList.toggle('dark', this.isDark)
		})
	}

	setMode(mode: 'light' | 'dark' | 'system') {
		this.#mode = mode
	}

	toggle() {
		if (this.#mode === 'light') {
			this.#mode = 'dark'
		} else if (this.#mode === 'dark') {
			this.#mode = 'system'
		} else {
			this.#mode = 'light'
		}
	}
}

Passo 6: Composição em Vez de Herança

Quando contextos compartilham comportamento, prefira composição em vez de herança. Isso mantém as classes focadas e testáveis:

// Reusable behavior modules
// persistence.svelte.ts
export function createPersistence<T>(
	key: string,
	serialize: (data: T) => string,
	deserialize: (data: string) => T
) {
	return {
		load(): T | null {
			try {
				const stored = localStorage.getItem(key)
				return stored ? deserialize(stored) : null
			} catch {
				return null
			}
		},

		save(data: T) {
			localStorage.setItem(key, serialize(data))
		},

		clear() {
			localStorage.removeItem(key)
		}
	}
}

// history.svelte.ts
export class History<T> {
	#states = $state<T[]>([])
	#index = $state(-1)
	#maxSize: number

	constructor(maxSize = 50) {
		this.#maxSize = maxSize
	}

	get canUndo() {
		return this.#index > 0
	}

	get canRedo() {
		return this.#index < this.#states.length - 1
	}

	get current(): T | undefined {
		return this.#states[this.#index]
	}

	push(state: T) {
		// Remove any future states if we're not at the end
		this.#states = this.#states.slice(0, this.#index + 1)

		// Add new state
		this.#states.push(state)

		// Trim to max size
		if (this.#states.length > this.#maxSize) {
			this.#states = this.#states.slice(-this.#maxSize)
		}

		this.#index = this.#states.length - 1
	}

	undo(): T | undefined {
		if (this.canUndo) {
			this.#index--
			return this.current
		}
	}

	redo(): T | undefined {
		if (this.canRedo) {
			this.#index++
			return this.current
		}
	}

	clear() {
		this.#states = []
		this.#index = -1
	}
}

Agora componha-os em um contexto:

// document-context.svelte.ts
export class DocumentContext {
	#content = $state('')
	#title = $state('Untitled')
	#savedAt = $state<Date | null>(null)

	// Composed behaviors
	#history = new History<string>(100)
	#persistence = createPersistence<{ title: string; content: string }>(
		'document',
		JSON.stringify,
		JSON.parse
	)

	get content() {
		return this.#content
	}

	get title() {
		return this.#title
	}

	get savedAt() {
		return this.#savedAt
	}

	get canUndo() {
		return this.#history.canUndo
	}

	get canRedo() {
		return this.#history.canRedo
	}

	get hasUnsavedChanges() {
		const saved = this.#persistence.load()
		return !saved || saved.content !== this.#content || saved.title !== this.#title
	}

	constructor() {
		// Load saved document
		const saved = this.#persistence.load()
		if (saved) {
			this.#content = saved.content
			this.#title = saved.title
		}

		// Initialize history with current content
		this.#history.push(this.#content)
	}

	setContent(content: string) {
		this.#content = content
		this.#history.push(content)
	}

	setTitle(title: string) {
		this.#title = title
	}

	undo() {
		const previous = this.#history.undo()
		if (previous !== undefined) {
			this.#content = previous
		}
	}

	redo() {
		const next = this.#history.redo()
		if (next !== undefined) {
			this.#content = next
		}
	}

	save() {
		this.#persistence.save({
			title: this.#title,
			content: this.#content
		})
		this.#savedAt = new Date()
	}

	clear() {
		this.#content = ''
		this.#title = 'Untitled'
		this.#history.clear()
		this.#history.push('')
		this.#persistence.clear()
		this.#savedAt = null
	}
}

A composição mantém cada parte focada. A classe History cuida de desfazer/refazer. O módulo de persistência cuida do armazenamento. O DocumentContext os orquestra sem misturar responsabilidades.

Erros Comuns e Anti-Padrões

Ao usar contexto baseado em classes, certos problemas podem surgir. Aqui estão os erros mais comuns e como evitá-los.

1: Erro: Perder o Contexto de `this`

class Counter {
	count = $state(0)

	// ❌ Arrow function loses `this` context in some scenarios
	increment = () => {
		this.count++
	}

	// ❌ Destructuring breaks `this` binding
	// const { increment } = counter; increment() // Error!
}

Por que acontece: Quando métodos são desestruturados ou passados como callbacks, eles perdem o vínculo com this.

Solução: Use métodos regulares e vincule no local de chamada, ou use funções de seta de forma consistente com consciência das trocas envolvidas:

class Counter {
  count = $state(0)

  // ✅ Regular method - works when called on the instance
  increment() {
    this.count++
  }
}

// In component: always call on the instance
<button onclick={() => counter.increment()}>+</button>

2: Criando Classes no Lugar Errado

<!-- ❌ Creates new instance every render -->
<script>
	class Counter {
		count = $state(0)
	}

	const counter = new Counter() // Recreated on each render!
</script>

Por que acontece: A classe é definida e instanciada dentro do componente, o que ocorre durante a inicialização.

Solução: Defina classes em arquivos .svelte.ts separados:

// counter.svelte.ts
export class Counter {
	count = $state(0)
	increment() {
		this.count++
	}
}

<!-- Component.svelte -->
<script>
	import { Counter } from './counter.svelte'

	const counter = new Counter() // Created once during initialization
</script>

3: Expondo Arrays ou Objetos Mutáveis

class TodoContext {
	// ❌ Consumers can mutate the array directly
	todos = $state<Todo[]>([])

	addTodo(text: string) {
		this.todos.push({ id: Date.now(), text, done: false })
	}
}

// Consumer can break encapsulation:
// context.todos.push({ id: 'fake', text: 'hacked', done: true })

Por que acontece: Arrays e objetos são referências. Expô-los permite que consumidores contornem seus métodos.

Solução: Use campos privados com getters somente leitura:

class TodoContext {
	#todos = $state<Todo[]>([])

	// Return a copy or use a getter that TypeScript sees as readonly
	get todos(): readonly Todo[] {
		return this.#todos
	}

	addTodo(text: string) {
		this.#todos.push({ id: Date.now(), text, done: false })
	}
}

4: Usando `$derived` em Campos de Classe

class Counter {
	count = $state(0)

	// ❌ This doesn't work as expected in class fields
	doubled = $derived(this.count * 2) // 'this' may not be bound correctly
}

Por que acontece: A inicialização de campos de classe ocorre antes da execução do construtor, e o vínculo com this pode ser problemático com $derived em inicializadores de campo.

Solução: Use getters nativos em vez disso:

class Counter {
	count = $state(0)

	// ✅ Getter works correctly
	get doubled() {
		return this.count * 2
	}
}

5: Lógica Pesada no Construtor

class DataContext {
	data = $state<Data[]>([])

	constructor() {
		// ❌ Blocking async operations in constructor
		const response = await fetch('/api/data') // Syntax error!
		this.data = await response.json()
	}
}

Por que acontece: Construtores não podem ser assíncronos, e operações bloqueantes causam problemas.

Solução: Use um método de inicialização explícito ou inicialize via efeito:

class DataContext {
	#data = $state<Data[]>([])
	#loading = $state(false)
	#error = $state<Error | null>(null)

	get data() {
		return this.#data
	}
	get loading() {
		return this.#loading
	}
	get error() {
		return this.#error
	}

	constructor() {
		// Start loading in an effect
		$effect(() => {
			this.load()
		})
	}

	async load() {
		this.#loading = true
		this.#error = null

		try {
			const response = await fetch('/api/data')
			if (!response.ok) throw new Error('Failed to fetch')
			this.#data = await response.json()
		} catch (e) {
			this.#error = e instanceof Error ? e : new Error('Unknown error')
		} finally {
			this.#loading = false
		}
	}
}

Considerações de Desempenho e Escalabilidade

Reatividade Granular

A reatividade do Svelte é granular no nível de propriedade. Quando você tem uma classe com múltiplos campos $state, alterar um campo afeta apenas os componentes que leem aquele campo específico:

class AppContext {
	user = $state<User | null>(null)
	theme = $state<'light' | 'dark'>('light')
	notifications = $state<Notification[]>([])
}

Um componente que lê apenas context.theme não será re-renderizado quando context.notifications mudar. Isso significa que classes de contexto grandes não causam problemas de desempenho inerentemente — apenas as partes relevantes disparam atualizações.

Evitando Getters Desnecessários

O acesso simples a propriedades não precisa da sobrecarga de um getter:

class Counter {
	count = $state(0)

	// ❌ Unnecessary getter for simple state
	get value() {
		return this.count
	}

	// ✅ Just expose the field directly
	// Consumers use: counter.count
}

Use getters quando precisar de:

Valores computados/derivados
Controle de acesso (retornando cópias de arrays/objetos)
Avaliação lazy de operações custosas

Coleções Grandes

Para contextos que gerenciam coleções grandes (centenas de itens), considere:

class ItemsContext {
	#items = $state<Map<string, Item>>(new Map())

	get items(): readonly Item[] {
		return Array.from(this.#items.values())
	}

	getById(id: string): Item | undefined {
		return this.#items.get(id) // O(1) lookup
	}

	updateItem(id: string, updates: Partial<Item>) {
		const item = this.#items.get(id)
		if (item) {
			// Mutate in place for reactivity
			Object.assign(item, updates)
		}
	}

	// For bulk operations, batch updates
	bulkUpdate(updates: Map<string, Partial<Item>>) {
		for (const [id, changes] of updates) {
			this.updateItem(id, changes)
		}
	}
}

Usar um Map fornece buscas em O(1). Mutar itens no lugar mantém a reatividade sem recriar toda a coleção.

Gerenciamento de Memória

Classes persistem durante o tempo de vida do componente provedor. Esteja atento a:

class CacheContext {
	#cache = $state<Map<string, CachedItem>>(new Map())
	#maxSize = 1000

	set(key: string, value: unknown, ttl = 60000) {
		// Evict if at capacity
		if (this.#cache.size >= this.#maxSize) {
			const oldestKey = this.#cache.keys().next().value
			if (oldestKey) this.#cache.delete(oldestKey)
		}

		this.#cache.set(key, {
			value,
			expiresAt: Date.now() + ttl
		})
	}

	get(key: string): unknown | undefined {
		const item = this.#cache.get(key)
		if (!item) return undefined

		if (Date.now() > item.expiresAt) {
			this.#cache.delete(key)
			return undefined
		}

		return item.value
	}

	// Periodic cleanup
	constructor() {
		$effect(() => {
			const interval = setInterval(() => {
				const now = Date.now()
				for (const [key, item] of this.#cache) {
					if (now > item.expiresAt) {
						this.#cache.delete(key)
					}
				}
			}, 60000)

			return () => clearInterval(interval)
		})
	}
}

Quando NÃO Usar Classes

Classes adicionam estrutura, mas também cerimônia. Não as use quando:

Contexto Simples

Para contextos simples com um ou dois campos de estado e lógica mínima, um objeto simples é mais limpo:

// ❌ Overkill for simple context
class ToggleContext {
	value = $state(false)
	toggle() {
		this.value = !this.value
	}
}

// ✅ Simple object is better
export function createToggleContext() {
	let value = $state(false)

	return setContext('toggle', {
		get value() {
			return value
		},
		toggle() {
			value = !value
		}
	})
}

Estado Singleton

Se você tem estado global da aplicação que não precisa da API de contexto (não dependente da posição na árvore de componentes), considere um módulo simples:

// global-state.svelte.ts
// ✅ Simpler for true globals
export const appState = {
	#darkMode: $state(false),

	get darkMode() {
		return this.#darkMode
	},
	toggleDarkMode() {
		this.#darkMode = !this.#darkMode
	}
}

// Use directly without context:
// import { appState } from './global-state.svelte'

Utilitários Sem Estado

Não envolva utilitários sem estado em classes:

// ❌ Class with no state is just functions with extra steps
class Validators {
	isEmail(value: string) {
		return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
	}
}

// ✅ Just use functions
export function isEmail(value: string) {
	return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
}

Herança Profundamente Aninhada

Evite hierarquias de herança profundas. Elas são difíceis de entender e manter:

// ❌ Deep inheritance is confusing
class BaseContext {
	/* ... */
}
class StatefulContext extends BaseContext {
	/* ... */
}
class PersistentContext extends StatefulContext {
	/* ... */
}
class UserContext extends PersistentContext {
	/* ... */
}

// ✅ Prefer composition
class UserContext {
	#persistence = new Persistence('user')
	#state = new StateMachine(/* ... */)
	// ...
}

Exemplo Completo de Produção

Aqui está um sistema de notificações completo demonstrando todos os padrões:

// notifications-context.svelte.ts
import { setContext, getContext, hasContext } from 'svelte'

const NOTIFICATIONS_KEY = Symbol('notifications')

export type NotificationType = 'info' | 'success' | 'warning' | 'error'

export interface Notification {
	readonly id: string
	readonly message: string
	readonly type: NotificationType
	readonly timestamp: number
	readonly dismissible: boolean
}

export interface NotificationOptions {
	type?: NotificationType
	duration?: number
	dismissible?: boolean
}

export class NotificationsContext {
	// Private state
	#notifications = $state<Notification[]>([])
	#timers = new Map<string, ReturnType<typeof setTimeout>>()

	// Configuration
	readonly #defaultDuration: number
	readonly #maxNotifications: number

	constructor(options: { defaultDuration?: number; maxNotifications?: number } = {}) {
		this.#defaultDuration = options.defaultDuration ?? 5000
		this.#maxNotifications = options.maxNotifications ?? 5
	}

	// Public getters
	get all(): readonly Notification[] {
		return this.#notifications
	}

	get count() {
		return this.#notifications.length
	}

	get hasNotifications() {
		return this.#notifications.length > 0
	}

	// Convenience methods for common notification types
	info(message: string, options?: Omit<NotificationOptions, 'type'>) {
		return this.add(message, { ...options, type: 'info' })
	}

	success(message: string, options?: Omit<NotificationOptions, 'type'>) {
		return this.add(message, { ...options, type: 'success' })
	}

	warning(message: string, options?: Omit<NotificationOptions, 'type'>) {
		return this.add(message, { ...options, type: 'warning' })
	}

	error(message: string, options?: Omit<NotificationOptions, 'type'>) {
		// Errors stay longer and don't auto-dismiss by default
		return this.add(message, { duration: 0, ...options, type: 'error' })
	}

	// Core add method
	add(message: string, options: NotificationOptions = {}): string {
		const { type = 'info', duration = this.#defaultDuration, dismissible = true } = options

		const id = this.#generateId()

		const notification: Notification = {
			id,
			message,
			type,
			timestamp: Date.now(),
			dismissible
		}

		// Add to the beginning (newest first)
		this.#notifications.unshift(notification)

		// Enforce max notifications
		while (this.#notifications.length > this.#maxNotifications) {
			const oldest = this.#notifications.pop()
			if (oldest) {
				this.#clearTimer(oldest.id)
			}
		}

		// Set up auto-dismiss if duration > 0
		if (duration > 0) {
			const timer = setTimeout(() => {
				this.dismiss(id)
			}, duration)
			this.#timers.set(id, timer)
		}

		return id
	}

	// Dismiss a specific notification
	dismiss(id: string) {
		const index = this.#notifications.findIndex((n) => n.id === id)
		if (index !== -1) {
			this.#notifications.splice(index, 1)
			this.#clearTimer(id)
		}
	}

	// Dismiss all notifications
	dismissAll() {
		for (const notification of this.#notifications) {
			this.#clearTimer(notification.id)
		}
		this.#notifications.length = 0
	}

	// Dismiss all notifications of a specific type
	dismissByType(type: NotificationType) {
		const toDismiss = this.#notifications.filter((n) => n.type === type).map((n) => n.id)

		for (const id of toDismiss) {
			this.dismiss(id)
		}
	}

	// Private helpers
	#generateId(): string {
		return `notification-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
	}

	#clearTimer(id: string) {
		const timer = this.#timers.get(id)
		if (timer) {
			clearTimeout(timer)
			this.#timers.delete(id)
		}
	}
}

// Context setup helpers
export function setNotificationsContext(
	options?: ConstructorParameters<typeof NotificationsContext>[0]
) {
	return setContext(NOTIFICATIONS_KEY, new NotificationsContext(options))
}

export function getNotificationsContext(): NotificationsContext {
	if (!hasContext(NOTIFICATIONS_KEY)) {
		throw new Error(
			'Notifications context not found. ' + 'Wrap your component tree with a NotificationsProvider.'
		)
	}
	return getContext(NOTIFICATIONS_KEY)
}

Componente Provider com UI:

<!-- NotificationsProvider.svelte -->
<script lang="ts">
	import { setNotificationsContext } from './notifications-context.svelte'
	import { fly, fade } from 'svelte/transition'
	import type { Snippet } from 'svelte'

	interface Props {
		defaultDuration?: number
		maxNotifications?: number
		children: Snippet
	}

	let { defaultDuration = 5000, maxNotifications = 5, children }: Props = $props()

	const notifications = setNotificationsContext({
		defaultDuration,
		maxNotifications
	})
</script>

{@render children()}

<!-- Toast container -->
{#if notifications.hasNotifications}
	<div class="notifications-container" role="region" aria-label="Notifications" aria-live="polite">
		{#each notifications.all as notification (notification.id)}
			<div
				class="notification notification-{notification.type}"
				role="alert"
				in:fly={{ y: -20, duration: 200 }}
				out:fade={{ duration: 150 }}
			>
				<span class="notification-message">{notification.message}</span>

				{#if notification.dismissible}
					<button
						class="notification-dismiss"
						onclick={() => notifications.dismiss(notification.id)}
						aria-label="Dismiss notification"
					>
						<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
							<path d="M18 6L6 18M6 6l12 12" />
						</svg>
					</button>
				{/if}
			</div>
		{/each}
	</div>
{/if}

<style>
	.notifications-container {
		position: fixed;
		top: 1rem;
		right: 1rem;
		display: flex;
		flex-direction: column;
		gap: 0.5rem;
		z-index: 9999;
		max-width: 400px;
	}

	.notification {
		display: flex;
		align-items: flex-start;
		gap: 0.75rem;
		padding: 0.875rem 1rem;
		border-radius: 8px;
		background: white;
		box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
		border-left: 4px solid;
	}

	.notification-info {
		border-left-color: #3b82f6;
	}

	.notification-success {
		border-left-color: #10b981;
	}

	.notification-warning {
		border-left-color: #f59e0b;
	}

	.notification-error {
		border-left-color: #ef4444;
	}

	.notification-message {
		flex: 1;
		font-size: 0.9375rem;
		line-height: 1.5;
		color: #1e293b;
	}

	.notification-dismiss {
		flex-shrink: 0;
		width: 20px;
		height: 20px;
		padding: 0;
		border: none;
		background: none;
		color: #94a3b8;
		cursor: pointer;
		transition: color 0.2s;
	}

	.notification-dismiss:hover {
		color: #475569;
	}

	.notification-dismiss svg {
		width: 100%;
		height: 100%;
	}
</style>

Uso em toda a aplicação:

<script lang="ts">
	import { getNotificationsContext } from '$lib/notifications-context.svelte'

	const notifications = getNotificationsContext()

	async function handleSave() {
		try {
			await saveDocument()
			notifications.success('Document saved successfully!')
		} catch (err) {
			notifications.error(`Failed to save: ${err.message}`)
		}
	}

	function handleFormSubmit() {
		if (!validateForm()) {
			notifications.warning('Please fill in all required fields')
			return
		}
		// ... proceed with submission
	}
</script>

<button onclick={handleSave}>Save</button>

Conclusão

O contexto baseado em classes representa a evolução natural dos padrões de gerenciamento de estado à medida que a complexidade cresce. Quando um contexto possui múltiplos campos de estado relacionados, propriedades computadas, métodos de ação e preocupações de ciclo de vida, as classes fornecem a estrutura organizacional que mantém o código sustentável.

A percepção-chave é que as runes do Svelte 5 funcionam perfeitamente dentro de classes. $state cria campos reativos. Getters JavaScript servem como propriedades computadas (semelhante ao $derived). $effect em construtores lida com a configuração do ciclo de vida. Campos privados reforçam o encapsulamento. TypeScript fornece segurança de tipos e suporte a IDE.

Mas classes nem sempre são a resposta. Contextos simples com um ou dois campos de estado são melhor atendidos por objetos simples. Estado verdadeiramente global pode não precisar de contexto algum. Utilitários sem estado devem ser apenas funções. O objetivo é adequar a solução à complexidade do problema — nem mais, nem menos.

Quando você recorrer às classes, os padrões neste artigo servirão bem: campos privados para encapsulamento, getters para valores computados, parâmetros de construtor para configuração, comportamentos compostos para reusabilidade e tipagem explícita para segurança.

Principais Conclusões

Classes organizam contextos complexos. Quando um contexto possui muitos campos de estado, métodos e valores computados relacionados, uma classe fornece uma estrutura clara que objetos simples não possuem.

Runes funcionam dentro de classes. Use $state para campos reativos, getters JavaScript para propriedades computadas e $effect em construtores para gerenciamento do ciclo de vida. A sintaxe é familiar; a classe apenas fornece organização.

Campos privados reforçam o encapsulamento. A sintaxe #field do TypeScript cria estado verdadeiramente privado que os consumidores não podem acessar diretamente, forçando-os a usar sua API pública.

Getters substituem $derived. Em contextos de classe, getters JavaScript nativos servem ao mesmo propósito que $derived — eles computam valores reativamente sem a necessidade da rune.

Construtores inicializam, mas não devem bloquear. Use construtores para configurar o estado inicial e os efeitos, mas lide com operações assíncronas por meio de métodos explícitos ou efeitos que sejam executados após a construção.

Composição supera herança. Construa módulos de comportamento reutilizáveis (persistência, histórico, validação) e componha-os em classes de contexto em vez de criar hierarquias de herança profundas.

Adeque a complexidade às necessidades. Contextos simples não precisam de classes. Use objetos simples para um ou dois campos de estado. Reserve classes para contextos onde os benefícios organizacionais superam a cerimônia.

O Que Vem a Seguir

Pronto para aplicar o contexto baseado em classes a funcionalidades do mundo real? O próximo artigo, Context as a Feature Boundary, mostra como encapsular funcionalidades inteiras — como carrinhos de compras, autenticação e notificações — por trás de APIs limpas e testáveis. Você aprenderá a substituir stores globais, compor funcionalidades com segurança e escalar sua arquitetura conforme sua aplicação cresce.

Veja Também

Documentação Oficial

Svelte 5 Classes — Usando runes em classes
TypeScript Class Fields — Campos privados e modificadores de acesso