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.

[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>[] };