| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178 |
- /**
- * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
- /**
- * @module utils/ckeditorerror
- */
- /* globals console */
- /**
- * URL to the documentation with error codes.
- */
- export const DOCUMENTATION_URL =
- 'https://ckeditor.com/docs/ckeditor5/latest/framework/guides/support/error-codes.html';
- /**
- * The CKEditor error class.
- *
- * You should throw `CKEditorError` when:
- *
- * * An unexpected situation occurred and the editor (most probably) will not work properly. Such exception will be handled
- * by the {@link module:watchdog/watchdog~Watchdog watchdog} (if it is integrated),
- * * If the editor is incorrectly integrated or the editor API is used in the wrong way. This way you will give
- * feedback to the developer as soon as possible. Keep in mind that for common integration issues which should not
- * stop editor initialization (like missing upload adapter, wrong name of a toolbar component) we use
- * {@link module:utils/ckeditorerror~logWarning `logWarning()`} and
- * {@link module:utils/ckeditorerror~logError `logError()`}
- * to improve developers experience and let them see the working editor as soon as possible.
- *
- * /**
- * * Error thrown when a plugin cannot be loaded due to JavaScript errors, lack of plugins with a given name, etc.
- * *
- * * @error plugin-load
- * * @param pluginName The name of the plugin that could not be loaded.
- * * @param moduleName The name of the module which tried to load this plugin.
- * * /
- * throw new CKEditorError( 'plugin-load', {
- * pluginName: 'foo',
- * moduleName: 'bar'
- * } );
- *
- * @extends Error
- */
- export default class CKEditorError extends Error {
- /**
- * Creates an instance of the CKEditorError class.
- *
- * @param {String} errorName The error id in an `error-name` format. A link to this error documentation page will be added
- * to the thrown error's `message`.
- * @param {Object|null} context A context of the error by which the {@link module:watchdog/watchdog~Watchdog watchdog}
- * is able to determine which editor crashed. It should be an editor instance or a property connected to it. It can be also
- * a `null` value if the editor should not be restarted in case of the error (e.g. during the editor initialization).
- * The error context should be checked using the `areConnectedThroughProperties( editor, context )` utility
- * to check if the object works as the context.
- * @param {Object} [data] Additional data describing the error. A stringified version of this object
- * will be appended to the error message, so the data are quickly visible in the console. The original
- * data object will also be later available under the {@link #data} property.
- */
- constructor( errorName, context, data ) {
- const message = `${ errorName }${ ( data ? ` ${ JSON.stringify( data ) }` : '' ) }${ getLinkToDocumentationMessage( errorName ) }`;
- super( message );
- /**
- * @type {String}
- */
- this.name = 'CKEditorError';
- /**
- * A context of the error by which the Watchdog is able to determine which editor crashed.
- *
- * @type {Object|null}
- */
- this.context = context;
- /**
- * The additional error data passed to the constructor. Undefined if none was passed.
- *
- * @type {Object|undefined}
- */
- this.data = data;
- }
- /**
- * Checks if the error is of the `CKEditorError` type.
- */
- is( type ) {
- return type === 'CKEditorError';
- }
- /**
- * A utility that ensures the the thrown error is a {@link module:utils/ckeditorerror~CKEditorError} one.
- * It is useful when combined with the {@link module:watchdog/watchdog~Watchdog} feature, which can restart the editor in case
- * of a {@link module:utils/ckeditorerror~CKEditorError} error.
- *
- * @param {Error} err An error.
- * @param {Object} context An object connected through properties with the editor instance. This context will be used
- * by the watchdog to verify which editor should be restarted.
- */
- static rethrowUnexpectedError( err, context ) {
- if ( err.is && err.is( 'CKEditorError' ) ) {
- throw err;
- }
- /**
- * An unexpected error occurred inside the CKEditor 5 codebase. This error will look like the original one
- * to make the debugging easier.
- *
- * This error is only useful when the editor is initialized using the {@link module:watchdog/watchdog~Watchdog} feature.
- * In case of such error (or any {@link module:utils/ckeditorerror~CKEditorError} error) the watchdog should restart the editor.
- *
- * @error unexpected-error
- */
- const error = new CKEditorError( err.message, context );
- // Restore the original stack trace to make the error look like the original one.
- // See https://github.com/ckeditor/ckeditor5/issues/5595 for more details.
- error.stack = err.stack;
- throw error;
- }
- }
- /**
- * Logs a warning to a console with proper message formatting and adds the link to the documentation.
- * Use whenever you want to log a warning on the console.
- *
- * /**
- * * There was a problem processing the configuration of the toolbar. The item with the given
- * * name does not exist, so it was omitted when rendering the toolbar.
- * *
- * * @error toolbarview-item-unavailable
- * * @param {String} name The name of the component.
- * * /
- * logWarning( 'toolbarview-item-unavailable', { name } );
- *
- * @param {String} errorName Error name to be logged.
- * @param {Object} [data] Additional data to be logged.
- * @returns {String}
- */
- export function logWarning( errorName, data ) {
- console.warn( ...formatConsoleArguments( errorName, data ) );
- }
- /**
- * Logs an error to a console with proper message formatting and adds the link to the documentation.
- * Use whenever you want to log a error on the console.
- *
- * /**
- * * There was a problem processing the configuration of the toolbar. The item with the given
- * * name does not exist, so it was omitted when rendering the toolbar.
- * *
- * * @error toolbarview-item-unavailable
- * * @param {String} name The name of the component.
- * * /
- * logError( 'toolbarview-item-unavailable', { name } );
- *
- * *Note*: In most cases logging a warning using {@link module:utils/ckeditorerror~logWarning} is enough.
- *
- * @param {String} errorName Error name to be logged.
- * @param {Object} [data] Additional data to be logged.
- * @returns {String}
- */
- export function logError( errorName, data ) {
- console.error( ...formatConsoleArguments( errorName, data ) );
- }
- function getLinkToDocumentationMessage( errorName ) {
- return `\nRead more: ${ DOCUMENTATION_URL }#error-${ errorName }`;
- }
- function formatConsoleArguments( errorName, data ) {
- const documentationMessage = getLinkToDocumentationMessage( errorName );
- return data ? [ errorName, data, documentationMessage ] : [ errorName, documentationMessage ];
- }
|