Reference

Classes

BoundReflagClient

A client bound with a specific user, company, and other context.

Constructors

new BoundReflagClient()

new BoundReflagClient(client: ReflagClient, options: ContextWithTracking): BoundReflagClient

Internal

(Internal) Creates a new BoundReflagClient. Use bindClient to create a new client bound with a specific context.

Parameters

Parameter	Type	Description
client	ReflagClient	The ReflagClient to use.
options	ContextWithTracking	The options for the client.

Returns

BoundReflagClient

Accessors

company

Get Signature

get company(): 
  | undefined
  | {
[k: string]: any;   avatar: string;
  id: undefined | string | number;
  name: string;
}

Gets the company associated with the client.

Returns

| undefined | { [k: string]: any; avatar: string; id: undefined | string | number; name: string; }

The company or undefined if it is not set.

otherContext

Get Signature

get otherContext(): 
  | undefined
| Record<string, any>

Gets the "other" context associated with the client.

Returns

| undefined | Record<string, any>

The "other" context or undefined if it is not set.

user

Get Signature

get user(): 
  | undefined
  | {
[k: string]: any;   avatar: string;
  email: string;
  id: undefined | string | number;
  name: string;
}

Gets the user associated with the client.

Returns

| undefined | { [k: string]: any; avatar: string; email: string; id: undefined | string | number; name: string; }

The user or undefined if it is not set.

Methods

bindClient()

bindClient(context: ContextWithTracking): BoundReflagClient

Create a new client bound with the additional context. Note: This performs a shallow merge for user/company/other individually.

Parameters

Parameter	Type	Description
context	ContextWithTracking	The context to bind the client to.

Returns

BoundReflagClient

new client bound with the additional context

flush()

flush(): Promise<void>

Flushes the batch buffer.

Returns

Promise<void>

getFlag()

getFlag<TKey>(key: TKey): Flag

Get a specific flag for the user/company/other context bound to this client. Using the isEnabled property sends a check event to Reflag.

Type Parameters

Type Parameter
TKey extends string

Parameters

Parameter	Type	Description
key	TKey	The key of the flag to get.

Returns

Flag

Flags for the given user/company and whether each one is enabled or not

getFlagRemote()

getFlagRemote(key: string): Promise<Flag>

Get remotely evaluated flag for the user/company/other context bound to this client.

Parameters

Parameter	Type	Description
key	string	The key of the flag to get.

Returns

Promise<Flag>

Flag for the given user/company and key and whether it's enabled or not

getFlags()

getFlags(): Record<string, Flag>

Get flags for the user/company/other context bound to this client. Meant for use in serialization of flags for transferring to the client-side/browser.

Returns

Record<string, Flag>

Flags for the given user/company and whether each one is enabled or not

getFlagsForBootstrap()

getFlagsForBootstrap(): BootstrappedFlags

Get raw flags for the user/company/other context bound to this client without wrapping them in getters. This method returns raw flag data suitable for bootstrapping client-side applications.

Returns

BootstrappedFlags

Raw flags for the given user/company and whether each one is enabled or not

getFlagsRemote()

getFlagsRemote(): Promise<Record<string, Flag>>

Get remotely evaluated flag for the user/company/other context bound to this client.

Returns

Promise<Record<string, Flag>>

Flags for the given user/company and whether each one is enabled or not

refreshFlags()

refreshFlags(waitForVersion?: number): Promise<void>

Refreshes the flag definitions from the server.

Fetch starts are throttled to at most once per second. Outside in-request mode, a call to refreshFlags(waitForVersion) still waits until the cache has applied that version or newer.

In in-request mode, a throttled call only records pending refresh work. The fetch then runs on the next request/access or refreshFlags() call after the throttle window expires.

Parameters

Parameter	Type	Description
waitForVersion?	number	Optional flag state version to wait for before returning updated definitions.

Returns

Promise<void>

track()

track(event: string, options?: TrackOptions & {
  companyId: string;
}): Promise<void>

Track an event in Reflag.

Parameters

Parameter	Type	Description
event	string	The event to track.
options?	TrackOptions & { companyId: string; }	The options for the event.

Returns

Promise<void>

Throws

An error if the event is invalid or the options are invalid.

---

EdgeClient

The EdgeClient is ReflagClient pre-configured to be used in edge runtimes, like Cloudflare Workers.

It always uses flagsSyncMode: "in-request". Refresh fetch starts are throttled to at most once per second. A refreshFlags() call made during that throttle window only records pending refresh work, so the call may resolve before the fetch runs. That pending refresh is executed on the next request/access or refreshFlags() call after the window expires.

Example

// set the REFLAG_SECRET_KEY environment variable or pass the secret key in the constructor
const client = new EdgeClient();

// evaluate a flag
const context = {
  user: { id: "user-id" },
  company: { id: "company-id" },
}
const { isEnabled } = client.getFlag(context, "flag-key");

Extends

• ReflagClient

Constructors

new EdgeClient()

new EdgeClient(options: EdgeClientOptions): EdgeClient

Parameters

Parameter	Type
options	EdgeClientOptions

Returns

EdgeClient

Overrides

ReflagClient.constructor

Properties

Property	Modifier	Type	Description
httpClient	public	HttpClient	‐
logger	readonly	Logger	Gets the logger associated with the client.

Accessors

flagOverrides

Set Signature

set flagOverrides(overrides: 
  | Partial<Record<string, FlagOverride>>
  | FlagOverridesFn): void

Deprecated

Use setFlagOverrides() for replacing the base override set.

Parameters

Parameter	Type
overrides	| Partial<Record<string, FlagOverride>> | FlagOverridesFn

Returns

void

Inherited from

ReflagClient.flagOverrides

Methods

bindClient()

bindClient(context: ContextWithTracking): BoundReflagClient

Returns a new BoundReflagClient with the user/company/otherContext set to be used in subsequent calls. For example, for evaluating flag targeting or tracking events.

Parameters

Parameter	Type	Description
context	ContextWithTracking	The context to bind the client to.

Returns

BoundReflagClient

A new client bound with the arguments given.

Throws

An error if the user/company is given but their ID is not a string.

Remarks

The updateUser / updateCompany methods will automatically be called when the user/company is set respectively.

Inherited from

ReflagClient.bindClient

clearFlagOverrides()

clearFlagOverrides(): void

Clears the base flag overrides.

Returns

void

Remarks

This does not affect temporary layers added with pushFlagOverrides().

Example

client.clearFlagOverrides();

Inherited from

ReflagClient.clearFlagOverrides

destroy()

destroy(): void

Destroys the client and cleans up all resources including timers and background processes.

Returns

void

Remarks

After calling this method, the client should not be used anymore. This is particularly useful in development environments with hot reloading to prevent multiple background processes from running simultaneously.

Inherited from

ReflagClient.destroy

flush()

flush(): Promise<void>

Flushes and completes any in-flight fetches in the flag cache.

Returns

Promise<void>

Remarks

It is recommended to call this method when the application is shutting down to ensure all events are sent before the process exits.

This method is automatically called when the process exits if batchOptions.flushOnExit is true in the options (default).

Inherited from

ReflagClient.flush

getFlag()

getFlag<TKey>(__namedParameters: ContextWithTracking, key: TKey): Flag

Gets the evaluated flag for the current context which includes the user, company, and custom context. Using the isEnabled property sends a check event to Reflag.

Type Parameters

Type Parameter
TKey extends string

Parameters

Parameter	Type	Description
__namedParameters	ContextWithTracking	‐
key	TKey	The key of the flag to get.

Returns

Flag

The evaluated flag.

Remarks

Call initialize before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise.

Inherited from

ReflagClient.getFlag

getFlagDefinitions()

getFlagDefinitions(): FlagDefinition[]

Gets the flag definitions, including all config values. To evaluate which flags are enabled for a given user/company, use getFlags.

Returns

FlagDefinition[]

The flags definitions.

Inherited from

ReflagClient.getFlagDefinitions

getFlagRemote()

getFlagRemote<TKey>(
   key: TKey, 
   userId?: IdType, 
   companyId?: IdType, 
additionalContext?: Context): Promise<Flag>

Gets evaluated flag with the usage of remote context. This method triggers a network request every time it's called.

Type Parameters

Type Parameter
TKey extends string

Parameters

Parameter	Type	Description
key	TKey	The key of the flag to get.
userId?	IdType	The userId of the user to get the flag for.
companyId?	IdType	The companyId of the company to get the flag for.
additionalContext?	Context	The additional context to get the flag for.

Returns

Promise<Flag>

evaluated flag

Inherited from

ReflagClient.getFlagRemote

getFlags()

getFlags(options: ContextWithTracking): Record<string, Flag>

Gets the evaluated flags for the current context which includes the user, company, and custom context.

Parameters

Parameter	Type	Description
options	ContextWithTracking	The options for the context.

Returns

Record<string, Flag>

The evaluated flags.

Remarks

Call initialize before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise.

Inherited from

ReflagClient.getFlags

getFlagsForBootstrap()

getFlagsForBootstrap(options: ContextWithTracking): BootstrappedFlags

Gets the evaluated flags for the current context without wrapping them in getters. This method returns raw flag data suitable for bootstrapping client-side applications.

Parameters

Parameter	Type	Description
options	ContextWithTracking	The options for the context.

Returns

BootstrappedFlags

The evaluated raw flags and the context.

Remarks

Call initialize before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise. This method returns RawFlag objects without wrapping them in getters, making them suitable for serialization.

Inherited from

ReflagClient.getFlagsForBootstrap

getFlagsRemote()

getFlagsRemote(
   userId?: IdType, 
   companyId?: IdType, 
additionalContext?: Context): Promise<Record<string, Flag>>

Gets evaluated flags with the usage of remote context. This method triggers a network request every time it's called.

Parameters

Parameter	Type	Description
userId?	IdType	The userId of the user to get the flags for.
companyId?	IdType	The companyId of the company to get the flags for.
additionalContext?	Context	The additional context to get the flags for.

Returns

Promise<Record<string, Flag>>

evaluated flags

Inherited from

ReflagClient.getFlagsRemote

initialize()

initialize(): Promise<void>

Initializes the client by caching the flags definitions.

Returns

Promise<void>

Remarks

Call this method before calling getFlags to ensure the flag definitions are cached. The client will ignore subsequent calls to this method.

Inherited from

ReflagClient.initialize

pushFlagOverrides()

pushFlagOverrides(overrides: 
  | Partial<Record<string, FlagOverride>>
  | FlagOverridesFn): () => void

Temporarily layers flag overrides on top of the current overrides.

Parameters

Parameter	Type	Description
overrides	| Partial<Record<string, FlagOverride>> | FlagOverridesFn	The flag overrides to apply for the scoped period.

Returns

Function

A remove function that removes only this override layer.

Returns

void

Remarks

This is intended for tests or other short-lived local overrides. The remove function is idempotent and can safely be called multiple times.

Example

let remove: (() => void) | undefined;

beforeEach(() => {
  remove = client.pushFlagOverrides({ "flag-1": true });
});

afterEach(() => {
  remove?.();
  remove = undefined;
});

Inherited from

ReflagClient.pushFlagOverrides

refreshFlags()

refreshFlags(waitForVersion?: number): Promise<void>

Refreshes the flag definitions from the server.

Parameters

Parameter	Type	Description
waitForVersion?	number	Optional flag state version to wait for before returning updated definitions.

Returns

Promise<void>

Remarks

This triggers an on-demand refresh of the cached flag definitions. Useful when you know flags have changed and don't want to wait for the next automatic refresh cycle.

Note: updated flag rules take a few seconds to propagate to all servers.

Fetch starts are throttled to at most once per second. Outside in-request mode, throttling only delays when the next fetch begins: refreshFlags(99) still waits until the cache has applied flag definitions from version 99 or newer before the promise resolves. Concurrent callers are deduplicated and may share the same in-flight or scheduled follow-up refresh.

In in-request mode, delayed follow-up refreshes are not scheduled. On edge runtimes like Cloudflare Workers, a call during the throttle window only records pending refresh work, and the promise may resolve before that fetch runs. The pending refresh is executed on the next request/access or refreshFlags() call after the throttle window expires.

Inherited from

ReflagClient.refreshFlags

setFlagOverrides()

setFlagOverrides(overrides: 
  | Partial<Record<string, FlagOverride>>
  | FlagOverridesFn): void

Replaces the base flag overrides used by the client.

Parameters

Parameter	Type	Description
overrides	| Partial<Record<string, FlagOverride>> | FlagOverridesFn	The flag overrides.

Returns

void

Remarks

Base overrides are always applied before any temporary layers added through pushFlagOverrides().

Example

client.setFlagOverrides({
  "flag-1": true,
  "flag-2": false,
});

Inherited from

ReflagClient.setFlagOverrides

track()

track(
   userId: IdType, 
   event: string, 
   options?: TrackOptions & {
  companyId: IdType;
}): Promise<void>

Tracks an event in Reflag.

Parameters

Parameter	Type
userId	IdType
event	string
options?	TrackOptions & { companyId: IdType; }

Returns

Promise<void>

Throws

An error if the user is not set or the event is invalid or the options are invalid.

Remarks

If the company is set, the event will be associated with the company.

Inherited from

ReflagClient.track

updateCompany()

updateCompany(companyId: IdType, options?: TrackOptions & {
  userId: IdType;
}): Promise<void>

Updates the associated company in Reflag.

Parameters

Parameter	Type	Description
companyId	IdType	The companyId of the company to update.
options?	TrackOptions & { userId: IdType; }	The options for the company.

Returns

Promise<void>

Throws

An error if the company is not set or the options are invalid.

Remarks

The company must be set using withCompany before calling this method. If the user is set, the company will be associated with the user.

Inherited from

ReflagClient.updateCompany

updateUser()

updateUser(userId: IdType, options?: TrackOptions): Promise<void>

Updates the associated user in Reflag.

Parameters

Parameter	Type	Description
userId	IdType	The userId of the user to update.
options?	TrackOptions	The options for the user.

Returns

Promise<void>

Throws

An error if the company is not set or the options are invalid.

Remarks

The company must be set using withCompany before calling this method. If the user is set, the company will be associated with the user.

Inherited from

ReflagClient.updateUser

---

ReflagClient

The SDK client.

Remarks

This is the main class for interacting with Reflag. It is used to evaluate flags, update user and company contexts, and track events.

Example

// set the REFLAG_SECRET_KEY environment variable or pass the secret key to the constructor
const client = new ReflagClient();

// evaluate a flag
const isFlagEnabled = client.getFlag("flag-key", {
  user: { id: "user-id" },
  company: { id: "company-id" },
});

Extended by

• EdgeClient

Constructors

new ReflagClient()

new ReflagClient(options: ClientOptions): ReflagClient

Creates a new SDK client. See README for configuration options.

Parameters

Parameter	Type	Description
options	ClientOptions	The options for the client or an existing client to clone.

Returns

ReflagClient

Throws

An error if the options are invalid.

Properties

Property	Modifier	Type	Description
httpClient	public	HttpClient	‐
logger	readonly	Logger	Gets the logger associated with the client.

Accessors

flagOverrides

Set Signature

set flagOverrides(overrides: 
  | Partial<Record<string, FlagOverride>>
  | FlagOverridesFn): void

Deprecated

Use setFlagOverrides() for replacing the base override set.

Parameters

Parameter	Type
overrides	| Partial<Record<string, FlagOverride>> | FlagOverridesFn

Returns

void

Methods

bindClient()

bindClient(context: ContextWithTracking): BoundReflagClient

Returns a new BoundReflagClient with the user/company/otherContext set to be used in subsequent calls. For example, for evaluating flag targeting or tracking events.

Parameters

Parameter	Type	Description
context	ContextWithTracking	The context to bind the client to.

Returns

BoundReflagClient

A new client bound with the arguments given.

Throws

An error if the user/company is given but their ID is not a string.

Remarks

The updateUser / updateCompany methods will automatically be called when the user/company is set respectively.

clearFlagOverrides()

clearFlagOverrides(): void

Clears the base flag overrides.

Returns

void

Remarks

This does not affect temporary layers added with pushFlagOverrides().

Example

client.clearFlagOverrides();

destroy()

destroy(): void

Destroys the client and cleans up all resources including timers and background processes.

Returns

void

Remarks

After calling this method, the client should not be used anymore. This is particularly useful in development environments with hot reloading to prevent multiple background processes from running simultaneously.

flush()

flush(): Promise<void>

Flushes and completes any in-flight fetches in the flag cache.

Returns

Promise<void>

Remarks

It is recommended to call this method when the application is shutting down to ensure all events are sent before the process exits.

This method is automatically called when the process exits if batchOptions.flushOnExit is true in the options (default).

getFlag()

getFlag<TKey>(__namedParameters: ContextWithTracking, key: TKey): Flag

Gets the evaluated flag for the current context which includes the user, company, and custom context. Using the isEnabled property sends a check event to Reflag.

Type Parameters

Type Parameter
TKey extends string

Parameters

Parameter	Type	Description
__namedParameters	ContextWithTracking	‐
key	TKey	The key of the flag to get.

Returns

Flag

The evaluated flag.

Remarks

Call initialize before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise.

getFlagDefinitions()

getFlagDefinitions(): FlagDefinition[]

Gets the flag definitions, including all config values. To evaluate which flags are enabled for a given user/company, use getFlags.

Returns

FlagDefinition[]

The flags definitions.

getFlagRemote()

getFlagRemote<TKey>(
   key: TKey, 
   userId?: IdType, 
   companyId?: IdType, 
additionalContext?: Context): Promise<Flag>

Gets evaluated flag with the usage of remote context. This method triggers a network request every time it's called.

Type Parameters

Type Parameter
TKey extends string

Parameters

Parameter	Type	Description
key	TKey	The key of the flag to get.
userId?	IdType	The userId of the user to get the flag for.
companyId?	IdType	The companyId of the company to get the flag for.
additionalContext?	Context	The additional context to get the flag for.

Returns

Promise<Flag>

evaluated flag

getFlags()

getFlags(options: ContextWithTracking): Record<string, Flag>

Gets the evaluated flags for the current context which includes the user, company, and custom context.

Parameters

Parameter	Type	Description
options	ContextWithTracking	The options for the context.

Returns

Record<string, Flag>

The evaluated flags.

Remarks

Call initialize before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise.

getFlagsForBootstrap()

getFlagsForBootstrap(options: ContextWithTracking): BootstrappedFlags

Gets the evaluated flags for the current context without wrapping them in getters. This method returns raw flag data suitable for bootstrapping client-side applications.

Parameters

Parameter	Type	Description
options	ContextWithTracking	The options for the context.

Returns

BootstrappedFlags

The evaluated raw flags and the context.

Remarks

Call initialize before calling this method to ensure the flag definitions are cached, no flags will be returned otherwise. This method returns RawFlag objects without wrapping them in getters, making them suitable for serialization.

getFlagsRemote()

getFlagsRemote(
   userId?: IdType, 
   companyId?: IdType, 
additionalContext?: Context): Promise<Record<string, Flag>>

Gets evaluated flags with the usage of remote context. This method triggers a network request every time it's called.

Parameters

Parameter	Type	Description
userId?	IdType	The userId of the user to get the flags for.
companyId?	IdType	The companyId of the company to get the flags for.
additionalContext?	Context	The additional context to get the flags for.

Returns

Promise<Record<string, Flag>>

evaluated flags

initialize()

initialize(): Promise<void>

Initializes the client by caching the flags definitions.

Returns

Promise<void>

Remarks

Call this method before calling getFlags to ensure the flag definitions are cached. The client will ignore subsequent calls to this method.

pushFlagOverrides()

pushFlagOverrides(overrides: 
  | Partial<Record<string, FlagOverride>>
  | FlagOverridesFn): () => void

Temporarily layers flag overrides on top of the current overrides.

Parameters

Parameter	Type	Description
overrides	| Partial<Record<string, FlagOverride>> | FlagOverridesFn	The flag overrides to apply for the scoped period.

Returns

Function

A remove function that removes only this override layer.

Returns

void

Remarks

This is intended for tests or other short-lived local overrides. The remove function is idempotent and can safely be called multiple times.

Example

let remove: (() => void) | undefined;

beforeEach(() => {
  remove = client.pushFlagOverrides({ "flag-1": true });
});

afterEach(() => {
  remove?.();
  remove = undefined;
});

refreshFlags()

refreshFlags(waitForVersion?: number): Promise<void>

Refreshes the flag definitions from the server.

Parameters

Parameter	Type	Description
waitForVersion?	number	Optional flag state version to wait for before returning updated definitions.

Returns

Promise<void>

Remarks

This triggers an on-demand refresh of the cached flag definitions. Useful when you know flags have changed and don't want to wait for the next automatic refresh cycle.

Note: updated flag rules take a few seconds to propagate to all servers.

Fetch starts are throttled to at most once per second. Outside in-request mode, throttling only delays when the next fetch begins: refreshFlags(99) still waits until the cache has applied flag definitions from version 99 or newer before the promise resolves. Concurrent callers are deduplicated and may share the same in-flight or scheduled follow-up refresh.

In in-request mode, delayed follow-up refreshes are not scheduled. On edge runtimes like Cloudflare Workers, a call during the throttle window only records pending refresh work, and the promise may resolve before that fetch runs. The pending refresh is executed on the next request/access or refreshFlags() call after the throttle window expires.

setFlagOverrides()

setFlagOverrides(overrides: 
  | Partial<Record<string, FlagOverride>>
  | FlagOverridesFn): void

Replaces the base flag overrides used by the client.

Parameters

Parameter	Type	Description
overrides	| Partial<Record<string, FlagOverride>> | FlagOverridesFn	The flag overrides.

Returns

void

Remarks

Base overrides are always applied before any temporary layers added through pushFlagOverrides().

Example

client.setFlagOverrides({
  "flag-1": true,
  "flag-2": false,
});

track()

track(
   userId: IdType, 
   event: string, 
   options?: TrackOptions & {
  companyId: IdType;
}): Promise<void>

Tracks an event in Reflag.

Parameters

Parameter	Type
userId	IdType
event	string
options?	TrackOptions & { companyId: IdType; }

Returns

Promise<void>

Throws

An error if the user is not set or the event is invalid or the options are invalid.

Remarks

If the company is set, the event will be associated with the company.

updateCompany()

updateCompany(companyId: IdType, options?: TrackOptions & {
  userId: IdType;
}): Promise<void>

Updates the associated company in Reflag.

Parameters

Parameter	Type	Description
companyId	IdType	The companyId of the company to update.
options?	TrackOptions & { userId: IdType; }	The options for the company.

Returns

Promise<void>

Throws

An error if the company is not set or the options are invalid.

Remarks

The company must be set using withCompany before calling this method. If the user is set, the company will be associated with the user.

updateUser()

updateUser(userId: IdType, options?: TrackOptions): Promise<void>

Updates the associated user in Reflag.

Parameters

Parameter	Type	Description
userId	IdType	The userId of the user to update.
options?	TrackOptions	The options for the user.

Returns

Promise<void>

Throws

An error if the company is not set or the options are invalid.

Remarks

The company must be set using withCompany before calling this method. If the user is set, the company will be associated with the user.

Interfaces

ContextWithTracking

A context with tracking option.

Extends

• Context

Properties

Property	Type	Description
company?	{ [k: string]: any; avatar: string; id: undefined | string | number; name: string; }	The company context. If no id key is set, the whole object is ignored.
company.avatar?	string	The avatar URL of the company.
company.id	undefined | string | number	The identifier of the company.
company.name?	string	The name of the company.
enableTracking?	boolean	Enable tracking for the context. If set to false, tracking will be disabled for the context. Default is true.
meta?	TrackingMeta	The meta context used to update the user or company when syncing is required during feature retrieval.
other?	Record<string, any>	The other context. This is used for any additional context that is not related to user or company.
user?	{ [k: string]: any; avatar: string; email: string; id: undefined | string | number; name: string; }	The user context. If no id key is set, the whole object is ignored.
user.avatar?	string	The avatar URL of the user.
user.email?	string	The email of the user.
user.id	undefined | string | number	The identifier of the user.
user.name?	string	The name of the user.

---

Flag<TConfig>

Describes a feature

Type Parameters

Type Parameter	Default type
TConfig extends FlagType["config"]	EmptyFlagRemoteConfig

Properties

Property	Type	Description
config	| EmptyFlagRemoteConfig | { key: string; } & TConfig	‐
isEnabled	boolean	If the feature is enabled.
key	string	The key of the feature.

Methods

track()

track(): Promise<void>

Track feature usage in Reflag.

Returns

Promise<void>

---

Flags

Describes a collection of evaluated features.

Remarks

You should extend the Flags interface to define the available features.

---

FlagsFallbackProvider

Provider used to load and save raw flag definition snapshots.

Methods

load()

load(context: FlagsFallbackProviderContext): Promise<undefined | FlagsFallbackSnapshot>

Load a previously saved snapshot.

Parameters

Parameter	Type
context	FlagsFallbackProviderContext

Returns

Promise<undefined | FlagsFallbackSnapshot>

save()

save(context: FlagsFallbackProviderContext, snapshot: FlagsFallbackSnapshot): Promise<void>

Persist a snapshot after a successful live fetch.

Parameters

Parameter	Type
context	FlagsFallbackProviderContext
snapshot	FlagsFallbackSnapshot

Returns

Promise<void>

---

HttpClient

Defines the interface for an HTTP client.

Remarks

This interface is used to abstract the HTTP client implementation from the SDK. Define your own implementation of this interface to use a different HTTP client.

Methods

get()

get<TResponse>(
   url: string, 
   headers: Record<string, string>, 
timeoutMs: number): Promise<HttpClientResponse<TResponse>>

Sends a GET request to the specified URL.

Type Parameters

Type Parameter
TResponse

Parameters

Parameter	Type	Description
url	string	The URL to send the request to.
headers	Record<string, string>	The headers to include in the request.
timeoutMs	number	‐

Returns

Promise<HttpClientResponse<TResponse>>

The response from the server.

post()

post<TBody, TResponse>(
   url: string, 
   headers: Record<string, string>, 
body: TBody): Promise<HttpClientResponse<TResponse>>

Sends a POST request to the specified URL.

Type Parameters

Type Parameter
TBody
TResponse

Parameters

Parameter	Type	Description
url	string	The URL to send the request to.
headers	Record<string, string>	The headers to include in the request.
body	TBody	The body of the request.

Returns

Promise<HttpClientResponse<TResponse>>

The response from the server.

---

Logger

Logger interface for logging messages

Properties

Property	Type	Description
debug	(message: string, data?: any) => void	Log a debug messages
error	(message: string, data?: any) => void	Log an error messages
info	(message: string, data?: any) => void	Log an info messages
warn	(message: string, data?: any) => void	Log a warning messages

---

RawFlag

Describes a feature.

Properties

Property	Type	Description
config?	RawFlagRemoteConfig	The remote configuration value for the feature.
isEnabled	boolean	If the feature is enabled.
key	string	The key of the feature.
missingContextFields?	string[]	The missing fields in the evaluation context (optional).
ruleEvaluationResults?	boolean[]	The rule results of the evaluation (optional).
targetingVersion?	number	The version of the targeting used to evaluate if the feature is enabled (optional).

Type Aliases

Attributes

type Attributes = Record<string, any>;

Describes the attributes of a user, company or event.

---

BatchBufferOptions<T>

type BatchBufferOptions<T> = {
  flushHandler: (items: T[]) => Promise<void>;
  flushOnExit: boolean;
  intervalMs: number;
  logger: Logger;
  maxSize: number;
};

Options for configuring the BatchBuffer.

Type Parameters

Type Parameter	Description
T	The type of items in the buffer.

Type declaration

Name	Type	Description
flushHandler	(items: T[]) => Promise<void>	A function that handles flushing the items in the buffer.
flushOnExit?	boolean	Whether to flush the buffer on exit.
intervalMs?	number	The interval in milliseconds at which the buffer is flushed. Remarks If 0, the buffer is flushed only when maxSize is reached.
logger?	Logger	The logger to use for logging (optional).
maxSize?	number	The maximum size of the buffer before it is flushed.

---

BootstrappedFlags

type BootstrappedFlags = {
  context: Context;
  flags: RawFlags;
  flagStateVersion: number;
};

Describes a collection of evaluated raw flags and the context for bootstrapping.

Type declaration

Name	Type
context	Context
flags	RawFlags
flagStateVersion?	number

---

CacheStrategy

type CacheStrategy = "periodically-update" | "in-request";

---

ClientOptions

type ClientOptions = {
  apiBaseUrl: string;
  batchOptions: Omit<BatchBufferOptions<any>, "flushHandler" | "logger">;
  cacheStrategy: CacheStrategy;
  configFile: string;
  emitEvaluationEvents: boolean;
  fallbackFlags:   | TypedFlagKey[]
     | Record<TypedFlagKey, Exclude<FlagOverride, false>>;
  fetchTimeoutMs: number;
  flagOverrides:   | FlagOverrides
     | (context: Context) => FlagOverrides;
  flagsFallbackProvider: FlagsFallbackProvider;
  flagsFetchRetries: number;
  flagsPushUrl: string;
  flagsSyncMode: FlagsSyncMode;
  host: string;
  httpClient: HttpClient;
  logger: Logger;
  logLevel: LogLevel;
  offline: boolean;
  secretKey: string;
};

Defines the options for the SDK client.

Type declaration

Name	Type	Description
apiBaseUrl?	string	The host to send requests to (optional).
batchOptions?	Omit<BatchBufferOptions<any>, "flushHandler" | "logger">	The options for the batch buffer (optional). If not provided, the default options are used.
cacheStrategy?	CacheStrategy	Deprecated Use flagsSyncMode.
configFile?	string	The path to the config file. If supplied, the config file will be loaded. Defaults to reflag.config.json when NODE_ENV is not production. Can also be set through the environment variable REFLAG_CONFIG_FILE.
emitEvaluationEvents?	boolean	Deprecated: evaluation events are no longer emitted. Deprecated This option has no effect and will be removed in the next major version.
fallbackFlags?	| TypedFlagKey[] | Record<TypedFlagKey, Exclude<FlagOverride, false>>	The features to "enable" as fallbacks when the API is unavailable (optional). Can be an array of feature keys, or a record of feature keys and boolean or object values. If a record is supplied instead of array, the values of each key are either the configuration values or the boolean value true. Deprecated Use flagsFallbackProvider instead.
fetchTimeoutMs?	number	The timeout in milliseconds for fetching feature targeting data (optional). Default is 10000 ms.
flagOverrides?	| FlagOverrides | (context: Context) => FlagOverrides	Local flag overrides for testing or development. If a function is specified, the function will be called with the context and should return a record of flag keys and boolean or object values.
flagsFallbackProvider?	FlagsFallbackProvider	Optional provider used to load and save raw flag definitions for fallback startup. Ignored in offline mode.
flagsFetchRetries?	number	Number of times to retry fetching feature definitions (optional). Default is 3 times.
flagsPushUrl?	string	Push endpoint used when flagsSyncMode is "push".
flagsSyncMode?	FlagsSyncMode	How flag definitions are synchronized. push (default): live updates over SSE keep flag definitions up to date. polling: periodic background refresh. in-request: stale refresh is triggered during request handling.
host?	string	Deprecated Use apiBaseUrl instead.
httpClient?	HttpClient	The HTTP client to use for sending requests (optional). Default is the built-in fetch client.
logger?	Logger	The logger to use for logging (optional). Default is info level logging to console.
logLevel?	LogLevel	Use the console logger, but set a log level. Ineffective if a custom logger is provided.
offline?	boolean	In offline mode, no data is sent or fetched from the the Reflag API, and flagsFallbackProvider is not used. This is useful for testing or development.
secretKey?	string	The secret key used to authenticate with the Reflag API.

---

Context

type Context = {
  company: {
   [k: string]: any;   avatar: string;
     id: string | number | undefined;
     name: string;
    };
  other: Record<string, any>;
  user: {
   [k: string]: any;   avatar: string;
     email: string;
     id: string | number | undefined;
     name: string;
    };
};

Describes the current user context, company context, and other context. This is used to determine if feature targeting matches and to track events.

Type declaration

Name	Type	Description
company?	{ [k: string]: any; avatar: string; id: string | number | undefined; name: string; }	The company context. If no id key is set, the whole object is ignored.
company.avatar?	string	The avatar URL of the company.
company.id	string | number | undefined	The identifier of the company.
company.name?	string	The name of the company.
other?	Record<string, any>	The other context. This is used for any additional context that is not related to user or company.
user?	{ [k: string]: any; avatar: string; email: string; id: string | number | undefined; name: string; }	The user context. If no id key is set, the whole object is ignored.
user.avatar?	string	The avatar URL of the user.
user.email?	string	The email of the user.
user.id	string | number | undefined	The identifier of the user.
user.name?	string	The name of the user.

---

EdgeClientOptions

type EdgeClientOptions = Omit<ClientOptions, "flagsSyncMode" | "cacheStrategy" | "flushIntervalMs" | "batchOptions">;

---

EmptyFlagRemoteConfig

type EmptyFlagRemoteConfig = {
  key: undefined;
  payload: undefined;
};

Type declaration

Name	Type
key	undefined
payload	undefined

---

FileFallbackProviderOptions

type FileFallbackProviderOptions = {
  directory: string;
};

Type declaration

Name	Type	Description
directory?	string	Directory where per-environment snapshots are stored.

---

FlagAPIResponse

type FlagAPIResponse = {
  config: {
     variants: FlagConfigVariant[];
     version: number;
    };
  description: string | null;
  key: string;
  targeting: {
     rules: {
        filter: RuleFilter;
       }[];
     version: number;
    };
};

Internal

(Internal) Describes a specific feature in the API response.

Type declaration

Name	Type	Description
config?	{ variants: FlagConfigVariant[]; version: number; }	The remote configuration for the feature.
config.variants	FlagConfigVariant[]	The variants of the remote configuration.
config.version	number	The version of the remote configuration.
description	string | null	Description of the feature.
key	string	The key of the feature.
targeting	{ rules: { filter: RuleFilter; }[]; version: number; }	The targeting rules for the feature.
targeting.rules	{ filter: RuleFilter; }[]	The targeting rules.
targeting.version	number	The version of the targeting rules.

---

FlagConfigVariant

type FlagConfigVariant = {
  filter: RuleFilter;
  key: string;
  payload: any;
};

Describes a remote feature config variant.

Type declaration

Name	Type	Description
filter	RuleFilter	The filter for the variant.
key	string	The key of the variant.
payload	any	The optional user-supplied payload data.

---

FlagDefinition

type FlagDefinition = {
  config: {
     variants: FlagConfigVariant[];
     version: number;
    };
  description: string | null;
  flag: {
     rules: {
        filter: RuleFilter;
       }[];
     version: number;
    };
  key: string;
};

Describes a feature definition.

Type declaration

Name	Type	Description
config?	{ variants: FlagConfigVariant[]; version: number; }	The remote configuration for the feature.
config.variants	FlagConfigVariant[]	The variants of the remote configuration.
config.version	number	The version of the remote configuration.
description	string | null	Description of the feature.
flag	{ rules: { filter: RuleFilter; }[]; version: number; }	The targeting rules for the feature.
flag.rules	{ filter: RuleFilter; }[]	The targeting rules.
flag.version	number	The version of the targeting rules.
key	string	The key of the feature.

---

FlagOverride

type FlagOverride = 
  | FlagType & {
  config: {
     key: string;
    };
  isEnabled: boolean;
 }
  | boolean;

---

FlagOverrides

type FlagOverrides = Partial<keyof Flags extends never ? Record<string, FlagOverride> : { [FlagKey in keyof Flags]: Flags[FlagKey] extends FlagOverride ? Flags[FlagKey] : Exclude<FlagOverride, "config"> }>;

Describes the feature overrides.

---

FlagOverridesFn()

type FlagOverridesFn = (context: Context) => FlagOverrides;

Parameters

Parameter	Type
context	Context

Returns

FlagOverrides

---

FlagRemoteConfig

type FlagRemoteConfig = 
  | {
  key: string;
  payload: any;
 }
  | EmptyFlagRemoteConfig;

A remotely managed configuration value for a feature.

Type declaration

{ key: string; payload: any; }

Name	Type	Description
key	string	The key of the matched configuration value.
payload	any	The optional user-supplied payload data.

EmptyFlagRemoteConfig

---

FlagsAPIResponse

type FlagsAPIResponse = {
  features: FlagAPIResponse[];
  flagStateVersion: number;
};

Internal

(Internal) Describes the response of the features endpoint.

Type declaration

Name	Type	Description
features	FlagAPIResponse[]	The feature definitions.
flagStateVersion?	number	Optional for backward compatibility; when absent, the snapshot version should be treated as unknown by consumers.

---

FlagsFallbackProviderContext

type FlagsFallbackProviderContext = {
  secretKeyHash: string;
};

Non-secret context passed to fallback providers so they can derive storage keys without access to the raw secret key.

Type declaration

Name	Type	Description
secretKeyHash	string	Deterministic hash of the configured secret key.

---

FlagsFallbackSnapshot

type FlagsFallbackSnapshot = {
  flags: FlagAPIResponse[];
  savedAt: string;
  version: number;
};

Snapshot of flag definitions used for fallback initialization.

Type declaration

Name	Type	Description
flags	FlagAPIResponse[]	Raw flag definitions as returned by the API.
savedAt	string	ISO timestamp indicating when the snapshot was saved.
version	number	Snapshot schema version.

---

FlagsSyncMode

type FlagsSyncMode = "polling" | "in-request" | "push";

---

FlagType

type FlagType = {
  config: {
     payload: any;
    };
};

Type declaration

Name	Type
config?	{ payload: any; }
config.payload	any

---

GCSFallbackProviderClient

type GCSFallbackProviderClient = 
  | GCSLegacyClient
  | GCSGoogleApisClient;

---

GCSFallbackProviderOptions

type GCSFallbackProviderOptions = {
  bucket: string;
  client: GCSFallbackProviderClient;
  keyPrefix: string;
};

Type declaration

Name	Type	Description
bucket	string	Bucket where snapshots are stored.
client?	GCSFallbackProviderClient	Optional GCS client. A default client is created when omitted. Accepts either a legacy bucket().file() client or a generated @googleapis/storage client. TODO(next major): Replace this with a simpler object-store interface.
keyPrefix?	string	Prefix for generated per-environment keys.

---

GCSGoogleApisClient

type GCSGoogleApisClient = {
  objects: {
     get: Promise<{
        data: unknown;
       }>;
     insert: Promise<unknown>;
    };
};

Type declaration

Name	Type
objects	{ get: Promise<{ data: unknown; }>; insert: Promise<unknown>; }
get()	Promise<{ data: unknown; }>
insert()	Promise<unknown>

---

GCSLegacyClient

type GCSLegacyClient = {
  bucket: {
     file: {
        download: Promise<[Uint8Array]>;
        exists: Promise<[boolean]>;
        save: Promise<unknown>;
       };
    };
};

Type declaration

Name	Type
bucket()	{ file: { download: Promise<[Uint8Array]>; exists: Promise<[boolean]>; save: Promise<unknown>; }; }

---

HttpClientResponse<TResponse>

type HttpClientResponse<TResponse> = {
  body: TResponse | undefined;
  ok: boolean;
  status: number;
};

Describes the response of a HTTP client.

Type Parameters

Type Parameter	Description
TResponse	The type of the response body.

Type declaration

Name	Type	Description
body	TResponse | undefined	The body of the response if available.
ok	boolean	Indicates that the request succeeded.
status	number	The status code of the response.

---

IdType

type IdType = string | number;

---

LogLevel

type LogLevel = typeof LOG_LEVELS[number];

---

RawFlagRemoteConfig

type RawFlagRemoteConfig = {
  key: string;
  missingContextFields: string[];
  payload: any;
  ruleEvaluationResults: boolean[];
  targetingVersion: number;
};

A remotely managed configuration value for a feature.

Type declaration

Name	Type	Description
key	string	The key of the matched configuration value.
missingContextFields?	string[]	The missing fields in the evaluation context (optional).
payload	any	The optional user-supplied payload data.
ruleEvaluationResults?	boolean[]	The rule results of the evaluation (optional).
targetingVersion?	number	The version of the targeting rules used to select the config value.

---

RawFlags

type RawFlags = Record<TypedFlagKey, RawFlag>;

Describes a collection of evaluated raw flags.

---

RedisFallbackProviderOptions

type RedisFallbackProviderOptions = {
  client: {
     get: Promise<undefined | null | string>;
     set: Promise<unknown>;
    };
  keyPrefix: string;
};

Type declaration

Name	Type	Description
client?	{ get: Promise<undefined | null | string>; set: Promise<unknown>; }	Optional Redis client. When omitted, a client is created using REDIS_URL.
get()	Promise<undefined | null | string>	‐
set()	Promise<unknown>	‐
keyPrefix?	string	Prefix for generated per-environment keys.

---

S3FallbackProviderOptions

type S3FallbackProviderOptions = {
  bucket: string;
  client: {
     send: Promise<any>;
    };
  keyPrefix: string;
};

Type declaration

Name	Type	Description
bucket	string	Bucket where snapshots are stored.
client?	{ send: Promise<any>; }	Optional S3 client. A default client is created when omitted.
send()	Promise<any>	‐
keyPrefix?	string	Prefix for generated per-environment keys.

---

StaticFallbackProviderOptions

type StaticFallbackProviderOptions = {
  flags: Record<string, boolean>;
};

Type declaration

Name	Type	Description
flags	Record<string, boolean>	Static fallback flags keyed by flag key.

---

TrackingMeta

type TrackingMeta = {
  active: boolean;
};

Describes the meta context associated with tracking.

Type declaration

Name	Type	Description
active?	boolean	Whether the user or company is active.

---

TrackOptions

type TrackOptions = {
  attributes: Attributes;
  meta: TrackingMeta;
};

Defines the options for tracking of entities.

Type declaration

Name	Type	Description
attributes?	Attributes	The attributes associated with the event.
meta?	TrackingMeta	The meta context associated with the event.

---

TypedFlagKey

type TypedFlagKey = keyof TypedFlags;

---

TypedFlags

type TypedFlags = keyof Flags extends never ? Record<string, Flag> : { [FlagKey in keyof Flags]: Flags[FlagKey] extends FlagType ? Flag<Flags[FlagKey]["config"]> : Flag };

Describes a collection of evaluated feature.

Remarks

This types falls back to a generic Record<string, Flag> if the Flags interface has not been extended.

Variables

fallbackProviders

const fallbackProviders: {
  file: (__namedParameters: FileFallbackProviderOptions) => FlagsFallbackProvider;
  gcs: (__namedParameters: GCSFallbackProviderOptions) => FlagsFallbackProvider;
  redis: (__namedParameters: RedisFallbackProviderOptions) => FlagsFallbackProvider;
  s3: (__namedParameters: S3FallbackProviderOptions) => FlagsFallbackProvider;
  static: (__namedParameters: StaticFallbackProviderOptions) => FlagsFallbackProvider;
};

Type declaration

Name	Type	Default value
file	(__namedParameters: FileFallbackProviderOptions) => FlagsFallbackProvider	createFileFallbackProvider
gcs	(__namedParameters: GCSFallbackProviderOptions) => FlagsFallbackProvider	createGCSFallbackProvider
redis	(__namedParameters: RedisFallbackProviderOptions) => FlagsFallbackProvider	createRedisFallbackProvider
s3	(__namedParameters: S3FallbackProviderOptions) => FlagsFallbackProvider	createS3FallbackProvider
static	(__namedParameters: StaticFallbackProviderOptions) => FlagsFallbackProvider	createStaticFallbackProvider

---

LOG_LEVELS

const LOG_LEVELS: readonly ["DEBUG", "INFO", "WARN", "ERROR"];