Class FlagshipBinding<E>

Accessor for a Flagship feature-flag binding.

Remarks

Flagship evaluates a flag at request time, so a value that is a vars entry today — read once per deploy, changed only by deploying again — becomes something a targeting rule can move for a percentage of traffic, or for named callers first. That is the whole reason to reach for it: a rollback stops being a deploy.

This one degrades instead of throwing, and that is the point

Every other accessor here answers a missing binding with a MissingBindingError, because a Worker that lost its database cannot serve the request either way and should say so. A flag is the opposite. The value exists to decide between two paths that both work, so a Worker that cannot reach Flagship should take the path it would have taken before flags existed — not fail.

So every method here takes a fallback and returns it when the binding is absent, when evaluation fails, or when the flag's type does not match. An evaluation error is logged and swallowed, the way AnalyticsBinding's writeSafe treats a failed telemetry write: the caller asked a question that has a safe answer, and raising instead would make the flag service a new way for the Worker to be down.

The corollary is that the fallback is not boilerplate. It is the deployed behaviour, and choosing it badly is how a flag outage becomes an incident — so pass the value the Worker used before the flag existed, which for the migration this package was written for means the vars entry it replaces.

resolve(env) is still inherited and still throws, for the rare caller that genuinely cannot proceed without a live evaluation.

Why there is no `FlagshipService`

Same reason as WorkflowBinding: the kernel names no capability this could implement. Unlike durable execution, feature flagging is the strongest candidate in this package for one — it has many providers, and none of its vocabulary is Cloudflare's. When a second provider is actually in play, a FeatureFlags interface belongs in @bayudwiyansatria/core and this becomes its adapter. Declaring it now, against one implementation and no consumers, would be ceremony rather than abstraction.

Example

const flags = new FlagshipBinding()

// env.RELEASE_CHANNEL is the deployed value and the fallback if Flagship is unreachable.
const channel = await flags.string(env, 'release-channel', env.RELEASE_CHANNEL ?? 'stable')

// Per-request attributes for a targeting rule.
const enabled = await flags.boolean(env, 'new-checkout', false, { cohort })

Author

Bayu Dwiyan Satria

Version

1.0.0

Since

1.3.0

Type Parameters

E extends CloudflareEnv = CloudflareEnv

Hierarchy (View Summary)

Binding<Flagship, E>
- FlagshipBinding

Index

Constructors

constructor

new FlagshipBinding<E extends CloudflareEnv = CloudflareEnv>(
settings?: FlagshipSettings,
): FlagshipBinding<E>
Constructs a FlagshipBinding instance.
Type Parameters
- E extends CloudflareEnv = CloudflareEnv
Parameters
- Optionalsettings: FlagshipSettings
  Resolved settings. Defaults to resolve('flagship'), so callers normally construct this with no arguments at all.
Returns FlagshipBinding<E>
Overrides Binding.constructor
- Defined in src/core/bindings/FlagshipBinding.ts:87

Properties

`Private` `Readonly`settings

settings: () => FlagshipSettings

This accessor's settings, resolved on first read.

Accessors

name

get name(): string
The binding name this instance resolves.

Returns string
The binding name as declared in wrangler.json.
Inherited from Binding.name
- Defined in src/core/bindings/Binding.ts:58

Methods

boolean

boolean(
    env: E,
    key: string,
    fallback: boolean,
    context?: FlagshipEvaluationContext,
): Promise<boolean>
Evaluates a boolean flag.
Parameters
- env: E
  The Worker environment.
- key: string
  The flag key, as it is named in the Flagship app.
- fallback: boolean
  The value to use when the flag cannot be evaluated. Pass the deployed behaviour.
- Optionalcontext: FlagshipEvaluationContext
  Per-request attributes for targeting, merged over the configured context.
Returns Promise<boolean>
The evaluated value, or fallback.
- Defined in src/core/bindings/FlagshipBinding.ts:104

`Private`context

context(context?: FlagshipEvaluationContext): FlagshipEvaluationContext
Merges a call's evaluation context over the configured one.
Parameters
- Optionalcontext: FlagshipEvaluationContext
  Per-request attributes, if the caller supplied any.
Returns FlagshipEvaluationContext
The combined context, or undefined when neither side has one.

Remarks
The call wins on any key both name. The configured context describes the deployment and the call describes the request, so the more specific of the two is the one that arrived last.
- Defined in src/core/bindings/FlagshipBinding.ts:211

`Private`evaluate

evaluate<T>(
    env: E,
    fallback: T,
    evaluate: (flags: Flagship) => Promise<T>,
): Promise<T>
Runs an evaluation, answering with the fallback rather than raising.
Type Parameters
- T
  The flag's value type.
Parameters
- env: E
  The Worker environment.
- fallback: T
  The value to answer with when evaluation cannot happen.
- evaluate: (flags: Flagship) => Promise<T>
  The evaluation to attempt against the resolved binding.
Returns Promise<T>
The evaluated value, or fallback.
- Defined in src/core/bindings/FlagshipBinding.ts:184

isAvailable

isAvailable(env: E): boolean
Reports whether this deployment can evaluate flags at all.
Parameters
- env: E
  The Worker environment.
Returns boolean
true when the binding is present.

Remarks
Rarely needed, since every method above already answers with its fallback. It is here for the one caller that wants to say so out loud — a health endpoint reporting degraded flag evaluation, or a log line explaining why every flag read the deployed value.
- Defined in src/core/bindings/FlagshipBinding.ts:170

isBound

isBound(env: E): boolean
Checks whether the binding is available on the given environment.

Use this to degrade gracefully when a binding is optional.
Parameters
- env: E
  The Worker environment.
Returns boolean
true when the binding is present.
Inherited from Binding.isBound
- Defined in src/core/bindings/Binding.ts:74

number

number(
    env: E,
    key: string,
    fallback: number,
    context?: FlagshipEvaluationContext,
): Promise<number>
Evaluates a numeric flag.
Parameters
- env: E
  The Worker environment.
- key: string
  The flag key, as it is named in the Flagship app.
- fallback: number
  The value to use when the flag cannot be evaluated. Pass the deployed behaviour.
- Optionalcontext: FlagshipEvaluationContext
  Per-request attributes for targeting, merged over the configured context.
Returns Promise<number>
The evaluated value, or fallback.
- Defined in src/core/bindings/FlagshipBinding.ts:134

object

object<T extends object>(
    env: E,
    key: string,
    fallback: T,
    context?: FlagshipEvaluationContext,
): Promise<T>
Evaluates a structured flag.
Type Parameters
- T extends object
  The shape the flag carries.
Parameters
- env: E
  The Worker environment.
- key: string
  The flag key, as it is named in the Flagship app.
- fallback: T
  The value to use when the flag cannot be evaluated. Pass the deployed behaviour.
- Optionalcontext: FlagshipEvaluationContext
  Per-request attributes for targeting, merged over the configured context.
Returns Promise<T>
The evaluated value, or fallback.
- Defined in src/core/bindings/FlagshipBinding.ts:149

resolve

resolve(env: E): Flagship
Resolves the binding, failing fast when it is not configured.
Parameters
- env: E
  The Worker environment.
Returns Flagship
The resolved binding.

Throws
MissingBindingError When the binding is absent from the environment.
Inherited from Binding.resolve
- Defined in src/core/bindings/Binding.ts:85

string

string(
    env: E,
    key: string,
    fallback: string,
    context?: FlagshipEvaluationContext,
): Promise<string>
Evaluates a string flag.
Parameters
- env: E
  The Worker environment.
- key: string
  The flag key, as it is named in the Flagship app.
- fallback: string
  The value to use when the flag cannot be evaluated. Pass the deployed behaviour.
- Optionalcontext: FlagshipEvaluationContext
  Per-request attributes for targeting, merged over the configured context.
Returns Promise<string>
The evaluated value, or fallback.

Remarks
Useful for named modes, where the deployed fallback is a string rather than a boolean.
- Defined in src/core/bindings/FlagshipBinding.ts:121

tryResolve

tryResolve(env: E): Flagship
Resolves the binding without throwing.
Parameters
- env: E
  The Worker environment.
Returns Flagship
The resolved binding, or null when it is not configured.
Inherited from Binding.tryResolve
- Defined in src/core/bindings/Binding.ts:101

Class FlagshipBinding<E>

Remarks

This one degrades instead of throwing, and that is the point

Why there is no FlagshipService

Example

Author

Version

Since

Type Parameters

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns FlagshipBinding<E>

Properties

Private Readonlysettings

Accessors

name

Returns string

Methods

boolean

Parameters

Returns Promise<boolean>

Privatecontext

Parameters

Returns FlagshipEvaluationContext

Remarks

Privateevaluate

Type Parameters

Parameters

Returns Promise<T>

isAvailable

Parameters

Returns boolean

Remarks

isBound

Parameters

Returns boolean

number

Parameters

Returns Promise<number>

object

Type Parameters

Parameters

Returns Promise<T>

resolve

Parameters

Returns Flagship

Throws

string

Parameters

Returns Promise<string>

Remarks

tryResolve

Parameters

Returns Flagship

Settings

On This Page

Why there is no `FlagshipService`

`Private` `Readonly`settings

`Private`context

`Private`evaluate