TypeScript types for collections

[sixers]

Could Payload provide TypeScript definitions for collections? Also, it would be great if Local API was fully typed.
I couldn't find anything in the documentation, also current TS definitions for Payload class don't seem to support generics. The closest thing I found was to use https://www.graphql-code-generator.com on GraphQL schema.

It would be awesome if types could be inferred, e.g. similar to zod library:

const A = z.string();
type A = z.infer<typeof A>; // string

const u: A = 12; // TypeError
const u: A = "asdf"; // compiles

So something like:

const Catalog: CollectionConfig = {
  slug: "catalogs",
  fields: [
    {
      name: "name",
      label: "Name",
      type: "text",
      required: true,
    },
    {
      name: "size",
      label: "Size",
      type: "number",
      required: false,
    }
  ]
}

type Catalog = payload.infer<typeof Catalog> // {id: string, name: string, size?: number, createdAt: Date, updatedAt: Date}

I'm not sure if it's possible to infer given how collection configs are structured, but would be super awesome if possible.

If not possible, it would be great to be able to run some code-generation tool to generate types & typed APIs (e.g. what Prisma does).

WDYT?

[DanRibbens]

We have this on our radar as well! The conversation keeps coming up internally so it is something we know we need to do. It will be one of the items on the roadmap coming.

I'm going to set aside a day next week to take a deep dive in and see what I can come up for this. It is really a great topic, and I'm excited you brought it up and provided expected usage too. This is great!

[sixers]

@DanRibbens Sounds good, thank you!

FWIW, this is my early attempt to define something (I'm a newbie when it comes to TS generics and advanced types, so it's likely invalid, but sharing it anyway):

const Test = {
  slug: "tests",
  fields: [
    {
      name: "f1",
      type: "text",
    } as const,
    {
      name: "f2",
      type: "richText",
    } as const,
    {
      name: "f3",
      type: "number",
    } as const,
    {
      name: "f4",
      type: "select",
      options: ["o1", "o2"],
    } as const,
  ],
};

type MapTuple<T extends Array<{ readonly name: string }>> = {
  [K in T[number]["name"]]: Extract<T[number], { name: K }> extends {
    type: "text" | "richText";
  }
    ? string
    : Extract<T[number], { name: K }> extends {
        type: "number";
      }
    ? number
    : Extract<T[number], { name: K }> extends {
        type: "select";
        options: any;
      }
    ? Extract<T[number], { name: K; options: any }>["options"][number]
    : any;
};

type Collection<T extends { fields: Array<{ readonly name: string }> }> =
  MapTuple<T["fields"]> & {
    id: string;
    createdAt: string;
    updatedAt: string;
  };

type Test = Collection<typeof Test>;

// same as: 
// type Test = {
//   id: string;
//   f1: string;
//   f2: string;
//   f3: number;
//   f4: "o1" | "o2";
//   createdAt: string;
//   updatedAt: string;
// }

{

[sixers]

// EDIT: Added a relationship field to example

Hey, any update on this? I was thinking that because Payload wants to support plugins and JavaScript, pure typescript inference approach might turn out to be insufficient, and type generation approach might be more bulletproof.

The POC approach could be to transform the collection config to JSON Schema, and use https://github.com/bcherny/json-schema-to-typescript to generate types.

Example:

import { compile } from "json-schema-to-typescript";
import { CollectionConfig } from "payload/types";

const User: CollectionConfig = {
  slug: "users",
  labels: {
    singular: "User",
  },
  fields: [
    {
      name: "name",
      type: "text",
      required: true,
    },
  ],
};

const Test: CollectionConfig = {
  slug: "tests",
  labels: {
    singular: "Test",
  },
  fields: [
    {
      name: "f1",
      type: "text",
      required: true,
    },
    {
      name: "f2",
      type: "richText",
    },
    {
      name: "f3",
      type: "number",
      defaultValue: 10,
    },
    {
      name: "f4",
      type: "select",
      options: ["o1", "o2"],
      required: true,
    },
    {
      type: "relationship",
      name: "user",
      relationTo: "users",
    },
  ],
};

const Config = {
  collections: [User, Test],
};

function collectionToJsonSchema(
  collection: CollectionConfig,
  slugToLabel: Record<string, string>
): any {
  return {
    title: collection.labels.singular,
    type: "object",
    properties: Object.fromEntries(
      collection.fields.map((field) => {
        const type =
          field.type == "number"
            ? { type: "integer" }
            : field.type == "relationship"
            ? {
                $ref: `#/definitions/${
                  slugToLabel[field.relationTo as string]
                }`,
              }
            : { type: "string" };
        const enum_ = field.type == "select" ? { enum: field.options } : {};
        const default_ = field.defaultValue
          ? { default: field.defaultValue }
          : {};

        return [
          field.name,
          {
            ...type,
            ...enum_,
            ...default_,
          },
        ];
      })
    ),
    required: collection.fields
      .filter((field) => field.required === true)
      .map((field) => field.name),
    additionalProperties: false,
  };
}

function configToJsonSchema(config: { collections: CollectionConfig[] }): any {
  const slugToLabel = Object.fromEntries(
    config.collections.map((collection) => [
      collection.slug,
      collection.labels.singular,
    ])
  );
  return {
    definitions: Object.fromEntries(
      config.collections.map((collection) => [
        collection.labels.singular,
        collectionToJsonSchema(collection, slugToLabel),
      ])
    ),
    additionalProperties: false,
  };
}

await compile(configToJsonSchema(Config), "Config", {
  bannerComment: "// auto-generated by payload",
  unreachableDefinitions: true,
});

Output:

// auto-generated by payload

export interface Config {}
/**
 * This interface was referenced by `Config`'s JSON-Schema
 * via the `definition` "User".
 */
export interface User {
  name: string;
}
/**
 * This interface was referenced by `Config`'s JSON-Schema
 * via the `definition` "Test".
 */
export interface Test {
  f1: string;
  f2?: string;
  f3?: number;
  f4: "o1" | "o2";
  user?: User;
}

[DanRibbens]

I still need to do a deep dive of this. If we have to do generators to make the types usable everywhere, that could be an option. I personally don't want to have to add more to the development process if it can be avoided. Having to introduce developers to generators and having to integrate them in build tools or remember to run them after changes forces devs to start thinking about Payload and what it needs rather than their own business requirements. My ideal scenario is that these types are automated in runtime and also usable, though that might not be possible. Again, I need to explore it more.

With the plugin ecosystem, it shouldn't make the type creation any more difficult. The functions for dynamic type building will need to take the complete config after all the plugins are applied.

[Ontopic]

Little late to the party, even foolishly created a discussion really similar, #258. Not really any additions to eveything being said here, just that Typebox (https://github.com/sinclairzx81/typebox) has a +1 from me. And that Dan - kinda - says he hopes to bring a solution into the core 🤗

[richardvanbergen]

While I agree something like this would be great I do understand @DanRibbens hesitation. Unfortunately not every JS developer has discovered the way, the truth and the life that is TypeScript and implementing something like Typebox would give those developers another API to learn when getting started with Payload as opposed to JSON which is just typescript.

Also while it could (and has) lead to bugs where the types drift from the schema definition I've been having success just exporting the types alongside the collection.

export type Example = {
  property: string
}

const ExampleCollection = {
  slug: 'exampleCollection',
  fields: [
    {
       type: 'text',
       name: 'property',
       required: true,
    }
  ]
}

export default ExampleCollection

Compared to typebox

Advantages

• Clean
• Uses core TS features
• Doesn't place any burden on non-TS developers
• Frees up core team to work on other things

Disadvantages

• Separate types have to be maintained by the developer and kept up to date with collection
• Core developers need to validate collections on startup using JOI which has led to bugs for me
• Anything else?

If only Javascript had real types in it's core 🙄

[jmikrut]

Hey all,

SUPER excited to say that the Payload team has been working on a way to generate TypeScript interfaces from collection and global configs, and we've got a PR open that does it perfectly!

Going to do some testing and then add documentation but the PR is pretty close to being ready to merge.

🎉

Thanks to @sixers — we went your direction by first creating a JSON schema out of a fully built config and then used json-schema-to-typescript in order to auto-generate types.

#363