@dotcms/client
Version:
Official JavaScript library for interacting with DotCMS REST APIs.
201 lines (200 loc) • 6.72 kB
TypeScript
import { DotHttpClient, DotRequestOptions, DotCMSClientConfig, DotErrorContent } from '@dotcms/types';
import { GetCollectionResponse, SortBy, GetCollectionRawResponse, OnFullfilled, OnRejected } from '../../content/shared/types';
import { BaseApiClient } from '../api/base-api';
/**
* Abstract base class for content builders that provides common functionality
* for querying content from the DotCMS Content API.
*
* This class extracts shared behavior between different builder implementations,
* including pagination, sorting, rendering, and response formatting.
*
* @export
* @abstract
* @class BaseBuilder
* @template T - The type of the content items (defaults to unknown)
*/
export declare abstract class BaseBuilder<T = unknown> extends BaseApiClient {
#private;
/**
* Creates an instance of BaseBuilder.
*
* @param {object} params - Constructor parameters
* @param {DotRequestOptions} params.requestOptions - Options for the client request
* @param {DotCMSClientConfig} params.config - The client configuration
* @param {DotHttpClient} params.httpClient - HTTP client for making requests
* @memberof BaseBuilder
*/
constructor(params: {
requestOptions: DotRequestOptions;
config: DotCMSClientConfig;
httpClient: DotHttpClient;
});
/**
* Returns the offset for pagination based on current page and limit.
*
* @readonly
* @protected
* @memberof BaseBuilder
*/
protected get offset(): number;
/**
* Returns the sort query in the format: field order, field order, ...
*
* @readonly
* @protected
* @memberof BaseBuilder
*/
protected get sort(): string | undefined;
/**
* Returns the full URL for the content API.
*
* @readonly
* @protected
* @memberof BaseBuilder
*/
protected get url(): string;
/**
* Sets the maximum amount of content to fetch.
*
* @example
* ```typescript
* builder.limit(20);
* ```
*
* @param {number} limit - The maximum amount of content to fetch
* @return {this} The builder instance for method chaining
* @memberof BaseBuilder
*/
limit(limit: number): this;
/**
* Sets the page number to fetch.
*
* @example
* ```typescript
* builder.page(2);
* ```
*
* @param {number} page - The page number to fetch
* @return {this} The builder instance for method chaining
* @memberof BaseBuilder
*/
page(page: number): this;
/**
* Sorts the content by the specified fields and orders.
*
* @example
* ```typescript
* const sortBy = [
* { field: 'title', order: 'asc' },
* { field: 'modDate', order: 'desc' }
* ];
* builder.sortBy(sortBy);
* ```
*
* @param {SortBy[]} sortBy - Array of constraints to sort the content by
* @return {this} The builder instance for method chaining
* @memberof BaseBuilder
*/
sortBy(sortBy: SortBy[]): this;
/**
* Setting this to true will server-side render (using velocity) any widgets
* that are returned by the content query.
*
* More information here: {@link https://www.dotcms.com/docs/latest/content-api-retrieval-and-querying#ParamsOptional}
*
* @example
* ```typescript
* builder.render();
* ```
*
* @return {this} The builder instance for method chaining
* @memberof BaseBuilder
*/
render(): this;
/**
* Sets the depth of the relationships of the content.
* Specifies the depth of related content to return in the results.
*
* More information here: {@link https://www.dotcms.com/docs/latest/content-api-retrieval-and-querying#ParamsOptional}
*
* @example
* ```typescript
* builder.depth(2);
* ```
*
* @param {number} depth - The depth of the relationships of the content (0-3)
* @return {this} The builder instance for method chaining
* @throws {Error} When depth is not between 0 and 3
* @memberof BaseBuilder
*/
depth(depth: number): this;
/**
* Executes the fetch and returns a promise that resolves to the content or rejects with an error.
*
* @example
* ```typescript
* builder
* .limit(10)
* .then((response) => console.log(response))
* .catch((error) => console.error(error));
* ```
*
* @example Using async/await
* ```typescript
* const response = await builder.limit(10);
* ```
*
* @param {OnFullfilled} [onfulfilled] - A callback that is called when the fetch is successful
* @param {OnRejected} [onrejected] - A callback that is called when the fetch fails
* @return {Promise<GetCollectionResponse<T> | DotErrorContent>} A promise that resolves to the content or rejects with an error
* @memberof BaseBuilder
*/
then(onfulfilled?: OnFullfilled<T>, onrejected?: OnRejected): Promise<GetCollectionResponse<T> | DotErrorContent>;
/**
* Formats the response to the desired format.
*
* @protected
* @param {GetCollectionRawResponse<T>} data - The raw response data
* @return {GetCollectionResponse<T>} The formatted response
* @memberof BaseBuilder
*/
protected formatResponse<T>(data: GetCollectionRawResponse<T>): GetCollectionResponse<T>;
/**
* Calls the content API to fetch the content.
*
* @protected
* @return {Promise<GetCollectionRawResponse<T>>} The fetch response data
* @throws {DotHttpError} When the HTTP request fails
* @memberof BaseBuilder
*/
protected fetch(): Promise<GetCollectionRawResponse<T>>;
/**
* Wraps an error in a DotErrorContent instance with helpful context.
*
* @protected
* @param {unknown} error - The error to wrap
* @return {DotErrorContent} The wrapped error
* @memberof BaseBuilder
*/
protected abstract wrapError(error: unknown): DotErrorContent;
/**
* Builds the final Lucene query string.
* Subclasses must implement this method to define their query building strategy.
*
* @protected
* @abstract
* @return {string} The final Lucene query string
* @memberof BaseBuilder
*/
protected abstract buildFinalQuery(): string;
/**
* Gets the language ID for the query.
* Subclasses must implement this method to provide the language ID.
*
* @protected
* @abstract
* @return {number | string} The language ID
* @memberof BaseBuilder
*/
protected abstract getLanguageId(): number | string | undefined;
}