Stricter Typing in Local API

[echocrow]

Currently, the Local API has some interoperability with generated types, but the current state comes with a couple drawbacks.

With some stricter type-checking, and earlier type "injection", the following could be achievable:

• Auto-complete of global and collection slugs.
• Warning when e.g. a slug was misspelled, or a collection name was passed into a globals query (or vice versa).
• Type inference based on the global or collection slug.
• Not needing to pass in the (hopefully correct) global/collection type into every API call.
• Automatic resolving of relationship fields, collapsing them to either string or whatever the type of the reference entity is, based on the depth provided.
• Probably more?

(Waterfall ahead - warning & apologies in advance!)

[echocrow]

To reflect, here are some current-state vs preferred behaviors:

Globals & Collections

Current Behavior

For example, roughly from the docs, this works fine:

import { Post } from './payload-types'

const posts = await payload.find<Post>({
  collection: 'posts',
})
// ✅ Typed as PaginatedDocs<Post>

However, so does this:

const posts = await payload.find<Post>({
  collection: 'users',
})
// ❌ Typed as PaginatedDocs<Post>, but will actually be PaginatedDocs<User>.
// No warning about the casting error.

and also:

const post = await payload.find<Post>({
  collection: 'whatever-does-not-exist',
})
// ❌ Typed as PaginatedDocs<Post>, but will never work.
// No warning about the invalid collection slug.

Preferred Behavior

const posts = await localApi.find({ collection: 'posts' })
// ✅ Automatically typed as PaginatedDocs<Post>.

const users = await localApi.find({ collection: 'users' })
// ✅ Automatically typed as PaginatedDocs<User>.

const foobar = await localApi.find({ collection: 'does-not-exist' })
// ⚠️ TS warning: "does-not-exist" does not satisfy "posts" | "users" | "...".

const wip = await localApi.find({ collection: 'po|' })
// ✅ Auto-completion suggestion for "posts" (and other collections starting with "po").

Depths & Relationships

Current Behavior

Taking this a step further, imagine posts have a field image, that is a reference to a Media entity:

const post = await payload.findByID<Post>({
  collection: 'posts',
  id: '...',
  depth: 2,
})

const { image } = post
// ❌ Typed as string | Media
// We know this will be a Media entity due to "depth: 2".

Preferred Behavior

const postA = await localApi.findByID({ collection: 'posts', id: '...', depth: 2 })
const { image } = postA
// ✅ Automatically typed as Media.

const postB = await localApi.findByID({ collection: 'posts', id: '...', depth: 1 })
const { image } = postB
// ✅ Automatically typed as string.

[echocrow]

There are probably different ways go to about this.

Spoiling one way that has worked for us was done in three steps:

1. Generate a single Schemas interface that groups collections and globals keyed by their slug
2. Wrap the Local API functions in a basic wrapper that can receive this Schemas interface
   • Using that generic, the API wrapper can reduce options to valid global slugs and collection slugs (based on the function), and automatically type the returned result
3. Going further, the depth option can be typed, and the resulting interface can be recursively scanned for relation field types, and be collapsed to string or the actual type, based on the remaining depth

The extra Schemas during type generation may look something like this:

export default interface Schemas {
  globals: {
    header: Header;
    footer: Footer;
    // ...
  };
  collections: {
    media: Media;
    posts: Post;
    users: User;
    // ...
  };
}

(maybe the name Schemas can be customized, to let people avoid name collections, should they have a custom collection called "Schemas"? or maybe this should be prefixed as PayloadSchemas?)

The setup then might look something like:

import type Schemas from './payload-types'

const localApi = new payload.LocalApi<Schemas>()

export default localApi

(This particular setup is similar to how type definitions are fed into Directus' SDK.)

From here, this localApi can be imported and used anywhere on the backend, e.g.

import localApi from './localApi'

const post = await localApi.findByID({ collection: 'post's, id: '...', depth: 2 })
// ✅ "posts" got auto-completed.
// ✅ Automatically typed as Post.

const { image } = post
// ✅ Automatically typed as Media.

Is there any interest in this?

If so, happy to help get this implemented, and/or share the code we've used to wrap the existing local API functions as proof of concept.

We also got helper types that resolve the various relation field types based on the depth, but the types currently required here are not exactly pretty.
I'm talking something like:

type ResolveNested<V, D extends Depth> =
  // Relation (Many/Single)
  [IsRelationManySingle<V>] extends [true]
    ? D extends 0
      ? string[]
      : ResolveNested<ArrayItem<Exclude<V, string[]>>, NextDepths[D]>[]
    :
  // Relation (Single/Single)
  [IsRelationSingleSingle<V>] extends [true]
  // ...

(Though there may be better solutions to resolving nested relation fields.)

[jmikrut]

Hey @echocrow — I have a WIP PR in motion that does a lot of what you've referenced above. I would love a hand implementing some of the TS utilities that you're describing:

#1563 (comment)

[echocrow]

(apologies for the triple quadruple post - what's a better format to share and present this?)

[DanRibbens]

No complaints here on formatting, this is great! We are going to be taking what you have here and expanding on it and seeing what we can accomplish in the coming weeks.

[DanRibbens]

We added a roadmap item for improving typescript support overall #1563 that covers these improvements.

[timofei-iatsenko]

"where" could be also typed (similarly how it's typed in mongo driver)

interface FindOptions<T> {
  where: Where<T>
}

[denolfe]

This shipped with https://github.com/payloadcms/payload/releases/tag/v1.6.1

[bormm]

This is fixed and shipped? "Automatic resolving of relationship fields, collapsing them to either string or whatever the type of the reference entity is, based on the depth provided." ?