@openmrs/esm-config 3.4.1-pre.96 → 4.0.0-pre.1

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

@@ -0,0 +1,57 @@
+import { Config, ConfigObject, ConfigSchema } from "../types";
+/**
+ * This defines a configuration schema for a module. The schema tells the
+ * configuration system how the module can be configured. It specifies
+ * what makes configuration valid or invalid.
+ *
+ * See [Configuration System](http://o3-dev.docs.openmrs.org/#/main/config)
+ * for more information about defining a config schema.
+ *
+ * @param moduleName Name of the module the schema is being defined for. Generally
+ *   should be the one in which the `defineConfigSchema` call takes place.
+ * @param schema The config schema for the module
+ */
+export declare function defineConfigSchema(moduleName: string, schema: ConfigSchema): void;
+/**
+ * This defines a configuration schema for an extension. When a schema is defined
+ * for an extension, that extension will receive the configuration corresponding
+ * to that schema, rather than the configuration corresponding to the module
+ * in which it is defined.
+ *
+ * The schema tells the configuration system how the module can be configured.
+ * It specifies what makes configuration valid or invalid.
+ *
+ * See [Configuration System](http://o3-dev.docs.openmrs.org/#/main/config)
+ * for more information about defining a config schema.
+ *
+ * @param extensionName Name of the extension the schema is being defined for.
+ *   Should match the `name` of one of the `extensions` entries being returned
+ *   by `setupOpenMRS`.
+ * @param schema The config schema for the extension
+ */
+export declare function defineExtensionConfigSchema(extensionName: string, schema: ConfigSchema): void;
+export declare function provide(config: Config, sourceName?: string): void;
+/**
+ * A promise-based way to access the config as soon as it is fully loaded.
+ * If it is already loaded, resolves the config in its present state.
+ *
+ * In general you should use the Unistore-based API provided by
+ * `getConfigStore`, which allows creating a subscription so that you always
+ * have the latest config. If using React, just use `useConfig`.
+ *
+ * This is a useful function if you need to get the config in the course
+ * of the execution of a function.
+ *
+ * @param moduleName The name of the module for which to look up the config
+ */
+export declare function getConfig(moduleName: string): Promise<Config>;
+/**
+ * Validate and interpolate defaults for `providedConfig` according to `schema`
+ *
+ * @param schema  a configuration schema
+ * @param providedConfig  an object of config values (without the top-level module name)
+ * @param keyPathContext  a dot-deparated string which helps the user figure out where
+ *     the provided config came from
+ * @internal
+ */
+export declare function processConfig(schema: ConfigSchema, providedConfig: ConfigObject, keyPathContext: string, devDefaultsAreOn?: boolean): Config;

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

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

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/jest.config.js

@@ -8,4 +8,8 @@ module.exports = {
     "@openmrs/esm-globals": "<rootDir>/__mocks__/openmrs-esm-globals.mock.tsx",
     "@openmrs/esm-state": "<rootDir>/__mocks__/openmrs-esm-state.mock.tsx",
   },
+  testEnvironment: "jsdom",
+  testEnvironmentOptions: {
+    url: "http://localhost/",
+  },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-config",
-  "version": "3.4.1-pre.96",
+  "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",
@@ -39,18 +39,18 @@
     "ramda": "^0.26.1"
   },
   "peerDependencies": {
-    "@openmrs/esm-globals": "3.x",
-    "@openmrs/esm-state": "3.x",
+    "@openmrs/esm-globals": "4.x",
+    "@openmrs/esm-state": "4.x",
     "single-spa": "5.x",
     "systemjs": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-globals": "^3.4.1-pre.96",
-    "@openmrs/esm-state": "^3.4.1-pre.96",
+    "@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": "593214cd88408e07e9c18eab4c204be4a3722c73"
+  "gitHead": "9f58b801f07526083a9edc1cc5a1e58660d71eb0"
 }

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

@@ -15,14 +15,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

@@ -11,12 +11,17 @@ function trimTrailingSlash(str: string) {
  * parameters in configurable URLs.
  *
  * @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
 }
 
@@ -38,7 +43,10 @@ export function interpolateUrl(template: string): string {
  * @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]),

package/src/navigation/navigate.ts

@@ -7,8 +7,11 @@ function trimTrailingSlash(str: string) {
   return str.replace(/\/$/, "");
 }
 
+export type TemplateParams = { [key: string]: string };
+
 export interface NavigateOptions {
   to: string;
+  templateParams?: TemplateParams;
 }
 
 /**
@@ -16,19 +19,22 @@ export interface NavigateOptions {
  *
  * Example usage:
  * ```js
- * const config = getConfig();
+ * const config = useConfig();
  * const submitHandler = () => {
  *   navigate({ to: config.links.submitSuccess });
  * };
  * ```
  *
- * @param to The target path or URL. Supports templating with 'openmrsBase' and 'openmrsSpaBase'.
+ * @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 function navigate({ to }: NavigateOptions): void {
+export function navigate({ to, templateParams }: NavigateOptions): void {
   const openmrsSpaBase = trimTrailingSlash(window.getOpenmrsSpaBase());
-  const target = interpolateUrl(to);
+  const target = interpolateUrl(to, templateParams);
   const isSpaPath = target.startsWith(openmrsSpaBase);
 
   if (isSpaPath) {