@openmrs/esm-config 4.0.0-pre.0 → 4.0.1-pre.206

package/src/module-config/module-config.test.ts

@@ -12,7 +12,6 @@ import {
   ConfigInternalStore,
   configInternalStore,
   getExtensionConfig,
-  getExtensionsConfigStore,
   ImplementerToolsConfigStore,
   implementerToolsConfigStore,
   temporaryConfigStore,
@@ -101,6 +100,33 @@ describe("defineConfigSchema", () => {
     expect(console.error).not.toHaveBeenCalled();
   });
 
+  it("runs top-level validators on filled-in config", () => {
+    const schema = {
+      foo: {
+        _type: Type.String,
+        _default: "bar-value",
+      },
+      fooStart: {
+        _type: Type.String,
+        _default: "bar",
+      },
+      _validators: [
+        validator(
+          (v) => v.foo.startsWith(v.fooStart),
+          (v) =>
+            `The value of \`foo\` must start with the value of \`fooStart\` (which is ${v.fooStart}).`
+        ),
+      ],
+    };
+    Config.defineConfigSchema("foo-module", schema);
+    Config.provide({ "foo-module": { foo: "different" } });
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringMatching(
+        /The value of `foo` must start with the value of `fooStart`.*bar/
+      )
+    );
+  });
+
   it("logs an error if a non-function validator is provided", () => {
     const schema = {
       bar: { _default: [], _validators: [false] },
@@ -175,6 +201,20 @@ describe("defineConfigSchema", () => {
     Config.defineConfigSchema("mod-mod", schema);
     expect(console.error).not.toHaveBeenCalled();
   });
+
+  it("logs an error if the schema attempts to include a key named 'Display conditions'", () => {
+    const schema = {
+      "Display conditions": {
+        _type: Type.Array,
+        _default: [],
+      },
+    };
+
+    Config.defineConfigSchema("mod-mod", schema);
+    expect(console.error).toHaveBeenCalledWith(
+      expect.stringMatching(/mod-mod.*\bDisplay conditions\b/)
+    );
+  });
 });
 
 describe("getConfig", () => {
@@ -264,7 +304,7 @@ describe("getConfig", () => {
     await Config.getConfig("foo-module");
     expect(console.error).toHaveBeenCalledWith(
       expect.stringMatching(
-        /value.*{\"a\":{\"b\":5}\}.*foo-module.bar.*c must equal a\.b \+ diff/
+        /Invalid configuration for foo-module.bar.*c must equal a\.b \+ diff/
       )
     );
 
@@ -275,7 +315,11 @@ describe("getConfig", () => {
     Config.provide(goodConfig);
     const result = await Config.getConfig("foo-module");
     expect(result).toStrictEqual({
-      bar: { a: { b: 0 }, c: 2, diff: 2 },
+      bar: {
+        a: { b: 0 },
+        c: 2,
+        diff: 2,
+      },
     });
   });
 
@@ -360,6 +404,19 @@ describe("getConfig", () => {
     );
   });
 
+  it("tolerates defaults that don't pass validation", async () => {
+    Config.defineConfigSchema("foo-module", {
+      foo: {
+        _default: null,
+        _validators: [
+          validator((val) => val.startsWith("thi"), "must start with 'thi'"),
+        ],
+      },
+    });
+    await Config.getConfig("foo-module");
+    expect(console.error).not.toHaveBeenCalled();
+  });
+
   it("validators pass", async () => {
     Config.defineConfigSchema("foo-module", {
       foo: {
@@ -446,16 +503,14 @@ describe("getConfig", () => {
     Config.defineConfigSchema("object-def", {
       furi: {
         _type: Type.Object,
-        _elements: {
-          gohan: { _type: Type.String },
-        },
-        _default: {
-          kake: { gohan: "ok" },
-        },
+        _elements: { gohan: { _type: Type.String } },
+        _default: { kake: { gohan: "ok" } },
       },
     });
     const config = await Config.getConfig("object-def");
-    expect(config).toStrictEqual({ furi: { kake: { gohan: "ok" } } });
+    expect(config).toStrictEqual({
+      furi: { kake: { gohan: "ok" } },
+    });
   });
 
   it("interpolates freeform object element defaults", async () => {
@@ -505,6 +560,27 @@ describe("getConfig", () => {
     expect(console.error).not.toHaveBeenCalled();
   });
 
+  it("supports array of string elements", async () => {
+    Config.defineConfigSchema("foo-module", {
+      foo: {
+        _type: Type.Array,
+        _default: ["bar"],
+        _elements: {
+          _type: Type.String,
+        },
+      },
+    });
+    const testConfig = {
+      "foo-module": {
+        foo: ["bar", "baz", "qux"],
+      },
+    };
+    Config.provide(testConfig);
+    const config = await Config.getConfig("foo-module");
+    expect(config.foo).toStrictEqual(["bar", "baz", "qux"]);
+    expect(console.error).not.toHaveBeenCalled();
+  });
+
   it("supports validation of array elements", async () => {
     Config.defineConfigSchema("foo-module", {
       foo: {
@@ -638,9 +714,7 @@ describe("getConfig", () => {
     Config.provide(badConfig);
     await Config.getConfig("foo-module");
     expect(console.error).toHaveBeenCalledWith(
-      expect.stringMatching(
-        /value.*{\"a\":{\"b\":1},\"c\":3}.*foo-module.bar\[1\].*c must equal a\.b \+ 1/
-      )
+      expect.stringMatching(/foo-module.bar\[1\].*c must equal a\.b \+ 1/i)
     );
 
     await resetAll();
@@ -765,9 +839,29 @@ describe("implementer tools config", () => {
           _description: "All the foo",
           _validators: [],
         },
+        "Display conditions": {
+          privileges: {
+            _default: [],
+            _description:
+              "The privilege(s) the user must have to use this extension",
+            _source: "default",
+            _type: Type.Array,
+            _value: [],
+          },
+        },
       },
       "bar-module": {
         bar: { _value: "baz", _source: "my config source", _default: "quinn" },
+        "Display conditions": {
+          privileges: {
+            _default: [],
+            _description:
+              "The privilege(s) the user must have to use this extension",
+            _source: "default",
+            _type: Type.Array,
+            _value: [],
+          },
+        },
       },
     });
   });
@@ -917,6 +1011,16 @@ describe("extension slot config", () => {
             remove: { _value: ["bar"], _source: "provided" },
           },
         },
+        "Display conditions": {
+          privileges: {
+            _default: [],
+            _description:
+              "The privilege(s) the user must have to use this extension",
+            _source: "default",
+            _type: Type.Array,
+            _value: [],
+          },
+        },
       },
     });
   });

package/src/module-config/module-config.ts

@@ -1,5 +1,5 @@
 /** @module @category Config */
-import { clone, reduce, mergeDeepRight, equals } from "ramda";
+import { clone, reduce, mergeDeepRight, equals, omit } from "ramda";
 import {
   Config,
   ConfigObject,
@@ -27,7 +27,6 @@ import {
   implementerToolsConfigStore,
   temporaryConfigStore,
   getExtensionSlotsConfigStore,
-  ExtensionsConfigStore,
 } from "./state";
 import type {} from "@openmrs/esm-globals";
 import { TemporaryConfigStore } from "..";
@@ -192,9 +191,14 @@ function computeExtensionConfigs(
  */
 export function defineConfigSchema(moduleName: string, schema: ConfigSchema) {
   validateConfigSchema(moduleName, schema);
+  const enhancedSchema = mergeDeepRight(
+    schema,
+    displayConditionsSchema
+  ) as ConfigSchema;
+
   const state = configInternalStore.getState();
   configInternalStore.setState({
-    schemas: { ...state.schemas, [moduleName]: schema },
+    schemas: { ...state.schemas, [moduleName]: enhancedSchema },
   });
 }
 
@@ -220,14 +224,20 @@ export function defineExtensionConfigSchema(
   schema: ConfigSchema
 ) {
   validateConfigSchema(extensionName, schema);
+  const enhancedSchema = mergeDeepRight(
+    schema,
+    displayConditionsSchema
+  ) as ConfigSchema;
+
   const state = configInternalStore.getState();
   if (state.schemas[extensionName]) {
     console.warn(
       `Config schema for extension ${extensionName} already exists. If there are multiple extensions with this same name, one will probably crash.`
     );
   }
+
   configInternalStore.setState({
-    schemas: { ...state.schemas, [extensionName]: schema },
+    schemas: { ...state.schemas, [extensionName]: enhancedSchema },
   });
 }
 
@@ -256,7 +266,8 @@ export function getConfig(moduleName: string): Promise<Config> {
     const store = getConfigStore(moduleName);
     function update(state: ConfigStore) {
       if (state.loaded && state.config) {
-        resolve(state.config);
+        const config = omit(["Display conditions"], state.config);
+        resolve(config);
         unsubscribe && unsubscribe();
       }
     }
@@ -280,8 +291,9 @@ export function processConfig(
   keyPathContext: string,
   devDefaultsAreOn: boolean = false
 ) {
-  validateConfig(schema, providedConfig, keyPathContext);
+  validateStructure(schema, providedConfig, keyPathContext);
   const config = setDefaults(schema, providedConfig, devDefaultsAreOn);
+  runAllValidatorsInConfigTree(schema, config, keyPathContext);
   return config;
 }
 
@@ -326,12 +338,13 @@ function computeExtensionConfig(
   // TODO: validate that a schema exists for the module
   const schema =
     extensionConfigSchema ?? configState.schemas[extensionModuleName];
-  validateConfig(schema, combinedConfig, nameOfSchemaSource);
+  validateStructure(schema, combinedConfig, nameOfSchemaSource);
   const config = setDefaults(
     schema,
     combinedConfig,
     configState.devDefaultsAreOn
   );
+  runAllValidatorsInConfigTree(schema, config, nameOfSchemaSource);
   delete config.extensionSlots;
   return config;
 }
@@ -360,7 +373,7 @@ function getSchemaWithValuesAndSources(schema) {
       return obj;
     }, {});
   } else {
-    // Schema is bad; error will have been logged during schema validation
+    // at this point, the schema is bad and an error will have been logged during schema validation
     return {};
   }
 }
@@ -490,6 +503,12 @@ function validateConfigSchema(
     const thisKeyPath = keyPath + (keyPath && ".") + key;
     const schemaPart = schema[key] as ConfigSchema;
 
+    if (thisKeyPath === "Display conditions") {
+      console.error(
+        `${moduleName} declares a configuration option called "Display conditions"; the "Display conditions" option is a reserved name. ${updateMessage}`
+      );
+    }
+
     if (!isOrdinaryObject(schemaPart)) {
       console.error(
         `${moduleName} has bad config schema definition for key '${thisKeyPath}'. ${updateMessage}`
@@ -571,8 +590,9 @@ function getConfigForModule(
     moduleName,
     getProvidedConfigs(configState, tempConfigState)
   );
-  validateConfig(schema, inputConfig, moduleName);
+  validateStructure(schema, inputConfig, moduleName);
   const config = setDefaults(schema, inputConfig, configState.devDefaultsAreOn);
+  runAllValidatorsInConfigTree(schema, config, moduleName);
   delete config.extensionSlots;
   return config;
 }
@@ -593,21 +613,25 @@ function mergeConfigs(configs: Array<Config>) {
   return mergeDeepAll({}, configs) as Config;
 }
 
-// Recursively check the provided config tree to make sure that all
-// of the provided properties exist in the schema. Run validators
-// where present in the schema.
-const validateConfig = (
+/**
+ * Recursively check the provided config tree to make sure that all
+ * of the provided properties exist in the schema, and that types are
+ * correct. Does not run validators yet, since those will be run on
+ * the config with the defaults filled in.
+ */
+function validateStructure(
   schema: ConfigSchema,
   config: ConfigObject,
   keyPath = ""
-) => {
+) {
+  // validate each constituent element
   for (const key of Object.keys(config)) {
     const value = config[key];
     const thisKeyPath = keyPath + "." + key;
     const schemaPart = schema[key] as ConfigSchema;
 
     if (!schema.hasOwnProperty(key)) {
-      if (key !== "extensionSlots") {
+      if (!(key === "extensionSlots" && keyPath !== "")) {
         console.error(
           `Unknown config key '${thisKeyPath}' provided. Ignoring.`
         );
@@ -616,27 +640,34 @@ const validateConfig = (
       continue;
     }
 
-    checkType(thisKeyPath, schemaPart._type, value);
-    runValidators(thisKeyPath, schemaPart._validators, value);
-
-    if (isOrdinaryObject(value)) {
-      // structurally validate only if there's elements specified
-      // or there's a `_default` value, which indicates a freeform object
-      if (schemaPart._type === Type.Object) {
-        validateDictionary(schemaPart, value, thisKeyPath);
-      } else if (!schemaPart.hasOwnProperty("_default")) {
-        // recurse to validate nested object structure
-        validateConfig(schemaPart, value, thisKeyPath);
-      }
-    } else {
-      if (schemaPart._type === Type.Array) {
-        validateArray(schemaPart, value, thisKeyPath);
-      }
+    validateBranchStructure(schemaPart, value, thisKeyPath);
+  }
+}
+
+function validateBranchStructure(
+  schemaPart: ConfigSchema,
+  value: any,
+  keyPath: string
+) {
+  checkType(keyPath, schemaPart._type, value);
+
+  if (isOrdinaryObject(value)) {
+    // structurally validate only if there's elements specified
+    // or there's no `_default` value (which would indicate a freeform object)
+    if (schemaPart._type === Type.Object) {
+      validateDictionaryStructure(schemaPart, value, keyPath);
+    } else if (!schemaPart.hasOwnProperty("_default")) {
+      // recurse to validate nested object structure
+      validateStructure(schemaPart, value, keyPath);
+    }
+  } else {
+    if (schemaPart._type === Type.Array) {
+      validateArrayStructure(schemaPart, value, keyPath);
     }
   }
-};
+}
 
-function validateDictionary(
+function validateDictionaryStructure(
   dictionarySchema: ConfigSchema,
   config: ConfigObject,
   keyPath: string
@@ -644,12 +675,12 @@ function validateDictionary(
   if (dictionarySchema._elements) {
     for (const key of Object.keys(config)) {
       const value = config[key];
-      validateConfig(dictionarySchema._elements, value, `${keyPath}.${key}`);
+      validateStructure(dictionarySchema._elements, value, `${keyPath}.${key}`);
     }
   }
 }
 
-function validateArray(
+function validateArrayStructure(
   arraySchema: ConfigSchema,
   value: ConfigObject,
   keyPath: string
@@ -657,17 +688,55 @@ function validateArray(
   // if there is an array element object schema, verify that elements match it
   if (hasObjectSchema(arraySchema._elements)) {
     for (let i = 0; i < value.length; i++) {
-      validateConfig(arraySchema._elements, value[i], `${keyPath}[${i}]`);
+      validateBranchStructure(
+        arraySchema._elements,
+        value[i],
+        `${keyPath}[${i}]`
+      );
     }
   }
 
   for (let i = 0; i < value.length; i++) {
     checkType(`${keyPath}[${i}]`, arraySchema._elements?._type, value[i]);
-    runValidators(
-      `${keyPath}[${i}]`,
-      arraySchema._elements?._validators,
-      value[i]
-    );
+  }
+}
+
+/**
+ * Run all the validators in the config tree. This should be run
+ * on the config object after it has been filled in with all the defaults, since
+ * higher-level validators may refer to default values.
+ */
+function runAllValidatorsInConfigTree(
+  schema: ConfigSchema,
+  config: ConfigObject,
+  keyPath = ""
+) {
+  // If `!schema`, there should have been a structural validation error printed already.
+  if (schema) {
+    if (config !== schema._default) {
+      runValidators(keyPath, schema._validators, config);
+    }
+
+    if (isOrdinaryObject(config)) {
+      for (const key of Object.keys(config)) {
+        const value = config[key];
+        const thisKeyPath = keyPath + "." + key;
+        const schemaPart = schema[key] as ConfigSchema;
+        if (schema._type === Type.Object && schema._elements) {
+          runAllValidatorsInConfigTree(schema._elements, value, thisKeyPath);
+        } else {
+          runAllValidatorsInConfigTree(schemaPart, value, thisKeyPath);
+        }
+      }
+    } else if (Array.isArray(config) && schema._elements) {
+      for (let i = 0; i < config.length; i++) {
+        runAllValidatorsInConfigTree(
+          schema._elements,
+          config[i],
+          `${keyPath}[${i}]`
+        );
+      }
+    }
   }
 }
 
@@ -699,15 +768,21 @@ function runValidators(
         const validatorResult = validator(value);
 
         if (typeof validatorResult === "string") {
-          const valueString =
-            typeof value === "object" ? JSON.stringify(value) : value;
-          console.error(
-            `Invalid configuration value ${valueString} for ${keyPath}: ${validatorResult}`
-          );
+          if (typeof value === "object") {
+            console.error(
+              `Invalid configuration for ${keyPath}: ${validatorResult}`
+            );
+          } else {
+            console.error(
+              `Invalid configuration value ${value} for ${keyPath}: ${validatorResult}`
+            );
+          }
         }
       }
     } catch (e) {
-      console.error(`Skipping invalid validator at "${keyPath}".`);
+      console.error(
+        `Skipping invalid validator at "${keyPath}". Encountered error\n\t${e}`
+      );
     }
   }
 }
@@ -748,7 +823,7 @@ const setDefaults = (
       const elements = schemaPart._elements;
 
       if (configPart && hasObjectSchema(elements)) {
-        if (schemaPart._type === Type.Array) {
+        if (schemaPart._type === Type.Array && Array.isArray(configPart)) {
           const configWithDefaults = configPart.map((conf: Config) =>
             setDefaults(elements, conf, devDefaultsAreOn)
           );
@@ -805,3 +880,16 @@ function getExtensionNameFromId(extensionId: string) {
   const [extensionName] = extensionId.split("#");
   return extensionName;
 }
+
+/**
+ * The displayConditionsSchema is implicitly included in every configuration schema
+ */
+const displayConditionsSchema: ConfigSchema = {
+  "Display conditions": {
+    privileges: {
+      _description: "The privilege(s) the user must have to use this extension",
+      _type: Type.Array,
+      _default: [],
+    },
+  },
+};

package/src/module-config/state.ts

@@ -1,5 +1,6 @@
 /** @module @category Config */
 import { createGlobalStore, getGlobalStore } from "@openmrs/esm-state";
+import { omit } from "ramda";
 import {
   Config,
   ConfigObject,
@@ -199,11 +200,16 @@ export function getExtensionsConfigStore() {
 
 /** @internal */
 export function getExtensionConfig(slotName: string, extensionId: string) {
-  return getExtensionConfigFromStore(
-    getExtensionsConfigStore().getState(),
-    slotName,
-    extensionId
+  const extensionConfig = Object.assign(
+    {},
+    getExtensionConfigFromStore(
+      getExtensionsConfigStore().getState(),
+      slotName,
+      extensionId
+    )
   );
+  extensionConfig.config = omit(["Display conditions"], extensionConfig.config);
+  return extensionConfig;
 }
 
 /** @internal */

package/src/navigation/interpolate-string.test.ts

@@ -6,6 +6,15 @@ describe("interpolateUrl", () => {
     expect(result).toBe("test /openmrs /openmrs/spa ok");
   });
 
+  it("interpolates other URL template parameters", () => {
+    const result = interpolateUrl("${openmrsSpaBase}/patient/${patientUuid}", {
+      patientUuid: "4fcb7185-c6c9-450f-8828-ccae9436bd82",
+    });
+    expect(result).toBe(
+      "/openmrs/spa/patient/4fcb7185-c6c9-450f-8828-ccae9436bd82"
+    );
+  });
+
   it("works when no interpolation needed", () => {
     const result = interpolateUrl("test ok");
     expect(result).toBe("test ok");
@@ -15,14 +24,14 @@ describe("interpolateUrl", () => {
 describe("interpolateString", () => {
   it("interpolates template elements", () => {
     const result = interpolateString("test ${one} ${two} 3", {
-      one: 1,
-      two: 2,
+      one: "1",
+      two: "2",
     });
     expect(result).toBe("test 1 2 3");
   });
 
   it("tolerates extra parameters", () => {
-    const result = interpolateString("test ok", { one: 1, two: 2 });
+    const result = interpolateString("test ok", { one: "1", two: "2" });
     expect(result).toBe("test ok");
   });
 });

package/src/navigation/interpolate-string.ts

@@ -7,38 +7,63 @@ function trimTrailingSlash(str: string) {
 /**
  * Interpolates a string with openmrsBase and openmrsSpaBase.
  *
- * Useful for accepting `${openmrsBase}` or `${openmrsSpaBase}` template
+ * Useful for accepting `${openmrsBase}` or `${openmrsSpaBase}`plus additional template
  * parameters in configurable URLs.
  *
+ * Example usage:
+ * ```js
+ * interpolateUrl("test ${openmrsBase} ${openmrsSpaBase} ok");
+ *    // will return "test /openmrs /openmrs/spa ok"
+ *
+ * interpolateUrl("${openmrsSpaBase}/patient/${patientUuid}", {
+ *    patientUuid: "4fcb7185-c6c9-450f-8828-ccae9436bd82",
+ * }); // will return "/openmrs/spa/patient/4fcb7185-c6c9-450f-8828-ccae9436bd82"
+ * ```
+ *
+ * This can be used in conjunction with the `navigate` function like so
+ * ```js
+ * navigate({
+ *  to: interpolateUrl(
+ *    "${openmrsSpaBase}/patient/${patientUuid}",
+ *    { patientUuid: patient.uuid }
+ *  )
+ * }); // will navigate to "/openmrs/spa/patient/4fcb7185-c6c9-450f-8828-ccae9436bd82"
+ * ```
+ *
  * @param template A string to interpolate
+ * @param additionalParams Additional values to interpolate into the string template
  */
-export function interpolateUrl(template: string): string {
+export function interpolateUrl(
+  template: string,
+  additionalParams?: { [key: string]: string }
+): string {
   const openmrsSpaBase = trimTrailingSlash(window.getOpenmrsSpaBase());
   return interpolateString(template, {
     openmrsBase: window.openmrsBase,
     openmrsSpaBase: openmrsSpaBase,
+    ...additionalParams,
   }).replace(/^\/\//, "/"); // remove extra initial slash if present
 }
 
 /**
  * Interpolates values of `params` into the `template` string.
  *
- * Useful for additional template parameters in URLs.
- *
  * Example usage:
  * ```js
- * navigate({
- *  to: interpolateString(
- *    config.links.patientChart,
- *    { patientUuid: patient.uuid }
- *  )
- * });
+ * interpolateString("test ${one} ${two} 3", {
+ *    one: "1",
+ *    two: "2",
+ * }); // will return "test 1 2 3"
+ * interpolateString("test ok", { one: "1", two: "2" }) // will return "test ok"
  * ```
  *
  * @param template With optional params wrapped in `${ }`
  * @param params Values to interpolate into the string template
  */
-export function interpolateString(template: string, params: object): string {
+export function interpolateString(
+  template: string,
+  params: { [key: string]: string }
+): string {
   const names = Object.keys(params);
   return names.reduce(
     (prev, curr) => prev.split("${" + curr + "}").join(params[curr]),