contentful-query.ts

/**
 * The Contentful content delivery API is very dynamic, and Contentful has not
 * strongly typed the interface for the options of the getEntries operation.
 *
 * This interface is an attempt to document the properties of these options.
 *
 * Ref: https://www.contentful.com/developers/docs/references/content-delivery-api/
 */
export interface ContentfulQueryOptions {
  /**
   * To search for entries with a specific content type, set the content_type
   * URI query parameter to the ID you want to search for.
   *
   * @example Get entries with content type 'landingPage'
   * const options = {
   *   content_type: 'landingPage'
   * }
   */
  content_type?: string;
  /**
   * The select operator allows you to choose what fields to return from an
   * entity. You can choose multiple values by combining comma separated operators.
   *
   * @example Get entries with content type 'landingPage', return 'handle` field
   * const options = {
   *   content_type: 'landingPage',
   *   select: 'fields.handle'
   * };
   */
  select?: string;
  /**
   * The default locale used to query the entries.
   */
  locale?: string;
  /**
   * Limit is the number of records to request. It has a limit of 100.
   *
   * @example Get first entry with content type 'landingPage' where the `handle` property is '/pages/about-us'
   * const options = {
   *   content_type: 'landingPage',
   *   'fields.handle[eq]': '/pages/about-us',
   *   limit: 1,
   * };
   */
  limit?: number;
  /**
   * Include is the depth of the model to retrieve.  Default 1, limit 10.
   *
   * @example Get the 'about-us' landing page content up to depth of 10.
   * const options = {
   *   content_type: 'landingPage',
   *   'fields.handle[eq]': '/pages/about-us',
   *   include: 10,
   * };
   */
  include?: number;
  /**
   * Number of records to skip.
   */
  skip?: number;
  /**
   * You can order items in the response by specifying the order search
   * parameter. You can use sys properties (such as sys.createdAt) or field
   * values (such as fields.myCustomDateField) for ordering.
   */
  order?: string;
  /**
   * Contentful search operators have specific suffixes. See documentation for
   * additional details.
   */
  [key: SearchOperator]: string;
}

export type EqualityOperator<T = string> = T extends string ? `${T}[eq]` : T;

export type InequalityOperator<T = string> = T extends string ? `${T}[ne]` : T;

export type InclusionOperator<T = string> = T extends string ? `${T}[in]` : T;

export type ExclusionOperator<T = string> = T extends string ? `${T}[nin]` : T;

export type ExistenceOperator<T = string> = T extends string ? `${T}[nin]` : T;

export type LessThanOperator<T = string> = T extends string ? `${T}[lt]` : T;

export type LessThanOrEqualToOperator<T = string> = T extends string
  ? `${T}[lte]`
  : T;

export type GreaterThanOperator<T = string> = T extends string ? `${T}[gt]` : T;

export type GreaterThanOrEqualToOperator<T = string> = T extends string
  ? `${T}[gte]`
  : T;

export type MatchOperator<T = string> = T extends string ? `${T}[match]` : T;

export type FieldMatcher<T = string> = T extends string ? `fields.${T}` : T;

export type SearchOperator<T = string> =
  | EqualityOperator<T>
  | InequalityOperator<T>
  | InclusionOperator<T>
  | ExclusionOperator<T>
  | ExistenceOperator<T>
  | LessThanOperator<T>
  | LessThanOrEqualToOperator<T>
  | GreaterThanOperator<T>
  | GreaterThanOrEqualToOperator<T>
  | MatchOperator<T>
  | FieldMatcher<T>;