@xh/hoist 73.0.0-SNAPSHOT.1744145928224 → 73.0.0-SNAPSHOT.1744147015222

package/CHANGELOG.md

@@ -2,13 +2,16 @@
 
 ## v73.0.0-SNAPSHOT - unreleased
 
+### ⚙️ Technical
+* Added enhanced `ClientHealthService` for managing client health report.
+
 ## v72.3.0 - 2025-04-08
 
 ### 🎁 New Features
 
 * Added support for posting a "Client Health Report" track message on a configurable interval. This
   message will include basic client information, and can be extended to include any other desired
-  data via `XH.trackService.addClientHealthReportSource()`. Enable by updating your app's
+  data via `XH.clientHealthService.addSource()`. Enable by updating your app's
   `xhActivityTrackingConfig` to include `clientHealthReport: {intervalMins: XXXX}`.
 * Enabled opt-in support for telemetry in `MsalClient`, leveraging hooks built-in to MSAL to collect
   timing and success/failure count for all events emitted by the library.

package/admin/AdminUtils.ts

@@ -5,7 +5,9 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {XH} from '@xh/hoist/core';
-import {LocalDate} from '@xh/hoist/utils/datetime';
+import {DAYS, LocalDate} from '@xh/hoist/utils/datetime';
+import {isNumber} from 'lodash';
+import {fmtDateTimeSec} from '@xh/hoist/format';
 
 /**
  * Generate a standardized filename for an Admin module grid export, without datestamp.
@@ -21,3 +23,18 @@ export function exportFilename(moduleName: string): string {
 export function exportFilenameWithDate(moduleName: string): () => string {
     return () => `${XH.appCode}-${moduleName}-${LocalDate.today()}`;
 }
+
+/**
+ * Replacer for JSON.stringify to replace timestamp properties with formatted strings.
+ */
+export function timestampReplacer(k: string, v: any) {
+    if (
+        (k.endsWith('Time') || k.endsWith('Date') || k.endsWith('Timestamp') || k == 'timestamp') &&
+        isNumber(v) &&
+        v > Date.now() - 25 * 365 * DAYS // heuristic to avoid catching smaller ms ranges
+    ) {
+        return fmtDateTimeSec(v, {fmt: 'MMM DD HH:mm:ss.SSS'});
+    }
+
+    return v;
+}

package/admin/tabs/activity/tracking/detail/ActivityDetailModel.ts

@@ -4,14 +4,14 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {exportFilename} from '@xh/hoist/admin/AdminUtils';
+import {exportFilename, timestampReplacer} from '@xh/hoist/admin/AdminUtils';
 import * as Col from '@xh/hoist/admin/columns';
 import {FormModel} from '@xh/hoist/cmp/form';
 import {GridModel} from '@xh/hoist/cmp/grid';
 import {HoistModel, lookup, managed} from '@xh/hoist/core';
-import {fmtJson} from '@xh/hoist/format';
 import {action, computed, makeObservable, observable} from '@xh/hoist/mobx';
 import {ActivityTrackingModel} from '../ActivityTrackingModel';
+import {fmtJson} from '@xh/hoist/format';
 
 export class ActivityDetailModel extends HoistModel {
     @lookup(ActivityTrackingModel) activityTrackingModel: ActivityTrackingModel;
@@ -118,7 +118,7 @@ export class ActivityDetailModel extends HoistModel {
         let formattedTrackData = trackData;
         if (formattedTrackData) {
             try {
-                formattedTrackData = fmtJson(trackData);
+                formattedTrackData = fmtJson(trackData, {replacer: timestampReplacer});
             } catch (ignored) {}
         }
 

package/admin/tabs/cluster/instances/BaseInstanceModel.ts

@@ -5,10 +5,7 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {InstancesTabModel} from '@xh/hoist/admin/tabs/cluster/instances/InstancesTabModel';
-import {HoistModel, LoadSpec, lookup, PlainObject, XH} from '@xh/hoist/core';
-import {fmtDateTimeSec, fmtJson} from '@xh/hoist/format';
-import {DAYS} from '@xh/hoist/utils/datetime';
-import {cloneDeep, forOwn, isArray, isNumber, isPlainObject} from 'lodash';
+import {HoistModel, LoadSpec, lookup, XH} from '@xh/hoist/core';
 import {createRef} from 'react';
 import {isDisplayed} from '@xh/hoist/utils/js';
 
@@ -21,12 +18,6 @@ export class BaseInstanceModel extends HoistModel {
         return this.parent.instanceName;
     }
 
-    fmtStats(stats: PlainObject): string {
-        stats = cloneDeep(stats);
-        this.processTimestamps(stats);
-        return fmtJson(JSON.stringify(stats));
-    }
-
     handleLoadException(e: unknown, loadSpec: LoadSpec) {
         const instanceNotFound = this.isInstanceNotFound(e),
             connDown = this.parent.lastLoadException,
@@ -49,23 +40,4 @@ export class BaseInstanceModel extends HoistModel {
     private isInstanceNotFound(e: unknown): boolean {
         return e['name'] == 'InstanceNotFoundException';
     }
-
-    private processTimestamps(stats: PlainObject) {
-        forOwn(stats, (v, k) => {
-            // Convert numbers that look like recent timestamps to date values.
-            if (
-                (k.endsWith('Time') ||
-                    k.endsWith('Date') ||
-                    k.endsWith('Timestamp') ||
-                    k == 'timestamp') &&
-                isNumber(v) &&
-                v > Date.now() - 365 * DAYS
-            ) {
-                stats[k] = v ? fmtDateTimeSec(v, {fmt: 'MMM DD HH:mm:ss.SSS'}) : null;
-            }
-            if (isPlainObject(v) || isArray(v)) {
-                this.processTimestamps(v);
-            }
-        });
-    }
 }

package/admin/tabs/cluster/instances/services/DetailsPanel.ts

@@ -12,6 +12,8 @@ import {panel} from '@xh/hoist/desktop/cmp/panel';
 import {jsonInput} from '@xh/hoist/desktop/cmp/input';
 import {Icon} from '@xh/hoist/icon';
 import {isEmpty} from 'lodash';
+import {fmtJson} from '@xh/hoist/format';
+import {timestampReplacer} from '@xh/hoist/admin/AdminUtils';
 
 export const detailsPanel = hoistCmp.factory({
     model: creates(DetailsModel),
@@ -57,7 +59,7 @@ const stats = hoistCmp.factory<DetailsModel>({
                       enableSearch: true,
                       showFullscreenButton: false,
                       editorProps: {lineNumbers: false},
-                      value: model.parent.fmtStats(stats)
+                      value: fmtJson(stats, {replacer: timestampReplacer})
                   })
               );
     }

package/admin/tabs/cluster/objects/DetailModel.ts

@@ -6,21 +6,11 @@
  */
 import {ClusterObjectsModel} from '@xh/hoist/admin/tabs/cluster/objects/ClusterObjectsModel';
 import {ColumnSpec, GridModel} from '@xh/hoist/cmp/grid';
-import {HoistModel, lookup, managed, PlainObject, XH} from '@xh/hoist/core';
+import {HoistModel, lookup, managed, XH} from '@xh/hoist/core';
 import {StoreRecord} from '@xh/hoist/data';
-import {fmtDateTimeSec, fmtJson} from '@xh/hoist/format';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
-import {DAYS} from '@xh/hoist/utils/datetime';
-import {
-    cloneDeep,
-    forOwn,
-    isArray,
-    isEmpty,
-    isEqual,
-    isNumber,
-    isPlainObject,
-    without
-} from 'lodash';
+import {isEmpty, isEqual, without} from 'lodash';
+import {timestampReplacer} from '@xh/hoist/admin/AdminUtils';
 
 export class DetailModel extends HoistModel {
     @lookup(ClusterObjectsModel)
@@ -66,12 +56,6 @@ export class DetailModel extends HoistModel {
         });
     }
 
-    fmtStats(stats: PlainObject): string {
-        stats = cloneDeep(stats);
-        this.processTimestamps(stats);
-        return fmtJson(JSON.stringify(stats));
-    }
-
     //----------------------
     // Implementation
     //----------------------
@@ -95,8 +79,8 @@ export class DetailModel extends HoistModel {
         const gridModel = this.createGridModel(diffFields, otherFields);
         gridModel.loadData(
             instanceNames.map(instanceName => {
-                const data = cloneDeep(adminStatsByInstance[instanceName] ?? {});
-                this.processTimestamps(data);
+                let data = adminStatsByInstance[instanceName] ?? {};
+                data = JSON.parse(JSON.stringify(data, timestampReplacer));
                 return {instanceName, ...data};
             })
         );
@@ -136,23 +120,4 @@ export class DetailModel extends HoistModel {
         }
         return ret;
     }
-
-    private processTimestamps(stats: PlainObject) {
-        forOwn(stats, (v, k) => {
-            // Convert numbers that look like recent timestamps to date values.
-            if (
-                (k.endsWith('Time') ||
-                    k.endsWith('Date') ||
-                    k.endsWith('Timestamp') ||
-                    k == 'timestamp') &&
-                isNumber(v) &&
-                v > Date.now() - 365 * DAYS
-            ) {
-                stats[k] = v ? fmtDateTimeSec(v, {fmt: 'MMM DD HH:mm:ss.SSS'}) : null;
-            }
-            if (isPlainObject(v) || isArray(v)) {
-                this.processTimestamps(v);
-            }
-        });
-    }
 }

package/admin/tabs/cluster/objects/DetailPanel.ts

@@ -12,6 +12,8 @@ import {panel} from '@xh/hoist/desktop/cmp/panel';
 import {Icon} from '@xh/hoist/icon';
 import {DetailModel} from './DetailModel';
 import './ClusterObjects.scss';
+import {timestampReplacer} from '@xh/hoist/admin/AdminUtils';
+import {fmtJson} from '@xh/hoist/format';
 
 export const detailPanel = hoistCmp.factory({
     model: creates(DetailModel),
@@ -42,7 +44,7 @@ export const detailPanel = hoistCmp.factory({
                         height: '100%',
                         showFullscreenButton: false,
                         editorProps: {lineNumbers: false},
-                        value: model.fmtStats(selectedAdminStats)
+                        value: fmtJson(selectedAdminStats, {replacer: timestampReplacer})
                     })
                 })
             ]

package/appcontainer/AppContainerModel.ts

@@ -25,6 +25,7 @@ import {
     AlertBannerService,
     AutoRefreshService,
     ChangelogService,
+    ClientHealthService,
     ConfigService,
     EnvironmentService,
     FetchService,
@@ -237,6 +238,7 @@ export class AppContainerModel extends HoistModel {
                 AlertBannerService,
                 AutoRefreshService,
                 ChangelogService,
+                ClientHealthService,
                 IdleService,
                 InspectorService,
                 GridAutosizeService,

package/appcontainer/AppStateModel.ts

@@ -7,7 +7,6 @@
 import {AppState, AppSuspendData, HoistModel, XH} from '@xh/hoist/core';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {Timer} from '@xh/hoist/utils/async';
-import {getClientDeviceInfo} from '@xh/hoist/utils/js';
 import {camelCase, isBoolean, isString, mapKeys} from 'lodash';
 
 /**
@@ -97,7 +96,7 @@ export class AppStateModel extends HoistModel {
                         appBuild: XH.appBuild,
                         locationHref: window.location.href,
                         timings: mapKeys(timings, (v, k) => camelCase(k)),
-                        ...getClientDeviceInfo()
+                        clientHealth: XH.clientHealthService.getReport()
                     },
                     logData: ['appVersion', 'appBuild'],
                     omit: !XH.appSpec.trackAppLoad

package/build/types/admin/AdminUtils.d.ts

@@ -7,3 +7,7 @@ export declare function exportFilename(moduleName: string): string;
  * Returned as a closure to ensure current date is evaluated at export time.
  */
 export declare function exportFilenameWithDate(moduleName: string): () => string;
+/**
+ * Replacer for JSON.stringify to replace timestamp properties with formatted strings.
+ */
+export declare function timestampReplacer(k: string, v: any): any;

package/build/types/admin/tabs/cluster/instances/BaseInstanceModel.d.ts

@@ -1,13 +1,11 @@
 /// <reference types="react" />
 import { InstancesTabModel } from '@xh/hoist/admin/tabs/cluster/instances/InstancesTabModel';
-import { HoistModel, LoadSpec, PlainObject } from '@xh/hoist/core';
+import { HoistModel, LoadSpec } from '@xh/hoist/core';
 export declare class BaseInstanceModel extends HoistModel {
     viewRef: import("react").RefObject<HTMLElement>;
     parent: InstancesTabModel;
     get instanceName(): string;
-    fmtStats(stats: PlainObject): string;
     handleLoadException(e: unknown, loadSpec: LoadSpec): void;
     get isVisible(): boolean;
     private isInstanceNotFound;
-    private processTimestamps;
 }

package/build/types/admin/tabs/cluster/objects/DetailModel.d.ts

@@ -1,6 +1,6 @@
 import { ClusterObjectsModel } from '@xh/hoist/admin/tabs/cluster/objects/ClusterObjectsModel';
 import { GridModel } from '@xh/hoist/cmp/grid';
-import { HoistModel, PlainObject } from '@xh/hoist/core';
+import { HoistModel } from '@xh/hoist/core';
 import { StoreRecord } from '@xh/hoist/data';
 export declare class DetailModel extends HoistModel {
     parent: ClusterObjectsModel;
@@ -11,9 +11,7 @@ export declare class DetailModel extends HoistModel {
     get instanceName(): string;
     get selectedAdminStats(): any;
     constructor();
-    fmtStats(stats: PlainObject): string;
     private updateGridModel;
     private createGridModel;
     private createColSpec;
-    private processTimestamps;
 }

package/build/types/core/XH.d.ts

@@ -1,7 +1,7 @@
 import { RouterModel } from '@xh/hoist/appcontainer/RouterModel';
 import { HoistAuthModel } from '@xh/hoist/core/HoistAuthModel';
 import { Store } from '@xh/hoist/data';
-import { AlertBannerService, AutoRefreshService, ChangelogService, ConfigService, EnvironmentService, FetchOptions, FetchService, GridAutosizeService, GridExportService, IdentityService, IdleService, InspectorService, JsonBlobService, LocalStorageService, PrefService, SessionStorageService, TrackService, WebSocketService } from '@xh/hoist/svc';
+import { AlertBannerService, AutoRefreshService, ChangelogService, ConfigService, EnvironmentService, FetchOptions, FetchService, GridAutosizeService, GridExportService, IdentityService, IdleService, InspectorService, JsonBlobService, LocalStorageService, PrefService, SessionStorageService, TrackService, WebSocketService, ClientHealthService } from '@xh/hoist/svc';
 import { Router, State } from 'router5';
 import { CancelFn } from 'router5/types/types/base';
 import { SetOptional } from 'type-fest';
@@ -47,6 +47,7 @@ export declare class XHApi {
     alertBannerService: AlertBannerService;
     autoRefreshService: AutoRefreshService;
     changelogService: ChangelogService;
+    clientHealthService: ClientHealthService;
     configService: ConfigService;
     environmentService: EnvironmentService;
     fetchService: FetchService;

package/build/types/format/FormatMisc.d.ts

@@ -1,4 +1,5 @@
 import { CSSProperties, ReactNode } from 'react';
+import { PlainObject } from '@xh/hoist/core';
 export interface FormatOptions<T = any> {
     /** Display value for null values. */
     nullDisplay?: ReactNode;
@@ -32,9 +33,9 @@ export interface JSONFormatOptions {
     space?: number | string;
 }
 /**
- * Pretty-print a JSON string, adding line breaks and indentation.
+ * Pretty-print a JSON string or (JSON Object), adding line breaks and indentation.
  */
-export declare function fmtJson(str: string, opts?: JSONFormatOptions): string;
+export declare function fmtJson(v: string | PlainObject, opts?: JSONFormatOptions): string;
 /**
  * Basic util for splitting a string (via ' ') and capitalizing each word - e.g. for names.
  * Not intended to handle more advanced usages such as HTML or other word boundary characters.

package/build/types/svc/ClientHealthService.d.ts

@@ -0,0 +1,80 @@
+import { HoistService, PlainObject } from '@xh/hoist/core';
+/**
+ * Service for gathering data about client health.
+ *
+ * Hoist sends this data once on application load, and can be configured to send
+ * it at regularly scheduled intervals.  Configure via soft-config property
+ * 'xhActivityTracking.clientHealthReport'.
+ */
+export declare class ClientHealthService extends HoistService {
+    static instance: ClientHealthService;
+    private sources;
+    initAsync(): Promise<void>;
+    /**
+     * Main Entry report.  Return a default report of client health.
+     */
+    getReport(): ClientHealthReport;
+    /**
+     * Register a new source for client health report data. No-op if background health report is
+     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
+     *
+     * @param key - key under which to report the data - can be used to remove this source later.
+     * @param callback - function returning serializable to include with each report.
+     */
+    addSource(key: string, callback: () => any): void;
+    /** Unregister a previously-enabled source for client health report data. */
+    removeSource(key: string): void;
+    getSession(): SessionData;
+    getConnection(): ConnectionData;
+    getMemory(): MemoryData;
+    getScreen(): ScreenData;
+    getWindow(): WindowData;
+    getCustom(): PlainObject;
+    private sendReport;
+}
+export interface SessionData {
+    startTime: number;
+    durationMins: number;
+}
+export interface ConnectionData {
+    downlink: number;
+    effectiveType: string;
+    rtt: number;
+}
+export interface MemoryData {
+    modelCount: number;
+    usedPctLimit?: number;
+    jsHeapSizeLimit?: number;
+    totalJSHeapSize?: number;
+    usedJSHeapSize?: number;
+}
+export interface WindowData {
+    devicePixelRatio: number;
+    screenX: number;
+    screenY: number;
+    innerWidth: number;
+    innerHeight: number;
+    outerWidth: number;
+    outerHeight: number;
+}
+export interface ScreenData {
+    availWidth: number;
+    availHeight: number;
+    width: number;
+    height: number;
+    colorDepth: number;
+    pixelDepth: number;
+    availLeft: number;
+    availTop: number;
+    orientation?: {
+        angle: number;
+        type: string;
+    };
+}
+export interface ClientHealthReport {
+    session: SessionData;
+    connection: ConnectionData;
+    memory: MemoryData;
+    window: WindowData;
+    screen: ScreenData;
+}

package/build/types/svc/TrackService.d.ts

@@ -6,7 +6,6 @@ import { HoistService, TrackOptions } from '@xh/hoist/core';
  */
 export declare class TrackService extends HoistService {
     static instance: TrackService;
-    private clientHealthReportSources;
     private oncePerSessionSent;
     private pending;
     initAsync(): Promise<void>;
@@ -14,21 +13,10 @@ export declare class TrackService extends HoistService {
     get enabled(): boolean;
     /** Track User Activity. */
     track(options: TrackOptions | string): void;
-    /**
-     * Register a new source for client health report data. No-op if background health report is
-     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
-     *
-     * @param key - key under which to report the data - can be used to remove this source later.
-     * @param callback - function returning serializable to include with each report.
-     */
-    addClientHealthReportSource(key: string, callback: () => any): void;
-    /** Unregister a previously-enabled source for client health report data. */
-    removeClientHealthReportSource(key: string): void;
     private pushPendingAsync;
     private pushPendingBuffered;
     private toServerJson;
     private logMessage;
-    private sendClientHealthReport;
 }
 interface ActivityTrackingConfig {
     clientHealthReport?: Partial<TrackOptions> & {

package/build/types/svc/index.d.ts

@@ -13,5 +13,6 @@ export * from './JsonBlobService';
 export * from './PrefService';
 export * from './TrackService';
 export * from './WebSocketService';
+export * from './ClientHealthService';
 export * from './storage/LocalStorageService';
 export * from './storage/SessionStorageService';

package/build/types/utils/js/index.d.ts

@@ -3,6 +3,5 @@ export * from './LangUtils';
 export * from './Decorators';
 export * from './LogUtils';
 export * from './DomUtils';
-export * from './BrowserUtils';
 export * from './TestUtils';
 export * from './VersionUtils';

package/core/XH.ts

@@ -28,7 +28,8 @@ import {
     PrefService,
     SessionStorageService,
     TrackService,
-    WebSocketService
+    WebSocketService,
+    ClientHealthService
 } from '@xh/hoist/svc';
 import {camelCase, flatten, isString, uniqueId} from 'lodash';
 import {Router, State} from 'router5';
@@ -131,6 +132,7 @@ export class XHApi {
     alertBannerService: AlertBannerService;
     autoRefreshService: AutoRefreshService;
     changelogService: ChangelogService;
+    clientHealthService: ClientHealthService;
     configService: ConfigService;
     environmentService: EnvironmentService;
     fetchService: FetchService;

package/format/FormatMisc.ts

@@ -5,8 +5,9 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {span} from '@xh/hoist/cmp/layout';
-import {capitalize, isNil, kebabCase, map} from 'lodash';
+import {capitalize, isNil, isString, kebabCase, map} from 'lodash';
 import {CSSProperties, ReactNode} from 'react';
+import {PlainObject} from '@xh/hoist/core';
 
 export interface FormatOptions<T = any> {
     /** Display value for null values. */
@@ -63,11 +64,12 @@ export interface JSONFormatOptions {
 }
 
 /**
- * Pretty-print a JSON string, adding line breaks and indentation.
+ * Pretty-print a JSON string or (JSON Object), adding line breaks and indentation.
  */
-export function fmtJson(str: string, opts?: JSONFormatOptions): string {
+export function fmtJson(v: string | PlainObject, opts?: JSONFormatOptions): string {
     const {replacer = undefined, space = 2} = opts ?? {};
-    return isNil(str) ? '' : JSON.stringify(JSON.parse(str), replacer, space);
+    if (isString(v)) v = JSON.parse(v);
+    return isNil(v) ? '' : JSON.stringify(v, replacer, space);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "73.0.0-SNAPSHOT.1744145928224",
+  "version": "73.0.0-SNAPSHOT.1744147015222",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",

package/security/msal/MsalClient.ts

@@ -320,11 +320,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
         // Handle TrackService not yet initialized (common, this client likely initialized before.)
         this.addReaction({
             when: () => XH.appIsRunning,
-            run: () =>
-                XH.trackService.addClientHealthReportSource(
-                    'msalClient',
-                    () => this.telemetryResults
-                )
+            run: () => XH.clientHealthService.addSource('msalClient', () => this.telemetryResults)
         });
 
         this.logInfo('Telemetry enabled');
@@ -339,7 +335,7 @@ export class MsalClient extends BaseOAuthClient<MsalClientConfig, MsalTokenSpec>
         this.client.removePerformanceCallback(this._telemetryCbHandle);
         this._telemetryCbHandle = null;
 
-        XH.trackService.removeClientHealthReportSource('msalClient');
+        XH.clientHealthService.removeSource('msalClient');
         this.logInfo('Telemetry disabled', this.telemetryResults);
     }