DEV Community

Cover image for From Resilience4j to TypeScript: Build the JVM Patterns You Already Know
Gabriel Anhaia
Gabriel Anhaia

Posted on

From Resilience4j to TypeScript: Build the JVM Patterns You Already Know

#typescript #java #kotlin #backend

You joined a Node service. The first ticket says: make paymentService.charge resilient: circuit breaker, retry on 5xx, rate limit per merchant. On the JVM the answer is muscle memory:

@CircuitBreaker(name = "payments", fallbackMethod = "fallback")
@Retry(name = "payments")
@RateLimiter(name = "payments")
public Receipt charge(Charge req) {
    return gateway.send(req);
}
Enter fullscreen mode Exit fullscreen mode

Five lines. Three resilience guarantees. The @CircuitBreaker and @Retry annotations come from Resilience4j, the @RateLimiter either there or in Spring Cloud, and the AOP machinery wraps charge at startup. The method body has zero idea any of this is happening.

You open VS Code, type @Circuit, and wait for autocomplete. Nothing. You search npm for "resilience4j typescript". A handful of half-maintained ports show up. None match. You look at the Spring docs link from the ticket and feel the floor tilt: the framework I rely on for this isn't here at all.

The patterns are still here. Circuit breaker, retry, bulkhead, rate limiter, time limiter, fallback, cache: every one of them ports to TypeScript and runs in production at companies you've heard of. What changed is the shape. JVM resilience is annotations on methods. TypeScript resilience is functions that wrap functions.

Once you internalise that shift, the rest is mechanical: pick a wrapper library, compose the policies you need, pass the wrapped function around.

What Resilience4j actually ships

Resilience4j is the Hystrix successor most JVM teams settled on after Netflix moved Hystrix into maintenance mode in 2018. The Resilience4j docs ship six core modules: CircuitBreaker (open / half-open / closed state machine), Retry (N attempts with backoff and jitter), RateLimiter (token bucket or fixed window), Bulkhead (concurrency cap, in SemaphoreBulkhead and ThreadPoolBulkhead flavours), TimeLimiter (deadline-driven TimeoutException), and Cache (JCache-backed memoisation). The @CircuitBreaker / @Retry / @Bulkhead / @RateLimiter / @TimeLimiter annotations wire those decorators in through Spring's AOP proxies, configuration lives in application.yml, and metrics ship to Micrometer. The whole thing is a four-line dependency add and a config block.

That density is what JVM developers miss when they land in TypeScript. The patterns are not exotic. They're commodity infrastructure on the JVM.

TypeScript has the patterns, not the annotations

TC39's decorators proposal reached Stage 3 in March 2022 and TypeScript 5.0 shipped native support in March 2023. Decorators exist in the language. Frameworks that use them (NestJS, TypeORM, class-validator) feel familiar to a Spring developer.

Most TypeScript code does not use them. Most TypeScript code is plain functions and modules. There's no Spring container scanning your beans at startup, no AOP proxy generated around your class, no annotation processor reading metadata at runtime. NestJS adds that machinery on top, and inside a NestJS service you can write @UseInterceptors(CircuitBreakerInterceptor) and have something close to the JVM experience. Outside NestJS (plain Express, Fastify, Hono, Bun.serve, a worker script), decorators are an unusual choice.

The reason is structural. JavaScript decorators are call-time wrappers around functions and class members. They don't have a DI container behind them, so you'd have to build one to make the annotation style pay off. The shorter path is the one the ecosystem actually took: ship the wrapper directly.

Sketch of the shape (the real Cockatiel API is in the next section):

const charge = withCircuitBreaker(
  withRetry(
    withRateLimiter(rawCharge, { tokensPerInterval: 100, interval: 1000 }),
    { maxAttempts: 3, backoff: "exponential" },
  ),
  { failureThreshold: 0.5, openFor: 30_000 },
);

await charge(req);
Enter fullscreen mode Exit fullscreen mode

Three function calls, each returning a function that wraps the next one. No annotations. No reflection. The composition is visible at the call site, and the wrapped charge is another value you pass around. That is the shift.

Side-by-side: Spring vs TypeScript, same service

Take a payment service that needs all of: circuit breaker, retry, rate limiter. The JVM version uses three Resilience4j annotations:

@Service
public class PaymentService {

    @CircuitBreaker(name = "gateway", fallbackMethod = "denied")
    @Retry(name = "gateway")
    @RateLimiter(name = "gateway")
    public Receipt charge(Charge req) {
        return gateway.send(req);
    }

    public Receipt denied(Charge req, Throwable t) {
        return Receipt.failed(t.getMessage());
    }
}
Enter fullscreen mode Exit fullscreen mode

Configuration in application.yml:

resilience4j:
  circuitbreaker:
    instances:
      gateway:
        failureRateThreshold: 50
        waitDurationInOpenState: 30s
  retry:
    instances:
      gateway:
        maxAttempts: 3
        waitDuration: 250ms
  ratelimiter:
    instances:
      gateway:
        limitForPeriod: 100
        limitRefreshPeriod: 1s
Enter fullscreen mode Exit fullscreen mode

The TypeScript version is the same shape, in code:

import {
  circuitBreaker,
  retry,
  ConsecutiveBreaker,
  ExponentialBackoff,
  handleAll,
  wrap,
} from "cockatiel";
import { RateLimiterMemory } from "rate-limiter-flexible";

const limiter = new RateLimiterMemory({
  points: 100,
  duration: 1, // per second
});

const policy = wrap(
  circuitBreaker(handleAll, {
    halfOpenAfter: 30_000,
    breaker: new ConsecutiveBreaker(5),
  }),
  retry(handleAll, {
    maxAttempts: 3,
    backoff: new ExponentialBackoff({ initialDelay: 250 }),
  }),
);

// gateway.send: (req: Charge) => Promise<Receipt>
export async function charge(req: Charge): Promise<Receipt> {
  await limiter.consume(req.merchantId);
  try {
    return await policy.execute(() => gateway.send(req));
  } catch (err) {
    const message = err instanceof Error ? err.message : String(err);
    return Receipt.failed(message);
  }
}
Enter fullscreen mode Exit fullscreen mode

Two functions doing the same job, expressed in two different shapes. In the Spring version the annotations declare what charge is. In the TypeScript version the code constructs it. Both ship to production. Both behave identically against a stubbed gateway.send.

A JVM developer's first instinct on reading the TS code is "this is more verbose". It is, by line count. What you get back is everything is a value: policy is a regular object, charge is a regular function, both go into a Map, both serialise into snapshot tests, both behave under vi.useFakeTimers() without any AOP-aware testing harness. The annotation magic in Spring buys density. The cost: at runtime you can't tell what's actually wrapping the method without reading the proxy chain in a debugger. TypeScript's tradeoff goes the other way.

Cockatiel, the closest thing to Resilience4j

When a JVM developer asks "what's the TS equivalent of Resilience4j", the honest answer is Cockatiel. It was started by Connor Peet, a Microsoft engineer on the VS Code team, and ships the same six policy types Resilience4j ships, with the same composability story.

What Cockatiel covers:

  • retry(...) — maxAttempts, ConstantBackoff, ExponentialBackoff, IterableBackoff for custom delay schedules. Filter on errors via handleType, handleWhen, handleResultType.
  • circuitBreaker(...) — ConsecutiveBreaker, SamplingBreaker (rolling window failure rate), CountBreaker. halfOpenAfter and state events.
  • bulkhead(concurrency, queue) — cap concurrent and queued executions.
  • timeout(ms, strategy) — Cooperative (passes a signal) or Aggressive (rejects regardless).
  • fallback(handle, value) — return a default on failure.
  • wrap(...policies) — compose, outer-to-inner. wrap(circuit, retry) runs retry inside circuit; the breaker only sees the final result of the retry block.

A real composed policy:

import {
  bulkhead,
  circuitBreaker,
  ConsecutiveBreaker,
  ExponentialBackoff,
  handleAll,
  retry,
  timeout,
  TimeoutStrategy,
  wrap,
} from "cockatiel";

const policy = wrap(
  bulkhead(10, 50),
  circuitBreaker(handleAll, {
    halfOpenAfter: 30_000,
    breaker: new ConsecutiveBreaker(5),
  }),
  retry(handleAll, {
    maxAttempts: 3,
    backoff: new ExponentialBackoff(),
  }),
  timeout(2_000, TimeoutStrategy.Cooperative),
);

const result = await policy.execute(({ signal }) =>
  fetch(url, { signal }).then((r) => r.json()),
);
Enter fullscreen mode Exit fullscreen mode

Read inside-out: the leaf fetch is given a 2-second cooperative timeout (Cockatiel passes you an AbortSignal you should plumb into fetch). If it fails, retry kicks in for up to 3 attempts with exponential backoff. The retry block sits behind a circuit breaker that opens after 5 consecutive failures. The whole thing is gated by a bulkhead that allows 10 concurrent in-flight calls plus 50 queued.

This is the same composition Resilience4j gives you with Decorators.ofSupplier(...).withRetry(...).withCircuitBreaker(...).withBulkhead(...).withTimeLimiter(...). Function-level, not annotation-level, but the policies and the order of application are the same.

For rate limiting, Cockatiel doesn't ship a primitive; the de-facto choice is rate-limiter-flexible, which gives you token-bucket and leaky-bucket implementations backed by memory, Redis, MongoDB, or Postgres. For caching the call result, p-memoize plus quick-lru is the small, focused combo most teams pick. None of these talk to each other automatically, but each is a function that wraps a function, which is the whole point.

The decorator-vs-wrapper mental shift

Walk through what changes when you stop looking for @CircuitBreaker.

Composition is explicit. In Spring, @CircuitBreaker and @Retry on the same method get applied in an order determined by aspect ordering: Ordered constants, @Order annotations, or framework defaults. The order matters (retry inside the breaker vs breaker inside the retry are very different behaviours), and the order is invisible at the call site. In TypeScript, wrap(circuit, retry) and wrap(retry, circuit) are different expressions. You can read which is outer and which is inner.

Wrapped functions are values. The wrapped charge is just a function. You can hold it in a variable, pass it to a queue worker, snapshot-test it, hand it to a test double, swap it out per-environment. The Spring proxy is also a value, but you have to ask the application context for it, and the bean's identity at runtime is not the class you wrote — it's a generated CGLIB or JDK proxy subclass. Tests for @CircuitBreaker end up being integration tests with Spring loaded.

No DI container is required. Resilience4j's annotation magic depends on Spring AOP, which depends on the ApplicationContext. Strip Spring out and the annotations stop doing anything — they're just metadata on a method nobody reads. Cockatiel runs the same in a Node script, an AWS Lambda, a Cloudflare Worker, a Bun HTTP server, a Deno cron, a Vite-bundled browser app. There's no container to bring up.

Configuration lives in code. Spring's application.yml profile system lets ops change a circuit breaker's threshold without a redeploy. The TypeScript equivalent is reading the threshold from process.env and rebuilding the policy on startup, or using a config service and rebuilding the policy on change. Both work; the JVM version is more declarative and the TS version is more direct. Pick the one that matches your deploy story.

The shift, said one way: JVM resilience is declared on a method. TypeScript resilience is built into a function. Once that lands, every Resilience4j primitive has a clean port.

Quick translation table

Resilience4j TypeScript equivalent
@CircuitBreaker(name = "x") circuitBreaker(handleAll, { breaker: new ConsecutiveBreaker(n), halfOpenAfter: ms }) from Cockatiel
@Retry(name = "x") retry(handleAll, { maxAttempts: n, backoff: new ExponentialBackoff() }) from Cockatiel
@RateLimiter(name = "x") RateLimiterMemory / RateLimiterRedis from rate-limiter-flexible, await limiter.consume(key)
@Bulkhead(name = "x") (semaphore) bulkhead(concurrency, queue) from Cockatiel
@Bulkhead(type = THREADPOOL) a worker pool (Piscina, BullMQ workers) — the model is different
@TimeLimiter(name = "x") timeout(ms, TimeoutStrategy.Cooperative) from Cockatiel, or AbortSignal.timeout(ms)
@Cache(cacheName = "x") p-memoize over a quick-lru or Redis-backed cache
Decorators.ofSupplier(...).withRetry(...).withCircuitBreaker(...) wrap(circuitBreaker(...), retry(...)) from Cockatiel
Resilience4j Micrometer metrics Cockatiel policy.onSuccess / onFailure / onBreak events into your metrics client
application.yml config block env-driven config, parsed at startup, passed to the wrapper constructors
Spring @Order on aspects argument order in wrap(...)

The one row where the shape doesn't match is @Bulkhead(type = THREADPOOL). That assumes a JVM thread pool you can offload work to. Node, Bun, and Deno are single-threaded for user code; CPU-bound parallelism comes from Worker threads with explicit message passing. The SemaphoreBulkhead row maps cleanly because it's I/O concurrency, which translates directly. The thread-pool row is genuinely lossy and the right answer is usually a job queue (BullMQ, Quirrel, Inngest) rather than an in-process pool.

Wrappers are the substrate

NestJS interceptors give you the annotation feel on top of the same wrapper machine. Decorators in TS are sugar over wrappers, the same way async is sugar over Promise. Reach for the wrappers first and the decorators-when-you-want-them story is additive instead of foundational.

Once you stop searching for @CircuitBreaker and start writing wrap(circuitBreaker(...), retry(...)), the move is mostly done.

If this was useful

The TypeScript Library is a 5-book collection that maps cleanly to where you start:

  • TypeScript Essentials — Amazon — entry point. Types, narrowing, modules, async, daily-driver tooling.
  • The TypeScript Type System — Amazon — deep dive. Generics, mapped/conditional types, infer, template literals, branded types.
  • Kotlin and Java to TypeScript — Amazon — bridge for JVM developers. Variance, null safety, sealed→unions, coroutines→async/await.
  • PHP to TypeScript — Amazon — bridge for PHP 8+ developers. Sync→async paradigm, generics, discriminated unions.
  • TypeScript in Production — Amazon — production layer. tsconfig, build tools, monorepos, library authoring, dual ESM/CJS, JSR.

Books 1 and 2 are the core path. Books 3 and 4 substitute for 1 and 2 if you're coming from JVM or PHP — this post is a sample of what book 3 covers. Book 5 is for anyone shipping TypeScript at work.

All five books ship in ebook, paperback, and hardcover.

The TypeScript Library — the 5-book collection

Top comments (0)