@xh/hoist 67.0.0-SNAPSHOT.1723668375053 → 67.0.0-SNAPSHOT.1723839594443

package/CHANGELOG.md

@@ -8,14 +8,19 @@
     * 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.
+        * `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 `XH.genUUID()` method to generate UUIDs for use as Correlation IDs or elsewhere.
+* 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.
 * `GridModel` will now accept `contextMenu: false` to omit context menus.
 
 ### 🐞 Bug Fixes
@@ -33,7 +38,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
@@ -403,6 +403,7 @@ export declare class XHApi {
      */
     genUUID(): string;
     private get acm();
+    private shortUniqueId;
 }
 /** The app-wide singleton instance. */
 export declare const XH: XHApi;

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, FetchResponse, 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';
@@ -25,6 +25,8 @@ export declare class FetchService extends HoistService {
     static instance: FetchService;
     NO_JSON_RESPONSES: StatusCodes[];
     private autoAborters;
+    private _defaultHeaders;
+    private _interceptors;
     /** True to auto-generate a Correlation ID for each request unless otherwise specified. */
     autoGenCorrelationIds: boolean;
     /**
@@ -34,35 +36,45 @@ export declare class FetchService extends HoistService {
     genCorrelationId: () => string;
     /** Request header name to be used for Correlation ID tracking. */
     correlationIdHeaderKey: string;
-    /**
-     * Timeout to be used for all requests made via this service that do not themselves spec a
-     * custom timeout.
-     */
+    /** Default timeout to be used for all requests made via this service */
     defaultTimeout: PromiseTimeoutSpec;
-    private _defaultHeaders;
-    get defaultHeaders(): Array<PlainObject | ((arg: FetchOptions) => Awaitable<PlainObject>)>;
-    /**
-     * Set default headers to be sent with all subsequent requests.
-     * @param headers - to be sent with all fetch requests, or a function to generate.
-     * @deprecated use addDefaultHeaders instead.
-     */
-    setDefaultHeaders(headers: PlainObject | ((arg: FetchOptions) => Awaitable<PlainObject>)): void;
+    /** Default headers to be sent with all subsequent requests. */
+    get defaultHeaders(): DefaultHeaders[];
+    /**
+     * Promise handlers to be executed before fufilling or rejecting returned Promise.
+     *
+     * Use the `onRejected` handler for apps requiring common handling for particular exceptions.
+     * Useful for recognizing 401s (i.e. session end), or wrapping, logging, or enhancing exceptions.
+     * The simplest onRejected handler will simply rethrow the passed exception, or a wrapped version of it.
+     * Such handlers may also return `never()` to prevent further processing of the request -- this
+     * is useful, i.e. if the handler is going to redirect the entire app, or otherwise end normal
+     * app processing.  Rejected handlers may also be able to retry and return valid results via
+     * another call to fetch.
+     *
+     * Use the `onFulfilled` hander for enhancing, tracking, or even rejecting "successful" returns.
+     * For example, a handler of this form could be used to transform a 200 response returned by
+     * an API with an "error" flag into a proper client-side exception.
+     */
+    addInterceptor(handler: FetchInterceptor): void;
     /**
      * Add default headers to be sent with all subsequent requests.
      * @param headers - to be sent with all fetch requests, or a function to generate.
      */
-    addDefaultHeaders(headers: PlainObject | ((arg: FetchOptions) => Awaitable<PlainObject>)): void;
-    /**
-     * Set the timeout (default 30 seconds) to be used for all requests made via this service that
-     * do not themselves spec a custom timeout.
-     * @deprecated modify `defaultTimeout` directly instead.
-     */
-    setDefaultTimeout(timeout: PromiseTimeoutSpec): void;
+    addDefaultHeaders(headers: DefaultHeaders): void;
     /**
      * Send a request via the underlying fetch API.
-     * @returns Promise which resolves to a Fetch Response.
-     */
-    fetch(opts: FetchOptions): Promise<FetchResponse>;
+     *
+     * This is the main entry point for this API, and can be used to satisfy all
+     * 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 Response.
+     *  Note that shortcut variant of this method (e.g. `fetchJson`, `postJson`) will set this
+     *  flag for you.
+     *
+     * @returns Promise which resolves to a Response or JSON.
+     */
+    fetch(opts: FetchOptions): Promise<any>;
     /**
      * 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}.
@@ -98,15 +110,35 @@ export declare class FetchService extends HoistService {
      * @returns false if no request pending for the given key.
      */
     abort(autoAbortKey: string): boolean;
-    /** Resolve convenience options for Correlation ID to server-ready string */
+    /**
+     * Set the timeout (default 30 seconds) to be used for all requests made via this service that
+     * do not themselves spec a custom timeout.
+     * @deprecated modify `defaultTimeout` directly instead.
+     */
+    setDefaultTimeout(timeout: PromiseTimeoutSpec): void;
+    /**
+     * Set default headers to be sent with all subsequent requests.
+     * @param headers - to be sent with all fetch requests, or a function to generate.
+     * @deprecated use addDefaultHeaders instead.
+     */
+    setDefaultHeaders(headers: DefaultHeaders): void;
+    private fetchInternalAsync;
+    private sendJsonInternalAsync;
     private withCorrelationId;
     private withDefaultHeadersAsync;
     private managedFetchAsync;
-    private fetchInternalAsync;
-    private sendJsonInternalAsync;
+    private abortableFetchAsync;
+    private parseJsonAsync;
     private safeResponseTextAsync;
     private qsFilterFn;
 }
+/** Headers to be applied to all requests.  Specified as object, or dynamic function to create. */
+export type DefaultHeaders = PlainObject | ((opts: FetchOptions) => Awaitable<PlainObject>);
+/** Handlers to be executed before fufilling or rejecting any exception to caller. */
+export interface FetchInterceptor {
+    onFulfilled: (opts: FetchOptions, value: any) => Promise<any>;
+    onRejected: (opts: FetchOptions, cause: unknown) => Promise<any>;
+}
 /**
  * Standard options to pass through to fetch, with some additions.
  * See MDN for available options - {@link https://developer.mozilla.org/en-US/docs/Web/API/Request}.
@@ -163,4 +195,13 @@ export interface FetchOptions {
      * aborted in favor of the new request.
      */
     autoAbortKey?: string;
+    /**
+     * 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,7 @@ import {
 import {installServicesAsync} from './impl/InstallServices';
 import {instanceManager} from './impl/InstanceManager';
 import {HoistModel, ModelSelector, RefreshContextModel} from './model';
-import {v4} from 'uuid';
+import ShortUniqueId from 'short-unique-id';
 
 export const MIN_HOIST_CORE_VERSION = '18.0';
 
@@ -263,7 +262,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);
     }
 
@@ -785,7 +784,7 @@ export class XHApi {
      * Generate a universally unique identifier (UUID). Useful for generating Correlation IDs.
      */
     genUUID(): string {
-        return v4();
+        return this.shortUniqueId.rnd();
     }
 
     //----------------
@@ -794,6 +793,8 @@ export class XHApi {
     private get acm(): AppContainerModel {
         return this.appContainerModel;
     }
+
+    private shortUniqueId = new ShortUniqueId({length: 16});
 }
 
 /** The app-wide singleton instance. */

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.1723668375053",
+  "version": "67.0.0-SNAPSHOT.1723839594443",
   "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,6 @@ 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';
 
 export type LoginMethod = 'REDIRECT' | 'POPUP';
 
@@ -255,7 +254,7 @@ export abstract class BaseOAuthClient<C extends BaseOAuthClientConfig<S>, S> ext
     protected captureRedirectState(): string {
         const {pathname, search} = window.location,
             state = {
-                key: uuid(),
+                key: XH.genUUID(),
                 timestamp: Date.now(),
                 pathname,
                 search