@xh/hoist 78.0.0-SNAPSHOT.1763737348746 → 79.0.0-SNAPSHOT.1763737948137

package/CHANGELOG.md

@@ -1,6 +1,8 @@
 # Changelog
 
-## 78.0.0-SNAPSHOT - unreleased
+## 79.0.0-SNAPSHOT - unreleased
+
+## 78.0.0 - 2025-11-21
 
 ### 💥 Breaking Changes
 
@@ -27,8 +29,7 @@
 
 ### ⚙️ Technical
 
-* Updated the Cube API's `BucketSpecFn` to return either a concrete `BucketSpec` class instance (as
-  before) or a plain object conforming to the new `BucketSpecConfig` interface.
+* Improved documentation on `BucketSpec` class.
 * Enhanced `FetchService` to recognize variants on the `application/json` content-type when
   processing failed responses and decoding exceptions - e.g. `application/problem+json`.
 

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

@@ -20,6 +20,8 @@ export type Thunkable<T> = T | (() => T);
 export type Awaitable<T> = Promise<T> | T;
 /** Convenience type for a "plain", string-keyed object holding any kind of values. */
 export type PlainObject = Record<string, any>;
+/** Convenience type to make a set of keys optional in a given type. */
+export type SetOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 /**
  * Specification for debouncing in Hoist.
  *

package/build/types/data/cube/BucketSpec.d.ts

@@ -1,4 +1,5 @@
 import { BaseRow } from './row/BaseRow';
+import { SetOptional } from '@xh/hoist/core';
 /**
  * Spec to define a bucketing level within the hierarchy of data returned by a Query, as identified
  * by a set of rows passed to a {@link BucketSpecFn} configured on that Query (or defaulted from
@@ -6,7 +7,7 @@ import { BaseRow } from './row/BaseRow';
  * spec's `bucketFn` to determine if it should yield a value for the bucket, causing the row to be
  * nested underneath a new {@link BucketRow} created to hold all rows with that value.
  */
-export interface BucketSpecConfig {
+export declare class BucketSpec {
     /** Name for the bucketing level configured by this spec - equivalent to a dimension name. */
     name: string;
     /**
@@ -18,19 +19,13 @@ export interface BucketSpecConfig {
      * Function returning bucket row label from the bucket value string returned by bucketFn.
      * Defaults to using the value directly.
      */
-    labelFn?: (bucket: string) => string;
+    labelFn: (bucket: string) => string;
     /**
      * Fields on which the `bucketFn` depends, to ensure rows are re-bucketed if dependent field
      * values change. If not provided or does not cover all fields potentially accessed by
      * `bucketFn`, an incremental "data only" update that should have changed a row's bucket can
      * fail to do so.
      */
-    dependentFields?: string[];
-}
-export declare class BucketSpec {
-    name: string;
-    bucketFn: (row: BaseRow) => string;
-    labelFn: (bucket: string) => string;
     dependentFields: string[];
-    constructor(config: BucketSpecConfig);
+    constructor(config: SetOptional<BucketSpec, 'labelFn' | 'dependentFields'>);
 }

package/build/types/data/cube/Cube.d.ts

@@ -8,7 +8,7 @@ import { StoreRecord } from '../StoreRecord';
 import { AggregateRow } from './row/AggregateRow';
 import { BucketRow } from './row/BucketRow';
 import { BaseRow } from './row/BaseRow';
-import { BucketSpec, BucketSpecConfig } from './BucketSpec';
+import { BucketSpec } from './BucketSpec';
 export interface CubeConfig {
     fields: CubeField[] | CubeFieldSpec[];
     /** Default configs applied to all `CubeField`s constructed internally by this Cube. */
@@ -60,9 +60,9 @@ export type OmitFn = (row: AggregateRow | BucketRow) => boolean;
  * aggregations and create an unwanted "Open" grouping.
  *
  * @param rows - the rows being checked for bucketing
- * @returns {@link BucketSpecConfig} for dynamic sub-aggregations, or null to perform no bucketing.
+ * @returns {@link BucketSpec} for dynamic sub-aggregations, or null to perform no bucketing.
  */
-export type BucketSpecFn = (rows: BaseRow[]) => BucketSpecConfig | BucketSpec;
+export type BucketSpecFn = (rows: BaseRow[]) => BucketSpec;
 /**
  * A data store that supports grouping, aggregating, and filtering data on multiple dimensions.
  *

package/build/types/data/cube/Query.d.ts

@@ -79,7 +79,7 @@ export interface QueryConfig {
      *
      * 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 BucketSpecFn} type and {@link BucketSpecConfig} interface for additional information.
+     * {@link BucketSpecFn} type and {@link BucketSpec} interface for additional information.
      *
      * Defaults to {@link Cube.bucketSpecFn}.
      */

package/core/types/Types.ts

@@ -34,6 +34,9 @@ export type Awaitable<T> = Promise<T> | T;
 /** Convenience type for a "plain", string-keyed object holding any kind of values. */
 export type PlainObject = Record<string, any>;
 
+/** Convenience type to make a set of keys optional in a given type. */
+export type SetOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
 /**
  * Specification for debouncing in Hoist.
  *

package/data/cube/BucketSpec.ts

@@ -6,6 +6,7 @@
  */
 
 import {BaseRow} from './row/BaseRow';
+import {SetOptional} from '@xh/hoist/core';
 
 /**
  * Spec to define a bucketing level within the hierarchy of data returned by a Query, as identified
@@ -14,35 +15,31 @@ import {BaseRow} from './row/BaseRow';
  * spec's `bucketFn` to determine if it should yield a value for the bucket, causing the row to be
  * nested underneath a new {@link BucketRow} created to hold all rows with that value.
  */
-export interface BucketSpecConfig {
+export class BucketSpec {
     /** Name for the bucketing level configured by this spec - equivalent to a dimension name. */
     name: string;
+
     /**
      * Function returning the bucketed value (if any) into which the given row should be placed -
      * equivalent to a dimension value. Return null/undefined to exclude the row from bucketing.
      */
     bucketFn: (row: BaseRow) => string;
+
     /**
      * Function returning bucket row label from the bucket value string returned by bucketFn.
      * Defaults to using the value directly.
      */
-    labelFn?: (bucket: string) => string;
+    labelFn: (bucket: string) => string;
+
     /**
      * Fields on which the `bucketFn` depends, to ensure rows are re-bucketed if dependent field
      * values change. If not provided or does not cover all fields potentially accessed by
      * `bucketFn`, an incremental "data only" update that should have changed a row's bucket can
      * fail to do so.
      */
-    dependentFields?: string[];
-}
-
-export class BucketSpec {
-    name: string;
-    bucketFn: (row: BaseRow) => string;
-    labelFn: (bucket: string) => string;
     dependentFields: string[];
 
-    constructor(config: BucketSpecConfig) {
+    constructor(config: SetOptional<BucketSpec, 'labelFn' | 'dependentFields'>) {
         this.name = config.name;
         this.bucketFn = config.bucketFn;
         this.labelFn = config.labelFn ?? (b => b);

package/data/cube/Cube.ts

@@ -17,7 +17,7 @@ import {StoreRecord} from '../StoreRecord';
 import {AggregateRow} from './row/AggregateRow';
 import {BucketRow} from './row/BucketRow';
 import {BaseRow} from './row/BaseRow';
-import {BucketSpec, BucketSpecConfig} from './BucketSpec';
+import {BucketSpec} from './BucketSpec';
 import {defaultsDeep, isEmpty} from 'lodash';
 
 export interface CubeConfig {
@@ -82,9 +82,9 @@ export type OmitFn = (row: AggregateRow | BucketRow) => boolean;
  * aggregations and create an unwanted "Open" grouping.
  *
  * @param rows - the rows being checked for bucketing
- * @returns {@link BucketSpecConfig} for dynamic sub-aggregations, or null to perform no bucketing.
+ * @returns {@link BucketSpec} for dynamic sub-aggregations, or null to perform no bucketing.
  */
-export type BucketSpecFn = (rows: BaseRow[]) => BucketSpecConfig | BucketSpec;
+export type BucketSpecFn = (rows: BaseRow[]) => BucketSpec;
 
 /**
  * A data store that supports grouping, aggregating, and filtering data on multiple dimensions.

package/data/cube/Query.ts

@@ -107,7 +107,7 @@ export interface QueryConfig {
      *
      * 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 BucketSpecFn} type and {@link BucketSpecConfig} interface for additional information.
+     * {@link BucketSpecFn} type and {@link BucketSpec} interface for additional information.
      *
      * Defaults to {@link Cube.bucketSpecFn}.
      */

package/data/cube/View.ts

@@ -18,7 +18,6 @@ import {
     StoreRecord,
     StoreRecordId
 } from '@xh/hoist/data';
-import {BucketSpec} from '@xh/hoist/data/cube/BucketSpec';
 import {ViewRowData} from '@xh/hoist/data/cube/ViewRowData';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {shallowEqualArrays} from '@xh/hoist/utils/impl';
@@ -365,13 +364,9 @@ export class View extends HoistBase {
         if (!query.bucketSpecFn) return rows;
         if (!query.includeLeaves && rows[0]?.isLeaf) return rows;
 
-        const bucketSpecOrConf = query.bucketSpecFn(rows);
-        if (!bucketSpecOrConf) return rows;
+        const bucketSpec = query.bucketSpecFn(rows);
+        if (!bucketSpec) return rows;
 
-        const bucketSpec =
-            bucketSpecOrConf instanceof BucketSpec
-                ? bucketSpecOrConf
-                : new BucketSpec(bucketSpecOrConf);
         const {name: bucketName, bucketFn, dependentFields} = bucketSpec,
             buckets: Record<string, BaseRow[]> = {},
             ret: BaseRow[] = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "78.0.0-SNAPSHOT.1763737348746",
+  "version": "79.0.0-SNAPSHOT.1763737948137",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",