Generic 'Where' type

[dolanoadriano]

Proposal: Generic: 'Where' type

Currently, the Where type in Payload relies on a loosely typed structure (e.g., JsonValue), which results in limited editor autocompletion and a higher risk of runtime errors. I'd like to propose a generic version of Where that leverages TypeScript's type system, providing stronger type safety and better DX.

import { Operator } from 'payload';
import { FieldPath, FieldPathValue } from 'react-hook-form';

export type WhereField<TValue> = {
  [K in Operator]?: TValue;
};

export type Where<T extends object> = {
  [TPath in FieldPath<T>]?: WhereField<FieldPathValue<T, TPath>>;
} & { and?: Where<T>[]; or?: Where<T>[] };

---

Example

// Some collections
type User = {
  id: string;
  name: string;
};

type Post = {
  id: string;
  title: string;
  content: string;
  author: User;
};

// Usage
const exampleA: Where<Post> = {
  title: { equals: 'Hello' },                 // ✅ good value
  content: { equals: false },                 // ❌ wrong value
};

const exampleB: Where<Post> = {
  content: { equals: 'John Doe' },            // ✅ good key
  'blah-blah': { equals: 'whatever' },        // ❌ wrong key
};

const exampleC: Where<Post> = {
  'author.id': { equals: '1' },               // ✅ good nested value
  'author.name': { equals: false },           // ❌ wrong nested value
};

const exampleD: Where<Post> = {
  'author.id': { equals: 'John Doe' },        // ✅ good nested key
  'author.blah-blah': { equals: 'whatever' }, // ❌ wrong nested key
};

[r1tsuu]

It's a primitive solution, for example it doesn't support nested keys (for arrays / relations etc), richtext / json querying and the exists operator should accept boolean in any case.
But we do have in plans to improve type safety for where, we can get it probably after the depth generic - #9782 as I'm thinking some of the implementation from there may be re-used.

[sviatoslav-hulko]

Hi!
Is there a plan to support typed select? Meaning if I have something like:

class MyRepository {
  ...
  async find(select) {
    return this.payload.find({ collection, select });
  }
}

class MyService {
  result = await this.myRepository({ title: true }); 
  // type will be displayed as {id: string, title: string}
  // instead of object with all fields from collection's config 
  // (e.g. not a {id: string, title: string, anotherField: number, anotherField2: string})
}

As for now I see that I can receive typed response if I do something like:

async find<
  TSelect extends SelectType = SelectFromCollectionSlug<'myCollection'> & SelectType,
>(select?: TSelect): Promise<PaginatedDocs<TransformCollectionWithSelect<"myCollection", TSelect>>> {
  const result = await this.payload.find({
    collection: this.collection,
    select,
  });
  return result;
}

But the problem is that this way I can pass any params to select and I won't get any warning/error, which looks not really type-safe to me.
So ideally it would be great to have both these features work together:

• That you can only pass valid keys to select
• And the response type aligns with those keys

As of now I found only a way to do either one of these.

[dolanoadriano]

Ok, a little update. The documentation doesn't have many examples of how to use some operators (e.g. near).

As for arrays, I'll think about how to approach this in the next few days.

import { FieldPath, FieldPathValue } from 'react-hook-form';

export type AnyWhereField<TValue> = {
  exists?: boolean;
  equals?: TValue;
  not_equals?: TValue;
};

export type ComparableWhereField<TValue extends number | string> = {
  greater_than?: TValue;
  greater_than_equal?: TValue;
  less_than?: TValue;
  less_than_equal?: TValue;
};

export type SearchableWhereField<TValue extends string> = {
  like?: TValue;
  contains?: TValue;
};

export type Point = [number, number];
export type PointValue = { type: 'Polygon'; coordinates: Point[] }; // TODO
export type SpatialableWhereField<TValue extends Point> = {
  near?: [number, number, number | null, number | null]; // TODO
  within?: PointValue;
  intersect?: PointValue;
};

export type WhereField<TValue> = AnyWhereField<TValue> &
  (TValue extends number | string ? ComparableWhereField<TValue> : {}) &
  (TValue extends string ? SearchableWhereField<TValue> : {}) &
  (TValue extends Point ? SpatialableWhereField<TValue> : {});

export type Where<T extends object> = {
  [TPath in FieldPath<T>]?: WhereField<FieldPathValue<T, TPath>>;
} & { and?: Where<T>[]; or?: Where<T>[] };

[samtgarson]

I'm in the process of implementing Payload on an existing, fairly complex Next js app and in the process migrating from Prisma to use Payload's local api client.

I'm shocked that these calls are so loosely typed (e.g. where, select, etc), this is one of the main advantages of using a typed ORM like drizzle. Payload has access to everything it needs at compile-time to strongly type these calls, and there has been no movement on this discussion in a year.

Are there any plans to improve this?