@ckeditor/ckeditor5-utils 39.0.1 → 40.0.0

package/CHANGELOG.md

@@ -93,13 +93,13 @@ Internal changes only (updated dependencies, documentation, etc.).
 ### Other changes
 
 * The issue tracker for this package was moved to https://github.com/ckeditor/ckeditor5/issues. See [ckeditor/ckeditor5#1988](https://github.com/ckeditor/ckeditor5/issues/1988). ([71469ac](https://github.com/ckeditor/ckeditor5-utils/commit/71469ac))
-* Removed the CKEditor 5 logger and its usage. Part of [ckeditor/ckeditor5#383](https://github.com/ckeditor/ckeditor5/issues/383). ([584ef1d](https://github.com/ckeditor/ckeditor5-utils/commit/584ef1d))
+* Removed the CKEditor 5 logger and its usage. Part of [ckeditor/ckeditor5#383](https://github.com/ckeditor/ckeditor5/issues/383). ([584ef1d](https://github.com/ckeditor/ckeditor5-utils/commit/584ef1d))
 
 ### BREAKING CHANGES
 
 * The`Locale()` constructor arguments syntax has changed. Please refer to the API documentation to learn more.
 * The `Locale#language` property has been deprecated by `Locale#uiLanguage`. Please refer to the API documentation to learn more.
-* Removed the CKEditor 5 logger utility.
+* Removed the CKEditor 5 logger utility.
 
 
 ## [13.0.1](https://github.com/ckeditor/ckeditor5-utils/compare/v13.0.0...v13.0.1) (2019-07-10)
@@ -217,7 +217,7 @@ Internal changes only (updated dependencies, documentation, etc.).
 
 ### BREAKING CHANGES
 
-* The license under which CKEditor 5 is released has been changed from a triple GPL, LGPL and MPL license to a GPL2+ only. See [ckeditor/ckeditor5#991](https://github.com/ckeditor/ckeditor5/issues/991) for more information.
+* The license under which CKEditor 5 is released has been changed from a triple GPL, LGPL and MPL license to a GPL2+ only. See [ckeditor/ckeditor5#991](https://github.com/ckeditor/ckeditor5/issues/991) for more information.
 
 
 ## [1.0.0-beta.4](https://github.com/ckeditor/ckeditor5-utils/compare/v1.0.0-beta.2...v1.0.0-beta.4) (2018-04-19)

package/LICENSE.md

@@ -1,7 +1,7 @@
 Software License Agreement
 ==========================
 
-**CKEditor 5 utilities** – https://github.com/ckeditor/ckeditor5-utils <br>
+**CKEditor&nbsp;5 utilities** – https://github.com/ckeditor/ckeditor5-utils <br>
 Copyright (c) 2003-2023, [CKSource Holding sp. z o.o.](https://cksource.com) All rights reserved.
 
 Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html).

package/README.md

@@ -1,15 +1,15 @@
-CKEditor 5 utilities
+CKEditor 5 utilities
 ========================================
 
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-utils.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils)
 [![Coverage Status](https://coveralls.io/repos/github/ckeditor/ckeditor5/badge.svg?branch=master)](https://coveralls.io/github/ckeditor/ckeditor5?branch=master)
 [![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://app.travis-ci.com/github/ckeditor/ckeditor5)
 
-Various utilities used by CKEditor 5 and its features. This is a sort of  CKEditor 5's standard library.
+Various utilities used by CKEditor 5 and its features. This is a sort of  CKEditor 5's standard library.
 
 ## Documentation
 
-See the [`@ckeditor/ckeditor5-utils` package](https://ckeditor.com/docs/ckeditor5/latest/api/utils.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
+See the [`@ckeditor/ckeditor5-utils` package](https://ckeditor.com/docs/ckeditor5/latest/api/utils.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-utils",
-  "version": "39.0.1",
+  "version": "40.0.0",
   "description": "Miscellaneous utilities used by CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -13,10 +13,6 @@
   "dependencies": {
     "lodash-es": "4.17.21"
   },
-  "engines": {
-    "node": ">=16.0.0",
-    "npm": ">=5.7.1"
-  },
   "author": "CKSource (http://cksource.com/)",
   "license": "GPL-2.0-or-later",
   "homepage": "https://ckeditor.com/ckeditor-5",

package/src/areconnectedthroughproperties.d.ts

@@ -1,11 +1,11 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @module utils/areconnectedthroughproperties
- */
-/**
- * Traverses both structures to find out whether there is a reference that is shared between both structures.
- */
-export default function areConnectedThroughProperties(obj1: object, obj2: object): boolean;
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module utils/areconnectedthroughproperties
+ */
+/**
+ * Traverses both structures to find out whether there is a reference that is shared between both structures.
+ */
+export default function areConnectedThroughProperties(obj1: object, obj2: object): boolean;

package/src/areconnectedthroughproperties.js

@@ -1,73 +1,73 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @module utils/areconnectedthroughproperties
- */
-/* globals EventTarget, Event */
-/**
- * Traverses both structures to find out whether there is a reference that is shared between both structures.
- */
-export default function areConnectedThroughProperties(obj1, obj2) {
-    if (obj1 === obj2 && isObject(obj1)) {
-        return true;
-    }
-    const subNodes1 = getSubNodes(obj1);
-    const subNodes2 = getSubNodes(obj2);
-    for (const node of subNodes1) {
-        if (subNodes2.has(node)) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Traverses JS structure and stores all sub-nodes, including the head node.
- * It walks into each iterable structures with the `try catch` block to omit errors that might be thrown during
- * tree walking. All primitives, functions and built-ins are skipped.
- */
-function getSubNodes(head) {
-    const nodes = [head];
-    // Nodes are stored to prevent infinite looping.
-    const subNodes = new Set();
-    while (nodes.length > 0) {
-        const node = nodes.shift();
-        if (subNodes.has(node) || shouldNodeBeSkipped(node)) {
-            continue;
-        }
-        subNodes.add(node);
-        // Handle arrays, maps, sets, custom collections that implements `[ Symbol.iterator ]()`, etc.
-        if (node[Symbol.iterator]) {
-            // The custom editor iterators might cause some problems if the editor is crashed.
-            try {
-                nodes.push(...node);
-            }
-            catch (err) {
-                // eslint-disable-line no-empty
-            }
-        }
-        else {
-            nodes.push(...Object.values(node));
-        }
-    }
-    return subNodes;
-}
-function shouldNodeBeSkipped(node) {
-    const type = Object.prototype.toString.call(node);
-    return (type === '[object Number]' ||
-        type === '[object Boolean]' ||
-        type === '[object String]' ||
-        type === '[object Symbol]' ||
-        type === '[object Function]' ||
-        type === '[object Date]' ||
-        type === '[object RegExp]' ||
-        node === undefined ||
-        node === null ||
-        // Skip native DOM objects, e.g. Window, nodes, events, etc.
-        node instanceof EventTarget ||
-        node instanceof Event);
-}
-function isObject(structure) {
-    return typeof structure === 'object' && structure !== null;
-}
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module utils/areconnectedthroughproperties
+ */
+/* globals EventTarget, Event */
+/**
+ * Traverses both structures to find out whether there is a reference that is shared between both structures.
+ */
+export default function areConnectedThroughProperties(obj1, obj2) {
+    if (obj1 === obj2 && isObject(obj1)) {
+        return true;
+    }
+    const subNodes1 = getSubNodes(obj1);
+    const subNodes2 = getSubNodes(obj2);
+    for (const node of subNodes1) {
+        if (subNodes2.has(node)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Traverses JS structure and stores all sub-nodes, including the head node.
+ * It walks into each iterable structures with the `try catch` block to omit errors that might be thrown during
+ * tree walking. All primitives, functions and built-ins are skipped.
+ */
+function getSubNodes(head) {
+    const nodes = [head];
+    // Nodes are stored to prevent infinite looping.
+    const subNodes = new Set();
+    while (nodes.length > 0) {
+        const node = nodes.shift();
+        if (subNodes.has(node) || shouldNodeBeSkipped(node)) {
+            continue;
+        }
+        subNodes.add(node);
+        // Handle arrays, maps, sets, custom collections that implements `[ Symbol.iterator ]()`, etc.
+        if (node[Symbol.iterator]) {
+            // The custom editor iterators might cause some problems if the editor is crashed.
+            try {
+                nodes.push(...node);
+            }
+            catch (err) {
+                // eslint-disable-line no-empty
+            }
+        }
+        else {
+            nodes.push(...Object.values(node));
+        }
+    }
+    return subNodes;
+}
+function shouldNodeBeSkipped(node) {
+    const type = Object.prototype.toString.call(node);
+    return (type === '[object Number]' ||
+        type === '[object Boolean]' ||
+        type === '[object String]' ||
+        type === '[object Symbol]' ||
+        type === '[object Function]' ||
+        type === '[object Date]' ||
+        type === '[object RegExp]' ||
+        node === undefined ||
+        node === null ||
+        // Skip native DOM objects, e.g. Window, nodes, events, etc.
+        node instanceof EventTarget ||
+        node instanceof Event);
+}
+function isObject(structure) {
+    return typeof structure === 'object' && structure !== null;
+}

package/src/ckeditorerror.d.ts

@@ -1,123 +1,123 @@
-/**
- * @license Copyright (c) 2003-2023, 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
- */
-/**
- * URL to the documentation with error codes.
- */
-export declare 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.
-     */
-    readonly context: object | null | undefined;
-    /**
-     * The additional error data passed to the constructor. Undefined if none was passed.
-     */
-    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);
-    /**
-     * Checks if the error is of the `CKEditorError` type.
-     */
-    is(type: string): boolean;
-    /**
-     * 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.
-     */
-    static rethrowUnexpectedError(err: Error, context: object): never;
-}
-/**
- * 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 declare function logWarning(errorName: string, data?: object): void;
-/**
- * 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 declare function logError(errorName: string, data?: object): void;
+/**
+ * @license Copyright (c) 2003-2023, 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
+ */
+/**
+ * URL to the documentation with error codes.
+ */
+export declare 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.
+     */
+    readonly context: object | null | undefined;
+    /**
+     * The additional error data passed to the constructor. Undefined if none was passed.
+     */
+    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);
+    /**
+     * Checks if the error is of the `CKEditorError` type.
+     */
+    is(type: string): boolean;
+    /**
+     * 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.
+     */
+    static rethrowUnexpectedError(err: Error, context: object): never;
+}
+/**
+ * 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 declare function logWarning(errorName: string, data?: object): void;
+/**
+ * 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 declare function logError(errorName: string, data?: object): void;