"Type could be instantiated with a different subtype" error using spread and rest

I'm trying to map an object such that the object stays the same except one property is mapped to a different type, but I'm having an issue with using spread and rest with generic types. Code and error below and playground here.

type DocumentReference<T extends {} = {}> = T & {
	id: number;
};

type MappableDocumentReference<T extends {} = {}> = T & {
	id: string;
};

export const mapFromDocumentReference = <T extends {}>({
	id,
	...rest
}: DocumentReference<T>): MappableDocumentReference<T> => ({
	...rest,
	id: `${id}`,
});

Type 'Omit<DocumentReference<T>, "id"> & { id: string; }' is not assignable to type 'MappableDocumentReference<T>'.
  Type 'Omit<DocumentReference<T>, "id"> & { id: string; }' is not assignable to type 'T'.
    'Omit<DocumentReference<T>, "id"> & { id: string; }' is assignable to the constraint of type 'T', but 'T' could be instantiated with a different subtype of constraint '{}'.(2322)

I understand that the error is saying T can be defined as a narrower type than {} and the value being returned may not conform to that narrower type. But when using spread and rest I assumed that would cover narrower types since the properties of the argument would be spread into the returned value. In theory this is ensuring T is conformed to. So I don't understand why I still get the error.

I can make this work by removing the annotation for the return type and letting TS infer the return type which is good enough for my use case. But I'd like to know why this doesn't work with the annotation.

The issue here is that TypeScript is unable to guarantee that the mapped object will still conform to the original type T. This is because the spread operator (...rest) is not type-preserving, meaning that TypeScript cannot guarantee that the properties spread from rest will still satisfy the constraints of T.

In your case, you're trying to return a MappableDocumentReference<T>, which includes T. However, TypeScript can't guarantee that the { ...rest, id: ${id} } object will still be a T, because the spread operator might not include all properties of T (or might include additional properties that are not in T).

One way to fix this is to cast the returned object to MappableDocumentReference<T>, but this is not type-safe and should be avoided if possible:

export const mapFromDocumentReference = <T extends {}>({
    id,
    ...rest
}: DocumentReference<T>): MappableDocumentReference<T> => ({
    ...rest,
    id: `${id}`,
} as MappableDocumentReference<T>);

A better solution would be to refactor your types so that T only includes the properties that you want to preserve when mapping from DocumentReference<T> to MappableDocumentReference<T>. This way, TypeScript can guarantee that the mapped object will still conform to T. T only includes the properties that you want to preserve when mapping, and id is separate from T. This allows TypeScript to guarantee that the mapped object will still conform to T.

type DocumentReference<T extends {} = {}> = {
    data: T;
    id: number;
};

type MappableDocumentReference<T extends {} = {}> = {
    data: T;
    id: string;
};

export const mapFromDocumentReference = <T extends {}>({
    id,
    data
}: DocumentReference<T>): MappableDocumentReference<T> => ({
    data,
    id: `${id}`,
});