@effect.healthcare/messenger 0.3.1 → 0.4.2

package/src/messenger.ts

@@ -1,347 +1,386 @@
-/**
- * @module Component
- */
-
-// Base Component
-import { Component } from "@scalable.software/component";
-import { type Configuration } from "@scalable.software/component";
-
-// Component Metadata
-import { Tag, Attributes, Connection, Event, Gesture } from "./messenger.meta.js";
-import { Session, Protocol, Message } from "./messenger.meta.js";
-import { type Endpoint } from "./messenger.meta.js";
-
-// Component Validation
-import { Validate } from "./messenger.validation.js";
-
-/**
- * Configuration for the headless component — no template or stylesheet.
- * @category Configuration
- */
-export const configuration: Configuration = {
-  url: import.meta.url,
-} as const;
-
-/**
- * @category Component
- */
-export class Messenger extends Component {
-  /**
-   * The tag name of the component
-   * @category Configuration
-   */
-  public static get Tag() {
-    return Tag;
-  }
-
-  /**
-   * Only attributes defined the Attributes object will be observed in DOM
-   * @category State
-   */
-  public static get Attributes(): Attributes {
-    return Attributes;
-  }
-
-  /**
-   * The live connection status of the messenger. Internally owned.
-   * @category State
-   * @hidden
-   */
-  private _connection: Connection = Connection.DISCONNECTED;
-
-  /**
-   * The negotiate endpoint URL. When absent the messenger stays disconnected.
-   * @category State
-   * @hidden
-   */
-  private _endpoint: Endpoint | null = null;
-
-  /**
-   * The live Web PubSub socket. Held so it can be closed and replaced.
-   * @category State
-   * @hidden
-   */
-  private _socket: WebSocket | null = null;
-
-  /**
-   * Event subscription handler slots.
-   * @category Event
-   * @hidden
-   */
-  private _onendpointchange: EventListener | null = null;
-  private _onconnecting: EventListener | null = null;
-  private _onconnected: EventListener | null = null;
-  private _ondisconnected: EventListener | null = null;
-  private _onmasterdatachange: EventListener | null = null;
-
-  /**
-   * Cache element references to improve performance
-   * @category State
-   * @hidden
-   */
-  protected elements: {} = {};
-
-  /**
-   * @hidden
-   */
-  constructor() {
-    super(configuration);
-  }
-
-  /**
-   * The live connection status of the messenger. Internally owned — readable
-   * externally, but only mutable from within (protected setter).
-   * @category State
-   */
-  public get connection(): Connection {
-    return this._connection;
-  }
-
-  protected set connection(connection: Connection) {
-    // Guard
-    if (this._connection === connection) return;
-
-    // Mutate
-    this._connection = connection;
-    this.setAttribute(Attributes.CONNECTION, connection);
-
-    // Dispatch
-    const event = { detail: { connection } };
-    connection === Connection.CONNECTING &&
-      this._dispatchEvent(Event.ON_CONNECTING, event);
-    connection === Connection.CONNECTED &&
-      this._dispatchEvent(Event.ON_CONNECTED, event);
-    connection === Connection.DISCONNECTED &&
-      this._dispatchEvent(Event.ON_DISCONNECTED, event);
-  }
-
-  /**
-   * The negotiate endpoint URL. When absent the messenger stays disconnected.
-   * @category State
-   */
-  public get endpoint(): Endpoint | null {
-    return this._endpoint;
-  }
-
-  public set endpoint(endpoint: Endpoint | null) {
-    // Normalize
-    endpoint = endpoint ?? null;
-
-    // Validate
-    endpoint = endpoint ? Validate.endpoint(endpoint) : null;
-
-    // Guard
-    if (this._endpoint === endpoint) return;
-
-    // Mutate
-    this._endpoint = endpoint;
-    endpoint === null
-      ? this.removeAttribute(Attributes.ENDPOINT)
-      : this.setAttribute(Attributes.ENDPOINT, endpoint);
-
-    // Dispatch
-    this._dispatchEvent(Event.ON_ENDPOINT_CHANGE, { detail: { endpoint } });
-  }
-
-  /**
-   * The session token, read fresh from local storage on every access — never
-   * cached — because the License component renews and rewrites the key.
-   * @category Operation
-   * @hidden
-   */
-  private get _token(): string | null {
-    return localStorage.getItem(Session);
-  }
-
-  /**
-   * Negotiates a client access URL from the configured endpoint, authenticating
-   * with the session token, then opens the live connection. No-op when the
-   * endpoint or token is unavailable, or when already connecting or connected.
-   * @category Operation
-   */
-  public connect = async (): Promise<void> => {
-    const token = this._token;
-
-    // Gate + guard
-    if (!this.endpoint || !token) return;
-    if (this._connection !== Connection.DISCONNECTED) return;
-
-    // Establish
-    this.connection = Connection.CONNECTING;
-    const url = await this._negotiate(token);
-    this._socket = this._open(url);
-  };
-
-  /**
-   * Closes the live connection.
-   * @category Operation
-   */
-  public disconnect = (): void => {
-    this._socket?.close();
-    this._socket = null;
-    this.connection = Connection.DISCONNECTED;
-  };
-
-  /**
-   * Subscribes to the `onendpointchange` event. Assigning replaces the previous
-   * handler; assigning `null` removes it.
-   * @category Event
-   */
-  public set onendpointchange(handler: EventListener | null) {
-    this._onendpointchange &&
-      this.removeEventListener(Event.ON_ENDPOINT_CHANGE, this._onendpointchange);
-
-    this._onendpointchange = handler;
-
-    this._onendpointchange &&
-      this.addEventListener(Event.ON_ENDPOINT_CHANGE, this._onendpointchange);
-  }
-
-  /**
-   * Subscribes to the `onconnecting` event. Assigning replaces the previous
-   * handler; assigning `null` removes it.
-   * @category Event
-   */
-  public set onconnecting(handler: EventListener | null) {
-    this._onconnecting &&
-      this.removeEventListener(Event.ON_CONNECTING, this._onconnecting);
-
-    this._onconnecting = handler;
-
-    this._onconnecting &&
-      this.addEventListener(Event.ON_CONNECTING, this._onconnecting);
-  }
-
-  /**
-   * Subscribes to the `onconnected` event. Assigning replaces the previous
-   * handler; assigning `null` removes it.
-   * @category Event
-   */
-  public set onconnected(handler: EventListener | null) {
-    this._onconnected &&
-      this.removeEventListener(Event.ON_CONNECTED, this._onconnected);
-
-    this._onconnected = handler;
-
-    this._onconnected &&
-      this.addEventListener(Event.ON_CONNECTED, this._onconnected);
-  }
-
-  /**
-   * Subscribes to the `ondisconnected` event. Assigning replaces the previous
-   * handler; assigning `null` removes it.
-   * @category Event
-   */
-  public set ondisconnected(handler: EventListener | null) {
-    this._ondisconnected &&
-      this.removeEventListener(Event.ON_DISCONNECTED, this._ondisconnected);
-
-    this._ondisconnected = handler;
-
-    this._ondisconnected &&
-      this.addEventListener(Event.ON_DISCONNECTED, this._ondisconnected);
-  }
-
-  /**
-   * Subscribes to the `onmasterdatachange` event. Assigning replaces the
-   * previous handler; assigning `null` removes it.
-   * @category Event
-   */
-  public set onmasterdatachange(handler: EventListener | null) {
-    this._onmasterdatachange &&
-      this.removeEventListener(
-        Event.ON_MASTERDATACHANGE,
-        this._onmasterdatachange,
-      );
-
-    this._onmasterdatachange = handler;
-
-    this._onmasterdatachange &&
-      this.addEventListener(Event.ON_MASTERDATACHANGE, this._onmasterdatachange);
-  }
-
-  /**
-   * List operations to perform for selected attributes being observed in the DOM.
-   * @category Configuration
-   * @hidden
-   */
-  protected _attributeHandlers = {
-    [Attributes.CONNECTION]: (value: Connection) =>
-      value !== this._connection &&
-      this.setAttribute(Attributes.CONNECTION, this._connection),
-    [Attributes.ENDPOINT]: (value: Endpoint) => (this.endpoint = value),
-  };
-
-  /**
-   * Cache element references to improve performance
-   * @category Configuration
-   * @hidden
-   */
-  protected _cache = () => {};
-
-  /**
-   * Initialize component attributes with default values
-   * @category Configuration
-   * @hidden
-   */
-  protected _initialize = () => {
-    !this.hasAttribute(Attributes.CONNECTION) &&
-      this.setAttribute(Attributes.CONNECTION, this._connection);
-  };
-
-  /**
-   * Called by the connectedCallback prototypical method
-   * @category Configuration
-   * @hidden
-   */
-  protected _addEventListeners = () => {};
-
-  /**
-   * Called by the disconnectedCallback prototypical method
-   * @category Configuration
-   * @hidden
-   */
-  protected _removeEventListeners = () => {};
-
-  /**
-   * Negotiates a short-lived Web PubSub client access URL from the endpoint,
-   * authenticating the request with the session token.
-   * @category Operation
-   * @hidden
-   */
-  private _negotiate = async (token: string): Promise<string> => {
-    const response = await fetch(this.endpoint as string, {
-      headers: { Authorization: `Bearer ${token}` },
-    });
-    const { url } = await response.json();
-    return url;
-  };
-
-  /**
-   * Opens a Web PubSub WebSocket with the required subprotocol and wires the
-   * connection lifecycle handlers.
-   * @category Operation
-   * @hidden
-   */
-  private _open = (url: string): WebSocket => {
-    const socket = new WebSocket(url, Protocol);
-    socket.onopen = () => (this.connection = Connection.CONNECTED);
-    socket.onclose = () => (this.connection = Connection.DISCONNECTED);
-    socket.addEventListener(Gesture.MESSAGE, this._handleMessage);
-    return socket;
-  };
-
-  /**
-   * Handles an inbound Web PubSub message (the `message` gesture). Dispatches
-   * `onmasterdatachange` when the payload's `data.type` is `masterData.changed`.
-   * @category Gesture
-   * @hidden
-   */
-  private _handleMessage = (event: MessageEvent) => {
-    const message = JSON.parse(event.data);
-    message.data?.type === Message.MASTER_DATA_CHANGED &&
-      this._dispatchEvent(Event.ON_MASTERDATACHANGE, {
-        detail: { datetime: new Date().toISOString() },
-      });
-  };
-}
+/**
+ * @module Component
+ */
+
+// Base Component
+import { Component } from "@scalable.software/component";
+import { type Configuration } from "@scalable.software/component";
+
+// Component Metadata
+import {
+  Tag,
+  Attributes,
+  Connection,
+  Event,
+  Gesture,
+  Session,
+  Protocol,
+  Message,
+} from "./messenger.meta.js";
+
+import { type Endpoint } from "./messenger.meta.js";
+
+// Component Validation
+import { Validate } from "./messenger.validation.js";
+
+/**
+ * Configuration for the headless component — no template or stylesheet.
+ * @category Configuration
+ */
+export const configuration: Configuration = {
+  url: import.meta.url,
+} as const;
+
+/**
+ * @category Component
+ */
+export class Messenger extends Component {
+  /**
+   * The tag name of the component
+   * @category Configuration
+   */
+  public static get Tag() {
+    return Tag;
+  }
+
+  /**
+   * Only attributes defined the Attributes object will be observed in DOM
+   * @category State
+   */
+  public static get Attributes(): Attributes {
+    return Attributes;
+  }
+
+  /**
+   * The live connection status of the messenger. Internally owned.
+   * @category State
+   * @hidden
+   */
+  private _connection: Connection = Connection.DISCONNECTED;
+
+  /**
+   * The negotiate endpoint URL. When absent the messenger stays disconnected.
+   * @category State
+   * @hidden
+   */
+  private _endpoint: Endpoint | null = null;
+
+  /**
+   * The live Web PubSub socket. Held so it can be closed and replaced.
+   * @category State
+   * @hidden
+   */
+  private _socket: WebSocket | null = null;
+
+  /**
+   * Event subscription handler slots.
+   * @category Event
+   * @hidden
+   */
+  private _onendpointchange: EventListener | null = null;
+  private _onconnecting: EventListener | null = null;
+  private _onconnected: EventListener | null = null;
+  private _ondisconnected: EventListener | null = null;
+  private _onmasterdatachange: EventListener | null = null;
+
+  /**
+   * Cache element references to improve performance
+   * @category State
+   * @hidden
+   */
+  protected elements: {} = {};
+
+  /**
+   * @hidden
+   */
+  constructor() {
+    super(configuration);
+  }
+
+  /**
+   * The live connection status of the messenger. Internally owned — readable
+   * externally, but only mutable from within (protected setter).
+   * @category State
+   */
+  public get connection(): Connection {
+    return this._connection;
+  }
+
+  protected set connection(connection: Connection) {
+    // Guard
+    if (this._connection === connection) return;
+
+    // Mutate
+    this._connection = connection;
+    this.setAttribute(Attributes.CONNECTION, connection);
+
+    // Dispatch
+    const event = { detail: { connection } };
+    connection === Connection.CONNECTING &&
+      this._dispatchEvent(Event.ON_CONNECTING, event);
+    connection === Connection.CONNECTED &&
+      this._dispatchEvent(Event.ON_CONNECTED, event);
+    connection === Connection.DISCONNECTED &&
+      this._dispatchEvent(Event.ON_DISCONNECTED, event);
+  }
+
+  /**
+   * The negotiate endpoint URL. When absent the messenger stays disconnected.
+   * @category State
+   */
+  public get endpoint(): Endpoint | null {
+    return this._endpoint;
+  }
+
+  public set endpoint(endpoint: Endpoint | null) {
+    // Normalize
+    endpoint = endpoint ?? null;
+
+    // Validate
+    endpoint = endpoint ? Validate.endpoint(endpoint) : null;
+
+    // Guard
+    if (this._endpoint === endpoint) return;
+
+    // Mutate
+    this._endpoint = endpoint;
+    endpoint === null
+      ? this.removeAttribute(Attributes.ENDPOINT)
+      : this.setAttribute(Attributes.ENDPOINT, endpoint);
+
+    // Dispatch
+    this._dispatchEvent(Event.ON_ENDPOINT_CHANGE, { detail: { endpoint } });
+  }
+
+  /**
+   * The session token, read fresh from local storage on every access — never
+   * cached — because the License component renews and rewrites the key.
+   * @category State
+   * @hidden
+   */
+  private get _token(): string | null {
+    return localStorage.getItem(Session);
+  }
+
+  /**
+   * Negotiates a client access URL from the configured endpoint, authenticating
+   * with the session token, then opens the live connection. No-op when the
+   * endpoint or token is unavailable, or when already connecting or connected.
+   * @category Operation
+   */
+  public connect = async (): Promise<void> => {
+    const token = this._token;
+
+    // Gate + guard
+    if (!this.endpoint || !token) return;
+    if (this._connection !== Connection.DISCONNECTED) return;
+
+    // Establish
+    this.connection = Connection.CONNECTING;
+    const url = await this._negotiate(token);
+    this._socket = this._open(url);
+  };
+
+  /**
+   * Closes the live connection.
+   * @category Operation
+   */
+  public disconnect = (): void => {
+    this._socket?.close();
+    this._socket = null;
+    this.connection = Connection.DISCONNECTED;
+  };
+
+  /**
+   * Sends a JSON message to the server over the open Web PubSub connection by
+   * wrapping it in an `event` frame — the client-to-server mirror of the inbound
+   * `masterData.changed` notification. No-op returning `false` when there is no
+   * open connection; returns `true` when a frame is sent.
+   * @category Operation
+   */
+  public send = (message: object): boolean => {
+    // Gate
+    if (!this._socket || this._connection !== Connection.CONNECTED)
+      return false;
+
+    // Send — wrap in an Azure Web PubSub `event` frame, message rides as `data`
+    this._socket.send(
+      JSON.stringify({
+        type: "event",
+        event: "message",
+        dataType: "json",
+        data: message,
+      }),
+    );
+    return true;
+  };
+
+  /**
+   * Subscribes to the `onendpointchange` event. Assigning replaces the previous
+   * handler; assigning `null` removes it.
+   * @category Event
+   */
+  public set onendpointchange(handler: EventListener | null) {
+    this._onendpointchange &&
+      this.removeEventListener(
+        Event.ON_ENDPOINT_CHANGE,
+        this._onendpointchange,
+      );
+
+    this._onendpointchange = handler;
+
+    this._onendpointchange &&
+      this.addEventListener(Event.ON_ENDPOINT_CHANGE, this._onendpointchange);
+  }
+
+  /**
+   * Subscribes to the `onconnecting` event. Assigning replaces the previous
+   * handler; assigning `null` removes it.
+   * @category Event
+   */
+  public set onconnecting(handler: EventListener | null) {
+    this._onconnecting &&
+      this.removeEventListener(Event.ON_CONNECTING, this._onconnecting);
+
+    this._onconnecting = handler;
+
+    this._onconnecting &&
+      this.addEventListener(Event.ON_CONNECTING, this._onconnecting);
+  }
+
+  /**
+   * Subscribes to the `onconnected` event. Assigning replaces the previous
+   * handler; assigning `null` removes it.
+   * @category Event
+   */
+  public set onconnected(handler: EventListener | null) {
+    this._onconnected &&
+      this.removeEventListener(Event.ON_CONNECTED, this._onconnected);
+
+    this._onconnected = handler;
+
+    this._onconnected &&
+      this.addEventListener(Event.ON_CONNECTED, this._onconnected);
+  }
+
+  /**
+   * Subscribes to the `ondisconnected` event. Assigning replaces the previous
+   * handler; assigning `null` removes it.
+   * @category Event
+   */
+  public set ondisconnected(handler: EventListener | null) {
+    this._ondisconnected &&
+      this.removeEventListener(Event.ON_DISCONNECTED, this._ondisconnected);
+
+    this._ondisconnected = handler;
+
+    this._ondisconnected &&
+      this.addEventListener(Event.ON_DISCONNECTED, this._ondisconnected);
+  }
+
+  /**
+   * Subscribes to the `onmasterdatachange` event. Assigning replaces the
+   * previous handler; assigning `null` removes it.
+   * @category Event
+   */
+  public set onmasterdatachange(handler: EventListener | null) {
+    this._onmasterdatachange &&
+      this.removeEventListener(
+        Event.ON_MASTERDATACHANGE,
+        this._onmasterdatachange,
+      );
+
+    this._onmasterdatachange = handler;
+
+    this._onmasterdatachange &&
+      this.addEventListener(
+        Event.ON_MASTERDATACHANGE,
+        this._onmasterdatachange,
+      );
+  }
+
+  /**
+   * List operations to perform for selected attributes being observed in the DOM.
+   * @category Configuration
+   * @hidden
+   */
+  protected _attributeHandlers = {
+    [Attributes.CONNECTION]: (value: Connection) =>
+      value !== this._connection &&
+      this.setAttribute(Attributes.CONNECTION, this._connection),
+    [Attributes.ENDPOINT]: (value: Endpoint) => (this.endpoint = value),
+  };
+
+  /**
+   * Cache element references to improve performance
+   * @category Configuration
+   * @hidden
+   */
+  protected _cache = () => {};
+
+  /**
+   * Initialize component attributes with default values
+   * @category Configuration
+   * @hidden
+   */
+  protected _initialize = () => {
+    !this.hasAttribute(Attributes.CONNECTION) &&
+      this.setAttribute(Attributes.CONNECTION, this._connection);
+  };
+
+  /**
+   * Called by the connectedCallback prototypical method
+   * @category Configuration
+   * @hidden
+   */
+  protected _addEventListeners = () => {};
+
+  /**
+   * Called by the disconnectedCallback prototypical method
+   * @category Configuration
+   * @hidden
+   */
+  protected _removeEventListeners = () => {};
+
+  /**
+   * Negotiates a short-lived Web PubSub client access URL from the endpoint,
+   * authenticating the request with the session token.
+   * @category Operation
+   * @hidden
+   */
+  private _negotiate = async (token: string): Promise<string> => {
+    const response = await fetch(this.endpoint as string, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const { url } = await response.json();
+    return url;
+  };
+
+  /**
+   * Opens a Web PubSub WebSocket with the required subprotocol and wires the
+   * connection lifecycle handlers.
+   * @category Operation
+   * @hidden
+   */
+  private _open = (url: string): WebSocket => {
+    const socket = new WebSocket(url, Protocol);
+    socket.onopen = () => (this.connection = Connection.CONNECTED);
+    socket.onclose = () => (this.connection = Connection.DISCONNECTED);
+    socket.addEventListener(Gesture.MESSAGE, this._handleMessage);
+    return socket;
+  };
+
+  /**
+   * Handles an inbound Web PubSub message (the `message` gesture). Dispatches
+   * `onmasterdatachange` when the payload's `data.type` is `masterData.changed`.
+   * @category Gesture
+   * @hidden
+   */
+  private _handleMessage = (event: MessageEvent) => {
+    const message = JSON.parse(event.data);
+    message.data?.type === Message.MASTER_DATA_CHANGED &&
+      this._dispatchEvent(Event.ON_MASTERDATACHANGE, {
+        detail: { datetime: new Date().toISOString() },
+      });
+  };
+}