@koech/esm-core 8.0.0

package/packages/framework/esm-config/src/module-config/state.ts

@@ -0,0 +1,258 @@
+import { createGlobalStore, getGlobalStore } from '@openmrs/esm-state';
+import { shallowEqual } from '@openmrs/esm-utils';
+import { type StoreApi } from 'zustand';
+import type { Config, ConfigObject, ConfigSchema, ExtensionSlotConfig, 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>;
+  /**
+   * Before modules are loaded, they get implicit schemas added to `schemas`. Therefore
+   * we need to track separately whether they have actually been loaded (that is,
+   * whether the schema has actually been defined).
+   */
+  moduleLoaded: Record<string, boolean>;
+}
+
+const configInternalStoreInitialValue = {
+  providedConfigs: [],
+  schemas: {},
+  moduleLoaded: {},
+};
+
+/**
+ * @internal
+ */
+export const configInternalStore = createGlobalStore<ConfigInternalStore>(
+  'config-internal',
+  configInternalStoreInitialValue,
+);
+
+/**
+ * Temporary config
+ *   LocalStorage-based config used by the implementer tools
+ * @internal
+ */
+export interface TemporaryConfigStore {
+  config: Config;
+}
+
+/** @internal */
+export const temporaryConfigStore = createGlobalStore<TemporaryConfigStore>('temporary-config', {
+  config: getTemporaryConfig(),
+});
+
+temporaryConfigStore.subscribe((state) => {
+  setTemporaryConfig(state.config);
+});
+
+function setTemporaryConfig(value: Config) {
+  localStorage.setItem('openmrs:temporaryConfig', JSON.stringify(value));
+}
+
+function getTemporaryConfig(): Config {
+  try {
+    return JSON.parse(localStorage.getItem('openmrs:temporaryConfig') || '{}');
+  } catch (e) {
+    return {};
+  }
+}
+
+/**
+ * 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 const configExtensionStore = createGlobalStore<ConfigExtensionStore>('config-store-of-extension-state', {
+  mountedExtensions: [],
+});
+
+/**
+ * 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;
+  translationOverridesLoaded: boolean;
+}
+
+function initializeConfigStore() {
+  return {
+    config: null,
+    loaded: false,
+    translationOverridesLoaded: false,
+  };
+}
+
+/** @internal */
+export function getConfigStore(moduleName: string) {
+  // We use a store for each module's config, named `config-module-${moduleName}`
+  return getGlobalStore<ConfigStore>(`config-module-${moduleName}`, initializeConfigStore());
+}
+
+/**
+ * Configuration for all the specific extension slots
+ * @internal
+ */
+export interface ExtensionSlotsConfigStore {
+  slots: {
+    [slotName: string]: {
+      config: ExtensionSlotConfig;
+      loaded: boolean;
+    };
+  };
+}
+
+/** @internal */
+export function getExtensionSlotsConfigStore() {
+  return getGlobalStore<ExtensionSlotsConfigStore>(`config-extension-slots`, {
+    slots: {},
+  });
+}
+
+/** @internal */
+export function getExtensionSlotConfig(slotName: string) {
+  return getExtensionSlotConfigFromStore(getExtensionSlotsConfigStore().getState(), slotName);
+}
+
+/** @internal */
+export function getExtensionSlotConfigFromStore(state: ExtensionSlotsConfigStore, slotName: string) {
+  const slotConfig = state.slots[slotName];
+  return slotConfig ?? { loaded: false, config: {} };
+}
+
+/** @internal */
+export interface ExtensionsConfigStore {
+  configs: {
+    [slotName: string]: {
+      [extensionId: string]: ConfigStore;
+    };
+  };
+}
+
+/**
+ * One store for all the extensions
+ * @internal
+ */
+export function getExtensionsConfigStore() {
+  return getGlobalStore<ExtensionsConfigStore>(`config-extensions`, {
+    configs: {},
+  });
+}
+
+/** @internal */
+export function getExtensionConfig(
+  slotName: string,
+  extensionId: string,
+): StoreApi<Omit<ConfigStore, 'translationOverridesLoaded'>> {
+  if (
+    typeof slotName !== 'string' ||
+    typeof extensionId !== 'string' ||
+    slotName === '__proto__' ||
+    extensionId === '__proto__' ||
+    slotName === 'constructor' ||
+    extensionId === 'constructor' ||
+    slotName === 'prototype' ||
+    extensionId === 'prototype'
+  ) {
+    throw new Error('Attempted to call `getExtensionConfig()` with invalid argument');
+  }
+
+  const extensionConfigStore = getExtensionsConfigStore();
+  const selector = (configStore: ExtensionsConfigStore) => configStore.configs[slotName]?.[extensionId];
+
+  return {
+    getInitialState() {
+      return selector(extensionConfigStore.getInitialState());
+    },
+    getState() {
+      return selector(extensionConfigStore.getState()) ?? { loaded: false, config: null };
+    },
+    setState(
+      partial: ConfigStore | Partial<ConfigStore> | ((state: ConfigStore) => ConfigStore | Partial<ConfigStore>),
+      replace: boolean = false,
+    ) {
+      extensionConfigStore.setState((state) => {
+        if (!state.configs[slotName]) {
+          state.configs[slotName] = {};
+        }
+
+        const newState = typeof partial === 'function' ? partial(state.configs.slotName[extensionId]) : partial;
+        if (replace) {
+          state.configs[slotName][extensionId] = Object.assign({}, newState) as ConfigStore;
+        } else {
+          state.configs[slotName][extensionId] = Object.assign({}, state.configs[slotName][extensionId], newState);
+        }
+
+        return state;
+      });
+    },
+    subscribe(listener) {
+      return extensionConfigStore.subscribe((state, prevState) => {
+        const newState = selector(state);
+        const oldState = selector(prevState);
+
+        if (!shallowEqual(newState, oldState)) {
+          listener(newState, oldState);
+        }
+      });
+    },
+    destroy() {
+      /* this is a no-op */
+    },
+  };
+}
+
+/** @internal */
+export function getExtensionConfigFromStore(state: ExtensionsConfigStore, slotName: string, extensionId: string) {
+  const extensionConfig = state.configs[slotName]?.[extensionId];
+  return extensionConfig ?? { loaded: false, config: null };
+}
+
+/** @internal */
+export function getExtensionConfigFromExtensionSlotStore(
+  state: ExtensionSlotConfig,
+  slotName: string,
+  extensionId: string,
+) {
+  const extensionConfig = state.configure?.[extensionId];
+  return extensionConfig ?? null;
+}
+
+/**
+ * A store of the implementer tools output config
+ * @internal
+ */
+export interface ImplementerToolsConfigStore {
+  config: Config;
+}
+
+/** @internal */
+export const implementerToolsConfigStore = createGlobalStore<ImplementerToolsConfigStore>('config-implementer-tools', {
+  config: {},
+});

package/packages/framework/esm-config/src/public.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './validators/validator';
+export * from './validators/validators';
+export { defineConfigSchema, defineExtensionConfigSchema, provide, getConfig } from './module-config/module-config';
+export { type ConfigStore, getConfigStore } from './module-config/state';

package/packages/framework/esm-config/src/setup-tests.js

@@ -0,0 +1,14 @@
+/* eslint-disable no-undef */
+import { vi } from 'vitest';
+
+global.window.System = {
+  import: vi.fn().mockRejectedValue(new Error('config.json not available in import map')),
+  resolve: vi.fn().mockImplementation(() => {
+    throw new Error('config.json not available in import map');
+  }),
+  register: vi.fn(),
+};
+
+global.window.openmrsBase = '/openmrs';
+global.window.spaBase = '/spa';
+global.window.getOpenmrsSpaBase = () => '/openmrs/spa/';

package/packages/framework/esm-config/src/types.ts

@@ -0,0 +1,69 @@
+export enum Type {
+  Array = 'Array',
+  Boolean = 'Boolean',
+  ConceptUuid = 'ConceptUuid',
+  Number = 'Number',
+  Object = 'Object',
+  String = 'String',
+  UUID = 'UUID',
+  PersonAttributeTypeUuid = 'PersonAttributeTypeUuid',
+  PatientIdentifierTypeUuid = 'PatientIdentifierTypeUuid',
+}
+
+// Full-powered typing for Config and Schema trees depends on being able to
+// have types like `string not "_default"`. There is an experimental PR
+// for this feature, https://github.com/microsoft/TypeScript/pull/29317
+// But it is not likely to be merged any time terribly soon. (Nov 11, 2020)
+export interface ConfigSchema {
+  [key: string]: ConfigSchema | ConfigValue;
+  _type?: Type;
+  _validators?: Array<Validator>;
+  _elements?: ConfigSchema;
+}
+
+export interface Config {
+  [moduleName: string]: { [key: string]: any };
+}
+
+export interface ConfigObject {
+  [key: string]: any;
+  /** Options that control when this extension is displayed  */
+  'Display conditions'?: DisplayConditionsConfigObject;
+  'Translation overrides'?: Record<string, Record<string, string>>;
+}
+
+export interface DisplayConditionsConfigObject {
+  /** The privileges a user should have to see this extension */
+  privileges?: string[];
+  /** An expression to evaluate whether or not the user should see this extension */
+  expression?: string;
+  /** Whether to display this extension when connected to the server */
+  online?: boolean;
+  /** Whether to display this extension when not connected to the server */
+  offline?: boolean;
+}
+
+export type ConfigValue = string | number | boolean | void | Array<any> | object;
+
+export interface ExtensionSlotConfig {
+  /** 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>;
+  configure?: ExtensionSlotConfigureValueObject;
+}
+
+export interface ExtensionSlotConfigureValueObject {
+  [key: string]: object;
+}
+
+export type ProvidedConfig = {
+  source: string;
+  config: Config;
+};
+
+export type ValidatorFunction = (value: any) => boolean;
+
+export type Validator = (value: any) => void | string;

package/packages/framework/esm-config/src/validators/type-validators.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import { isString, isBoolean, isUuid, isObject, isNumber, isArray } from './type-validators';
+
+describe('all validators', () => {
+  it('fail on undefined', () => {
+    expect(isString(undefined)).toMatch(/.*/);
+    expect(isBoolean(undefined)).toMatch(/.*/);
+    expect(isUuid(undefined)).toMatch(/.*/);
+    expect(isObject(undefined)).toMatch(/.*/);
+    expect(isNumber(undefined)).toMatch(/.*/);
+  });
+});
+
+describe('isString', () => {
+  it('accepts strings', () => {
+    expect(isString('')).toBeUndefined();
+  });
+
+  it('rejects non-strings', () => {
+    expect(isString([''])).toMatch('must be a string');
+  });
+});
+
+describe('isNumber', () => {
+  it('accepts numbers', () => {
+    expect(isNumber(10)).toBeUndefined();
+  });
+
+  it('rejects non-numbers', () => {
+    expect(isNumber('Not a Number')).toMatch('must be a number');
+  });
+
+  it('accepts zero and negative numbers', () => {
+    expect(isNumber(0)).toBeUndefined();
+    expect(isNumber(-1)).toBeUndefined();
+  });
+
+  it('accepts floating point numbers', () => {
+    expect(isNumber(3.14)).toBeUndefined();
+  });
+});
+
+describe('isBoolean', () => {
+  it('accepts bools', () => {
+    expect(isBoolean(false)).toBeUndefined();
+  });
+
+  it('rejects non-bools', () => {
+    expect(isBoolean(1)).toMatch('must be a bool');
+  });
+});
+
+describe('isUuid', () => {
+  it('accepts a CIEL External ID', () => {
+    expect(isUuid('123118AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')).toBeUndefined();
+  });
+
+  it('accepts a valid UUID with dashes', () => {
+    expect(isUuid('28c37ff6-0079-4fa7-b803-5d547ac454e0')).toBeUndefined();
+  });
+
+  it('rejects a bad UUID', () => {
+    expect(isUuid('28c37ff6-0079-4fa7-b803-5d547ac454e')).toMatch('must be a valid UUID');
+  });
+
+  it('rejects a bad CIEL External ID', () => {
+    expect(isUuid('123118AAAAAAAAAAAAAAAAAAAAAAAAAAAAA')).toMatch('must be a valid UUID');
+  });
+
+  it('rejects UUIDs with wrong segment lengths', () => {
+    expect(isUuid('28c37ff6-0079-4fa7-b803-5d547ac454e0a')).toMatch('must be a valid UUID');
+    expect(isUuid('28c37ff6-0079-4fa7-b803-5d547ac454')).toMatch('must be a valid UUID');
+  });
+});
+
+describe('isObject', () => {
+  it('accepts plain objects', () => {
+    expect(isObject({})).toBeUndefined();
+    expect(isObject({ foo: 0 })).toBeUndefined();
+  });
+
+  it('rejects arrays', () => {
+    expect(isObject([])).toMatch(/must be an object/i);
+  });
+
+  it('rejects null', () => {
+    expect(isObject(null)).toMatch(/must be an object/i);
+  });
+
+  it('rejects primitive types', () => {
+    expect(isObject(42)).toMatch(/must be an object/i);
+    expect(isObject('string')).toMatch(/must be an object/i);
+    expect(isObject(true)).toMatch(/must be an object/i);
+  });
+
+  it('rejects functions', () => {
+    expect(isObject(() => {})).toMatch(/must be an object/i);
+  });
+});
+
+describe('isArray', () => {
+  it('accepts arrays', () => {
+    expect(isArray([])).toBeUndefined();
+    expect(isArray([1, 2, 3])).toBeUndefined();
+  });
+
+  it('rejects non-arrays', () => {
+    expect(isArray({})).toMatch('must be an array');
+    expect(isArray('not an array')).toMatch('must be an array');
+  });
+});

package/packages/framework/esm-config/src/validators/type-validators.ts

@@ -0,0 +1,19 @@
+import { validator } from './validator';
+
+export const isArray = validator((val) => Array.isArray(val), 'must be an array');
+
+export const isBoolean = validator((val) => typeof val === 'boolean', 'must be a boolean');
+
+export const isNumber = validator((val) => typeof val === 'number', 'must be a number');
+
+export const isString = validator((val) => typeof val === 'string', 'must be a string');
+
+export const isObject = validator(
+  (val) => typeof val === 'object' && !Array.isArray(val) && val !== null,
+  'must be an object (not an array or null)',
+);
+
+export const isUuid = validator(
+  (val) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(val) || /^[0-9a-f]{36}$/i.test(val),
+  'must be a valid UUID or a 36-character hexadecimal string',
+);

package/packages/framework/esm-config/src/validators/validator.ts

@@ -0,0 +1,38 @@
+/** @module @category Config Validation */
+import type { 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 function validator(
+  validationFunction: ValidatorFunction,
+  message: string | ((value: any) => string),
+): Validator {
+  return (value) => {
+    if (!validationFunction(value)) {
+      if (typeof message === 'function') {
+        return message(value);
+      } else {
+        return message;
+      }
+    }
+  };
+}

package/packages/framework/esm-config/src/validators/validators.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { inRange, isUrl, isUrlWithTemplateParameters, oneOf } from './validators';
+
+describe('all validators', () => {
+  it('fail on undefined', () => {
+    expect(inRange(0, 10)(undefined)).toMatch(/.*/);
+    expect(isUrl(undefined)).toMatch(/.*/);
+    expect(isUrlWithTemplateParameters(['foo'])(undefined)).toMatch(/.*/);
+    expect(oneOf(['foo', 'bar'])(undefined)).toMatch(/.*/);
+  });
+});
+
+describe('isUrl', () => {
+  it('accepts a string with valid URL parameters', () => {
+    expect(isUrl('${openmrsSpaBase}/${openmrsBase}/thing')).toBeUndefined();
+  });
+
+  it('accepts a string with no parameters', () => {
+    expect(isUrl('/thing')).toBeUndefined();
+  });
+
+  it('rejects a string with unknkown URL parameters', () => {
+    expect(isUrl('${foo}/bad')).toMatch(/allowed template parameters are \${openmrsBase}, \${openmrsSpaBase}/i);
+  });
+});
+
+describe('oneOf', () => {
+  it('accepts one of the valid options', () => {
+    expect(oneOf(['foo', 'bar'])('foo')).toBeUndefined();
+  });
+
+  it('rejects anything else', () => {
+    expect(oneOf(['foo', 'bar'])('baz')).toMatch(/one of.*foo.*bar/i);
+  });
+});

package/packages/framework/esm-config/src/validators/validators.ts

@@ -0,0 +1,70 @@
+/** @module @category Config Validation */
+import { validator } from './validator';
+
+/**
+ * Verifies that the value is between the provided minimum and maximum
+ *
+ * @param min Minimum acceptable value
+ * @param max Maximum acceptable value
+ */
+export const inRange = (min: number, max: number) => {
+  return validator((val) => min <= val && val <= max, `must be between ${min} and ${max}`);
+};
+
+/**
+ * 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 const isUrlWithTemplateParameters = (allowedTemplateParameters: Array<string> | readonly string[]) => {
+  const allowedParams = allowedTemplateParameters.concat(['openmrsBase', 'openmrsSpaBase']);
+  return validator(
+    (val) => {
+      if (!val || typeof val != 'string') {
+        return false;
+      }
+
+      const rx = /\${(.*?)}/g;
+      let match = rx.exec(val);
+
+      while (match) {
+        if (!allowedParams.includes(match[1])) {
+          return false;
+        }
+
+        match = rx.exec(val);
+      }
+
+      return true;
+    },
+    'Should be a URL or path. The allowed template parameters are ' +
+      allowedParams.map((p) => '${' + p + '}').join(', '),
+  );
+};
+
+/**
+ * Verifies that a string contains only the default URL template parameters.
+ *
+ * @category Navigation
+ */
+export const isUrl = isUrlWithTemplateParameters([]);
+
+/**
+ * Verifies that the value is one of the allowed options.
+ * @param allowedValues The list of allowable values
+ */
+export const oneOf = (allowedValues: Array<any> | readonly any[]) => {
+  return validator(
+    (val) => allowedValues.includes(val),
+    `Must be one of the following: '${allowedValues.join("', '")}'.`,
+  );
+};
+
+export const validators = {
+  inRange,
+  isUrl,
+  isUrlWithTemplateParameters,
+  oneOf,
+};

package/packages/framework/esm-config/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig.json",
+  "compilerOptions": {
+    "declarationDir": "dist",
+    "emitDeclarationOnly": true
+  },
+  "extends": "./tsconfig.json",
+  "exclude": ["**/*.test.*", "**/setup-tests.*"]
+}

package/packages/framework/esm-config/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig.json",
+  "extends": "../tsconfig.json",
+  "include": ["src/**/*.ts*"]
+}

package/packages/framework/esm-config/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'happy-dom',
+    mockReset: true,
+  },
+});

package/packages/framework/esm-context/.swcrc

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://swc.rs/schema.json",
+  "exclude": [".*\\.test\\..*", "setup-tests\\..*"],
+  "module": {
+    "type": "es6",
+    "resolveFully": true
+  },
+  "jsc": {
+    "parser": {
+      "syntax": "typescript",
+      "tsx": false
+    },
+    "target": "es2020",
+    "baseUrl": "src"
+  }
+}

package/packages/framework/esm-context/README.md

@@ -0,0 +1,3 @@
+# openmrs-esm-context
+
+openmrs-esm-context provides the AppContext that is useful for sharing contextual state across the application.