@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.
Files changed (197) hide show
  1. package/README.md +70 -4
  2. package/lib/cjs/FeatureFlags.d.ts +98 -0
  3. package/lib/cjs/FeatureFlags.d.ts.map +1 -0
  4. package/lib/cjs/FeatureFlags.js +260 -0
  5. package/lib/cjs/appconfig/appConfigStore.d.ts +38 -0
  6. package/lib/cjs/appconfig/appConfigStore.d.ts.map +1 -0
  7. package/lib/cjs/appconfig/appConfigStore.js +65 -0
  8. package/lib/cjs/appconfig/index.d.ts +4 -0
  9. package/lib/cjs/appconfig/index.d.ts.map +1 -0
  10. package/lib/cjs/appconfig/index.js +5 -0
  11. package/lib/cjs/appconfig-agent/appConfigAgentStore.d.ts +37 -0
  12. package/lib/cjs/appconfig-agent/appConfigAgentStore.d.ts.map +1 -0
  13. package/lib/cjs/appconfig-agent/appConfigAgentStore.js +59 -0
  14. package/lib/cjs/appconfig-agent/appConfigVariantStore.d.ts +46 -0
  15. package/lib/cjs/appconfig-agent/appConfigVariantStore.d.ts.map +1 -0
  16. package/lib/cjs/appconfig-agent/appConfigVariantStore.js +176 -0
  17. package/lib/cjs/appconfig-agent/index.d.ts +6 -0
  18. package/lib/cjs/appconfig-agent/index.d.ts.map +1 -0
  19. package/lib/cjs/appconfig-agent/index.js +8 -0
  20. package/lib/cjs/constants.d.ts +56 -0
  21. package/lib/cjs/constants.d.ts.map +1 -0
  22. package/lib/cjs/constants.js +86 -0
  23. package/lib/cjs/context.d.ts +21 -0
  24. package/lib/cjs/context.d.ts.map +1 -0
  25. package/lib/cjs/context.js +42 -0
  26. package/lib/cjs/envelope/index.d.ts +20 -0
  27. package/lib/cjs/envelope/index.d.ts.map +1 -0
  28. package/lib/cjs/envelope/index.js +29 -0
  29. package/lib/cjs/errors.d.ts +74 -0
  30. package/lib/cjs/errors.d.ts.map +1 -0
  31. package/lib/cjs/errors.js +116 -0
  32. package/lib/cjs/index.d.ts +6 -0
  33. package/lib/cjs/index.d.ts.map +1 -0
  34. package/lib/cjs/index.js +15 -0
  35. package/lib/cjs/package.json +1 -0
  36. package/lib/cjs/parameters-stores/classify.d.ts +20 -0
  37. package/lib/cjs/parameters-stores/classify.d.ts.map +1 -0
  38. package/lib/cjs/parameters-stores/classify.js +50 -0
  39. package/lib/cjs/parameters-stores/createDocumentSource.d.ts +17 -0
  40. package/lib/cjs/parameters-stores/createDocumentSource.d.ts.map +1 -0
  41. package/lib/cjs/parameters-stores/createDocumentSource.js +31 -0
  42. package/lib/cjs/parameters-stores/envelope.d.ts +22 -0
  43. package/lib/cjs/parameters-stores/envelope.d.ts.map +1 -0
  44. package/lib/cjs/parameters-stores/envelope.js +39 -0
  45. package/lib/cjs/ruleEngine/actions.d.ts +5 -0
  46. package/lib/cjs/ruleEngine/actions.d.ts.map +1 -0
  47. package/lib/cjs/ruleEngine/actions.js +155 -0
  48. package/lib/cjs/ruleEngine/datetime.d.ts +12 -0
  49. package/lib/cjs/ruleEngine/datetime.d.ts.map +1 -0
  50. package/lib/cjs/ruleEngine/datetime.js +134 -0
  51. package/lib/cjs/ruleEngine/evaluate.d.ts +15 -0
  52. package/lib/cjs/ruleEngine/evaluate.d.ts.map +1 -0
  53. package/lib/cjs/ruleEngine/evaluate.js +60 -0
  54. package/lib/cjs/ruleEngine/guards.d.ts +51 -0
  55. package/lib/cjs/ruleEngine/guards.d.ts.map +1 -0
  56. package/lib/cjs/ruleEngine/guards.js +123 -0
  57. package/lib/cjs/ruleEngine/index.d.ts +35 -0
  58. package/lib/cjs/ruleEngine/index.d.ts.map +1 -0
  59. package/lib/cjs/ruleEngine/index.js +70 -0
  60. package/lib/cjs/ruleEngine/json.d.ts +16 -0
  61. package/lib/cjs/ruleEngine/json.d.ts.map +1 -0
  62. package/lib/cjs/ruleEngine/json.js +38 -0
  63. package/lib/cjs/ruleEngine/time.d.ts +14 -0
  64. package/lib/cjs/ruleEngine/time.d.ts.map +1 -0
  65. package/lib/cjs/ruleEngine/time.js +102 -0
  66. package/lib/cjs/ruleEngine/validate.d.ts +11 -0
  67. package/lib/cjs/ruleEngine/validate.d.ts.map +1 -0
  68. package/lib/cjs/ruleEngine/validate.js +134 -0
  69. package/lib/cjs/ruleEngine/validateScheduleAndModulo.d.ts +13 -0
  70. package/lib/cjs/ruleEngine/validateScheduleAndModulo.d.ts.map +1 -0
  71. package/lib/cjs/ruleEngine/validateScheduleAndModulo.js +38 -0
  72. package/lib/cjs/ruleEngine/validationCache.d.ts +12 -0
  73. package/lib/cjs/ruleEngine/validationCache.d.ts.map +1 -0
  74. package/lib/cjs/ruleEngine/validationCache.js +29 -0
  75. package/lib/cjs/types/AppConfigAgentStore.d.ts +20 -0
  76. package/lib/cjs/types/AppConfigAgentStore.d.ts.map +1 -0
  77. package/lib/cjs/types/AppConfigAgentStore.js +2 -0
  78. package/lib/cjs/types/AppConfigStore.d.ts +25 -0
  79. package/lib/cjs/types/AppConfigStore.d.ts.map +1 -0
  80. package/lib/cjs/types/AppConfigStore.js +2 -0
  81. package/lib/cjs/types/AppConfigVariantStore.d.ts +16 -0
  82. package/lib/cjs/types/AppConfigVariantStore.d.ts.map +1 -0
  83. package/lib/cjs/types/AppConfigVariantStore.js +2 -0
  84. package/lib/cjs/types/Envelope.d.ts +16 -0
  85. package/lib/cjs/types/Envelope.d.ts.map +1 -0
  86. package/lib/cjs/types/Envelope.js +2 -0
  87. package/lib/cjs/types/RuleEngine.d.ts +83 -0
  88. package/lib/cjs/types/RuleEngine.d.ts.map +1 -0
  89. package/lib/cjs/types/RuleEngine.js +2 -0
  90. package/lib/cjs/types/VariantEvaluation.d.ts +20 -0
  91. package/lib/cjs/types/VariantEvaluation.d.ts.map +1 -0
  92. package/lib/cjs/types/VariantEvaluation.js +2 -0
  93. package/lib/cjs/types/index.d.ts +81 -0
  94. package/lib/cjs/types/index.d.ts.map +1 -0
  95. package/lib/cjs/types/index.js +2 -0
  96. package/lib/cjs/variant.d.ts +9 -0
  97. package/lib/cjs/variant.d.ts.map +1 -0
  98. package/lib/cjs/variant.js +26 -0
  99. package/lib/esm/FeatureFlags.d.ts +98 -0
  100. package/lib/esm/FeatureFlags.d.ts.map +1 -0
  101. package/lib/esm/FeatureFlags.js +257 -0
  102. package/lib/esm/appconfig/appConfigStore.d.ts +38 -0
  103. package/lib/esm/appconfig/appConfigStore.d.ts.map +1 -0
  104. package/lib/esm/appconfig/appConfigStore.js +62 -0
  105. package/lib/esm/appconfig/index.d.ts +4 -0
  106. package/lib/esm/appconfig/index.d.ts.map +1 -0
  107. package/lib/esm/appconfig/index.js +1 -0
  108. package/lib/esm/appconfig-agent/appConfigAgentStore.d.ts +37 -0
  109. package/lib/esm/appconfig-agent/appConfigAgentStore.d.ts.map +1 -0
  110. package/lib/esm/appconfig-agent/appConfigAgentStore.js +56 -0
  111. package/lib/esm/appconfig-agent/appConfigVariantStore.d.ts +46 -0
  112. package/lib/esm/appconfig-agent/appConfigVariantStore.d.ts.map +1 -0
  113. package/lib/esm/appconfig-agent/appConfigVariantStore.js +172 -0
  114. package/lib/esm/appconfig-agent/index.d.ts +6 -0
  115. package/lib/esm/appconfig-agent/index.d.ts.map +1 -0
  116. package/lib/esm/appconfig-agent/index.js +2 -0
  117. package/lib/esm/constants.d.ts +56 -0
  118. package/lib/esm/constants.d.ts.map +1 -0
  119. package/lib/esm/constants.js +77 -0
  120. package/lib/esm/context.d.ts +21 -0
  121. package/lib/esm/context.d.ts.map +1 -0
  122. package/lib/esm/context.js +37 -0
  123. package/lib/esm/envelope/index.d.ts +20 -0
  124. package/lib/esm/envelope/index.d.ts.map +1 -0
  125. package/lib/esm/envelope/index.js +26 -0
  126. package/lib/esm/errors.d.ts +74 -0
  127. package/lib/esm/errors.d.ts.map +1 -0
  128. package/lib/esm/errors.js +107 -0
  129. package/lib/esm/index.d.ts +6 -0
  130. package/lib/esm/index.d.ts.map +1 -0
  131. package/lib/esm/index.js +3 -0
  132. package/lib/esm/package.json +1 -0
  133. package/lib/esm/parameters-stores/classify.d.ts +20 -0
  134. package/lib/esm/parameters-stores/classify.d.ts.map +1 -0
  135. package/lib/esm/parameters-stores/classify.js +47 -0
  136. package/lib/esm/parameters-stores/createDocumentSource.d.ts +17 -0
  137. package/lib/esm/parameters-stores/createDocumentSource.d.ts.map +1 -0
  138. package/lib/esm/parameters-stores/createDocumentSource.js +28 -0
  139. package/lib/esm/parameters-stores/envelope.d.ts +22 -0
  140. package/lib/esm/parameters-stores/envelope.d.ts.map +1 -0
  141. package/lib/esm/parameters-stores/envelope.js +35 -0
  142. package/lib/esm/ruleEngine/actions.d.ts +5 -0
  143. package/lib/esm/ruleEngine/actions.d.ts.map +1 -0
  144. package/lib/esm/ruleEngine/actions.js +152 -0
  145. package/lib/esm/ruleEngine/datetime.d.ts +12 -0
  146. package/lib/esm/ruleEngine/datetime.d.ts.map +1 -0
  147. package/lib/esm/ruleEngine/datetime.js +131 -0
  148. package/lib/esm/ruleEngine/evaluate.d.ts +15 -0
  149. package/lib/esm/ruleEngine/evaluate.d.ts.map +1 -0
  150. package/lib/esm/ruleEngine/evaluate.js +57 -0
  151. package/lib/esm/ruleEngine/guards.d.ts +51 -0
  152. package/lib/esm/ruleEngine/guards.d.ts.map +1 -0
  153. package/lib/esm/ruleEngine/guards.js +113 -0
  154. package/lib/esm/ruleEngine/index.d.ts +35 -0
  155. package/lib/esm/ruleEngine/index.d.ts.map +1 -0
  156. package/lib/esm/ruleEngine/index.js +67 -0
  157. package/lib/esm/ruleEngine/json.d.ts +16 -0
  158. package/lib/esm/ruleEngine/json.d.ts.map +1 -0
  159. package/lib/esm/ruleEngine/json.js +34 -0
  160. package/lib/esm/ruleEngine/time.d.ts +14 -0
  161. package/lib/esm/ruleEngine/time.d.ts.map +1 -0
  162. package/lib/esm/ruleEngine/time.js +97 -0
  163. package/lib/esm/ruleEngine/validate.d.ts +11 -0
  164. package/lib/esm/ruleEngine/validate.d.ts.map +1 -0
  165. package/lib/esm/ruleEngine/validate.js +131 -0
  166. package/lib/esm/ruleEngine/validateScheduleAndModulo.d.ts +13 -0
  167. package/lib/esm/ruleEngine/validateScheduleAndModulo.d.ts.map +1 -0
  168. package/lib/esm/ruleEngine/validateScheduleAndModulo.js +35 -0
  169. package/lib/esm/ruleEngine/validationCache.d.ts +12 -0
  170. package/lib/esm/ruleEngine/validationCache.d.ts.map +1 -0
  171. package/lib/esm/ruleEngine/validationCache.js +26 -0
  172. package/lib/esm/types/AppConfigAgentStore.d.ts +20 -0
  173. package/lib/esm/types/AppConfigAgentStore.d.ts.map +1 -0
  174. package/lib/esm/types/AppConfigStore.d.ts +25 -0
  175. package/lib/esm/types/AppConfigStore.d.ts.map +1 -0
  176. package/lib/esm/types/AppConfigStore.js +1 -0
  177. package/lib/esm/types/AppConfigVariantStore.d.ts +16 -0
  178. package/lib/esm/types/AppConfigVariantStore.d.ts.map +1 -0
  179. package/lib/esm/types/AppConfigVariantStore.js +1 -0
  180. package/lib/esm/types/Envelope.d.ts +16 -0
  181. package/lib/esm/types/Envelope.d.ts.map +1 -0
  182. package/lib/esm/types/Envelope.js +1 -0
  183. package/lib/esm/types/RuleEngine.d.ts +83 -0
  184. package/lib/esm/types/RuleEngine.d.ts.map +1 -0
  185. package/lib/esm/types/RuleEngine.js +1 -0
  186. package/lib/esm/types/VariantEvaluation.d.ts +20 -0
  187. package/lib/esm/types/VariantEvaluation.d.ts.map +1 -0
  188. package/lib/esm/types/VariantEvaluation.js +1 -0
  189. package/lib/esm/types/index.d.ts +81 -0
  190. package/lib/esm/types/index.d.ts.map +1 -0
  191. package/lib/esm/types/index.js +1 -0
  192. package/lib/esm/variant.d.ts +9 -0
  193. package/lib/esm/variant.d.ts.map +1 -0
  194. package/lib/esm/variant.js +21 -0
  195. package/package.json +133 -13
  196. package/lib/index.js +0 -3
  197. /package/lib/{index.d.ts → esm/types/AppConfigAgentStore.js} +0 -0
@@ -0,0 +1,15 @@
1
+ import type { StoreResult } from '../types/index.js';
2
+ import type { EvaluateFlagOptions, Flag } from '../types/RuleEngine.js';
3
+ /**
4
+ * Evaluates one flag using its first fully matching Rule or its Flag Default.
5
+ * @param name - Identify the flag
6
+ * @param flag - Supply the validated flag definition
7
+ * @param {Object} options - Configure evaluation facts, logging, and the clock
8
+ * @param {EvaluationContext} options.context - Supply caller facts for evaluation
9
+ * @param {GenericLogger} options.logger - Log the selected Rule or Flag Default without values
10
+ * @param {Date} options.now - Supply the Store call's shared clock instant
11
+ * @internal
12
+ */
13
+ declare const evaluate: (name: string, flag: Flag, { context, logger, now }: EvaluateFlagOptions) => StoreResult;
14
+ export { evaluate };
15
+ //# sourceMappingURL=evaluate.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../../src/ruleEngine/evaluate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAEV,mBAAmB,EACnB,IAAI,EAEL,MAAM,wBAAwB,CAAC;AAKhC;;;;;;;;;GASG;AACH,QAAA,MAAM,QAAQ,GACZ,MAAM,MAAM,EACZ,MAAM,IAAI,EACV,0BAA0B,mBAAmB,KAC5C,WAoBF,CAAC;AA4BF,OAAO,EAAE,QAAQ,EAAE,CAAC"}
@@ -0,0 +1,60 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.evaluate = void 0;
4
+ const commons_1 = require("@aws-lambda-powertools/commons");
5
+ const constants_js_1 = require("../constants.js");
6
+ const errors_js_1 = require("../errors.js");
7
+ const actions_js_1 = require("./actions.js");
8
+ const json_js_1 = require("./json.js");
9
+ const time_js_1 = require("./time.js");
10
+ /**
11
+ * Evaluates one flag using its first fully matching Rule or its Flag Default.
12
+ * @param name - Identify the flag
13
+ * @param flag - Supply the validated flag definition
14
+ * @param {Object} options - Configure evaluation facts, logging, and the clock
15
+ * @param {EvaluationContext} options.context - Supply caller facts for evaluation
16
+ * @param {GenericLogger} options.logger - Log the selected Rule or Flag Default without values
17
+ * @param {Date} options.now - Supply the Store call's shared clock instant
18
+ * @internal
19
+ */
20
+ const evaluate = (name, flag, { context, logger, now }) => {
21
+ for (const [rule, definition] of Object.entries(flag.rules)) {
22
+ if (definition.conditions.every((condition) => matches(condition, { name, rule, context, now }))) {
23
+ const value = (0, json_js_1.cloneJSONValue)(definition.when_match);
24
+ logger?.debug({
25
+ store: constants_js_1.StoreNames.RULE_ENGINE,
26
+ name,
27
+ outcome: 'rule',
28
+ rule,
29
+ });
30
+ return { found: true, value, enabled: (0, commons_1.isTruthy)(value) };
31
+ }
32
+ }
33
+ const value = (0, json_js_1.cloneJSONValue)(flag.default);
34
+ logger?.debug({ store: constants_js_1.StoreNames.RULE_ENGINE, name, outcome: 'default' });
35
+ return { found: true, value, enabled: (0, commons_1.isTruthy)(value) };
36
+ };
37
+ exports.evaluate = evaluate;
38
+ /**
39
+ * Applies the shared clock instant to schedule Conditions and own context keys to ordinary Conditions.
40
+ * @param condition - Supply the validated Condition
41
+ * @param {Object} options - Supply identifiers, caller facts, and the clock
42
+ * @param {string} options.name - Identify the flag
43
+ * @param {string} options.rule - Identify the Rule
44
+ * @param {EvaluationContext} options.context - Supply caller facts for evaluation
45
+ * @param {Date} options.now - Supply the Store call's shared clock instant
46
+ * @internal
47
+ */
48
+ const matches = (condition, { name, rule, context, now }) => {
49
+ const { key, action, value } = condition;
50
+ try {
51
+ if ((0, time_js_1.isTimeAction)(action))
52
+ return time_js_1.timeActions[action](value, now);
53
+ if (!Object.hasOwn(context, key))
54
+ return false;
55
+ return actions_js_1.actions[action](context[key], value);
56
+ }
57
+ catch {
58
+ throw new errors_js_1.ConditionEvaluationError(`Flag '${name}', rule '${rule}', key '${key}', action '${action}': incompatible operands`);
59
+ }
60
+ };
@@ -0,0 +1,51 @@
1
+ import type { DatetimeRange, DaysOfWeek, ModuloRange, TimeRange } from '../types/RuleEngine.js';
2
+ /**
3
+ * Identifies malformed modulo objects, integer fields, and inclusive bounds.
4
+ * @param value - Supply the document operand
5
+ * @internal
6
+ */
7
+ declare const getModuloRangeError: (value: unknown) => string | null;
8
+ /**
9
+ * Identifies malformed anchored HH:MM bounds or optional IANA zones.
10
+ * @param value - Supply the document operand
11
+ * @internal
12
+ */
13
+ declare const getTimeRangeError: (value: unknown) => string | null;
14
+ /**
15
+ * Identifies malformed naive ISO bounds or optional IANA zones.
16
+ * @param value - Supply the document operand
17
+ * @internal
18
+ */
19
+ declare const getDatetimeRangeError: (value: unknown) => string | null;
20
+ /**
21
+ * Identifies malformed Python day lists or optional IANA zones.
22
+ * @param value - Supply the document operand
23
+ * @internal
24
+ */
25
+ declare const getDaysOfWeekError: (value: unknown) => string | null;
26
+ /**
27
+ * Narrows complete modulo shapes using the same rules as document validation.
28
+ * @param value - Supply the operand to check
29
+ * @internal
30
+ */
31
+ declare const isModuloRange: (value: unknown) => value is ModuloRange;
32
+ /**
33
+ * Narrows complete time-range shapes, including anchored bounds and valid zones.
34
+ * @param value - Supply the operand to check
35
+ * @internal
36
+ */
37
+ declare const isTimeRange: (value: unknown) => value is TimeRange;
38
+ /**
39
+ * Narrows complete datetime-range shapes, including naive ISO bounds and valid zones.
40
+ * @param value - Supply the operand to check
41
+ * @internal
42
+ */
43
+ declare const isDatetimeRange: (value: unknown) => value is DatetimeRange;
44
+ /**
45
+ * Narrows complete day-list shapes, including Python names and valid zones.
46
+ * @param value - Supply the operand to check
47
+ * @internal
48
+ */
49
+ declare const isDaysOfWeek: (value: unknown) => value is DaysOfWeek;
50
+ export { getDatetimeRangeError, getDaysOfWeekError, getModuloRangeError, getTimeRangeError, isDatetimeRange, isDaysOfWeek, isModuloRange, isTimeRange, };
51
+ //# sourceMappingURL=guards.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../src/ruleEngine/guards.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,WAAW,EACX,SAAS,EACV,MAAM,wBAAwB,CAAC;AAqBhC;;;;GAIG;AACH,QAAA,MAAM,mBAAmB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAiBtD,CAAC;AAqBF;;;;GAIG;AACH,QAAA,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAQlD,CAAC;AAEJ;;;;GAIG;AACH,QAAA,MAAM,qBAAqB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAKtD,CAAC;AAEJ;;;;GAIG;AACH,QAAA,MAAM,kBAAkB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAUrD,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,WACZ,CAAC;AAEtC;;;;GAIG;AACH,QAAA,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,SACZ,CAAC;AAEpC;;;;GAIG;AACH,QAAA,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,aACZ,CAAC;AAExC;;;;GAIG;AACH,QAAA,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,UACZ,CAAC;AAErC,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,WAAW,GACZ,CAAC"}
@@ -0,0 +1,123 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.isTimeRange = exports.isModuloRange = exports.isDaysOfWeek = exports.isDatetimeRange = exports.getTimeRangeError = exports.getModuloRangeError = exports.getDaysOfWeekError = exports.getDatetimeRangeError = void 0;
4
+ const commons_1 = require("@aws-lambda-powertools/commons");
5
+ const constants_js_1 = require("../constants.js");
6
+ const datetime_js_1 = require("./datetime.js");
7
+ /**
8
+ * Identifies invalid optional IANA zones without throwing or exposing values.
9
+ * @param timezone - Supply the optional document timezone
10
+ * @internal
11
+ */
12
+ const getTimezoneError = (timezone) => {
13
+ if (timezone === undefined)
14
+ return null;
15
+ if (!(0, commons_1.isString)(timezone))
16
+ return 'TIMEZONE must be a string';
17
+ try {
18
+ // Intl accepts fixed-offset identifiers, but schedules require named IANA zones.
19
+ if (/^[+-]/.test(timezone))
20
+ return 'TIMEZONE must be a valid IANA timezone';
21
+ new Intl.DateTimeFormat('en-US', { timeZone: timezone });
22
+ return null;
23
+ }
24
+ catch {
25
+ return 'TIMEZONE must be a valid IANA timezone';
26
+ }
27
+ };
28
+ /**
29
+ * Identifies malformed modulo objects, integer fields, and inclusive bounds.
30
+ * @param value - Supply the document operand
31
+ * @internal
32
+ */
33
+ const getModuloRangeError = (value) => {
34
+ if (!(0, commons_1.isRecord)(value))
35
+ return 'value must be an object with BASE, START, and END';
36
+ const { BASE: base, START: start, END: end } = value;
37
+ if (typeof base !== 'number' ||
38
+ !Number.isInteger(base) ||
39
+ typeof start !== 'number' ||
40
+ !Number.isInteger(start) ||
41
+ typeof end !== 'number' ||
42
+ !Number.isInteger(end))
43
+ return 'BASE, START, and END must be integers';
44
+ // Integer END < BASE avoids rounding BASE - 1 while enforcing the same bound.
45
+ if (!(0 <= start && start <= end && end < base))
46
+ return 'must satisfy 0 <= START <= END <= BASE - 1';
47
+ return null;
48
+ };
49
+ exports.getModuloRangeError = getModuloRangeError;
50
+ /**
51
+ * Identifies malformed schedule objects, bounds, and optional timezones.
52
+ * @param value - Supply the document operand
53
+ * @param validateBound - Check one bound's format
54
+ * @param boundError - Identify a malformed bound without its value
55
+ * @internal
56
+ */
57
+ const getRangeError = (value, validateBound, boundError) => {
58
+ if (!(0, commons_1.isRecord)(value))
59
+ return 'value must be an object';
60
+ for (const bound of [value.START, value.END]) {
61
+ if (!validateBound(bound))
62
+ return boundError;
63
+ }
64
+ return getTimezoneError(value.TIMEZONE);
65
+ };
66
+ /**
67
+ * Identifies malformed anchored HH:MM bounds or optional IANA zones.
68
+ * @param value - Supply the document operand
69
+ * @internal
70
+ */
71
+ const getTimeRangeError = (value) => getRangeError(value, (bound) => (0, commons_1.isString)(bound) &&
72
+ bound.length === 5 &&
73
+ /^(?:2[0-3]|[01]\d):[0-5]\d$/.test(bound), 'START and END must use HH:MM');
74
+ exports.getTimeRangeError = getTimeRangeError;
75
+ /**
76
+ * Identifies malformed naive ISO bounds or optional IANA zones.
77
+ * @param value - Supply the document operand
78
+ * @internal
79
+ */
80
+ const getDatetimeRangeError = (value) => getRangeError(value, (bound) => (0, datetime_js_1.parseNaiveDatetime)(bound) !== null, 'START and END must use timezone-naive ISO8601');
81
+ exports.getDatetimeRangeError = getDatetimeRangeError;
82
+ /**
83
+ * Identifies malformed Python day lists or optional IANA zones.
84
+ * @param value - Supply the document operand
85
+ * @internal
86
+ */
87
+ const getDaysOfWeekError = (value) => {
88
+ if (!(0, commons_1.isRecord)(value))
89
+ return 'value must be an object';
90
+ if (!Array.isArray(value.DAYS) ||
91
+ value.DAYS.some((day) => !(0, commons_1.isString)(day) || !constants_js_1.TimeDays.some((validDay) => validDay === day)))
92
+ return 'DAYS must be an array of Python day names';
93
+ return getTimezoneError(value.TIMEZONE);
94
+ };
95
+ exports.getDaysOfWeekError = getDaysOfWeekError;
96
+ /**
97
+ * Narrows complete modulo shapes using the same rules as document validation.
98
+ * @param value - Supply the operand to check
99
+ * @internal
100
+ */
101
+ const isModuloRange = (value) => getModuloRangeError(value) === null;
102
+ exports.isModuloRange = isModuloRange;
103
+ /**
104
+ * Narrows complete time-range shapes, including anchored bounds and valid zones.
105
+ * @param value - Supply the operand to check
106
+ * @internal
107
+ */
108
+ const isTimeRange = (value) => getTimeRangeError(value) === null;
109
+ exports.isTimeRange = isTimeRange;
110
+ /**
111
+ * Narrows complete datetime-range shapes, including naive ISO bounds and valid zones.
112
+ * @param value - Supply the operand to check
113
+ * @internal
114
+ */
115
+ const isDatetimeRange = (value) => getDatetimeRangeError(value) === null;
116
+ exports.isDatetimeRange = isDatetimeRange;
117
+ /**
118
+ * Narrows complete day-list shapes, including Python names and valid zones.
119
+ * @param value - Supply the operand to check
120
+ * @internal
121
+ */
122
+ const isDaysOfWeek = (value) => getDaysOfWeekError(value) === null;
123
+ exports.isDaysOfWeek = isDaysOfWeek;
@@ -0,0 +1,35 @@
1
+ import type { Store } from '../types/index.js';
2
+ import type { RuleEngineStoreOptions } from '../types/RuleEngine.js';
3
+ /**
4
+ * Creates a local {@link Store | `Store`} that evaluates Python-format Flag Documents.
5
+ * Supports Powertools for Python 3.36.0 Actions and missing-key semantics.
6
+ * Uses strict boolean/number equality, throws for incompatible operands, rejects numeric Rule names that JavaScript reorders, and rejects falsy non-object rules.
7
+ *
8
+ * Membership Actions check strict array membership, own object keys, or Unicode code-point substrings.
9
+ * Retrieves the source on every call and propagates source errors unchanged.
10
+ * Keeps only the latest validated, compiled snapshot, keyed by JSON content without sorting keys.
11
+ * Validates the entire document when content changes; invalid replacements throw without replacing the snapshot.
12
+ * Empty-document and empty-rules warnings fire on validation, once per new document content rather than every call.
13
+ * Each call evaluates its captured, owned snapshot and returns copies of structured values.
14
+ * Schedule Actions ignore caller context and read the clock in their IANA timezone, defaulting to UTC.
15
+ * Reads the clock once after retrieving and validating each document, sharing the instant across all flags and Conditions in that call.
16
+ * MODULO_RANGE uses Python's positive-divisor remainder, including negative and fractional contexts.
17
+ *
18
+ * @param {Object} options - Configure retrieval and logging
19
+ * @param {string} options.name - Name the Store, defaulting to `rule-engine`
20
+ * @param {Function} options.source - Retrieve a Flag Document for each Store call
21
+ * @param {GenericLogger} options.logger - Log warnings and outcomes without values
22
+ * @param {Function} options.now - Supply the schedule clock, defaulting to () => new Date()
23
+ * @example
24
+ * ```typescript
25
+ * const store = ruleEngineStore({
26
+ * source: async () => ({ checkout_v2: { default: true } }),
27
+ * });
28
+ * const flags = new FeatureFlags({ store });
29
+ * const enabled = await flags.evaluate({ name: 'checkout_v2', default: false });
30
+ * ```
31
+ */
32
+ declare const ruleEngineStore: ({ source, logger, now, name, }: RuleEngineStoreOptions) => Store;
33
+ export type { RuleEngineStoreOptions } from '../types/RuleEngine.js';
34
+ export { ruleEngineStore };
35
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ruleEngine/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAe,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAKrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,QAAA,MAAM,eAAe,GAAI,gCAKtB,sBAAsB,KAAG,KAiC3B,CAAC;AAEF,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,CAAC"}
@@ -0,0 +1,70 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ruleEngineStore = void 0;
4
+ const constants_js_1 = require("../constants.js");
5
+ const evaluate_js_1 = require("./evaluate.js");
6
+ const time_js_1 = require("./time.js");
7
+ const validationCache_js_1 = require("./validationCache.js");
8
+ /**
9
+ * Creates a local {@link Store | `Store`} that evaluates Python-format Flag Documents.
10
+ * Supports Powertools for Python 3.36.0 Actions and missing-key semantics.
11
+ * Uses strict boolean/number equality, throws for incompatible operands, rejects numeric Rule names that JavaScript reorders, and rejects falsy non-object rules.
12
+ *
13
+ * Membership Actions check strict array membership, own object keys, or Unicode code-point substrings.
14
+ * Retrieves the source on every call and propagates source errors unchanged.
15
+ * Keeps only the latest validated, compiled snapshot, keyed by JSON content without sorting keys.
16
+ * Validates the entire document when content changes; invalid replacements throw without replacing the snapshot.
17
+ * Empty-document and empty-rules warnings fire on validation, once per new document content rather than every call.
18
+ * Each call evaluates its captured, owned snapshot and returns copies of structured values.
19
+ * Schedule Actions ignore caller context and read the clock in their IANA timezone, defaulting to UTC.
20
+ * Reads the clock once after retrieving and validating each document, sharing the instant across all flags and Conditions in that call.
21
+ * MODULO_RANGE uses Python's positive-divisor remainder, including negative and fractional contexts.
22
+ *
23
+ * @param {Object} options - Configure retrieval and logging
24
+ * @param {string} options.name - Name the Store, defaulting to `rule-engine`
25
+ * @param {Function} options.source - Retrieve a Flag Document for each Store call
26
+ * @param {GenericLogger} options.logger - Log warnings and outcomes without values
27
+ * @param {Function} options.now - Supply the schedule clock, defaulting to () => new Date()
28
+ * @example
29
+ * ```typescript
30
+ * const store = ruleEngineStore({
31
+ * source: async () => ({ checkout_v2: { default: true } }),
32
+ * });
33
+ * const flags = new FeatureFlags({ store });
34
+ * const enabled = await flags.evaluate({ name: 'checkout_v2', default: false });
35
+ * ```
36
+ */
37
+ const ruleEngineStore = ({ source, logger, now = time_js_1.currentDate, name = constants_js_1.StoreNames.RULE_ENGINE, }) => {
38
+ const validateDocument = (0, validationCache_js_1.createValidationCache)(logger);
39
+ return {
40
+ name,
41
+ getMany: async (names, context) => {
42
+ const document = validateDocument(await source());
43
+ const instant = now();
44
+ const results = [];
45
+ for (const name of new Set(names)) {
46
+ results.push([
47
+ name,
48
+ Object.hasOwn(document, name)
49
+ ? (0, evaluate_js_1.evaluate)(name, document[name], { context, logger, now: instant })
50
+ : { found: false },
51
+ ]);
52
+ }
53
+ // Object.fromEntries keeps __proto__ and other inherited names as own keys.
54
+ return Object.fromEntries(results);
55
+ },
56
+ getAll: async (context) => {
57
+ const document = validateDocument(await source());
58
+ const instant = now();
59
+ const results = [];
60
+ for (const [name, flag] of Object.entries(document)) {
61
+ results.push([
62
+ name,
63
+ (0, evaluate_js_1.evaluate)(name, flag, { context, logger, now: instant }),
64
+ ]);
65
+ }
66
+ return Object.fromEntries(results);
67
+ },
68
+ };
69
+ };
70
+ exports.ruleEngineStore = ruleEngineStore;
@@ -0,0 +1,16 @@
1
+ import type { JSONValue } from '@aws-lambda-powertools/commons/types';
2
+ /**
3
+ * Checks JSON values at the source boundary, including callers that bypass types.
4
+ * @param value - Supply the value to check
5
+ * @param ancestors - Track containers to reject cycles without rejecting shared values
6
+ * @internal
7
+ */
8
+ declare const isJSONValue: (value: unknown, ancestors?: Set<unknown>) => value is JSONValue;
9
+ /**
10
+ * Copies structured results so callers cannot mutate a cached snapshot.
11
+ * @param value - Supply the validated result value
12
+ * @internal
13
+ */
14
+ declare const cloneJSONValue: (value: JSONValue) => JSONValue;
15
+ export { cloneJSONValue, isJSONValue };
16
+ //# sourceMappingURL=json.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/ruleEngine/json.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAEtE;;;;;GAKG;AACH,QAAA,MAAM,WAAW,GACf,OAAO,OAAO,EACd,wBAA8B,KAC7B,KAAK,IAAI,SAeX,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,cAAc,GAAI,OAAO,SAAS,KAAG,SACmC,CAAC;AAE/E,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC"}
@@ -0,0 +1,38 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.isJSONValue = exports.cloneJSONValue = void 0;
4
+ const commons_1 = require("@aws-lambda-powertools/commons");
5
+ /**
6
+ * Checks JSON values at the source boundary, including callers that bypass types.
7
+ * @param value - Supply the value to check
8
+ * @param ancestors - Track containers to reject cycles without rejecting shared values
9
+ * @internal
10
+ */
11
+ const isJSONValue = (value, ancestors = new Set()) => {
12
+ if ((0, commons_1.isNull)(value) || (0, commons_1.isString)(value) || typeof value === 'boolean')
13
+ return true;
14
+ if ((0, commons_1.isNumber)(value))
15
+ return Number.isFinite(value);
16
+ if (!Array.isArray(value) && !(0, commons_1.isRecord)(value))
17
+ return false;
18
+ // Custom serializers can hide invalid fields or replace content before the cache key is computed.
19
+ if (typeof Reflect.get(value, 'toJSON') === 'function')
20
+ return false;
21
+ if (ancestors.has(value))
22
+ return false;
23
+ ancestors.add(value);
24
+ const entries = Array.isArray(value)
25
+ ? Array.from(value)
26
+ : Object.values(value);
27
+ const valid = entries.every((entry) => isJSONValue(entry, ancestors));
28
+ ancestors.delete(value);
29
+ return valid;
30
+ };
31
+ exports.isJSONValue = isJSONValue;
32
+ /**
33
+ * Copies structured results so callers cannot mutate a cached snapshot.
34
+ * @param value - Supply the validated result value
35
+ * @internal
36
+ */
37
+ const cloneJSONValue = (value) => typeof value === 'object' && value !== null ? structuredClone(value) : value;
38
+ exports.cloneJSONValue = cloneJSONValue;
@@ -0,0 +1,14 @@
1
+ import type { JSONValue } from '@aws-lambda-powertools/commons/types';
2
+ import type { TimeAction } from '../types/RuleEngine.js';
3
+ /**
4
+ * Identifies Actions that ignore caller context and read the clock.
5
+ * @param action - Supply the validated Action
6
+ * @internal
7
+ */
8
+ declare const isTimeAction: (action: string) => action is TimeAction;
9
+ /** Supplies the default clock without reading host-local calendar fields. @internal */
10
+ declare const currentDate: () => Date;
11
+ /** Dispatches schedule Actions after validation, without using context values. @internal */
12
+ declare const timeActions: Record<TimeAction, (value: JSONValue, now: Date) => boolean>;
13
+ export { currentDate, isTimeAction, timeActions };
14
+ //# sourceMappingURL=time.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../../src/ruleEngine/time.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAEtE,OAAO,KAAK,EAEV,UAAU,EAEX,MAAM,wBAAwB,CAAC;AAIhC;;;;GAIG;AACH,QAAA,MAAM,YAAY,GAAI,QAAQ,MAAM,KAAG,MAAM,IAAI,UACV,CAAC;AAExC,uFAAuF;AACvF,QAAA,MAAM,WAAW,QAAO,IAAkB,CAAC;AA0E3C,4FAA4F;AAC5F,QAAA,MAAM,WAAW,EAAE,MAAM,CACvB,UAAU,EACV,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAgBzC,CAAC;AAEF,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC"}
@@ -0,0 +1,102 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.timeActions = exports.isTimeAction = exports.currentDate = void 0;
4
+ const constants_js_1 = require("../constants.js");
5
+ const datetime_js_1 = require("./datetime.js");
6
+ const guards_js_1 = require("./guards.js");
7
+ /**
8
+ * Identifies Actions that ignore caller context and read the clock.
9
+ * @param action - Supply the validated Action
10
+ * @internal
11
+ */
12
+ const isTimeAction = (action) => Object.hasOwn(constants_js_1.TimeActionKeys, action);
13
+ exports.isTimeAction = isTimeAction;
14
+ /** Supplies the default clock without reading host-local calendar fields. @internal */
15
+ const currentDate = () => new Date();
16
+ exports.currentDate = currentDate;
17
+ /**
18
+ * Reads wall-clock fields from an instant in the document's timezone, defaulting to UTC.
19
+ * @param now - Supply the clock instant
20
+ * @param timeZone - Supply the validated IANA zone
21
+ * @internal
22
+ */
23
+ const wallClock = (now, timeZone = 'UTC') => {
24
+ const formatter = new Intl.DateTimeFormat('en-US', {
25
+ timeZone,
26
+ calendar: 'gregory',
27
+ numberingSystem: 'latn',
28
+ hourCycle: 'h23',
29
+ year: 'numeric',
30
+ month: '2-digit',
31
+ day: '2-digit',
32
+ hour: '2-digit',
33
+ minute: '2-digit',
34
+ second: '2-digit',
35
+ fractionalSecondDigits: 3,
36
+ weekday: 'long',
37
+ });
38
+ const fields = {};
39
+ for (const { type, value } of formatter.formatToParts(now))
40
+ fields[type] = value;
41
+ return fields;
42
+ };
43
+ /**
44
+ * Converts HH:MM to full minutes since midnight.
45
+ * @param value - Supply a validated time bound
46
+ * @internal
47
+ */
48
+ const minutesSinceMidnight = (value) => Number(value.slice(0, 2)) * 60 + Number(value.slice(3));
49
+ /**
50
+ * Matches inclusive time bounds, including ranges crossing midnight within one hour.
51
+ * Python replaces only hours/minutes on now, retaining its seconds/microseconds.
52
+ * Comparing minutes therefore includes the entire START and END minutes.
53
+ * @param value - Supply validated schedule bounds
54
+ * @param now - Supply the clock instant
55
+ * @internal
56
+ */
57
+ const compareTimeRange = (value, now) => {
58
+ const fields = wallClock(now, value.TIMEZONE);
59
+ const current = Number(fields.hour) * 60 + Number(fields.minute);
60
+ const start = minutesSinceMidnight(value.START);
61
+ const end = minutesSinceMidnight(value.END);
62
+ return end < start
63
+ ? start <= current || current <= end
64
+ : start <= current && current <= end;
65
+ };
66
+ /**
67
+ * Matches inclusive naive datetime bounds against zoned wall-clock fields.
68
+ * Python attaches the same dateutil tzinfo to START, END, and now. Its datetime
69
+ * comparisons then ignore offsets and fold, comparing wall-clock fields. This
70
+ * deliberately matches both occurrences of a fall-back time and leaves spring
71
+ * gaps unnormalized. Reversed intervals validate but never match.
72
+ * @param value - Supply validated naive datetime bounds and timezone
73
+ * @param now - Supply the clock instant
74
+ * @internal
75
+ */
76
+ const compareDatetimeRange = (value, now) => {
77
+ const fields = wallClock(now, value.TIMEZONE);
78
+ const current = `${fields.year.padStart(4, '0')}-${fields.month}-${fields.day}T${fields.hour}:${fields.minute}:${fields.second}.${fields.fractionalSecond.padEnd(6, '0')}`;
79
+ // Validation guarantees both bounds parse to canonical wall-clock strings.
80
+ const start = (0, datetime_js_1.parseNaiveDatetime)(value.START);
81
+ const end = (0, datetime_js_1.parseNaiveDatetime)(value.END);
82
+ return start <= current && current <= end;
83
+ };
84
+ /** Dispatches schedule Actions after validation, without using context values. @internal */
85
+ const timeActions = {
86
+ [constants_js_1.RuleActions.SCHEDULE_BETWEEN_TIME_RANGE]: (value, now) => {
87
+ if (!(0, guards_js_1.isTimeRange)(value))
88
+ throw new TypeError('Incompatible operands');
89
+ return compareTimeRange(value, now);
90
+ },
91
+ [constants_js_1.RuleActions.SCHEDULE_BETWEEN_DATETIME_RANGE]: (value, now) => {
92
+ if (!(0, guards_js_1.isDatetimeRange)(value))
93
+ throw new TypeError('Incompatible operands');
94
+ return compareDatetimeRange(value, now);
95
+ },
96
+ [constants_js_1.RuleActions.SCHEDULE_BETWEEN_DAYS_OF_WEEK]: (value, now) => {
97
+ if (!(0, guards_js_1.isDaysOfWeek)(value))
98
+ throw new TypeError('Incompatible operands');
99
+ return value.DAYS.includes(wallClock(now, value.TIMEZONE).weekday.toUpperCase());
100
+ },
101
+ };
102
+ exports.timeActions = timeActions;
@@ -0,0 +1,11 @@
1
+ import type { GenericLogger } from '@aws-lambda-powertools/commons/types';
2
+ import type { FlagDocument } from '../types/RuleEngine.js';
3
+ /**
4
+ * Validates an entire Python-format Flag Document and returns typed definitions.
5
+ * @param document - Supply the retrieved document
6
+ * @param logger - Log accepted empty documents and empty Rules without values
7
+ * @internal
8
+ */
9
+ declare const validate: (document: unknown, logger?: GenericLogger) => FlagDocument;
10
+ export { validate };
11
+ //# sourceMappingURL=validate.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/ruleEngine/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EAEd,MAAM,sCAAsC,CAAC;AAG9C,OAAO,KAAK,EAGV,YAAY,EAGb,MAAM,wBAAwB,CAAC;AAIhC;;;;;GAKG;AACH,QAAA,MAAM,QAAQ,GAAI,UAAU,OAAO,EAAE,SAAS,aAAa,KAAG,YA+B7D,CAAC;AAuIF,OAAO,EAAE,QAAQ,EAAE,CAAC"}