@xh/hoist 76.0.0-SNAPSHOT.1758217044052 → 76.0.0-SNAPSHOT.1758310971360

package/utils/async/Timer.ts

@@ -7,8 +7,7 @@
 import {XH} from '@xh/hoist/core';
 import {wait} from '@xh/hoist/promise';
 import {MILLISECONDS, MINUTES, olderThan} from '@xh/hoist/utils/datetime';
-import {throwIf} from '@xh/hoist/utils/js';
-import {logError, logWarn} from '@xh/hoist/utils/log';
+import {logError, logWarn, throwIf} from '@xh/hoist/utils/js';
 import {isBoolean, isFinite, isFunction, isNil, isString, pull} from 'lodash';
 
 /**

package/utils/js/Decorators.ts

@@ -4,10 +4,10 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {XH} from '@xh/hoist/core';
+import {Exception} from '@xh/hoist/exception';
 import {debounce, isFunction} from 'lodash';
-import {getOrCreate, throwIf, warnIf} from './LangUtils';
-import {withDebug, withInfo} from '../log';
+import {getOrCreate, throwIf} from './LangUtils';
+import {withDebug, warnIf, withInfo} from './LogUtils';
 
 /**
  * Decorates a class method so that it is debounced by the specified duration.
@@ -106,7 +106,7 @@ export function abstract(target, key, descriptor) {
     return {
         ...descriptor,
         [baseFnName]: function () {
-            throw XH.exception(`${key} must be implemented by ${this.constructor.name}`);
+            throw Exception.create(`${key} must be implemented by ${this.constructor.name}`);
         }
     };
 }

package/utils/js/LangUtils.ts

@@ -4,8 +4,8 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import type {PlainObject, Thunkable, LogSource} from '@xh/hoist/core';
-import {Exception} from '@xh/hoist/core/exception/Exception';
+import type {PlainObject, Thunkable} from '@xh/hoist/core';
+import {Exception} from '@xh/hoist/exception';
 import {
     flatMap,
     forOwn,
@@ -121,25 +121,7 @@ export function isJSON(obj: any): boolean {
  */
 export function throwIf(condition: any, message: unknown) {
     if (condition) {
-        throw Exception.create(message);
-    }
-}
-
-/**
- * Log a warning to the console if a condition evaluates as truthy.
- */
-export function warnIf(condition: any, message: any) {
-    if (condition) {
-        console.warn(message);
-    }
-}
-
-/**
- * Log an error to the console if a condition evaluates as truthy.
- */
-export function errorIf(condition: any, message: any) {
-    if (condition) {
-        console.error(message);
+        throw Exception.create(message); // low-level exception api for low-level package
     }
 }
 
@@ -156,52 +138,6 @@ export function createSingleton<T>(clazz: new () => T): T {
     return (clazz['instance'] = new clazz());
 }
 
-export interface APIWarnOptions {
-    /**
-     * If provided and undefined, this method will be a no-op.
-     * Useful for testing if a parameter has been provided in caller.
-     */
-    test?: any;
-
-    /** Version when this API will no longer be supported or this warning should be removed. */
-    v?: string;
-
-    /** An additional message. Can contain suggestions for alternatives. */
-    msg?: string;
-
-    /** Source of message for labeling log message.  */
-    source?: LogSource;
-}
-
-/**
- * Document and prevent usage of a removed parameter.
- */
-export function apiRemoved(name: string, opts: APIWarnOptions = {}) {
-    if ('test' in opts && isUndefined(opts.test)) return;
-
-    const src = opts.source ? `[${opts.source}] ` : '',
-        msg = opts.msg ? ` ${opts.msg}.` : '';
-    throw Exception.create(`${src}The use of '${name}' is no longer supported.${msg}`);
-}
-
-/**
- * Document and warn on usage of a deprecated API
- *
- * @param name - the name of the deprecated parameter
- */
-const _seenWarnings = {};
-export function apiDeprecated(name: string, opts: APIWarnOptions = {}) {
-    if ('test' in opts && isUndefined(opts.test)) return;
-
-    const v = opts.v ?? 'a future release',
-        msg = opts.msg ?? '',
-        warn = `The use of '${name}' has been deprecated and will be removed in ${v}. ${msg}`;
-    if (!_seenWarnings[warn]) {
-        console.warn(warn, opts.source);
-        _seenWarnings[warn] = true;
-    }
-}
-
 /**
  * Throw an exception if the provided object or collection is empty, as per lodash isEmpty().
  *

package/utils/{log → js}/LogUtils.ts

@@ -4,9 +4,11 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import type {Some, LogLevel, LogSource} from '@xh/hoist/core';
-import {castArray, flatMap, isString} from 'lodash';
+import type {Some} from '@xh/hoist/core';
+import {Exception} from '@xh/hoist/exception';
+import {castArray, isString, isUndefined} from 'lodash';
 import store from 'store2';
+import {intersperse} from './LangUtils';
 
 /**
  * Utility functions providing managed, structured logging to Hoist apps.
@@ -22,6 +24,29 @@ import store from 'store2';
  * XH.logLevel from the console.
  */
 
+/** Severity Level for log statement */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+
+/** Object identifying the source of log statement.  Typically, a javascript class */
+export type LogSource = string | {displayName: string} | {constructor: {name: string}};
+
+export interface APIWarnOptions {
+    /**
+     * If provided and undefined, this method will be a no-op.
+     * Useful for testing if a parameter has been provided in caller.
+     */
+    test?: any;
+
+    /** Version when this API will no longer be supported or this warning should be removed. */
+    v?: string;
+
+    /** An additional message. Can contain suggestions for alternatives. */
+    msg?: string;
+
+    /** Source of message for labelling log message.  */
+    source?: LogSource;
+}
+
 /**
  * Current minimum severity for Hoist log utils (default 'info').
  * Messages logged via managed Hoist log utils with lower severity will be ignored.
@@ -29,11 +54,7 @@ import store from 'store2';
  * @internal - use public `XH.logLevel`.
  */
 export function getLogLevel() {
-    try {
-        return _logLevel;
-    } catch (e) {
-        return 'info';
-    }
+    return _logLevel;
 }
 
 /**
@@ -121,13 +142,59 @@ export function logWarn(msgs: Some<unknown>, source?: LogSource) {
     return loggedDo(msgs, null, source, 'warn');
 }
 
+/**
+ * Log a warning to the console if a condition evaluates as truthy.
+ */
+export function warnIf(condition: any, message: any) {
+    if (condition) {
+        logWarn(message);
+    }
+}
+
+/**
+ * Log an error to the console if a condition evaluates as truthy.
+ */
+export function errorIf(condition: any, message: any) {
+    if (condition) {
+        logError(message);
+    }
+}
+
+/**
+ * Document and prevent usage of a removed parameter.
+ */
+export function apiRemoved(name: string, opts: APIWarnOptions = {}) {
+    if ('test' in opts && isUndefined(opts.test)) return;
+
+    const src = opts.source ? `[${opts.source}] ` : '',
+        msg = opts.msg ? ` ${opts.msg}.` : '';
+    // low-level exception api for low-level package
+    throw Exception.create(`${src}The use of '${name}' is no longer supported.${msg}`);
+}
+
+/**
+ * Document and warn on usage of a deprecated API
+ *
+ * @param name - the name of the deprecated parameter
+ */
+const _seenWarnings = {};
+export function apiDeprecated(name: string, opts: APIWarnOptions = {}) {
+    if ('test' in opts && isUndefined(opts.test)) return;
+
+    const v = opts.v ?? 'a future release',
+        msg = opts.msg ?? '',
+        warn = `The use of '${name}' has been deprecated and will be removed in ${v}. ${msg}`;
+    if (!_seenWarnings[warn]) {
+        logWarn(warn, opts.source);
+        _seenWarnings[warn] = true;
+    }
+}
+
 //----------------------------------
 // Implementation
 //----------------------------------
 function loggedDo<T>(messages: Some<unknown>, fn: () => T, source: LogSource, level: LogLevel): T {
-    const _severity: Record<LogLevel, number> = {error: 3, warn: 2, info: 1, debug: 0};
-
-    if (_severity[level] < _severity[getLogLevel()]) {
+    if (_severity[level] < _severity[_logLevel]) {
         return fn?.();
     }
 
@@ -202,19 +269,11 @@ function parseSource(source: LogSource): string {
     return null;
 }
 
-/**
- * Intersperse a separator between each item in an array.
- * Same method as in LangUtils, but duplicated here to avoid circular dependency.
- */
-function intersperse<T>(arr: T[], separator: T): T[] {
-    return flatMap(arr, (it, idx) => {
-        return idx > 0 ? [separator, it] : [it];
-    });
-}
 //----------------------------------------------------------------
 // Initialization + Level/Severity support.
 // Initialize during parsing to make available immediately.
 //----------------------------------------------------------------
 let _logLevel: LogLevel = 'info';
+const _severity: Record<LogLevel, number> = {error: 3, warn: 2, info: 1, debug: 0};
 
 setLogLevel(store.session.get('xhLogLevel', 'info'));

package/utils/js/index.ts

@@ -7,5 +7,7 @@
 export * from './HtmlUtils';
 export * from './LangUtils';
 export * from './Decorators';
+export * from './LogUtils';
 export * from './DomUtils';
 export * from './TestUtils';
+export * from './VersionUtils';

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

@@ -1,61 +0,0 @@
-import { FetchOptions } from '@xh/hoist/svc';
-import { FetchException, HoistException, TimeoutException, TimeoutExceptionConfig } from './Types';
-/**
- * Standardized Exception/Error objects.
- *
- * The main entry point for this class is the create() method.
- * Applications can use this method to create various generic runtime exceptions.
- * @see ExceptionHandler.handleException
- */
-export declare class Exception {
-    /**
-     * Create and return a HoistException
-     *
-     * See {@link XH.exception} - an alias for this factory off of `XH`.
-     *
-     * @param src - If a native JS Error, it will be enhanced into a HoistException and returned.
-     *      If a plain object, all properties will be set on a new HoistException.
-     *      Other inputs will be treated as the `message` of a new HoistException.
-     */
-    static create(src: unknown): HoistException;
-    /** Create an Error for when an operation (e.g. a Promise) times out. */
-    static timeout(config: TimeoutExceptionConfig): TimeoutException;
-    /**
-     * Create an Error to throw when a fetch call returns a !ok response.
-     * @param fetchOptions - original options passed to FetchService.
-     * @param response - return value of native fetch.
-     * @param responseText - optional additional details from the server.
-     */
-    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.
-     * @param cause - object thrown by native {@link response.json}.
-     */
-    static fetchJsonParseError(fetchOptions: FetchOptions, cause: any): FetchException;
-    /**
-     * Create an Error to throw when a fetch call is aborted.
-     * @param fetchOptions - original options passed to FetchService.
-     * @param cause - object thrown by native fetch
-     */
-    static fetchAborted(fetchOptions: FetchOptions, cause: any): FetchException;
-    /**
-     * Create an Error to throw when a fetch call times out.
-     * @param fetchOptions - original options the app passed when calling FetchService.
-     * @param cause - underlying timeout exception
-     * @param message - optional custom message
-     *
-     * @returns an exception that is both a TimeoutException, and a FetchException, with the
-     *      underlying TimeoutException as its cause.
-     */
-    static fetchTimeout(fetchOptions: FetchOptions, cause: TimeoutException, message: string): FetchException & TimeoutException;
-    /**
-     * Create an Error for when the server called by fetch does not respond
-     * @param fetchOptions - original options the app passed to FetchService.fetch
-     * @param cause - object thrown by native fetch
-     */
-    static serverUnavailable(fetchOptions: FetchOptions, cause: any): FetchException;
-    private static createFetchException;
-    private static createInternal;
-}
-export declare function isHoistException(src: unknown): src is HoistException;

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

@@ -1 +0,0 @@
-export * from './LogUtils';

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

@@ -1 +0,0 @@
-export * from './VersionUtils';

package/core/exception/Exception.ts

@@ -1,256 +0,0 @@
-/*
- * This file belongs to Hoist, an application development toolkit
- * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
- *
- * Copyright © 2025 Extremely Heavy Industries Inc.
- */
-import {PlainObject, XH} from '@xh/hoist/core';
-import {FetchOptions} from '@xh/hoist/svc';
-import {pluralize} from '@xh/hoist/utils/js';
-import {isPlainObject, isString, truncate} from 'lodash';
-import {FetchException, HoistException, TimeoutException, TimeoutExceptionConfig} from './Types';
-
-/**
- * Standardized Exception/Error objects.
- *
- * The main entry point for this class is the create() method.
- * Applications can use this method to create various generic runtime exceptions.
- * @see ExceptionHandler.handleException
- */
-export class Exception {
-    /**
-     * Create and return a HoistException
-     *
-     * See {@link XH.exception} - an alias for this factory off of `XH`.
-     *
-     * @param src - If a native JS Error, it will be enhanced into a HoistException and returned.
-     *      If a plain object, all properties will be set on a new HoistException.
-     *      Other inputs will be treated as the `message` of a new HoistException.
-     */
-    static create(src: unknown): HoistException {
-        if (isHoistException(src)) return src;
-        if (src instanceof Error) return this.createInternal({}, src);
-
-        const attributes: PlainObject = isPlainObject(src) ? src : {message: src?.toString()};
-        return this.createInternal({
-            name: 'Exception',
-            message: 'An unknown error occurred',
-            ...attributes
-        });
-    }
-
-    /** Create an Error for when an operation (e.g. a Promise) times out. */
-    static timeout(config: TimeoutExceptionConfig): TimeoutException {
-        const {interval, ...rest} = config,
-            // Display timeout in seconds if an even multiple (or very close to it).
-            displayInterval =
-                interval % 1000 < 5
-                    ? pluralize('second', Math.round(interval / 1000), true)
-                    : `${interval}ms`;
-
-        return this.createInternal({
-            name: 'Timeout Exception',
-            // Note FetchService.managedFetchAsync appends to this message - review if changing.
-            message: `Timed out after ${displayInterval}`,
-            isTimeout: true,
-            stack: null,
-            interval,
-            ...rest
-        }) as TimeoutException;
-    }
-
-    /**
-     * Create an Error to throw when a fetch call returns a !ok response.
-     * @param fetchOptions - original options passed to FetchService.
-     * @param response - return value of native fetch.
-     * @param responseText - optional additional details from the server.
-     */
-    static fetchError(
-        fetchOptions: FetchOptions,
-        response: Response,
-        responseText: string = null
-    ): FetchException {
-        const {headers, status, statusText} = response,
-            defaults = {
-                name: 'HTTP Error ' + (status || ''),
-                message: statusText,
-                httpStatus: status,
-                serverDetails: responseText,
-                fetchOptions
-            };
-
-        if (status === 401) {
-            return this.createFetchException({
-                ...defaults,
-                name: 'Unauthorized',
-                message: 'Your session may have timed out and you may need to log in again.'
-            });
-        }
-
-        // Try to "smart" decode as server provided JSON Exception (with a name)
-        try {
-            const cType = headers.get('Content-Type');
-            if (cType?.includes('application/json')) {
-                const parsedResp = safeParseJson(responseText);
-                return this.createFetchException({
-                    ...defaults,
-                    name: parsedResp?.name ?? defaults.name,
-                    message: extractMessage(parsedResp, responseText, statusText),
-                    isRoutine: parsedResp?.isRoutine ?? false,
-                    serverDetails: parsedResp ?? responseText
-                });
-            }
-        } catch (ignored) {}
-
-        // Fall back to raw defaults
-        return this.createFetchException(defaults);
-    }
-
-    /**
-     * Create an Error to throw when a fetchJson call encounters a SyntaxError.
-     * @param fetchOptions - original options passed to FetchService.
-     * @param cause - object thrown by native {@link response.json}.
-     */
-    static fetchJsonParseError(fetchOptions: FetchOptions, cause: any): FetchException {
-        return this.createFetchException({
-            name: 'JSON Parsing Error',
-            message:
-                'Error parsing the response body as JSON. The server may have returned an invalid ' +
-                'or empty response. Use "XH.fetch()" to process the response manually.',
-            fetchOptions,
-            cause
-        });
-    }
-
-    /**
-     * Create an Error to throw when a fetch call is aborted.
-     * @param fetchOptions - original options passed to FetchService.
-     * @param cause - object thrown by native fetch
-     */
-    static fetchAborted(fetchOptions: FetchOptions, cause: any): FetchException {
-        return this.createFetchException({
-            name: 'Fetch Aborted',
-            message: `Fetch request aborted, url: "${fetchOptions.url}"`,
-            isRoutine: true,
-            isFetchAborted: true,
-            fetchOptions,
-            cause
-        });
-    }
-
-    /**
-     * Create an Error to throw when a fetch call times out.
-     * @param fetchOptions - original options the app passed when calling FetchService.
-     * @param cause - underlying timeout exception
-     * @param message - optional custom message
-     *
-     * @returns an exception that is both a TimeoutException, and a FetchException, with the
-     *      underlying TimeoutException as its cause.
-     */
-    static fetchTimeout(
-        fetchOptions: FetchOptions,
-        cause: TimeoutException,
-        message: string
-    ): FetchException & TimeoutException {
-        return this.createFetchException({
-            name: 'Fetch Timeout',
-            message,
-            isFetchTimeout: true,
-            isTimeout: true,
-            interval: cause.interval,
-            fetchOptions,
-            cause
-        }) as FetchException & TimeoutException;
-    }
-
-    /**
-     * Create an Error for when the server called by fetch does not respond
-     * @param fetchOptions - original options the app passed to FetchService.fetch
-     * @param cause - object thrown by native fetch
-     */
-    static serverUnavailable(fetchOptions: FetchOptions, cause: any): FetchException {
-        const protocolPattern = /^[a-z]+:\/\//i,
-            originPattern = /^[a-z]+:\/\/[^/]+/i,
-            match = fetchOptions.url.match(originPattern),
-            origin = match
-                ? match[0]
-                : protocolPattern.test(XH.baseUrl)
-                  ? XH.baseUrl
-                  : window.location.origin;
-
-        return this.createFetchException({
-            name: 'Server Unavailable',
-            message: `Unable to contact the server at ${origin}`,
-            isServerUnavailable: true,
-            fetchOptions,
-            cause
-        });
-    }
-
-    //-----------------------
-    // Implementation
-    //-----------------------
-    private static createFetchException(attributes: PlainObject) {
-        let correlationId: string = null;
-        const correlationIdHeaderKey = XH?.fetchService?.correlationIdHeaderKey;
-        if (correlationIdHeaderKey) {
-            correlationId = attributes.fetchOptions?.headers?.[correlationIdHeaderKey];
-        }
-
-        return this.createInternal({
-            isFetchAborted: false,
-            httpStatus: 0, // native fetch doesn't put status on its Error
-            serverDetails: null,
-            stack: null, // server-sourced exceptions do not include, neither should client, not relevant
-            correlationId,
-            ...attributes
-        }) as FetchException;
-    }
-
-    private static createInternal(attributes: PlainObject, baseError?: Error) {
-        const {message, ...rest} = attributes;
-        const ret = Object.assign(
-            baseError ?? new Error(message),
-            {
-                isRoutine: false,
-                isHoistException: true
-            },
-            rest
-        ) as HoistException;
-
-        // statuses of 0, 4XX, 5XX are server errors, so stack irrelevant and potentially misleading
-        if (ret.stack == null || /^[045]/.test(ret.httpStatus)) delete ret.stack;
-
-        return ret;
-    }
-}
-
-function safeParseJson(txt: string): PlainObject {
-    try {
-        return JSON.parse(txt);
-    } catch (ignored) {
-        return null;
-    }
-}
-
-function extractMessage(parsedResp: PlainObject, responseText: string, statusText: string): string {
-    let ret: string;
-    if (parsedResp) {
-        // From parsed response, including cause if provided (e.g. ExternalHttpException)
-        ret = parsedResp.message;
-        if (isString(parsedResp.cause)) {
-            const cause = truncate(parsedResp.cause, {length: 255});
-            ret = ret ? `${ret} (Caused by: ${cause})` : cause;
-        }
-    } else {
-        // Use raw text if not JSON parseable
-        ret = truncate(responseText?.trim(), {length: 255});
-    }
-
-    // Fallback to statusText if we have nothing else.
-    return ret || statusText;
-}
-
-export function isHoistException(src: unknown): src is HoistException {
-    return src?.['isHoistException'];
-}

package/utils/version/index.ts

@@ -1,8 +0,0 @@
-/*
- * This file belongs to Hoist, an application development toolkit
- * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
- *
- * Copyright © 2025 Extremely Heavy Industries Inc.
- */
-
-export * from './VersionUtils';