API reference

featureFlags(options) creates a Layeron Feature Flags module for code-defined flags, rollout rules, publishing, rollback, and evaluation.

Import

import { featureFlags } from "@layeron/modules"

featureFlags

Create a Layeron Feature Flags module from code-defined flags.

featureFlags(options: FeatureFlagsModuleOptions): FeatureFlagsModule

FeatureFlagsProductRef

Reference to a Layeron product instance used by Feature Flags.

Field	Type	Description
productName	string	Layeron product name for the referenced instance.
namespace	string	Platform namespace for the instance. Defaults to default.
name	string	Stable name of the referenced product instance.

FeatureFlagsModuleOptions

Options accepted by featureFlags(options).

Field	Type	Description
name	string	Stable Feature Flags instance name.
namespace	string | undefined	Platform namespace for the instance. Defaults to default.
flags	Record<Layeron.Modules.FeatureFlags.FeatureFlag>	Code-defined flags keyed by flag key.
policy	Layeron.Modules.Policy.PolicyModule | undefined	Policy module used to authorize Feature Flags operations.
audit	boolean | undefined	Whether Feature Flags records audit history for publish and rollback operations. Defaults to true.
observability	Layeron.Observability.ObservabilityConfig | undefined	Observability settings for evaluations, publishes, history reads, and rollbacks.

FeatureFlag

Code-defined flag definition.

Field	Type	Description
key	string	Stable flag key used for evaluation.
type	”boolean” | “string” | “number” | “json” | “variant”	Value type returned by the flag.
default	unknown	Fallback value returned when no rule or environment override matches.
environments	Record<unknown> | undefined	Environment-specific override values keyed by environment name.
rules	FeatureFlagRule[] | undefined	Ordered targeting rules evaluated before the default value.

FeatureFlagRule

Targeting rule for one feature flag.

Field	Type	Description
id	string | undefined	Optional stable rule id returned when this rule matches.
kind	”tenant” | “user” | “attribute” | “percentage”	Targeting strategy used by the rule.
value	unknown	Flag value returned when the rule matches.
tenants	string[] | undefined	Tenant ids matched by a tenant rule.
users	string[] | undefined	User ids matched by a user rule.
attribute	string | undefined	Attribute name read from evaluation attributes.
operator	”equals” | undefined	Attribute comparison operator. The current operator is equals.
expected	unknown | undefined	Expected attribute value for an attribute rule.
percentage	int32 | undefined	Percentage rollout from 0 to 100 for a percentage rule.
stickiness	string | undefined	Evaluation context field used to keep percentage rollout assignment stable.

FeatureFlagsBackingConfig

Backing product references used by the Feature Flags runtime.

Field	Type	Description
policy	FeatureFlagsProductRef | undefined	Policy product reference used for Feature Flags authorization.

FeatureFlagsConfig

Normalized Feature Flags module configuration.

Field	Type	Description
kind	”feature_flags”	Module configuration discriminator for Feature Flags.
name	string	Stable Feature Flags instance name.
namespace	string	Platform namespace for the instance. Defaults to default.
flags	FeatureFlag[]	Normalized flag definitions compiled from code.
backing	FeatureFlagsBackingConfig	Backing product references used by the Feature Flags runtime.
audit	boolean	Whether Feature Flags records audit history for publish and rollback operations.
snapshot	FeatureFlagsSnapshot	Current code-defined Feature Flags snapshot.
observability	Layeron.Observability.ObservabilityConfig | undefined	Observability settings recorded with the Feature Flags product configuration.

FeatureFlagsSnapshot

Immutable Feature Flags snapshot that can be published, read, or rolled back.

Field	Type	Description
version	”0.1”	Snapshot schema version.
namespace	string	Platform namespace for the instance. Defaults to default.
name	string	Stable Feature Flags instance name.
flags	FeatureFlag[]	Flag definitions contained in the snapshot.
checksum	string	Stable checksum of the snapshot content.

FeatureFlagsEvaluateInput

Input accepted by Feature Flags evaluation.

Field	Type	Description
key	string	Flag key to evaluate.
environment	string | undefined	Environment name used for environment overrides and published snapshots.
tenantId	string | undefined	Tenant id used by tenant rules, percentage stickiness, and Policy context.
userId	string | undefined	User id used by user rules, percentage stickiness, and Policy subject derivation.
sessionId	string | undefined	Session id used by percentage stickiness when selected.
attributes	Record<unknown> | undefined	Structured attributes used by attribute rules and Policy context.
subject	Layeron.Modules.Policy.PolicySubject | undefined	Explicit Policy subject for authorized Feature Flags operations.
default	unknown | undefined	Fallback value returned when the flag key is missing.

FeatureFlagsEvaluateResult

Result returned after evaluating a feature flag.

Field	Type	Description
key	string	Flag key that was evaluated.
value	unknown	Selected flag value.
type	”boolean” | “string” | “number” | “json” | “variant”	Value type of the selected flag.
reason	”environment” | “tenant” | “user” | “attribute” | “percentage” | “default” | “fallback”	Reason that selected the returned value.
ruleId	string | undefined	Rule id that matched, when a targeting rule selected the value.
version	string	Snapshot schema version used for the evaluation.
checksum	string	Snapshot checksum used for the evaluation.

FeatureFlagsPublishInput

Input accepted when publishing the current code-defined snapshot.

Field	Type	Description
environment	string | undefined	Environment name that receives the published snapshot.
message	string | undefined	Human-readable publish message stored in history.
subject	Layeron.Modules.Policy.PolicySubject | undefined	Policy subject used to authorize the publish operation.

FeatureFlagsPublishResult

Result returned after publishing a Feature Flags snapshot.

Field	Type	Description
namespace	string	Platform namespace for the instance. Defaults to default.
name	string	Stable Feature Flags instance name.
version	string	Published snapshot schema version.
checksum	string	Published snapshot checksum.
publishedAt	string	ISO timestamp when the snapshot was published.
environment	string | undefined	Environment name that received the published snapshot.

FeatureFlagsReadInput

Input accepted when reading the active Feature Flags snapshot.

Field	Type	Description
environment	string | undefined	Environment name used to read a published snapshot.
subject	Layeron.Modules.Policy.PolicySubject | undefined	Policy subject used to authorize the read operation.

FeatureFlagsReadResult

Result returned after reading the active Feature Flags snapshot.

Field	Type	Description
namespace	string	Platform namespace for the instance. Defaults to default.
name	string	Stable Feature Flags instance name.
environment	string | undefined	Environment name used for the read.
source	”code” | “published”	Source of the returned snapshot.
snapshot	FeatureFlagsSnapshot	Returned Feature Flags snapshot.
publishedAt	string | undefined	ISO timestamp when the returned snapshot was published.
message	string | undefined	Publish or rollback message associated with the returned snapshot.

FeatureFlagsHistoryInput

Input accepted when reading Feature Flags publish history.

Field	Type	Description
environment	string | undefined	Environment name used to filter history entries.
limit	int32 | undefined	Maximum history entries to return. The runtime caps this value at 100.
subject	Layeron.Modules.Policy.PolicySubject | undefined	Policy subject used to authorize the history read.

FeatureFlagsHistoryEntry

One Feature Flags publish or rollback history entry.

Field	Type	Description
action	”publish” | “rollback”	History action recorded for the snapshot.
environment	string | undefined	Environment name associated with the history entry.
message	string | undefined	Human-readable message stored with the history entry.
version	string	Snapshot schema version recorded in the history entry.
checksum	string	Snapshot checksum recorded in the history entry.
publishedAt	string	ISO timestamp when the history entry was created.

FeatureFlagsHistoryResult

Result returned after reading Feature Flags history.

Field	Type	Description
items	FeatureFlagsHistoryEntry[]	History entries ordered from newest to oldest.
cursor	string | undefined	Pagination cursor reserved for future history pagination.

FeatureFlagsRollbackInput

Input accepted when rolling back to a published Feature Flags snapshot.

Field	Type	Description
checksum	string	Snapshot checksum to restore.
environment	string | undefined	Environment name to roll back.
message	string | undefined	Human-readable rollback message stored in history.
subject	Layeron.Modules.Policy.PolicySubject | undefined	Policy subject used to authorize the rollback operation.

FeatureFlagsRollbackResult

Result returned after rolling back a Feature Flags snapshot.

Field	Type	Description
rolledBackToChecksum	string	Snapshot checksum restored by the rollback.
rolledBackFromChecksum	string | undefined	Snapshot checksum replaced by the rollback when a previous published snapshot existed.

FeatureFlagsModule

Layeron Feature Flags module returned by featureFlags(options).

Field	Type	Description
name	”feature_flags”	Module name.
config	FeatureFlagsConfig	Normalized Feature Flags module configuration.
observability	Layeron.Observability.ObservabilityConfig | undefined	Effective observability policy recorded on the module declaration.

Operations

evaluate

Evaluate one feature flag and return the selected value plus selection metadata.

evaluate(input: FeatureFlagsEvaluateInput): FeatureFlagsEvaluateResult

publish

Publish the current code-defined Feature Flags snapshot.

publish(input?: FeatureFlagsPublishInput): FeatureFlagsPublishResult

read

Read the active Feature Flags snapshot for an environment or the code-defined snapshot.

read(input?: FeatureFlagsReadInput): FeatureFlagsReadResult

history

Read Feature Flags publish and rollback history.

history(input?: FeatureFlagsHistoryInput): FeatureFlagsHistoryResult

rollback

Restore a previously published Feature Flags snapshot by checksum.

rollback(input: FeatureFlagsRollbackInput): FeatureFlagsRollbackResult