Effect 4.0: runtime reescrito, bundle 5x menor e LTS até 2029 — o que muda no seu código TypeScript

Effect 4.0: runtime reescrito, bundle 5x menor e LTS até 2029

O Effect 4.0 chegou ao estável em 30 de setembro de 2026, depois de oito meses em beta e seis semanas em release candidate. Não é um bump de versão com ajustes de API: é uma reescrita do runtime de fibers do zero, com consolidação de pacotes, remoção de todas as dependências de runtime e uma política de suporte de longo prazo que coloca a linha 4.x em manutenção até, no mínimo, setembro de 2029.

Para quem usa Effect em produção, o recado é ambíguo e vale encarar assim mesmo. As métricas que o time publicou são boas o suficiente para justificar a atualização, e ao mesmo tempo o tamanho da mudança é grande o suficiente para exigir um plano de migração com inventário de imports, não um npm i effect@latest na sexta-feira à tarde.

O contexto importa: Effect é a biblioteca TypeScript que trata erro tipado, concorrência estruturada, injeção de dependência e observabilidade como um conjunto único de abstrações. Ela não é um framework de UI nem um substituto de Express — é uma camada de execução que passa a intermediar praticamente todo o seu código de domínio. Quando o runtime muda, muda o comportamento de tudo o que roda em cima dele.

O que mudou de fato

Quatro mudanças estruturais definem a versão:

Runtime de fibers reescrito. O agendador e a máquina de estados das fibers foram reimplementados. Isso afeta cancelamento, interrupção de escopos e propagação de contexto (spans, loggers, relógio).

Zero dependências de runtime. O time substituiu o pg por um cliente PgProtocol nativo e removeu o MessagePack. O package-lock.json de um serviço que usa @effect/sql-pg encolhe de verdade.

Pacotes consolidados. Módulos centrais de @effect/platform , @effect/rpc e @effect/cluster passaram para o pacote principal effect . Adaptadores de plataforma ( @effect/platform-node ), dados ( @effect/sql-* ) e IA ( @effect/ai-* ) continuam separados — mas agora todos compartilham o mesmo número de versão.

Política de LTS. A linha 4.x recebe correções por um ciclo definido, o que resolve um dos problemas históricos de adotar a biblioteca: a sensação de que qualquer atualização podia ser uma reescrita.

Os números: 7,1 kB e 4,57 milhões de tarefas por segundo

Os benchmarks divulgados pela Effectful Technologies, que não foram verificados de forma independente até agora , apontam:

A redução de bundle é o número mais fácil de subestimar e o mais fácil de conferir. Um bundle mínimo de 35,6 kB não parece problema em um app server-side, mas aparece em toda função serverless com cold start, em workers na borda e em CLIs distribuídas por npm. Já o heap é o número que muda a conta de memória de um serviço que processa streams com muitos consumidores concorrentes.

Reproduza você mesmo o teste de concorrência antes de acreditar:

Rode em um container com limite fixo de memória e meça o RSS. É o tipo de verificação que custa vinte minutos e evita decisão baseada em gráfico de release note.

Os imports mudam — e isso é a maior parte do diff

A consolidação não é cosmética. Um handler com erro tipado, timeout e retry, escrito para 3.x:

Em 4.0, os mesmos símbolos vêm do pacote effect :

A forma da composição sobrevive; os caminhos de import e parte dos nomes de API, não. Além do remanejamento de pacotes, a versão renomeou APIs de definição de serviço e de erro tipado e mexeu em funções de introspecção de Schema — por exemplo, Schema.resolveInto virou Schema.resolveAnnotations , com resolveAnnotationsKey acrescentado para ler anotações no nível de chave. O MIGRATION.md do repositório lista o mapa completo; é leitura obrigatória, não opcional.

Versão única é faca de dois lados. Todos os pacotes @effect/* passam a sair com o mesmo número. Some a compatibilidade cruzada a testar, mas entra um problema operacional: subir um pacote exige subir todos. Em monorepos, vale fixar a versão num catalog (pnpm), overrides (npm) ou resolutions (yarn) para que nenhum serviço do time fique meio migrado. É exatamente o tipo de decisão de engenharia que times multidisciplinares com vários repositórios TypeScript, Python e .NET precisam padronizar antes de começar — na Maquinaweb esse tipo de padronização de versão e pipeline é parte do trabalho de arquitetura, não um detalhe de final de sprint.

Onde a migração dói

Três armadilhas tendem a passar batido:

Peer dependencies antigas. Bibliotecas de terceiros que expõem tipos do Effect ficam presas ao 3.x até publicarem suporte. O caso de @xstate/test/effect-schema ilustra o padrão: a alpha mais recente declara effect@^4.0.0 e quebra quem está no 3.x. Antes de migrar, rode npm ls effect e veja quem depende da versão antiga.

Mudança de comportamento em cancelamento. Como o runtime foi reescrito, código que dependia de efeitos colaterais em finalizadores — fechar conexão, dar flush em buffer, emitir métrica no onInterrupt — merece teste explícito com Effect.onInterrupt e Scope . Compila igual, comporta diferente.

Números de benchmark não batem no seu app. O 7,1 kB é um programa mínimo. Em aplicação real, @effect/sql , @effect/ai e adaptadores puxam bem mais. Meça com o próprio bundle analyzer, não com a tabela da release note.

Vale migrar agora?

Minha leitura: sim, com escopo controlado. A combinação de LTS definido, cadência já visível (o 4.1 saiu com os módulos crypto e Glob ) e runtime sem dependências é o argumento mais forte que o projeto já teve para adoção corporativa. Mas trate como migração de plataforma: um serviço piloto, um branch de trabalho, um inventário de imports e uma bateria de testes de concorrência antes de tocar no resto.

Para quem ainda não usa Effect, o 4.0 melhora a conta. Um runtime menor e previsível, com erro tipado no sistema de tipos, é uma alternativa real a empilhar bibliotecas soltas para retry, cache, semáforo e telemetria — cada uma com seu próprio jeito de propagar contexto.

Se o seu time está avaliando migrar de stack, repensar a camada de execução de serviços TypeScript ou desenhar um projeto novo que precise de concorrência séria desde o primeiro dia, vale conversar com o time da Maquinaweb sobre arquitetura e desenvolvimento sob medida.

Fontes