@openmrs/esm-utils 6.3.1-pre.2961 → 6.3.1-pre.2986

package/dist/patient-helpers.d.ts

@@ -0,0 +1,42 @@
+/** @module @category Utility */
+/// <reference types="fhir" />
+import { type NameUse } from '@openmrs/esm-globals';
+/**
+ * Gets the formatted display name for a patient.
+ *
+ * The display name will be taken from the patient's 'usual' name,
+ * or may fall back to the patient's 'official' name.
+ *
+ * @param patient The patient details in FHIR format.
+ * @returns The patient's display name or an empty string if name is not present.
+ */
+export declare function getPatientName(patient: fhir.Patient): string;
+/** @deprecated Use `getPatientName` */
+export declare function displayName(patient: fhir.Patient): string;
+/**
+ * Get a formatted display string for an FHIR name.
+ * @param name The name to be formatted.
+ * @returns The formatted display name or an empty string if name is undefined.
+ */
+export declare function formatPatientName(name: fhir.HumanName | undefined): string;
+/** @deprecated Use `formatPatientName` */
+export declare function formattedName(name: fhir.HumanName | undefined): string;
+/**
+ * Select the preferred name from the collection of names associated with a patient.
+ *
+ * Names may be specified with a usage such as 'usual', 'official', 'nickname', 'maiden', etc.
+ * A name with no usage specified is treated as the 'usual' name.
+ *
+ * The chosen name will be selected according to the priority order of `preferredNames`,
+ * @example
+ * // normal use case; prefer usual name, fallback to official name
+ * displayNameByUsage(patient, 'usual', 'official')
+ * @example
+ * // prefer usual name over nickname, fallback to official name
+ * displayNameByUsage(patient, 'usual', 'nickname', 'official')
+ *
+ * @param patient The patient from whom a name will be selected.
+ * @param preferredNames Optional ordered sequence of preferred name usages; defaults to 'usual' if not specified.
+ * @return the preferred name for the patient, or undefined if no acceptable name could be found.
+ */
+export declare function selectPreferredName(patient: fhir.Patient, ...preferredNames: NameUse[]): fhir.HumanName | undefined;

package/dist/patient-helpers.js

@@ -0,0 +1,78 @@
+/** @module @category Utility */ /**
+ * Gets the formatted display name for a patient.
+ *
+ * The display name will be taken from the patient's 'usual' name,
+ * or may fall back to the patient's 'official' name.
+ *
+ * @param patient The patient details in FHIR format.
+ * @returns The patient's display name or an empty string if name is not present.
+ */ export function getPatientName(patient) {
+    const name = selectPreferredName(patient, 'usual', 'official');
+    return formatPatientName(name);
+}
+/** @deprecated Use `getPatientName` */ export function displayName(patient) {
+    return getPatientName(patient);
+}
+/**
+ * Get a formatted display string for an FHIR name.
+ * @param name The name to be formatted.
+ * @returns The formatted display name or an empty string if name is undefined.
+ */ export function formatPatientName(name) {
+    if (name) return name.text ?? defaultFormat(name);
+    return '';
+}
+/** @deprecated Use `formatPatientName` */ export function formattedName(name) {
+    return formatPatientName(name);
+}
+/**
+ * Select the preferred name from the collection of names associated with a patient.
+ *
+ * Names may be specified with a usage such as 'usual', 'official', 'nickname', 'maiden', etc.
+ * A name with no usage specified is treated as the 'usual' name.
+ *
+ * The chosen name will be selected according to the priority order of `preferredNames`,
+ * @example
+ * // normal use case; prefer usual name, fallback to official name
+ * displayNameByUsage(patient, 'usual', 'official')
+ * @example
+ * // prefer usual name over nickname, fallback to official name
+ * displayNameByUsage(patient, 'usual', 'nickname', 'official')
+ *
+ * @param patient The patient from whom a name will be selected.
+ * @param preferredNames Optional ordered sequence of preferred name usages; defaults to 'usual' if not specified.
+ * @return the preferred name for the patient, or undefined if no acceptable name could be found.
+ */ export function selectPreferredName(patient, ...preferredNames) {
+    if (preferredNames.length == 0) {
+        preferredNames = [
+            'usual'
+        ];
+    }
+    for (const usage of preferredNames){
+        const name = patient.name?.find((name)=>nameUsageMatches(name, usage));
+        if (name) {
+            return name;
+        }
+    }
+    return undefined;
+}
+/**
+ * Generate a display name by concatenating forenames and surname.
+ * @param name the person's name.
+ * @returns the person's name as a string.
+ */ function defaultFormat(name) {
+    const forenames = name.given ?? [];
+    const names = name.family ? forenames.concat(name.family) : forenames;
+    return names.join(' ');
+}
+/**
+ * Determine whether the usage of a given name matches the given NameUse.
+ *
+ * A name with no usage is treated as the 'usual' name.
+ *
+ * @param name the name to test.
+ * @param usage the NameUse to test for.
+ */ function nameUsageMatches(name, usage) {
+    if (!name.use) // a name with no usage is treated as 'usual'
+    return usage === 'usual';
+    return name.use === usage;
+}

package/dist/retry.d.ts

@@ -0,0 +1,38 @@
+/** @module @category Utility */
+/**
+ * Options for configuring the behavior of the {@link retry} function.
+ */
+export interface RetryOptions {
+    /**
+     * Determines whether the retry function should retry executing the function after it failed
+     * with an error on the current attempt.
+     * @param attempt The current (zero-based) retry attempt. `0` indicates the initial attempt.
+     */
+    shouldRetry?(attempt: number): any;
+    /**
+     * Calculates the next delay (in milliseconds) before a retry attempt.
+     * Returning a value for the inital attempt (`0`) delays the initial function invocation.
+     * @param attempt The current (zero-based) retry attempt. `0` indicates the initial attempt.
+     */
+    getDelay?(attempt: number): number;
+    /**
+     * Called when invoking the function resulted in an error.
+     * Allows running side-effects on errors, e.g. logging.
+     * @param e The error thrown by the function.
+     * @param attempt The current (zero-based) retry attempt. `0` indicates the initial attempt.
+     */
+    onError?(e: any, attempt: number): void;
+}
+/**
+ * Executes the specified function and retries executing on failure with a custom backoff strategy
+ * defined by the options.
+ *
+ * If not configured otherwise, this function uses the following default options:
+ * * Retries 5 times beyond the initial attempt.
+ * * Uses an exponential backoff starting with an initial delay of 1000ms.
+ * @param fn The function to be executed and retried on failure.
+ * @param options Additional options which configure the retry behavior.
+ * @returns The result of successfully executing `fn`.
+ * @throws Rethrows the final error of running `fn` when the function stops retrying.
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/retry.js

@@ -0,0 +1,45 @@
+/** @module @category Utility */ /**
+ * Options for configuring the behavior of the {@link retry} function.
+ */ /**
+ * Executes the specified function and retries executing on failure with a custom backoff strategy
+ * defined by the options.
+ *
+ * If not configured otherwise, this function uses the following default options:
+ * * Retries 5 times beyond the initial attempt.
+ * * Uses an exponential backoff starting with an initial delay of 1000ms.
+ * @param fn The function to be executed and retried on failure.
+ * @param options Additional options which configure the retry behavior.
+ * @returns The result of successfully executing `fn`.
+ * @throws Rethrows the final error of running `fn` when the function stops retrying.
+ */ export async function retry(fn, options = {}) {
+    let { shouldRetry, getDelay, onError } = options;
+    shouldRetry = shouldRetry ?? ((attempt)=>limitAttempts(attempt, 5));
+    getDelay = getDelay ?? ((attempt)=>getExponentialDelay(attempt, 1000));
+    let attempt = 0;
+    let lastError = undefined;
+    do {
+        try {
+            await delay(getDelay(attempt));
+            return await fn();
+        } catch (e) {
+            onError?.(e, attempt);
+            lastError = e;
+        }
+    }while (shouldRetry(attempt++))
+    // If we reach this fn errored and shouldn't retry anymore. Simply rethrow the final error as
+    // a means of ending the retry process without a result.
+    throw lastError;
+}
+function limitAttempts(attempt, maxAttempts) {
+    return attempt <= maxAttempts;
+}
+function getExponentialDelay(attempt, startingDelay, initialDelay = false) {
+    const exponent = initialDelay ? attempt + 1 : attempt;
+    return startingDelay * Math.pow(2, exponent);
+}
+async function delay(ms) {
+    if (ms <= 0) {
+        return;
+    }
+    return new Promise((res)=>setTimeout(res, ms));
+}

package/dist/shallowEqual.d.ts

@@ -0,0 +1,12 @@
+/** @module @category Utility */
+/**
+ * Checks whether two objects are equal, using a shallow comparison, similar to React.
+ *
+ * In essence, shallowEquals ensures two objects have the same own properties and that the values
+ * of these are equal (===) to each other.
+ *
+ * @param a The first value to compare
+ * @param b The second value to compare
+ * @returns true if the objects are shallowly equal to each other
+ */
+export declare function shallowEqual(a: unknown, b: unknown): boolean;

package/dist/shallowEqual.js

@@ -0,0 +1,36 @@
+/** @module @category Utility */ /**
+ * Checks whether two objects are equal, using a shallow comparison, similar to React.
+ *
+ * In essence, shallowEquals ensures two objects have the same own properties and that the values
+ * of these are equal (===) to each other.
+ *
+ * @param a The first value to compare
+ * @param b The second value to compare
+ * @returns true if the objects are shallowly equal to each other
+ */ export function shallowEqual(a, b) {
+    if (a === b || Object.is(a, b)) {
+        return true;
+    }
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b)) {
+            return false;
+        }
+        if (a.length !== b.length) {
+            return false;
+        }
+        for(let i = 0; i < a.length; i++){
+            if (a[i] !== b[i]) {
+                return false;
+            }
+        }
+        return true;
+    } else if (Array.isArray(b)) {
+        return false;
+    }
+    if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+        return false;
+    }
+    const objAKeys = Object.getOwnPropertyNames(a);
+    const objBKeys = Object.getOwnPropertyNames(b);
+    return objAKeys.length === objBKeys.length && objAKeys.every((key)=>a[key] === b[key]);
+}

package/dist/storage.d.ts

@@ -0,0 +1,10 @@
+/** @module @category Utility */
+/**
+ * Simple utility function to determine if an object implementing the WebStorage API
+ * is actually available. Useful for testing the availability of `localStorage` or
+ * `sessionStorage`.
+ *
+ * @param storage The WebStorage API object to check. Defaults to `localStorage`.
+ * @returns True if the WebStorage API object is able to be accessed, false otherwise
+ */
+export declare function canAccessStorage(storage?: Storage): boolean;

package/dist/storage.js

@@ -0,0 +1,15 @@
+/** @module @category Utility */ /**
+ * Simple utility function to determine if an object implementing the WebStorage API
+ * is actually available. Useful for testing the availability of `localStorage` or
+ * `sessionStorage`.
+ *
+ * @param storage The WebStorage API object to check. Defaults to `localStorage`.
+ * @returns True if the WebStorage API object is able to be accessed, false otherwise
+ */ export function canAccessStorage(storage = window.localStorage) {
+    try {
+        storage.getItem('test');
+        return true;
+    } catch  {
+        return false;
+    }
+}

package/dist/test-helpers.d.ts

@@ -0,0 +1,12 @@
+/** @module @category Utility */
+/**
+ * Given a config schema, this returns an object like is returned by `useConfig`
+ * with all default values.
+ *
+ * This should be used in tests and not in production code.
+ *
+ * If all you need is the default values in your tests, these are returned by
+ * default from the `useConfig`/`getConfig` mock. This function is useful if you
+ * need to override some of the default values.
+ */
+export declare function getDefaultsFromConfigSchema<T = Record<string, any>>(schema: Record<string | number | symbol, unknown>): T;

package/dist/test-helpers.js

@@ -0,0 +1,27 @@
+/** @module @category Utility */ /**
+ * Given a config schema, this returns an object like is returned by `useConfig`
+ * with all default values.
+ *
+ * This should be used in tests and not in production code.
+ *
+ * If all you need is the default values in your tests, these are returned by
+ * default from the `useConfig`/`getConfig` mock. This function is useful if you
+ * need to override some of the default values.
+ */ export function getDefaultsFromConfigSchema(schema) {
+    let tmp = {};
+    for (let k of Object.keys(schema)){
+        if (isOrdinaryObject(schema[k]) && schema[k].hasOwnProperty('_default')) {
+            tmp[k] = schema[k]._default;
+        } else if (k.startsWith('_')) {
+            continue;
+        } else if (isOrdinaryObject(schema[k])) {
+            tmp[k] = getDefaultsFromConfigSchema(schema[k]);
+        } else {
+            tmp[k] = schema[k];
+        }
+    }
+    return tmp;
+}
+function isOrdinaryObject(x) {
+    return !!x && x.constructor === Object;
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare function isVersionSatisfied(requiredVersion: string, installedVersion: string): boolean;

package/dist/version.js

@@ -0,0 +1,21 @@
+/** @module @category Utility */ import * as semver from "semver";
+function normalizeOnlyVersion(version) {
+    const [major, minor, patch] = version.split('.');
+    return `${major}.${minor}.${patch}`;
+}
+function normalizeFullVersion(version) {
+    const idx = version.indexOf('-');
+    const prerelease = idx >= 0;
+    if (prerelease) {
+        const ver = normalizeOnlyVersion(version.slice(0, idx));
+        const pre = version.slice(idx + 1);
+        return `${ver}-${pre}`;
+    }
+    return normalizeOnlyVersion(version);
+}
+export function isVersionSatisfied(requiredVersion, installedVersion) {
+    const version = normalizeFullVersion(installedVersion);
+    return semver.satisfies(version, requiredVersion, {
+        includePrerelease: true
+    });
+}

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "@openmrs/esm-utils",
-  "version": "6.3.1-pre.2961",
+  "version": "6.3.1-pre.2986",
   "license": "MPL-2.0",
   "description": "Helper utilities for OpenMRS",
-  "browser": "dist/openmrs-esm-utils.js",
-  "main": "src/index.ts",
+  "type": "module",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "source": true,
   "sideEffects": false,
   "scripts": {
-    "test": "cross-env TZ=UTC jest --config jest.config.js --verbose false --passWithNoTests --color",
-    "test:watch": "cross-env TZ=UTC jest --watch --config jest.config.js --color",
-    "build": "webpack --mode=production",
-    "build:development": "webpack --mode development",
-    "analyze": "webpack --mode=production --env analyze=true",
-    "typescript": "tsc",
+    "test": "cross-env TZ=UTC vitest run --passWithNoTests",
+    "test:watch": "cross-env TZ=UTC vitest watch --passWithNoTests",
+    "build": "rimraf dist && concurrently \"swc --strip-leading-paths src -d dist\" \"tsc --project tsconfig.build.json\"",
+    "build:development": "rimraf dist && concurrently \"swc --strip-leading-paths src -d dist\" \"tsc --project tsconfig.build.json\"",
+    "typescript": "tsc --project tsconfig.build.json",
     "lint": "eslint src --ext ts,tsx"
   },
   "keywords": [
@@ -38,13 +44,12 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "@openmrs/esm-globals": "6.3.1-pre.2961",
-    "@types/lodash-es": "^4.17.12",
-    "@types/semver": "^7.3.4",
-    "dayjs": "^1.10.4",
-    "jest": "^29.7.0",
-    "rxjs": "^6.5.3"
+  "dependencies": {
+    "@formatjs/intl-durationformat": "^0.7.3",
+    "@internationalized/date": "^3.8.0",
+    "any-date-parser": "^2.0.3",
+    "lodash-es": "^4.17.21",
+    "semver": "7.3.2"
   },
   "peerDependencies": {
     "@openmrs/esm-globals": "6.x",
@@ -52,12 +57,19 @@
     "i18next": "21.x",
     "rxjs": "6.x"
   },
-  "dependencies": {
-    "@formatjs/intl-durationformat": "^0.7.3",
-    "@internationalized/date": "^3.8.0",
-    "any-date-parser": "^2.0.3",
-    "lodash-es": "^4.17.21",
-    "semver": "7.3.2"
+  "devDependencies": {
+    "@openmrs/esm-globals": "6.3.1-pre.2986",
+    "@swc/cli": "^0.7.7",
+    "@swc/core": "^1.11.29",
+    "@types/lodash-es": "^4.17.12",
+    "@types/semver": "^7.3.4",
+    "concurrently": "^9.1.2",
+    "cross-env": "^7.0.3",
+    "dayjs": "^1.11.13",
+    "happy-dom": "^17.4.7",
+    "rimraf": "^6.0.1",
+    "rxjs": "^6.5.3",
+    "vitest": "^3.1.4"
   },
   "stableVersion": "6.3.0"
 }

package/src/age-helpers.test.ts

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import dayjs from 'dayjs';
 import type { i18n } from 'i18next';
 import { age } from '.';

package/src/age-helpers.ts

@@ -3,7 +3,7 @@ import { DurationFormat } from '@formatjs/intl-durationformat';
 import { type DurationFormatOptions, type DurationInput } from '@formatjs/intl-durationformat/src/types';
 import { attempt } from 'any-date-parser';
 import dayjs from 'dayjs';
-import objectSupport from 'dayjs/plugin/objectSupport';
+import objectSupport from 'dayjs/plugin/objectSupport.js';
 import { omit } from 'lodash-es';
 import { getLocale } from './get-locale';
 

package/src/dates/date-util.test.ts

@@ -1,3 +1,7 @@
+import { describe, expect, it } from 'vitest';
+import dayjs from 'dayjs';
+import timezoneMock from 'timezone-mock';
+import type { i18n } from 'i18next';
 import {
   toOmrsIsoString,
   toDateObjectStrict,
@@ -8,9 +12,6 @@ import {
   registerDefaultCalendar,
   formatPartialDate,
 } from './date-util';
-import dayjs from 'dayjs';
-import timezoneMock from 'timezone-mock';
-import type { i18n } from 'i18next';
 
 window.i18next = { language: 'en' } as i18n;
 

package/src/dates/date-util.ts

@@ -10,13 +10,13 @@ import {
   createCalendar,
   toCalendar,
 } from '@internationalized/date';
-import { getLocale } from '@openmrs/esm-utils';
 import { attempt } from 'any-date-parser';
 import dayjs from 'dayjs';
-import isToday from 'dayjs/plugin/isToday';
-import objectSupport from 'dayjs/plugin/objectSupport';
-import utc from 'dayjs/plugin/utc';
+import isToday from 'dayjs/plugin/isToday.js';
+import objectSupport from 'dayjs/plugin/objectSupport.js';
+import utc from 'dayjs/plugin/utc.js';
 import { isNil, omit } from 'lodash-es';
+import { getLocale } from '../';
 
 dayjs.extend(isToday);
 dayjs.extend(utc);

package/src/patient-helpers.test.ts

@@ -1,3 +1,5 @@
+import { describe, expect, it } from 'vitest';
+import { type NameUse } from '@openmrs/esm-globals';
 import { formatPatientName, getPatientName, selectPreferredName } from './patient-helpers';
 import {
   mockPatientWithNoName,
@@ -9,7 +11,6 @@ import {
   mockPatientWithMultipleNames,
   mockPatientWithNickAndOfficialName,
 } from './patient-helpers.test.data';
-import { type NameUse } from '@openmrs/esm-globals';
 
 describe('Formatted display name', () => {
   it.each([

package/src/test-helpers.ts

@@ -10,15 +10,20 @@
  * default from the `useConfig`/`getConfig` mock. This function is useful if you
  * need to override some of the default values.
  */
-export function getDefaultsFromConfigSchema<T = Record<string, any>>(schema): T {
+export function getDefaultsFromConfigSchema<T = Record<string, any>>(
+  schema: Record<string | number | symbol, unknown>,
+): T {
   let tmp = {};
   for (let k of Object.keys(schema)) {
-    if (schema[k].hasOwnProperty('_default')) {
-      tmp[k] = schema[k]._default;
+    if (
+      isOrdinaryObject(schema[k]) &&
+      (schema[k] as Record<string | number | symbol, unknown>).hasOwnProperty('_default')
+    ) {
+      tmp[k] = (schema[k] as Record<string | number | symbol, unknown>)._default;
     } else if (k.startsWith('_')) {
       continue;
     } else if (isOrdinaryObject(schema[k])) {
-      tmp[k] = getDefaultsFromConfigSchema(schema[k]);
+      tmp[k] = getDefaultsFromConfigSchema(schema[k] as Record<string | number | symbol, unknown>);
     } else {
       tmp[k] = schema[k];
     }
@@ -26,6 +31,6 @@ export function getDefaultsFromConfigSchema<T = Record<string, any>>(schema): T
   return tmp as T;
 }
 
-function isOrdinaryObject(x) {
+function isOrdinaryObject(x: any): x is Record<string | number | symbol, unknown> {
   return !!x && x.constructor === Object;
 }

package/src/version.test.ts

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { isVersionSatisfied } from './version';
 
 describe('Version utilities', () => {
@@ -53,13 +54,16 @@ describe('Version utilities', () => {
 
   it('Is satisfied with major version caret specifier and pre', () => {
     const result = isVersionSatisfied('^3', '3.1.14-pre.3');
+    expect(result).toBe(true);
   });
 
   it('Is satisfied with major version caret specifier and pre and a build number', () => {
     const result = isVersionSatisfied('^3', '3.1.14.7e24fb-pre.3');
+    expect(result).toBe(true);
   });
 
   it('Is satisfied with major version caret specifier and a build number', () => {
     const result = isVersionSatisfied('^3', '3.1.14.7e24fb');
+    expect(result).toBe(true);
   });
 });

package/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/tsconfig.json

@@ -1,25 +1,5 @@
 {
-  "compilerOptions": {
-    "esModuleInterop": true,
-    "module": "esnext",
-    "target": "es2015",
-    "allowSyntheticDefaultImports": true,
-    "jsx": "react",
-    "strictNullChecks": true,
-    "moduleResolution": "node",
-    "declaration": true,
-    "declarationDir": "dist",
-    "emitDeclarationOnly": true,
-    "lib": [
-      "dom",
-      "es5",
-      "scripthost",
-      "es2015",
-      "es2015.promise",
-      "es2016.array.include",
-      "es2018",
-      "esnext"
-    ]
-  },
-  "include": ["src/**/*"]
+  "$schema": "https://json.schemastore.org/tsconfig.json",
+  "extends": "../tsconfig.json",
+  "include": ["./src/**/*.ts*"]
 }

package/vitest.config.ts

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