RFC: Feature Flags utility with AppConfig multi-variant support

[dreamorosi]

Is this related to an existing feature request or issue?

#3754

Which area does this RFC relate to?

New Feature: Feature Flags

Summary

A Feature Flags utility for Powertools for AWS Lambda (TypeScript) that covers both what Powertools for Python ships today (a local rule engine over a freeform JSON document) and AWS AppConfig multi-variant flags, which are evaluated by AppConfig itself through the AppConfig Agent. One FeatureFlags API sits over both. It reuses the Parameters utility for retrieval where a Parameters provider exists, including the AppConfig Agent support added in v2.35.0 (#5399).

This RFC is the output of a design session. The decisions below are proposals, and the questions at the end are the ones we could not settle without wider input.

Use case

Two groups asked for this in #3754 and they want different things:

• Teams running Python and TypeScript functions side by side want the Python Feature Flags experience, reading the same AppConfig freeform document from both runtimes.
• Teams using AppConfig multi-variant flags want to pass an evaluation context (user id, tier, opted-in) and receive the variant AppConfig selects, without hand-writing HTTP calls to the Agent.

Both want a default that is honoured when the store is unreachable, and neither wants undefined checks sprinkled through handler code.

Proposal

Language

Terms used throughout, with the words we avoid so the docs and code stay consistent:

Term	Meaning	Avoid
Feature Flag	A named setting whose value can vary per request. A JSON value, not only a boolean.	toggle, switch, config key
Evaluation Context	Per-request facts supplied by the caller. Values are string, number, boolean, or flat arrays of those; never nested objects. Never read from the environment or event automatically.	attributes, payload, request context
Store	The source that answers "what is flag X worth for context Y". May evaluate rules itself or hand a document to the local rule engine.	provider (belongs to Parameters), backend, client
Flag Document	A JSON document in the Powertools for Python shape, read by the local rule engine.	schema, config, configuration profile
Flag Default	The value a flag takes when no Rule matches. Lives in the Flag Document.	default value, base value
Rule	A named group of Conditions plus the value when all match. Document order; first match wins.	policy, target, segment
Condition	One test: an Action applied to a context key and a document value. A missing key never satisfies a Condition.	predicate, matcher, criterion
Action	The comparison a Condition performs, named exactly as Python names it.	operator, comparator
Variant	The resolved form of a multi-variant flag: enabled, variant name, attributes. Produced only by AppConfig.	flag data, response, treatment
Attribute	A named value carried by a Variant.	property, field, payload
Fallback	The value passed to evaluate as default, returned only when the Store cannot answer or the flag does not exist. Distinct from Flag Default.	default (reserved for Flag Default)

API

import { FeatureFlags } from '@aws-lambda-powertools/feature-flags';
import { AppConfigStore } from '@aws-lambda-powertools/feature-flags/appconfig';

const flags = new FeatureFlags({
  store: new AppConfigStore({ application: 'my-app', environment: 'prod', name: 'features' }),
});

export const handler = async (event) => {
  const context = { tier: event.tier, tenantId: event.tenantId };

  // One flag; return type inferred from `default`, never undefined
  const checkoutV2 = await flags.evaluate({ name: 'checkout_v2', context, default: false });

  // Several flags in one round-trip; per-flag fallback
  const { banner, limit } = await flags.evaluateMany({
    flags: { banner: 'none', limit: 10 },
    context,
  });

  // Names of every enabled flag for this context
  const enabled = await flags.getEnabledFeatures({ context });
};

Result contract, shared by every Store:

• evaluate never returns undefined. Retrieval failure and "flag not found" return the Fallback. Misconfiguration throws: malformed Flag Document, access denied, incompatible operand types in a Condition, unparseable Agent response.
• evaluateMany applies that per flag. If the transport itself fails, every requested flag gets its Fallback and one warning is logged. Misconfiguration throws for the batch.
• getEnabledFeatures returns string[]; on a store failure it returns [].

Two kinds of Store, one evaluator

The Store owns evaluation. This inverts Python, where the store is a dumb document source and FeatureFlags runs the rules. The inversion is what lets one API cover both cases:

1. Local rule engine (RuleEngineStore): takes a source: () => Promise<JSONValue> that returns a Flag Document, validates it once per document version, evaluates Rules in-process. Any Parameters provider, S3, or a plain function can be the source.
2. Agent multi-variant store: sends the Evaluation Context as Context: key=value headers to the AppConfig Agent, which selects the Variant. evaluate requests ?flag=<name>; evaluateMany repeats ?flag=; getEnabledFeatures fetches the whole profile. Requires Agent 2.0.45 or later. No cache of ours; the Agent is the cache.

Built-in stores under @aws-lambda-powertools/feature-flags/appconfig, mirroring Parameters naming: one over AppConfigProvider (SDK, freeform documents), one over getConfig (Agent, freeform documents), and the Agent multi-variant store. All accept the same awsSdkV3Client/clientConfig passthrough that Parameters accepts, plus envelope (JMESPath) for documents embedded in a larger configuration.

Flag Document: Python's schema, verbatim

The local rule engine reads exactly the document Powertools for Python defines: default, boolean_type, rules keyed by name, when_match, conditions with action/key/value, the same Action vocabulary including the IN/KEY_IN_VALUE alias pairs, all three time Actions with IANA TIMEZONE, MODULO_RANGE, and first-match rule order by object key order.

We considered a TypeScript-native shape (array of rules, explicit priority). The only quirk it fixes that matters is implicit rule ordering, and that is not worth losing cross-language documents. Deferred, not rejected.

Conforming on shape does not mean copying every behaviour. Where Python's evaluation is a footgun rather than a design choice, we pick the defensible semantics, document the divergence, and open an issue on Powertools for Python proposing the same change for its next major. Proposed divergences:

Behaviour	Python today	Proposed here
Missing context key	Becomes None; NOT_EQUALS and negative membership Actions match	Never satisfies any Condition
Incompatible operand types (STARTSWITH on a number)	Exception swallowed, Condition is false; validation_exception_handler can intercept	Throws a misconfiguration error naming flag, rule, key. Handler hook not ported
Time range crossing midnight	Compares hours only; 23:30 to 23:00 never matches	Compares full HH:MM
HH:MM validation	Unanchored regex	Anchored
boolean_type	Required semantics, absent means boolean	Optional; inferred from default when absent (agrees with Python for boolean defaults)
Validation	Whole document on every evaluate	Once per fetched document version
Documents Python accepts but are odd (rules: [], empty top level)	Accepted silently	Accepted with a warning; throw only where Python also throws

Multi-variant: the Variant type

The Agent returns { "_variant": "QA", "enabled": true, "dark_mode_support": true } per flag. The Agent store returns it as a Variant:

type Variant = {
  enabled: boolean;
  variant: string;
  attributes: Record<string, string | number | boolean | Array<string | number | boolean>>;
};

always, even when the flag has no attributes. On that store the Fallback must itself be a Variant. We rejected: returning enabled alone (discards the attributes that justify multi-variant), returning the raw object (always truthy, so if (await evaluate(...)) silently breaks, and _variant leaks wire format), and unwrapping to a boolean when there are no attributes (return type would change when someone adds an attribute in the console, with no code change).

Because Context: headers cannot carry arrays, the Agent store throws, naming the key, if an Evaluation Context value is an array. The local store supports array values for ALL_IN_VALUE/ANY_IN_VALUE/NONE_IN_VALUE, as Python does.

Package boundary

@aws-lambda-powertools/feature-flags is a new package. The core sub-path (evaluator, Store interface, local rule engine) depends only on commons. Stores that wrap Parameters live under /appconfig and import @aws-lambda-powertools/parameters (and @aws-lambda-powertools/jmespath for envelopes) as optional peers, the same pattern Parameters uses for AWS SDK clients. An Agent-only or custom-store user never pulls the AppConfigData SDK client into the bundle, which was the first concern raised in #3754.

Time and clock

All three time Actions ship in v1 using Intl.DateTimeFormat for IANA zones, no new dependency. The local store accepts an optional now: () => Date for tests; documents cannot override the clock, matching Python.

Logging

Evaluation Context values are never logged at any level; key names only. With a logger supplied: debug lines for flag name, matched Rule or Flag Default, store, and Variant name; one warning per evaluate/evaluateMany that returned a Fallback. No metrics or traces. No logger means no output (no console fallback).

Phasing

1. This RFC, plus upstream Python issues for each divergence above.
2. Core package and local store with a conformance suite ported from Python's functional tests.
3. Parameters-backed stores (SDK and Agent, freeform), envelope, docs, layer bundling.
4. Multi-variant Agent store, evaluateMany batching, e2e against a real multi-variant profile. Closes Feature request: Add support for multi-variant AWS AppConfig feature flags #3754.

Multi-variant is last even though it is the original ask: it is the only part with no Python reference and gains most from RFC feedback, and the local store is the harder half and should pressure-test the API first.

Out of scope

• A TypeScript-native Flag Document shape (explicit rule ordering).
• Custom Actions or comparators (would make documents unreadable by Python).
• Python's validation_exception_handler.
• Metrics or tracing per evaluation.
• Function-style getFeatureFlag() with a hidden default store (would need three new env vars).
• A cache in front of the AppConfig Agent.

Potential challenges

• Keeping the divergence list honest across releases; each entry needs a linked Python issue.
• Fallbacks on the Agent store being verbose ({ enabled: false, variant: 'default', attributes: {} }). A disabledVariant() helper is a likely mitigation.
• Confirming the Agent returns 404 rather than {} for an unknown ?flag= key; our "missing flag" detection depends on it.
• Traffic splitting: MODULO_RANGE in a Flag Document and AppConfig's own split hashing bucket users differently. Documentation only.

Dependencies and Integrations

• @aws-lambda-powertools/commons (hard).
• @aws-lambda-powertools/parameters v2.35.0+ (optional peer): AppConfigProvider, getConfig.
• @aws-lambda-powertools/jmespath (optional peer): envelopes.
• AWS AppConfig Agent Lambda extension 2.0.45+ for multi-variant and per-flag retrieval.

Alternative solutions

• Local rule engine only (strict Python parity). Excludes multi-variant, the original ask.
• Thin wrapper over the Agent only. Excludes users without the Agent layer and every non-AppConfig store.
• Feature Flags as a sub-path of parameters. Muddles a retrieval library with a rule engine; Python's clean split comes partly from the package boundary.
• evaluateAll() returning every flag's value. No per-flag Fallback is possible, so it reintroduces undefined; replaced by evaluateMany with explicit Fallbacks.

Open questions for reviewers

1. Exact Store interface. Sketch: get(name, context): Promise<{ value, enabled } | { missing: true }> and getAll(context).
2. Should evaluateMany on the local store validate only the named flags, or the whole document?
3. Is a Variant Fallback acceptable, or do you want default: false to mean "disabled Variant" on Agent stores?
4. Any divergence in the table you would rather we copy from Python as-is?

Acknowledgment

• This RFC meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.