why does the nullish coalescing operator removing one part of the union of records

I've been scratching my head without finding an answer. I don't understand why the nullish coalescing operator removes one part of the union in the following snippet:

declare const thing:
  | { id: number; version: number; label: string }
  | {
      label: string;
    }
  | undefined;

// it yields {label: string} | null instead of the expected { id: number; version: number; label: string } | { label: string; } | null
const thingWithCoallesce = thing ?? null;

I created a playground to demonstrate the case. I couldn't find anything in the issue tracker about that.

This isn't specific to nullish coalescing. The compiler is performing subtype reduction, which it can do whenever it "wants" to; see microsoft/TypeScript#49952 for more information.

Let's give these types names. Your code is essentially identical to:

interface Base {
  label: string
}

interface Subtype extends Base {
  id: number;
  version: number;
}

declare const thing: Subtype | Base | undefined
// const thing: Base | Subtype | undefined

const thingWithCoallesce = thing ?? null;
// const thingWithCoallesce: Base | null

For our purposes, the type Subtype is equivalent to {id: number; version: number; label: string}, while the type Base is equivalent to {label: string}.

The type Subtype is a subtype of Base (hence the naming); every value of type Subtype is also a value of type Base:

const s: Subtype = { id: 1, version: 2, label: "abc" };
const b: Base = s; // okay

(Note that excess property checking sometimes confuses people into thinking otherwise; see https://stackoverflow.com/q/72819923/2887218 for more information).

And that means that the union type Subtype | Base is equivalent to Base. You can see that from following some rules about unions like: X extends (X | Y) and: if X extends Z and Y extends Z then (X | Y) extends Z. So (Subtype | Base) extends Base and Base extends (Subtype | Base) and thus they are equivalent. Of course TypeScript's type system isn't fully sound so sometimes "equivalent" things can behave differently in some situations.

Okay, so Subtype | Base and Base are equivalent types. And so the compiler may, whenever it wants, perform subtype reduction and actually collapse Subtype | Base to Base. It is effectively an implementation detail of the compiler whether and when it "wants" to perform subtype reduction. It happens that when you explicitly create the union it tends to stick around where you've defined it:

declare const thing: Subtype | Base | undefined
// const thing: Base | Subtype | undefined

But switching/narrowing operations like nullish coalescing tend to reduce the unions:

const thingWithCoallesce = thing ?? null;
// const thingWithCoallesce: Base | null

If this is undesirable behavior, then you should probably change your types so that "every Subtype is a valid Base" doesn't apply. If by {label: string} you meant "has a label but lacks an id and a version", then you will need to say so explicitly:

interface OtherSubtype extends Base {
  id?: never;
  version?: never;
}

declare const thing: Subtype | OtherSubtype | undefined
// const thing: Subtype | OtherSubtype | undefined

const thingWithCoallesce = thing ?? null;
// const thingWithCoallesce: Subtype | OtherSubtype | null

And the subtype reduction doesn't happen because neither Subtype nor OtherSubtype are subtypes of the other.

Playground link to code