Improving typings of depth in collections

[tyteen4a03]

Right now, Payload types does not have the concept of depth-aware types. For a typical collection, when a relationship type is generated into the schema, it hints RelatedEntity | number (or string depending on your ID type). This isn't useful behaviour for the consumers as they now need to either cast the variable to RelatedEntity to get type completion or do some type guard checks to make sure the variable resolved to RelatedEntity.

I'm not sure how this can be improved in TypeScript but just throwing this out there.

[jmikrut]

Hey there - a solid fix here is super important for sure, but it's more complicated than depth alone unfortunately. For example, you might have access control that prevents a user from reading a document - or, in MongoDB at least, you might have deleted a document which will then prevent the document from populating successfully.

Basically - this problem runs a bit deeper than solely being based on depth alone. But I agree, something needs to be done here. We will figure out a solution one way or another. Will bring this forward in our priorities list.

[mbaroukhcw]

Hi.

As a dirty fixe, I generate type in a file named payload-typs-raw.ts and use this :

import type * as PL from './payload-types-raw'

type ElementType<T> = T extends (infer U)[] ? U : never;

type TransformType<T> = {
  [K in keyof T]: K extends "layout" ? TransformType<ElementType<T[K]>>[] : T[K] extends number | infer U ? U : TransformType<T[K]>
  
}
type TransformCollection<T> = {
  [K in keyof T]: TransformType<T[K]>
}

export type Config = {
  globals: PL.Config['globals']
  collections: TransformCollection<PL.Config['collections']>
}

export type Page = TransformType<PL.Page>
<Export all your entities>

At least it does the job for me (all my ids are number).

I just suppose that, if there is an ID, the referenced object will always be present.

[6TELOIV]

I recently ran into this with a poly relationship field, and had to ask on stack overflow. jcalz provided a thourough and great answer. I have copied it here for posterity
https://stackoverflow.com/a/79562932/3984972

---

One problem you're having is that TypeScript does not synthesize union types during inference of generic type arguments. When you call a function of the form function f<T>(arg: A<T>): R<T>, TypeScript will accept arguments of type A<X> for any X that's already part of the type. But if you pass in an argument of a union type like A<X> | A<Y>, TypeScript will usually not attempt to unify X and Y into a single type argument X | Y. Instead it decides that the call was probably a mistake and issues a warning. This behavior is intentional and described in microsoft/TypeScript#23312 and https://stackoverflow.com/q/39905523/2887218.

Of course nothing stops you from explicitly specifying the type argument, like this:

const arr = polyRelationshipMany<TypeA | TypeB | TypeC>(e.items); // okay
/* const arr: {
  relationTo: string;
  value: TypeA | TypeB | TypeC;
}[] */

That works, but... the output type isn't really what you want, is it? The resulting array has no idea that relationTo can only be one of the known string literal types, or that those string literal types are correlated with the value. Instead TypeA, TypeB, and TypeC have been squished together. That means the elements of your array are no longer discriminated unions:

e.items.map(x => {
  if (typeof x.value === "number") return 0;
  switch (x.relationTo) {
    case "type-a": return x.value.a; // okay
    case "type-b": return x.value.b; // okay
    case "type-c": return x.value.c; // okay
  }
});

const arr = polyRelationshipMany<TypeA | TypeB | TypeC>(e.items);
arr.map(x => {
  switch (x.relationTo) {
    case "type-a": return x.value.a; // error!
    case "type-b": return x.value.b; // error!
    case "type-c": return x.value.c; // error!
  }
});

Ideally you want arr's element type to still be a discriminated union, where each of the union members' value property has number excluded from it. This is possible, but it's more complicated to write. TypeScript won't automatically distribute generic function calls over union types in its function arguments, as requested in microsoft/TypeScript#52295, so you'll have to explicitly anticipate this and write for it.

---

Here's one approach:

function numberGuard<T extends { value: unknown }>(v: T):
  v is ExcludeNumberFromValue<T> {
  return typeof v.value !== "number"
}
function polyRelationshipMany<T extends { value: unknown }>(
  items: T[]
): ExcludeNumberFromValue<T>[] {
  return items.filter(numberGuard);
}

where ExcludeNumberFromValue<T> is what we have to write. A first attempt could be

type ExcludeNumberFromValue<T extends { value: unknown }> =
    Omit<T, "value"> & { value: Exclude<T["value"], number> };

using the Omit and Exclude utility types. That does something reasonable for an input type like

type X = ExcludeNumberFromValue<{ x: Date, value: string | number }>
// type X = Omit<{ x: Date, value: string | number }, "value"> & { value: string }

well, it's hard to see what type that is, so we can use something like https://stackoverflow.com/q/57683303/2887218 to show us:

type IdX = Id<X>;
// type IdX = { x: Date; value: string; }

Hooray! Unfortunately, this does not distribute over unions in T:

type Y = Id<ExcludeNumberFromValue<
  { x: Date, value: string | number } | 
  { y: number, value: boolean | number }
>>
// type Y = { value: string | boolean; }

We lost x and y entirely, and squished value together. That's just the nature of Omit (see https://stackoverflow.com/q/57103834/2887218
). We need a technique to operate over each union member separately. The go-to approach here is to make it a distributive conditional type. Wrapping it with T extends unknown ? ⋯ : never will do it:

type ExcludeNumberFromValue<T extends { value: unknown }> =
  T extends unknown ? 
    Omit<T, "value"> & { value: Exclude<T["value"], number> } 
  : never;

Now we get the right type for Y:

/* type Y = {
  x: Date;
  value: string;
} | {
  y: number;
  value: boolean;
} */

Once we use a conditional type like this it's a little bit easier to use infer within conditional types to pull out the value property type, instead of using an indexed access type:

type ExcludeNumberFromValue<T extends { value: unknown }> =
  T extends { value: infer V } ?
    Omit<T, "value"> & { value: Exclude<V, number> } 
 : never;

But that's the same thing.

---

So that type is what we want, mostly... except, we can't directly use it:

declare function numberGuard<T extends { value: unknown; }>(
  v: T): v is ExcludeNumberFromValue<T> // error!
// A type predicate's type must be assignable to its parameter's type.   

Oops, TypeScript can't tell that ExcludeNumberFromValue<T> is a valid narrowing of T. See https://stackoverflow.com/q/75621955/2887218. We need to force that to happen, possibly just by intersecting with T:

type ExcludeNumberFromValue<T extends { value: unknown }> =
  (T extends { value: infer V } ?
    Omit<T, "value"> & { value: Exclude<V, number> } : never) & T;

declare function numberGuard<T extends { value: unknown; }>(
  v: T): v is ExcludeNumberFromValue<T> // okay

but while conceptually that's right, intersection tends to have some weird effects:

/* type Y = {
  x: Date;
  value: string;
} | {
  x: Date;
  value: never;
  y: number;
} | {
  y: number;
  value: boolean;
}*/

That {value: never} is weird. In this case I think we can use Extract instead:

type ExcludeNumberFromValue<T extends { value: unknown }> =
  Extract<T extends { value: infer V } ?
    Omit<T, "value"> & { value: Exclude<V, number> } : never, T>;

That works, and Y looks correct... if you use the Id<T> utility type. We could leave it there, but then your output type might be a bit unpleasant to look at:

const arr = polyRelationshipMany(e.items);
/* const arr: ((Omit<{
    relationTo: "type-a";
    value: number | TypeA;
}, "value"> & {
    value: TypeA;
}) | (Omit<{
    relationTo: "type-b";
    value: number | TypeB;
}, "value"> & {
    value: TypeB;
}) | (Omit<...> & {
    ...;
}))[];

So let's build in that Id<T> utility type in there. It looks like

type Id<T> = T extends infer U ? { [K in keyof U]: U[K] } : never;

which is really just splitting a union into members, doing an "identity" mapped type over each member, and pushing the union together again. We want to put that inline, and it should be inside the Extract since we want the whole thing to be assignable to T. Now we have:

type ExcludeNumberFromValue<T extends { value: unknown }> =
  Extract<(T extends { value: infer V } ?
    Omit<T, "value"> & { value: Exclude<V, number> } : never
  ) extends infer U ? { [K in keyof U]: U[K] } : never, T>;

and

const arr = polyRelationshipMany(e.items);
/* const arr: (
  { relationTo: "type-a"; value: TypeA; } |
  { relationTo: "type-b"; value: TypeB; } | 
  { relationTo: "type-c"; value: TypeC; }
)[] */

arr.map(x => {
  switch (x.relationTo) {
    case "type-a": return x.value.a; // okay
    case "type-b": return x.value.b; // okay
    case "type-c": return x.value.c; // okay
  }
})

That looks like what we wanted. The type of arr's elements looks like Example with all the number parts of value filtered out without affecting the rest of the shape. And thus we can treat each element like the discriminated union it is.

Playground link to code