`Object.groupBy` should not return `Partial<Record<string, T>>` or `Partial<Record<number, T>>`

[joshkel]

⚙ Compilation target

es2022

⚙ Library

lib.es2024.object

Missing / Incorrect Definition

The type definitions for Object.groupBy<K, T> state that it returns a Partial<Record<K, T>>. This is useful if K is a union, enum, etc. - the result is is likely Partial, and the result is consistent with a Partial<Record<K, T>> literal, and having Partial helps prevent mistakes from assuming that every key is present in the resulting record. However, it's unnecessary if K is a unrestricted number or string: there's no way that a declared key within the result can have an undefined value, and the result is more consistent with a Record<string | number, T> literal than a Partial<Record<string | number, T>> literal, and any mistakes are more consistently dealt with using TypeScript's noUncheckedIndexedAccess option.

See #56805 (comment) and #56805 (comment) from the PR that originally added types for Object.groupBy.

Sample Code

type Employee = { name: string, role: 'ic' | 'manager' };
const employees: Set<Employee> = new Set();

const byName = Object.groupBy(employees, x => x.name);
for (const [name, nameGroup] of byName) {
  // TypeScript gives an error that nameGroup may be undefined,
  // but it's always defined
  console.log(nameGroup.length);
}

Documentation Link

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/groupBy

[joshkel]

A possible implementation of this change:

/**
 * Identifies unrestricted strings and numbers (i.e., not unions, not numeric
 * enums which can broaden to numbers, etc.).
 */
type IsAnyStringOrNumber<K extends PropertyKey> = K extends string | number
  ? string extends K
    ? K
    : `${number}` extends `${K}`
    ? K
    : string | number extends K
    ? K
    : never
  : never;

interface ObjectConstructor {
    /**
     * Groups members of an iterable according to the return value of the passed callback.
     * @param items An iterable.
     * @param keySelector A callback which will be invoked for each item in items.
     */
    groupBy<K extends PropertyKey, T>(
        items: Iterable<T>,
        keySelector: (item: T, index: number) => K,
    ): [K] extends [IsAnyStringOrNumber<K>] ? Record<K, T[]> : Partial<Record<K, T[]>>;
}

[RyanCavanaugh]

Changing this would introduce a confusing variance break where you can have code that is legal become illegal when an input type becomes narrower, which is usually not possible.

[TiAlRo]

The function groupBy<K extends PropertyKey, T> should return the type Record<K, T[]>, because when K is unrestricted like string, partiality is unnecessary.

Proposal
Change the behavior of Record<K extends PropertyKey, T> when K is a literal union type ('a' | 'b' | 'c') so that:

Objects of type Record<K, T> are allowed to omit some keys at runtime.

Autocompletion and type inference still show all keys from K.

Accessing a missing key returns T | undefined, similar to Partial<Record<K, T>>.

Existing Record<string, T> behavior remains unchanged.

Rationale
Matches the behavior of Record<string, T> for union-literal keys.

Reduces friction for APIs like groupBy, where a union-returning keySelector may not produce all keys in a particular array.

Avoids the need for partiality in common scenarios, while keeping type safety.

Optional enhancements
Could allow a compiler flag or strict mode for backward compatibility.

[TiAlRo]

Additionally, the type Partial<Record<string, T>> should be assignable to the type Record<string, T> because there is no difference.