@tanstack/table-core 9.0.0-beta.49 → 9.0.0-beta.50

package/dist/features/aggregation/aggregationFeature.types.d.ts

@@ -16,6 +16,14 @@ interface AggregationContext<TFeatures extends TableFeatures, TData extends RowD
   column: Column<TFeatures, TData, TValue>;
   /** Convenience alias for `column.id`. */
   columnId: string;
+  /** Maximum relative sub-row depth used to select `rows`. */
+  maxDepth: number;
+  /**
+   * Immediate sub-rows for grouped aggregation. This property is omitted
+   * for root or caller-supplied-row aggregation. At a terminal grouping level
+   * these are the direct data rows; at a nested level they are sub-row groups.
+   */
+  subRows?: ReadonlyArray<Row<TFeatures, TData>>;
   /** Reads this column's value from one of `rows`. */
   getValue: (row: Row<TFeatures, TData>) => TValue;
   /**
@@ -25,8 +33,8 @@ interface AggregationContext<TFeatures extends TableFeatures, TData extends RowD
    */
   groupingRow?: Row<TFeatures, TData>;
   /**
-   * Terminal leaf rows included in this aggregation. The executor normalizes
-   * hierarchical and duplicate row inputs before invoking the definition.
+   * Unique rows selected at `maxDepth`. Branches that end before `maxDepth`
+   * contribute their deepest available row.
    */
   rows: ReadonlyArray<Row<TFeatures, TData>>;
   /** The table that owns the column and rows. */
@@ -34,18 +42,18 @@ interface AggregationContext<TFeatures extends TableFeatures, TData extends RowD
 }
 /** Additional values available when merging nested grouped results. */
 interface AggregationMergeContext<TFeatures extends TableFeatures, TData extends RowData, TValue, TResult> extends AggregationContext<TFeatures, TData, TValue> {
-  /** Results produced for each immediate child group, in child-row order. */
-  childResults: ReadonlyArray<TResult>;
-  /** Immediate child group rows corresponding to `childResults`. */
-  childRows: ReadonlyArray<Row<TFeatures, TData>>;
+  /** Results produced for each immediate sub-row group, in sub-row order. */
+  subRowResults: ReadonlyArray<TResult>;
+  /** Immediate sub-row groups corresponding to `subRowResults`. */
+  subRows: ReadonlyArray<Row<TFeatures, TData>>;
 }
 /** A context-based aggregation definition and optional grouped-result merge. */
 interface AggregationFnDef<TFeatures extends TableFeatures = any, TData extends RowData = any, TValue = unknown, TResult = unknown> {
-  /** Computes a result directly from normalized terminal rows. */
+  /** Computes a result directly from the selected `rows`. */
   aggregate: (context: AggregationContext<TFeatures, TData, TValue>) => TResult;
   /**
-   * Combines already-computed immediate child-group results. When omitted,
-   * nested grouping falls back to `aggregate` over the group's terminal rows.
+   * Combines already-computed immediate sub-row results. When omitted,
+   * nested grouping falls back to `aggregate` over the group's selected rows.
    */
   merge?: (context: AggregationMergeContext<TFeatures, TData, TValue, TResult>) => TResult;
 }
@@ -114,6 +122,12 @@ interface ColumnDef_Aggregation<in out TFeatures extends TableFeatures, in out T
    * result object. Inline definitions in an array require an explicit `id`.
    */
   aggregationFn?: AggregationFnOption<TFeatures, TData, TValue>;
+  /**
+   * Maximum relative sub-row depth used for grouped aggregation and cached
+   * default totals. `0` selects the supplied root rows, `1` their direct
+   * sub-rows, and so on. Defaults to `0`.
+   */
+  maxAggregationDepth?: number;
   /**
    * Optionally supplies a precomputed aggregation value for this column.
    * Return `{ value }` to handle the request, including `{ value: undefined }`;
@@ -127,13 +141,20 @@ interface Column_Aggregation<in out TFeatures extends TableFeatures, in out TDat
   getAggregationFns: () => ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>>;
   /**
    * Aggregates this column over the default pre-grouped row model, or over a
-   * caller-provided array of rows. Explicit rows are normalized to unique
-   * terminal leaves and are intentionally not cached.
+   * caller-provided array of rows. `options.maxDepth` overrides the column's
+   * `maxAggregationDepth`. Explicit-row calls are intentionally not cached.
    */
-  getAggregationValue: <TResult = ColumnAggregationValue<TFeatures>>(rows?: ReadonlyArray<Row<TFeatures, TData>>) => TResult;
+  getAggregationValue: <TResult = ColumnAggregationValue<TFeatures>>(options?: AggregationValueOptions<TFeatures, TData>) => TResult;
   /** Infers `sum` for a numeric first row and `extent` for a Date first row. */
   getAutoAggregationFn: () => AggregationFnDef<TFeatures, TData, any, any> | undefined;
 }
+/** Options for a caller-requested column aggregation value. */
+interface AggregationValueOptions<in out TFeatures extends TableFeatures, in out TData extends RowData> {
+  /** Overrides the column's `maxAggregationDepth` for this request. */
+  maxDepth?: number;
+  /** Rows to aggregate instead of the default pre-grouped row model. */
+  rows?: ReadonlyArray<Row<TFeatures, TData>>;
+}
 /** Cell instance APIs installed by `aggregationFeature`. */
 interface Cell_Aggregation {
   /** Whether this cell displays an aggregate on a synthetic grouped row. */
@@ -148,6 +169,8 @@ interface Row_Aggregation {
 interface AggregationValueContext<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData> {
   /** The column whose value was requested. */
   column: Column<TFeatures, TData, TValue>;
+  /** Maximum relative sub-row depth used for the request. */
+  maxDepth: number;
   /** Caller-provided rows, or `undefined` for the default row model. */
   rows?: ReadonlyArray<Row<TFeatures, TData>>;
   /** The table that owns the column. */
@@ -168,5 +191,5 @@ interface TableOptions_Aggregation {
   manualAggregation?: boolean;
 }
 //#endregion
-export { AggregationContext, AggregationFnDef, AggregationFnDescriptor, AggregationFnListItem, AggregationFnOption, AggregationFnRef, AggregationFns, AggregationMergeContext, AggregationResult, AggregationResultOf, AggregationValueContext, AggregationValueResult, Cell_Aggregation, ColumnAggregationValue, ColumnDef_Aggregation, Column_Aggregation, CustomAggregationFns, ExtractAggregationFnKeys, ResolvedAggregationFn, RowModelFns_Aggregation, Row_Aggregation, TableOptions_Aggregation, constructAggregationFn };
+export { AggregationContext, AggregationFnDef, AggregationFnDescriptor, AggregationFnListItem, AggregationFnOption, AggregationFnRef, AggregationFns, AggregationMergeContext, AggregationResult, AggregationResultOf, AggregationValueContext, AggregationValueOptions, AggregationValueResult, Cell_Aggregation, ColumnAggregationValue, ColumnDef_Aggregation, Column_Aggregation, CustomAggregationFns, ExtractAggregationFnKeys, ResolvedAggregationFn, RowModelFns_Aggregation, Row_Aggregation, TableOptions_Aggregation, constructAggregationFn };
 //# sourceMappingURL=aggregationFeature.types.d.ts.map

package/dist/features/aggregation/aggregationFeature.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"aggregationFeature.types.js","names":[],"sources":["../../../src/features/aggregation/aggregationFeature.types.ts"],"sourcesContent":["import type { BuiltInAggregationFn } from './aggregationFns'\nimport type { Cell } from '../../types/Cell'\nimport type { Column } from '../../types/Column'\nimport type { ColumnDefTemplate } from '../../types/ColumnDef'\nimport type { IsAny, TableFeatures } from '../../types/TableFeatures'\nimport type { Row } from '../../types/Row'\nimport type { Table } from '../../types/Table'\nimport type { CellData, RowData } from '../../types/type-utils'\n\n/** Declaration-merging fallback for named aggregation definitions. */\nexport interface AggregationFns {}\n\n/** Values and table objects available while one aggregation is evaluated. */\nexport interface AggregationContext<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue = unknown,\n> {\n  /** The column whose values are being aggregated. */\n  column: Column<TFeatures, TData, TValue>\n  /** Convenience alias for `column.id`. */\n  columnId: string\n  /** Reads this column's value from one of `rows`. */\n  getValue: (row: Row<TFeatures, TData>) => TValue\n  /**\n   * The synthetic grouped row receiving this result. This property is omitted\n   * for root or caller-supplied-row aggregation. Its `depth` identifies the\n   * grouping level when grouped aggregation needs that distinction.\n   */\n  groupingRow?: Row<TFeatures, TData>\n  /**\n   * Terminal leaf rows included in this aggregation. The executor normalizes\n   * hierarchical and duplicate row inputs before invoking the definition.\n   */\n  rows: ReadonlyArray<Row<TFeatures, TData>>\n  /** The table that owns the column and rows. */\n  table: Table<TFeatures, TData>\n}\n\n/** Additional values available when merging nested grouped results. */\nexport interface AggregationMergeContext<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue,\n  TResult,\n> extends AggregationContext<TFeatures, TData, TValue> {\n  /** Results produced for each immediate child group, in child-row order. */\n  childResults: ReadonlyArray<TResult>\n  /** Immediate child group rows corresponding to `childResults`. */\n  childRows: ReadonlyArray<Row<TFeatures, TData>>\n}\n\n/** A context-based aggregation definition and optional grouped-result merge. */\nexport interface AggregationFnDef<\n  TFeatures extends TableFeatures = any,\n  TData extends RowData = any,\n  TValue = unknown,\n  TResult = unknown,\n> {\n  /** Computes a result directly from normalized terminal rows. */\n  aggregate: (context: AggregationContext<TFeatures, TData, TValue>) => TResult\n  /**\n   * Combines already-computed immediate child-group results. When omitted,\n   * nested grouping falls back to `aggregate` over the group's terminal rows.\n   */\n  merge?: (\n    context: AggregationMergeContext<TFeatures, TData, TValue, TResult>,\n  ) => TResult\n}\n\n/**\n * Creates a typed context-based aggregation definition for a column or\n * aggregation-function registry.\n */\nexport function constructAggregationFn<\n  TFeatures extends TableFeatures = any,\n  TData extends RowData = any,\n  TValue = unknown,\n  TResult = unknown,\n>(\n  definition: AggregationFnDef<TFeatures, TData, TValue, TResult>,\n): AggregationFnDef<TFeatures, TData, TValue, TResult> {\n  return definition\n}\n\n/** Aggregation-definition registry carried by a table feature set. */\nexport interface RowModelFns_Aggregation<\n  in out TFeatures extends TableFeatures,\n  in out TData extends RowData,\n> {\n  aggregationFns: Record<string, AggregationFnDef<TFeatures, TData, any, any>>\n}\n\n/** Named context-based aggregation definitions registered on a feature set. */\nexport type CustomAggregationFns<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n> = Record<string, AggregationFnDef<TFeatures, TData, any, any>>\n\n/** String names available from a feature set's aggregation registry. */\nexport type ExtractAggregationFnKeys<TFeatures extends TableFeatures> =\n  IsAny<TFeatures> extends true\n    ? keyof AggregationFns | BuiltInAggregationFn\n    : TFeatures extends { aggregationFns: infer TAggregationFns extends object }\n      ? Extract<keyof TAggregationFns, string>\n      : keyof AggregationFns\n\n/** A registered name, automatic inference, or inline aggregation definition. */\nexport type AggregationFnRef<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue = unknown,\n  TResult = unknown,\n> =\n  | 'auto'\n  | ExtractAggregationFnKeys<TFeatures>\n  | AggregationFnDef<TFeatures, TData, TValue, TResult>\n\n/** Gives an aggregation reference a stable key in a multiple result. */\nexport interface AggregationFnDescriptor<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue = unknown,\n  TResult = unknown,\n> {\n  /** The named, automatic, or inline definition to execute. */\n  aggregationFn: AggregationFnRef<TFeatures, TData, TValue, TResult>\n  /** Stable key used in the object returned by a multiple aggregation. */\n  id: string\n}\n\n/** One named or explicitly keyed entry in a multiple aggregation option. */\nexport type AggregationFnListItem<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue = unknown,\n> =\n  | 'auto'\n  | ExtractAggregationFnKeys<TFeatures>\n  | AggregationFnDescriptor<TFeatures, TData, TValue, any>\n\n/** A scalar aggregation reference or a list that produces a keyed object. */\nexport type AggregationFnOption<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue = unknown,\n> =\n  | AggregationFnRef<TFeatures, TData, TValue, any>\n  | ReadonlyArray<AggregationFnListItem<TFeatures, TData, TValue>>\n\n/** Extracts the result type produced by an aggregation definition. */\nexport type AggregationResultOf<TDefinition> =\n  TDefinition extends AggregationFnDef<any, any, any, infer TResult>\n    ? TResult\n    : unknown\n\ntype RegisteredAggregationDefinition<\n  TFeatures extends TableFeatures,\n  TKey extends PropertyKey,\n> = TFeatures extends {\n  aggregationFns: infer TRegistry extends Record<PropertyKey, unknown>\n}\n  ? TKey extends keyof TRegistry\n    ? TRegistry[TKey]\n    : never\n  : never\n\ntype AggregationResultOfRef<TRef, TFeatures extends TableFeatures> =\n  TRef extends AggregationFnDef<any, any, any, any>\n    ? AggregationResultOf<TRef>\n    : TRef extends 'auto'\n      ? RegisteredAggregationResult<TFeatures>\n      : TRef extends PropertyKey\n        ? AggregationResultOf<RegisteredAggregationDefinition<TFeatures, TRef>>\n        : unknown\n\ntype AggregationEntryId<TEntry> = TEntry extends string\n  ? TEntry\n  : TEntry extends { id: infer TId extends string }\n    ? TId\n    : never\n\ntype AggregationEntryDefinition<TEntry> = TEntry extends {\n  aggregationFn: infer TDefinition\n}\n  ? TDefinition\n  : TEntry\n\n/** Infers the scalar or keyed result produced by an aggregation option. */\nexport type AggregationResult<TOption, TFeatures extends TableFeatures = any> =\n  TOption extends ReadonlyArray<infer TEntry>\n    ? {\n        [TKey in AggregationEntryId<TEntry>]: AggregationResultOfRef<\n          AggregationEntryDefinition<Extract<TEntry, TKey | { id: TKey }>>,\n          TFeatures\n        >\n      }\n    : AggregationResultOfRef<TOption, TFeatures>\n\ntype RegisteredAggregationResult<TFeatures extends TableFeatures> =\n  TFeatures extends {\n    aggregationFns: infer TRegistry extends Record<string, unknown>\n  }\n    ? AggregationResultOf<TRegistry[keyof TRegistry]>\n    : unknown\n\n/** Default public result union when a column's precise option is not known. */\nexport type ColumnAggregationValue<TFeatures extends TableFeatures> =\n  | RegisteredAggregationResult<TFeatures>\n  | Record<string, RegisteredAggregationResult<TFeatures> | undefined>\n  | undefined\n\n/** A validated aggregation entry returned by `column.getAggregationFns()`. */\nexport interface ResolvedAggregationFn<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n> {\n  /** Resolved definition, or `undefined` when configuration is invalid. */\n  aggregationFn: AggregationFnDef<TFeatures, TData, any, any> | undefined\n  /** Key used for a multiple result; scalar inline definitions have no id. */\n  id: string | undefined\n}\n\n/** Column-definition options installed by `aggregationFeature`. */\nexport interface ColumnDef_Aggregation<\n  in out TFeatures extends TableFeatures,\n  in out TData extends RowData,\n  TValue extends CellData = CellData,\n> {\n  /** Renderer used for a grouped row's aggregated cell. */\n  aggregatedCell?: ColumnDefTemplate<\n    ReturnType<Cell<TFeatures, TData, TValue>['getContext']>\n  >\n  /**\n   * One aggregation reference for a scalar result, or an array for a keyed\n   * result object. Inline definitions in an array require an explicit `id`.\n   */\n  aggregationFn?: AggregationFnOption<TFeatures, TData, TValue>\n  /**\n   * Optionally supplies a precomputed aggregation value for this column.\n   * Return `{ value }` to handle the request, including `{ value: undefined }`;\n   * return `undefined` to use the local aggregation fallback.\n   */\n  getAggregationValue?: (\n    context: AggregationValueContext<TFeatures, TData, TValue>,\n  ) => AggregationValueResult | undefined\n}\n\n/** Column instance APIs installed by `aggregationFeature`. */\nexport interface Column_Aggregation<\n  in out TFeatures extends TableFeatures,\n  in out TData extends RowData,\n> {\n  /** Resolves the configured scalar or multiple aggregation definitions. */\n  getAggregationFns: () => ReadonlyArray<\n    ResolvedAggregationFn<TFeatures, TData>\n  >\n  /**\n   * Aggregates this column over the default pre-grouped row model, or over a\n   * caller-provided array of rows. Explicit rows are normalized to unique\n   * terminal leaves and are intentionally not cached.\n   */\n  getAggregationValue: <TResult = ColumnAggregationValue<TFeatures>>(\n    rows?: ReadonlyArray<Row<TFeatures, TData>>,\n  ) => TResult\n  /** Infers `sum` for a numeric first row and `extent` for a Date first row. */\n  getAutoAggregationFn: () =>\n    | AggregationFnDef<TFeatures, TData, any, any>\n    | undefined\n}\n\n/** Cell instance APIs installed by `aggregationFeature`. */\nexport interface Cell_Aggregation {\n  /** Whether this cell displays an aggregate on a synthetic grouped row. */\n  getIsAggregated: () => boolean\n}\n\n/** Internal per-row cache used while grouped aggregates are evaluated. */\nexport interface Row_Aggregation {\n  /** Cached aggregate results keyed by column id. */\n  _aggregationValuesCache: Record<string, unknown>\n}\n\n/** Values passed to a column-level aggregation-value provider. */\nexport interface AggregationValueContext<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n> {\n  /** The column whose value was requested. */\n  column: Column<TFeatures, TData, TValue>\n  /** Caller-provided rows, or `undefined` for the default row model. */\n  rows?: ReadonlyArray<Row<TFeatures, TData>>\n  /** The table that owns the column. */\n  table: Table<TFeatures, TData>\n}\n\n/** Marks an aggregation-value override as handled. */\nexport interface AggregationValueResult<TResult = unknown> {\n  /** The supplied value. `undefined` is still a handled result. */\n  value: TResult\n}\n\n/** Table options installed by `aggregationFeature`. */\nexport interface TableOptions_Aggregation {\n  /**\n   * Disables local `column.getAggregationValue()` calculation when a column\n   * override does not handle the request. Group values supplied by manually\n   * grouped rows remain the responsibility of the data owner.\n   */\n  manualAggregation?: boolean\n}\n"],"mappings":";;;;;AA0EA,SAAgB,uBAMd,YACqD;CACrD,OAAO;AACT"}
+{"version":3,"file":"aggregationFeature.types.js","names":[],"sources":["../../../src/features/aggregation/aggregationFeature.types.ts"],"sourcesContent":["import type { BuiltInAggregationFn } from './aggregationFns'\nimport type { Cell } from '../../types/Cell'\nimport type { Column } from '../../types/Column'\nimport type { ColumnDefTemplate } from '../../types/ColumnDef'\nimport type { IsAny, TableFeatures } from '../../types/TableFeatures'\nimport type { Row } from '../../types/Row'\nimport type { Table } from '../../types/Table'\nimport type { CellData, RowData } from '../../types/type-utils'\n\n/** Declaration-merging fallback for named aggregation definitions. */\nexport interface AggregationFns {}\n\n/** Values and table objects available while one aggregation is evaluated. */\nexport interface AggregationContext<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue = unknown,\n> {\n  /** The column whose values are being aggregated. */\n  column: Column<TFeatures, TData, TValue>\n  /** Convenience alias for `column.id`. */\n  columnId: string\n  /** Maximum relative sub-row depth used to select `rows`. */\n  maxDepth: number\n  /**\n   * Immediate sub-rows for grouped aggregation. This property is omitted\n   * for root or caller-supplied-row aggregation. At a terminal grouping level\n   * these are the direct data rows; at a nested level they are sub-row groups.\n   */\n  subRows?: ReadonlyArray<Row<TFeatures, TData>>\n  /** Reads this column's value from one of `rows`. */\n  getValue: (row: Row<TFeatures, TData>) => TValue\n  /**\n   * The synthetic grouped row receiving this result. This property is omitted\n   * for root or caller-supplied-row aggregation. Its `depth` identifies the\n   * grouping level when grouped aggregation needs that distinction.\n   */\n  groupingRow?: Row<TFeatures, TData>\n  /**\n   * Unique rows selected at `maxDepth`. Branches that end before `maxDepth`\n   * contribute their deepest available row.\n   */\n  rows: ReadonlyArray<Row<TFeatures, TData>>\n  /** The table that owns the column and rows. */\n  table: Table<TFeatures, TData>\n}\n\n/** Additional values available when merging nested grouped results. */\nexport interface AggregationMergeContext<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue,\n  TResult,\n> extends AggregationContext<TFeatures, TData, TValue> {\n  /** Results produced for each immediate sub-row group, in sub-row order. */\n  subRowResults: ReadonlyArray<TResult>\n  /** Immediate sub-row groups corresponding to `subRowResults`. */\n  subRows: ReadonlyArray<Row<TFeatures, TData>>\n}\n\n/** A context-based aggregation definition and optional grouped-result merge. */\nexport interface AggregationFnDef<\n  TFeatures extends TableFeatures = any,\n  TData extends RowData = any,\n  TValue = unknown,\n  TResult = unknown,\n> {\n  /** Computes a result directly from the selected `rows`. */\n  aggregate: (context: AggregationContext<TFeatures, TData, TValue>) => TResult\n  /**\n   * Combines already-computed immediate sub-row results. When omitted,\n   * nested grouping falls back to `aggregate` over the group's selected rows.\n   */\n  merge?: (\n    context: AggregationMergeContext<TFeatures, TData, TValue, TResult>,\n  ) => TResult\n}\n\n/**\n * Creates a typed context-based aggregation definition for a column or\n * aggregation-function registry.\n */\nexport function constructAggregationFn<\n  TFeatures extends TableFeatures = any,\n  TData extends RowData = any,\n  TValue = unknown,\n  TResult = unknown,\n>(\n  definition: AggregationFnDef<TFeatures, TData, TValue, TResult>,\n): AggregationFnDef<TFeatures, TData, TValue, TResult> {\n  return definition\n}\n\n/** Aggregation-definition registry carried by a table feature set. */\nexport interface RowModelFns_Aggregation<\n  in out TFeatures extends TableFeatures,\n  in out TData extends RowData,\n> {\n  aggregationFns: Record<string, AggregationFnDef<TFeatures, TData, any, any>>\n}\n\n/** Named context-based aggregation definitions registered on a feature set. */\nexport type CustomAggregationFns<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n> = Record<string, AggregationFnDef<TFeatures, TData, any, any>>\n\n/** String names available from a feature set's aggregation registry. */\nexport type ExtractAggregationFnKeys<TFeatures extends TableFeatures> =\n  IsAny<TFeatures> extends true\n    ? keyof AggregationFns | BuiltInAggregationFn\n    : TFeatures extends { aggregationFns: infer TAggregationFns extends object }\n      ? Extract<keyof TAggregationFns, string>\n      : keyof AggregationFns\n\n/** A registered name, automatic inference, or inline aggregation definition. */\nexport type AggregationFnRef<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue = unknown,\n  TResult = unknown,\n> =\n  | 'auto'\n  | ExtractAggregationFnKeys<TFeatures>\n  | AggregationFnDef<TFeatures, TData, TValue, TResult>\n\n/** Gives an aggregation reference a stable key in a multiple result. */\nexport interface AggregationFnDescriptor<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue = unknown,\n  TResult = unknown,\n> {\n  /** The named, automatic, or inline definition to execute. */\n  aggregationFn: AggregationFnRef<TFeatures, TData, TValue, TResult>\n  /** Stable key used in the object returned by a multiple aggregation. */\n  id: string\n}\n\n/** One named or explicitly keyed entry in a multiple aggregation option. */\nexport type AggregationFnListItem<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue = unknown,\n> =\n  | 'auto'\n  | ExtractAggregationFnKeys<TFeatures>\n  | AggregationFnDescriptor<TFeatures, TData, TValue, any>\n\n/** A scalar aggregation reference or a list that produces a keyed object. */\nexport type AggregationFnOption<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue = unknown,\n> =\n  | AggregationFnRef<TFeatures, TData, TValue, any>\n  | ReadonlyArray<AggregationFnListItem<TFeatures, TData, TValue>>\n\n/** Extracts the result type produced by an aggregation definition. */\nexport type AggregationResultOf<TDefinition> =\n  TDefinition extends AggregationFnDef<any, any, any, infer TResult>\n    ? TResult\n    : unknown\n\ntype RegisteredAggregationDefinition<\n  TFeatures extends TableFeatures,\n  TKey extends PropertyKey,\n> = TFeatures extends {\n  aggregationFns: infer TRegistry extends Record<PropertyKey, unknown>\n}\n  ? TKey extends keyof TRegistry\n    ? TRegistry[TKey]\n    : never\n  : never\n\ntype AggregationResultOfRef<TRef, TFeatures extends TableFeatures> =\n  TRef extends AggregationFnDef<any, any, any, any>\n    ? AggregationResultOf<TRef>\n    : TRef extends 'auto'\n      ? RegisteredAggregationResult<TFeatures>\n      : TRef extends PropertyKey\n        ? AggregationResultOf<RegisteredAggregationDefinition<TFeatures, TRef>>\n        : unknown\n\ntype AggregationEntryId<TEntry> = TEntry extends string\n  ? TEntry\n  : TEntry extends { id: infer TId extends string }\n    ? TId\n    : never\n\ntype AggregationEntryDefinition<TEntry> = TEntry extends {\n  aggregationFn: infer TDefinition\n}\n  ? TDefinition\n  : TEntry\n\n/** Infers the scalar or keyed result produced by an aggregation option. */\nexport type AggregationResult<TOption, TFeatures extends TableFeatures = any> =\n  TOption extends ReadonlyArray<infer TEntry>\n    ? {\n        [TKey in AggregationEntryId<TEntry>]: AggregationResultOfRef<\n          AggregationEntryDefinition<Extract<TEntry, TKey | { id: TKey }>>,\n          TFeatures\n        >\n      }\n    : AggregationResultOfRef<TOption, TFeatures>\n\ntype RegisteredAggregationResult<TFeatures extends TableFeatures> =\n  TFeatures extends {\n    aggregationFns: infer TRegistry extends Record<string, unknown>\n  }\n    ? AggregationResultOf<TRegistry[keyof TRegistry]>\n    : unknown\n\n/** Default public result union when a column's precise option is not known. */\nexport type ColumnAggregationValue<TFeatures extends TableFeatures> =\n  | RegisteredAggregationResult<TFeatures>\n  | Record<string, RegisteredAggregationResult<TFeatures> | undefined>\n  | undefined\n\n/** A validated aggregation entry returned by `column.getAggregationFns()`. */\nexport interface ResolvedAggregationFn<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n> {\n  /** Resolved definition, or `undefined` when configuration is invalid. */\n  aggregationFn: AggregationFnDef<TFeatures, TData, any, any> | undefined\n  /** Key used for a multiple result; scalar inline definitions have no id. */\n  id: string | undefined\n}\n\n/** Column-definition options installed by `aggregationFeature`. */\nexport interface ColumnDef_Aggregation<\n  in out TFeatures extends TableFeatures,\n  in out TData extends RowData,\n  TValue extends CellData = CellData,\n> {\n  /** Renderer used for a grouped row's aggregated cell. */\n  aggregatedCell?: ColumnDefTemplate<\n    ReturnType<Cell<TFeatures, TData, TValue>['getContext']>\n  >\n  /**\n   * One aggregation reference for a scalar result, or an array for a keyed\n   * result object. Inline definitions in an array require an explicit `id`.\n   */\n  aggregationFn?: AggregationFnOption<TFeatures, TData, TValue>\n  /**\n   * Maximum relative sub-row depth used for grouped aggregation and cached\n   * default totals. `0` selects the supplied root rows, `1` their direct\n   * sub-rows, and so on. Defaults to `0`.\n   */\n  maxAggregationDepth?: number\n  /**\n   * Optionally supplies a precomputed aggregation value for this column.\n   * Return `{ value }` to handle the request, including `{ value: undefined }`;\n   * return `undefined` to use the local aggregation fallback.\n   */\n  getAggregationValue?: (\n    context: AggregationValueContext<TFeatures, TData, TValue>,\n  ) => AggregationValueResult | undefined\n}\n\n/** Column instance APIs installed by `aggregationFeature`. */\nexport interface Column_Aggregation<\n  in out TFeatures extends TableFeatures,\n  in out TData extends RowData,\n> {\n  /** Resolves the configured scalar or multiple aggregation definitions. */\n  getAggregationFns: () => ReadonlyArray<\n    ResolvedAggregationFn<TFeatures, TData>\n  >\n  /**\n   * Aggregates this column over the default pre-grouped row model, or over a\n   * caller-provided array of rows. `options.maxDepth` overrides the column's\n   * `maxAggregationDepth`. Explicit-row calls are intentionally not cached.\n   */\n  getAggregationValue: <TResult = ColumnAggregationValue<TFeatures>>(\n    options?: AggregationValueOptions<TFeatures, TData>,\n  ) => TResult\n  /** Infers `sum` for a numeric first row and `extent` for a Date first row. */\n  getAutoAggregationFn: () =>\n    | AggregationFnDef<TFeatures, TData, any, any>\n    | undefined\n}\n\n/** Options for a caller-requested column aggregation value. */\nexport interface AggregationValueOptions<\n  in out TFeatures extends TableFeatures,\n  in out TData extends RowData,\n> {\n  /** Overrides the column's `maxAggregationDepth` for this request. */\n  maxDepth?: number\n  /** Rows to aggregate instead of the default pre-grouped row model. */\n  rows?: ReadonlyArray<Row<TFeatures, TData>>\n}\n\n/** Cell instance APIs installed by `aggregationFeature`. */\nexport interface Cell_Aggregation {\n  /** Whether this cell displays an aggregate on a synthetic grouped row. */\n  getIsAggregated: () => boolean\n}\n\n/** Internal per-row cache used while grouped aggregates are evaluated. */\nexport interface Row_Aggregation {\n  /** Cached aggregate results keyed by column id. */\n  _aggregationValuesCache: Record<string, unknown>\n}\n\n/** Values passed to a column-level aggregation-value provider. */\nexport interface AggregationValueContext<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n> {\n  /** The column whose value was requested. */\n  column: Column<TFeatures, TData, TValue>\n  /** Maximum relative sub-row depth used for the request. */\n  maxDepth: number\n  /** Caller-provided rows, or `undefined` for the default row model. */\n  rows?: ReadonlyArray<Row<TFeatures, TData>>\n  /** The table that owns the column. */\n  table: Table<TFeatures, TData>\n}\n\n/** Marks an aggregation-value override as handled. */\nexport interface AggregationValueResult<TResult = unknown> {\n  /** The supplied value. `undefined` is still a handled result. */\n  value: TResult\n}\n\n/** Table options installed by `aggregationFeature`. */\nexport interface TableOptions_Aggregation {\n  /**\n   * Disables local `column.getAggregationValue()` calculation when a column\n   * override does not handle the request. Group values supplied by manually\n   * grouped rows remain the responsibility of the data owner.\n   */\n  manualAggregation?: boolean\n}\n"],"mappings":";;;;;AAkFA,SAAgB,uBAMd,YACqD;CACrD,OAAO;AACT"}

package/dist/features/aggregation/aggregationFeature.utils.cjs

@@ -10,16 +10,20 @@ function isAggregationFnDescriptor(value) {
 function warn(message) {
 	if (process.env.NODE_ENV === "development") console.warn(message);
 }
+function resolveMaxAggregationDepth(maxDepth) {
+	return maxDepth === void 0 || Number.isNaN(maxDepth) ? 0 : Math.max(0, Math.floor(maxDepth));
+}
 /**
-* Flattens hierarchical row inputs to unique terminal leaves in encounter
-* order. This is the normalization used by public aggregation-value calls.
+* Selects unique rows at a maximum relative depth in encounter order.
+* Branches that end before the requested depth contribute their deepest row.
 */
-function normalizeAggregationRows(rows) {
+function normalizeAggregationRows(rows, maxDepth = 0) {
 	const result = [];
 	const seen = /* @__PURE__ */ new Set();
-	const visit = (row) => {
-		if (row.subRows.length) {
-			for (let i = 0; i < row.subRows.length; i++) visit(row.subRows[i]);
+	const normalizedMaxDepth = resolveMaxAggregationDepth(maxDepth);
+	const visit = (row, depth) => {
+		if (row.subRows.length && depth < normalizedMaxDepth) {
+			for (let i = 0; i < row.subRows.length; i++) visit(row.subRows[i], depth + 1);
 			return;
 		}
 		if (!seen.has(row.id)) {
@@ -27,7 +31,7 @@ function normalizeAggregationRows(rows) {
 			result.push(row);
 		}
 	};
-	for (let i = 0; i < rows.length; i++) visit(rows[i]);
+	for (let i = 0; i < rows.length; i++) visit(rows[i], 0);
 	return result;
 }
 function getAutoAggregationFnName(value) {
@@ -105,33 +109,37 @@ function column_getAggregationFns(column) {
 	}
 	return finish(resolved);
 }
-function getChildResult(childValue, isMultiple, id) {
-	if (!isMultiple) return childValue;
-	if (!id || !childValue || typeof childValue !== "object") return void 0;
-	return require_utils.hasOwn(childValue, id) ? childValue[id] : void 0;
+function getSubRowResult(subRowValue, isMultiple, id) {
+	if (!isMultiple) return subRowValue;
+	if (!id || !subRowValue || typeof subRowValue !== "object") return void 0;
+	return require_utils.hasOwn(subRowValue, id) ? subRowValue[id] : void 0;
 }
-/** Executes every configured aggregation for a column over normalized rows. */
+/** Executes every configured aggregation over a depth-selected row frontier. */
 function aggregateColumnValue(args) {
-	const { childRows, column, groupingRow, rows } = args;
+	const { subRows, column, groupingRow, rows } = args;
 	const internalColumn = column;
+	const maxDepth = resolveMaxAggregationDepth(args.maxDepth ?? internalColumn.columnDef.maxAggregationDepth);
+	const aggregationRows = normalizeAggregationRows(rows, maxDepth);
 	const entries = column_getAggregationFns(internalColumn);
 	const isMultiple = Array.isArray(internalColumn.columnDef.aggregationFn);
-	const canMerge = !!childRows?.length && childRows.every((row) => !!row.groupingColumnId && row.groupingColumnId !== column.id);
+	const canMerge = !!subRows?.length && subRows.every((row) => !!row.groupingColumnId && row.groupingColumnId !== column.id);
 	const execute = (entry) => {
 		const definition = entry.aggregationFn;
 		if (!definition) return void 0;
 		const context = {
+			...subRows ? { subRows } : {},
 			column,
 			columnId: column.id,
 			getValue: (row) => row.getValue(column.id),
 			...groupingRow ? { groupingRow } : {},
-			rows,
+			maxDepth,
+			rows: aggregationRows,
 			table: column.table
 		};
 		if (canMerge && definition.merge) return definition.merge({
 			...context,
-			childResults: childRows.map((row) => getChildResult(row.getValue(column.id), isMultiple, entry.id)),
-			childRows
+			subRowResults: subRows.map((row) => getSubRowResult(row.getValue(column.id), isMultiple, entry.id)),
+			subRows
 		});
 		return definition.aggregate(context);
 	};
@@ -143,10 +151,13 @@ function aggregateColumnValue(args) {
 	}
 	return result;
 }
-/** Implements `column.getAggregationValue(rows?)` and its default-value cache. */
-function column_getAggregationValue(column, rows) {
+/** Implements `column.getAggregationValue(options?)` and its default cache. */
+function column_getAggregationValue(column, options) {
+	const rows = options?.rows;
+	const resolvedMaxDepth = resolveMaxAggregationDepth(options?.maxDepth ?? column.columnDef.maxAggregationDepth);
 	const providedResult = column.columnDef.getAggregationValue?.({
 		column,
+		maxDepth: resolvedMaxDepth,
 		rows,
 		table: column.table
 	});
@@ -154,20 +165,23 @@ function column_getAggregationValue(column, rows) {
 	if (column.table.options.manualAggregation) return void 0;
 	if (rows !== void 0) return aggregateColumnValue({
 		column,
-		rows: normalizeAggregationRows(rows)
+		maxDepth: resolvedMaxDepth,
+		rows
 	});
 	const model = column.table.getPreGroupedRowModel();
 	const previous = column._aggregationValueCache;
 	const registry = column.table._rowModelFns.aggregationFns;
 	const aggregationFnOption = column.columnDef.aggregationFn;
-	if (previous && previous.dependency === model && previous.registry === registry && previous.aggregationFnOption === aggregationFnOption) return previous.value;
+	if (previous && previous.dependency === model && previous.maxDepth === resolvedMaxDepth && previous.registry === registry && previous.aggregationFnOption === aggregationFnOption) return previous.value;
 	const value = aggregateColumnValue({
 		column,
-		rows: normalizeAggregationRows(model.rows)
+		maxDepth: resolvedMaxDepth,
+		rows: model.rows
 	});
 	column._aggregationValueCache = {
 		aggregationFnOption,
 		dependency: model,
+		maxDepth: resolvedMaxDepth,
 		registry,
 		value
 	};

package/dist/features/aggregation/aggregationFeature.utils.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"aggregationFeature.utils.cjs","names":["makeObjectMap","hasOwn"],"sources":["../../../src/features/aggregation/aggregationFeature.utils.ts"],"sourcesContent":["import { hasOwn, makeObjectMap } from '../../utils'\nimport type { Cell } from '../../types/Cell'\nimport type { Column, Column_Internal } from '../../types/Column'\nimport type { Row } from '../../types/Row'\nimport type { TableFeatures } from '../../types/TableFeatures'\nimport type { CellData, RowData } from '../../types/type-utils'\nimport type {\n  AggregationFnDef,\n  AggregationFnDescriptor,\n  AggregationFnRef,\n  ColumnAggregationValue,\n  ResolvedAggregationFn,\n} from './aggregationFeature.types'\n\ninterface AggregationCacheEntry {\n  aggregationFnOption: unknown\n  dependency: unknown\n  registry: unknown\n  value: unknown\n}\n\ninterface ResolvedAggregationFnsCacheEntry<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n> {\n  coreRowModel: unknown\n  option: unknown\n  registry: unknown\n  value: ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>>\n}\n\nfunction isAggregationFnDef(value: unknown): value is AggregationFnDef {\n  return !!value && typeof value === 'object' && 'aggregate' in value\n}\n\nfunction isAggregationFnDescriptor(\n  value: unknown,\n): value is AggregationFnDescriptor<any, any> {\n  return (\n    !!value &&\n    typeof value === 'object' &&\n    'id' in value &&\n    'aggregationFn' in value\n  )\n}\n\nfunction warn(message: string) {\n  if (process.env.NODE_ENV === 'development') {\n    console.warn(message)\n  }\n}\n\n/**\n * Flattens hierarchical row inputs to unique terminal leaves in encounter\n * order. This is the normalization used by public aggregation-value calls.\n */\nexport function normalizeAggregationRows<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(rows: ReadonlyArray<Row<TFeatures, TData>>): Array<Row<TFeatures, TData>> {\n  const result: Array<Row<TFeatures, TData>> = []\n  const seen = new Set<string>()\n\n  const visit = (row: Row<TFeatures, TData>) => {\n    if (row.subRows.length) {\n      for (let i = 0; i < row.subRows.length; i++) {\n        visit(row.subRows[i]!)\n      }\n      return\n    }\n\n    if (!seen.has(row.id)) {\n      seen.add(row.id)\n      result.push(row)\n    }\n  }\n\n  for (let i = 0; i < rows.length; i++) {\n    visit(rows[i]!)\n  }\n\n  return result\n}\n\nfunction getAutoAggregationFnName(\n  value: unknown,\n): 'extent' | 'sum' | undefined {\n  if (typeof value === 'number') {\n    return 'sum'\n  }\n\n  if (value instanceof Date && !Number.isNaN(value.getTime())) {\n    return 'extent'\n  }\n\n  return undefined\n}\n\n/** Resolves the `sum` or `extent` definition inferred from the first core row. */\nexport function column_getAutoAggregationFn<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(column: Column_Internal<TFeatures, TData, TValue>) {\n  const value = column.table.getCoreRowModel().flatRows[0]?.getValue(column.id)\n\n  const name = getAutoAggregationFnName(value)\n  if (!name) return undefined\n\n  const aggregationFn = column.table._rowModelFns.aggregationFns?.[name]\n\n  if (!aggregationFn) {\n    warn(\n      `aggregationFn '${name}' (auto) for column '${column.id}' is not registered`,\n    )\n  }\n\n  return aggregationFn\n}\n\nfunction resolveAggregationFn<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(\n  column: Column_Internal<TFeatures, TData, any>,\n  ref: AggregationFnRef<TFeatures, TData, any, any>,\n): AggregationFnDef<TFeatures, TData, any, any> | undefined {\n  if (isAggregationFnDef(ref)) return ref as any\n  if (ref === 'auto') return column_getAutoAggregationFn(column)\n\n  const aggregationFn =\n    column.table._rowModelFns.aggregationFns?.[ref as string]\n  if (!aggregationFn) {\n    warn(\n      `aggregationFn '${String(ref)}' for column '${column.id}' is not registered`,\n    )\n  }\n  return aggregationFn\n}\n\n/** Resolves and validates a column's scalar or multiple aggregation option. */\nexport function column_getAggregationFns<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(\n  column: Column_Internal<TFeatures, TData, TValue>,\n): ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>> {\n  const option = column.columnDef.aggregationFn\n  const registry = column.table._rowModelFns.aggregationFns\n  const coreRowModel = column.table.getCoreRowModel()\n  const previous = (column as any)._resolvedAggregationFnsCache as\n    | ResolvedAggregationFnsCacheEntry<TFeatures, TData>\n    | undefined\n\n  if (\n    previous &&\n    previous.option === option &&\n    previous.registry === registry &&\n    previous.coreRowModel === coreRowModel\n  ) {\n    return previous.value\n  }\n\n  const finish = (\n    value: ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>>,\n  ) => {\n    ;(column as any)._resolvedAggregationFnsCache = {\n      coreRowModel,\n      option,\n      registry,\n      value,\n    } satisfies ResolvedAggregationFnsCacheEntry<TFeatures, TData>\n    return value\n  }\n\n  if (option == null) return finish([])\n\n  if (!Array.isArray(option)) {\n    return finish([\n      {\n        aggregationFn: resolveAggregationFn(column, option as any),\n        id: typeof option === 'string' ? option : undefined,\n      },\n    ])\n  }\n\n  const ids = makeObjectMap<number>()\n  for (let i = 0; i < option.length; i++) {\n    const item = option[i]\n    const id =\n      typeof item === 'string'\n        ? item\n        : isAggregationFnDescriptor(item)\n          ? item.id\n          : undefined\n    if (id !== undefined) ids[id] = (ids[id] ?? 0) + 1\n  }\n\n  const resolved: Array<ResolvedAggregationFn<TFeatures, TData>> = []\n\n  for (let i = 0; i < option.length; i++) {\n    const item = option[i]\n    const id =\n      typeof item === 'string'\n        ? item\n        : isAggregationFnDescriptor(item)\n          ? item.id\n          : undefined\n\n    if (id === undefined) {\n      warn(\n        `aggregationFn at index ${i} for column '${column.id}' needs a stable id`,\n      )\n      resolved.push({ aggregationFn: undefined, id: undefined })\n      continue\n    }\n\n    if (ids[id]! > 1) {\n      warn(`aggregationFn id '${id}' for column '${column.id}' is duplicated`)\n      resolved.push({ aggregationFn: undefined, id })\n      continue\n    }\n\n    const ref = isAggregationFnDescriptor(item) ? item.aggregationFn : item\n    resolved.push({\n      aggregationFn: resolveAggregationFn(column, ref),\n      id,\n    })\n  }\n\n  return finish(resolved)\n}\n\nfunction getChildResult(\n  childValue: unknown,\n  isMultiple: boolean,\n  id: string | undefined,\n) {\n  if (!isMultiple) return childValue\n  if (!id || !childValue || typeof childValue !== 'object') return undefined\n  return hasOwn(childValue, id)\n    ? (childValue as Record<string, unknown>)[id]\n    : undefined\n}\n\n/** Executes every configured aggregation for a column over normalized rows. */\nexport function aggregateColumnValue<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(args: {\n  childRows?: ReadonlyArray<Row<TFeatures, TData>>\n  column: Column<TFeatures, TData, unknown>\n  groupingRow?: Row<TFeatures, TData>\n  rows: ReadonlyArray<Row<TFeatures, TData>>\n}): unknown {\n  const { childRows, column, groupingRow, rows } = args\n  const internalColumn = column as Column_Internal<TFeatures, TData, unknown>\n  const entries = column_getAggregationFns(internalColumn)\n  const isMultiple = Array.isArray(internalColumn.columnDef.aggregationFn)\n  const canMerge =\n    !!childRows?.length &&\n    childRows.every(\n      (row) =>\n        !!(row as any).groupingColumnId &&\n        (row as any).groupingColumnId !== column.id,\n    )\n\n  const execute = (entry: ResolvedAggregationFn<TFeatures, TData>) => {\n    const definition = entry.aggregationFn\n    if (!definition) return undefined\n\n    const context = {\n      column,\n      columnId: column.id,\n      getValue: (row: Row<TFeatures, TData>) => row.getValue(column.id),\n      ...(groupingRow ? { groupingRow } : {}),\n      rows,\n      table: column.table as any,\n    }\n\n    if (canMerge && definition.merge) {\n      return definition.merge({\n        ...context,\n        childResults: childRows.map((row) =>\n          getChildResult(row.getValue(column.id), isMultiple, entry.id),\n        ),\n        childRows: childRows,\n      })\n    }\n\n    return definition.aggregate(context)\n  }\n\n  if (!isMultiple) {\n    return entries[0] ? execute(entries[0]) : undefined\n  }\n\n  const result = makeObjectMap<unknown>()\n  for (let i = 0; i < entries.length; i++) {\n    const entry = entries[i]!\n    if (entry.id !== undefined) {\n      result[entry.id] = execute(entry)\n    }\n  }\n  return result\n}\n\n/** Implements `column.getAggregationValue(rows?)` and its default-value cache. */\nexport function column_getAggregationValue<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(\n  column: Column_Internal<TFeatures, TData, TValue>,\n  rows?: ReadonlyArray<Row<TFeatures, TData>>,\n): ColumnAggregationValue<TFeatures> {\n  const providedResult = column.columnDef.getAggregationValue?.({\n    column: column as any,\n    rows,\n    table: column.table as any,\n  })\n\n  if (providedResult) return providedResult.value as any\n  if (column.table.options.manualAggregation) return undefined\n\n  if (rows !== undefined) {\n    return aggregateColumnValue({\n      column: column as any,\n      rows: normalizeAggregationRows(rows),\n    }) as any\n  }\n\n  const model = column.table.getPreGroupedRowModel()\n  const previous = (column as any)._aggregationValueCache as\n    | AggregationCacheEntry\n    | undefined\n  const registry = column.table._rowModelFns.aggregationFns\n  const aggregationFnOption = column.columnDef.aggregationFn\n\n  if (\n    previous &&\n    previous.dependency === model &&\n    previous.registry === registry &&\n    previous.aggregationFnOption === aggregationFnOption\n  ) {\n    return previous.value as any\n  }\n\n  const value = aggregateColumnValue({\n    column: column as any,\n    rows: normalizeAggregationRows(model.rows),\n  })\n  ;(column as any)._aggregationValueCache = {\n    aggregationFnOption,\n    dependency: model,\n    registry,\n    value,\n  } satisfies AggregationCacheEntry\n  return value as any\n}\n\n/** Implements `cell.getIsAggregated()` for synthetic grouped rows. */\nexport function cell_getIsAggregated<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(cell: Cell<TFeatures, TData, TValue>) {\n  const groupingColumnId = (cell.row as any).groupingColumnId as\n    | string\n    | undefined\n  if (!groupingColumnId || groupingColumnId === cell.column.id) return false\n\n  const grouping = (cell.column.table as any).atoms.grouping?.get?.() as\n    | Array<string>\n    | undefined\n  if (grouping?.includes(cell.column.id)) return false\n\n  return column_getAggregationFns(cell.column as any).some(\n    (entry) => !!entry.aggregationFn,\n  )\n}\n\n/** Formats the default scalar or keyed aggregated-cell representation. */\nexport function formatAggregatedCellValue(\n  value: unknown,\n  option: unknown,\n): string | null {\n  if (value == null) return null\n\n  if (Array.isArray(option) && typeof value === 'object') {\n    const entries = Object.keys(value)\n    return entries\n      .map(\n        (key) => `${key}: ${String((value as Record<string, unknown>)[key])}`,\n      )\n      .join(', ')\n  }\n\n  return String(value)\n}\n"],"mappings":"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"}
+{"version":3,"file":"aggregationFeature.utils.cjs","names":["makeObjectMap","hasOwn"],"sources":["../../../src/features/aggregation/aggregationFeature.utils.ts"],"sourcesContent":["import { hasOwn, makeObjectMap } from '../../utils'\nimport type { Cell } from '../../types/Cell'\nimport type { Column, Column_Internal } from '../../types/Column'\nimport type { Row } from '../../types/Row'\nimport type { TableFeatures } from '../../types/TableFeatures'\nimport type { CellData, RowData } from '../../types/type-utils'\nimport type {\n  AggregationContext,\n  AggregationFnDef,\n  AggregationFnDescriptor,\n  AggregationFnRef,\n  AggregationValueOptions,\n  ColumnAggregationValue,\n  ResolvedAggregationFn,\n} from './aggregationFeature.types'\n\ninterface AggregationCacheEntry {\n  aggregationFnOption: unknown\n  dependency: unknown\n  maxDepth: number\n  registry: unknown\n  value: unknown\n}\n\ninterface ResolvedAggregationFnsCacheEntry<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n> {\n  coreRowModel: unknown\n  option: unknown\n  registry: unknown\n  value: ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>>\n}\n\nfunction isAggregationFnDef(value: unknown): value is AggregationFnDef {\n  return !!value && typeof value === 'object' && 'aggregate' in value\n}\n\nfunction isAggregationFnDescriptor(\n  value: unknown,\n): value is AggregationFnDescriptor<any, any> {\n  return (\n    !!value &&\n    typeof value === 'object' &&\n    'id' in value &&\n    'aggregationFn' in value\n  )\n}\n\nfunction warn(message: string) {\n  if (process.env.NODE_ENV === 'development') {\n    console.warn(message)\n  }\n}\n\nfunction resolveMaxAggregationDepth(maxDepth: number | undefined) {\n  return maxDepth === undefined || Number.isNaN(maxDepth)\n    ? 0\n    : Math.max(0, Math.floor(maxDepth))\n}\n\n/**\n * Selects unique rows at a maximum relative depth in encounter order.\n * Branches that end before the requested depth contribute their deepest row.\n */\nexport function normalizeAggregationRows<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(\n  rows: ReadonlyArray<Row<TFeatures, TData>>,\n  maxDepth = 0,\n): Array<Row<TFeatures, TData>> {\n  const result: Array<Row<TFeatures, TData>> = []\n  const seen = new Set<string>()\n  const normalizedMaxDepth = resolveMaxAggregationDepth(maxDepth)\n\n  const visit = (row: Row<TFeatures, TData>, depth: number) => {\n    if (row.subRows.length && depth < normalizedMaxDepth) {\n      for (let i = 0; i < row.subRows.length; i++) {\n        visit(row.subRows[i]!, depth + 1)\n      }\n      return\n    }\n\n    if (!seen.has(row.id)) {\n      seen.add(row.id)\n      result.push(row)\n    }\n  }\n\n  for (let i = 0; i < rows.length; i++) {\n    visit(rows[i]!, 0)\n  }\n\n  return result\n}\n\nfunction getAutoAggregationFnName(\n  value: unknown,\n): 'extent' | 'sum' | undefined {\n  if (typeof value === 'number') {\n    return 'sum'\n  }\n\n  if (value instanceof Date && !Number.isNaN(value.getTime())) {\n    return 'extent'\n  }\n\n  return undefined\n}\n\n/** Resolves the `sum` or `extent` definition inferred from the first core row. */\nexport function column_getAutoAggregationFn<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(column: Column_Internal<TFeatures, TData, TValue>) {\n  const value = column.table.getCoreRowModel().flatRows[0]?.getValue(column.id)\n\n  const name = getAutoAggregationFnName(value)\n  if (!name) return undefined\n\n  const aggregationFn = column.table._rowModelFns.aggregationFns?.[name]\n\n  if (!aggregationFn) {\n    warn(\n      `aggregationFn '${name}' (auto) for column '${column.id}' is not registered`,\n    )\n  }\n\n  return aggregationFn\n}\n\nfunction resolveAggregationFn<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(\n  column: Column_Internal<TFeatures, TData, any>,\n  ref: AggregationFnRef<TFeatures, TData, any, any>,\n): AggregationFnDef<TFeatures, TData, any, any> | undefined {\n  if (isAggregationFnDef(ref)) return ref as any\n  if (ref === 'auto') return column_getAutoAggregationFn(column)\n\n  const aggregationFn =\n    column.table._rowModelFns.aggregationFns?.[ref as string]\n  if (!aggregationFn) {\n    warn(\n      `aggregationFn '${String(ref)}' for column '${column.id}' is not registered`,\n    )\n  }\n  return aggregationFn\n}\n\n/** Resolves and validates a column's scalar or multiple aggregation option. */\nexport function column_getAggregationFns<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(\n  column: Column_Internal<TFeatures, TData, TValue>,\n): ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>> {\n  const option = column.columnDef.aggregationFn\n  const registry = column.table._rowModelFns.aggregationFns\n  const coreRowModel = column.table.getCoreRowModel()\n  const previous = (column as any)._resolvedAggregationFnsCache as\n    | ResolvedAggregationFnsCacheEntry<TFeatures, TData>\n    | undefined\n\n  if (\n    previous &&\n    previous.option === option &&\n    previous.registry === registry &&\n    previous.coreRowModel === coreRowModel\n  ) {\n    return previous.value\n  }\n\n  const finish = (\n    value: ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>>,\n  ) => {\n    ;(column as any)._resolvedAggregationFnsCache = {\n      coreRowModel,\n      option,\n      registry,\n      value,\n    } satisfies ResolvedAggregationFnsCacheEntry<TFeatures, TData>\n    return value\n  }\n\n  if (option == null) return finish([])\n\n  if (!Array.isArray(option)) {\n    return finish([\n      {\n        aggregationFn: resolveAggregationFn(column, option as any),\n        id: typeof option === 'string' ? option : undefined,\n      },\n    ])\n  }\n\n  const ids = makeObjectMap<number>()\n  for (let i = 0; i < option.length; i++) {\n    const item = option[i]\n    const id =\n      typeof item === 'string'\n        ? item\n        : isAggregationFnDescriptor(item)\n          ? item.id\n          : undefined\n    if (id !== undefined) ids[id] = (ids[id] ?? 0) + 1\n  }\n\n  const resolved: Array<ResolvedAggregationFn<TFeatures, TData>> = []\n\n  for (let i = 0; i < option.length; i++) {\n    const item = option[i]\n    const id =\n      typeof item === 'string'\n        ? item\n        : isAggregationFnDescriptor(item)\n          ? item.id\n          : undefined\n\n    if (id === undefined) {\n      warn(\n        `aggregationFn at index ${i} for column '${column.id}' needs a stable id`,\n      )\n      resolved.push({ aggregationFn: undefined, id: undefined })\n      continue\n    }\n\n    if (ids[id]! > 1) {\n      warn(`aggregationFn id '${id}' for column '${column.id}' is duplicated`)\n      resolved.push({ aggregationFn: undefined, id })\n      continue\n    }\n\n    const ref = isAggregationFnDescriptor(item) ? item.aggregationFn : item\n    resolved.push({\n      aggregationFn: resolveAggregationFn(column, ref),\n      id,\n    })\n  }\n\n  return finish(resolved)\n}\n\nfunction getSubRowResult(\n  subRowValue: unknown,\n  isMultiple: boolean,\n  id: string | undefined,\n) {\n  if (!isMultiple) return subRowValue\n  if (!id || !subRowValue || typeof subRowValue !== 'object') return undefined\n  return hasOwn(subRowValue, id)\n    ? (subRowValue as Record<string, unknown>)[id]\n    : undefined\n}\n\n/** Executes every configured aggregation over a depth-selected row frontier. */\nexport function aggregateColumnValue<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(args: {\n  maxDepth?: number\n  subRows?: ReadonlyArray<Row<TFeatures, TData>>\n  column: Column<TFeatures, TData, unknown>\n  groupingRow?: Row<TFeatures, TData>\n  rows: ReadonlyArray<Row<TFeatures, TData>>\n}): unknown {\n  const { subRows, column, groupingRow, rows } = args\n  const internalColumn = column as Column_Internal<TFeatures, TData, unknown>\n  const maxDepth = resolveMaxAggregationDepth(\n    args.maxDepth ?? internalColumn.columnDef.maxAggregationDepth,\n  )\n  const aggregationRows = normalizeAggregationRows(rows, maxDepth)\n  const entries = column_getAggregationFns(internalColumn)\n  const isMultiple = Array.isArray(internalColumn.columnDef.aggregationFn)\n  const canMerge =\n    !!subRows?.length &&\n    subRows.every(\n      (row) =>\n        !!(row as any).groupingColumnId &&\n        (row as any).groupingColumnId !== column.id,\n    )\n\n  const execute = (entry: ResolvedAggregationFn<TFeatures, TData>) => {\n    const definition = entry.aggregationFn\n    if (!definition) return undefined\n\n    const context: AggregationContext<TFeatures, TData, unknown> = {\n      ...(subRows ? { subRows } : {}),\n      column,\n      columnId: column.id,\n      getValue: (row: Row<TFeatures, TData>) => row.getValue(column.id),\n      ...(groupingRow ? { groupingRow } : {}),\n      maxDepth,\n      rows: aggregationRows,\n      table: column.table as any,\n    }\n\n    if (canMerge && definition.merge) {\n      return definition.merge({\n        ...context,\n        subRowResults: subRows.map((row) =>\n          getSubRowResult(row.getValue(column.id), isMultiple, entry.id),\n        ),\n        subRows,\n      })\n    }\n\n    return definition.aggregate(context)\n  }\n\n  if (!isMultiple) {\n    return entries[0] ? execute(entries[0]) : undefined\n  }\n\n  const result = makeObjectMap<unknown>()\n  for (let i = 0; i < entries.length; i++) {\n    const entry = entries[i]!\n    if (entry.id !== undefined) {\n      result[entry.id] = execute(entry)\n    }\n  }\n  return result\n}\n\n/** Implements `column.getAggregationValue(options?)` and its default cache. */\nexport function column_getAggregationValue<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(\n  column: Column_Internal<TFeatures, TData, TValue>,\n  options?: AggregationValueOptions<TFeatures, TData>,\n): ColumnAggregationValue<TFeatures> {\n  const rows = options?.rows\n  const resolvedMaxDepth = resolveMaxAggregationDepth(\n    options?.maxDepth ?? column.columnDef.maxAggregationDepth,\n  )\n  const providedResult = column.columnDef.getAggregationValue?.({\n    column: column as any,\n    maxDepth: resolvedMaxDepth,\n    rows,\n    table: column.table as any,\n  })\n\n  if (providedResult) return providedResult.value as any\n  if (column.table.options.manualAggregation) return undefined\n\n  if (rows !== undefined) {\n    return aggregateColumnValue({\n      column: column as any,\n      maxDepth: resolvedMaxDepth,\n      rows,\n    }) as any\n  }\n\n  const model = column.table.getPreGroupedRowModel()\n  const previous = (column as any)._aggregationValueCache as\n    | AggregationCacheEntry\n    | undefined\n  const registry = column.table._rowModelFns.aggregationFns\n  const aggregationFnOption = column.columnDef.aggregationFn\n\n  if (\n    previous &&\n    previous.dependency === model &&\n    previous.maxDepth === resolvedMaxDepth &&\n    previous.registry === registry &&\n    previous.aggregationFnOption === aggregationFnOption\n  ) {\n    return previous.value as any\n  }\n\n  const value = aggregateColumnValue({\n    column: column as any,\n    maxDepth: resolvedMaxDepth,\n    rows: model.rows,\n  })\n  ;(column as any)._aggregationValueCache = {\n    aggregationFnOption,\n    dependency: model,\n    maxDepth: resolvedMaxDepth,\n    registry,\n    value,\n  } satisfies AggregationCacheEntry\n  return value as any\n}\n\n/** Implements `cell.getIsAggregated()` for synthetic grouped rows. */\nexport function cell_getIsAggregated<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(cell: Cell<TFeatures, TData, TValue>) {\n  const groupingColumnId = (cell.row as any).groupingColumnId as\n    | string\n    | undefined\n  if (!groupingColumnId || groupingColumnId === cell.column.id) return false\n\n  const grouping = (cell.column.table as any).atoms.grouping?.get?.() as\n    | Array<string>\n    | undefined\n  if (grouping?.includes(cell.column.id)) return false\n\n  return column_getAggregationFns(cell.column as any).some(\n    (entry) => !!entry.aggregationFn,\n  )\n}\n\n/** Formats the default scalar or keyed aggregated-cell representation. */\nexport function formatAggregatedCellValue(\n  value: unknown,\n  option: unknown,\n): string | null {\n  if (value == null) return null\n\n  if (Array.isArray(option) && typeof value === 'object') {\n    const entries = Object.keys(value)\n    return entries\n      .map(\n        (key) => `${key}: ${String((value as Record<string, unknown>)[key])}`,\n      )\n      .join(', ')\n  }\n\n  return String(value)\n}\n"],"mappings":"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"}

package/dist/features/aggregation/aggregationFeature.utils.d.cts

@@ -1,5 +1,5 @@
 import { CellData, RowData } from "../../types/type-utils.cjs";
-import { AggregationFnDef, ColumnAggregationValue, ResolvedAggregationFn } from "./aggregationFeature.types.cjs";
+import { AggregationFnDef, AggregationValueOptions, ColumnAggregationValue, ResolvedAggregationFn } from "./aggregationFeature.types.cjs";
 import { Cell } from "../../types/Cell.cjs";
 import { Row } from "../../types/Row.cjs";
 import { Column } from "../../types/Column.cjs";
@@ -7,23 +7,24 @@ import { TableFeatures } from "../../types/TableFeatures.cjs";
 
 //#region src/features/aggregation/aggregationFeature.utils.d.ts
 /**
- * Flattens hierarchical row inputs to unique terminal leaves in encounter
- * order. This is the normalization used by public aggregation-value calls.
+ * Selects unique rows at a maximum relative depth in encounter order.
+ * Branches that end before the requested depth contribute their deepest row.
  */
-declare function normalizeAggregationRows<TFeatures extends TableFeatures, TData extends RowData>(rows: ReadonlyArray<Row<TFeatures, TData>>): Array<Row<TFeatures, TData>>;
+declare function normalizeAggregationRows<TFeatures extends TableFeatures, TData extends RowData>(rows: ReadonlyArray<Row<TFeatures, TData>>, maxDepth?: number): Array<Row<TFeatures, TData>>;
 /** Resolves the `sum` or `extent` definition inferred from the first core row. */
 declare function column_getAutoAggregationFn<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column<TFeatures, TData, TValue>): AggregationFnDef<TFeatures, TData, any, any> | undefined;
 /** Resolves and validates a column's scalar or multiple aggregation option. */
 declare function column_getAggregationFns<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column<TFeatures, TData, TValue>): ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>>;
-/** Executes every configured aggregation for a column over normalized rows. */
+/** Executes every configured aggregation over a depth-selected row frontier. */
 declare function aggregateColumnValue<TFeatures extends TableFeatures, TData extends RowData>(args: {
-  childRows?: ReadonlyArray<Row<TFeatures, TData>>;
+  maxDepth?: number;
+  subRows?: ReadonlyArray<Row<TFeatures, TData>>;
   column: Column<TFeatures, TData, unknown>;
   groupingRow?: Row<TFeatures, TData>;
   rows: ReadonlyArray<Row<TFeatures, TData>>;
 }): unknown;
-/** Implements `column.getAggregationValue(rows?)` and its default-value cache. */
-declare function column_getAggregationValue<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column<TFeatures, TData, TValue>, rows?: ReadonlyArray<Row<TFeatures, TData>>): ColumnAggregationValue<TFeatures>;
+/** Implements `column.getAggregationValue(options?)` and its default cache. */
+declare function column_getAggregationValue<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column<TFeatures, TData, TValue>, options?: AggregationValueOptions<TFeatures, TData>): ColumnAggregationValue<TFeatures>;
 /** Implements `cell.getIsAggregated()` for synthetic grouped rows. */
 declare function cell_getIsAggregated<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
 /** Formats the default scalar or keyed aggregated-cell representation. */

package/dist/features/aggregation/aggregationFeature.utils.d.ts

@@ -1,5 +1,5 @@
 import { CellData, RowData } from "../../types/type-utils.js";
-import { AggregationFnDef, ColumnAggregationValue, ResolvedAggregationFn } from "./aggregationFeature.types.js";
+import { AggregationFnDef, AggregationValueOptions, ColumnAggregationValue, ResolvedAggregationFn } from "./aggregationFeature.types.js";
 import { Cell } from "../../types/Cell.js";
 import { Row } from "../../types/Row.js";
 import { Column } from "../../types/Column.js";
@@ -7,23 +7,24 @@ import { TableFeatures } from "../../types/TableFeatures.js";
 
 //#region src/features/aggregation/aggregationFeature.utils.d.ts
 /**
- * Flattens hierarchical row inputs to unique terminal leaves in encounter
- * order. This is the normalization used by public aggregation-value calls.
+ * Selects unique rows at a maximum relative depth in encounter order.
+ * Branches that end before the requested depth contribute their deepest row.
  */
-declare function normalizeAggregationRows<TFeatures extends TableFeatures, TData extends RowData>(rows: ReadonlyArray<Row<TFeatures, TData>>): Array<Row<TFeatures, TData>>;
+declare function normalizeAggregationRows<TFeatures extends TableFeatures, TData extends RowData>(rows: ReadonlyArray<Row<TFeatures, TData>>, maxDepth?: number): Array<Row<TFeatures, TData>>;
 /** Resolves the `sum` or `extent` definition inferred from the first core row. */
 declare function column_getAutoAggregationFn<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column<TFeatures, TData, TValue>): AggregationFnDef<TFeatures, TData, any, any> | undefined;
 /** Resolves and validates a column's scalar or multiple aggregation option. */
 declare function column_getAggregationFns<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column<TFeatures, TData, TValue>): ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>>;
-/** Executes every configured aggregation for a column over normalized rows. */
+/** Executes every configured aggregation over a depth-selected row frontier. */
 declare function aggregateColumnValue<TFeatures extends TableFeatures, TData extends RowData>(args: {
-  childRows?: ReadonlyArray<Row<TFeatures, TData>>;
+  maxDepth?: number;
+  subRows?: ReadonlyArray<Row<TFeatures, TData>>;
   column: Column<TFeatures, TData, unknown>;
   groupingRow?: Row<TFeatures, TData>;
   rows: ReadonlyArray<Row<TFeatures, TData>>;
 }): unknown;
-/** Implements `column.getAggregationValue(rows?)` and its default-value cache. */
-declare function column_getAggregationValue<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column<TFeatures, TData, TValue>, rows?: ReadonlyArray<Row<TFeatures, TData>>): ColumnAggregationValue<TFeatures>;
+/** Implements `column.getAggregationValue(options?)` and its default cache. */
+declare function column_getAggregationValue<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column<TFeatures, TData, TValue>, options?: AggregationValueOptions<TFeatures, TData>): ColumnAggregationValue<TFeatures>;
 /** Implements `cell.getIsAggregated()` for synthetic grouped rows. */
 declare function cell_getIsAggregated<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
 /** Formats the default scalar or keyed aggregated-cell representation. */

package/dist/features/aggregation/aggregationFeature.utils.js

@@ -10,16 +10,20 @@ function isAggregationFnDescriptor(value) {
 function warn(message) {
 	if (process.env.NODE_ENV === "development") console.warn(message);
 }
+function resolveMaxAggregationDepth(maxDepth) {
+	return maxDepth === void 0 || Number.isNaN(maxDepth) ? 0 : Math.max(0, Math.floor(maxDepth));
+}
 /**
-* Flattens hierarchical row inputs to unique terminal leaves in encounter
-* order. This is the normalization used by public aggregation-value calls.
+* Selects unique rows at a maximum relative depth in encounter order.
+* Branches that end before the requested depth contribute their deepest row.
 */
-function normalizeAggregationRows(rows) {
+function normalizeAggregationRows(rows, maxDepth = 0) {
 	const result = [];
 	const seen = /* @__PURE__ */ new Set();
-	const visit = (row) => {
-		if (row.subRows.length) {
-			for (let i = 0; i < row.subRows.length; i++) visit(row.subRows[i]);
+	const normalizedMaxDepth = resolveMaxAggregationDepth(maxDepth);
+	const visit = (row, depth) => {
+		if (row.subRows.length && depth < normalizedMaxDepth) {
+			for (let i = 0; i < row.subRows.length; i++) visit(row.subRows[i], depth + 1);
 			return;
 		}
 		if (!seen.has(row.id)) {
@@ -27,7 +31,7 @@ function normalizeAggregationRows(rows) {
 			result.push(row);
 		}
 	};
-	for (let i = 0; i < rows.length; i++) visit(rows[i]);
+	for (let i = 0; i < rows.length; i++) visit(rows[i], 0);
 	return result;
 }
 function getAutoAggregationFnName(value) {
@@ -105,33 +109,37 @@ function column_getAggregationFns(column) {
 	}
 	return finish(resolved);
 }
-function getChildResult(childValue, isMultiple, id) {
-	if (!isMultiple) return childValue;
-	if (!id || !childValue || typeof childValue !== "object") return void 0;
-	return hasOwn(childValue, id) ? childValue[id] : void 0;
+function getSubRowResult(subRowValue, isMultiple, id) {
+	if (!isMultiple) return subRowValue;
+	if (!id || !subRowValue || typeof subRowValue !== "object") return void 0;
+	return hasOwn(subRowValue, id) ? subRowValue[id] : void 0;
 }
-/** Executes every configured aggregation for a column over normalized rows. */
+/** Executes every configured aggregation over a depth-selected row frontier. */
 function aggregateColumnValue(args) {
-	const { childRows, column, groupingRow, rows } = args;
+	const { subRows, column, groupingRow, rows } = args;
 	const internalColumn = column;
+	const maxDepth = resolveMaxAggregationDepth(args.maxDepth ?? internalColumn.columnDef.maxAggregationDepth);
+	const aggregationRows = normalizeAggregationRows(rows, maxDepth);
 	const entries = column_getAggregationFns(internalColumn);
 	const isMultiple = Array.isArray(internalColumn.columnDef.aggregationFn);
-	const canMerge = !!childRows?.length && childRows.every((row) => !!row.groupingColumnId && row.groupingColumnId !== column.id);
+	const canMerge = !!subRows?.length && subRows.every((row) => !!row.groupingColumnId && row.groupingColumnId !== column.id);
 	const execute = (entry) => {
 		const definition = entry.aggregationFn;
 		if (!definition) return void 0;
 		const context = {
+			...subRows ? { subRows } : {},
 			column,
 			columnId: column.id,
 			getValue: (row) => row.getValue(column.id),
 			...groupingRow ? { groupingRow } : {},
-			rows,
+			maxDepth,
+			rows: aggregationRows,
 			table: column.table
 		};
 		if (canMerge && definition.merge) return definition.merge({
 			...context,
-			childResults: childRows.map((row) => getChildResult(row.getValue(column.id), isMultiple, entry.id)),
-			childRows
+			subRowResults: subRows.map((row) => getSubRowResult(row.getValue(column.id), isMultiple, entry.id)),
+			subRows
 		});
 		return definition.aggregate(context);
 	};
@@ -143,10 +151,13 @@ function aggregateColumnValue(args) {
 	}
 	return result;
 }
-/** Implements `column.getAggregationValue(rows?)` and its default-value cache. */
-function column_getAggregationValue(column, rows) {
+/** Implements `column.getAggregationValue(options?)` and its default cache. */
+function column_getAggregationValue(column, options) {
+	const rows = options?.rows;
+	const resolvedMaxDepth = resolveMaxAggregationDepth(options?.maxDepth ?? column.columnDef.maxAggregationDepth);
 	const providedResult = column.columnDef.getAggregationValue?.({
 		column,
+		maxDepth: resolvedMaxDepth,
 		rows,
 		table: column.table
 	});
@@ -154,20 +165,23 @@ function column_getAggregationValue(column, rows) {
 	if (column.table.options.manualAggregation) return void 0;
 	if (rows !== void 0) return aggregateColumnValue({
 		column,
-		rows: normalizeAggregationRows(rows)
+		maxDepth: resolvedMaxDepth,
+		rows
 	});
 	const model = column.table.getPreGroupedRowModel();
 	const previous = column._aggregationValueCache;
 	const registry = column.table._rowModelFns.aggregationFns;
 	const aggregationFnOption = column.columnDef.aggregationFn;
-	if (previous && previous.dependency === model && previous.registry === registry && previous.aggregationFnOption === aggregationFnOption) return previous.value;
+	if (previous && previous.dependency === model && previous.maxDepth === resolvedMaxDepth && previous.registry === registry && previous.aggregationFnOption === aggregationFnOption) return previous.value;
 	const value = aggregateColumnValue({
 		column,
-		rows: normalizeAggregationRows(model.rows)
+		maxDepth: resolvedMaxDepth,
+		rows: model.rows
 	});
 	column._aggregationValueCache = {
 		aggregationFnOption,
 		dependency: model,
+		maxDepth: resolvedMaxDepth,
 		registry,
 		value
 	};