@xh/hoist 57.0.0 → 57.0.1

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

@@ -0,0 +1,36 @@
+import { HoistService } from '@xh/hoist/core';
+/**
+ * Service to read soft-configuration values.
+ *
+ * Server-side configuration support is provided by hoist-core. AppConfigs must be predefined on the
+ * server (they can be managed by the Admin console) and are referenced by their string key. These
+ * entries can then be changed on the fly or given per-environment values that allow the app to
+ * adjust without requiring a code change or redeployment.
+ *
+ * Note that for a config to be available here on the client, it must have its `clientVisible` flag
+ * set to true. This is to provide support for configurations that should *not* be sent down for
+ * possible inspection by end users.
+ *
+ * Note that this service does *not* currently attempt to reload or update configs once the client
+ * application has loaded. A refresh of the application is required to load new entries.
+ */
+export declare class ConfigService extends HoistService {
+    static instance: ConfigService;
+    private _data;
+    initAsync(): Promise<void>;
+    /**
+     * Get the list of available keys.
+     */
+    get list(): string[];
+    /**
+     * Get the configured value for a given key. Typically accessed via `XH.getConf()` alias.
+     *
+     * @param key - identifier of the config to return.
+     * @param defaultValue - value to return if the configuration key is not found - i.e. the
+     *      config has not been created on the server - instead of throwing. Use sparingly! In
+     *      general, it's better to not provide defaults here, but instead keep entries up-to-date
+     *      via the Admin client and have it be obvious when one is missing.
+     * @returns the soft-configured value.
+     */
+    get(key: string, defaultValue?: any): any;
+}

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

@@ -0,0 +1,24 @@
+import { HoistService } from '@xh/hoist/core';
+export declare class EnvironmentService extends HoistService {
+    static instance: EnvironmentService;
+    /**
+     * Version of this application currently running on the Hoist UI server.
+     * Unlike all other EnvironmentService state, this is refreshed by default on a configured
+     * interval and is observable to allow apps to take actions (e.g. reload immediately) when
+     * they detect an update on the server.
+     */
+    serverVersion: string;
+    /** Build of this application currently running on the Hoist UI server. */
+    serverBuild: string;
+    private _data;
+    initAsync(): Promise<void>;
+    get(key: string): any;
+    isProduction(): boolean;
+    isTest(): boolean;
+    isMinHoistCoreVersion(version: string): boolean;
+    isMaxHoistCoreVersion(version: string): boolean;
+    constructor();
+    private startVersionChecking;
+    private checkServerVersionAsync;
+    private setServerVersion;
+}

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

@@ -0,0 +1,139 @@
+import { HoistService, PlainObject, Thunkable, FetchResponse } from '@xh/hoist/core';
+import { StatusCodes } from 'http-status-codes';
+import { IStringifyOptions } from 'qs';
+import { PromiseTimeoutSpec } from '@xh/hoist/promise';
+/**
+ * Service for making managed HTTP requests, both to the app's own Hoist server and to remote APIs.
+ *
+ * Wrapper around the standard Fetch API with some enhancements to streamline the process for
+ * the most common use-cases. The Fetch API will be called with CORS enabled, credentials
+ * included, and redirects followed.
+ *
+ * Custom headers can be provided to fetch as a plain object. App-wide default headers can be set
+ * using `setDefaultHeaders()`.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API|Fetch API Docs}
+ *
+ * Note that the convenience methods `fetchJson`, `postJson`, `putJson` all accept the same options
+ * as the main entry point `fetch`, as they delegate to fetch after setting additional defaults.
+ *
+ * Note: For non-SSO apps, FetchService will automatically trigger a reload of the app if a
+ * 401 is encountered from a local (relative) request.  This default behavior is designed to allow
+ * more seamless re-establishment of timed out authentication sessions, but can be turned off
+ * via config if needed.
+ */
+export declare class FetchService extends HoistService {
+    static instance: FetchService;
+    NO_JSON_RESPONSES: StatusCodes[];
+    private autoAborters;
+    defaultHeaders: {};
+    defaultTimeout: any;
+    /**
+     * Set default headers to be sent with all subsequent requests.
+     * @param headers - to be sent with all fetch requests, or a function to generate.
+     */
+    setDefaultHeaders(headers: Thunkable<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.
+     */
+    setDefaultTimeout(timeout: PromiseTimeoutSpec): void;
+    /**
+     * Send a request via the underlying fetch API.
+     * @returns Promise which resolves to a Fetch Response.
+     */
+    fetch(opts: FetchOptions): Promise<FetchResponse>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Manually abort any pending request for a given autoAbortKey.
+     * @returns false if no request pending for the given key.
+     */
+    abort(autoAbortKey: string): boolean;
+    private managedFetchAsync;
+    private fetchInternalAsync;
+    private maybeReloadForAuthAsync;
+    private sendJsonInternalAsync;
+    private safeResponseTextAsync;
+    private qsFilterFn;
+}
+/**
+ * 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}.
+ */
+export interface FetchOptions {
+    /** URL for the request. Relative urls will be appended to XH.baseUrl. */
+    url: string;
+    /**
+     * Data to send in the request body (for POSTs/PUTs of JSON).
+     * When using `fetch`, provide a string. Otherwise, provide a PlainObject.
+     */
+    body?: PlainObject | string;
+    /**
+     * Parameters to encode and append as a query string, or send with the request body
+     * (for POSTs/PUTs sending form-url-encoded).
+     */
+    params?: PlainObject;
+    /**
+     * HTTP Request method to use for the request. If not specified, the method will be set to POST
+     * if there are params, otherwise GET.
+     */
+    method?: string;
+    /**
+     * Headers to send with this request. A Content-Type header will be set if not provided by
+     * the caller directly or via one of the xxxJson convenience methods.
+     */
+    headers?: PlainObject;
+    /**
+     * MS to wait for response before rejecting with a timeout exception. Defaults to 30 seconds,
+     * but may be specified as null to specify no timeout.
+     */
+    timeout?: PromiseTimeoutSpec;
+    /**
+     * Optional metadata about the underlying request. Passed through for downstream processing by
+     * utils such as {@link ExceptionHandler}.
+     */
+    loadSpec?: PlainObject;
+    /**
+     * Options to pass to the underlying fetch request.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch
+     */
+    fetchOpts?: PlainObject;
+    /**
+     * Options for qs, the library used to encode query strings.
+     */
+    qsOpts?: Partial<IStringifyOptions>;
+    /**
+     * If set, any pending requests made with the same autoAbortKey will be immediately
+     * aborted in favor of the new request.
+     */
+    autoAbortKey?: string;
+}

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

@@ -0,0 +1,38 @@
+import { HoistService } from '@xh/hoist/core';
+import { GridModel, GridAutosizeOptions } from '@xh/hoist/cmp/grid';
+/**
+ * Sets appropriate column widths for a grid based on its contents. Generally seeks to make columns
+ * at least as wide as all of their contents, including headers.
+ *
+ * Unlike the native ag-Grid autosizing, this service will compute a size based on all data in the
+ * grid, including off-screen rows and columns and (if requested) collapsed rows.
+ *
+ * In order to do this efficiently, this service uses heuristics and generally assumes each
+ * column consists of similarly formatted strings.
+ *
+ * @see GridAutosizeOptions
+ */
+export declare class GridAutosizeService extends HoistService {
+    xhImpl: boolean;
+    static instance: GridAutosizeService;
+    private _columnWidthCalculator;
+    /**
+     * Calculate and apply autosized column widths.
+     *
+     * @param gridModel - GridModel to autosize.
+     * @param colIds - array of columns in model to compute sizing for.
+     * @param options - options to use for this autosize.
+     */
+    autosizeAsync(gridModel: GridModel, colIds: string[], options: GridAutosizeOptions): Promise<void>;
+    private calcRequiredWidthsAsync;
+    private gatherRecordsToBeSized;
+    /**
+     * Calculate the increased size of columns to fill any remaining space.
+     */
+    private calcFillWidths;
+    private fillEvenly;
+    private fillSequentially;
+    private getFillState;
+    private getColumnFillState;
+    private getTotalColumnWidth;
+}

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

@@ -0,0 +1,56 @@
+import { HoistService } from '@xh/hoist/core';
+import { GridModel, Column } from '@xh/hoist/cmp/grid';
+import { StoreRecord } from '@xh/hoist/data';
+/**
+ * Exports Grid data to either Excel or CSV via Hoist's server-side export capabilities.
+ * See the Column API for options to control exported values and formats.
+ */
+export declare class GridExportService extends HoistService {
+    xhImpl: boolean;
+    static instance: GridExportService;
+    /**
+     * Export the data within a GridModel to a file. Typically called via `GridModel.exportAsync()`.
+     */
+    exportAsync(gridModel: GridModel, { filename, type, columns, track, timeout }?: ExportOptions): Promise<void>;
+    /**
+     * Get the exportable value for a given cell.
+     * Used internally by this service + public to support Grid's "copy cell" context menu action.
+     */
+    getExportableValueForCell({ gridModel, record, column, node, forExcel }: {
+        gridModel: GridModel;
+        record: StoreRecord;
+        column: Column;
+        node?: any;
+        forExcel?: boolean;
+    }): any;
+    private showFailToast;
+    private getExportableColumns;
+    private getExportFieldType;
+    private getColumnMetadata;
+    private getHeaderRow;
+    private getRecordRowsRecursive;
+    private getRecordRow;
+    private getContentType;
+    private getFileExtension;
+    private minWait;
+    private getCellSpecificType;
+}
+export interface ExportOptions {
+    /**
+     * Name for export file, or closure to generate.
+     * Do not include the file extension - that will be appended based on the specified type.
+     */
+    filename?: string | ((g: GridModel) => string);
+    /** Type of export. */
+    type?: 'excel' | 'excelTable' | 'csv';
+    /**
+     *  Columns to include in export. Supports tokens 'VISIBLE' (default - all currently visible cols),
+     *  'ALL', or specific column IDs to include (can be used in conjunction with VISIBLE to export
+     *  all visible and enumerated columns). Also supports a function returning column IDs to include.
+     */
+    columns?: 'VISIBLE' | 'ALL' | string[] | ((g: GridModel) => string[]);
+    /** True to enable activity tracking of exports (default false). */
+    track?: boolean;
+    /** Timeout (in ms) for export request - defaults to 30 seconds. */
+    timeout?: number;
+}

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

@@ -0,0 +1,61 @@
+import { HoistService, HoistUser } from '@xh/hoist/core';
+/**
+ * Provides basic information related to the authenticated user, including application roles.
+ * This service loads its data from Hoist Core's server-side identity service.
+ *
+ * Also provides support for recognizing impersonation and distinguishing between the apparent and
+ * actual underlying user.
+ */
+export declare class IdentityService extends HoistService {
+    static instance: IdentityService;
+    private _authUser;
+    private _apparentUser;
+    initAsync(): Promise<void>;
+    /** Current acting user (see authUser for notes on impersonation) */
+    get user(): HoistUser;
+    /** Current acting user's username. */
+    get username(): string;
+    /**
+     * Actual user who authenticated to the web application.
+     * This will be the same as the user except when an administrator is impersonation another
+     * user for troubleshooting or testing. In those cases, this getter will return the actual
+     * administrator, whereas `this.user` will return the user they are impersonating.
+     */
+    get authUser(): HoistUser;
+    get authUsername(): string;
+    /**
+     * For applications that support a logout operation (i.e. not SSO), logs the current user out
+     * and refreshes the application to present a login panel.
+     */
+    logoutAsync(): Promise<any>;
+    /** Is an impersonation session currently active? */
+    get isImpersonating(): boolean;
+    /**
+     * Can the user impersonate other users?
+     *
+     * See also canAuthUserImpersonate() which should be consulted before actually
+     * triggering any impersonation attempts.
+     */
+    get canImpersonate(): boolean;
+    /**
+     * Can the underlying authenticated user impersonate other users?
+     *
+     * Use this getter to determine if Hoist should allow the client to show impersonation
+     * affordances and to trigger impersonation actions.
+     */
+    get canAuthUserImpersonate(): boolean;
+    /**
+     * Begin an impersonation session to act as another user. The UI server will allow this only
+     * if the actual authenticated user has the rights to do, and is attempting to impersonate
+     * a known user who has permission to and has accessed the app themselves. If successful,
+     * the application will reload and the admin will now be acting as the other user.
+     *
+     * @param username - the end-user to impersonate
+     */
+    impersonateAsync(username: string): Promise<void>;
+    /** Exit any active impersonation, reloading the app to resume accessing it as yourself. */
+    endImpersonateAsync(): Promise<any>;
+    private createUser;
+    private hasGate;
+    private canUserImpersonate;
+}

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

@@ -0,0 +1,21 @@
+import { HoistService } from '@xh/hoist/core';
+/**
+ * Manage the idling/suspension of this application after a certain period of user inactivity
+ * to cancel background tasks and prompt the user to reload the page when they wish to resume
+ * using the app. This approach is typically employed to reduce potential load on back-end
+ * system from unattended clients and/or as a "belt-and-suspenders" defence against memory
+ * leaks or other performance issues that can arise with long-running sessions.
+ *
+ * This service consults the `xhIdleConfig` soft-config and the `xhIdleDetectionDisabled`
+ * user preference to determine if and when it should suspend the app.
+ */
+export declare class IdleService extends HoistService {
+    xhImpl: boolean;
+    static instance: IdleService;
+    private timer;
+    private timeout;
+    constructor();
+    private startMonitoring;
+    private createTimer;
+    private checkInactivityTimeout;
+}

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

@@ -0,0 +1,74 @@
+import { HoistService } from '@xh/hoist/core';
+import { Timer } from '@xh/hoist/utils/async';
+/**
+ * Developer/Admin focused service to provide additional processing and stats related to the
+ * running application, specifically its current HoistModel, HoistService, and Store instances.
+ *
+ * Activating this service will cause it to maintain an observable array of summary data synced
+ * (with a minimal throttle) on each change to the Hoist registry, as well as an array of model
+ * count / memory usage stats, also updated on model changes and periodically in the background.
+ *
+ * When running in a Desktop application, activating this service will trigger the display of the
+ * Hoist Inspector UI - {@link inspectorPanel}. A built-in control to activate/deactivate this
+ * service is provided within the Desktop versionBar component.
+ *
+ * This service may be completely disabled via an optional `xhInspectorConfig` appConfig, although
+ * note that this config does *not* disable the backing registry within XH. Access to Inspector can
+ * also be limited to users with a particular app role, using the same config.
+ */
+export declare class InspectorService extends HoistService {
+    xhImpl: boolean;
+    static instance: InspectorService;
+    persistWith: {
+        localStorageKey: string;
+    };
+    /**
+     * True if Inspector is generally enabled via config.
+     * If enabled but !active, this service won't do any work, but can be activated on demand.
+     */
+    get enabled(): boolean;
+    /** True to start processing model stats and show the Inspector UI. */
+    active: boolean;
+    /** Info on current services/models/stores (when active). */
+    activeInstances: InspectorInstanceData[];
+    /** Timestamped model counts w/memory usage (when active). */
+    stats: InspectorStat[];
+    statsUpdateTimer: Timer;
+    private _syncRun;
+    private _idToSyncRun;
+    constructor();
+    initAsync(): Promise<void>;
+    toggleActive(): void;
+    activate(): void;
+    deactivate(): void;
+    updateStats(): void;
+    clearStats(): void;
+    restoreDefaultsAsync(): Promise<void>;
+    private sync;
+    setActiveInstances(ai: any): void;
+    _prevModelCount: number;
+    get conf(): any;
+}
+interface InspectorInstanceData {
+    className: string;
+    created: Date;
+    isHoistModel: boolean;
+    isHoistService: boolean;
+    isStore: boolean;
+    isLinked: boolean;
+    isXhImpl: boolean;
+    hasLoadSupport: boolean;
+    lastLoadCompleted: Date;
+    lastLoadException: any;
+    syncRun: number;
+}
+interface InspectorStat {
+    id: number;
+    timestamp: number;
+    modelCount: number;
+    modelCountChange: number;
+    totalJSHeapSize: number;
+    usedJSHeapSize: number;
+    syncRun: number;
+}
+export {};

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

@@ -0,0 +1,35 @@
+import { HoistService } from '@xh/hoist/core';
+/**
+ * Service to read and set chunks of user-specific JSON persisted via Hoist Core's JSONBlob class.
+ */
+export declare class JsonBlobService extends HoistService {
+    static instance: JsonBlobService;
+    getAsync(token: any): Promise<any>;
+    /**
+     * Return the list of blobs visible to the current user.
+     *
+     * @param type - reference key for which type of data to list.
+     * @param includeValue - true to include the full value string for each blob.
+     */
+    listAsync({ type, includeValue }: {
+        type: string;
+        includeValue?: boolean;
+    }): Promise<any>;
+    /** Persist a new JSONBlob back to the server. */
+    createAsync({ type, name, value, meta, description }: {
+        type: string;
+        name: string;
+        description?: string;
+        value: any;
+        meta?: any;
+    }): Promise<any>;
+    /** Modify an existing JSONBlob, as identified by its unique token. */
+    updateAsync(token: string, { name, value, meta, description }: {
+        name?: string;
+        value?: any;
+        meta?: any;
+        description?: string;
+    }): Promise<any>;
+    /** Archive (soft-delete) an existing JSONBlob, as identified by its unique token. */
+    archiveAsync(token: string): Promise<any>;
+}

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

@@ -0,0 +1,24 @@
+import { HoistService } from '@xh/hoist/core';
+/**
+ * Service to provide simple key/value access to browser local storage, appropriately namespaced
+ * by application code and username.
+ *
+ * In the unexpected case that local storage is not available, will provide a transient in-memory
+ * storage to support its operations and API.
+ *
+ * Relied upon by Hoist features such as local preference values and grid state.
+ */
+export declare class LocalStorageService extends HoistService {
+    static instance: LocalStorageService;
+    constructor();
+    get(key: string, defaultValue?: any): any;
+    set(key: string, value: any): void;
+    apply(key: string, newProps: object): void;
+    remove(key: string): void;
+    removeIf(predicateFn: (s: string) => boolean): void;
+    clear(): void;
+    keys(): string[];
+    get isFake(): boolean;
+    private getInstance;
+    private getNamespace;
+}

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

@@ -0,0 +1,76 @@
+import { HoistService } from '@xh/hoist/core';
+/**
+ * Service to read and set user-specific preference values.
+ *
+ * Server-side preference support is provided by hoist-core. Preferences must be predefined on the
+ * server (they can be managed via the Admin console) and are referenced by their string key. They
+ * are assigned default values that apply to users who have yet to have a value set that is specific
+ * to their account. Once set, however, the user will get their customized value instead of the
+ * default going forwards.
+ *
+ * This could happen via an explicit option the user adjusts, or happen transparently based on a
+ * natural user action or component integration (e.g. collapsing or resizing a `Resizable` that has
+ * been configured with preference support).
+ *
+ * Preferences are persisted automatically back to the server by default so as to follow their user
+ * across workstations.
+ */
+export declare class PrefService extends HoistService {
+    static instance: PrefService;
+    private _data;
+    private _updates;
+    private pushPendingBuffered;
+    constructor();
+    initAsync(): Promise<void>;
+    /**
+     * Check to see if a given preference has been *defined*.
+     */
+    hasKey(key: string): boolean;
+    /**
+     * Get the value for a given key, either the user-specific value (if set) or the default.
+     * Typically accessed via the convenience alias {@link XH.getPref}.
+     *
+     * @param key - unique key used to identify the pref.
+     * @param defaultValue - value to return if the preference key is not found - i.e.
+     *      the config has not been created on the server - instead of throwing. Use sparingly!
+     *      In general, it's better to not provide defaults here, but instead keep entries updated
+     *      via the Admin client and have it be obvious when one is missing.
+     */
+    get(key: string, defaultValue?: any): any;
+    /**
+     * Set a preference value for the current user.
+     * Typically accessed via the convenience alias {@link XH.setPref}.
+     *
+     * Values are validated client-side to ensure they (probably) are of the correct data type.
+     *
+     * Values are saved to the server in an asynchronous and debounced manner.
+     * See pushAsync() and pushPendingAsync()
+     */
+    set(key: string, value: any): void;
+    /**
+     * Restore a preference to its default value.
+     */
+    unset(key: string): void;
+    /**
+     * Set a preference value for the current user, and immediately trigger a sync to the server.
+     *
+     * Useful when important to verify that the preference has been fully round-tripped - e.g.
+     * before making another call that relies on its updated value being read on the server.
+     */
+    pushAsync(key: string, value: any): Promise<void>;
+    /**
+     * Reset *all* preferences, reverting their effective values back to defaults.
+     * @returns a Promise that resolves when preferences have been cleared and defaults reloaded.
+     */
+    clearAllAsync(): Promise<void>;
+    /**
+     * Push any pending buffered updates to persist newly set values to server.
+     * Called automatically by this app on page unload to avoid dropping changes when e.g. a user
+     * changes and option and then immediately hits a (browser) refresh.
+     */
+    pushPendingAsync(): Promise<void>;
+    private loadPrefsAsync;
+    private migrateLocalPrefsAsync;
+    private validateBeforeSet;
+    private valueIsOfType;
+}

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

@@ -0,0 +1,15 @@
+import { HoistService, TrackOptions } from '@xh/hoist/core';
+/**
+ * Primary service for tracking any activity that an application's admins want to track.
+ * Activities are available for viewing/querying in the Admin Console's Client Activity tab.
+ * Client metadata is set automatically by the server's parsing of request headers.
+ */
+export declare class TrackService extends HoistService {
+    static instance: TrackService;
+    private _oncePerSessionSent;
+    get conf(): any;
+    get enabled(): boolean;
+    /** Track User Activity. */
+    track(options: TrackOptions | string): void;
+    private doTrackAsync;
+}