@tanstack/table-core 9.0.0-beta.5 → 9.0.0-beta.51

package/dist/features/row-aggregation/rowAggregationFeature.types.d.ts

@@ -0,0 +1,195 @@
+import { CellData, RowData } from "../../types/type-utils.js";
+import { BuiltInAggregationFn } from "./aggregationFns.js";
+import { ColumnDefTemplate } from "../../types/ColumnDef.js";
+import { Cell } from "../../types/Cell.js";
+import { Row } from "../../types/Row.js";
+import { Table } from "../../types/Table.js";
+import { Column } from "../../types/Column.js";
+import { IsAny, TableFeatures } from "../../types/TableFeatures.js";
+
+//#region src/features/row-aggregation/rowAggregationFeature.types.d.ts
+/** Declaration-merging fallback for named aggregation definitions. */
+interface AggregationFns {}
+/** Values and table objects available while one aggregation is evaluated. */
+interface AggregationContext<TFeatures extends TableFeatures, TData extends RowData, TValue = unknown> {
+  /** The column whose values are being aggregated. */
+  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;
+  /**
+   * The synthetic grouped row receiving this result. This property is omitted
+   * for root or caller-supplied-row aggregation. Its `depth` identifies the
+   * grouping level when grouped aggregation needs that distinction.
+   */
+  groupingRow?: Row<TFeatures, TData>;
+  /**
+   * 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. */
+  table: Table<TFeatures, TData>;
+}
+/** 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 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 the selected `rows`. */
+  aggregate: (context: AggregationContext<TFeatures, TData, TValue>) => TResult;
+  /**
+   * 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;
+}
+/**
+ * Creates a typed context-based aggregation definition for a column or
+ * aggregation-function registry.
+ */
+declare function constructAggregationFn<TFeatures extends TableFeatures = any, TData extends RowData = any, TValue = unknown, TResult = unknown>(definition: AggregationFnDef<TFeatures, TData, TValue, TResult>): AggregationFnDef<TFeatures, TData, TValue, TResult>;
+/** Aggregation-definition registry carried by a table feature set. */
+interface RowModelFns_Aggregation<in out TFeatures extends TableFeatures, in out TData extends RowData> {
+  aggregationFns: Record<string, AggregationFnDef<TFeatures, TData, any, any>>;
+}
+/** Named context-based aggregation definitions registered on a feature set. */
+type CustomAggregationFns<TFeatures extends TableFeatures, TData extends RowData> = Record<string, AggregationFnDef<TFeatures, TData, any, any>>;
+/** String names available from a feature set's aggregation registry. */
+type ExtractAggregationFnKeys<TFeatures extends TableFeatures> = IsAny<TFeatures> extends true ? keyof AggregationFns | BuiltInAggregationFn : TFeatures extends {
+  aggregationFns: infer TAggregationFns extends object;
+} ? Extract<keyof TAggregationFns, string> : keyof AggregationFns;
+/** A registered name, automatic inference, or inline aggregation definition. */
+type AggregationFnRef<TFeatures extends TableFeatures, TData extends RowData, TValue = unknown, TResult = unknown> = 'auto' | ExtractAggregationFnKeys<TFeatures> | AggregationFnDef<TFeatures, TData, TValue, TResult>;
+/** Gives an aggregation reference a stable key in a multiple result. */
+interface AggregationFnDescriptor<TFeatures extends TableFeatures, TData extends RowData, TValue = unknown, TResult = unknown> {
+  /** The named, automatic, or inline definition to execute. */
+  aggregationFn: AggregationFnRef<TFeatures, TData, TValue, TResult>;
+  /** Stable key used in the object returned by a multiple aggregation. */
+  id: string;
+}
+/** One named or explicitly keyed entry in a multiple aggregation option. */
+type AggregationFnListItem<TFeatures extends TableFeatures, TData extends RowData, TValue = unknown> = 'auto' | ExtractAggregationFnKeys<TFeatures> | AggregationFnDescriptor<TFeatures, TData, TValue, any>;
+/** A scalar aggregation reference or a list that produces a keyed object. */
+type AggregationFnOption<TFeatures extends TableFeatures, TData extends RowData, TValue = unknown> = AggregationFnRef<TFeatures, TData, TValue, any> | ReadonlyArray<AggregationFnListItem<TFeatures, TData, TValue>>;
+/** Extracts the result type produced by an aggregation definition. */
+type AggregationResultOf<TDefinition> = TDefinition extends AggregationFnDef<any, any, any, infer TResult> ? TResult : unknown;
+type RegisteredAggregationDefinition<TFeatures extends TableFeatures, TKey extends PropertyKey> = TFeatures extends {
+  aggregationFns: infer TRegistry extends Record<PropertyKey, unknown>;
+} ? TKey extends keyof TRegistry ? TRegistry[TKey] : never : never;
+type AggregationResultOfRef<TRef, TFeatures extends TableFeatures> = TRef extends AggregationFnDef<any, any, any, any> ? AggregationResultOf<TRef> : TRef extends 'auto' ? RegisteredAggregationResult<TFeatures> : TRef extends PropertyKey ? AggregationResultOf<RegisteredAggregationDefinition<TFeatures, TRef>> : unknown;
+type AggregationEntryId<TEntry> = TEntry extends string ? TEntry : TEntry extends {
+  id: infer TId extends string;
+} ? TId : never;
+type AggregationEntryDefinition<TEntry> = TEntry extends {
+  aggregationFn: infer TDefinition;
+} ? TDefinition : TEntry;
+/** Infers the scalar or keyed result produced by an aggregation option. */
+type AggregationResult<TOption, TFeatures extends TableFeatures = any> = TOption extends ReadonlyArray<infer TEntry> ? { [TKey in AggregationEntryId<TEntry>]: AggregationResultOfRef<AggregationEntryDefinition<Extract<TEntry, TKey | {
+  id: TKey;
+}>>, TFeatures> } : AggregationResultOfRef<TOption, TFeatures>;
+type RegisteredAggregationResult<TFeatures extends TableFeatures> = TFeatures extends {
+  aggregationFns: infer TRegistry extends Record<string, unknown>;
+} ? AggregationResultOf<TRegistry[keyof TRegistry]> : unknown;
+/** Default public result union when a column's precise option is not known. */
+type ColumnAggregationValue<TFeatures extends TableFeatures> = RegisteredAggregationResult<TFeatures> | Record<string, RegisteredAggregationResult<TFeatures> | undefined> | undefined;
+/** A validated aggregation entry returned by `column.getAggregationFns()`. */
+interface ResolvedAggregationFn<TFeatures extends TableFeatures, TData extends RowData> {
+  /** Resolved definition, or `undefined` when configuration is invalid. */
+  aggregationFn: AggregationFnDef<TFeatures, TData, any, any> | undefined;
+  /** Key used for a multiple result; scalar inline definitions have no id. */
+  id: string | undefined;
+}
+/** Column-definition options installed by `rowAggregationFeature`. */
+interface ColumnDef_Aggregation<in out TFeatures extends TableFeatures, in out TData extends RowData, TValue extends CellData = CellData> {
+  /** Renderer used for a grouped row's aggregated cell. */
+  aggregatedCell?: ColumnDefTemplate<ReturnType<Cell<TFeatures, TData, TValue>['getContext']>>;
+  /**
+   * One aggregation reference for a scalar result, or an array for a keyed
+   * 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 }`;
+   * return `undefined` to use the local aggregation fallback.
+   */
+  getAggregationValue?: (context: AggregationValueContext<TFeatures, TData, TValue>) => AggregationValueResult | undefined;
+}
+/** Column instance APIs installed by `rowAggregationFeature`. */
+interface Column_Aggregation<in out TFeatures extends TableFeatures, in out TData extends RowData> {
+  /** Resolves the configured scalar or multiple aggregation definitions. */
+  getAggregationFns: () => ReadonlyArray<ResolvedAggregationFn<TFeatures, TData>>;
+  /**
+   * Aggregates this column over the default pre-grouped row model, or over a
+   * caller-provided array of rows. `options.maxDepth` overrides the column's
+   * `maxAggregationDepth`. Explicit-row calls are intentionally not cached.
+   */
+  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 `rowAggregationFeature`. */
+interface Cell_Aggregation {
+  /** Whether this cell displays an aggregate on a synthetic grouped row. */
+  getIsAggregated: () => boolean;
+}
+/** Internal per-row cache used while grouped aggregates are evaluated. */
+interface Row_Aggregation {
+  /** Cached aggregate results keyed by column id. */
+  _aggregationValuesCache: Record<string, unknown>;
+}
+/** Values passed to a column-level aggregation-value provider. */
+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. */
+  table: Table<TFeatures, TData>;
+}
+/** Marks an aggregation-value override as handled. */
+interface AggregationValueResult<TResult = unknown> {
+  /** The supplied value. `undefined` is still a handled result. */
+  value: TResult;
+}
+/** Table options installed by `rowAggregationFeature`. */
+interface TableOptions_Aggregation {
+  /**
+   * Disables local `column.getAggregationValue()` calculation when a column
+   * override does not handle the request. Group values supplied by manually
+   * grouped rows remain the responsibility of the data owner.
+   */
+  manualAggregation?: boolean;
+}
+//#endregion
+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=rowAggregationFeature.types.d.ts.map

package/dist/features/row-aggregation/rowAggregationFeature.types.js

@@ -0,0 +1,12 @@
+//#region src/features/row-aggregation/rowAggregationFeature.types.ts
+/**
+* Creates a typed context-based aggregation definition for a column or
+* aggregation-function registry.
+*/
+function constructAggregationFn(definition) {
+	return definition;
+}
+
+//#endregion
+export { constructAggregationFn };
+//# sourceMappingURL=rowAggregationFeature.types.js.map

package/dist/features/row-aggregation/rowAggregationFeature.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowAggregationFeature.types.js","names":[],"sources":["../../../src/features/row-aggregation/rowAggregationFeature.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 `rowAggregationFeature`. */\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 `rowAggregationFeature`. */\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 `rowAggregationFeature`. */\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 `rowAggregationFeature`. */\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/row-aggregation/rowAggregationFeature.utils.cjs

@@ -0,0 +1,212 @@
+const require_utils = require('../../utils.cjs');
+
+//#region src/features/row-aggregation/rowAggregationFeature.utils.ts
+function isAggregationFnDef(value) {
+	return !!value && typeof value === "object" && "aggregate" in value;
+}
+function isAggregationFnDescriptor(value) {
+	return !!value && typeof value === "object" && "id" in value && "aggregationFn" in 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));
+}
+/**
+* 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, maxDepth = 0) {
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	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)) {
+			seen.add(row.id);
+			result.push(row);
+		}
+	};
+	for (let i = 0; i < rows.length; i++) visit(rows[i], 0);
+	return result;
+}
+function getAutoAggregationFnName(value) {
+	if (typeof value === "number") return "sum";
+	if (value instanceof Date && !Number.isNaN(value.getTime())) return "extent";
+}
+/** Resolves the `sum` or `extent` definition inferred from the first core row. */
+function column_getAutoAggregationFn(column) {
+	const value = column.table.getCoreRowModel().flatRows[0]?.getValue(column.id);
+	const name = getAutoAggregationFnName(value);
+	if (!name) return void 0;
+	const aggregationFn = column.table._rowModelFns.aggregationFns?.[name];
+	if (!aggregationFn) warn(`aggregationFn '${name}' (auto) for column '${column.id}' is not registered`);
+	return aggregationFn;
+}
+function resolveAggregationFn(column, ref) {
+	if (isAggregationFnDef(ref)) return ref;
+	if (ref === "auto") return column_getAutoAggregationFn(column);
+	const aggregationFn = column.table._rowModelFns.aggregationFns?.[ref];
+	if (!aggregationFn) warn(`aggregationFn '${String(ref)}' for column '${column.id}' is not registered`);
+	return aggregationFn;
+}
+/** Resolves and validates a column's scalar or multiple aggregation option. */
+function column_getAggregationFns(column) {
+	const option = column.columnDef.aggregationFn;
+	const registry = column.table._rowModelFns.aggregationFns;
+	const coreRowModel = column.table.getCoreRowModel();
+	const previous = column._resolvedAggregationFnsCache;
+	if (previous && previous.option === option && previous.registry === registry && previous.coreRowModel === coreRowModel) return previous.value;
+	const finish = (value) => {
+		column._resolvedAggregationFnsCache = {
+			coreRowModel,
+			option,
+			registry,
+			value
+		};
+		return value;
+	};
+	if (option == null) return finish([]);
+	if (!Array.isArray(option)) return finish([{
+		aggregationFn: resolveAggregationFn(column, option),
+		id: typeof option === "string" ? option : void 0
+	}]);
+	const ids = require_utils.makeObjectMap();
+	for (let i = 0; i < option.length; i++) {
+		const item = option[i];
+		const id = typeof item === "string" ? item : isAggregationFnDescriptor(item) ? item.id : void 0;
+		if (id !== void 0) ids[id] = (ids[id] ?? 0) + 1;
+	}
+	const resolved = [];
+	for (let i = 0; i < option.length; i++) {
+		const item = option[i];
+		const id = typeof item === "string" ? item : isAggregationFnDescriptor(item) ? item.id : void 0;
+		if (id === void 0) {
+			warn(`aggregationFn at index ${i} for column '${column.id}' needs a stable id`);
+			resolved.push({
+				aggregationFn: void 0,
+				id: void 0
+			});
+			continue;
+		}
+		if (ids[id] > 1) {
+			warn(`aggregationFn id '${id}' for column '${column.id}' is duplicated`);
+			resolved.push({
+				aggregationFn: void 0,
+				id
+			});
+			continue;
+		}
+		const ref = isAggregationFnDescriptor(item) ? item.aggregationFn : item;
+		resolved.push({
+			aggregationFn: resolveAggregationFn(column, ref),
+			id
+		});
+	}
+	return finish(resolved);
+}
+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 over a depth-selected row frontier. */
+function aggregateColumnValue(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 = !!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 } : {},
+			maxDepth,
+			rows: aggregationRows,
+			table: column.table
+		};
+		if (canMerge && definition.merge) return definition.merge({
+			...context,
+			subRowResults: subRows.map((row) => getSubRowResult(row.getValue(column.id), isMultiple, entry.id)),
+			subRows
+		});
+		return definition.aggregate(context);
+	};
+	if (!isMultiple) return entries[0] ? execute(entries[0]) : void 0;
+	const result = require_utils.makeObjectMap();
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		if (entry.id !== void 0) result[entry.id] = execute(entry);
+	}
+	return result;
+}
+/** 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
+	});
+	if (providedResult) return providedResult.value;
+	if (column.table.options.manualAggregation) return void 0;
+	if (rows !== void 0) return aggregateColumnValue({
+		column,
+		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.maxDepth === resolvedMaxDepth && previous.registry === registry && previous.aggregationFnOption === aggregationFnOption) return previous.value;
+	const value = aggregateColumnValue({
+		column,
+		maxDepth: resolvedMaxDepth,
+		rows: model.rows
+	});
+	column._aggregationValueCache = {
+		aggregationFnOption,
+		dependency: model,
+		maxDepth: resolvedMaxDepth,
+		registry,
+		value
+	};
+	return value;
+}
+/** Implements `cell.getIsAggregated()` for synthetic grouped rows. */
+function cell_getIsAggregated(cell) {
+	const groupingColumnId = cell.row.groupingColumnId;
+	if (!groupingColumnId || groupingColumnId === cell.column.id) return false;
+	if ((cell.column.table.atoms.grouping?.get?.())?.includes(cell.column.id)) return false;
+	return column_getAggregationFns(cell.column).some((entry) => !!entry.aggregationFn);
+}
+/** Formats the default scalar or keyed aggregated-cell representation. */
+function formatAggregatedCellValue(value, option) {
+	if (value == null) return null;
+	if (Array.isArray(option) && typeof value === "object") return Object.keys(value).map((key) => `${key}: ${String(value[key])}`).join(", ");
+	return String(value);
+}
+
+//#endregion
+exports.aggregateColumnValue = aggregateColumnValue;
+exports.cell_getIsAggregated = cell_getIsAggregated;
+exports.column_getAggregationFns = column_getAggregationFns;
+exports.column_getAggregationValue = column_getAggregationValue;
+exports.column_getAutoAggregationFn = column_getAutoAggregationFn;
+exports.formatAggregatedCellValue = formatAggregatedCellValue;
+exports.normalizeAggregationRows = normalizeAggregationRows;
+//# sourceMappingURL=rowAggregationFeature.utils.cjs.map

package/dist/features/row-aggregation/rowAggregationFeature.utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowAggregationFeature.utils.cjs","names":["makeObjectMap","hasOwn"],"sources":["../../../src/features/row-aggregation/rowAggregationFeature.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 './rowAggregationFeature.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/row-aggregation/rowAggregationFeature.utils.d.cts

@@ -0,0 +1,34 @@
+import { CellData, RowData } from "../../types/type-utils.cjs";
+import { AggregationFnDef, AggregationValueOptions, ColumnAggregationValue, ResolvedAggregationFn } from "./rowAggregationFeature.types.cjs";
+import { Cell } from "../../types/Cell.cjs";
+import { Row } from "../../types/Row.cjs";
+import { Column } from "../../types/Column.cjs";
+import { TableFeatures } from "../../types/TableFeatures.cjs";
+
+//#region src/features/row-aggregation/rowAggregationFeature.utils.d.ts
+/**
+ * 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>>, 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 over a depth-selected row frontier. */
+declare function aggregateColumnValue<TFeatures extends TableFeatures, TData extends RowData>(args: {
+  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(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. */
+declare function formatAggregatedCellValue(value: unknown, option: unknown): string | null;
+//#endregion
+export { aggregateColumnValue, cell_getIsAggregated, column_getAggregationFns, column_getAggregationValue, column_getAutoAggregationFn, formatAggregatedCellValue, normalizeAggregationRows };
+//# sourceMappingURL=rowAggregationFeature.utils.d.cts.map

package/dist/features/row-aggregation/rowAggregationFeature.utils.d.ts

@@ -0,0 +1,34 @@
+import { CellData, RowData } from "../../types/type-utils.js";
+import { AggregationFnDef, AggregationValueOptions, ColumnAggregationValue, ResolvedAggregationFn } from "./rowAggregationFeature.types.js";
+import { Cell } from "../../types/Cell.js";
+import { Row } from "../../types/Row.js";
+import { Column } from "../../types/Column.js";
+import { TableFeatures } from "../../types/TableFeatures.js";
+
+//#region src/features/row-aggregation/rowAggregationFeature.utils.d.ts
+/**
+ * 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>>, 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 over a depth-selected row frontier. */
+declare function aggregateColumnValue<TFeatures extends TableFeatures, TData extends RowData>(args: {
+  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(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. */
+declare function formatAggregatedCellValue(value: unknown, option: unknown): string | null;
+//#endregion
+export { aggregateColumnValue, cell_getIsAggregated, column_getAggregationFns, column_getAggregationValue, column_getAutoAggregationFn, formatAggregatedCellValue, normalizeAggregationRows };
+//# sourceMappingURL=rowAggregationFeature.utils.d.ts.map