@openmrs/esm-emr-api 8.0.1-pre.3605 → 8.0.1-pre.3614

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 19 files with swc (122.56ms)
+[0] Successfully compiled: 21 files with swc (174.5ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/events/index.d.ts

@@ -0,0 +1,11 @@
+import { type EventsWithPayload, type OpenmrsEvent, type EventsWithoutPayload, type EventTypes } from './types';
+export { type OpenmrsEvent, type EventTypes as OpenmrsEventTypes } from './types';
+export declare function fireOpenmrsEvent<T extends EventsWithoutPayload>(event: T, payload?: never): boolean;
+export declare function fireOpenmrsEvent<T extends EventsWithPayload>(event: T, payload: EventTypes[T]): boolean;
+/**
+ * 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 declare function subscribeOpenmrsEvent<T extends OpenmrsEvent>(event: T, handler: (payload?: EventTypes[T]) => boolean | void): () => void;

package/dist/events/index.js

@@ -0,0 +1,29 @@
+/**
+ * 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(event, payload) {
+    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, handler) {
+    const internalHandler = (event)=>{
+        const detail = 'detail' in event && event.detail !== null ? event.detail : undefined;
+        handler(detail);
+    };
+    window.addEventListener(`openmrs:${event}`, internalHandler);
+    return ()=>{
+        window.removeEventListener(`openmrs:${event}`, internalHandler);
+    };
+}

package/dist/events/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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/dist/events/types.js

@@ -0,0 +1,3 @@
+/**
+ * Payload returned from the "page-change" event
+ */ export { };

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from "./attachments.js";
 export * from "./current-patient.js";
+export * from "./events/index.js";
 export * from "./location.js";
 export * from "./types/index.js";
 export * from "./visit-type.js";

package/dist/public.d.ts

@@ -1,5 +1,6 @@
 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';

package/dist/public.js

@@ -1,5 +1,6 @@
 export * from "./attachments.js";
 export * from "./current-patient.js";
+export { subscribeOpenmrsEvent } from "./events/index.js";
 export * from "./types/index.js";
 export * from "./visit-utils.js";
 export * from "./visit-type.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-emr-api",
-  "version": "8.0.1-pre.3605",
+  "version": "8.0.1-pre.3614",
   "license": "MPL-2.0",
   "description": "The javascript module for interacting with the OpenMRS API",
   "type": "module",
@@ -62,9 +62,9 @@
     "@openmrs/esm-state": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "8.0.1-pre.3605",
-    "@openmrs/esm-offline": "8.0.1-pre.3605",
-    "@openmrs/esm-state": "8.0.1-pre.3605",
+    "@openmrs/esm-api": "8.0.1-pre.3614",
+    "@openmrs/esm-offline": "8.0.1-pre.3614",
+    "@openmrs/esm-state": "8.0.1-pre.3614",
     "@swc/cli": "^0.7.7",
     "@swc/core": "^1.11.29",
     "@vitest/coverage-v8": "^4.0.7",

package/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/src/events/index.ts

@@ -0,0 +1,37 @@
+import { type EventsWithPayload, type OpenmrsEvent, type EventsWithoutPayload, type EventTypes } 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<T extends OpenmrsEvent>(
+  event: T,
+  handler: (payload?: EventTypes[T]) => boolean | 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/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/src/index.ts

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

package/src/public.ts

@@ -1,5 +1,6 @@
 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';