@aws-lambda-powertools/feature-flags 0.0.0 → 2.37.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +70 -4
- package/lib/cjs/FeatureFlags.d.ts +98 -0
- package/lib/cjs/FeatureFlags.d.ts.map +1 -0
- package/lib/cjs/FeatureFlags.js +260 -0
- package/lib/cjs/appconfig/appConfigStore.d.ts +38 -0
- package/lib/cjs/appconfig/appConfigStore.d.ts.map +1 -0
- package/lib/cjs/appconfig/appConfigStore.js +65 -0
- package/lib/cjs/appconfig/index.d.ts +4 -0
- package/lib/cjs/appconfig/index.d.ts.map +1 -0
- package/lib/cjs/appconfig/index.js +5 -0
- package/lib/cjs/appconfig-agent/appConfigAgentStore.d.ts +37 -0
- package/lib/cjs/appconfig-agent/appConfigAgentStore.d.ts.map +1 -0
- package/lib/cjs/appconfig-agent/appConfigAgentStore.js +59 -0
- package/lib/cjs/appconfig-agent/appConfigVariantStore.d.ts +46 -0
- package/lib/cjs/appconfig-agent/appConfigVariantStore.d.ts.map +1 -0
- package/lib/cjs/appconfig-agent/appConfigVariantStore.js +176 -0
- package/lib/cjs/appconfig-agent/index.d.ts +6 -0
- package/lib/cjs/appconfig-agent/index.d.ts.map +1 -0
- package/lib/cjs/appconfig-agent/index.js +8 -0
- package/lib/cjs/constants.d.ts +56 -0
- package/lib/cjs/constants.d.ts.map +1 -0
- package/lib/cjs/constants.js +86 -0
- package/lib/cjs/context.d.ts +21 -0
- package/lib/cjs/context.d.ts.map +1 -0
- package/lib/cjs/context.js +42 -0
- package/lib/cjs/envelope/index.d.ts +20 -0
- package/lib/cjs/envelope/index.d.ts.map +1 -0
- package/lib/cjs/envelope/index.js +29 -0
- package/lib/cjs/errors.d.ts +74 -0
- package/lib/cjs/errors.d.ts.map +1 -0
- package/lib/cjs/errors.js +116 -0
- package/lib/cjs/index.d.ts +6 -0
- package/lib/cjs/index.d.ts.map +1 -0
- package/lib/cjs/index.js +15 -0
- package/lib/cjs/package.json +1 -0
- package/lib/cjs/parameters-stores/classify.d.ts +20 -0
- package/lib/cjs/parameters-stores/classify.d.ts.map +1 -0
- package/lib/cjs/parameters-stores/classify.js +50 -0
- package/lib/cjs/parameters-stores/createDocumentSource.d.ts +17 -0
- package/lib/cjs/parameters-stores/createDocumentSource.d.ts.map +1 -0
- package/lib/cjs/parameters-stores/createDocumentSource.js +31 -0
- package/lib/cjs/parameters-stores/envelope.d.ts +22 -0
- package/lib/cjs/parameters-stores/envelope.d.ts.map +1 -0
- package/lib/cjs/parameters-stores/envelope.js +39 -0
- package/lib/cjs/ruleEngine/actions.d.ts +5 -0
- package/lib/cjs/ruleEngine/actions.d.ts.map +1 -0
- package/lib/cjs/ruleEngine/actions.js +155 -0
- package/lib/cjs/ruleEngine/datetime.d.ts +12 -0
- package/lib/cjs/ruleEngine/datetime.d.ts.map +1 -0
- package/lib/cjs/ruleEngine/datetime.js +134 -0
- package/lib/cjs/ruleEngine/evaluate.d.ts +15 -0
- package/lib/cjs/ruleEngine/evaluate.d.ts.map +1 -0
- package/lib/cjs/ruleEngine/evaluate.js +60 -0
- package/lib/cjs/ruleEngine/guards.d.ts +51 -0
- package/lib/cjs/ruleEngine/guards.d.ts.map +1 -0
- package/lib/cjs/ruleEngine/guards.js +123 -0
- package/lib/cjs/ruleEngine/index.d.ts +35 -0
- package/lib/cjs/ruleEngine/index.d.ts.map +1 -0
- package/lib/cjs/ruleEngine/index.js +70 -0
- package/lib/cjs/ruleEngine/json.d.ts +16 -0
- package/lib/cjs/ruleEngine/json.d.ts.map +1 -0
- package/lib/cjs/ruleEngine/json.js +38 -0
- package/lib/cjs/ruleEngine/time.d.ts +14 -0
- package/lib/cjs/ruleEngine/time.d.ts.map +1 -0
- package/lib/cjs/ruleEngine/time.js +102 -0
- package/lib/cjs/ruleEngine/validate.d.ts +11 -0
- package/lib/cjs/ruleEngine/validate.d.ts.map +1 -0
- package/lib/cjs/ruleEngine/validate.js +134 -0
- package/lib/cjs/ruleEngine/validateScheduleAndModulo.d.ts +13 -0
- package/lib/cjs/ruleEngine/validateScheduleAndModulo.d.ts.map +1 -0
- package/lib/cjs/ruleEngine/validateScheduleAndModulo.js +38 -0
- package/lib/cjs/ruleEngine/validationCache.d.ts +12 -0
- package/lib/cjs/ruleEngine/validationCache.d.ts.map +1 -0
- package/lib/cjs/ruleEngine/validationCache.js +29 -0
- package/lib/cjs/types/AppConfigAgentStore.d.ts +20 -0
- package/lib/cjs/types/AppConfigAgentStore.d.ts.map +1 -0
- package/lib/cjs/types/AppConfigAgentStore.js +2 -0
- package/lib/cjs/types/AppConfigStore.d.ts +25 -0
- package/lib/cjs/types/AppConfigStore.d.ts.map +1 -0
- package/lib/cjs/types/AppConfigStore.js +2 -0
- package/lib/cjs/types/AppConfigVariantStore.d.ts +16 -0
- package/lib/cjs/types/AppConfigVariantStore.d.ts.map +1 -0
- package/lib/cjs/types/AppConfigVariantStore.js +2 -0
- package/lib/cjs/types/Envelope.d.ts +16 -0
- package/lib/cjs/types/Envelope.d.ts.map +1 -0
- package/lib/cjs/types/Envelope.js +2 -0
- package/lib/cjs/types/RuleEngine.d.ts +83 -0
- package/lib/cjs/types/RuleEngine.d.ts.map +1 -0
- package/lib/cjs/types/RuleEngine.js +2 -0
- package/lib/cjs/types/VariantEvaluation.d.ts +20 -0
- package/lib/cjs/types/VariantEvaluation.d.ts.map +1 -0
- package/lib/cjs/types/VariantEvaluation.js +2 -0
- package/lib/cjs/types/index.d.ts +81 -0
- package/lib/cjs/types/index.d.ts.map +1 -0
- package/lib/cjs/types/index.js +2 -0
- package/lib/cjs/variant.d.ts +9 -0
- package/lib/cjs/variant.d.ts.map +1 -0
- package/lib/cjs/variant.js +26 -0
- package/lib/esm/FeatureFlags.d.ts +98 -0
- package/lib/esm/FeatureFlags.d.ts.map +1 -0
- package/lib/esm/FeatureFlags.js +257 -0
- package/lib/esm/appconfig/appConfigStore.d.ts +38 -0
- package/lib/esm/appconfig/appConfigStore.d.ts.map +1 -0
- package/lib/esm/appconfig/appConfigStore.js +62 -0
- package/lib/esm/appconfig/index.d.ts +4 -0
- package/lib/esm/appconfig/index.d.ts.map +1 -0
- package/lib/esm/appconfig/index.js +1 -0
- package/lib/esm/appconfig-agent/appConfigAgentStore.d.ts +37 -0
- package/lib/esm/appconfig-agent/appConfigAgentStore.d.ts.map +1 -0
- package/lib/esm/appconfig-agent/appConfigAgentStore.js +56 -0
- package/lib/esm/appconfig-agent/appConfigVariantStore.d.ts +46 -0
- package/lib/esm/appconfig-agent/appConfigVariantStore.d.ts.map +1 -0
- package/lib/esm/appconfig-agent/appConfigVariantStore.js +172 -0
- package/lib/esm/appconfig-agent/index.d.ts +6 -0
- package/lib/esm/appconfig-agent/index.d.ts.map +1 -0
- package/lib/esm/appconfig-agent/index.js +2 -0
- package/lib/esm/constants.d.ts +56 -0
- package/lib/esm/constants.d.ts.map +1 -0
- package/lib/esm/constants.js +77 -0
- package/lib/esm/context.d.ts +21 -0
- package/lib/esm/context.d.ts.map +1 -0
- package/lib/esm/context.js +37 -0
- package/lib/esm/envelope/index.d.ts +20 -0
- package/lib/esm/envelope/index.d.ts.map +1 -0
- package/lib/esm/envelope/index.js +26 -0
- package/lib/esm/errors.d.ts +74 -0
- package/lib/esm/errors.d.ts.map +1 -0
- package/lib/esm/errors.js +107 -0
- package/lib/esm/index.d.ts +6 -0
- package/lib/esm/index.d.ts.map +1 -0
- package/lib/esm/index.js +3 -0
- package/lib/esm/package.json +1 -0
- package/lib/esm/parameters-stores/classify.d.ts +20 -0
- package/lib/esm/parameters-stores/classify.d.ts.map +1 -0
- package/lib/esm/parameters-stores/classify.js +47 -0
- package/lib/esm/parameters-stores/createDocumentSource.d.ts +17 -0
- package/lib/esm/parameters-stores/createDocumentSource.d.ts.map +1 -0
- package/lib/esm/parameters-stores/createDocumentSource.js +28 -0
- package/lib/esm/parameters-stores/envelope.d.ts +22 -0
- package/lib/esm/parameters-stores/envelope.d.ts.map +1 -0
- package/lib/esm/parameters-stores/envelope.js +35 -0
- package/lib/esm/ruleEngine/actions.d.ts +5 -0
- package/lib/esm/ruleEngine/actions.d.ts.map +1 -0
- package/lib/esm/ruleEngine/actions.js +152 -0
- package/lib/esm/ruleEngine/datetime.d.ts +12 -0
- package/lib/esm/ruleEngine/datetime.d.ts.map +1 -0
- package/lib/esm/ruleEngine/datetime.js +131 -0
- package/lib/esm/ruleEngine/evaluate.d.ts +15 -0
- package/lib/esm/ruleEngine/evaluate.d.ts.map +1 -0
- package/lib/esm/ruleEngine/evaluate.js +57 -0
- package/lib/esm/ruleEngine/guards.d.ts +51 -0
- package/lib/esm/ruleEngine/guards.d.ts.map +1 -0
- package/lib/esm/ruleEngine/guards.js +113 -0
- package/lib/esm/ruleEngine/index.d.ts +35 -0
- package/lib/esm/ruleEngine/index.d.ts.map +1 -0
- package/lib/esm/ruleEngine/index.js +67 -0
- package/lib/esm/ruleEngine/json.d.ts +16 -0
- package/lib/esm/ruleEngine/json.d.ts.map +1 -0
- package/lib/esm/ruleEngine/json.js +34 -0
- package/lib/esm/ruleEngine/time.d.ts +14 -0
- package/lib/esm/ruleEngine/time.d.ts.map +1 -0
- package/lib/esm/ruleEngine/time.js +97 -0
- package/lib/esm/ruleEngine/validate.d.ts +11 -0
- package/lib/esm/ruleEngine/validate.d.ts.map +1 -0
- package/lib/esm/ruleEngine/validate.js +131 -0
- package/lib/esm/ruleEngine/validateScheduleAndModulo.d.ts +13 -0
- package/lib/esm/ruleEngine/validateScheduleAndModulo.d.ts.map +1 -0
- package/lib/esm/ruleEngine/validateScheduleAndModulo.js +35 -0
- package/lib/esm/ruleEngine/validationCache.d.ts +12 -0
- package/lib/esm/ruleEngine/validationCache.d.ts.map +1 -0
- package/lib/esm/ruleEngine/validationCache.js +26 -0
- package/lib/esm/types/AppConfigAgentStore.d.ts +20 -0
- package/lib/esm/types/AppConfigAgentStore.d.ts.map +1 -0
- package/lib/esm/types/AppConfigStore.d.ts +25 -0
- package/lib/esm/types/AppConfigStore.d.ts.map +1 -0
- package/lib/esm/types/AppConfigStore.js +1 -0
- package/lib/esm/types/AppConfigVariantStore.d.ts +16 -0
- package/lib/esm/types/AppConfigVariantStore.d.ts.map +1 -0
- package/lib/esm/types/AppConfigVariantStore.js +1 -0
- package/lib/esm/types/Envelope.d.ts +16 -0
- package/lib/esm/types/Envelope.d.ts.map +1 -0
- package/lib/esm/types/Envelope.js +1 -0
- package/lib/esm/types/RuleEngine.d.ts +83 -0
- package/lib/esm/types/RuleEngine.d.ts.map +1 -0
- package/lib/esm/types/RuleEngine.js +1 -0
- package/lib/esm/types/VariantEvaluation.d.ts +20 -0
- package/lib/esm/types/VariantEvaluation.d.ts.map +1 -0
- package/lib/esm/types/VariantEvaluation.js +1 -0
- package/lib/esm/types/index.d.ts +81 -0
- package/lib/esm/types/index.d.ts.map +1 -0
- package/lib/esm/types/index.js +1 -0
- package/lib/esm/variant.d.ts +9 -0
- package/lib/esm/variant.d.ts.map +1 -0
- package/lib/esm/variant.js +21 -0
- package/package.json +133 -13
- package/lib/index.js +0 -3
- /package/lib/{index.d.ts → esm/types/AppConfigAgentStore.js} +0 -0
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import type { JSONValue } from '@aws-lambda-powertools/commons/types';
|
|
2
|
+
import type { StandardSchemaV1 } from '@standard-schema/spec';
|
|
3
|
+
import type { EvaluateManyOptions, EvaluateManyResult, EvaluateOptions, EvaluateResult, EvaluateWithSchemaOptions, FeatureFlagsOptions, GetEnabledFeaturesOptions, Variant } from './types/index.js';
|
|
4
|
+
import type { EvaluateManyVariantOptions, EvaluateManyVariantResult, EvaluateVariantOptions } from './types/VariantEvaluation.js';
|
|
5
|
+
/**
|
|
6
|
+
* Evaluates feature flags against a caller-supplied {@link Store | `Store`}.
|
|
7
|
+
*
|
|
8
|
+
* Infers the Store's value type. Variant stores require full Variant fallbacks
|
|
9
|
+
* and return Variants without schemas; JSON stores retain primitive inference
|
|
10
|
+
* and optional Standard Schema validation.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```typescript
|
|
14
|
+
* const flags = new FeatureFlags({ store: myStore });
|
|
15
|
+
* const enabled = await flags.evaluate({ name: 'checkout_v2', default: false });
|
|
16
|
+
* ```
|
|
17
|
+
*/
|
|
18
|
+
declare class FeatureFlags<Value = JSONValue> {
|
|
19
|
+
#private;
|
|
20
|
+
/**
|
|
21
|
+
* Creates a feature flag evaluator.
|
|
22
|
+
* @param {Object} options - Configure the evaluator
|
|
23
|
+
* @param {Store} options.store - Supply the Store for flag lookups
|
|
24
|
+
* @param {GenericLogger} options.logger - Log outcomes without values
|
|
25
|
+
*/
|
|
26
|
+
constructor(options: FeatureFlagsOptions<Value>);
|
|
27
|
+
/**
|
|
28
|
+
* Evaluates one flag and returns its value or the required fallback.
|
|
29
|
+
*
|
|
30
|
+
* Handles {@link StoreUnavailableError | `StoreUnavailableError`} with the fallback.
|
|
31
|
+
* With a schema, validates the fallback before contacting the {@link Store | `Store`}
|
|
32
|
+
* and replaces the primitive type check with schema validation. Returns the
|
|
33
|
+
* validated output on both the found path and the fallback path, and rejects
|
|
34
|
+
* schema outputs that are undefined.
|
|
35
|
+
* Variant stores require a full Variant fallback, return it unchanged on a
|
|
36
|
+
* fallback path, and do not accept schemas.
|
|
37
|
+
*
|
|
38
|
+
* @param {Object} options - Configure the flag evaluation
|
|
39
|
+
* @param {string} options.name - Identify the flag
|
|
40
|
+
* @param {EvaluationContext} options.context - Supply scalar facts for evaluation
|
|
41
|
+
* @param {JSONValue} options.default - Supply the fallback and, without a schema, the expected primitive type
|
|
42
|
+
* @param {StandardSchemaV1} options.schema - Validate the fallback and result with an optional schema
|
|
43
|
+
* @example
|
|
44
|
+
* ```typescript
|
|
45
|
+
* const enabled = await flags.evaluate({
|
|
46
|
+
* name: 'checkout_v2', context: { tier: 'premium' }, default: false,
|
|
47
|
+
* });
|
|
48
|
+
* ```
|
|
49
|
+
* @example
|
|
50
|
+
* ```typescript
|
|
51
|
+
* const settings = await flags.evaluate({
|
|
52
|
+
* name: 'settings', default: { theme: 'light' }, schema: settingsSchema,
|
|
53
|
+
* });
|
|
54
|
+
* ```
|
|
55
|
+
*/
|
|
56
|
+
evaluate<Schema extends StandardSchemaV1>(options: Value extends Variant ? never : EvaluateWithSchemaOptions<Schema>): Promise<StandardSchemaV1.InferOutput<Schema>>;
|
|
57
|
+
evaluate<Fallback extends JSONValue>(options: Value extends Variant ? EvaluateVariantOptions : EvaluateOptions<Fallback>): Promise<Value extends Variant ? Variant : EvaluateResult<Fallback>>;
|
|
58
|
+
/**
|
|
59
|
+
* Evaluates several flags with an independent fallback for each flag.
|
|
60
|
+
*
|
|
61
|
+
* Handles {@link StoreUnavailableError | `StoreUnavailableError`} with every fallback.
|
|
62
|
+
* Validates schema-backed fallbacks before contacting the {@link Store | `Store`}.
|
|
63
|
+
* Each schema replaces the primitive type check and supplies the output on both
|
|
64
|
+
* the found path and the fallback path. Rejects undefined schema outputs and
|
|
65
|
+
* throws for the whole batch if any flag fails validation.
|
|
66
|
+
* Variant stores require a full Variant fallback per flag and do not accept
|
|
67
|
+
* schemas. Each requested key resolves to a Variant.
|
|
68
|
+
*
|
|
69
|
+
* @param {Object} options - Configure the batch evaluation
|
|
70
|
+
* @param {Object} options.flags - Supply flag names and their fallbacks
|
|
71
|
+
* @param {EvaluationContext} options.context - Supply scalar facts for evaluation
|
|
72
|
+
* @param {Object} options.schemas - Validate selected flags and their fallbacks
|
|
73
|
+
* @example
|
|
74
|
+
* ```typescript
|
|
75
|
+
* const result = await flags.evaluateMany({
|
|
76
|
+
* flags: { checkout_v2: false, limit: 10 }, context: { tier: 'premium' },
|
|
77
|
+
* });
|
|
78
|
+
* const settings = await flags.evaluateMany({
|
|
79
|
+
* flags: { settings: { theme: 'light' }, banner: 'none' },
|
|
80
|
+
* schemas: { settings: settingsSchema },
|
|
81
|
+
* });
|
|
82
|
+
* ```
|
|
83
|
+
*/
|
|
84
|
+
evaluateMany<Flags extends Record<string, JSONValue>, Schemas extends Partial<Record<string, StandardSchemaV1>> = Partial<Record<string, never>>>(options: Value extends Variant ? EvaluateManyVariantOptions<Flags> : EvaluateManyOptions<Flags, Schemas>): Promise<Value extends Variant ? EvaluateManyVariantResult<Flags> : EvaluateManyResult<Flags, Schemas>>;
|
|
85
|
+
/**
|
|
86
|
+
* Gets enabled flag names in the {@link Store | `Store`}'s iteration order.
|
|
87
|
+
*
|
|
88
|
+
* @param {Object} options - Configure the lookup
|
|
89
|
+
* @param {EvaluationContext} options.context - Supply scalar facts for evaluation
|
|
90
|
+
* @example
|
|
91
|
+
* ```typescript
|
|
92
|
+
* const enabled = await flags.getEnabledFeatures({ context: { tier: 'premium' } });
|
|
93
|
+
* ```
|
|
94
|
+
*/
|
|
95
|
+
getEnabledFeatures(options?: GetEnabledFeaturesOptions): Promise<string[]>;
|
|
96
|
+
}
|
|
97
|
+
export { FeatureFlags };
|
|
98
|
+
//# sourceMappingURL=FeatureFlags.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"FeatureFlags.d.ts","sourceRoot":"","sources":["../../src/FeatureFlags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EACV,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAQ9D,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,yBAAyB,EAEzB,mBAAmB,EACnB,yBAAyB,EAGzB,OAAO,EACR,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,8BAA8B,CAAC;AAGtC;;;;;;;;;;;;GAYG;AACH,cAAM,YAAY,CAAC,KAAK,GAAG,SAAS;;IAKlC;;;;;OAKG;gBACgB,OAAO,EAAE,mBAAmB,CAAC,KAAK,CAAC;IAMtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACI,QAAQ,CAAC,MAAM,SAAS,gBAAgB,EAC7C,OAAO,EAAE,KAAK,SAAS,OAAO,GAAG,KAAK,GAAG,yBAAyB,CAAC,MAAM,CAAC,GACzE,OAAO,CAAC,gBAAgB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAEzC,QAAQ,CAAC,QAAQ,SAAS,SAAS,EACxC,OAAO,EAAE,KAAK,SAAS,OAAO,GAC1B,sBAAsB,GACtB,eAAe,CAAC,QAAQ,CAAC,GAC5B,OAAO,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAwDtE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,YAAY,CACjB,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EACvC,OAAO,SAAS,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,GAAG,OAAO,CACjE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CACtB,EAED,OAAO,EAAE,KAAK,SAAS,OAAO,GAC1B,0BAA0B,CAAC,KAAK,CAAC,GACjC,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,GACtC,OAAO,CACR,KAAK,SAAS,OAAO,GACjB,yBAAyB,CAAC,KAAK,CAAC,GAChC,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,CACvC;IAqFD;;;;;;;;;OASG;IACU,kBAAkB,CAC7B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,MAAM,EAAE,CAAC;CA2BrB;AA6ED,OAAO,EAAE,YAAY,EAAE,CAAC"}
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
import { getInvalidContextKind, isScalar } from './context.js';
|
|
2
|
+
import { FlagResultValidationError, FlagValueTypeError, InvalidContextError, StoreUnavailableError, } from './errors.js';
|
|
3
|
+
import { isVariant, isVariantStore } from './variant.js';
|
|
4
|
+
/**
|
|
5
|
+
* Evaluates feature flags against a caller-supplied {@link Store | `Store`}.
|
|
6
|
+
*
|
|
7
|
+
* Infers the Store's value type. Variant stores require full Variant fallbacks
|
|
8
|
+
* and return Variants without schemas; JSON stores retain primitive inference
|
|
9
|
+
* and optional Standard Schema validation.
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* ```typescript
|
|
13
|
+
* const flags = new FeatureFlags({ store: myStore });
|
|
14
|
+
* const enabled = await flags.evaluate({ name: 'checkout_v2', default: false });
|
|
15
|
+
* ```
|
|
16
|
+
*/
|
|
17
|
+
class FeatureFlags {
|
|
18
|
+
#store;
|
|
19
|
+
#variantStore;
|
|
20
|
+
#logger;
|
|
21
|
+
/**
|
|
22
|
+
* Creates a feature flag evaluator.
|
|
23
|
+
* @param {Object} options - Configure the evaluator
|
|
24
|
+
* @param {Store} options.store - Supply the Store for flag lookups
|
|
25
|
+
* @param {GenericLogger} options.logger - Log outcomes without values
|
|
26
|
+
*/
|
|
27
|
+
constructor(options) {
|
|
28
|
+
this.#store = options.store;
|
|
29
|
+
this.#variantStore = isVariantStore(options.store);
|
|
30
|
+
this.#logger = options.logger;
|
|
31
|
+
}
|
|
32
|
+
async evaluate(options) {
|
|
33
|
+
const { name, context = {} } = options;
|
|
34
|
+
validateContext(context);
|
|
35
|
+
if (this.#variantStore)
|
|
36
|
+
validateVariantFallback(name, options.default);
|
|
37
|
+
const fallback = !this.#variantStore && 'schema' in options
|
|
38
|
+
? await validateWithSchema(name, 'fallback', options.default, options.schema)
|
|
39
|
+
: options.default;
|
|
40
|
+
let result;
|
|
41
|
+
try {
|
|
42
|
+
result = await this.#store.getMany([name], context);
|
|
43
|
+
}
|
|
44
|
+
catch (error) {
|
|
45
|
+
if (!(error instanceof StoreUnavailableError))
|
|
46
|
+
throw error;
|
|
47
|
+
this.#logger?.warn({
|
|
48
|
+
name,
|
|
49
|
+
store: this.#store.name,
|
|
50
|
+
reason: 'unavailable',
|
|
51
|
+
});
|
|
52
|
+
this.#logger?.debug({
|
|
53
|
+
name,
|
|
54
|
+
store: this.#store.name,
|
|
55
|
+
outcome: 'fallback',
|
|
56
|
+
});
|
|
57
|
+
return fallback;
|
|
58
|
+
}
|
|
59
|
+
const flag = result[name];
|
|
60
|
+
if (!flag?.found) {
|
|
61
|
+
this.#logger?.warn({ name, store: this.#store.name, reason: 'missing' });
|
|
62
|
+
this.#logger?.debug({
|
|
63
|
+
name,
|
|
64
|
+
store: this.#store.name,
|
|
65
|
+
outcome: 'fallback',
|
|
66
|
+
});
|
|
67
|
+
return fallback;
|
|
68
|
+
}
|
|
69
|
+
let value = flag.value;
|
|
70
|
+
if (!this.#variantStore && 'schema' in options) {
|
|
71
|
+
value = await validateWithSchema(name, 'result', value, options.schema);
|
|
72
|
+
}
|
|
73
|
+
else if (!this.#variantStore) {
|
|
74
|
+
validateFlagValue(name, fallback, value);
|
|
75
|
+
}
|
|
76
|
+
this.#logger?.debug({ name, store: this.#store.name, outcome: 'found' });
|
|
77
|
+
return value;
|
|
78
|
+
}
|
|
79
|
+
async evaluateMany(options) {
|
|
80
|
+
const { flags, context = {}, schemas = {} } = options;
|
|
81
|
+
validateContext(context);
|
|
82
|
+
const names = Object.keys(flags);
|
|
83
|
+
const fallbacks = [];
|
|
84
|
+
for (const name of names) {
|
|
85
|
+
if (this.#variantStore)
|
|
86
|
+
validateVariantFallback(name, flags[name]);
|
|
87
|
+
const schema = !this.#variantStore && Object.hasOwn(schemas, name)
|
|
88
|
+
? schemas[name]
|
|
89
|
+
: undefined;
|
|
90
|
+
fallbacks.push([
|
|
91
|
+
name,
|
|
92
|
+
schema
|
|
93
|
+
? await validateWithSchema(name, 'fallback', flags[name], schema)
|
|
94
|
+
: flags[name],
|
|
95
|
+
]);
|
|
96
|
+
}
|
|
97
|
+
let result;
|
|
98
|
+
try {
|
|
99
|
+
result = await this.#store.getMany(names, context);
|
|
100
|
+
}
|
|
101
|
+
catch (error) {
|
|
102
|
+
if (!(error instanceof StoreUnavailableError))
|
|
103
|
+
throw error;
|
|
104
|
+
this.#logger?.warn({
|
|
105
|
+
store: this.#store.name,
|
|
106
|
+
reason: 'unavailable',
|
|
107
|
+
names,
|
|
108
|
+
});
|
|
109
|
+
this.#logger?.debug({
|
|
110
|
+
store: this.#store.name,
|
|
111
|
+
outcome: 'fallback',
|
|
112
|
+
names,
|
|
113
|
+
});
|
|
114
|
+
return Object.fromEntries(fallbacks);
|
|
115
|
+
}
|
|
116
|
+
const values = [];
|
|
117
|
+
const missing = [];
|
|
118
|
+
for (const [name, fallback] of fallbacks) {
|
|
119
|
+
const flag = result[name];
|
|
120
|
+
if (!flag?.found) {
|
|
121
|
+
missing.push(name);
|
|
122
|
+
values.push([name, fallback]);
|
|
123
|
+
}
|
|
124
|
+
else {
|
|
125
|
+
const schema = !this.#variantStore && Object.hasOwn(schemas, name)
|
|
126
|
+
? schemas[name]
|
|
127
|
+
: undefined;
|
|
128
|
+
if (schema) {
|
|
129
|
+
values.push([
|
|
130
|
+
name,
|
|
131
|
+
await validateWithSchema(name, 'result', flag.value, schema),
|
|
132
|
+
]);
|
|
133
|
+
}
|
|
134
|
+
else {
|
|
135
|
+
if (!this.#variantStore)
|
|
136
|
+
validateFlagValue(name, fallback, flag.value);
|
|
137
|
+
values.push([name, flag.value]);
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
if (missing.length > 0) {
|
|
142
|
+
this.#logger?.warn({
|
|
143
|
+
store: this.#store.name,
|
|
144
|
+
reason: 'missing',
|
|
145
|
+
names: missing,
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
this.#logger?.debug({
|
|
149
|
+
store: this.#store.name,
|
|
150
|
+
outcome: missing.length === 0
|
|
151
|
+
? 'found'
|
|
152
|
+
: missing.length === names.length
|
|
153
|
+
? 'fallback'
|
|
154
|
+
: 'partial',
|
|
155
|
+
names,
|
|
156
|
+
});
|
|
157
|
+
return Object.fromEntries(values);
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Gets enabled flag names in the {@link Store | `Store`}'s iteration order.
|
|
161
|
+
*
|
|
162
|
+
* @param {Object} options - Configure the lookup
|
|
163
|
+
* @param {EvaluationContext} options.context - Supply scalar facts for evaluation
|
|
164
|
+
* @example
|
|
165
|
+
* ```typescript
|
|
166
|
+
* const enabled = await flags.getEnabledFeatures({ context: { tier: 'premium' } });
|
|
167
|
+
* ```
|
|
168
|
+
*/
|
|
169
|
+
async getEnabledFeatures(options = {}) {
|
|
170
|
+
const { context = {} } = options;
|
|
171
|
+
validateContext(context);
|
|
172
|
+
let result;
|
|
173
|
+
try {
|
|
174
|
+
result = await this.#store.getAll(context);
|
|
175
|
+
}
|
|
176
|
+
catch (error) {
|
|
177
|
+
if (!(error instanceof StoreUnavailableError))
|
|
178
|
+
throw error;
|
|
179
|
+
this.#logger?.warn({ store: this.#store.name, reason: 'unavailable' });
|
|
180
|
+
this.#logger?.debug({
|
|
181
|
+
store: this.#store.name,
|
|
182
|
+
outcome: 'fallback',
|
|
183
|
+
enabled: 0,
|
|
184
|
+
});
|
|
185
|
+
return [];
|
|
186
|
+
}
|
|
187
|
+
const enabled = [];
|
|
188
|
+
for (const [name, flag] of Object.entries(result)) {
|
|
189
|
+
if (flag.found && flag.enabled)
|
|
190
|
+
enabled.push(name);
|
|
191
|
+
}
|
|
192
|
+
this.#logger?.debug({
|
|
193
|
+
store: this.#store.name,
|
|
194
|
+
outcome: 'found',
|
|
195
|
+
enabled: enabled.length,
|
|
196
|
+
});
|
|
197
|
+
return enabled;
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
/**
|
|
201
|
+
* Validates a fallback or Store result and returns the schema output.
|
|
202
|
+
* @param name - Identify the flag
|
|
203
|
+
* @param source - Identify the fallback or result
|
|
204
|
+
* @param value - Supply the value to validate
|
|
205
|
+
* @param schema - Supply the Standard Schema validator
|
|
206
|
+
* @internal
|
|
207
|
+
*/
|
|
208
|
+
const validateWithSchema = async (name, source, value, schema) => {
|
|
209
|
+
let result;
|
|
210
|
+
try {
|
|
211
|
+
result = await schema['~standard'].validate(value);
|
|
212
|
+
}
|
|
213
|
+
catch (cause) {
|
|
214
|
+
throw new FlagResultValidationError(name, source, [], { cause });
|
|
215
|
+
}
|
|
216
|
+
if (result.issues) {
|
|
217
|
+
throw new FlagResultValidationError(name, source, result.issues);
|
|
218
|
+
}
|
|
219
|
+
if (result.value === undefined) {
|
|
220
|
+
throw new FlagResultValidationError(name, source, []);
|
|
221
|
+
}
|
|
222
|
+
// Schemas own the validated value contract; public overloads expose their output type.
|
|
223
|
+
return result.value;
|
|
224
|
+
};
|
|
225
|
+
/**
|
|
226
|
+
* Validates scalar context facts before contacting the Store.
|
|
227
|
+
* @param context - Supply the evaluation context
|
|
228
|
+
* @internal
|
|
229
|
+
*/
|
|
230
|
+
const validateContext = (context) => {
|
|
231
|
+
for (const [key, value] of Object.entries(context)) {
|
|
232
|
+
if (!(Array.isArray(value)
|
|
233
|
+
? Array.from(value).every(isScalar)
|
|
234
|
+
: isScalar(value))) {
|
|
235
|
+
throw new InvalidContextError(`Invalid evaluation context key '${key}': expected a string, number, boolean, or array of those, received ${getInvalidContextKind(value)}`);
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
};
|
|
239
|
+
/**
|
|
240
|
+
* Checks a Store value against its primitive fallback type.
|
|
241
|
+
* @param name - Identify the flag
|
|
242
|
+
* @param fallback - Supply the expected primitive type
|
|
243
|
+
* @param value - Supply the Store value
|
|
244
|
+
* @internal
|
|
245
|
+
*/
|
|
246
|
+
const validateFlagValue = (name, fallback, value) => {
|
|
247
|
+
if (isScalar(fallback) && typeof value !== typeof fallback) {
|
|
248
|
+
throw new FlagValueTypeError(`Flag '${name}' expected type '${typeof fallback}' but received '${typeof value}'`);
|
|
249
|
+
}
|
|
250
|
+
};
|
|
251
|
+
/** Rejects invalid Variant fallbacks before contacting the Store. @internal */
|
|
252
|
+
const validateVariantFallback = (name, fallback) => {
|
|
253
|
+
if (!isVariant(fallback)) {
|
|
254
|
+
throw new FlagValueTypeError(`Flag '${name}' requires a Variant fallback`);
|
|
255
|
+
}
|
|
256
|
+
};
|
|
257
|
+
export { FeatureFlags };
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import type { AppConfigStoreOptions } from '../types/AppConfigStore.js';
|
|
2
|
+
import type { Store } from '../types/index.js';
|
|
3
|
+
/**
|
|
4
|
+
* Creates a Store that retrieves and evaluates AppConfig freeform Flag Documents.
|
|
5
|
+
*
|
|
6
|
+
* Install `@aws-lambda-powertools/parameters` and `@aws-sdk/client-appconfigdata`
|
|
7
|
+
* to use this sub-path. One provider per Store owns retrieval caching.
|
|
8
|
+
* Supply both `envelope` and `envelopeSearchFn` to select an embedded document.
|
|
9
|
+
* Known availability failures return the evaluator's fallback; configuration,
|
|
10
|
+
* transform, and envelope errors propagate.
|
|
11
|
+
*
|
|
12
|
+
* @param {Object} options - Configure retrieval and logging
|
|
13
|
+
* @param {string} options.name - Identify the configuration profile
|
|
14
|
+
* @param {string} options.environment - Identify the environment
|
|
15
|
+
* @param {string} options.application - Identify the application or use the service name
|
|
16
|
+
* @param {string} options.envelope - Select an embedded Flag Document
|
|
17
|
+
* @param {Function} options.envelopeSearchFn - Apply the envelope expression
|
|
18
|
+
* @param {number} options.maxAge - Set the Parameters cache duration in seconds
|
|
19
|
+
* @param {AppConfigDataClient} options.awsSdkV3Client - Supply an AppConfigData client
|
|
20
|
+
* @param {AppConfigDataClientConfig} options.clientConfig - Configure a new AppConfigData client
|
|
21
|
+
* @param {GenericLogger} options.logger - Log rule engine outcomes without values
|
|
22
|
+
* @example
|
|
23
|
+
* ```typescript
|
|
24
|
+
* import { FeatureFlags } from '@aws-lambda-powertools/feature-flags';
|
|
25
|
+
* import { appConfigStore } from '@aws-lambda-powertools/feature-flags/appconfig';
|
|
26
|
+
* import { search } from '@aws-lambda-powertools/feature-flags/envelope';
|
|
27
|
+
*
|
|
28
|
+
* const store = appConfigStore({
|
|
29
|
+
* application: 'my-app', environment: 'prod', name: 'features',
|
|
30
|
+
* envelope: 'settings.flags', envelopeSearchFn: search,
|
|
31
|
+
* });
|
|
32
|
+
* const flags = new FeatureFlags({ store });
|
|
33
|
+
* const enabled = await flags.evaluate({ name: 'checkout_v2', default: false });
|
|
34
|
+
* ```
|
|
35
|
+
*/
|
|
36
|
+
declare const appConfigStore: (options: AppConfigStoreOptions) => Store;
|
|
37
|
+
export { appConfigStore };
|
|
38
|
+
//# sourceMappingURL=appConfigStore.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"appConfigStore.d.ts","sourceRoot":"","sources":["../../../src/appconfig/appConfigStore.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,QAAA,MAAM,cAAc,GAAI,SAAS,qBAAqB,KAAG,KAuBxD,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,CAAC"}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';
|
|
2
|
+
import { StoreNames } from '../constants.js';
|
|
3
|
+
import { createDocumentSource } from '../parameters-stores/createDocumentSource.js';
|
|
4
|
+
import { validateEnvelopeOptions } from '../parameters-stores/envelope.js';
|
|
5
|
+
import { ruleEngineStore } from '../ruleEngine/index.js';
|
|
6
|
+
/**
|
|
7
|
+
* Creates a Store that retrieves and evaluates AppConfig freeform Flag Documents.
|
|
8
|
+
*
|
|
9
|
+
* Install `@aws-lambda-powertools/parameters` and `@aws-sdk/client-appconfigdata`
|
|
10
|
+
* to use this sub-path. One provider per Store owns retrieval caching.
|
|
11
|
+
* Supply both `envelope` and `envelopeSearchFn` to select an embedded document.
|
|
12
|
+
* Known availability failures return the evaluator's fallback; configuration,
|
|
13
|
+
* transform, and envelope errors propagate.
|
|
14
|
+
*
|
|
15
|
+
* @param {Object} options - Configure retrieval and logging
|
|
16
|
+
* @param {string} options.name - Identify the configuration profile
|
|
17
|
+
* @param {string} options.environment - Identify the environment
|
|
18
|
+
* @param {string} options.application - Identify the application or use the service name
|
|
19
|
+
* @param {string} options.envelope - Select an embedded Flag Document
|
|
20
|
+
* @param {Function} options.envelopeSearchFn - Apply the envelope expression
|
|
21
|
+
* @param {number} options.maxAge - Set the Parameters cache duration in seconds
|
|
22
|
+
* @param {AppConfigDataClient} options.awsSdkV3Client - Supply an AppConfigData client
|
|
23
|
+
* @param {AppConfigDataClientConfig} options.clientConfig - Configure a new AppConfigData client
|
|
24
|
+
* @param {GenericLogger} options.logger - Log rule engine outcomes without values
|
|
25
|
+
* @example
|
|
26
|
+
* ```typescript
|
|
27
|
+
* import { FeatureFlags } from '@aws-lambda-powertools/feature-flags';
|
|
28
|
+
* import { appConfigStore } from '@aws-lambda-powertools/feature-flags/appconfig';
|
|
29
|
+
* import { search } from '@aws-lambda-powertools/feature-flags/envelope';
|
|
30
|
+
*
|
|
31
|
+
* const store = appConfigStore({
|
|
32
|
+
* application: 'my-app', environment: 'prod', name: 'features',
|
|
33
|
+
* envelope: 'settings.flags', envelopeSearchFn: search,
|
|
34
|
+
* });
|
|
35
|
+
* const flags = new FeatureFlags({ store });
|
|
36
|
+
* const enabled = await flags.evaluate({ name: 'checkout_v2', default: false });
|
|
37
|
+
* ```
|
|
38
|
+
*/
|
|
39
|
+
const appConfigStore = (options) => {
|
|
40
|
+
const envelopeOptions = validateEnvelopeOptions(options);
|
|
41
|
+
const provider = new AppConfigProvider({
|
|
42
|
+
application: options.application,
|
|
43
|
+
environment: options.environment,
|
|
44
|
+
...(options.awsSdkV3Client
|
|
45
|
+
? { awsSdkV3Client: options.awsSdkV3Client }
|
|
46
|
+
: { clientConfig: options.clientConfig }),
|
|
47
|
+
});
|
|
48
|
+
return ruleEngineStore({
|
|
49
|
+
name: StoreNames.APPCONFIG,
|
|
50
|
+
logger: options.logger,
|
|
51
|
+
source: createDocumentSource({
|
|
52
|
+
storeName: StoreNames.APPCONFIG,
|
|
53
|
+
...envelopeOptions,
|
|
54
|
+
retrieve: () => provider.get(options.name, {
|
|
55
|
+
transform: 'json',
|
|
56
|
+
maxAge: options.maxAge,
|
|
57
|
+
throwOnMissing: true,
|
|
58
|
+
}),
|
|
59
|
+
}),
|
|
60
|
+
});
|
|
61
|
+
};
|
|
62
|
+
export { appConfigStore };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/appconfig/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { appConfigStore } from './appConfigStore.js';
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { AppConfigAgentStoreOptions } from '../types/AppConfigAgentStore.js';
|
|
2
|
+
import type { Store } from '../types/index.js';
|
|
3
|
+
/**
|
|
4
|
+
* Creates a Store that retrieves freeform Flag Documents through the AppConfig Agent.
|
|
5
|
+
*
|
|
6
|
+
* Install `@aws-lambda-powertools/parameters` to use this sub-path. Attach the AppConfig
|
|
7
|
+
* Agent Lambda extension to your function. The Agent owns caching and polling;
|
|
8
|
+
* this Store evaluates the retrieved document locally without loading the SDK.
|
|
9
|
+
* Supply both `envelope` and `envelopeSearchFn` to select an embedded document.
|
|
10
|
+
* Known availability failures return the evaluator's fallback; configuration,
|
|
11
|
+
* transform, and envelope errors propagate.
|
|
12
|
+
*
|
|
13
|
+
* @param {Object} options - Configure retrieval and logging
|
|
14
|
+
* @param {string} options.name - Identify the configuration profile
|
|
15
|
+
* @param {string} options.environment - Identify the environment
|
|
16
|
+
* @param {string} options.application - Identify the application or use the service name
|
|
17
|
+
* @param {string} options.envelope - Select an embedded Flag Document
|
|
18
|
+
* @param {Function} options.envelopeSearchFn - Apply the envelope expression
|
|
19
|
+
* @param {number} options.timeout - Set the request timeout in milliseconds
|
|
20
|
+
* @param {GenericLogger} options.logger - Log rule engine outcomes without values
|
|
21
|
+
* @example
|
|
22
|
+
* ```typescript
|
|
23
|
+
* import { FeatureFlags } from '@aws-lambda-powertools/feature-flags';
|
|
24
|
+
* import { appConfigAgentStore } from '@aws-lambda-powertools/feature-flags/appconfig-agent';
|
|
25
|
+
* import { search } from '@aws-lambda-powertools/feature-flags/envelope';
|
|
26
|
+
*
|
|
27
|
+
* const store = appConfigAgentStore({
|
|
28
|
+
* application: 'my-app', environment: 'prod', name: 'features',
|
|
29
|
+
* envelope: 'settings.flags', envelopeSearchFn: search,
|
|
30
|
+
* });
|
|
31
|
+
* const flags = new FeatureFlags({ store });
|
|
32
|
+
* const enabled = await flags.evaluate({ name: 'checkout_v2', default: false });
|
|
33
|
+
* ```
|
|
34
|
+
*/
|
|
35
|
+
declare const appConfigAgentStore: (options: AppConfigAgentStoreOptions) => Store;
|
|
36
|
+
export { appConfigAgentStore };
|
|
37
|
+
//# sourceMappingURL=appConfigAgentStore.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"appConfigAgentStore.d.ts","sourceRoot":"","sources":["../../../src/appconfig-agent/appConfigAgentStore.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,QAAA,MAAM,mBAAmB,GAAI,SAAS,0BAA0B,KAAG,KAkBlE,CAAC;AAEF,OAAO,EAAE,mBAAmB,EAAE,CAAC"}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { getConfig } from '@aws-lambda-powertools/parameters/appconfig-agent';
|
|
2
|
+
import { StoreNames } from '../constants.js';
|
|
3
|
+
import { createDocumentSource } from '../parameters-stores/createDocumentSource.js';
|
|
4
|
+
import { validateEnvelopeOptions } from '../parameters-stores/envelope.js';
|
|
5
|
+
import { ruleEngineStore } from '../ruleEngine/index.js';
|
|
6
|
+
/**
|
|
7
|
+
* Creates a Store that retrieves freeform Flag Documents through the AppConfig Agent.
|
|
8
|
+
*
|
|
9
|
+
* Install `@aws-lambda-powertools/parameters` to use this sub-path. Attach the AppConfig
|
|
10
|
+
* Agent Lambda extension to your function. The Agent owns caching and polling;
|
|
11
|
+
* this Store evaluates the retrieved document locally without loading the SDK.
|
|
12
|
+
* Supply both `envelope` and `envelopeSearchFn` to select an embedded document.
|
|
13
|
+
* Known availability failures return the evaluator's fallback; configuration,
|
|
14
|
+
* transform, and envelope errors propagate.
|
|
15
|
+
*
|
|
16
|
+
* @param {Object} options - Configure retrieval and logging
|
|
17
|
+
* @param {string} options.name - Identify the configuration profile
|
|
18
|
+
* @param {string} options.environment - Identify the environment
|
|
19
|
+
* @param {string} options.application - Identify the application or use the service name
|
|
20
|
+
* @param {string} options.envelope - Select an embedded Flag Document
|
|
21
|
+
* @param {Function} options.envelopeSearchFn - Apply the envelope expression
|
|
22
|
+
* @param {number} options.timeout - Set the request timeout in milliseconds
|
|
23
|
+
* @param {GenericLogger} options.logger - Log rule engine outcomes without values
|
|
24
|
+
* @example
|
|
25
|
+
* ```typescript
|
|
26
|
+
* import { FeatureFlags } from '@aws-lambda-powertools/feature-flags';
|
|
27
|
+
* import { appConfigAgentStore } from '@aws-lambda-powertools/feature-flags/appconfig-agent';
|
|
28
|
+
* import { search } from '@aws-lambda-powertools/feature-flags/envelope';
|
|
29
|
+
*
|
|
30
|
+
* const store = appConfigAgentStore({
|
|
31
|
+
* application: 'my-app', environment: 'prod', name: 'features',
|
|
32
|
+
* envelope: 'settings.flags', envelopeSearchFn: search,
|
|
33
|
+
* });
|
|
34
|
+
* const flags = new FeatureFlags({ store });
|
|
35
|
+
* const enabled = await flags.evaluate({ name: 'checkout_v2', default: false });
|
|
36
|
+
* ```
|
|
37
|
+
*/
|
|
38
|
+
const appConfigAgentStore = (options) => {
|
|
39
|
+
const envelopeOptions = validateEnvelopeOptions(options);
|
|
40
|
+
return ruleEngineStore({
|
|
41
|
+
name: StoreNames.APPCONFIG_AGENT,
|
|
42
|
+
logger: options.logger,
|
|
43
|
+
source: createDocumentSource({
|
|
44
|
+
storeName: StoreNames.APPCONFIG_AGENT,
|
|
45
|
+
...envelopeOptions,
|
|
46
|
+
retrieve: () => getConfig(options.name, {
|
|
47
|
+
application: options.application,
|
|
48
|
+
environment: options.environment,
|
|
49
|
+
timeout: options.timeout,
|
|
50
|
+
transform: 'json',
|
|
51
|
+
throwOnMissing: true,
|
|
52
|
+
}),
|
|
53
|
+
}),
|
|
54
|
+
});
|
|
55
|
+
};
|
|
56
|
+
export { appConfigAgentStore };
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { AppConfigVariantStoreOptions } from '../types/AppConfigVariantStore.js';
|
|
2
|
+
import type { Store, Variant } from '../types/index.js';
|
|
3
|
+
/**
|
|
4
|
+
* Creates a Store that retrieves Agent-selected AppConfig Variants.
|
|
5
|
+
*
|
|
6
|
+
* Requires AppConfig Agent Lambda extension version `2.0.678` or later and the optional
|
|
7
|
+
* `@aws-lambda-powertools/parameters` peer. The Agent owns evaluation, caching,
|
|
8
|
+
* and polling. A single requested flag in Lambda uses selective retrieval;
|
|
9
|
+
* batches and getAll retrieve the whole profile and select flags locally.
|
|
10
|
+
* Normalizes only requested flags in a batch.
|
|
11
|
+
*
|
|
12
|
+
* Outside Lambda or with `POWERTOOLS_DEV` enabled, every method uses the whole
|
|
13
|
+
* profile from `POWERTOOLS_APPCONFIG_AGENT_RETURN_VALUE`. Set that variable to a
|
|
14
|
+
* flag-keyed JSON object, not an unwrapped single flag.
|
|
15
|
+
*
|
|
16
|
+
* Context keys must match `^[A-Za-z_][A-Za-z0-9_.-]*$`; values must be strings,
|
|
17
|
+
* finite numbers, or booleans. Rejects arrays and invalid context before retrieval.
|
|
18
|
+
* Parameters JSON-quotes and ASCII-escapes strings in the Agent Context header.
|
|
19
|
+
*
|
|
20
|
+
* @param {Object} options - Configure retrieval and logging
|
|
21
|
+
* @param {string} options.name - Identify the configuration profile
|
|
22
|
+
* @param {string} options.environment - Identify the environment
|
|
23
|
+
* @param {string} options.application - Identify the application or use the service name
|
|
24
|
+
* @param {number} options.timeout - Set the request timeout in milliseconds
|
|
25
|
+
* @param {GenericLogger} options.logger - Log selected Variant names without values
|
|
26
|
+
* @example
|
|
27
|
+
* ```typescript
|
|
28
|
+
* const flags = new FeatureFlags({
|
|
29
|
+
* store: appConfigVariantStore({ environment: 'prod', name: 'features' }),
|
|
30
|
+
* });
|
|
31
|
+
* const ui = await flags.evaluate({
|
|
32
|
+
* name: 'ui_refresh', context: { tier: 'premium' }, default: disabledVariant(),
|
|
33
|
+
* });
|
|
34
|
+
* ```
|
|
35
|
+
*/
|
|
36
|
+
declare const appConfigVariantStore: (options: AppConfigVariantStoreOptions) => Store<Variant>;
|
|
37
|
+
/**
|
|
38
|
+
* Creates a fresh disabled Variant fallback with no attributes.
|
|
39
|
+
* @example
|
|
40
|
+
* ```typescript
|
|
41
|
+
* const ui = await flags.evaluate({ name: 'ui_refresh', default: disabledVariant() });
|
|
42
|
+
* ```
|
|
43
|
+
*/
|
|
44
|
+
declare const disabledVariant: () => Variant;
|
|
45
|
+
export { appConfigVariantStore, disabledVariant };
|
|
46
|
+
//# sourceMappingURL=appConfigVariantStore.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"appConfigVariantStore.d.ts","sourceRoot":"","sources":["../../../src/appconfig-agent/appConfigVariantStore.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACtF,OAAO,KAAK,EAIV,KAAK,EAEL,OAAO,EACR,MAAM,mBAAmB,CAAC;AAG3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,QAAA,MAAM,qBAAqB,GACzB,SAAS,4BAA4B,KACpC,KAAK,CAAC,OAAO,CAsEf,CAAC;AAqEF;;;;;;GAMG;AACH,QAAA,MAAM,eAAe,QAAO,OAI1B,CAAC;AAEH,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,CAAC"}
|