Announcing Node.js SDK v1.2.0: Instant Flag Checks with In-Memory Caching

Every millisecond counts when you are building modern web applications. When your server needs to determine whether a feature is enabled for a user, the last thing you want is to wait for a network roundtrip to a feature flagging API on every single request.

That is why we are incredibly excited to announce the release of @rocketflag/node-sdk version 1.2.0!

This release introduces opt-in in-memory caching for flag evaluations. With this new feature, you can dramatically speed up your application’s response times, save network bandwidth, and keep your application resilient even during network hiccups.

Let’s dive into how caching works, why it is a game-changer, and how you can use it.

What is Caching? (The Sticky Note Analogy)

If you are new to backend development, the word caching might sound fancy, but the concept is very simple.

Imagine you are doing your math homework, and you need a complex formula.

• Without caching: Every time you need the formula, you get up from your chair, walk down the street to the library, look up the formula in a textbook, and walk all the way back. It takes 20 minutes every time.
• With caching: The first time you walk to the library, you write the formula down on a sticky note and stick it to your computer monitor. The next time you need it, you just glance at the sticky note. It takes half a second!

In our SDK, the library is the remote RocketFlag API server, the sticky note is your server’s local RAM (in-memory cache), and the formula is the status of your feature flag.

What is a TTL?

Sticky notes are great, but what happens if the library updates the formula? If you keep looking at your old sticky note, you will use outdated information.

To solve this, we use a TTL (Time to Live). Think of it as writing an expiration time on your sticky note: “Throw away after 5 minutes.”

Once those 5 minutes are up, you throw the sticky note in the trash. The next time you need the formula, you make one more trip to the library to get the freshest version and write a new sticky note.

How to Use Caching in the Node.js SDK

Caching in version 1.2.0 is entirely opt-in. By default, the SDK behaves exactly as it did before—fetching fresh data from the RocketFlag API on every call.

To enable caching globally, pass a default ttlSeconds configuration option when creating your client:

import createRocketflagClient from "@rocketflag/node-sdk";

// Create a client where flag evaluations are cached for 5 minutes (300 seconds)
const rocketflag = createRocketflagClient(undefined, undefined, { ttlSeconds: 300 });

// The first call hits the RocketFlag API and saves the result in memory
const flag = await rocketflag.getFlag("IFldMzqP5jtv9wAL", { cohort: "beta" });

// Subsequent calls within 5 minutes return instantly from memory!
const cachedFlag = await rocketflag.getFlag("IFldMzqP5jtv9wAL", { cohort: "beta" });

Overriding TTL on Individual Calls

Sometimes you want a global cache policy, but need to bypass it for a specific critical operation. You can override the TTL per call by passing an options object as the third argument to getFlag:

// Scenario A: Force a fresh fetch from the API (bypassing the cache completely)
const freshFlag = await rocketflag.getFlag("IFldMzqP5jtv9wAL", {}, { ttlSeconds: 0 });

// Scenario B: Use a shorter, custom TTL (10 seconds) just for this specific check
const quickFlag = await rocketflag.getFlag("IFldMzqP5jtv9wAL", {}, { ttlSeconds: 10 });

Under the Hood: Designed for Safety

We built this caching layer with two key architectural principles to prevent bugs:

1. Context-Keyed Isolation: RocketFlag allows you to serve different flags based on environments and user cohorts. The SDK is smart: it keys the cache using both the Flag ID and the full user context. This means a cached response for a user in the beta cohort will never accidentally leak to a user in the general cohort.
2. Deep-Cloning Protection: In JavaScript, objects are passed by reference. If the SDK returned the direct cached object and you modified it in your code, you would accidentally mutate the cache for all future requests. To prevent this, the SDK deep-clones cached entries on both read and write, ensuring mutation safety.

High-Performance Use Case: Microservice Gateways

Let’s look at a real-world scenario where caching makes a night-and-day difference.

Imagine you run a backend service or API gateway that handles 5,000 requests per second. On every request, you check a feature flag to see if a new premium layout is enabled for the caller.

• Without Caching: Your server makes 5,000 network requests per second to RocketFlag. Even if the RocketFlag API responds in 20 milliseconds, that’s 5,000 open connections, extra network overhead, and an added 20ms of latency on every single client request.
• With Caching (TTL of 5 minutes): Your server makes exactly 1 network request every 5 minutes. The other 1,499,999 requests are served directly from RAM in less than 1 microsecond.

By caching, you reduce network congestion, drop your flag check latency to zero, and make your application incredibly snappy.

When NOT to Cache (Trade-offs & Gotchas)

While caching is powerful, it is not a silver bullet. As a developer, you need to understand the trade-offs:

1. When Real-Time is Critical (The Emergency Switch)

If you configure a 10-minute cache TTL for a feature, and that feature starts throwing errors in production, toggling the flag "Off" in the RocketFlag console won’t take effect immediately for your users. Your servers will continue to serve the cached "On" state until their local TTL expires.

• Rule of Thumb: For critical code paths where you need instant control, use a very low TTL (like 5-10 seconds) or disable caching (ttlSeconds: 0).

2. High-Cardinality Contexts & Memory Management

The SDK’s cache is a simple in-memory key-value map stored in the running Node.js process memory. It does not have a size cap, and old entries are only deleted when they are re-requested after their TTL has expired.

If you include highly unique user data in your context (like a unique userId or UUID) and serve millions of unique users, every user will get their own cache entry. If millions of users visit once and never return, those cache entries will sit in memory indefinitely.

• Rule of Thumb: If you are using high-cardinality user contexts, avoid setting a global client TTL. Instead, cache only specific flags, or write a routine that periodically reconstructs the RocketFlag client (createRocketflagClient()) to flush old memory.

Wrap Up

In-memory caching in @rocketflag/node-sdk v1.2.0 gives you the controls to build blazing-fast systems without sacrificing the power of feature flags. Start supercharging your backend today by updating your SDK:

npm install @rocketflag/node-sdk@latest

Happy shipping!

— JK @ RocketFlag