Consider adding `primitive` as a union of all primitive types

Search Terms

• primitive type
• primitive type union

Suggestion

primitive would be a union of all primitive types, e.g.:

type primitive = string | number | bigint | boolean | symbol | null | undefined; // unknown & not object

The advantage of doing this as a TypeScript built‑in rather than defining it in user space is that when a new primitive type gets added to ECMAScript (e.g.: bigdecimal), it will be supported automatically without needing to update the type definitions of the library.

Use Cases

When describing an API that takes all‑but‑one primitive type, it’s useful to be able to do Exclude<primitive, symbol> or Exclude<primitive, number | bigint> without needing https://github.com/microsoft/TypeScript/pull/29317.

Examples

From DefinitelyTyped/DefinitelyTyped#44805:

/**
 * @see https://tc39.es/ecma262/#sec-createhtml
 */
export function CreateHTML(
	string: object | Exclude<primitive, string>, // unknown & not string
	tag: string,
	attribute: string,
	value?: object | Exclude<primitive, string>, // unknown & not string
): string;

/**
 * @throws {TypeError} If `x` or `y` is a `number` or `bigint` or they're different types.
 * @see https://tc39.es/ecma262/#sec-samevaluenonnumeric
 */
export function SameValueNonNumeric(
	x: object | Exclude<primitive, number | bigint>, // unknown & not (number | bigint)
	y: object | Exclude<primitive, number | bigint>, // unknown & not (number | bigint)
): boolean;

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.

Related

• https://github.com/microsoft/TypeScript/issues/28131
• https://github.com/microsoft/TypeScript/pull/29317
• https://github.com/microsoft/TypeScript/issues/39498

Start by reviewing the related issues #28131 and #39498 and pull request #29317, which establish the prior discussion around primitive-type unions. Then inspect the TypeScript type-checker entry points relevant to built-in types; done means the design is resolved and the proposed union behaves consistently with all current primitive types and future ECMAScript additions.