TypeDrop

/** A record whose values can be safely used as Map keys. */
type Keyable = string | number | boolean;

/** Each distinct key maps to the subset of items that share it. */
type Grouped<K extends Keyable, T> = Map<K, T[]>;

/** One aggregated summary entry produced from a single group. */
type GroupSummary<K extends Keyable, S> = {
  key: K;
  summary: S;
};

// Group items by an arbitrary key —————————————————————————————
declare function groupBy<T, K extends Keyable>(
  items: T[],
  keySelector: (item: T) => K
): Grouped<K, T>;

// Reduce each group to a typed summary ————————————————————————
declare function aggregateGroups<K extends Keyable, T, S>(
  grouped: Grouped<K, T>,
  summarise: (items: T[]) => S
): GroupSummary<K, S>[];

// Pipeline convenience: group + aggregate in one call —————————
declare function groupAndAggregate<T, K extends Keyable, S>(
  items: T[],
  keySelector: (item: T) => K,
  summarise: (items: T[]) => S
): GroupSummary<K, S>[];

// Return the top-n summaries ranked by a numeric score ————————
declare function topN<K extends Keyable, S>(
  summaries: GroupSummary<K, S>[],
  score: (summary: S) => number,
  n: number
): GroupSummary<K, S>[];