Utility type: Object entries tuple

Search Terms

Utility type, object entries, tuple, mapped type

Suggestion

An Entries<T> utility type that constructs a union of all object entry tuples of type T in lib.es5.d.ts.

/**
 * Construct a union of all object entry tuples of type T
 */
type Entries<T> = {
    [P in keyof T]: [P, T[P]];
}[keyof T];

Use Cases

I understand the history behind why Object.entries provides string as the key type rather than the actual keys (because there may exist more actual keys that those defined in the type). I refer to discussion here.

Sometimes, however, we can be confident that only properties defined in the type will be present at runtime, and have found that a utility type like this can be helpful to more strictly define such types, particularly in tests.

Examples

const expected = {
   foo: "foo",
   bar: "Bar",
   baz: "BAZ",
} as const;

(Object.entries(expected) as Entries<typeof expected>).forEach(([input, output]) => {
  // where `myFunction`'s first parameter only accepts `"foo" | "bar" | "baz"` (or a superset)
  expect(myFunction(input)).to.equal(output);
});

function thatAcceptsJsxAttributeTuples(attributes: readonly Entries<JSX.IntrinsicElements["path"][]>): void {
  // ...
}

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

The proposal targets lib.es5.d.ts; start there and compare the existing utility-type declarations with the suggested Entries shape. Done means the utility type is added consistently with the standard library and supports the object-entry tuple examples described in the issue.