@elementor/utils
v0.2.2
Published
This package contains utility functions that are being used across the Elementor packages
Downloads
2,823
Keywords
Readme
Utils
This package contains utility functions that are being used across the Elementor packages.
Errors
This module contains a standard API for creating custom error classes in Elementor packages.
createError
To ensure consistency across the Elementor packages, we recommend creating a new error class that extends the
ElementorError
class using the createError
function that does it for you.
Creating a new error type
For convenience, we've exposed a createError
utility function that will create a custom error type for you.
This function will force your error code and message to be static (per our guidelines), and will shorten your code a little bit:
// errors.ts
import { createError } from '@elementor/utils';
export const CannotRender = createError<{ id: string; }>( 'cannot-render', 'Cannot render element' );
export const CannotSave = createError<{ id: number; status: string; }>( 'cannot-save', 'Cannot save document' );
export const ElementNotFound = createError<{ id: string; }>( 'element-not-found', 'Element not found' );
Creating a new error type manually
If you prefer to create a new error type manually, you can extend the ElementorError
class.
Inside your class, you'll need to define a unique error code and message that should be passed to the parent constructor.
We recommend having static string values for both the code and the message, so it'll then be easier to filter them in the
error-tracking tools (e.g. message = 'cannot render element';
rather than message = 'Cannot render element' + id;
).
If you need to pass more information about the error, attach it to the context.
import { ElementorError, type ElementorErrorOptions } from '@elementor/utils';
type CannotRenderContext = {
id: string;
};
type CannotRenderOptions = {
context: CannotRenderContext;
cause?: ElementorErrorOptions['cause'];
};
class CannotRender extends ElementorError {
constructor( { context, cause }: CannotRenderOptions ) {
const code = 'cannot-render';
const message = 'Cannot render element';
super( message, { cause, context, code } );
}
}
Throwing your custom error type
After creating your custom error type (as described above), you can throw it in your code:
Basic example:
export const ElementNotFound = createError<{ id: string; }>( 'element-not-found', 'Element not found' );
function renderElement( id: string ): string {
const element = findElementById( id );
if ( ! element ) {
throw new ElementNotFound({ context: { id } });
}
return element.render();
}
Example with a cause:
export const CannotSave = createError<{ id: number; status: string; }>( 'cannot-save', 'Cannot save document' );
try {
thirdPartyService.save( id );
} catch ( error ) {
throw new CannotSave({ context: { id, status: error.status }, cause: error });
}
ensureError
The ensureError
function is a utility function that ensures that the given value is an error.
If the value is already an error, it will be returned as is.
If the value is not an error, it will be wrapped with an Error
that includes the thrown value.
import { ensureError } from '@elementor/utils';
const CannotUpdate = createError<{ id: number; }>( 'cannot-update', 'Cannot update document' );
try {
thirdPartyService.update( id );
} catch ( error ) {
const errorInstance = ensureError( error );
throw new CannotUpdate({ context: { id }, cause: errorInstance });
}