@koech/esm-core 8.0.0

package/packages/framework/esm-emr-api/mock-jest.ts

@@ -0,0 +1,10 @@
+export const setCurrentVisit = jest.fn();
+export const attachmentUrl = '/ws/rest/v1/attachment';
+export const getAttachmentByUuid = jest.fn();
+export const getAttachments = jest.fn();
+export const createAttachment = jest.fn();
+export const deleteAttachmentPermanently = jest.fn();
+export const updateVisit = jest.fn();
+export const saveVisit = jest.fn();
+export const getVisitsForPatient = jest.fn();
+export const getStartedVisit = jest.fn();

package/packages/framework/esm-emr-api/mock.ts

@@ -0,0 +1,12 @@
+import { vi } from 'vitest';
+
+export const setCurrentVisit = vi.fn();
+export const attachmentUrl = '/ws/rest/v1/attachment';
+export const getAttachmentByUuid = vi.fn();
+export const getAttachments = vi.fn();
+export const createAttachment = vi.fn();
+export const deleteAttachmentPermanently = vi.fn();
+export const updateVisit = vi.fn();
+export const saveVisit = vi.fn();
+export const getVisitsForPatient = vi.fn();
+export const getStartedVisit = vi.fn();

package/packages/framework/esm-emr-api/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@openmrs/esm-emr-api",
+  "version": "8.0.0",
+  "license": "MPL-2.0",
+  "description": "The javascript module for interacting with the OpenMRS API",
+  "type": "module",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./src/public": {
+      "types": "./src/public.ts",
+      "default": "./dist/public.js"
+    },
+    "./mock": {
+      "import": "./mock.ts",
+      "require": "./mock-jest.ts"
+    }
+  },
+  "source": true,
+  "scripts": {
+    "test": "cross-env TZ=UTC vitest run --passWithNoTests",
+    "test:watch": "cross-env TZ=UTC vitest watch --passWithNoTests",
+    "coverage": "cross-env TZ=UTC vitest run --coverage --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": [
+    "openmrs",
+    "microfrontends"
+  ],
+  "directories": {
+    "lib": "dist",
+    "src": "src"
+  },
+  "browserslist": [
+    "extends browserslist-config-openmrs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openmrs/openmrs-esm-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/openmrs/openmrs-esm-core/issues"
+  },
+  "homepage": "https://github.com/openmrs/openmrs-esm-core#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@types/fhir": "0.0.31",
+    "lodash-es": "^4.17.21"
+  },
+  "peerDependencies": {
+    "@openmrs/esm-api": "6.x",
+    "@openmrs/esm-offline": "6.x",
+    "@openmrs/esm-state": "6.x"
+  },
+  "devDependencies": {
+    "@openmrs/esm-api": "workspace:*",
+    "@openmrs/esm-offline": "workspace:*",
+    "@openmrs/esm-state": "workspace:*",
+    "@swc/cli": "^0.7.7",
+    "@swc/core": "^1.11.29",
+    "@vitest/coverage-v8": "^4.0.7",
+    "concurrently": "^9.1.2",
+    "cross-env": "^7.0.3",
+    "happy-dom": "^17.4.7",
+    "rimraf": "^6.0.1",
+    "rxjs": "^6.5.3",
+    "vitest": "^4.0.7"
+  }
+}

package/packages/framework/esm-emr-api/src/attachments.ts

@@ -0,0 +1,43 @@
+/** @module @category API */
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-api';
+import type { UploadedFile } from './types';
+
+export const attachmentUrl = `${restBaseUrl}/attachment`;
+
+export function getAttachmentByUuid(attachmentUuid: string, abortController: AbortController) {
+  return openmrsFetch(`${attachmentUrl}/${attachmentUuid}`, {
+    signal: abortController.signal,
+  });
+}
+
+export function getAttachments(patientUuid: string, includeEncounterless: boolean, abortController: AbortController) {
+  return openmrsFetch(`${attachmentUrl}?patient=${patientUuid}&includeEncounterless=${includeEncounterless}`, {
+    signal: abortController.signal,
+  });
+}
+
+export async function createAttachment(patientUuid: string, fileToUpload: UploadedFile) {
+  const formData = new FormData();
+
+  formData.append('fileCaption', fileToUpload.fileDescription);
+  formData.append('patient', patientUuid);
+
+  if (fileToUpload.file) {
+    formData.append('file', fileToUpload.file, fileToUpload.fileName);
+  } else {
+    formData.append('file', new File([''], fileToUpload.fileName), fileToUpload.fileName);
+    formData.append('base64Content', fileToUpload.base64Content);
+  }
+
+  return openmrsFetch(`${attachmentUrl}`, {
+    method: 'POST',
+    body: formData,
+  });
+}
+
+export function deleteAttachmentPermanently(attachmentUuid: string, abortController: AbortController) {
+  return openmrsFetch(`${attachmentUrl}/${attachmentUuid}`, {
+    method: 'DELETE',
+    signal: abortController.signal,
+  });
+}

package/packages/framework/esm-emr-api/src/current-patient.test.ts

@@ -0,0 +1,53 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { openmrsFetch, type FetchResponse } from '@openmrs/esm-api';
+import { getSynchronizationItems } from '@openmrs/esm-offline';
+import { fetchCurrentPatient } from './current-patient';
+
+vi.mock('@openmrs/esm-api');
+
+const mockOpenmrsFetch = vi.mocked(openmrsFetch);
+const mockGetSynchronizationItems = vi.mocked(getSynchronizationItems);
+
+vi.mock('../openmrs-fetch', () => ({
+  openmrsFetch: vi.fn(),
+  fhirBaseUrl: '/ws/fhir2/R4',
+}));
+
+vi.mock('@openmrs/esm-offline', () => ({
+  getSynchronizationItems: vi.fn(),
+}));
+
+describe('fetchPatientData', () => {
+  beforeEach(() => {
+    mockGetSynchronizationItems.mockResolvedValue([]);
+  });
+
+  it('should return null when patientUuid is falsy', async () => {
+    const result = await fetchCurrentPatient('');
+    expect(result).toBeNull();
+  });
+
+  it('should return online patient data when available', async () => {
+    const mockPatient = { id: '123', name: [{ given: ['John'], family: 'Doe' }] };
+    mockOpenmrsFetch.mockResolvedValue({ data: mockPatient, ok: true } as Partial<FetchResponse> as FetchResponse);
+
+    const result = await fetchCurrentPatient('123');
+    expect(result).toEqual(mockPatient);
+  });
+
+  it('should return offline patient data when online fetch fails', async () => {
+    const mockOfflinePatient = { id: '123', name: [{ given: ['Jane'], family: 'Doe' }] };
+    mockOpenmrsFetch.mockRejectedValue(new Error('Network error'));
+    mockGetSynchronizationItems.mockResolvedValue([{ fhirPatient: mockOfflinePatient }]);
+
+    const result = await fetchCurrentPatient('123');
+    expect(result).toEqual(mockOfflinePatient);
+  });
+
+  it('should throw an error when both online and offline fetches fail', async () => {
+    mockOpenmrsFetch.mockRejectedValue(new Error('Network error'));
+    mockGetSynchronizationItems.mockResolvedValue([]);
+
+    await expect(fetchCurrentPatient('123')).rejects.toThrow('Network error');
+  });
+});

package/packages/framework/esm-emr-api/src/current-patient.ts

@@ -0,0 +1,58 @@
+/** @module @category API */
+import { fhirBaseUrl, openmrsFetch, type FetchConfig, type FetchResponse } from '@openmrs/esm-api';
+import { getSynchronizationItems } from '@openmrs/esm-offline';
+
+export type CurrentPatient = fhir.Patient | FetchResponse<fhir.Patient>;
+
+export interface CurrentPatientOptions {
+  includeConfig?: boolean;
+}
+
+export interface PatientWithFullResponse extends CurrentPatientOptions {
+  includeConfig: true;
+}
+
+export interface OnlyThePatient extends CurrentPatientOptions {
+  includeConfig: false;
+}
+
+export type PatientUuid = string | null;
+
+export async function fetchCurrentPatient(
+  patientUuid: PatientUuid,
+  fetchInit?: FetchConfig,
+  includeOfflinePatients: boolean = true,
+): Promise<fhir.Patient | null> {
+  if (patientUuid) {
+    let err: Error | null = null;
+    const [onlinePatient, offlinePatient] = await Promise.all([
+      openmrsFetch<fhir.Patient>(`${fhirBaseUrl}/Patient/${patientUuid}`, fetchInit).catch<FetchResponse<fhir.Patient>>(
+        (e) => (err = e),
+      ),
+      includeOfflinePatients ? getOfflineRegisteredPatientAsFhirPatient(patientUuid) : Promise.resolve(null),
+    ]);
+
+    if (onlinePatient.ok) {
+      return onlinePatient.data;
+    }
+
+    if (offlinePatient) {
+      return offlinePatient;
+    }
+
+    if (err) {
+      throw err;
+    }
+  }
+
+  return null;
+}
+
+async function getOfflineRegisteredPatientAsFhirPatient(patientUuid: string): Promise<fhir.Patient | null> {
+  const patientRegistrationSyncItems = await getSynchronizationItems<{
+    fhirPatient: fhir.Patient;
+  }>('patient-registration');
+  const patientSyncItem = patientRegistrationSyncItems.find((item) => item.fhirPatient.id === patientUuid);
+
+  return patientSyncItem?.fhirPatient ?? null;
+}

package/packages/framework/esm-emr-api/src/events/events.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireOpenmrsEvent, subscribeOpenmrsEvent } from './index';
+
+describe('Event system', () => {
+  describe('fireOpenmrsEvent', () => {
+    it('dispatches an event on window by default', () => {
+      const handler = vi.fn();
+      window.addEventListener('openmrs:started', handler);
+
+      fireOpenmrsEvent('started');
+
+      expect(handler).toHaveBeenCalledOnce();
+      window.removeEventListener('openmrs:started', handler);
+    });
+
+    it('dispatches an event with payload', () => {
+      const handler = vi.fn();
+      window.addEventListener('openmrs:before-page-changed', handler);
+
+      const payload = {
+        cancelNavigation: vi.fn(),
+        newPage: '/home',
+        oldUrl: 'http://localhost/old',
+        newUrl: 'http://localhost/new',
+      };
+      fireOpenmrsEvent('before-page-changed', payload);
+
+      expect(handler).toHaveBeenCalledOnce();
+      const event = handler.mock.calls[0][0] as CustomEvent;
+      expect(event.detail).toEqual(payload);
+      window.removeEventListener('openmrs:before-page-changed', handler);
+    });
+
+    it('returns true when event is not cancelled', () => {
+      const result = fireOpenmrsEvent('started');
+      expect(result).toBe(true);
+    });
+
+    it('returns false when event is cancelled', () => {
+      const handler = (e: Event) => e.preventDefault();
+      window.addEventListener('openmrs:started', handler);
+
+      const result = fireOpenmrsEvent('started');
+
+      expect(result).toBe(false);
+      window.removeEventListener('openmrs:started', handler);
+    });
+  });
+
+  describe('subscribeOpenmrsEvent', () => {
+    it('subscribes to an event on window by default', () => {
+      const handler = vi.fn();
+      const unsubscribe = subscribeOpenmrsEvent('started', handler);
+
+      fireOpenmrsEvent('started');
+
+      expect(handler).toHaveBeenCalledOnce();
+      unsubscribe();
+    });
+
+    it('receives the event payload', () => {
+      const handler = vi.fn();
+      const unsubscribe = subscribeOpenmrsEvent('before-page-changed', handler);
+
+      const payload = {
+        cancelNavigation: vi.fn(),
+        newPage: '/home',
+        oldUrl: 'http://localhost/old',
+        newUrl: 'http://localhost/new',
+      };
+      fireOpenmrsEvent('before-page-changed', payload);
+
+      expect(handler).toHaveBeenCalledWith(payload);
+      unsubscribe();
+    });
+
+    it('receives undefined for events without payload', () => {
+      const handler = vi.fn();
+      const unsubscribe = subscribeOpenmrsEvent('started', handler);
+
+      fireOpenmrsEvent('started');
+
+      expect(handler).toHaveBeenCalledWith(undefined);
+      unsubscribe();
+    });
+
+    it('unsubscribes correctly', () => {
+      const handler = vi.fn();
+      const unsubscribe = subscribeOpenmrsEvent('started', handler);
+
+      fireOpenmrsEvent('started');
+      expect(handler).toHaveBeenCalledOnce();
+
+      unsubscribe();
+
+      fireOpenmrsEvent('started');
+      expect(handler).toHaveBeenCalledOnce();
+    });
+
+    it('allows multiple subscribers to the same event', () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+      const unsubscribe1 = subscribeOpenmrsEvent('started', handler1);
+      const unsubscribe2 = subscribeOpenmrsEvent('started', handler2);
+
+      fireOpenmrsEvent('started');
+
+      expect(handler1).toHaveBeenCalledOnce();
+      expect(handler2).toHaveBeenCalledOnce();
+      unsubscribe1();
+      unsubscribe2();
+    });
+
+    it('calling unsubscribe multiple times is safe', () => {
+      const handler = vi.fn();
+      const unsubscribe = subscribeOpenmrsEvent('started', handler);
+
+      unsubscribe();
+      expect(() => unsubscribe()).not.toThrow();
+    });
+
+    it('unsubscribing one handler does not affect others', () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+      const unsubscribe1 = subscribeOpenmrsEvent('started', handler1);
+      const unsubscribe2 = subscribeOpenmrsEvent('started', handler2);
+
+      unsubscribe1();
+      fireOpenmrsEvent('started');
+
+      expect(handler1).not.toHaveBeenCalled();
+      expect(handler2).toHaveBeenCalledOnce();
+      unsubscribe2();
+    });
+  });
+});

package/packages/framework/esm-emr-api/src/events/index.ts

@@ -0,0 +1,45 @@
+import {
+  type EventsWithPayload,
+  type OpenmrsEvent,
+  type EventsWithoutPayload,
+  type EventTypes,
+  type PageChanged,
+} from './types';
+export { type OpenmrsEvent, type EventTypes as OpenmrsEventTypes } from './types';
+
+export function fireOpenmrsEvent<T extends EventsWithoutPayload>(event: T, payload?: never): boolean;
+export function fireOpenmrsEvent<T extends EventsWithPayload>(event: T, payload: EventTypes[T]): boolean;
+/**
+ * Fires an OpenMRS custom event
+ *
+ * @param event The custom event to fire
+ * @param payload The payload associated with this type of event
+ * @returns true if the event was not cancelled and false, i.e., the result of `dispatchEvent()`
+ */
+export function fireOpenmrsEvent<T extends OpenmrsEvent>(event: T, payload?: EventTypes[T]): boolean {
+  const evt = new CustomEvent(`openmrs:${event}`, { detail: payload ?? undefined, cancelable: true, bubbles: true });
+  return window.dispatchEvent(evt);
+}
+
+/**
+ * Subscribes to a custom OpenMRS event
+ *
+ * @param event The name of the event to listen to
+ * @param handler The callback to be called when the event fires
+ */
+export function subscribeOpenmrsEvent(event: 'started', handler: (payload: undefined) => void);
+export function subscribeOpenmrsEvent(event: 'before-page-changed', handler: (payload: PageChanged) => void);
+export function subscribeOpenmrsEvent<T extends OpenmrsEvent>(
+  event: T,
+  handler: (payload?: EventTypes[T]) => void,
+): () => void {
+  const internalHandler = (event: Event) => {
+    const detail = 'detail' in event && event.detail !== null ? event.detail : undefined;
+    handler(detail as EventTypes[T]);
+  };
+
+  window.addEventListener(`openmrs:${event}`, internalHandler);
+  return () => {
+    window.removeEventListener(`openmrs:${event}`, internalHandler);
+  };
+}

package/packages/framework/esm-emr-api/src/events/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Payload returned from the "page-change" event
+ */
+export interface PageChanged {
+  /**
+   * This function controls whether or not the page change goes ahead.
+   * Call this to interrupt the page navigation, e.g., if a user requested
+   * not to change the page.
+   *
+   * @param val If this is a value that ultimately results as "true", then navigation
+   *   is cancelled, which is the default value.
+   */
+  cancelNavigation(val?: boolean | Promise<boolean> | (() => boolean | Promise<boolean>)): void;
+  /**
+   * The name of the main content page that will be displayed, e.g., "@openmrs/esm-my-app-page-0".
+   * May be undefined if the navigation will not result in a main content page.
+   */
+  newPage: string | undefined;
+  /**
+   * The URL currently used by single-spa to determine the layout
+   */
+  oldUrl: string;
+  /**
+   * The URL that will be in effect once this update cycle is complete
+   */
+  newUrl: string;
+}
+
+/**
+ * This is the set of events supported by the custom event system
+ */
+export interface EventTypes {
+  /**
+   * The started event is fired once when the app started.
+   * Listeners should use this as an opportunity to do any initialization required.
+   */
+  started: never;
+  /**
+   * The before-page-changed event is fired before the active page in the application changes
+   */
+  'before-page-changed': PageChanged;
+}
+
+/**
+ * This type is the union of all supported events
+ */
+export type OpenmrsEvent = keyof EventTypes;
+
+export type EventsWithoutPayload = {
+  [K in OpenmrsEvent]: EventTypes[K] extends undefined ? K : never;
+}[OpenmrsEvent];
+
+export type EventsWithPayload = {
+  [K in OpenmrsEvent]: EventTypes[K] extends undefined ? never : K;
+}[OpenmrsEvent];

package/packages/framework/esm-emr-api/src/index.ts

@@ -0,0 +1,7 @@
+export * from './attachments';
+export * from './current-patient';
+export * from './events';
+export * from './location';
+export * from './types';
+export * from './visit-type';
+export * from './visit-utils';

package/packages/framework/esm-emr-api/src/location.ts

@@ -0,0 +1,36 @@
+/** @module @category API */
+import { openmrsObservableFetch, restBaseUrl } from '@openmrs/esm-api';
+import type { Observable } from 'rxjs';
+import { map, take } from 'rxjs/operators/index.js';
+import type { Location } from './types';
+
+export function toLocationObject(openmrsRestForm: any): Location {
+  return {
+    uuid: openmrsRestForm.uuid,
+    display: openmrsRestForm.display,
+  };
+}
+
+export function getLocations(
+  tagUuidOrName: string | null = null,
+  query: string | null = null,
+): Observable<Array<Location>> {
+  const params = new URLSearchParams();
+  if (tagUuidOrName) {
+    params.set('tag', tagUuidOrName);
+  }
+  if (query) {
+    params.set('q', query);
+  }
+  const queryString = params.toString();
+  const url = `${restBaseUrl}/location${queryString ? '?' + queryString : ''}`;
+
+  return openmrsObservableFetch<{ results: Array<Location> }>(url)
+    .pipe(
+      map((results) => {
+        const locations: Array<Location> = results.data.results.map(toLocationObject);
+        return locations;
+      }),
+    )
+    .pipe(take(1));
+}

package/packages/framework/esm-emr-api/src/public.ts

@@ -0,0 +1,7 @@
+export * from './attachments';
+export * from './current-patient';
+export { subscribeOpenmrsEvent, type OpenmrsEvent, type OpenmrsEventTypes } from './events';
+export * from './types';
+export * from './visit-utils';
+export * from './visit-type';
+export * from './location';

package/packages/framework/esm-emr-api/src/types/attachments-types.ts

@@ -0,0 +1,28 @@
+export interface UploadedFile {
+  file?: File;
+  base64Content: string;
+  fileName: string;
+  fileType: string;
+  fileDescription: string;
+  status?: 'uploading' | 'complete';
+  capturedFromWebcam?: boolean;
+}
+
+export interface Attachment {
+  id: string;
+  src: string;
+  filename: string;
+  dateTime: string;
+  bytesMimeType: string;
+  bytesContentFamily: string;
+  description?: string;
+}
+
+export interface AttachmentResponse {
+  bytesContentFamily: string;
+  bytesMimeType: string;
+  comment: string;
+  dateTime: string;
+  uuid: string;
+  filename?: string;
+}

package/packages/framework/esm-emr-api/src/types/diagnosis-resource.ts

@@ -0,0 +1,24 @@
+import { type Concept, type ConceptClass, type OpenmrsResource } from '@openmrs/esm-api';
+import { type Encounter } from './encounter-resource';
+import { type Patient } from './patient-resource';
+
+// TODO: make this extends OpenmrsResourceStrict
+export interface Diagnosis extends OpenmrsResource {
+  diagnosis?: {
+    coded?: {
+      uuid: string;
+      display?: string;
+      name?: Concept;
+      datatype?: OpenmrsResource;
+      conceptClass?: ConceptClass;
+    };
+    nonCoded?: string;
+  };
+  patient?: Patient;
+  encounter?: Encounter;
+  certainty?: string;
+  rank?: number;
+  formFieldNamespace?: string;
+  formFieldPath?: string;
+  voided?: boolean;
+}

package/packages/framework/esm-emr-api/src/types/drug-resource.ts

@@ -0,0 +1,9 @@
+import { type Concept, type OpenmrsResource } from '@openmrs/esm-api';
+
+export interface Drug extends OpenmrsResource {
+  uuid: string;
+  strength: string;
+  concept: Concept;
+  dosageForm: OpenmrsResource;
+  display: string;
+}

package/packages/framework/esm-emr-api/src/types/encounter-resource.ts

@@ -0,0 +1,36 @@
+import { type OpenmrsResource } from '@openmrs/esm-api';
+import { type Diagnosis } from './diagnosis-resource';
+import { type Location } from './location-resource';
+import { type Obs } from './obs-resource';
+import { type Patient } from './patient-resource';
+import { type Visit } from './visit-resource';
+
+// TODO: make this extends OpenmrsResourceStrict
+export interface Encounter extends OpenmrsResource {
+  encounterDatetime?: string;
+  patient?: Patient;
+  location?: Location;
+  encounterType?: EncounterType;
+  obs?: Array<Obs>;
+  visit?: Visit;
+  encounterProviders?: Array<EncounterProvider>;
+  diagnoses?: Array<Diagnosis>;
+  form?: OpenmrsResource;
+}
+
+export interface EncounterType extends OpenmrsResource {
+  name?: string;
+  description?: string;
+  retired?: boolean;
+}
+
+export interface EncounterProvider extends OpenmrsResource {
+  provider?: OpenmrsResource;
+  encounterRole?: EncounterRole;
+}
+
+export interface EncounterRole extends OpenmrsResource {
+  name?: string;
+  description?: string;
+  retired?: boolean;
+}