Core Operations

/**
 * Creates a new document in the specified collection
 * @param options - Creation options including collection, data, and configuration
 * @returns Promise resolving to the created document
 */
function create<T>(options: CreateOptions<T>): Promise<T>;

interface CreateOptions<T> {
  /** The collection slug to create the document in */
  collection: string;
  /** The data for the new document */
  data: Partial<T>;
  /** How many levels deep to populate relationships (default: 0) */
  depth?: number;
  /** Locale for the operation */
  locale?: string;
  /** Fallback locale if content not found in specified locale */
  fallbackLocale?: string;
  /** User context for access control */
  user?: User;
  /** Whether to override access control (requires proper permissions) */
  overrideAccess?: boolean;
  /** Whether to include hidden fields in the response */
  showHiddenFields?: boolean;
  /** Express request object for context */
  req?: PayloadRequest;
  /** Whether to save as draft */
  draft?: boolean;
  /** File path for file uploads */
  filePath?: string;
  /** File object for uploads */
  file?: File;
  /** Whether to overwrite existing files */
  overwriteExistingFiles?: boolean;
  /** Disable verification email for auth collections */
  disableVerificationEmail?: boolean;
}

import payload from "payload";

// Create a blog post
const post = await payload.create({
  collection: "posts",
  data: {
    title: "My First Post",
    content: "Hello, world!",
    status: "draft",
    author: userId,
  },
});

// Create with relationships populated
const postWithAuthor = await payload.create({
  collection: "posts",
  data: {
    title: "Post with Author",
    content: "Content here",
    author: authorId,
  },
  depth: 1, // Populate the author relationship
});

// Create with specific locale
const localizedPost = await payload.create({
  collection: "posts",
  data: {
    title: "Mon Premier Article",
    content: "Contenu en français",
  },
  locale: "fr",
});

/**
 * Find documents with criteria
 * @param options - Find options including collection, query parameters, and configuration
 * @returns Promise resolving to paginated documents
 */
function find<T>(options: FindOptions): Promise<PaginatedDocs<T>>;

/**
 * Find a specific document by ID
 * @param options - Find by ID options
 * @returns Promise resolving to the document
 */
function findByID<T>(options: FindByIDOptions): Promise<T>;

interface FindOptions {
  /** The collection slug to query */
  collection: string;
  /** Query conditions */
  where?: Where;
  /** Sort field and direction (e.g., "-createdAt", "title") */
  sort?: string;
  /** Maximum number of documents to return */
  limit?: number;
  /** Page number for pagination (1-based) */
  page?: number;
  /** How many levels deep to populate relationships */
  depth?: number;
  /** Locale for the operation */
  locale?: string;
  /** Fallback locale if content not found in specified locale */
  fallbackLocale?: string;
  /** User context for access control */
  user?: User;
  /** Whether to override access control */
  overrideAccess?: boolean;
  /** Whether to include hidden fields */
  showHiddenFields?: boolean;
  /** Express request object for context */
  req?: PayloadRequest;
  /** Current depth for recursive calls */
  currentDepth?: number;
  /** Whether to enable pagination */
  pagination?: boolean;
  /** Whether to include draft documents */
  draft?: boolean;
  /** Disable error throwing */
  disableErrors?: boolean;
}

interface FindByIDOptions {
  /** The collection slug */
  collection: string;
  /** Document ID to find */
  id: string | number;
  /** How many levels deep to populate relationships */
  depth?: number;
  /** Locale for the operation */
  locale?: string;
  /** Fallback locale if content not found in specified locale */
  fallbackLocale?: string;
  /** User context for access control */
  user?: User;
  /** Whether to override access control */
  overrideAccess?: boolean;
  /** Whether to include hidden fields */
  showHiddenFields?: boolean;
}

interface PaginatedDocs<T> {
  /** Array of documents */
  docs: T[];
  /** Total number of documents matching the query */
  totalDocs: number;
  /** Number of documents per page */
  limit: number;
  /** Total number of pages */
  totalPages: number;
  /** Current page number */
  page: number;
  /** Starting counter for current page */
  pagingCounter: number;
  /** Whether there is a previous page */
  hasPrevPage: boolean;
  /** Whether there is a next page */
  hasNextPage: boolean;
  /** Previous page number (if available) */
  prevPage?: number;
  /** Next page number (if available) */
  nextPage?: number;
}

// Find all published posts
const publishedPosts = await payload.find({
  collection: "posts",
  where: {
    status: {
      equals: "published",
    },
  },
  sort: "-createdAt",
  limit: 10,
});

// Find with complex where conditions
const featuredPosts = await payload.find({
  collection: "posts",
  where: {
    and: [
      {
        status: {
          equals: "published",
        },
      },
      {
        featured: {
          equals: true,
        },
      },
    ],
  },
});

// Find with populated relationships
const postsWithAuthors = await payload.find({
  collection: "posts",
  depth: 2, // Populate author and author's profile
});

// Find by ID
const specificPost = await payload.findByID({
  collection: "posts",
  id: "60f7b8c4e4b0b8001f5e4b0a",
  depth: 1,
});

/**
 * Update an existing document
 * @param options - Update options including collection, ID, data, and configuration
 * @returns Promise resolving to the updated document
 */
function update<T>(options: UpdateOptions<T>): Promise<T>;

interface UpdateOptions<T> {
  /** The collection slug */
  collection: string;
  /** Document ID to update */
  id?: string | number;
  /** Query conditions (alternative to ID) */
  where?: Where;
  /** Updated data (partial update) */
  data: Partial<T>;
  /** How many levels deep to populate relationships */
  depth?: number;
  /** Locale for the operation */
  locale?: string;
  /** Fallback locale if content not found in specified locale */
  fallbackLocale?: string;
  /** User context for access control */
  user?: User;
  /** Whether to override access control */
  overrideAccess?: boolean;
  /** Whether to include hidden fields */
  showHiddenFields?: boolean;
}

// Update by ID
const updatedPost = await payload.update({
  collection: "posts",
  id: postId,
  data: {
    title: "Updated Title",
    status: "published",
  },
});

// Update with query conditions
const publishedPosts = await payload.update({
  collection: "posts",
  where: {
    status: {
      equals: "draft",
    },
  },
  data: {
    status: "published",
  },
});

// Update with populated relationships
const postWithAuthor = await payload.update({
  collection: "posts",
  id: postId,
  data: {
    content: "Updated content",
  },
  depth: 1,
});

/**
 * Delete a document
 * @param options - Delete options including collection and ID
 * @returns Promise resolving to the deleted document
 */
function delete<T>(options: DeleteOptions): Promise<T>;

interface DeleteOptions {
  /** The collection slug */
  collection: string;
  /** Document ID to delete */
  id?: string | number;
  /** Query conditions (alternative to ID) */
  where?: Where;
  /** How many levels deep to populate relationships in response */
  depth?: number;
  /** Locale for the operation */
  locale?: string;
  /** Fallback locale if content not found in specified locale */
  fallbackLocale?: string;
  /** User context for access control */
  user?: User;
  /** Whether to override access control */
  overrideAccess?: boolean;
  /** Whether to include hidden fields */
  showHiddenFields?: boolean;
}

// Delete by ID
const deletedPost = await payload.delete({
  collection: "posts",
  id: postId,
});

// Delete with query conditions
const deletedDrafts = await payload.delete({
  collection: "posts",
  where: {
    status: {
      equals: "draft",
    },
  },
});

interface Where {
  [key: string]: any;
  /** Logical AND conditions */
  and?: Where[];
  /** Logical OR conditions */
  or?: Where[];
}

// Field operators
interface FieldOperators {
  /** Exact match */
  equals?: any;
  /** Not equal */
  not_equals?: any;
  /** Greater than */
  greater_than?: number | Date;
  /** Greater than or equal */
  greater_than_equal?: number | Date;
  /** Less than */
  less_than?: number | Date;
  /** Less than or equal */
  less_than_equal?: number | Date;
  /** Text contains (case-insensitive) */
  like?: string;
  /** Array contains value */
  contains?: any;
  /** Value exists in array */
  in?: any[];
  /** Value not in array */
  not_in?: any[];
  /** Field exists */
  exists?: boolean;
  /** Geographic near query */
  near?: {
    point: [number, number]; // [longitude, latitude]
    maxDistance?: number;
    minDistance?: number;
  };
}

// Complex where conditions
const complexQuery = await payload.find({
  collection: "posts",
  where: {
    or: [
      {
        and: [
          {
            status: {
              equals: "published",
            },
          },
          {
            createdAt: {
              greater_than: "2023-01-01",
            },
          },
        ],
      },
      {
        featured: {
          equals: true,
        },
      },
    ],
  },
});

// Text search
const searchResults = await payload.find({
  collection: "posts",
  where: {
    title: {
      like: "react",
    },
  },
});

// Array queries
const taggedPosts = await payload.find({
  collection: "posts",
  where: {
    tags: {
      contains: "javascript",
    },
  },
});