@xh/hoist 75.0.0-SNAPSHOT.1754335298677 → 75.0.0-SNAPSHOT.1754604038542

package/data/cube/Cube.ts

@@ -9,6 +9,7 @@ import {HoistBase, managed, PlainObject, Some} from '@xh/hoist/core';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {forEachAsync} from '@xh/hoist/utils/async';
 import {CubeField, CubeFieldSpec} from './CubeField';
+import {ViewRowData} from './ViewRowData';
 import {Query, QueryConfig} from './Query';
 import {View} from './View';
 import {Store, StoreRecordIdSpec, StoreTransaction} from '../Store';
@@ -56,6 +57,35 @@ export interface CubeConfig {
     omitFn?: OmitFn;
 }
 
+/**
+ * Function to be called for each node to aggregate to determine if it should be "locked",
+ * preventing drilldown into its children. If true returned for a node, no drilldown will be
+ * allowed, and the row will be marked with a boolean "locked" property.
+ */
+export type LockFn = (row: AggregateRow | BucketRow) => boolean;
+
+/**
+ * Function to be called for each node during row generation to determine if it should be
+ * skipped in tree output.  Useful for removing aggregates that are degenerate due to context.
+ * Note that skipping in this way has no effect on aggregations -- all children of this node are
+ * simply promoted to their parent node.
+ */
+export type OmitFn = (row: AggregateRow | BucketRow) => boolean;
+
+/**
+ * Function to be called for rows making up an aggregated dimension to determine if the children of
+ * that dimension should be dynamically bucketed into additional sub-groupings.
+ *
+ * An example use case would be a grouped collection of portfolio positions, where any closed
+ * positions are identified as such by this function and bucketed into a "Closed" sub-grouping,
+ * without having to add something like an "openClosed" dimension that would apply to all
+ * aggregations and create an unwanted "Open" grouping.
+ *
+ * @param rows - the rows being checked for bucketing
+ * @returns BucketSpec for configuring dynamic sub-aggregations, or null to perform no bucketing.
+ */
+export type BucketSpecFn = (rows: BaseRow[]) => BucketSpec;
+
 /**
  * A data store that supports grouping, aggregating, and filtering data on multiple dimensions.
  *
@@ -94,7 +124,7 @@ export class Cube extends HoistBase {
         this.store = new Store({
             fields: this.parseFields(fields, fieldDefaults),
             idSpec,
-            processRawData: processRawData as any,
+            processRawData: processRawData,
             freezeData: false,
             idEncodesTreePath: true
         });
@@ -143,9 +173,9 @@ export class Cube extends HoistBase {
      * @param query - Config for query defining the shape of the view.
      * @returns data containing the results of the query as a hierarchical set of rows.
      */
-    executeQuery(query: QueryConfig): any {
-        const q = new Query({...query, cube: this});
-        const view = new View({query: q}),
+    executeQuery(query: QueryConfig): ViewRowData[] {
+        const q = new Query({...query, cube: this}),
+            view = new View({query: q}),
             rows = view.result.rows;
 
         view.destroy();
@@ -153,19 +183,19 @@ export class Cube extends HoistBase {
     }
 
     /**
-     * Create a View on this data.
+     * Create a dynamic {@link View} of the cube data based on a query. Unlike the static snapshot
+     * returned by {@link Cube.executeQuery}, a View created with this method can be configured
+     * with `connect:true` to automatically update as the underlying data in the Cube changes.
      *
-     * Creates a dynamic View of the cube data, based on a query.  Useful for binding to grids a
-     * and efficiently displaying changing results in the Cube.
+     * Provide one or more `stores` to automatically populate them with the aggregated data returned
+     * by the query, or read the returned {@link View.result} directly.
      *
-     * Note: Applications should call {@link View.disconnect} or {@link View.destroy} on the View
-     * created by this method when appropriate to avoid unnecessary processing.
+     * When the returned View is no longer needed, call {@link View.destroy} (or save a reference
+     * via an `@managed` model property) to avoid unnecessary processing.
      *
      * @param query - query to be used to construct this view.
-     * @param stores - Stores to be loaded/reloaded with data from this view.
-     *      To receive data only, use the 'results' property of the returned View instead.
-     * @param connect - true to update View automatically when data in
-     *      the underlying cube is changed. Default false.
+     * @param stores - Stores to be automatically loaded/reloaded with View results.
+     * @param connect - true to update View automatically when data in the underlying Cube changes.
      */
     createView({
         query,
@@ -183,14 +213,12 @@ export class Cube extends HoistBase {
         });
     }
 
-    /**
-     * True if the provided view is connected to this Cube for live updates.
-     */
+    /** True if the provided view is connected to this Cube for live updates. */
     viewIsConnected(view: View): boolean {
         return this._connectedViews.has(view);
     }
 
-    /** @param view - view to disconnect from live updates. */
+    /** Cease pushing further updates to this Cube's data into a previously connected View. */
     disconnectView(view: View) {
         this._connectedViews.delete(view);
     }
@@ -200,12 +228,10 @@ export class Cube extends HoistBase {
     //-------------------
     /**
      * Populate this cube with a new dataset.
+     * This method largely delegates to {@link Store.loadData} - see that method for more info.
      *
-     * This method largely delegates to Store.loadData().  See that method for more
-     * information.
-     *
-     * Note that this method will update its views asynchronously, in order to avoid locking
-     * up the browser when attached to multiple expensive views.
+     * Note that this method will update its views asynchronously in order to avoid locking up the
+     * browser when attached to multiple expensive views.
      *
      * @param rawData - flat array of lowest/leaf level data rows.
      * @param info - optional metadata to associate with this cube/dataset.
@@ -303,28 +329,3 @@ export class Cube extends HoistBase {
         super.destroy();
     }
 }
-
-/**
- * Function to be called for each node to aggregate to determine if it should be "locked",
- * preventing drilldown into its children. If true returned for a node, no drilldown will be
- * allowed, and the row will be marked with a boolean "locked" property.
- */
-export type LockFn = (row: AggregateRow | BucketRow) => boolean;
-
-/**
- * Function to be called for each node during row generation to determine if it should be
- * skipped in tree output.  Useful for removing aggregates that are degenerate due to context.
- * Note that skipping in this way has no effect on aggregations -- all children of this node are
- * simply promoted to their parent node.
- */
-export type OmitFn = (row: AggregateRow | BucketRow) => boolean;
-
-/**
- * Function to be called for each dimension to determine if children of said dimension should be
- * bucketed into additional dynamic dimensions.
- *
- * @param rows - the rows being checked for bucketing
- * @returns a BucketSpec for configuring the bucket to place child rows into, or null to perform
- *          no bucketing
- */
-export type BucketSpecFn = (rows: BaseRow[]) => BucketSpec;

package/data/cube/Query.ts

@@ -5,53 +5,90 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 
-import {BucketSpecFn, Filter, LockFn, OmitFn, parseFilter, StoreRecord} from '@xh/hoist/data';
-import {isEqual, find} from 'lodash';
-import {FilterLike, FilterTestFn} from '../filter/Types';
-import {CubeField} from './CubeField';
-import {Cube} from './Cube';
+import {
+    BucketSpecFn,
+    Filter,
+    FilterLike,
+    FilterTestFn,
+    LockFn,
+    OmitFn,
+    parseFilter,
+    StoreRecord
+} from '@xh/hoist/data';
 import {throwIf} from '@xh/hoist/utils/js';
+import {find, isEqual} from 'lodash';
+import {Cube} from './Cube';
+import {CubeField} from './CubeField';
 
 /**
- * Queries determine what data is extracted from a cube and how it should be grouped + aggregated.
- *
- * Note that if no dimensions are provided, 'includeRoot' or 'includeLeaves' should be true -
- * otherwise no data will be returned!
+ * Queries determine what data is extracted, grouped, and aggregated from a {@link Cube}.
  */
 export interface QueryConfig {
     /**
-     * Associated Cube. Required, but note that `Cube.executeQuery()` will install a reference to
-     * itself on the query config (automatically)
+     * The Cube to query. Required, but note that the preferred {@link Cube.executeQuery} API will
+     * install a reference to itself on the query config (automatically).
      */
     cube?: Cube;
 
     /**
-     * Fields or field names. If unspecified will include all available fields
-     * from the source Cube, otherwise supply a subset to optimize aggregation performance.
+     * Fields or field names. If unspecified will include all available {@link Cube.fields}.
+     * Specify a subset to optimize aggregation performance.
      */
     fields?: string[] | CubeField[];
 
     /**
-     * Fields or field names to group on. Any fields provided must also be in fields config, above. If none
-     * given the resulting data will not be grouped.
+     * Fields or field names on which data should be grouped and aggregated. These are the ordered
+     * grouping levels in the resulting hierarchy - e.g. ['Country', 'State', 'City'].
+     *
+     * Any fields provided here must also be included in the `fields` array, if specified.
+     *
+     * If not provided or empty, the resulting data will not be grouped. Specify 'includeRoot' or
+     * 'includeLeaves' in that case, otherwise no data will be returned.
      */
     dimensions?: string[] | CubeField[];
 
     /**
-     * One or more filters or configs to create one.  If an array, a single 'AND' filter will
-     * be created.
+     * Filters to apply to leaf data, or configs to create. Note that leaf data will be filtered
+     * and then aggregated - i.e. the filters provided here will filter in/out the lowest level
+     * facts and _won't_ operate directly on any aggregates.
+     *
+     * Arrays will be combined into a single 'AND' CompoundFilter.
      */
     filter?: FilterLike;
 
     /**
-     * IncludeRoot?: True to include a synthetic root node in the return with grand total
-     * aggregate values.
+     * True to include a synthetic root node in the return with grand totals (aggregations across
+     * all data returned by the query). Pairs well with {@link StoreConfig.loadRootAsSummary} and
+     * {@link GridConfig.showSummary} to display a docked grand total row for grids rendering
+     * Cube results.
      */
     includeRoot?: boolean;
 
-    /** True to include leaf nodes in return.*/
+    /**
+     * True to include leaf nodes (the "flat" facts originally loaded into the Cube) as the
+     * {@link ViewRowData.children} of the lowest level of aggregated `dimensions`.
+     *
+     * False (the default) to only return aggregate rows based on requested `dimensions`.
+     *
+     * Useful when you wish to e.g. load Cube results into a tree grid and allow users to expand
+     * aggregated groups all the way out to see the source data. See also `provideLeaves`, which
+     * will provide access to these nodes without exposing as `children`.
+     */
     includeLeaves?: boolean;
 
+    /**
+     * True to provide access to leaf nodes via the {@link ViewRowData.cubeLeaves} getter on the
+     * lowest level of aggregated `dimensions`. This will allow programmatic access to the leaves
+     * used to produce a given aggregation, without exposing them as `children` in a way that would
+     * cause them to be rendered in a tree grid.
+     *
+     * Useful when e.g. a full leaf-level drill-down is not desired, but the app still needs
+     * access to those leaves to display in a separate view or for further processing.
+     *
+     * See also the more common `includeLeaves`.
+     */
+    provideLeaves?: boolean;
+
     /**
      * True (default) to recursively omit single-child parents in the hierarchy.
      * Apps can implement further omit logic using `omitFn`.
@@ -60,14 +97,21 @@ export interface QueryConfig {
 
     /**
      * Optional function to be called for each aggregate node to determine if it should be "locked",
-     * preventing drill-down into its children.  Defaults to Cube.lockFn.
+     * preventing drill-down into its children.
+     *
+     * Defaults to {@link Cube.lockFn}.
      */
     lockFn?: LockFn;
 
     /**
      * Optional function to be called for each dimension during row generation to determine if the
      * children of that dimension should be bucketed into additional dynamic dimensions.
-     * Defaults to Cube.bucketSpecFn.
+     *
+     * This can be used to break selected aggregations into sub-groups dynamically, without having
+     * to define another dimension in the Cube and have it apply to all aggregations. See the
+     * {@link BucketSpec} interface for additional information.
+     *
+     * Defaults to {@link Cube.bucketSpecFn}.
      */
     bucketSpecFn?: BucketSpecFn;
 
@@ -85,6 +129,7 @@ export class Query {
     readonly filter: Filter;
     readonly includeRoot: boolean;
     readonly includeLeaves: boolean;
+    readonly provideLeaves: boolean;
     readonly omitRedundantNodes: boolean;
     readonly cube: Cube;
     readonly lockFn: LockFn;
@@ -100,6 +145,7 @@ export class Query {
         filter = null,
         includeRoot = false,
         includeLeaves = false,
+        provideLeaves = false,
         omitRedundantNodes = true,
         lockFn = cube.lockFn,
         bucketSpecFn = cube.bucketSpecFn,
@@ -110,6 +156,7 @@ export class Query {
         this.dimensions = this.parseDimensions(dimensions);
         this.includeRoot = includeRoot;
         this.includeLeaves = includeLeaves;
+        this.provideLeaves = provideLeaves;
         this.omitRedundantNodes = omitRedundantNodes;
         this.filter = parseFilter(filter);
         this.lockFn = lockFn;
@@ -126,6 +173,7 @@ export class Query {
             filter: this.filter,
             includeRoot: this.includeRoot,
             includeLeaves: this.includeLeaves,
+            provideLeaves: this.provideLeaves,
             omitRedundantNodes: this.omitRedundantNodes,
             lockFn: this.lockFn,
             bucketSpecFn: this.bucketSpecFn,
@@ -153,8 +201,7 @@ export class Query {
     }
 
     /**
-     * True if the provided other Query is equivalent to this instance,
-     * not considering the filter.
+     * True if the provided other Query is equivalent to this instance, not considering the filter.
      */
     equalsExcludingFilter(other: Query): boolean {
         return (
@@ -163,6 +210,7 @@ export class Query {
             this.cube === other.cube &&
             this.includeRoot === other.includeRoot &&
             this.includeLeaves === other.includeLeaves &&
+            this.provideLeaves === other.provideLeaves &&
             this.omitRedundantNodes === other.omitRedundantNodes &&
             this.bucketSpecFn == other.bucketSpecFn &&
             this.omitFn == other.omitFn &&

package/data/cube/View.ts

@@ -17,6 +17,7 @@ import {
     StoreRecord,
     StoreRecordId
 } from '@xh/hoist/data';
+import {ViewRowData} from '@xh/hoist/data/cube/ViewRowData';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {shallowEqualArrays} from '@xh/hoist/utils/impl';
 import {logWithDebug, throwIf} from '@xh/hoist/utils/js';
@@ -32,19 +33,24 @@ export interface ViewConfig {
     query: Query;
 
     /**
-     * Store(s) to be automatically (re)loaded with data from this view. Optional - read the View's
-     * observable `result` property directly to use without a Store.
+     * Store(s) to be automatically (re)loaded with data from this view.
+     * Optional - read {@link View.result} directly to use without a Store.
      */
     stores?: Store[] | Store;
 
     /**
-     * True to reactively update the View's `result` and any connected store(s) when data in the
-     * underlying Cube is changed. False (default) to have this view run its query once to capture
-     * a snapshot without further updates based on Cube changes.
+     * True to reactively update the View's {@link View.result} and any connected store(s) when data
+     * in the underlying Cube changes. False (default) to have this view run its query once to
+     * capture a snapshot without further (automatic) updates.
      */
     connect?: boolean;
 }
 
+export interface ViewResult {
+    rows: ViewRowData[];
+    leafMap: Map<StoreRecordId, LeafRow>;
+}
+
 export interface DimensionValue {
     /** Dimension field. */
     field: CubeField;
@@ -62,34 +68,34 @@ export class View extends HoistBase {
         return true;
     }
 
-    /** Query defining this View. Update via `updateQuery()`. */
+    /** Query defining this View. Update via {@link updateQuery}. */
     @observable.ref
     query: Query = null;
 
     /**
-     * Results of this view, an observable object with a `rows` property
-     * containing an array of hierarchical data objects.
+     * Results of this view, an observable object with a `rows` property containing an array of
+     * hierarchical {@link ViewRowData} objects.
      */
     @observable.ref
-    result: {rows: PlainObject[]; leafMap: Map<StoreRecordId, LeafRow>} = null;
+    result: ViewResult = null;
 
     /** Stores to which results of this view should be (re)loaded. */
     stores: Store[] = null;
 
-    /** Cube info associated with this View when last updated. */
+    /** The source {@link Cube.info} as of the last time this View was updated. */
     @observable.ref
     info: PlainObject = null;
 
-    /** timestamp (ms) of the last time this view's data was changed. */
+    /** Timestamp (ms) of the last time this view's data was changed. */
     @observable
     lastUpdated: number;
 
     // Implementation
-    private _rows: PlainObject[] = null;
-    private _rowCache: Map<string, BaseRow> = null;
+    private _rowDatas: ViewRowData[] = null;
     private _leafMap: Map<StoreRecordId, LeafRow> = null;
     private _recordMap: Map<StoreRecordId, StoreRecord> = null;
     _aggContext: AggregationContext = null;
+    _rowCache: Map<string, BaseRow> = null;
 
     /** @internal - applications should use {@link Cube.createView} */
     constructor(config: ViewConfig) {
@@ -144,8 +150,7 @@ export class View extends HoistBase {
      * Change the query in some way, re-computing the data in this View to reflect the new query.
      *
      * @param overrides - changes to be applied to the query. May include any arguments to the query
-     *      constructor except `cube`, which cannot be changed on a view once set
-     *      via the initial query.
+     *      constructor except `cube`, which cannot be changed once set via the initial query.
      */
     @action
     updateQuery(overrides: Partial<QueryConfig>) {
@@ -164,9 +169,7 @@ export class View extends HoistBase {
         this.fullUpdate();
     }
 
-    /**
-     * Gathers all unique values for each dimension field in the query
-     */
+    /** Gather all unique values for each dimension field in the query. */
     getDimensionValues(): DimensionValue[] {
         const {_leafMap} = this,
             fields = this.query.fields.filter(it => it.isDimension);
@@ -229,6 +232,7 @@ export class View extends HoistBase {
         this.updateResults();
     }
 
+    @logWithDebug
     private dataOnlyUpdate(updates: StoreRecord[]) {
         const {_leafMap, _recordMap, stores} = this,
             updatedRowDatas = new Set<PlainObject>();
@@ -252,17 +256,17 @@ export class View extends HoistBase {
     }
 
     private loadStores() {
-        const {_leafMap, _rows} = this;
-        if (!_leafMap || !_rows) return;
+        const {_leafMap, _rowDatas} = this;
+        if (!_leafMap || !_rowDatas) return;
 
         // Skip degenerate root in stores/grids, but preserve in object api.
-        const storeRows = _leafMap.size !== 0 ? _rows : [];
+        const storeRows = _leafMap.size !== 0 ? _rowDatas : [];
         this.stores.forEach(s => s.loadData(storeRows));
     }
 
     private updateResults() {
-        const {_leafMap, _rows} = this;
-        this.result = {rows: _rows, leafMap: _leafMap};
+        const {_leafMap, _rowDatas} = this;
+        this.result = {rows: _rowDatas, leafMap: _leafMap};
         this.info = this.cube.info;
         this.lastUpdated = Date.now();
     }
@@ -274,7 +278,7 @@ export class View extends HoistBase {
             rootId = 'root';
 
         const records = this._aggContext.filteredRecords;
-        const leafMap = new Map();
+        const leafMap: Map<StoreRecordId, LeafRow> = new Map();
         let newRows = this.groupAndInsertRecords(records, dimensions, rootId, {}, leafMap);
         newRows = this.bucketRows(newRows, rootId, {});
 
@@ -292,10 +296,10 @@ export class View extends HoistBase {
 
         this._leafMap = leafMap;
 
-        // This is the magic.  We only actually reveal to API the network of *data* nodes.
+        // This is the magic. We only actually reveal to API the network of *data* nodes.
         // This hides all the meta information, as well as unwanted leaves and skipped rows.
         // Underlying network still there and updates will flow up through it via the leaves.
-        this._rows = newRows.flatMap(it => it.getVisibleDatas());
+        this._rowDatas = newRows.flatMap(it => it.getVisibleDatas());
     }
 
     private groupAndInsertRecords(

package/data/cube/ViewRowData.ts

@@ -0,0 +1,66 @@
+/*
+ * 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, Some} from '@xh/hoist/core';
+import {flatMap} from 'lodash';
+
+/**
+ * Grouped node data, as returned by {@link Cube.executeQuery} or exposed via {@link View.result}.
+ * Designed for direct consumption by hierarchical stores and their associated tree grids.
+ */
+export class ViewRowData implements PlainObject {
+    constructor(id: string) {
+        this.id = id;
+    }
+
+    /** Unique id. */
+    id: string;
+
+    /**
+     * Label of the row. The dimension value or, for leaf rows. the underlying cubeId.
+     * Suitable for display, although apps will typically wish to customize leaf row rendering.
+     */
+    cubeLabel: string;
+
+    /** Dimension on which this row was computed, or null for leaf rows. */
+    cubeDimension: string;
+
+    /**
+     * Buckets this row appears in
+     */
+    cubeBuckets: Record<string, any>;
+
+    /**
+     * Visible children of this row.
+     *
+     * Note that this may not be the same as the simple aggregation children of this row.  In
+     * particular, this property is subject to the semantics of row locking, redundant row omission,
+     * and bucketing as defined by the Query.
+     */
+    children: ViewRowData[];
+
+    /** True for leaf rows loaded into the cube (i.e. not a grouped aggregation). */
+    get isCubeLeaf(): boolean {
+        return this.cubeDimension == null;
+    }
+
+    /**
+     * All visible (i.e. non-locked) cube leaves associated with this row.
+     *
+     * For this to be populated, either {@link Query.includeLeaves} or {@link Query.provideLeaves}
+     * must have been set on the underlying Query.
+     */
+    get cubeLeaves(): Some<ViewRowData> {
+        if (this.isCubeLeaf) return this;
+        return this._cubeLeafChildren ?? flatMap(this.children, 'cubeLeaves');
+    }
+
+    //------------------
+    // Implementation
+    //-----------------
+    /** @internal */
+    _cubeLeafChildren: ViewRowData[];
+}

package/data/cube/row/AggregateRow.ts

@@ -11,14 +11,17 @@ import {View} from '../View';
 import {BaseRow} from './BaseRow';
 
 /**
- *  Object used by views to gather Aggregate rows.
+ *  Row within a dataset produced by a Cube / View representing aggregated data on a dimension.
+ *
+ * This is an internal data structure - {@link ViewRowData} is the public row-level data API.
  */
 export class AggregateRow extends BaseRow {
     override get isAggregate() {
         return true;
     }
 
-    readonly dim: CubeField = null; // null for summary row
+    /** The dimension for which this row is aggregating data. Null for a top-level summary row. */
+    readonly dim: CubeField = null;
     readonly dimName: string = null;
 
     constructor(