-
Notifications
You must be signed in to change notification settings - Fork 3.6k
/
ckeditorerror.ts
206 lines (184 loc) · 7.69 KB
/
ckeditorerror.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
/**
* @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. 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/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 a working editor as soon as possible.
*
* ```ts
* /**
* * 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'
* } );
* ```
*/
export default class CKEditorError extends Error {
/**
* A context of the error by which the Watchdog is able to determine which editor crashed.
*/
public readonly context: object | null | undefined;
/**
* The additional error data passed to the constructor. Undefined if none was passed.
*/
public readonly data?: object;
/**
* Creates an instance of the CKEditorError class.
*
* @param 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 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 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: string, context?: object | null, data?: object ) {
super( getErrorMessage( errorName, data ) );
this.name = 'CKEditorError';
this.context = context;
this.data = data;
}
/**
* Checks if the error is of the `CKEditorError` type.
*/
public is( type: string ): boolean {
return type === 'CKEditorError';
}
/**
* A utility that ensures that 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 err The error to rethrow.
* @param 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.
*/
public static rethrowUnexpectedError( err: Error, context: object ): never {
if ( ( err as any ).is && ( err as any ).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 the console with a properly formatted message and adds a link to the documentation.
* Use whenever you want to log a warning to the console.
*
* ```ts
* /**
* * 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 } );
* ```
*
* See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to throw an error and when to log
* a warning or an error to the console.
*
* @param errorName The error name to be logged.
* @param data Additional data to be logged.
*/
export function logWarning( errorName: string, data?: object ): void {
console.warn( ...formatConsoleArguments( errorName, data ) );
}
/**
* Logs an error to the console with a properly formatted message and adds a link to the documentation.
* Use whenever you want to log an error to the console.
*
* ```ts
* /**
* * 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.
*
* See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to use each method.
*
* @param errorName The error name to be logged.
* @param data Additional data to be logged.
*/
export function logError( errorName: string, data?: object ): void {
console.error( ...formatConsoleArguments( errorName, data ) );
}
/**
* Returns formatted link to documentation message.
*/
function getLinkToDocumentationMessage( errorName: string ): string {
return `\nRead more: ${ DOCUMENTATION_URL }#error-${ errorName }`;
}
/**
* Returns formatted error message.
*/
function getErrorMessage( errorName: string, data?: object ): string {
const processedObjects = new WeakSet();
const circularReferencesReplacer = ( key: string, value: unknown ) => {
if ( typeof value === 'object' && value !== null ) {
if ( processedObjects.has( value ) ) {
return `[object ${ value.constructor.name }]`;
}
processedObjects.add( value );
}
return value;
};
const stringifiedData = data ? ` ${ JSON.stringify( data, circularReferencesReplacer ) }` : '';
const documentationLink = getLinkToDocumentationMessage( errorName );
return errorName + stringifiedData + documentationLink;
}
/**
* Returns formatted console error arguments.
*/
function formatConsoleArguments( errorName: string, data?: object ): Array<unknown> {
const documentationMessage = getLinkToDocumentationMessage( errorName );
return data ? [ errorName, data, documentationMessage ] : [ errorName, documentationMessage ];
}