Bladeren bron

Merge branch 'master' into i/6091

Kamil Piechaczek 5 jaren geleden
bovenliggende
commit
bd1023cfa7

+ 13 - 0
packages/ckeditor5-watchdog/CHANGELOG.md

@@ -1,6 +1,19 @@
 Changelog
 =========
 
+## [17.0.0](https://github.com/ckeditor/ckeditor5-watchdog/compare/v16.0.0...v17.0.0) (2020-02-19)
+
+### MAJOR BREAKING CHANGES
+
+* The `Watchdog` class was renamed to `EditorWatchdog` and is available in `src/editorwatchdog.js`.
+* The `EditorWatchdog.for()` method was removed in favor of the constructor.
+* The `EditorWatchdog#constructor()` API changed. Now the `EditorWatchdog` constructor accepts the editor class as the first argument and the watchdog configuration as the second argument. The `EditorWatchdog` editor creator now defaults to `( sourceElementOrData, config ) => Editor.create( sourceElementOrData, config )`.
+
+### Features
+
+* Introduced `ContextWatchdog` which is a watchdog for `Context`. Closes [ckeditor/ckeditor5#6079](https://github.com/ckeditor/ckeditor5/issues/6079). Closes [ckeditor/ckeditor5#6042](https://github.com/ckeditor/ckeditor5/issues/6042). Closes [ckeditor/ckeditor5#4696](https://github.com/ckeditor/ckeditor5/issues/4696). ([76c4938](https://github.com/ckeditor/ckeditor5-watchdog/commit/76c4938))
+
+
 ## [16.0.0](https://github.com/ckeditor/ckeditor5-watchdog/compare/v15.0.0...v16.0.0) (2019-12-04)
 
 ### Bug fixes

+ 1 - 1
packages/ckeditor5-watchdog/docs/api/watchdog.md

@@ -14,7 +14,7 @@ See the {@link features/watchdog Watchdog feature} guide and the {@link module:w
 
 ## Installation
 
-```bash
+```
 npm install --save @ckeditor/ckeditor5-watchdog
 ```
 

+ 6 - 6
packages/ckeditor5-watchdog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-watchdog",
-  "version": "16.0.0",
+  "version": "17.0.0",
   "description": "A watchdog feature for CKEditor 5 editors. It keeps a CKEditor 5 editor instance running.",
   "keywords": [
     "ckeditor",
@@ -12,11 +12,11 @@
     "lodash-es": "^4.17.10"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-core": "^16.0.0",
-    "@ckeditor/ckeditor5-editor-classic": "^16.0.0",
-    "@ckeditor/ckeditor5-engine": "^16.0.0",
-    "@ckeditor/ckeditor5-paragraph": "^16.0.0",
-    "@ckeditor/ckeditor5-utils": "^16.0.0",
+    "@ckeditor/ckeditor5-core": "^17.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^17.0.0",
+    "@ckeditor/ckeditor5-engine": "^17.0.0",
+    "@ckeditor/ckeditor5-paragraph": "^17.0.0",
+    "@ckeditor/ckeditor5-utils": "^17.0.0",
     "eslint": "^5.5.0",
     "eslint-config-ckeditor5": "^2.0.0",
     "husky": "^2.4.1",

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

@@ -24,7 +24,7 @@ import getSubNodes from './utils/getsubnodes';
  */
 export default class ContextWatchdog extends Watchdog {
 	/**
-	 * The `ContextWatchdog` class constructor.
+	 * The context watchdog class constructor.
 	 *
 	 * 	const watchdog = new ContextWatchdog( Context );
 	 *
@@ -32,7 +32,7 @@ export default class ContextWatchdog extends Watchdog {
 	 *
 	 * 	await watchdog.add( item );
 	 *
-	 * See {@glink features/watchdog the watchdog feature guide} to learn more how to use this feature.
+	 * See the {@glink features/watchdog Watchdog feature guide} to learn more how to use this feature.
 	 *
 	 * @param {Function} Context The {@link module:core/context~Context} class.
 	 * @param {module:watchdog/watchdog~WatchdogConfig} [watchdogConfig] The watchdog configuration.
@@ -65,8 +65,8 @@ export default class ContextWatchdog extends Watchdog {
 		this._context = null;
 
 		/**
-		 * Context props (nodes/references) that are gathered during the initial context creation
-		 * and are used to distinguish error origin.
+		 * Context properties (nodes/references) that are gathered during the initial context creation
+		 * and are used to distinguish the origin of an error.
 		 *
 		 * @private
 		 * @type {Set.<*>}
@@ -82,7 +82,7 @@ export default class ContextWatchdog extends Watchdog {
 		this._actionQueue = new ActionQueue();
 
 		/**
-		 * Config for the {@link module:core/context~Context}.
+		 * The configuration for the {@link module:core/context~Context}.
 		 *
 		 * @private
 		 * @member {Object} #_contextConfig
@@ -137,7 +137,7 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * The context instance. Keep in mind that this property might be changed when the `ContextWatchdog` restarts,
+	 * The context instance. Keep in mind that this property might be changed when the context watchdog restarts,
 	 * so do not keep this instance internally. Always operate on the `ContextWatchdog#context` property.
 	 *
 	 * @type {module:core/context~Context|null}
@@ -147,14 +147,14 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Initializes the context watchdog. Once it's created the watchdog takes care about
-	 * recreating the context and provided items and starts the error handling mechanism.
+	 * Initializes the context watchdog. Once it is created, the watchdog takes care about
+	 * recreating the context and the provided items, and starts the error handling mechanism.
 	 *
 	 * 	await watchdog.create( {
 	 * 		plugins: []
 	 * 	} );
 	 *
-	 * @param {Object} [contextConfig] Context configuration. See {@link module:core/context~Context}.
+	 * @param {Object} [contextConfig] The context configuration. See {@link module:core/context~Context}.
 	 * @returns {Promise}
 	 */
 	create( contextConfig = {} ) {
@@ -166,12 +166,12 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Returns the item instance with the given `itemId`.
+	 * Returns an item instance with the given `itemId`.
 	 *
 	 * 	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.
+	 * @param {String} itemId The item ID.
+	 * @returns {*} The item instance or `undefined` if an item with a given ID has not been found.
 	 */
 	getItem( itemId ) {
 		const watchdog = this._getWatchdog( itemId );
@@ -180,11 +180,11 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Gets state of the given item. For the list of available states see {@link #state}.
+	 * Gets the state of the given item. See {@link #state} for a list of available states.
 	 *
 	 * 	const editor1State = watchdog.getItemState( 'editor1' );
 	 *
-	 * @param {String} itemId Item id.
+	 * @param {String} itemId Item ID.
 	 * @returns {'initializing'|'ready'|'crashed'|'crashedPermanently'|'destroyed'} The state of the item.
 	 */
 	getItemState( itemId ) {
@@ -222,15 +222,15 @@ export default class ContextWatchdog extends Watchdog {
 	 *		creator: ( element, config ) => ClassicEditor.create( element, config )
 	 *	] );
 	 *
-	 * And then the instance can be retrieved using the {@link #getItem} method:
+	 * Then an instance can be retrieved using the {@link #getItem} method:
 	 *
 	 * 	const editor1 = watchdog.getItem( 'editor1' );
 	 *
-	 * Note that this method can be called multiple times, but for performance reasons it's better
+	 * Note that this method can be called multiple times, but for performance reasons it is better
 	 * to pass all items together.
 	 *
 	 * @param {module:watchdog/contextwatchdog~WatchdogItemConfiguration|Array.<module:watchdog/contextwatchdog~WatchdogItemConfiguration>}
-	 * itemConfigurationOrItemConfigurations Item configuration object or an array of item configurations.
+	 * itemConfigurationOrItemConfigurations An item configuration object or an array of item configurations.
 	 * @returns {Promise}
 	 */
 	add( itemConfigurationOrItemConfigurations ) {
@@ -298,7 +298,7 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Removes and destroys item(s) with given id(s).
+	 * Removes and destroys item(s) with given ID(s).
 	 *
 	 * 	await watchdog.remove( 'editor1' );
 	 *
@@ -306,7 +306,7 @@ export default class ContextWatchdog extends Watchdog {
 	 *
 	 * 	await watchdog.remove( [ 'editor1', 'editor2' ] );
 	 *
-	 * @param {Array.<String>|String} itemIdOrItemIds Item id or an array of item ids.
+	 * @param {Array.<String>|String} itemIdOrItemIds Item ID or an array of item IDs.
 	 * @returns {Promise}
 	 */
 	remove( itemIdOrItemIds ) {
@@ -326,8 +326,8 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Destroys the `ContextWatchdog` and all added items.
-	 * Once the `ContextWatchdog` is destroyed new items can not be added.
+	 * Destroys the context watchdog and all added items.
+	 * Once the context watchdog is destroyed, new items cannot be added.
 	 *
 	 * 	await watchdog.destroy();
 	 *
@@ -345,7 +345,7 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Restarts the `ContextWatchdog`.
+	 * Restarts the context watchdog.
 	 *
 	 * @protected
 	 * @returns {Promise}
@@ -391,7 +391,7 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Destroys the `Context` instance and all added items.
+	 * Destroys the context instance and all added items.
 	 *
 	 * @private
 	 * @returns {Promise}
@@ -416,10 +416,10 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Returns watchdog for the given item id.
+	 * Returns the watchdog for a given item ID.
 	 *
 	 * @protected
-	 * @param {String} itemId Item id.
+	 * @param {String} itemId Item ID.
 	 * @returns {module:watchdog/watchdog~Watchdog} Watchdog
 	 */
 	_getWatchdog( itemId ) {
@@ -433,7 +433,7 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Checks whether the error comes from the `Context` instance and not from the item instances.
+	 * Checks whether an error comes from the context instance and not from the item instances.
 	 *
 	 * @protected
 	 * @param {Error} error
@@ -450,7 +450,7 @@ export default class ContextWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Fired after the watchdog restarts context and added items because of the crash.
+	 * Fired after the watchdog restarts the context and the added items because of a crash.
 	 *
 	 * 	watchdog.on( 'restart', () => {
 	 * 		console.log( 'The context has been restarted.' );
@@ -463,7 +463,7 @@ export default class ContextWatchdog extends Watchdog {
 	 * Fired when a new error occurred in one of the added items.
 	 *
 	 * 	watchdog.on( 'itemError', ( evt, { error, itemId, causesRestart } ) => {
-	 *		console.log( `An error occurred in an item with the '${ itemId }' id.` );
+	 *		console.log( `An error occurred in an item with the '${ itemId }' ID.` );
 	 * 	} );
 	 *
 	 * @event itemError
@@ -473,7 +473,7 @@ export default class ContextWatchdog extends Watchdog {
 	 * Fired after an item has been restarted.
 	 *
 	 * 	watchdog.on( 'itemRestart', ( evt, { itemId } ) => {
-	 *		console.log( 'An item with with the '${ itemId }' id has been restarted.' );
+	 *		console.log( 'An item with with the '${ itemId }' ID has been restarted.' );
 	 * 	} );
 	 *
 	 * @event itemRestart
@@ -520,27 +520,27 @@ class ActionQueue {
 }
 
 /**
- * The `WatchdogItemConfiguration` interface.
+ * The watchdog item configuration interface.
  *
  * @typedef {module:watchdog/contextwatchdog~EditorWatchdogConfiguration} module:watchdog/contextwatchdog~WatchdogItemConfiguration
  */
 
 /**
- * The `EditorWatchdogConfiguration` interface specifies how editors should be created and destroyed.
+ * The editor watchdog configuration interface specifies how editors should be created and destroyed.
  *
  * @typedef {Object} module:watchdog/contextwatchdog~EditorWatchdogConfiguration
  *
  * @property {String} id A unique item identificator.
  *
- * @property {'editor'} type Type of the item to create. At the moment, only `'editor'` is supported.
+ * @property {'editor'} type The type of the item to create. At the moment, only `'editor'` is supported.
  *
  * @property {Function} creator A function that initializes the item (the editor). The function takes editor initialization arguments
- * and should return a promise. E.g. `( el, config ) => ClassicEditor.create( el, config )`.
+ * and should return a promise. For example: `( el, config ) => ClassicEditor.create( el, config )`.
  *
  * @property {Function} [destructor] A function that destroys the item instance (the editor). The function
- * takes an item and should return a promise. E.g. `editor => editor.destroy()`
+ * takes an item and should return a promise. For example: `editor => editor.destroy()`
  *
- * @property {String|HTMLElement} sourceElementOrData The source element or data which will be passed
+ * @property {String|HTMLElement} sourceElementOrData The source element or data that will be passed
  * as the first argument to the `Editor.create()` method.
  *
  * @property {Object} config An editor configuration.

+ 7 - 7
packages/ckeditor5-watchdog/src/editorwatchdog.js

@@ -164,10 +164,10 @@ export default class EditorWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Creates and keep running the editor instance using the defined creator and destructor.
+	 * Creates the editor instance and keeps it running, using the defined creator and destructor.
 	 *
-	 * @param {HTMLElement|String|Object.<String|String>} [elementOrData] Editor's source element or the editor's data.
-	 * @param {module:core/editor/editorconfig~EditorConfig} [config] Editor configuration.
+	 * @param {HTMLElement|String|Object.<String|String>} [elementOrData] The editor source element or the editor data.
+	 * @param {module:core/editor/editorconfig~EditorConfig} [config] The editor configuration.
 	 * @param {Object} [context] A context for the editor.
 	 *
 	 * @returns {Promise}
@@ -203,7 +203,7 @@ export default class EditorWatchdog extends Watchdog {
 	/**
 	 * 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`.
+	 * It also sets the state to `destroyed`.
 	 *
 	 * @returns {Promise}
 	 */
@@ -290,8 +290,8 @@ export default class EditorWatchdog extends Watchdog {
 	}
 
 	/**
-	 * Traverses error context and the current editor to find out whether these structures are connected
-	 * via properties to each other.
+	 * Traverses the error context and the current editor to find out whether these structures are connected
+	 * to each other via properties.
 	 *
 	 * @protected
 	 * @param {module:utils/ckeditorerror~CKEditorError} error
@@ -301,7 +301,7 @@ export default class EditorWatchdog extends Watchdog {
 	}
 
 	/**
-	 * A function used to clone the editor configuration
+	 * Clones the editor configuration.
 	 *
 	 * @private
 	 * @param {Object} config

+ 24 - 24
packages/ckeditor5-watchdog/src/watchdog.js

@@ -41,12 +41,12 @@ export default class Watchdog {
 		/**
 		 * Specifies the state of the item watched by the watchdog. The state can be one of the following values:
 		 *
-		 * * `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 item is manually destroyed by the user after calling `watchdog.destroy()`
+		 * * `initializing` &ndash; Before the first initialization, and after crashes, before the item is ready.
+		 * * `ready` &ndash; A state when the user can interact with the item.
+		 * * `crashed` &ndash; A state when an error occurs. It quickly changes to `initializing` or `crashedPermanently`
+		 * depending on how many and how frequent errors have been caught recently.
+		 * * `crashedPermanently` &ndash; A state when the watchdog stops reacting to errors and keeps the item it is watching crashed,
+		 * * `destroyed` &ndash; A state when the item is manually destroyed by the user after calling `watchdog.destroy()`.
 		 *
 		 * @public
 		 * @member {'initializing'|'ready'|'crashed'|'crashedPermanently'|'destroyed'} #state
@@ -61,8 +61,8 @@ export default class Watchdog {
 		this._crashNumberLimit = typeof config.crashNumberLimit === 'number' ? config.crashNumberLimit : 3;
 
 		/**
-		 * Returns the result of `Date.now()` call. It can be overridden in tests to mock time as the popular
-		 * approaches like `sinon.useFakeTimers()` does not work well with error handling.
+		 * Returns the result of the `Date.now()` call. It can be overridden in tests to mock time as some popular
+		 * approaches like `sinon.useFakeTimers()` do not work well with error handling.
 		 *
 		 * @protected
 		 */
@@ -151,7 +151,7 @@ export default class Watchdog {
 	}
 
 	/**
-	 * Sets the function that is responsible for creating watchded items.
+	 * Sets the function that is responsible for creating watched items.
 	 *
 	 * @param {Function} creator A callback responsible for creating an item. Returns a promise
 	 * that is resolved when the item is created.
@@ -161,7 +161,7 @@ export default class Watchdog {
 	}
 
 	/**
-	 * Sets the function that is responsible for destructing watched items.
+	 * Sets the function that is responsible for destroying watched items.
 	 *
 	 * @param {Function} destructor A callback that takes the item and returns the promise
 	 * to the destroying process.
@@ -180,12 +180,12 @@ export default class Watchdog {
 	}
 
 	/**
-	 * Starts listening to the specific event name by registering a callback that will be executed
-	 * whenever an event with given name fires.
+	 * Starts listening to a specific event name by registering a callback that will be executed
+	 * whenever an event with a given name fires.
 	 *
 	 * Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.
 	 *
-	 * @param {String} eventName  Event name.
+	 * @param {String} eventName The event name.
 	 * @param {Function} callback A callback which will be added to event listeners.
 	 */
 	on( eventName, callback ) {
@@ -201,7 +201,7 @@ export default class Watchdog {
 	 *
 	 * Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.
 	 *
-	 * @param {String} eventName Event name.
+	 * @param {String} eventName The event name.
 	 * @param {Function} callback A callback which will be removed from event listeners.
 	 */
 	off( eventName, callback ) {
@@ -210,12 +210,12 @@ export default class Watchdog {
 	}
 
 	/**
-	 * Fires an event with given event name and arguments.
+	 * Fires an event with a given event name and arguments.
 	 *
 	 * Note that this method differs from the CKEditor 5's default `EventEmitterMixin` implementation.
 	 *
 	 * @protected
-	 * @param {String} eventName Event name.
+	 * @param {String} eventName The event name.
 	 * @param  {...*} args Event arguments.
 	 */
 	_fire( eventName, ...args ) {
@@ -247,13 +247,13 @@ export default class Watchdog {
 	}
 
 	/**
-	 * Checks if the error comes from the watched item and restarts it.
+	 * Checks if an error comes from the watched item and restarts it.
 	 * It reacts to {@link module:utils/ckeditorerror~CKEditorError `CKEditorError` errors} only.
 	 *
 	 * @private
 	 * @fires error
 	 * @param {Error} error Error.
-	 * @param {ErrorEvent|PromiseRejectionEvent} evt Error event.
+	 * @param {ErrorEvent|PromiseRejectionEvent} evt An error event.
 	 */
 	_handleError( error, evt ) {
 		// @if CK_DEBUG // if ( error.is && error.is( 'CKEditorError' ) && error.context === undefined ) {
@@ -288,7 +288,7 @@ export default class Watchdog {
 	}
 
 	/**
-	 * Checks whether the error should be handled by the watchdog.
+	 * Checks whether an error should be handled by the watchdog.
 	 *
 	 * @private
 	 * @param {Error} error An error that was caught by the error handling process.
@@ -347,13 +347,13 @@ export default class Watchdog {
  *
  * @property {Number} [crashNumberLimit=3] A threshold specifying the number of watched 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`
+ * After this limit is reached and the time between the last errors is shorter than `minimumNonErrorTimePeriod`,
  * 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 watched item errors
- * (defaults to 5000). When the period of time between errors is lower than that and the `crashNumberLimit` is also reached
+ * @property {Number} [minimumNonErrorTimePeriod=5000] An average number of milliseconds between the last watched 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 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.
+ * @property {Number} [saveInterval=5000] A minimum number of milliseconds between saving the editor data internally (defaults to 5000).
+ * Note that for large documents this might impact the editor performance.
  */