瀏覽代碼

Merged `i/6079`.

Maciej Bukowski 5 年之前
父節點
當前提交
f859927755

+ 90 - 53
packages/ckeditor5-watchdog/docs/features/watchdog.md

@@ -13,25 +13,26 @@ The {@link module:watchdog/watchdog~Watchdog} utility allows you to do exactly t
 
 It should be noticed that the most "dangerous" places in the API - like `editor.model.change()`, `editor.editing.view.change()`, emitters - are covered with checks and `try-catch` blocks that allow detecting unknown errors and restart editor when they occur.
 
-Currently there are two available watchdogs, which can be used depending on your needs:
-* [editor watchdog](#editor-watchdog) - that fills the most basic scenario when only one editor is created,
-* [context watchdog](#context-watchdog) - that keeps an advanced structure of connected editors via te context feature running
+There are two available types of watchdogs:
 
-## Usage
-
-### Editor watchdog
+* [editor watchdog](#editor-watchdog) - to be used with a single editor instance,
+* [context watchdog](#context-watchdog) - to be used when your application uses `Context`.
 
 <info-box>
-	Note: The editor watchdog can be used only with an {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source editor built from source}.
+	Note: a watchdog can be used only with an {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source editor built from source}.
 </info-box>
 
+## Usage
+
+### Editor watchdog
+
 Install the [`@ckeditor/ckeditor5-watchdog`](https://www.npmjs.com/package/@ckeditor/ckeditor5-watchdog) package:
 
 ```bash
 npm install --save @ckeditor/ckeditor5-watchdog
 ```
 
-And then change your `ClassicEditor.create()` call to `watchdog.create()` as follows:
+Then, change your `ClassicEditor.create()` call to `watchdog.create()` as follows:
 
 ```js
 import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
@@ -57,17 +58,18 @@ In other words, your goal is to create a watchdog instance and make the watchdog
 <info-box>
 	A new editor instance is created every time the watchdog detects a crash. Thus, the editor instance should not be kept in your application's state. Use the {@link module:watchdog/editorwatchdog~EditorWatchdog#editor `EditorWatchdog#editor`} property instead.
 
-	It also means that any code that should be executed for any new editor instance should be either loaded as an editor plugin or executed in the callbacks defined by {@link module:watchdog/editorwatchdog~EditorWatchdog#setCreator `EditorWatchdog#setCreator()`} and {@link module:watchdog/editorwatchdog~EditorWatchdog#setDestructor `EditorWatchdog#setDestructor()`}. Read more about controlling the editor creation and destruction in the next section.
+	It also means that any code that should be executed for any new editor instance should be either loaded as an editor plugin or executed in the callbacks defined using {@link module:watchdog/editorwatchdog~EditorWatchdog#setCreator `EditorWatchdog#setCreator()`} and {@link module:watchdog/editorwatchdog~EditorWatchdog#setDestructor `EditorWatchdog#setDestructor()`}. Read more about controlling the editor creation and destruction in the next section.
 </info-box>
 
 #### Controlling editor creation and destruction
 
-For more control over the creation and destruction of editor instances, you can use the {@link  module:watchdog/editorwatchdog~EditorWatchdog#setCreator `EditorWatchdog#setCreator()`} and, if needed, the {@link  module:watchdog/editorwatchdog~EditorWatchdog#setDestructor `EditorWatchdog#setDestructor()`} methods:
+For more control over the creation and destruction of editor instances, you can use {@link module:watchdog/editorwatchdog~EditorWatchdog#setCreator `EditorWatchdog#setCreator()`} and, if needed, the {@link module:watchdog/editorwatchdog~EditorWatchdog#setDestructor `EditorWatchdog#setDestructor()`}:
 
 ```js
-// Instantiate the watchdog manually (do not use the for() helper).
+// Create editor watchdog.
 const watchdog = new EditorWatchdog();
 
+// Define a callback that will create an editor instance and return it.
 watchdog.setCreator( ( elementOrData, editorConfig ) => {
 	return ClassicEditor
 		.create( elementOrData, editorConfig )
@@ -76,21 +78,23 @@ watchdog.setCreator( ( elementOrData, editorConfig ) => {
 		} );
 } );
 
+// Do something before the editor is destroyed. Return a promise.
 watchdog.setDestructor( editor => {
-	// Do something before the editor is destroyed.
+	// ...
 
 	return editor
 		.destroy()
 		.then( () => {
 			// Do something after the editor is destroyed.
 		} );
- } );
+} );
 
+// Create editor instance and start watching it.
 watchdog.create( elementOrData, editorConfig );
 ```
 
 <info-box>
-	The default (not overridden) editor destructor is the `editor => editor.destroy()` function.
+	The default (not overridden ny `setDestructor()`) editor destructor simply executes `Editor#destroy()`.
 </info-box>
 
 #### Editor watchdog API
@@ -109,6 +113,7 @@ watchdog.editor;
 
 // The current state of the editor.
 // The editor might be in one of the following states:
+//
 // * `initializing` - before the first initialization, and after crashes, before the editor is ready,
 // * `ready` - a state when a user can interact with the editor,
 // * `crashed` - a state when an error occurs - it quickly changes to `initializing` or `crashedPermanently` depending on how many and how frequency errors have been caught recently,
@@ -138,10 +143,6 @@ watchdog.crashes.forEach( crashInfo => console.log( crashInfo ) );
 
 ### Context watchdog
 
-<info-box>
-	Note: the context watchdog can be used only with an {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source editor built from source}.
-</info-box>
-
 Install the [`@ckeditor/ckeditor5-watchdog`](https://www.npmjs.com/package/@ckeditor/ckeditor5-watchdog) package:
 
 ```bash
@@ -160,17 +161,21 @@ import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
 import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
 import Context from '@ckeditor/ckeditor5-core/src/context';
 
-// Create a watchdog for the context and pass the `Context` class with optional watchdog configuration:
+// Create a context watchdog and pass the `Context` class with optional watchdog configuration:
 const watchdog = new ContextWatchdog( Context, {
 	crashNumberLimit: 10
 } );
 
-// Initialize it with the context configuration:
+// Initialize the watchdog with context configuration:
 await watchdog.create( {
-	plugins: []
-} )
+	plugins: [
+	    // ...
+	],
+	// ...
+} );
 
-// Add editor instances:
+// Add editor instances.
+// You mat also use multiple `ContextWatchdog#add()` calls, each adding a single editor.
 await watchdog.add( [ {
 	id: 'editor1',
 	type: 'editor',
@@ -190,26 +195,44 @@ await watchdog.add( [ {
 	},
 	creator: ( element, config ) => ClassicEditor.create( element, config )
 } ] );
-```
 
-<info-box>
-	The Watchdog will keep the context and item instances running
-	that are added via the {@link module:watchdog/contextwatchdog~ContextWatchdog#add `ContextWatchdog#add` method}. This method can be called multiple times during the `ContextWatchdog` lifetime.
+// Or:
+await watchdog.add( {
+	id: 'editor1',
+	type: 'editor',
+	sourceElementOrData: document.querySelector( '#editor' ),
+	config: {
+		plugins: [ Essentials, Paragraph, Bold, Italic ],
+		toolbar: [ 'bold', 'italic', 'alignment' ]
+	},
+	creator: ( element, config ) => ClassicEditor.create( element, config )
+} );
 
-	To destroy one of the item instances use the {@link module:watchdog/contextwatchdog~ContextWatchdog#remove `ContextWatchdog#remove` method}. This method can be called multiple times during the `ContextWatchdog` lifetime as well.
-</info-box>
+await watchdog.add( {
+    id: 'editor2',
+    type: 'editor',
+    sourceElementOrData: document.querySelector( '#editor' ),
+    config: {
+        plugins: [ Essentials, Paragraph, Bold, Italic ],
+        toolbar: [ 'bold', 'italic', 'alignment' ]
+    },
+    creator: ( element, config ) => ClassicEditor.create( element, config )
+} );
+```
+
+To destroy one of the item instances use {@link module:watchdog/contextwatchdog~ContextWatchdog#remove `ContextWatchdog#remove`}:
 
 ```js
 await watchdog.remove( [ 'editor1', 'editor2' ] );
 
-// Or
+// Or:
 await watchdog.remove( 'editor1' );
 await watchdog.remove( 'editor2' );
 ```
 
 <info-box>
 	Examples presents the "synchronous way" of the integration with the context watchdog feature, however it's not needed to wait for the promises returned by the `create()`, `add()` and `remove()` methods. There might be a need
-	to create and destroy items dynamically with shared context and that's can be easily achieved as all promises operating on the internal API will be chained.
+	to create and destroy items dynamically with shared context and that can be easily achieved as all promises operating on the internal API will be chained.
 </info-box>
 
 #### Context watchdog API
@@ -217,19 +240,19 @@ await watchdog.remove( 'editor2' );
 The context watchdog feature provides the following API:
 
 ```js
-// Creating watchdog that will use the `Context` class and given configuration.
+// Creating watchdog that will use the `Context` class and watchdog configuration.
 const watchdog = new ContextWatchdog( Context, watchdogConfig );
 
-// Setting a custom creator.
+// Setting a custom creator for the context.
 watchdog.setCreator( async config => {
-	const context = await Context.create( config ) );
+	const context = await Context.create( config );
 
 	// Do something when the context is initialized.
 
 	return context;
 } );
 
-// Setting a custom destructor.
+// Setting a custom destructor for the context.
 watchdog.setDestructor( async context => {
 	// Do something before destroy.
 
@@ -243,42 +266,56 @@ await watchdog.create( contextConfig );
 await watchdog.add( {
 	id: 'editor1',
 	type: 'editor',
-	sourceElementOrData: editorSourceElementOrEditorData
+	sourceElementOrData: domElementOrEditorData
 	config: editorConfig,
 	creator: createEditor,
 	destructor: destroyEditor,
 } );
 
-// Removing and destroy given item.
-await watchdog.remove( [ 'editor1' ] );
+await watchdog.add( [
+    {
+    	id: 'editor1',
+    	type: 'editor',
+    	sourceElementOrData: domElementOrEditorData
+    	config: editorConfig,
+    	creator: createEditor,
+    	destructor: destroyEditor,
+    },
+    // ...
+] );
+
+// Remove and destroy given item (or items).
+await watchdog.remove( 'editor1' );
+
+await watchdog.remove( [ 'editor1', 'editor2', ... ] );
 
 // Getting given item instance.
-const editor1 = watchdog.get( 'editor1' );
+const editor1 = watchdog.getItem( 'editor1' );
 
 // Getting given item state.
-const editor1State = watchdog.getState( 'editor1' );
+const editor1State = watchdog.getItemState( 'editor1' );
 
 // Getting the context state.
 const contextState = watchdog.state;
 
-// The `error` event is fired when the context watchdog catches the context-related error.
-// Note that the item errors are not re-fired in the `ContextWatchdog#error`.
+// The `error` event is fired when the context watchdog catches a context-related error.
+// Note that errors fired by items are not delegated to `ContextWatchdog#event:error`.
+// See also `ContextWatchdog#event:itemError`.
 watchdog.on( 'error', ( _, { error } ) => {
-	console.log( 'The context crashed.' );
-} );
 
-// The `restarted` event is fired when the context is set back to the `ready` state (after it was in `error` state).
+// The `restart` event is fired when the context is set back to the `ready` state (after it was in `crashed` state).
 // Similarly, this event is not thrown for internal item restarts.
 watchdog.on( 'restart', () => {
 	console.log( 'The context has been restarted.' );
 } );
 
-// The `itemError` event is fired when an error occurred in one of the added items
+
+// The `itemError` event is fired when an error occurred in one of the added items.
 watchdog.on( 'itemError', ( _, { error, itemId } ) => {
 	console.log( `An error occurred in an item with the '${ itemId }' id.` );
 } );
 
-// The `itemRestarted` event is fired when the item is set back to the `ready` state (after it was in `error` state).
+// The `itemRestart` event is fired when an item is set back to the `ready` state (after it was in `crashed` state).
 watchdog.on( 'itemRestart', ( _, { itemId } ) => {
 	console.log( 'An item with with the '${ itemId }' id has been restarted.' );
 } );
@@ -286,10 +323,10 @@ watchdog.on( 'itemRestart', ( _, { itemId } ) => {
 
 ## Configuration
 
-Both, {@link module:watchdog/editorwatchdog~EditorWatchdog#constructor `EditorWatchdog`} and {@link module:watchdog/contextwatchdog~ContextWatchdog#constructor `ContextWatchdog`} constructors accept a {{@link module:watchdog/watchdog~WatchdogConfig configuration object} as the second argument with the following optional properties:
+Both {@link module:watchdog/editorwatchdog~EditorWatchdog#constructor `EditorWatchdog`} and {@link module:watchdog/contextwatchdog~ContextWatchdog#constructor `ContextWatchdog`} constructors accept a {{@link module:watchdog/watchdog~WatchdogConfig configuration object} as the second argument with the following optional properties:
 
-* `crashNumberLimit` - A threshold specifying the number of editor errors (defaults to `3`). After this limit is reached and the time between last errors is shorter than `minimumNonErrorTimePeriod` the watchdog changes its state to `crashedPermanently` and it stops restarting the editor. This prevents an infinite restart loop.
-* `minimumNonErrorTimePeriod` - An average amount of milliseconds between last editor errors (defaults to 5000). When the period of time between errors is lower than that and the `crashNumberLimit` is also reached the watchdog changes its state to `crashedPermanently` and it stops restarting the editor. This prevents an infinite restart loop.
+* `crashNumberLimit` - A threshold specifying the number of errors (defaults to `3`). After this limit is reached and the time between last errors is shorter than `minimumNonErrorTimePeriod` the watchdog changes its state to `crashedPermanently` and it stops restarting the editor. This prevents an infinite restart loop.
+* `minimumNonErrorTimePeriod` - An average amount of milliseconds between last editor errors (defaults to 5000). When the period of time between errors is lower than that and the `crashNumberLimit` is also reachedm the watchdog changes its state to `crashedPermanently` and it stops restarting the editor. This prevents an infinite restart loop.
 * `saveInterval` - A minimum number of milliseconds between saving editor data internally (defaults to 5000). Note that for large documents this might have an impact on the editor performance.
 
 ```js
@@ -297,13 +334,13 @@ const editorWatchdog = new EditorWatchdog( ClassicEditor, {
 	minimumNonErrorTimePeriod: 2000,
 	crashNumberLimit: 4,
 	saveInterval: 1000
-} )
+} );
 ```
 
 <info-box>
-	Note that the context watchdog passes its configuration to the added editors.
+	Note that the context watchdog passes its configuration to editor watchdogs that it creates for added editors.
 </info-box>
 
 ## Limitations
 
-The watchdog does not handle errors thrown during the editor or context initialization (by e.g. `Editor.create()`) and editor destruction (e.g. `Editor#destroy()`). Errors thrown at these stages mean that there is a problem in the code integrating the editor with your application and such a problem cannot be fixed by restarting the editor.
+The watchdogs do not handle errors thrown during the editor or context initialization (e.g. in `Editor.create()`) and editor destruction (e.g. in `Editor#destroy()`). Errors thrown at these stages mean that there is a problem in the code integrating the editor with your application and such problem cannot be fixed by restarting the editor.

+ 28 - 28
packages/ckeditor5-watchdog/src/contextwatchdog.js

@@ -15,7 +15,7 @@ import areConnectedThroughProperties from './utils/areconnectedthroughproperties
 import getSubNodes from './utils/getsubnodes';
 
 /**
- * The Context Watchdog class.
+ * A watchdog for the {@link module:core/context~Context} class.
  *
  * See the {@glink features/watchdog Watchdog feature guide} to learn the rationale behind it and
  * how to use it.
@@ -111,10 +111,10 @@ export default class ContextWatchdog extends Watchdog {
 		 * It expects a function that should return a promise (or `undefined`).
 		 *
 		 *		watchdog.setCreator( config => Context.create( config ) );
-		*
-		* @method #setCreator
-		* @param {Function} creator
-		*/
+		 *
+		 * @method #setCreator
+		 * @param {Function} creator
+		 */
 
 		/**
 		 * Sets the function that is responsible for the context destruction.
@@ -123,17 +123,17 @@ export default class ContextWatchdog extends Watchdog {
 		 *
 		 *		watchdog.setDestructor( context => {
 		 *			// Do something before the context is destroyed.
-		*
-		*			return context
-		*				.destroy()
-		*				.then( () => {
-		*					// Do something after the context is destroyed.
-		*				} );
-		*		} );
-		*
-		* @method #setDestructor
-		* @param {Function} destructor
-		*/
+		 *
+		 *			return context
+		 *				.destroy()
+		 *				.then( () => {
+		 *					// Do something after the context is destroyed.
+		 *				} );
+		 *		} );
+		 *
+		 * @method #setDestructor
+		 * @param {Function} destructor
+		 */
 	}
 
 	/**
@@ -166,28 +166,28 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-     * Returns the item instance with the given `itemId`.
+	 * Returns the item instance with the given `itemId`.
 	 *
-	 * 	const editor1 = watchdog.get( 'editor1' );
+	 * 	const editor1 = watchdog.getItem( 'editor1' );
 	 *
 	 * @param {String} itemId The item id.
 	 * @returns {*} The item instance or `undefined` if an item with given id has not been found.
 	 */
-	get( itemId ) {
+	getItem( itemId ) {
 		const watchdog = this._getWatchdog( itemId );
 
-		return watchdog._instance;
+		return watchdog._item;
 	}
 
 	/**
 	 * Gets state of the given item. For the list of available states see {@link #state}.
 	 *
-	 * 	const editor1State = watchdog.getState( 'editor1' );
+	 * 	const editor1State = watchdog.getItemState( 'editor1' );
 	 *
 	 * @param {String} itemId Item id.
 	 * @returns {'initializing'|'ready'|'crashed'|'crashedPermanently'|'destroyed'} The state of the item.
 	 */
-	getState( itemId ) {
+	getItemState( itemId ) {
 		const watchdog = this._getWatchdog( itemId );
 
 		return watchdog.state;
@@ -224,7 +224,7 @@ export default class ContextWatchdog extends Watchdog {
 	 *
 	 * And then the instance can be retrieved using the {@link #get} method:
 	 *
-	 * 	const editor1 = watchdog.get( 'editor1' );
+	 * 	const editor1 = watchdog.getItem( 'editor1' );
 	 *
 	 * Note that this method can be called multiple times, but for performance reasons it's better
 	 * to pass all items together.
@@ -439,9 +439,9 @@ export default class ContextWatchdog extends Watchdog {
 	 * @param {Error} error
 	 * @returns {Boolean}
 	 */
-	_isErrorComingFromThisInstance( error ) {
+	_isErrorComingFromThisItem( error ) {
 		for ( const watchdog of this._watchdogs.values() ) {
-			if ( watchdog._isErrorComingFromThisInstance( error ) ) {
+			if ( watchdog._isErrorComingFromThisItem( error ) ) {
 				return false;
 			}
 		}
@@ -490,7 +490,7 @@ class ActionQueue {
 		this._onEmptyCallbacks = [];
 	}
 
-	// A method used to register callbacks that will be run when the queue becomes empty.
+	// Used to register callbacks that will be run when the queue becomes empty.
 	//
 	// @param {Function} onEmptyCallback A callback that will be run whenever the queue becomes empty.
 	onEmpty( onEmptyCallback ) {
@@ -520,13 +520,13 @@ class ActionQueue {
 }
 
 /**
- * The WatchdogItemConfiguration interface.
+ * The `WatchdogItemConfiguration` interface.
  *
  * @typedef {module:watchdog/contextwatchdog~EditorWatchdogConfiguration} module:watchdog/contextwatchdog~WatchdogItemConfiguration
  */
 
 /**
- * The EditorWatchdogConfiguration interface specifies how editors should be created and destroyed.
+ * The `EditorWatchdogConfiguration` interface specifies how editors should be created and destroyed.
  *
  * @typedef {Object} module:watchdog/contextwatchdog~EditorWatchdogConfiguration
  *

+ 5 - 4
packages/ckeditor5-watchdog/src/editorwatchdog.js

@@ -95,7 +95,7 @@ export default class EditorWatchdog extends Watchdog {
 	/**
 	 * @inheritDoc
 	 */
-	get _instance() {
+	get _item() {
 		return this._editor;
 	}
 
@@ -201,8 +201,9 @@ export default class EditorWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Destroys the current editor instance by using the destructor passed to the {@link #setDestructor `setDestructor()`} method
-	 * and sets state to `destroyed`.
+	 * Destroys the watchdog and the current editor instance. It fires the callback
+	 * registered in {@link #setDestructor `setDestructor()`} and uses it to destroy the editor instance.
+	 * It also sets state to `destroyed`.
 	 *
 	 * @returns {Promise}
 	 */
@@ -295,7 +296,7 @@ export default class EditorWatchdog extends Watchdog {
 	 * @protected
 	 * @param {module:utils/ckeditorerror~CKEditorError} error
 	 */
-	_isErrorComingFromThisInstance( error ) {
+	_isErrorComingFromThisItem( error ) {
 		return areConnectedThroughProperties( this._editor, error.context, this._excludedProps );
 	}
 

+ 27 - 26
packages/ckeditor5-watchdog/src/watchdog.js

@@ -43,14 +43,14 @@ export default class Watchdog extends SimpleEventEmitter {
 		this.crashes = [];
 
 		/**
-		 * Specifies the state of the instance handled by the watchdog. The state can be one of the following values:
+		 * Specifies the state of the watchdog item handled by the watchdog. The state can be one of the following values:
 		 *
-		 * * `initializing` - before the first initialization, and after crashes, before the instance is ready,
-		 * * `ready` - a state when a user can interact with the instance,
+		 * * `initializing` - before the first initialization, and after crashes, before the item is ready,
+		 * * `ready` - a state when a user can interact with the item,
 		 * * `crashed` - a state when an error occurs - it quickly changes to `initializing` or `crashedPermanently`
 		 * depending on how many and how frequency errors have been caught recently,
 		 * * `crashedPermanently` - a state when the watchdog stops reacting to errors and keeps the item it is watching crashed,
-		 * * `destroyed` - a state when the instance is manually destroyed by the user after calling `watchdog.destroy()`
+		 * * `destroyed` - a state when the item is manually destroyed by the user after calling `watchdog.destroy()`
 		 *
 		 * @public
 		 * @member {'initializing'|'ready'|'crashed'|'crashedPermanently'|'destroyed'} #state
@@ -80,7 +80,7 @@ export default class Watchdog extends SimpleEventEmitter {
 		this._minimumNonErrorTimePeriod = typeof config.minimumNonErrorTimePeriod === 'number' ? config.minimumNonErrorTimePeriod : 5000;
 
 		/**
-		 * Checks if the event error comes from the underlying instance and restarts the instance.
+		 * Checks if the event error comes from the underlying item and restarts the item.
 		 *
 		 * @private
 		 * @type {Function}
@@ -120,15 +120,15 @@ export default class Watchdog extends SimpleEventEmitter {
 		 */
 
 		/**
-		 * The handled instance.
+		 * The handled watchdog item.
 		 *
 		 * @abstract
 		 * @protected
-		 * @member {Object|undefined} #_instance
+		 * @member {Object|undefined} #_item
 		 */
 
 		/**
-		 * The method responsible for the instance restarting.
+		 * The method responsible for the watchdog item restarting.
 		 *
 		 * @abstract
 		 * @protected
@@ -136,29 +136,30 @@ export default class Watchdog extends SimpleEventEmitter {
 		 */
 
 		/**
-		 * Traverses the error context and the handled instance to find out whether the error should
-		 * be handled by the given instance.
+		 * Traverses the error context and the handled watchdog item to find out whether the error should
+		 * be handled by the given item.
 		 *
 		 * @abstract
 		 * @protected
-		 * @method #_isErrorComingFromThisInstance
+		 * @method #_isErrorComingFromThisItem
 		 * @param {module:utils/ckeditorerror~CKEditorError} error
 		 */
 	}
 
 	/**
-	 * Sets the function that is responsible for the instance creation.
+	 * Sets the function that is responsible for the watchdog item creation.
 	 *
-	 * @param {Function} creator A callback returning promise that is responsible for instance creation.
+	 * @param {Function} creator A callback responsible for creating an item. Returns a promise
+	 * that is resolved when the item is created.
 	 */
 	setCreator( creator ) {
 		this._creator = creator;
 	}
 
 	/**
-	 * Sets the function that is responsible for the instance destruction.
+	 * Sets the function that is responsible for the watchdog item destruction.
 	 *
-	 * @param {Function} destructor A callback that takes the instance and returns the promise
+	 * @param {Function} destructor A callback that takes the item and returns the promise
 	 * to the destroying process.
 	 */
 	setDestructor( destructor ) {
@@ -195,8 +196,8 @@ export default class Watchdog extends SimpleEventEmitter {
 	}
 
 	/**
-	 * Checks if the error comes from the instance that is handled by the watchdog  and
-	 * restarts it. It reacts to {@link module:utils/ckeditorerror~CKEditorError `CKEditorError` errors} only.
+	 * Checks if the error comes from the watchdog item and restarts it.
+	 * It reacts to {@link module:utils/ckeditorerror~CKEditorError `CKEditorError` errors} only.
 	 *
 	 * @private
 	 * @fires error
@@ -205,7 +206,7 @@ export default class Watchdog extends SimpleEventEmitter {
 	 */
 	_handleError( error, evt ) {
 		// @if CK_DEBUG // if ( error.is && error.is( 'CKEditorError' ) && error.context === undefined ) {
-		// @if CK_DEBUG // console.warn( 'The error is missing its context and Watchdog cannot restart the proper instance.' );
+		// @if CK_DEBUG // console.warn( 'The error is missing its context and Watchdog cannot restart the proper item.' );
 		// @if CK_DEBUG // }
 
 		if ( this._shouldReactToError( error ) ) {
@@ -247,19 +248,19 @@ export default class Watchdog extends SimpleEventEmitter {
 			error.is( 'CKEditorError' ) &&
 			error.context !== undefined &&
 
-			// In some cases the instance should not be restarted - e.g. during the instance initialization.
+			// In some cases the watchdog item should not be restarted - e.g. during the item initialization.
 			// That's why the `null` was introduced as a correct error context which does cause restarting.
 			error.context !== null &&
 
 			// Do not react to errors if the watchdog is in states other than `ready`.
 			this.state === 'ready' &&
 
-			this._isErrorComingFromThisInstance( error )
+			this._isErrorComingFromThisItem( error )
 		);
 	}
 
 	/**
-	 * Checks if the watchdog should restart the underlying instance.
+	 * Checks if the watchdog should restart the underlying item.
 	 */
 	_shouldRestart() {
 		if ( this.crashes.length <= this._crashNumberLimit ) {
@@ -291,14 +292,14 @@ export default class Watchdog extends SimpleEventEmitter {
  *
  * @typedef {Object} WatchdogConfig
  *
- * @property {Number} [crashNumberLimit=3] A threshold specifying the number of instance crashes
- * when the watchdog stops restarting the instance in case of errors.
+ * @property {Number} [crashNumberLimit=3] A threshold specifying the number of watchdog item crashes
+ * when the watchdog stops restarting the item in case of errors.
  * After this limit is reached and the time between last errors is shorter than `minimumNonErrorTimePeriod`
- * the watchdog changes its state to `crashedPermanently` and it stops restarting the instance. This prevents an infinite restart loop.
+ * the watchdog changes its state to `crashedPermanently` and it stops restarting the item. This prevents an infinite restart loop.
  *
- * @property {Number} [minimumNonErrorTimePeriod=5000] An average amount of milliseconds between last instance errors
+ * @property {Number} [minimumNonErrorTimePeriod=5000] An average amount of milliseconds between last watchdog item errors
  * (defaults to 5000). When the period of time between errors is lower than that and the `crashNumberLimit` is also reached
- * the watchdog changes its state to `crashedPermanently` and it stops restarting the instance. This prevents an infinite restart loop.
+ * the watchdog changes its state to `crashedPermanently` and it stops restarting the item. This prevents an infinite restart loop.
  *
  * @property {Number} [saveInterval=5000] A minimum number of milliseconds between saving editor data internally, (defaults to 5000).
  * Note that for large documents this might have an impact on the editor performance.

+ 26 - 26
packages/ckeditor5-watchdog/tests/contextwatchdog.js

@@ -346,7 +346,7 @@ describe( 'ContextWatchdog', () => {
 			await watchdog.destroy();
 		} );
 
-		it( 'should return the created items instances with ContextWatchdog#get( itemId )', async () => {
+		it( 'should return the created items instances with ContextWatchdog#getItem( itemId )', async () => {
 			watchdog = new ContextWatchdog( Context );
 
 			watchdog.create();
@@ -365,16 +365,16 @@ describe( 'ContextWatchdog', () => {
 				config: {}
 			} ] );
 
-			expect( watchdog.get( 'editor1' ) ).to.be.instanceOf( ClassicTestEditor );
-			expect( watchdog.get( 'editor2' ) ).to.be.instanceOf( ClassicTestEditor );
+			expect( watchdog.getItem( 'editor1' ) ).to.be.instanceOf( ClassicTestEditor );
+			expect( watchdog.getItem( 'editor2' ) ).to.be.instanceOf( ClassicTestEditor );
 
 			await watchdog.remove( 'editor1' );
 
 			expect( () => {
-				watchdog.get( 'editor1' );
+				watchdog.getItem( 'editor1' );
 			} ).to.throw( /Item with the given id was not registered: editor1\./ );
 
-			expect( watchdog.get( 'editor2' ) ).to.be.instanceOf( ClassicTestEditor );
+			expect( watchdog.getItem( 'editor2' ) ).to.be.instanceOf( ClassicTestEditor );
 
 			await watchdog.destroy();
 		} );
@@ -404,7 +404,7 @@ describe( 'ContextWatchdog', () => {
 
 				sinon.assert.calledOnce( restartSpy );
 
-				expect( watchdog.getState( 'editor1' ) ).to.equal( 'ready' );
+				expect( watchdog.getItemState( 'editor1' ) ).to.equal( 'ready' );
 				expect( watchdog.context ).to.not.equal( oldContext );
 
 				await watchdog.destroy();
@@ -426,7 +426,7 @@ describe( 'ContextWatchdog', () => {
 				const oldContext = watchdog.context;
 				const restartSpy = sinon.spy();
 
-				const oldEditor = watchdog.get( 'editor1' );
+				const oldEditor = watchdog.getItem( 'editor1' );
 
 				watchdog.on( 'restart', restartSpy );
 
@@ -438,7 +438,7 @@ describe( 'ContextWatchdog', () => {
 
 				expect( watchdog.context ).to.equal( oldContext );
 
-				expect( watchdog.get( 'editor1' ) ).to.not.equal( oldEditor );
+				expect( watchdog.getItem( 'editor1' ) ).to.not.equal( oldEditor );
 
 				await watchdog.destroy();
 			} );
@@ -464,11 +464,11 @@ describe( 'ContextWatchdog', () => {
 
 				const oldContext = watchdog.context;
 
-				const editorWatchdog1 = watchdog._watchdogs.get( 'editor1' );
-				const editorWatchdog2 = watchdog._watchdogs.get( 'editor2' );
+				const editorWatchdog1 = watchdog._getWatchdog( 'editor1' );
+				const editorWatchdog2 = watchdog._getWatchdog( 'editor2' );
 
-				const oldEditor1 = watchdog.get( 'editor1' );
-				const oldEditor2 = watchdog.get( 'editor2' );
+				const oldEditor1 = watchdog.getItem( 'editor1' );
+				const oldEditor2 = watchdog.getItem( 'editor2' );
 
 				const mainWatchdogRestartSpy = sinon.spy();
 				const editorWatchdog1RestartSpy = sinon.spy();
@@ -487,8 +487,8 @@ describe( 'ContextWatchdog', () => {
 				sinon.assert.notCalled( mainWatchdogRestartSpy );
 				sinon.assert.notCalled( editorWatchdog2RestartSpy );
 
-				expect( watchdog.getState( 'editor1' ) ).to.equal( 'ready' );
-				expect( watchdog.getState( 'editor2' ) ).to.equal( 'ready' );
+				expect( watchdog.getItemState( 'editor1' ) ).to.equal( 'ready' );
+				expect( watchdog.getItemState( 'editor2' ) ).to.equal( 'ready' );
 				expect( watchdog.state ).to.equal( 'ready' );
 
 				expect( oldEditor1 ).to.not.equal( editorWatchdog1.editor );
@@ -518,7 +518,7 @@ describe( 'ContextWatchdog', () => {
 					config: {}
 				} ] );
 
-				const editor1 = watchdog.get( 'editor1' );
+				const editor1 = watchdog.getItem( 'editor1' );
 
 				const removePromise = watchdog.remove( 'editor1' );
 
@@ -527,8 +527,8 @@ describe( 'ContextWatchdog', () => {
 				await waitCycle();
 				await removePromise;
 
-				expect( [ ...watchdog._watchdogs.keys() ] ).to.include( 'editor2' );
-				expect( [ ...watchdog._watchdogs.keys() ] ).to.not.include( 'editor1' );
+				expect( Array.from( watchdog._watchdogs.keys() ) ).to.include( 'editor2' );
+				expect( Array.from( watchdog._watchdogs.keys() ) ).to.not.include( 'editor1' );
 
 				await watchdog.destroy();
 			} );
@@ -552,14 +552,14 @@ describe( 'ContextWatchdog', () => {
 					config: {}
 				} ] );
 
-				setTimeout( () => throwCKEditorError( 'foo', watchdog.get( 'editor1' ) ) );
-				setTimeout( () => throwCKEditorError( 'foo', watchdog.get( 'editor1' ) ) );
-				setTimeout( () => throwCKEditorError( 'foo', watchdog.get( 'editor1' ) ) );
-				setTimeout( () => throwCKEditorError( 'foo', watchdog.get( 'editor1' ) ) );
+				setTimeout( () => throwCKEditorError( 'foo', watchdog.getItem( 'editor1' ) ) );
+				setTimeout( () => throwCKEditorError( 'foo', watchdog.getItem( 'editor1' ) ) );
+				setTimeout( () => throwCKEditorError( 'foo', watchdog.getItem( 'editor1' ) ) );
+				setTimeout( () => throwCKEditorError( 'foo', watchdog.getItem( 'editor1' ) ) );
 
 				await waitCycle();
 
-				expect( watchdog.getState( 'editor1' ) ).to.equal( 'crashedPermanently' );
+				expect( watchdog.getItemState( 'editor1' ) ).to.equal( 'crashedPermanently' );
 				expect( watchdog.state ).to.equal( 'ready' );
 
 				await watchdog.destroy();
@@ -586,11 +586,11 @@ describe( 'ContextWatchdog', () => {
 							return data.itemId === 'editor1';
 						} ) )
 						.callsFake( () => {
-							expect( watchdog.get( 'editor1' ).state ).to.equal( 'crashed' );
+							expect( watchdog.getItemState( 'editor1' ) ).to.equal( 'crashed' );
 						} )
 				);
 
-				setTimeout( () => throwCKEditorError( 'foo', watchdog.get( 'editor1' ) ) );
+				setTimeout( () => throwCKEditorError( 'foo', watchdog.getItem( 'editor1' ) ) );
 
 				await waitCycle();
 
@@ -620,11 +620,11 @@ describe( 'ContextWatchdog', () => {
 							return data.itemId === 'editor1';
 						} ) )
 						.callsFake( () => {
-							expect( watchdog.get( 'editor1' ).state ).to.equal( 'ready' );
+							expect( watchdog.getItemState( 'editor1' ) ).to.equal( 'ready' );
 						} )
 				);
 
-				setTimeout( () => throwCKEditorError( 'foo', watchdog.get( 'editor1' ) ) );
+				setTimeout( () => throwCKEditorError( 'foo', watchdog.getItem( 'editor1' ) ) );
 
 				await waitCycle();
 

+ 1 - 1
packages/ckeditor5-watchdog/tests/editorwatchdog.js

@@ -474,7 +474,7 @@ describe( 'EditorWatchdog', () => {
 
 			sinon.assert.calledWithExactly(
 				console.warn,
-				'The error is missing its context and Watchdog cannot restart the proper instance.'
+				'The error is missing its context and Watchdog cannot restart the proper item.'
 			);
 
 			await watchdog.destroy();

+ 1 - 1
packages/ckeditor5-watchdog/tests/watchdog.js

@@ -16,7 +16,7 @@ describe( 'Watchdog', () => {
 	it( 'should be created using the inheritance', () => {
 		class FooWatchdog extends Watchdog {
 			_restart() {}
-			_isErrorComingFromThisInstance() {}
+			_isErrorComingFromThisItem() {}
 		}
 
 		expect( () => {