@dotcms/client
Version:
Official JavaScript library for interacting with DotCMS REST APIs.
190 lines (189 loc) • 7.35 kB
TypeScript
import { DotHttpClient, DotRequestOptions, DotCMSClientConfig, DotErrorContent } from '@dotcms/types';
import { BaseBuilder } from '../../../base/builder/base-builder';
import { BuildQuery } from '../../shared/types';
/**
* Creates a Builder to filter and fetch content from the content API for a specific content type.
*
* @export
* @class CollectionBuilder
* @template T Represents the type of the content type to fetch. Defaults to unknown.
*/
export declare class CollectionBuilder<T = unknown> extends BaseBuilder<T> {
#private;
/**
* Creates an instance of CollectionBuilder.
* @param {object} params - Constructor parameters
* @param {DotRequestOptions} params.requestOptions - Options for the client request
* @param {DotCMSClientConfig} params.config - The client configuration
* @param {string} params.contentType - The content type to fetch
* @param {DotHttpClient} params.httpClient - HTTP client for making requests
* @memberof CollectionBuilder
*/
constructor(params: {
requestOptions: DotRequestOptions;
config: DotCMSClientConfig;
contentType: string;
httpClient: DotHttpClient;
});
/**
* Returns the current query built.
*
* @readonly
* @private
* @memberof CollectionBuilder
*/
private get currentQuery();
/**
* Filters the content by the specified language ID.
*
* @example
* ```typescript
* const client = new DotCMSClient(config);
* const collectionBuilder = client.content.getCollection("Blog");
* collectionBuilder.language(1);
* ```
*
* @param {number | string} languageId The language ID to filter the content by.
* @return {CollectionBuilder} A CollectionBuilder instance.
* @memberof CollectionBuilder
*/
language(languageId: number | string): this;
/**
* Filters the content by a Lucene query string.
*
* @param {string} query A Lucene query string.
* @return {CollectionBuilder} A CollectionBuilder instance.
* @memberof CollectionBuilder
*/
query(query: string): this;
/**
* Filters the content by building a query using a QueryBuilder function.
*
* @example
* ```typescript
* const client = new DotCMSClient(config);
* const collectionBuilder = client.content.getCollection("Blog");
* collectionBuilder.query((queryBuilder) =>
* queryBuilder.field('title').equals('Hello World').or().equals('Hello World 2')
* );
* ```
*
* @param {BuildQuery} buildQuery A function that receives a QueryBuilder instance and returns a valid query.
* @return {CollectionBuilder} A CollectionBuilder instance.
* @memberof CollectionBuilder
*/
query(buildQuery: BuildQuery): this;
/**
* Retrieves draft content.
* @example
* ```ts
* const client = new DotCMSClient(config);
* const collectionBuilder = client.content.getCollection("Blog");
* collectionBuilder
* .draft() // This will retrieve draft/working content
* .then((response) => // Your code here })
* .catch((error) => // Your code here })
* ```
*
* @return {CollectionBuilder} A CollectionBuilder instance.
* @memberof CollectionBuilder
*/
draft(): this;
/**
* Includes content from the dotCMS System Host in the query results.
*
* When enabled, content from the System Host is returned alongside content from
* the configured site. All positive `+conhost:` constraints present in the
* assembled query are collected and grouped into a single `+(conhost:X conhost:SYSTEM_HOST)`
* constraint, so dotCMS returns content from any of those hosts.
*
* Calling this method multiple times is idempotent — the constraint is only added once.
*
* @example
* ```ts
* client.content
* .getCollection<Blog>('Blog')
* .includeSystemHost()
* .limit(10)
* .then(({ contentlets }) => console.log(contentlets));
* ```
*
* @return {CollectionBuilder} A CollectionBuilder instance.
* @memberof CollectionBuilder
*/
includeSystemHost(): this;
/**
* Filters the content by a variant ID for [Experiments](https://www.dotcms.com/docs/latest/experiments-and-a-b-testing)
*
* More information here: {@link https://www.dotcms.com/docs/latest/content-api-retrieval-and-querying#ParamsOptional}
*
* @example
* ```ts
* const client = new DotCMSClient(config);
* const collectionBuilder = client.content.getCollection("Blog");
* collectionBuilder
* .variant("YOUR_VARIANT_ID")
* .then((response) => // Your code here })
* .catch((error) => // Your code here })
* ```
*
* @param {string} variantId A string that represents a variant ID.
* @return {CollectionBuilder} A CollectionBuilder instance.
* @memberof CollectionBuilder
*/
variant(variantId: string): this;
/**
* Wraps an error in a DotErrorContent instance with helpful context.
*
* @protected
* @param {unknown} error - The error to wrap
* @return {DotErrorContent} The wrapped error
* @memberof CollectionBuilder
*/
protected wrapError(error: unknown): DotErrorContent;
/**
* Gets the language ID for the query.
*
* @protected
* @return {number | string} The language ID
* @memberof CollectionBuilder
*/
protected getLanguageId(): number | string;
/**
* Builds the final Lucene query string by combining the base query with required system constraints.
*
* This method constructs the complete query by:
* 1. Adding language ID filter to ensure content matches the specified language
* 2. Adding live/draft status filter based on the draft flag
* 3. Applying content type specific query sanitization
* 4. Optionally adding site ID constraint if conditions are met
*
* Site ID constraint is added only when:
* - Query doesn't already contain a positive site constraint (+conhost)
* - Query doesn't explicitly exclude the current site ID (-conhost:currentSiteId)
* - Site ID is configured in the system
*
* @protected
* @returns {string} The complete Lucene query string ready for the Content API
* @memberof CollectionBuilder
*
* @example
* // For live content in language 1 with site ID 123:
* // Returns: "+contentType:Blog +languageId:1 +live:true +conhost:123"
*
* @example
* // For draft content without site constraint:
* // Returns: "+contentType:Blog +languageId:1 +(live:false AND working:true AND deleted:false)"
*
* @example
* // For content with explicit exclusion of current site (site ID 123):
* // Query: "+contentType:Blog -conhost:123"
* // Returns: "+contentType:Blog -conhost:123 +languageId:1 +live:true" (no site ID added)
*
* @example
* // For content with exclusion of different site (site ID 456, current is 123):
* // Query: "+contentType:Blog -conhost:456"
* // Returns: "+contentType:Blog -conhost:456 +languageId:1 +live:true +conhost:123" (site ID still added)
*/
protected buildFinalQuery(): string;
}