Fb/better interface (#40)

* start of main export re-write

* more small re-write stuff

* polish some ide warnings

* remove unused interface

* start with tests

* more re-work and polish

* tests work again

* remove dynamic controller

* new api in example cap server

* re-write docs for new interface

* some consistency fixes

* use shorter toggles config naming in docs

* slightly better text in jsdocs

* fix jsdocs for function with spread arg in signature

* use constructor, when you need the class

* remove unused code

* more cleanup

* again re-naming the default config filepath

* remove tests alongside code for expiring lazy cache

* remove old static class field

* one more change because you cannot call the static method readConfigFromFile on an instance

* remove unused imports

* go back to named import over spreading and constructor access

Author: rlindner81

cds-plugin.js

@@ -3,7 +3,7 @@
 
 const cds = require("@sap/cds");
 const cdsPackage = require("@sap/cds/package.json");
-const { initializeFeatures, getFeaturesKeys, getFeatureValue } = require("./src/singleton");
+const toggles = require("./src/");
 const { closeMainClient, closeSubscriberClient } = require("./src/redisWrapper");
 
 const FEATURE_KEY_REGEX = /\/fts\/([^\s/]+)$/;
@@ -23,7 +23,7 @@ const _registerFeatureProvider = () => {
   if (!cds.env.requires?.toggles) {
     return;
   }
-  const cdsFeatures = getFeaturesKeys().reduce((result, key) => {
+  const cdsFeatures = toggles.getFeaturesKeys().reduce((result, key) => {
     const match = FEATURE_KEY_REGEX.exec(key);
     if (match) {
       const feature = match[1];
@@ -42,7 +42,7 @@ const _registerFeatureProvider = () => {
         req.headers.features ||
         cds.context?.user?.features ||
         cdsFeatures.reduce((result, [key, feature]) => {
-          if (getFeatureValue(key, { user, tenant })) {
+          if (toggles.getFeatureValue(key, { user, tenant })) {
             result.push(feature);
           }
           return result;
@@ -68,7 +68,7 @@ const activate = async () => {
   _registerClientCloseOnShutdown();
 
   // TODO for the "cds build" use case, this initialize makes no sense
-  await initializeFeatures({
+  await toggles.initializeFeatures({
     config: envFeatureToggles.config,
     configFile: envFeatureToggles.configFile,
   });

docs/usage/index.md

@@ -25,11 +25,12 @@ const { FeatureToggles } = require("@cap-js-community/feature-toggle-library");
 const instance = new FeatureToggles({ uniqueName: "snowflake" });
 ```
 
-The library prepares a convenient `singleton` instance of FeatureToggles for out-of-the-box usage, where the Cloud
-Foundry _app name_ is used as unique name. This should be sufficient for most use-cases.
+The library prepares a convenient singleton instance of FeatureToggles for out-of-the-box usage, where the Cloud
+Foundry _app name_ is used as unique name. This should be sufficient for most use-cases and is the default export of
+the library.
 
 ```javascript
-const { singleton } = require("@cap-js-community/feature-toggle-library");
+const toggles = require("@cap-js-community/feature-toggle-library");
 ```
 
 {: .warn }
@@ -134,8 +135,8 @@ initialization settings are in `package.json`. For example:
 ```
 
 In this example, the path `./srv/feature/feature.yaml` points to the previously discussed configuration file. With
-these settings in place, the `singleton` instance of the library will be initialized and is ready for usage at and
-after the [bootstrap](https://cap.cloud.sap/cap/docs/node.js/cds-server#bootstrap) event.
+these settings in place, the singleton instance of the library will be initialized and is ready for usage at and after
+the [bootstrap](https://cap.cloud.sap/cap/docs/node.js/cds-server#bootstrap) event.
 
 {: .info }
 Using the feature toggles in CAP projects also enables a [REST service]({{ site.baseurl }}/plugin/), where toggles can
@@ -147,24 +148,20 @@ Other projects will need to use the corresponding filepath, in order to initiali
 
 ```javascript
 const pathlib = require("path");
-const {
-  singleton: { initializeFeatures },
-} = require("@cap-js-community/feature-toggle-library");
-const FEATURES_FILEPATH = pathlib.join(__dirname, "featureTogglesConfig.yml");
+const toggles = require("@cap-js-community/feature-toggle-library");
+const FEATURES_FILEPATH = pathlib.join(__dirname, ".toggles.yml");
 
 // ... during application bootstrap
-await initializeFeatures({ configFile: FEATURES_FILEPATH });
+await toggles.initializeFeatures({ configFile: FEATURES_FILEPATH });
 ```
 
 Alternatively, a runtime configuration object is also supported.
 
 ```javascript
-const {
-  singleton: { initializeFeatures },
-} = require("@cap-js-community/feature-toggle-library");
+const toggles = require("@cap-js-community/feature-toggle-library");
 
 // ... during application bootstrap
-await initializeFeatures({
+await toggles.initializeFeatures({
   config: {
     runNewCode: {
       type: "boolean",
@@ -183,16 +180,14 @@ feature toggles.
 
 ```javascript
 const pathlib = require("path");
-const {
-  singleton: { initializeFeatures },
-  readConfigFromFile,
-} = require("@cap-js-community/feature-toggle-library");
-const FEATURES_FILEPATH = pathlib.join(__dirname, "featureTogglesConfig.yml");
+const toggles = require("@cap-js-community/feature-toggle-library");
+const FEATURES_FILEPATH = pathlib.join(__dirname, ".toggles.yml");
+const { FeatureToggles } = toggles;
 
 // ... during application bootstrap
-const config = await readConfigFromFile(FEATURES_FILEPATH);
+const config = await FeatureToggles.readConfigFromFile(FEATURES_FILEPATH);
 // ... manipulate
-await initializeFeatures({ config });
+await toggles.initializeFeatures({ config });
 ```
 
 ## Integration Mode
@@ -232,41 +227,36 @@ a feature toggle with the key `/srv/util/logger/logLevel`, similar to the one de
 You can read the current in memory state of any feature toggle:
 
 ```javascript
-const {
-  singleton: { getFeatureValue },
-} = require("@cap-js-community/feature-toggle-library");
+const toggles = require("@cap-js-community/feature-toggle-library");
 
 // ... in some function
-const logLevel = getFeatureValue("/srv/util/logger/logLevel");
+const logLevel = toggles.getFeatureValue("/srv/util/logger/logLevel");
 
 // ... with runtime scope information
-const logLevel = getFeatureValue("/srv/util/logger/logLevel", {
+const logLevel = toggles.getFeatureValue("/srv/util/logger/logLevel", {
   tenant: cds.context.tenant,
   user: cds.context.user.id,
 });
 ```
 
 {: .warn }
 While `getFeatureValue` is synchronous, and could happen on the top-level of a module. The function will throw, if it
-is called _before_ `initializeFeatures`, which is asynchronous. So, it's never sensible to have this on
-top-level.
+is called _before_ `initializeFeatures`, which is asynchronous. So, it's never sensible to have this on top-level.
 
 ### Observing Feature Value Changes
 
 You can register a callback for all updates to a feature toggle:
 
 ```javascript
-const {
-  singleton: { registerFeatureValueChangeHandler },
-} = require("@cap-js-community/feature-toggle-library");
+const toggles = require("@cap-js-community/feature-toggle-library");
 
-registerFeatureValueChangeHandler("/srv/util/logger/logLevel", (newValue, oldValue, scopeMap) => {
+toggles.registerFeatureValueChangeHandler("/srv/util/logger/logLevel", (newValue, oldValue, scopeMap) => {
   console.log("changing log level from %s to %s (scope %j)", oldValue, newValue, scopeMap);
   updateLogLevel(newValue);
 });
 
 // ... or for async APIs
-registerFeatureValueChangeHandler("/srv/util/logger/logLevel", async (newValue, oldValue, scopeMap) => {
+toggles.registerFeatureValueChangeHandler("/srv/util/logger/logLevel", async (newValue, oldValue, scopeMap) => {
   await updateLogLevel(newValue);
 });
 ```
@@ -279,13 +269,11 @@ Registering any callback will not require that the feature toggles are initializ
 Finally, updating the feature toggle value:
 
 ```javascript
-const {
-  singleton: { changeFeatureValue },
-} = require("@cap-js-community/feature-toggle-library");
+const toggles = require("@cap-js-community/feature-toggle-library");
 
 // optionally pass in a scopeMap, which describes the least specific scope where the change should happen
 async function changeIt(newValue, scopeMap) {
-  const validationErrors = await changeFeatureValue("/srv/util/logger/logLevel", newValue, scopeMap);
+  const validationErrors = await toggles.changeFeatureValue("/srv/util/logger/logLevel", newValue, scopeMap);
   if (Array.isArray(validationErrors) && validationErrors.length > 0) {
     for (const { errorMessage, errorMessageValues } of validationErrors) {
       // show errors to the user, the change did not happen
@@ -306,7 +294,7 @@ scope-combination, which overrides that value, then you can use the option `{ cl
 argument. For example
 
 ```javascript
-await changeFeatureValue("/srv/util/logger/logLevel", "error", {}, { clearSubScopes: true });
+await toggles.changeFeatureValue("/srv/util/logger/logLevel", "error", {}, { clearSubScopes: true });
 ```
 
 will set the root-scope value to `"error"` and remove all sub-scopes. See
@@ -318,15 +306,13 @@ There is a convenience reset API just to reset a feature toggle and remove all a
 the feature toggle afterward will only yield the fallback value until new changes are made.
 
 ```javascript
-const {
-  singleton: { resetFeatureValue, changeFeatureValue },
-} = require("@cap-js-community/feature-toggle-library");
+const toggles = require("@cap-js-community/feature-toggle-library");
 
 // ... in some function
-await resetFeatureValue("/srv/util/logger/logLevel");
+await toggles.resetFeatureValue("/srv/util/logger/logLevel");
 
 // this is functionally equivalent to
-await changeFeatureValue("/srv/util/logger/logLevel", null, {}, { clearSubScopes: true });
+await toggles.changeFeatureValue("/srv/util/logger/logLevel", null, {}, { clearSubScopes: true });
 ```
 
 ### External Validation
@@ -335,11 +321,9 @@ The `string`-type feature toggles can theoretically encode very complex data str
 inputs in-depth before allowing changes to be published and propagated.
 
 ```javascript
-const {
-  singleton: { registerFeatureValueValidation },
-} = require("@cap-js-community/feature-toggle-library");
+const toggles = require("@cap-js-community/feature-toggle-library");
 
-registerFeatureValueValidation("/srv/util/logger/logLevel", (newValue) => {
+toggles.registerFeatureValueValidation("/srv/util/logger/logLevel", (newValue) => {
   if (isBad(newValue)) {
     return { errorMessage: "got bad value" };
   }

example-cap-server/srv/memoryStatistics.js

@@ -3,13 +3,11 @@
 const { format } = require("util");
 
 const cds = require("@sap/cds");
-const {
-  singleton: { registerFeatureValueChangeHandler, getFeatureValue },
-  DynamicIntervalController,
-} = require("@cap-js-community/feature-toggle-library");
+const toggles = require("@cap-js-community/feature-toggle-library");
 const { MEM_STAT_LOG_INTERVAL } = require("./feature");
 
 const logger = cds.log("memoryStatistics");
+let intervalId;
 
 const _logStatistics = () => {
   const memoryUsage = process.memoryUsage?.();
@@ -18,20 +16,20 @@ const _logStatistics = () => {
   }
 };
 
+const _updateValue = (newValue) => {
+  if (intervalId) {
+    clearInterval(intervalId);
+  }
+  if (newValue > 0) {
+    intervalId = setInterval(_logStatistics, newValue);
+  }
+};
+
 const initializeMemoryStatistics = () => {
-  const value = getFeatureValue(MEM_STAT_LOG_INTERVAL);
-  const logIntervalController = new DynamicIntervalController(_logStatistics, value > 0, value);
-
-  registerFeatureValueChangeHandler(MEM_STAT_LOG_INTERVAL, (newValue) => {
-    if (newValue <= 0) {
-      logIntervalController.setActive(false);
-    } else {
-      logIntervalController.setWaitInterval(newValue);
-      logIntervalController.setActive(true);
-    }
-  });
-
-  return logIntervalController;
+  const value = toggles.getFeatureValue(MEM_STAT_LOG_INTERVAL);
+  _updateValue(value);
+
+  toggles.registerFeatureValueChangeHandler(MEM_STAT_LOG_INTERVAL, _updateValue);
 };
 
 module.exports = {

example-cap-server/srv/service/check-service.js

@@ -1,8 +1,6 @@
 "use strict";
 
-const {
-  singleton: { getFeatureValue },
-} = require("@cap-js-community/feature-toggle-library");
+const toggles = require("@cap-js-community/feature-toggle-library");
 
 const { CHECK_API_PRIORITY } = require("../feature");
 
@@ -17,7 +15,7 @@ const HIGH_BOUNDARY = 100;
 const priorityHandler = async (context) => {
   const { "CheckService.priority": priority } = context.model.definitions;
   const isToggled = Boolean(priority["@marked"]);
-  const value = getFeatureValue(CHECK_API_PRIORITY, { user: context.user.id, tenant: context.tenant });
+  const value = toggles.getFeatureValue(CHECK_API_PRIORITY, { user: context.user.id, tenant: context.tenant });
   const messages =
     value >= HIGH_BOUNDARY
       ? HIGH_VALUE_RESPONSES

src/env.js

@@ -3,12 +3,7 @@
 const { ENV } = require("./shared/static");
 
 class CfEnv {
-  isOnCf;
-  cfApp;
-  cfServices;
-  cfInstanceGuid;
-  cfInstanceIp;
-  cfInstanceIndex;
+  static __instance;
 
   static parseEnvVar(env, envVar) {
     try {
@@ -35,9 +30,9 @@ class CfEnv {
   }
 
   /**
-   * @return CfEnv
+   * @returns {CfEnv}
    */
-  static get instance() {
+  static getInstance() {
     if (!CfEnv.__instance) {
       CfEnv.__instance = new CfEnv();
     }
@@ -57,7 +52,4 @@ class CfEnv {
   }
 }
 
-module.exports = {
-  CfEnv,
-  cfEnv: CfEnv.instance,
-};
+module.exports = CfEnv.getInstance();