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

⚙ 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

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[]>>;
}

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.

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.

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

The example is wrong: Object.groupBy does not return an iterable, but a null-prototype object. If you wrap the object with Object.entries and iterate the resulting array, then you get the error.

The underlying issue is that TypeScript doesn't support optional index signatures (see #46969), and compensates by adding undefined to the type of indexed properties. This in turn allows you to add arbitrary properties whose value is actually undefined to the object. These properties would be present in the array returned by Object.entries.

Thankfully in this case, you can just use Map.groupBy instead, which is arguably more appropriate when you have arbitrary keys.

A particularly awkward consequence is that the optionality leaks into enumeration, where undefined is impossible at runtime:

const groups = Object.groupBy(items, item => item.category);
// Partial<Record<string, Item[]>>

for (const group of Object.values(groups)) {
  group.length;
  // error: 'group' is possibly 'undefined'
}

Object.values() only returns values of properties that actually exist, and Object.groupBy() never creates an empty or undefined group. This forces either a redundant runtime check or a non-null assertion on every iteration.

It would be useful to distinguish bounded key unions from wide index-signature keys:

type GroupByResult<K extends PropertyKey, T> =
  string extends K ? Record<K, T[]> :
  number extends K ? Record<K, T[]> :
  symbol extends K ? Record<K, T[]> :
  Partial<Record<K, T[]>>;

This preserves the important optionality for "a" | "b" while avoiding false undefineds for ordinary dynamic string/number keys. It also aligns naturally with noUncheckedIndexedAccess: dynamic property lookup can remain checked when that option is enabled, without incorrectly affecting Object.values() and Object.entries().

Map.groupBy is a good workaround. I guess even superior one so we may consider current api as an implicit nudge towards it ;)

Navigation Menu

Repository navigation

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

⚙ Compilation target

⚙ Library

Missing / Incorrect Definition

Sample Code

Documentation Link

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

⚙ Compilation target

⚙ Library

Missing / Incorrect Definition

Sample Code

Documentation Link

Activity

joshkel commented on May 15, 2025

RyanCavanaugh commented on May 15, 2025

TiAlRo commented on Oct 22, 2025

TiAlRo commented on Oct 22, 2025

DominoPivot commented on Feb 25, 2026

erictheswift commented on Aug 14, 2026

erictheswift commented on Aug 14, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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