Node SDK v5.x.x to v6.0.0 Upgrade Guide

Summary

Node.js SDK V6.0.0 introduced breaking changes on

• Removed async version of core APIs (checkGate, getConfig..)
• Changed DataAdapter cache keys SDK used to read and write from
• Changed default hashing algorithm used for getClientInitializeResponse() which is being used for bootstrapping client sdk.
• If no environment tier is set for the SDK, the environment defaults to production when evaluating.
• Changed how you should disable exposure logging

Synchronous core APIs

Changes Changed all core apis to be synchronous functions

// All removed
async getFeatureGate(): Promise<FeatureGate> // Removed
getFeatureGate(): FeatureGate // New API

async checkGate(): Promise<bool> // Removed
checkGate(): bool // New API

async getConfig(): Promise<DynamicConfig>
getConfig(): DynamicConfig // New API

async getExperiment(): Promise<DynamicConfig>
getExperiment(): DynamicConfig // New API

Context The original async API design ensured that every evaluation could complete correctly, even when the SDK was not compatible, by requesting evaluation from the Statsig server. As the SDK and evaluation rules became more stable, this fallback is rarely needed. All APIs are now synchronous to improve performance.

Migration Guide If you are using JavaScript and call a gate as shown below, a runtime error occurs. Audit and update your usage. If you are using TypeScript, the compiler reports an error instead.

The *Sync() functions (for example, checkGateSync()) are deprecated. Use checkGate() instead.

Statsig.checkGate(user, "gate").then(() => {
  // do somethig
}).catch() // Compile error if you are using typescript. If you are using javascript, there will be runtime error please audit and 

If you are using await as shown below, Statsig recommends removing it, but it continues to work.

const gate = await Statsig.checkGate(user, "gate")

DataAdapter cache key changes

Context To better support multiple Statsig instances in one runtime and different response formats (for example, download_config_spec_v1 vs download_config_spec_v2), the cache keys the SDK reads and writes from were updated to avoid cache key collisions. The compress encoding format is also embedded in the key. Currently, the SDK stores only the plain-text uncompressed version in cache.

Changes

• Change cache key for config_specs from statsig.cache to

statsig|/v1/download_config_specs|{compressEncoding // plain text for now}|{SHA256HashedBase64(secretkey)}

• Change cache key for get_id_list_sources from statsig.id_lists to be:

statsig|/v1/get_id_lists|{compressEncoding // plain text for now}|{SHA256HashedBase64(secretkey)}

• Change cache key for individual id list to be

statsig|id_list::$\{String(idListName)\}|\{compressEncoding // plain text for now\}|${SHA256HashedBase64(secretKey)}

Migration Guide

1. Update your DataAdapter if you have customized the key, get, or read logic.
2. If you write to cache in other places (instead of relying on the SDK to set the cache), update the call site to use the new key.
3. If a cache miss on the first request is acceptable, no action is needed. The SDK writes to cache with the new key automatically.
4. To avoid a cold cache, write with the new key before deploying to production.

Hash algorithm change on getClientInitializeResponse()

Context To improve evaluation speed on both client and server and reduce payload size, the default hash algorithm for all config names changed from SHA256 to djb2.

Changes Config names (gates, experiments, layers) are now hashed with djb2 by default. If you specify a hash algorithm explicitly, this change doesn't affect you.

Migration Guide If you are using a recent client SDK version, client-side support is automatic and no action is needed. To continue using SHA256, set ClientInitializeResponseOptions.hash = 'sha256'.

Default environment is production if no environment is being set when SDK is initialized

Context The environment tier setting caused frequent confusion.

Changes If no environment tier is set (for example, StatsigOptions.environment.tier), the SDK now assigns a default value. If the SDK key is set, it uses that; otherwise it defaults to production.

Migration Call sites that don't set an environment tier now fail rules that target non-production environment tiers. Call sites that set an environment tier, or rules that don't set an environment or include the production tier, are unaffected.

Deprecate functions

The WithExposureLoggingDisabled functions are deprecated:

checkGateWithExposureLoggingDisabled()  // DO NOT USE
getFeatureGateWithExposureLoggingDisabled() // DO NOT USE

Use core APIs with options instead:

Statsig.checkGate(user, gate_name, {disableExposureLogging: true})  // Use
Statsig.getFeatureGate(user, gate_name, {disableExposureLogging: true})  // USE