@dotcms/types
Version:
The `@dotcms/types` package contains TypeScript type definitions for the dotCMS ecosystem. Use it to enable type safety and an enhanced developer experience when working with dotCMS APIs and structured content.
366 lines (359 loc) • 10.5 kB
JavaScript
'use strict';
/**
* Development mode
*
* @internal
*/
const DEVELOPMENT_MODE = 'development';
/**
* Production mode
*
* @internal
*/
const PRODUCTION_MODE = 'production';
/**
* Possible modes of UVE (Universal Visual Editor)
* @enum {string}
*
* @property {string} LIVE - Shows published and future content
* @property {string} PREVIEW - Shows published and working content
* @property {string} EDIT - Enables content editing functionality in UVE
* @property {string} UNKNOWN - Error state, UVE should not remain in this mode
*/
exports.UVE_MODE = void 0;
(function (UVE_MODE) {
UVE_MODE["EDIT"] = "EDIT_MODE";
UVE_MODE["PREVIEW"] = "PREVIEW_MODE";
UVE_MODE["LIVE"] = "LIVE";
UVE_MODE["UNKNOWN"] = "UNKNOWN";
})(exports.UVE_MODE || (exports.UVE_MODE = {}));
/**
* Actions send to the dotcms editor
*
* @export
* @enum {number}
*/
exports.DotCMSUVEAction = void 0;
(function (DotCMSUVEAction) {
/**
* Tell the dotcms editor that page change
*/
DotCMSUVEAction["NAVIGATION_UPDATE"] = "set-url";
/**
* Send the element position of the rows, columnsm containers and contentlets
*/
DotCMSUVEAction["SET_BOUNDS"] = "set-bounds";
/**
* Send the information of the hovered contentlet
*/
DotCMSUVEAction["SET_CONTENTLET"] = "set-contentlet";
/**
* Tell the editor that the page is being scrolled
*/
DotCMSUVEAction["IFRAME_SCROLL"] = "scroll";
/**
* Tell the editor that the page has stopped scrolling
*/
DotCMSUVEAction["IFRAME_SCROLL_END"] = "scroll-end";
/**
* Ping the editor to see if the page is inside the editor
*/
DotCMSUVEAction["PING_EDITOR"] = "ping-editor";
/**
* Tell the editor to init the inline editing editor.
*/
DotCMSUVEAction["INIT_INLINE_EDITING"] = "init-inline-editing";
/**
* Tell the editor to open the Copy-contentlet dialog
* To copy a content and then edit it inline.
*/
DotCMSUVEAction["COPY_CONTENTLET_INLINE_EDITING"] = "copy-contentlet-inline-editing";
/**
* Tell the editor to save inline edited contentlet
*/
DotCMSUVEAction["UPDATE_CONTENTLET_INLINE_EDITING"] = "update-contentlet-inline-editing";
/**
* Tell the editor to trigger a menu reorder
*/
DotCMSUVEAction["REORDER_MENU"] = "reorder-menu";
/**
* Tell the editor to send the page info to iframe
*/
DotCMSUVEAction["GET_PAGE_DATA"] = "get-page-data";
/**
* Tell the editor an user send a graphql query
*/
DotCMSUVEAction["CLIENT_READY"] = "client-ready";
/**
* Tell the editor to edit a contentlet
*/
DotCMSUVEAction["EDIT_CONTENTLET"] = "edit-contentlet";
/**
* Tell the editor to do nothing
*/
DotCMSUVEAction["NOOP"] = "noop";
})(exports.DotCMSUVEAction || (exports.DotCMSUVEAction = {}));
/**
* Available events in the Universal Visual Editor
* @enum {string}
*/
exports.UVEEventType = void 0;
(function (UVEEventType) {
/**
* Triggered when page data changes from the editor
*/
UVEEventType["CONTENT_CHANGES"] = "changes";
/**
* Triggered when the page needs to be reloaded
*/
UVEEventType["PAGE_RELOAD"] = "page-reload";
/**
* Triggered when the editor requests container bounds
*/
UVEEventType["REQUEST_BOUNDS"] = "request-bounds";
/**
* Triggered when scroll action is needed inside the iframe
*/
UVEEventType["IFRAME_SCROLL"] = "iframe-scroll";
/**
* Triggered when a contentlet is hovered
*/
UVEEventType["CONTENTLET_HOVERED"] = "contentlet-hovered";
})(exports.UVEEventType || (exports.UVEEventType = {}));
/* eslint-disable @typescript-eslint/no-explicit-any */
/**
* Page API specific error class
* Wraps HTTP errors and adds page-specific context including GraphQL information
*/
class DotErrorPage extends Error {
constructor(message, httpError, graphql) {
super(message);
this.name = 'DotCMSPageError';
this.httpError = httpError;
this.graphql = graphql;
// Ensure proper prototype chain for instanceof checks
Object.setPrototypeOf(this, DotErrorPage.prototype);
}
/**
* Serializes the error to a plain object for logging or transmission
*/
toJSON() {
return {
name: this.name,
message: this.message,
httpError: this.httpError?.toJSON(),
graphql: this.graphql,
stack: this.stack
};
}
}
/**
* Standardized HTTP error class for all HTTP client implementations
*/
class DotHttpError extends Error {
constructor(details) {
super(details.message);
this.name = 'DotHttpError';
this.status = details.status;
this.statusText = details.statusText;
this.data = details.data;
// Ensure proper prototype chain for instanceof checks
Object.setPrototypeOf(this, DotHttpError.prototype);
}
/**
* Serializes the error to a plain object for logging or transmission
*/
toJSON() {
return {
name: this.name,
message: this.message,
status: this.status,
statusText: this.statusText,
data: this.data,
stack: this.stack
};
}
}
/**
* Abstract base class for HTTP client implementations.
* Provides common error handling utilities and enforces HttpError contract.
*
* @example
* ```typescript
* // Fetch API example
* export class FetchHttpClient extends BaseHttpClient {
* async request<T>(url: string, options?: DotRequestOptions): Promise<T> {
* try {
* const response = await fetch(url, options);
*
* if (!response.ok) {
* // Parse response body and headers
* let errorBody: string | unknown;
* try {
* const contentType = response.headers.get('content-type');
* if (contentType?.includes('application/json')) {
* errorBody = await response.json();
* } else {
* errorBody = await response.text();
* }
* } catch {
* errorBody = response.statusText;
* }
*
* const headers: Record<string, string> = {};
* response.headers.forEach((value, key) => {
* headers[key] = value;
* });
*
* throw this.createHttpError(
* response.status,
* response.statusText,
* headers,
* errorBody
* );
* }
*
* return response.json();
* } catch (error) {
* if (error instanceof TypeError) {
* throw this.createNetworkError(error);
* }
* throw error;
* }
* }
* }
*
* // Axios example
* export class AxiosHttpClient extends BaseHttpClient {
* async request<T>(url: string, options?: DotRequestOptions): Promise<T> {
* try {
* const response = await axios(url, options);
* return response.data;
* } catch (error) {
* if (axios.isAxiosError(error)) {
* throw this.createHttpError(
* error.response?.status || 0,
* error.response?.statusText || 'Network Error',
* error.response?.headers,
* error.response?.data
* );
* }
* throw this.createNetworkError(error);
* }
* }
* }
* ```
*/
class BaseHttpClient {
/**
* Creates a standardized HttpError from HTTP response details.
* Handles parsing of error response body automatically.
*
* @param status - HTTP status code
* @param statusText - HTTP status text
* @param headers - Response headers (optional)
* @param body - Response body (optional)
* @param customMessage - Optional custom error message
* @returns HttpError instance with parsed response data
*/
createHttpError(status, statusText, headers, body, customMessage) {
let errorData = body;
// If body is a string, try to parse as JSON
if (typeof body === 'string') {
try {
const contentType = headers?.['content-type'] || headers?.['Content-Type'];
if (contentType?.includes('application/json')) {
errorData = JSON.parse(body);
} else {
errorData = body;
}
} catch {
errorData = body;
}
}
return new DotHttpError({
status,
statusText,
message: customMessage || `HTTP ${status}: ${statusText}`,
data: errorData
});
}
/**
* Creates a standardized HttpError for network/connection errors.
*
* @param originalError - The original network error
* @returns HttpError instance representing a network error
*/
createNetworkError(originalError) {
return new DotHttpError({
status: 0,
// Network error status
statusText: 'Network Error',
message: `Network error: ${originalError.message}`,
data: originalError
});
}
}
/**
* Content API specific error class
* Wraps HTTP errors and adds content-specific context including query information
*/
class DotErrorContent extends Error {
constructor(message, contentType, operation, httpError, query) {
super(message);
this.name = 'DotCMSContentError';
this.contentType = contentType;
this.operation = operation;
this.httpError = httpError;
this.query = query;
// Ensure proper prototype chain for instanceof checks
Object.setPrototypeOf(this, DotErrorContent.prototype);
}
/**
* Serializes the error to a plain object for logging or transmission
*/
toJSON() {
return {
name: this.name,
message: this.message,
contentType: this.contentType,
operation: this.operation,
httpError: this.httpError?.toJSON(),
query: this.query,
stack: this.stack
};
}
}
/**
* Navigation API specific error class
* Wraps HTTP errors and adds navigation-specific context
*/
class DotErrorNavigation extends Error {
constructor(message, path, httpError) {
super(message);
this.name = 'DotNavigationError';
this.path = path;
this.httpError = httpError;
// Ensure proper prototype chain for instanceof checks
Object.setPrototypeOf(this, DotErrorNavigation.prototype);
}
/**
* Serializes the error to a plain object for logging or transmission
*/
toJSON() {
return {
name: this.name,
message: this.message,
path: this.path,
httpError: this.httpError?.toJSON(),
stack: this.stack
};
}
}
exports.BaseHttpClient = BaseHttpClient;
exports.DEVELOPMENT_MODE = DEVELOPMENT_MODE;
exports.DotErrorContent = DotErrorContent;
exports.DotErrorNavigation = DotErrorNavigation;
exports.DotErrorPage = DotErrorPage;
exports.DotHttpError = DotHttpError;
exports.PRODUCTION_MODE = PRODUCTION_MODE;