@xh/hoist 67.0.0-SNAPSHOT.1723673844830 → 67.0.0-SNAPSHOT.1723841759825

package/CHANGELOG.md

@@ -8,15 +8,15 @@
     * New `FetchService` members: `autoGenCorrelationIds`, `genCorrelationId` and
       `correlationIdHeaderKey` to support generation and inclusion of Correlation IDs on outbound
       request headers.
-    * Correlation ID assignment is available via:
+    * Correlation IDs are assigned via:
         * `FetchOptions.correlationId` - specify an ID to be used on a particular request or `true`
           to use a UUID generated by Hoist (see `FetchService.genCorrelationId()`).
-        * `TrackOptions.correlationId` - specify an ID for a tracked activity, if not already
-          relayed from a `FetchService` response.
-    * If set on a fetch request, Correlation IDs are passed through to downstream Hoist activity
-      tracking and error reporting and are available for review in the Admin Console.
-    * New `XH.genUUID()` method to generate UUIDs for use as Correlation IDs or elsewhere.
-* `GridModel.contextMenu` will now accept `false` as a value to omit context menus.
+        * `TrackOptions.correlationId` - specify an ID for a tracked activity, if not using the
+          new `FetchOptions.track` API (see below).
+    * If set on a fetch request, Correlation IDs are passed through to downstream error reporting
+      and are available for review in the Admin Console.
+* New `FetchOptions.track` - specify `TrackOptions` or message `string` to track a request via
+  Hoist activity tracking. The request's Correlation ID and LoadSpec will be included automatically.
 * New global interceptors on `FetchService`. See `FetchService.addInterceptor()`.
 * New property `FetchOptions.asJson` to instruct `FetchService` to decode an HTTP response as JSON.
   Note that `FetchService` methods suffixed with `Json` will set this property automatically.
@@ -37,7 +37,7 @@
 
 ### 📚 Libraries
 
-* uuid `added @ 10.0`
+* short-unique-id `added @ 5.2`
 
 ## 66.1.1 - 2024-08-01
 

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

@@ -9,7 +9,7 @@ import { AppContainerModel } from '../appcontainer/AppContainerModel';
 import { BannerModel } from '../appcontainer/BannerModel';
 import { ToastModel } from '../appcontainer/ToastModel';
 import '../styles/XH.scss';
-import { AppSpec, AppState, AppSuspendData, BannerSpec, ExceptionHandler, ExceptionHandlerOptions, FetchResponse, HoistAppModel, HoistException, HoistService, HoistServiceClass, HoistUser, MessageSpec, PageState, PlainObject, SizingMode, TaskObserver, Theme, ToastSpec, TrackOptions } from './';
+import { AppSpec, AppState, AppSuspendData, BannerSpec, ExceptionHandler, ExceptionHandlerOptions, HoistAppModel, HoistException, HoistService, HoistServiceClass, HoistUser, MessageSpec, PageState, PlainObject, SizingMode, TaskObserver, Theme, ToastSpec, TrackOptions } from './';
 import { HoistModel, ModelSelector, RefreshContextModel } from './model';
 export declare const MIN_HOIST_CORE_VERSION = "18.0";
 /**
@@ -117,7 +117,7 @@ export declare class XHApi {
      * Send a request via the underlying fetch API.
      * @see FetchService.fetch
      */
-    fetch(opts: FetchOptions): Promise<FetchResponse>;
+    fetch(opts: FetchOptions): Promise<any>;
     /**
      * Send an HTTP request and decode the response as JSON.
      * @see FetchService.fetchJson
@@ -398,10 +398,6 @@ export declare class XHApi {
      * Deliberately *not* intended to be globally unique, suitable for reuse, or to appear as such.
      */
     genId(): string;
-    /**
-     * Generate a universally unique identifier (UUID). Useful for generating Correlation IDs.
-     */
-    genUUID(): string;
     private get acm();
 }
 /** The app-wide singleton instance. */

package/build/types/core/exception/Exception.d.ts

@@ -1,5 +1,4 @@
 import { FetchOptions } from '@xh/hoist/svc';
-import { FetchResponse } from '../';
 import { FetchException, HoistException, TimeoutException, TimeoutExceptionConfig } from './Types';
 /**
  * Standardized Exception/Error objects.
@@ -26,9 +25,10 @@ export declare class Exception {
     /**
      * Create an Error to throw when a fetch call returns a !ok response.
      * @param fetchOptions - original options passed to FetchService.
-     * @param fetchResponse - return value of native fetch, as enhanced by FetchService.
+     * @param response - return value of native fetch.
+     * @param responseText - optional additional details from the server.
      */
-    static fetchError(fetchOptions: FetchOptions, fetchResponse: FetchResponse): FetchException;
+    static fetchError(fetchOptions: FetchOptions, response: Response, responseText?: string): FetchException;
     /**
      * Create an Error to throw when a fetchJson call encounters a SyntaxError.
      * @param fetchOptions - original options passed to FetchService.

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

@@ -19,15 +19,6 @@ export interface HoistUser {
     hasRole(s: string): boolean;
     hasGate(s: string): boolean;
 }
-/**
- * Enhanced Response returned by FetchService.
- */
-export interface FetchResponse extends Response {
-    /**
-     * Property containing the already-awaited output of `response.text()`.
-     */
-    responseText: string;
-}
 /**
  * Options for showing a "toast" notification that appears and then automatically dismisses.
  */
@@ -170,10 +161,7 @@ export interface TrackOptions {
     message: string;
     /** App-supplied category.*/
     category?: string;
-    /**
-     * Correlation ID to save along with track log. If not provided, will attempt to source from the
-     * underlying Fetch Request.
-     */
+    /** Correlation ID to save along with track log. */
     correlationId?: string;
     /** App-supplied data to save along with track log.*/
     data?: PlainObject | PlainObject[];

package/build/types/promise/Promise.d.ts

@@ -58,11 +58,6 @@ declare global {
          * @param options - TrackOptions, or simply a message string.
          */
         track(options: TrackOptions | string): Promise<T>;
-        /**
-         * Set by FetchService to relay correlation IDs to downstream error handling and tracking.
-         * @internal
-         */
-        correlationId?: string;
     }
 }
 /**

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

@@ -1,4 +1,4 @@
-import { Awaitable, HoistService, LoadSpec, PlainObject } from '@xh/hoist/core';
+import { Awaitable, HoistService, LoadSpec, PlainObject, TrackOptions } from '@xh/hoist/core';
 import { PromiseTimeoutSpec } from '@xh/hoist/promise';
 import { StatusCodes } from 'http-status-codes';
 import { IStringifyOptions } from 'qs';
@@ -24,14 +24,16 @@ import { IStringifyOptions } from 'qs';
 export declare class FetchService extends HoistService {
     static instance: FetchService;
     NO_JSON_RESPONSES: StatusCodes[];
+    private idGenerator;
     private autoAborters;
     private _defaultHeaders;
     private _interceptors;
     /** True to auto-generate a Correlation ID for each request unless otherwise specified. */
     autoGenCorrelationIds: boolean;
     /**
-     * Method for generating Correlation ID's. Defaults to `XH.genUUID()` but can be modified
-     * by applications looking to customize the format of their Correlation ID's.
+     * Method for generating Correlation ID's. Defaults to a 16 character random string with
+     * an extremely low probability of collisions.  Applications may customize
+     * to improve readability or provide a stronger uniqueness guarantee.
      */
     genCorrelationId: () => string;
     /** Request header name to be used for Correlation ID tracking. */
@@ -68,11 +70,11 @@ export declare class FetchService extends HoistService {
      * requests.  Other shortcut variants will delegate to this method, after setting
      * default options and pre-processing content.
      *
-     *  Set `asJson` to true return a parsed JSON result, rather than the raw FetchResponse.
+     *  Set `asJson` to true return a parsed JSON result, rather than the raw Response.
      *  Note that shortcut variant of this method (e.g. `fetchJson`, `postJson`) will set this
      *  flag for you.
      *
-     * @returns Promise which resolves to a FetchResponse or JSON.
+     * @returns Promise which resolves to a Response or JSON.
      */
     fetch(opts: FetchOptions): Promise<any>;
     /**
@@ -199,4 +201,9 @@ export interface FetchOptions {
      * True to decode the HTTP response as JSON. Default false.
      */
     asJson?: boolean;
+    /**
+     * If set, the request will be tracked via Hoist activity tracking. (Do not set `correlationId`
+     * here - use the top-level `correlationId` property instead.)
+     */
+    track?: string | TrackOptions;
 }

package/core/XH.ts

@@ -46,7 +46,6 @@ import {
     Exception,
     ExceptionHandler,
     ExceptionHandlerOptions,
-    FetchResponse,
     HoistAppModel,
     HoistException,
     HoistService,
@@ -64,7 +63,6 @@ import {
 import {installServicesAsync} from './impl/InstallServices';
 import {instanceManager} from './impl/InstanceManager';
 import {HoistModel, ModelSelector, RefreshContextModel} from './model';
-import {v4} from 'uuid';
 
 export const MIN_HOIST_CORE_VERSION = '18.0';
 
@@ -263,7 +261,7 @@ export class XHApi {
      * Send a request via the underlying fetch API.
      * @see FetchService.fetch
      */
-    fetch(opts: FetchOptions): Promise<FetchResponse> {
+    fetch(opts: FetchOptions): Promise<any> {
         return this.fetchService.fetch(opts);
     }
 
@@ -781,13 +779,6 @@ export class XHApi {
         return uniqueId('xh-id-');
     }
 
-    /**
-     * Generate a universally unique identifier (UUID). Useful for generating Correlation IDs.
-     */
-    genUUID(): string {
-        return v4();
-    }
-
     //----------------
     // Implementation
     //----------------

package/core/exception/Exception.ts

@@ -5,7 +5,7 @@
  * Copyright © 2024 Extremely Heavy Industries Inc.
  */
 import {FetchOptions} from '@xh/hoist/svc';
-import {FetchResponse, PlainObject, XH} from '../';
+import {PlainObject, XH} from '../';
 import {isPlainObject} from 'lodash';
 
 import {FetchException, HoistException, TimeoutException, TimeoutExceptionConfig} from './Types';
@@ -58,10 +58,15 @@ export class Exception {
     /**
      * Create an Error to throw when a fetch call returns a !ok response.
      * @param fetchOptions - original options passed to FetchService.
-     * @param fetchResponse - return value of native fetch, as enhanced by FetchService.
+     * @param response - return value of native fetch.
+     * @param responseText - optional additional details from the server.
      */
-    static fetchError(fetchOptions: FetchOptions, fetchResponse: FetchResponse): FetchException {
-        const {headers, status, statusText, responseText} = fetchResponse,
+    static fetchError(
+        fetchOptions: FetchOptions,
+        response: Response,
+        responseText: string = null
+    ): FetchException {
+        const {headers, status, statusText} = response,
             defaults = {
                 name: 'HTTP Error ' + (status || ''),
                 message: statusText,

package/core/types/Interfaces.ts

@@ -28,16 +28,6 @@ export interface HoistUser {
     hasGate(s: string): boolean;
 }
 
-/**
- * Enhanced Response returned by FetchService.
- */
-export interface FetchResponse extends Response {
-    /**
-     * Property containing the already-awaited output of `response.text()`.
-     */
-    responseText: string;
-}
-
 /**
  * Options for showing a "toast" notification that appears and then automatically dismisses.
  */
@@ -213,10 +203,7 @@ export interface TrackOptions {
     /** App-supplied category.*/
     category?: string;
 
-    /**
-     * Correlation ID to save along with track log. If not provided, will attempt to source from the
-     * underlying Fetch Request.
-     */
+    /** Correlation ID to save along with track log. */
     correlationId?: string;
 
     /** App-supplied data to save along with track log.*/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "67.0.0-SNAPSHOT.1723673844830",
+  "version": "67.0.0-SNAPSHOT.1723841759825",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",
@@ -83,9 +83,9 @@
     "router5": "~7.0.2",
     "router5-plugin-browser": "~7.0.2",
     "semver": "~7.6.0",
+    "short-unique-id": "~5.2.0",
     "store2": "~2.13.1",
-    "ua-parser-js": "~1.0.2",
-    "uuid": "~10.0.0"
+    "ua-parser-js": "~1.0.2"
   },
   "peerDependencies": {
     "react": "~18.2.0",

package/promise/Promise.ts

@@ -92,12 +92,6 @@ declare global {
          * @param options - TrackOptions, or simply a message string.
          */
         track(options: TrackOptions | string): Promise<T>;
-
-        /**
-         * Set by FetchService to relay correlation IDs to downstream error handling and tracking.
-         * @internal
-         */
-        correlationId?: string;
     }
 }
 
@@ -206,7 +200,7 @@ const enhancePromise = promisePrototype => {
             const startTime = Date.now();
             return this.finally(() => {
                 options.elapsed = Date.now() - startTime;
-                XH.track({correlationId: this.correlationId, ...options});
+                XH.track(options);
             });
         },
 

package/security/BaseOAuthClient.ts

@@ -11,7 +11,7 @@ import {Timer} from '@xh/hoist/utils/async';
 import {MINUTES, olderThan, ONE_MINUTE, SECONDS} from '@xh/hoist/utils/datetime';
 import {isJSON, throwIf} from '@xh/hoist/utils/js';
 import {find, forEach, isEmpty, isObject, keys, pickBy, union} from 'lodash';
-import {v4 as uuid} from 'uuid';
+import ShortUniqueId from 'short-unique-id';
 
 export type LoginMethod = 'REDIRECT' | 'POPUP';
 
@@ -254,11 +254,12 @@ export abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>, S> ext
      */
     protected captureRedirectState(): string {
         const {pathname, search} = window.location,
+            key = new ShortUniqueId({length: 8}).rnd(),
             state = {
-                key: uuid(),
-                timestamp: Date.now(),
+                key,
                 pathname,
-                search
+                search,
+                timestamp: Date.now()
             };
 
         const recs = this.getLocalStorage('xhOAuthState', []).filter(

package/svc/FetchService.ts

@@ -7,18 +7,19 @@
 import {
     Awaitable,
     Exception,
-    FetchResponse,
     HoistService,
     LoadSpec,
     PlainObject,
+    TrackOptions,
     XH
 } from '@xh/hoist/core';
 import {PromiseTimeoutSpec} from '@xh/hoist/promise';
 import {isLocalDate, SECONDS} from '@xh/hoist/utils/datetime';
-import {apiDeprecated} from '@xh/hoist/utils/js';
+import {apiDeprecated, warnIf} from '@xh/hoist/utils/js';
 import {StatusCodes} from 'http-status-codes';
 import {isDate, isFunction, isNil, isObject, isString, omit, omitBy} from 'lodash';
 import {IStringifyOptions, stringify} from 'qs';
+import ShortUniqueId from 'short-unique-id';
 
 /**
  * Service for making managed HTTP requests, both to the app's own Hoist server and to remote APIs.
@@ -44,6 +45,7 @@ export class FetchService extends HoistService {
 
     NO_JSON_RESPONSES = [StatusCodes.NO_CONTENT, StatusCodes.RESET_CONTENT];
 
+    private idGenerator = new ShortUniqueId({length: 16});
     private autoAborters = {};
     private _defaultHeaders: DefaultHeaders[] = [];
     private _interceptors: FetchInterceptor[] = [];
@@ -54,10 +56,11 @@ export class FetchService extends HoistService {
     autoGenCorrelationIds = false;
 
     /**
-     * Method for generating Correlation ID's. Defaults to `XH.genUUID()` but can be modified
-     * by applications looking to customize the format of their Correlation ID's.
+     * Method for generating Correlation ID's. Defaults to a 16 character random string with
+     * an extremely low probability of collisions.  Applications may customize
+     * to improve readability or provide a stronger uniqueness guarantee.
      */
-    genCorrelationId: () => string = () => XH.genUUID();
+    genCorrelationId: () => string = () => this.idGenerator.rnd();
 
     /** Request header name to be used for Correlation ID tracking. */
     correlationIdHeaderKey: string = 'X-Correlation-ID';
@@ -107,13 +110,13 @@ export class FetchService extends HoistService {
      * requests.  Other shortcut variants will delegate to this method, after setting
      * default options and pre-processing content.
      *
-     *  Set `asJson` to true return a parsed JSON result, rather than the raw FetchResponse.
+     *  Set `asJson` to true return a parsed JSON result, rather than the raw Response.
      *  Note that shortcut variant of this method (e.g. `fetchJson`, `postJson`) will set this
      *  flag for you.
      *
-     * @returns Promise which resolves to a FetchResponse or JSON.
+     * @returns Promise which resolves to a Response or JSON.
      */
-    fetch(opts: FetchOptions): Promise<any> {
+    async fetch(opts: FetchOptions): Promise<any> {
         return this.fetchInternalAsync(opts);
     }
 
@@ -121,7 +124,7 @@ export class FetchService extends HoistService {
      * Send an HTTP request and decode the response as JSON.
      * @returns the decoded JSON object, or null if the response has status in {@link NO_JSON_RESPONSES}.
      */
-    fetchJson(opts: FetchOptions): Promise<any> {
+    async fetchJson(opts: FetchOptions): Promise<any> {
         return this.fetchInternalAsync({asJson: true, ...opts});
     }
 
@@ -129,7 +132,7 @@ export class FetchService extends HoistService {
      * Send a GET request and decode the response as JSON.
      * @returns the decoded JSON object, or null if the response status is in {@link NO_JSON_RESPONSES}.
      */
-    getJson(opts: FetchOptions): Promise<any> {
+    async getJson(opts: FetchOptions): Promise<any> {
         return this.fetchInternalAsync({asJson: true, method: 'GET', ...opts});
     }
 
@@ -137,7 +140,7 @@ export class FetchService extends HoistService {
      * Send a POST request with a JSON body and decode the response as JSON.
      * @returns the decoded JSON object, or null if the response status is in {@link NO_JSON_RESPONSES}.
      */
-    postJson(opts: FetchOptions): Promise<any> {
+    async postJson(opts: FetchOptions): Promise<any> {
         return this.sendJsonInternalAsync({method: 'POST', ...opts});
     }
 
@@ -145,7 +148,7 @@ export class FetchService extends HoistService {
      * Send a PUT request with a JSON body and decode the response as JSON.
      * @returns the decoded JSON object, or null if the response status is in {@link NO_JSON_RESPONSES}.
      */
-    putJson(opts: FetchOptions): Promise<any> {
+    async putJson(opts: FetchOptions): Promise<any> {
         return this.sendJsonInternalAsync({method: 'PUT', ...opts});
     }
 
@@ -153,7 +156,7 @@ export class FetchService extends HoistService {
      * Send a PATCH request with a JSON body and decode the response as JSON.
      * @returns the decoded JSON object, or null if the response status is in {@link NO_JSON_RESPONSES}.
      */
-    patchJson(opts: FetchOptions): Promise<any> {
+    async patchJson(opts: FetchOptions): Promise<any> {
         return this.sendJsonInternalAsync({method: 'PATCH', ...opts});
     }
 
@@ -161,7 +164,7 @@ export class FetchService extends HoistService {
      * Send a DELETE request with optional JSON body and decode the optional response as JSON.
      * @returns the decoded JSON object, or null if the response status is in {@link NO_JSON_RESPONSES}.
      */
-    deleteJson(opts: FetchOptions): Promise<any> {
+    async deleteJson(opts: FetchOptions): Promise<any> {
         return this.sendJsonInternalAsync({method: 'DELETE', ...opts});
     }
 
@@ -209,20 +212,30 @@ export class FetchService extends HoistService {
     //-----------------------
     // Implementation
     //-----------------------
-    private fetchInternalAsync(opts: FetchOptions): Promise<any> {
+    private async fetchInternalAsync(opts: FetchOptions): Promise<any> {
         opts = this.withCorrelationId(opts);
-        const ret = this.withDefaultHeadersAsync(opts).then(opts => {
-            let fetchPromise = this.managedFetchAsync(opts);
-            for (const interceptor of this._interceptors) {
-                fetchPromise = fetchPromise.then(
-                    value => interceptor.onFulfilled(opts, value),
-                    cause => interceptor.onRejected(opts, cause)
-                );
-            }
-            return fetchPromise;
-        });
+        opts = await this.withDefaultHeadersAsync(opts);
+        let ret = this.managedFetchAsync(opts);
+
+        // Apply tracking
+        const {correlationId, loadSpec, track} = opts;
+        if (track) {
+            const trackOptions = isString(track) ? {message: track} : track;
+            warnIf(
+                trackOptions.correlationId || trackOptions.loadSpec,
+                'Neither Correlation ID nor LoadSpec should be set in `FetchOptions.track`. Use `FetchOptions` top-level properties instead.'
+            );
+            ret = ret.track({...trackOptions, correlationId: correlationId as string, loadSpec});
+        }
+
+        // Apply interceptors
+        for (const interceptor of this._interceptors) {
+            ret = ret.then(
+                value => interceptor.onFulfilled(opts, value),
+                cause => interceptor.onRejected(opts, cause)
+            );
+        }
 
-        ret.correlationId = opts.correlationId as string;
         return ret;
     }
 
@@ -322,7 +335,7 @@ export class FetchService extends HoistService {
     private async abortableFetchAsync(
         opts: FetchOptions,
         aborter: AbortController
-    ): Promise<FetchResponse> {
+    ): Promise<Response> {
         // 1) Prepare URL
         let {url, method, headers, body, params} = opts,
             isRelativeUrl = !url.startsWith('/') && !url.includes('//');
@@ -363,12 +376,9 @@ export class FetchService extends HoistService {
         }
 
         // 4) Await underlying fetch and post-process response.
-        const ret = (await fetch(url, fetchOpts)) as FetchResponse;
+        const ret = await fetch(url, fetchOpts);
 
-        if (!ret.ok) {
-            ret.responseText = await this.safeResponseTextAsync(ret);
-            throw Exception.fetchError(opts, ret);
-        }
+        if (!ret.ok) throw Exception.fetchError(opts, ret, await this.safeResponseTextAsync(ret));
 
         return ret;
     }
@@ -475,4 +485,10 @@ export interface FetchOptions {
      * True to decode the HTTP response as JSON. Default false.
      */
     asJson?: boolean;
+
+    /**
+     * If set, the request will be tracked via Hoist activity tracking. (Do not set `correlationId`
+     * here - use the top-level `correlationId` property instead.)
+     */
+    track?: string | TrackOptions;
 }

package/svc/TrackService.ts

@@ -7,7 +7,7 @@
 import {HoistService, TrackOptions, XH} from '@xh/hoist/core';
 import {isOmitted} from '@xh/hoist/utils/impl';
 import {stripTags, withDefault} from '@xh/hoist/utils/js';
-import {isString} from 'lodash';
+import {isNil, isString} from 'lodash';
 
 /**
  * Primary service for tracking any activity that an application's admins want to track.
@@ -104,7 +104,9 @@ export class TrackService extends HoistService {
             }
 
             const elapsedStr = query.elapsed != null ? `${query.elapsed}ms` : null,
-                consoleMsgs = [query.category, query.msg, elapsedStr].filter(it => it != null);
+                consoleMsgs = [query.category, query.msg, query.correlationId, elapsedStr].filter(
+                    it => !isNil(it)
+                );
 
             this.logInfo(...consoleMsgs);