Methods

The Flagship binding provides the following methods for evaluating feature flags. All methods are asynchronous and return a Promise. For known evaluation failures, typed methods return the defaultValue you provide.

Refer to the types reference for the definitions of FlagshipEvaluationContext and FlagshipEvaluationDetails.

get()

Returns the raw flag value without type checking. Use this method when the flag type is not known at compile time.

If you provide defaultValue, get() returns that value for known evaluation failures, such as a missing flag. If you omit defaultValue, known evaluation failures are thrown.

TypeScript

get(flagKey: string, defaultValue?: unknown, context?: FlagshipEvaluationContext): Promise<unknown>

Parameter	Type	Required	Description
flagKey	string	Yes	The key of the flag to evaluate.
defaultValue	unknown	No	The fallback value returned if evaluation fails or the flag is not found.
context	FlagshipEvaluationContext	No	Key-value attributes for targeting rules.

TypeScript

const value = await env.FLAGS.get("checkout-flow", "v1", {
  userId: "user-42",
});

getBooleanValue()

Returns the flag value as a boolean.

TypeScript

getBooleanValue(flagKey: string, defaultValue: boolean, context?: FlagshipEvaluationContext): Promise<boolean>

Parameter	Type	Required	Description
flagKey	string	Yes	The key of the flag to evaluate.
defaultValue	boolean	Yes	The fallback value returned if evaluation fails or the flag is not found.
context	FlagshipEvaluationContext	No	Key-value attributes for targeting rules.

TypeScript

const enabled = await env.FLAGS.getBooleanValue("dark-mode", false, {
  userId: "user-42",
});

getStringValue()

Returns the flag value as a string.

TypeScript

getStringValue(flagKey: string, defaultValue: string, context?: FlagshipEvaluationContext): Promise<string>

Parameter	Type	Required	Description
flagKey	string	Yes	The key of the flag to evaluate.
defaultValue	string	Yes	The fallback value returned if evaluation fails or the flag is not found.
context	FlagshipEvaluationContext	No	Key-value attributes for targeting rules.

TypeScript

const variant = await env.FLAGS.getStringValue("checkout-flow", "v1", {
  userId: "user-42",
  country: "US",
});

getNumberValue()

Returns the flag value as a number.

TypeScript

getNumberValue(flagKey: string, defaultValue: number, context?: FlagshipEvaluationContext): Promise<number>

Parameter	Type	Required	Description
flagKey	string	Yes	The key of the flag to evaluate.
defaultValue	number	Yes	The fallback value returned if evaluation fails or the flag is not found.
context	FlagshipEvaluationContext	No	Key-value attributes for targeting rules.

TypeScript

const maxRetries = await env.FLAGS.getNumberValue("max-retries", 3, {
  plan: "enterprise",
});

getObjectValue()

Returns the flag value as a typed object. Use the generic parameter T to specify the expected shape.

TypeScript

getObjectValue<T extends object>(flagKey: string, defaultValue: T, context?: FlagshipEvaluationContext): Promise<T>

Parameter	Type	Required	Description
flagKey	string	Yes	The key of the flag to evaluate.
defaultValue	T	Yes	The fallback value returned if evaluation fails or the flag is not found.
context	FlagshipEvaluationContext	No	Key-value attributes for targeting rules.

TypeScript

interface ThemeConfig {
  primaryColor: string;
  fontSize: number;
}

const theme = await env.FLAGS.getObjectValue<ThemeConfig>(
  "theme-config",
  { primaryColor: "#000", fontSize: 14 },
  { userId: "user-42" },
);

getBooleanDetails()

Returns the flag value as a boolean with evaluation metadata.

TypeScript

getBooleanDetails(flagKey: string, defaultValue: boolean, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<boolean>>

Parameter	Type	Required	Description
flagKey	string	Yes	The key of the flag to evaluate.
defaultValue	boolean	Yes	The fallback value returned if evaluation fails or the flag is not found.
context	FlagshipEvaluationContext	No	Key-value attributes for targeting rules.

TypeScript

const details = await env.FLAGS.getBooleanDetails("dark-mode", false, {
  userId: "user-42",
});
console.log(details.value); // true
console.log(details.reason); // "TARGETING_MATCH"

getStringDetails()

Returns the flag value as a string with evaluation metadata.

TypeScript

getStringDetails(flagKey: string, defaultValue: string, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<string>>

Parameter	Type	Required	Description
flagKey	string	Yes	The key of the flag to evaluate.
defaultValue	string	Yes	The fallback value returned if evaluation fails or the flag is not found.
context	FlagshipEvaluationContext	No	Key-value attributes for targeting rules.

TypeScript

const details = await env.FLAGS.getStringDetails("checkout-flow", "v1", {
  userId: "user-42",
});
console.log(details.value); // "v2"
console.log(details.variant); // "new"
console.log(details.reason); // "TARGETING_MATCH"

getNumberDetails()

Returns the flag value as a number with evaluation metadata.

TypeScript

getNumberDetails(flagKey: string, defaultValue: number, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<number>>

Parameter	Type	Required	Description
flagKey	string	Yes	The key of the flag to evaluate.
defaultValue	number	Yes	The fallback value returned if evaluation fails or the flag is not found.
context	FlagshipEvaluationContext	No	Key-value attributes for targeting rules.

TypeScript

const details = await env.FLAGS.getNumberDetails("max-retries", 3, {
  plan: "enterprise",
});
console.log(details.value); // 5
console.log(details.reason); // "TARGETING_MATCH"

getObjectDetails()

Returns the flag value as a typed object with evaluation metadata. Use the generic parameter T to specify the expected shape.

TypeScript

getObjectDetails<T extends object>(flagKey: string, defaultValue: T, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<T>>

Parameter	Type	Required	Description
flagKey	string	Yes	The key of the flag to evaluate.
defaultValue	T	Yes	The fallback value returned if evaluation fails or the flag is not found.
context	FlagshipEvaluationContext	No	Key-value attributes for targeting rules.

TypeScript

interface ThemeConfig {
  primaryColor: string;
  fontSize: number;
}

const details = await env.FLAGS.getObjectDetails<ThemeConfig>(
  "theme-config",
  { primaryColor: "#000", fontSize: 14 },
  { userId: "user-42" },
);
console.log(details.value); // { primaryColor: "#0051FF", fontSize: 16 }
console.log(details.variant); // "brand-refresh"

Error handling

Typed evaluation methods return the defaultValue you provided for known evaluation failures, such as a missing flag or type mismatch. Unexpected runtime failures can still throw. Use the *Details methods to inspect known evaluation failures.

Type mismatch

If you call a typed method on a flag with a different type (for example, getBooleanValue on a string flag), the method returns the default value. The *Details methods set errorCode to "TYPE_MISMATCH".

TypeScript

// Flag "checkout-flow" is a string flag, but you call getBooleanDetails.
const details = await env.FLAGS.getBooleanDetails("checkout-flow", false);
console.log(details.value); // false (the default value)
console.log(details.errorCode); // "TYPE_MISMATCH"

Evaluation failure

If evaluation fails for another reason, the method returns the default value. The *Details methods include an errorCode such as "FLAG_NOT_FOUND", "INVALID_CONTEXT", "PARSE_ERROR", or "GENERAL".

TypeScript

const details = await env.FLAGS.getStringDetails(
  "nonexistent-flag",
  "fallback",
);
console.log(details.value); // "fallback"
console.log(details.errorCode); // "FLAG_NOT_FOUND"

Parameters reference

The following table summarizes the parameters shared across all evaluation methods.

Parameter	Type	Required	Description
flagKey	string	Yes	The key of the flag to evaluate.
defaultValue	varies	Yes (except get)	The fallback value returned if evaluation fails or the flag is not found.
context	FlagshipEvaluationContext	No	Key-value attributes for targeting rules (for example, { userId: "user-42", country: "US" }).