Preserve discriminated unions when merging query relations

[sgrowe]

How the merge works

For each possible item type, replace any fields supplied by the relations:

type MergeRelated<TItem, TRelated extends object> = TItem extends unknown
  ? Omit<TItem, keyof TRelated> & TRelated
  : never;

• keyof TRelated gives the relation field names.
• Omit<TItem, keyof TRelated> removes those fields from the original item.
• & TRelated adds the relation fields with their new types.

The subtle part is TItem extends unknown. Every type matches unknown, but TypeScript has a special rule: this conditional processes each union member separately.

For example:

StringField | DateField | ReferenceField;

becomes effectively:

MergeStringField | MergeDateField | MergeReferenceField;

Each variant keeps its own properties and discriminator. Without the conditional, Omit processes the union as a whole and loses those relationships.

The never branch is the required "otherwise" part of the conditional; ordinary item types always take the first branch.

[cursor]

Risk: low. Approved. Cursor Bugbot completed with no findings that need human review; this is a type-only union-distribution fix with compile-time coverage and no runtime behavior change.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver - Risk Based}