@openmrs/esm-config 4.0.0-pre.0 → 4.0.0-pre.1

package/dist/src/module-config/state.d.ts

@@ -0,0 +1,109 @@
+import { Config, ConfigObject, ConfigSchema, ExtensionSlotConfigObject, ProvidedConfig } from "../types";
+/**
+ * Internal store
+ *   A store of the inputs and internal state
+ * @internal
+ */
+export interface ConfigInternalStore {
+    /** Configs added using the `provide` function */
+    providedConfigs: Array<ProvidedConfig>;
+    /** An object with module names for keys and schemas for values */
+    schemas: Record<string, ConfigSchema>;
+    /** Whether to use dev defaults or not */
+    devDefaultsAreOn: boolean;
+}
+/**
+ * @internal
+ */
+export declare const configInternalStore: import("unistore").Store<ConfigInternalStore>;
+/**
+ * Temporary config
+ *   LocalStorage-based config used by the implementer tools
+ * @internal
+ */
+export interface TemporaryConfigStore {
+    config: Config;
+}
+/** @internal */
+export declare const temporaryConfigStore: import("unistore").Store<TemporaryConfigStore>;
+/**
+ * Config-side extension store
+ *   Just what esm-config needs to know about extension state. This
+ *   is to avoid having esm-config depend on esm-extensions, which would
+ *   create a circular dependency.
+ * @internal
+ */
+export interface ConfigExtensionStore {
+    mountedExtensions: Array<ConfigExtensionStoreElement>;
+}
+/** @internal */
+export interface ConfigExtensionStoreElement {
+    slotModuleName: string;
+    extensionModuleName: string;
+    slotName: string;
+    extensionId: string;
+}
+/** @internal */
+export declare const configExtensionStore: import("unistore").Store<ConfigExtensionStore>;
+/**
+ * Output configs
+ *
+ * Each module has its own stores for its config and its extension slots' configs.
+ * @internal
+ */
+export interface ConfigStore {
+    config: ConfigObject | null;
+    loaded: boolean;
+}
+/** @internal */
+export declare function getConfigStore(moduleName: string): import("unistore").Store<ConfigStore>;
+/**
+ * Configuration for all the specific extension slots
+ * @internal
+ */
+export interface ExtensionSlotsConfigStore {
+    slots: {
+        [slotName: string]: {
+            config: ExtensionSlotConfigObject;
+            loaded: boolean;
+        };
+    };
+}
+/** @internal */
+export declare function getExtensionSlotsConfigStore(): import("unistore").Store<ExtensionSlotsConfigStore>;
+/** @internal */
+export declare function getExtensionSlotConfig(slotName: string): {
+    config: ExtensionSlotConfigObject;
+    loaded: boolean;
+};
+/** @internal */
+export declare function getExtensionSlotConfigFromStore(state: ExtensionSlotsConfigStore, slotName: string): {
+    config: ExtensionSlotConfigObject;
+    loaded: boolean;
+};
+/** @internal */
+export interface ExtensionsConfigStore {
+    configs: {
+        [slotName: string]: {
+            [extensionId: string]: ConfigStore;
+        };
+    };
+}
+/**
+ * One store for all the extensions
+ * @internal
+ */
+export declare function getExtensionsConfigStore(): import("unistore").Store<ExtensionsConfigStore>;
+/** @internal */
+export declare function getExtensionConfig(slotName: string, extensionId: string): ConfigStore;
+/** @internal */
+export declare function getExtensionConfigFromStore(state: ExtensionsConfigStore, slotName: string, extensionId: string): ConfigStore;
+/**
+ * A store of the implementer tools output config
+ * @internal
+ */
+export interface ImplementerToolsConfigStore {
+    config: Config;
+}
+/** @internal */
+export declare const implementerToolsConfigStore: import("unistore").Store<ImplementerToolsConfigStore>;

package/dist/src/navigation/interpolate-string.d.ts

@@ -0,0 +1,34 @@
+/** @module @category Navigation */
+/**
+ * Interpolates a string with openmrsBase and openmrsSpaBase.
+ *
+ * Useful for accepting `${openmrsBase}` or `${openmrsSpaBase}` template
+ * parameters in configurable URLs.
+ *
+ * @param template A string to interpolate
+ * @param additionalParams Additional values to interpolate into the string template
+ */
+export declare function interpolateUrl(template: string, additionalParams?: {
+    [key: string]: string;
+}): string;
+/**
+ * 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 }
+ *  )
+ * });
+ * ```
+ *
+ * @param template With optional params wrapped in `${ }`
+ * @param params Values to interpolate into the string template
+ */
+export declare function interpolateString(template: string, params: {
+    [key: string]: string;
+}): string;

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

@@ -0,0 +1 @@
+export {};

package/dist/src/navigation/navigate.d.ts

@@ -0,0 +1,26 @@
+export declare type TemplateParams = {
+    [key: string]: string;
+};
+export interface NavigateOptions {
+    to: string;
+    templateParams?: TemplateParams;
+}
+/**
+ * Calls `location.assign` for non-SPA paths and [navigateToUrl](https://single-spa.js.org/docs/api/#navigatetourl) for SPA paths
+ *
+ * Example usage:
+ * ```js
+ * const config = useConfig();
+ * const submitHandler = () => {
+ *   navigate({ to: config.links.submitSuccess });
+ * };
+ * ```
+ *
+ * @param to The target path or URL. Supports templating with 'openmrsBase', 'openmrsSpaBase',
+ * and any additional template parameters defined in `templateParams`.
+ * For example, `${openmrsSpaBase}/home` will resolve to `/openmrs/spa/home`
+ * for implementations using the standard OpenMRS and SPA base paths.
+ * If `templateParams` contains `{ foo: "bar" }`, then the URL `${openmrsBase}/${foo}`
+ * will become `/openmrs/bar`.
+ */
+export declare function navigate({ to, templateParams }: NavigateOptions): void;

package/dist/src/navigation/navigate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/public.d.ts

@@ -0,0 +1,7 @@
+export * from "./types";
+export * from "./navigation/interpolate-string";
+export * from "./navigation/navigate";
+export * from "./validators/validator";
+export * from "./validators/validators";
+export { defineConfigSchema, defineExtensionConfigSchema, provide, getConfig, } from "./module-config/module-config";
+export { getConfigStore, ConfigStore } from "./module-config/state";

package/dist/src/types.d.ts

@@ -0,0 +1,49 @@
+export declare enum Type {
+    Array = "Array",
+    Boolean = "Boolean",
+    ConceptUuid = "ConceptUuid",
+    Number = "Number",
+    Object = "Object",
+    String = "String",
+    UUID = "UUID",
+    PersonAttributeTypeUuid = "PersonAttributeTypeUuid",
+    PatientIdentifierTypeUuid = "PatientIdentifierTypeUuid"
+}
+export interface ConfigSchema {
+    [key: string]: ConfigSchema | ConfigValue;
+    _type?: Type;
+    _validators?: Array<Validator>;
+    _elements?: ConfigSchema;
+}
+export interface Config extends Object {
+    [moduleName: string]: {
+        [key: string]: any;
+    };
+}
+export interface ConfigObject extends Object {
+    [key: string]: any;
+}
+export declare type ConfigValue = string | number | boolean | void | Array<any> | object;
+export interface ExtensionSlotConfig {
+    add?: Array<string>;
+    remove?: Array<string>;
+    order?: Array<string>;
+    configure?: ExtensionSlotConfigureValueObject;
+}
+export interface ExtensionSlotConfigureValueObject {
+    [key: string]: object;
+}
+export interface ExtensionSlotConfigObject {
+    /** Additional extension IDs to assign to this slot, in addition to those `attach`ed in code. */
+    add?: Array<string>;
+    /** Extension IDs which were `attach`ed to the slot but which should not be assigned. */
+    remove?: Array<string>;
+    /** Overrides the default ordering of extensions. */
+    order?: Array<string>;
+}
+export declare type ProvidedConfig = {
+    source: string;
+    config: Config;
+};
+export declare type ValidatorFunction = (value: any) => boolean;
+export declare type Validator = (value: any) => void | string;

package/dist/src/validators/type-validators.d.ts

@@ -0,0 +1,6 @@
+export declare const isArray: import("..").Validator;
+export declare const isBoolean: import("..").Validator;
+export declare const isNumber: import("..").Validator;
+export declare const isString: import("..").Validator;
+export declare const isObject: import("..").Validator;
+export declare const isUuid: import("..").Validator;

package/dist/src/validators/type-validators.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/validators/validator.d.ts

@@ -0,0 +1,24 @@
+/** @module @category Config Validation */
+import { Validator, ValidatorFunction } from "../types";
+/**
+ * Constructs a custom validator.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * {
+ *   foo: {
+ *     _default: 0,
+ *     _validators: [
+ *       validator(val => val >= 0, "Must not be negative.")
+ *     ]
+ *   }
+ * }
+ * ```
+ * @param validationFunction Takes the configured value as input. Returns true
+ *    if it is valid, false otherwise.
+ * @param message A string message that explains why the value is invalid. Can
+ *    also be a function that takes the value as input and returns a string.
+ * @returns A validator ready for use in a config schema
+ */
+export declare function validator(validationFunction: ValidatorFunction, message: string | ((value: any) => string)): Validator;

package/dist/src/validators/validators.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Verifies that the value is between the provided minimum and maximum
+ *
+ * @param min Minimum acceptable value
+ * @param max Maximum acceptable value
+ */
+export declare const inRange: (min: number, max: number) => import("..").Validator;
+/**
+ * Verifies that a string contains only the default URL template
+ * parameters, plus any specified in `allowedTemplateParameters`.
+ *
+ * @param allowedTemplateParameters To be added to `openmrsBase` and `openmrsSpaBase`
+ * @category Navigation
+ */
+export declare const isUrlWithTemplateParameters: (allowedTemplateParameters: string[]) => import("..").Validator;
+/**
+ * Verifies that a string contains only the default URL template parameters.
+ *
+ * @category Navigation
+ */
+export declare const isUrl: import("..").Validator;
+/**
+ * Verifies that the value is one of the allowed options.
+ * @param allowedValues The list of allowable values
+ */
+export declare const oneOf: (allowedValues: Array<any>) => import("..").Validator;
+export declare const validators: {
+    inRange: (min: number, max: number) => import("..").Validator;
+    isUrl: import("..").Validator;
+    isUrlWithTemplateParameters: (allowedTemplateParameters: string[]) => import("..").Validator;
+    oneOf: (allowedValues: Array<any>) => import("..").Validator;
+};

package/dist/src/validators/validators.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-config",
-  "version": "4.0.0-pre.0",
+  "version": "4.0.0-pre.1",
   "license": "MPL-2.0",
   "description": "A configuration library for the OpenMRS Single-Spa framework.",
   "browser": "dist/openmrs-esm-module-config.js",
@@ -45,12 +45,12 @@
     "systemjs": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-globals": "^4.0.0-pre.0",
-    "@openmrs/esm-state": "^4.0.0-pre.0",
+    "@openmrs/esm-globals": "^4.0.0-pre.1",
+    "@openmrs/esm-state": "^4.0.0-pre.1",
     "@types/ramda": "^0.26.44",
     "@types/systemjs": "^6.1.0",
     "babel-plugin-ramda": "^2.0.0",
     "single-spa": "^5.9.2"
   },
-  "gitHead": "254a7226212aac82df4434639b2584e24ac240e4"
+  "gitHead": "9f58b801f07526083a9edc1cc5a1e58660d71eb0"
 }

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] },
@@ -264,7 +290,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/
       )
     );
 
@@ -360,6 +386,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: {
@@ -505,6 +544,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 +698,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();

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

@@ -280,8 +280,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 +327,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;
 }
@@ -571,8 +573,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 +596,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 +623,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 +658,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 +671,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 +751,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 +806,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)
           );