Merge pull request #11755 from ckeditor/ck/11715-typescript-in-utils

Other (utils): Rewrites ckeditor5-utils in TypeScript. Closes #11715.

.gitignore

@@ -13,5 +13,9 @@ yarn.lock
 # Ignore `mrgit.json` this file contains info about external repositories.
 mrgit.json
 
+# Ignore yalc
+.yalc
+yalc.lock
+
 build/
 !packages/ckeditor5-build-*/build

packages/ckeditor5-editor-inline/src/inlineeditoruiview.js

@@ -116,7 +116,7 @@ export default class InlineEditorUIView extends EditorUIView {
 		 * See: {@link module:utils/dom/position~Options#positions}.
 		 *
 		 * @readonly
-		 * @type {Array.<module:utils/dom/position~positioningFunction>}
+		 * @type {Array.<module:utils/dom/position~PositioningFunction>}
 		 */
 		this.panelPositions = this._getPanelPositions();
 
@@ -207,7 +207,7 @@ export default class InlineEditorUIView extends EditorUIView {
 	 * See: {@link module:utils/dom/position~Options#positions}.
 	 *
 	 * @private
-	 * @returns {Array.<module:utils/dom/position~positioningFunction>}
+	 * @returns {Array.<module:utils/dom/position~PositioningFunction>}
 	 */
 	_getPanelPositions() {
 		const positions = [

packages/ckeditor5-ui/src/panel/balloon/balloonpanelview.js

@@ -756,14 +756,14 @@ BalloonPanelView._getOptimalPosition = getOptimalPosition;
  * The name that the position function returns will be reflected in the balloon panel's class that
  * controls the placement of the "arrow". See {@link #position} to learn more.
  *
- * @member {Object.<String,module:utils/dom/position~positioningFunction>}
+ * @member {Object.<String,module:utils/dom/position~PositioningFunction>}
  * module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions
  */
 BalloonPanelView.defaultPositions = generatePositions();
 
 /**
  * Returns available {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
- * {@link module:utils/dom/position~positioningFunction positioning functions} adjusted by the specific offsets.
+ * {@link module:utils/dom/position~PositioningFunction positioning functions} adjusted by the specific offsets.
  *
  * @protected
  * @param {Object} [options] Options to generate positions. If not specified, this helper will simply return
@@ -779,8 +779,8 @@ BalloonPanelView.defaultPositions = generatePositions();
  * will be used.
  * @param {Object} [options.config] Additional configuration of the balloon balloon panel view.
  * Currently only {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#withArrow} is supported. Learn more
- * about {@link module:utils/dom/position~positioningFunction positioning functions}.
- * @returns {Object.<String,module:utils/dom/position~positioningFunction>}
+ * about {@link module:utils/dom/position~PositioningFunction positioning functions}.
+ * @returns {Object.<String,module:utils/dom/position~PositioningFunction>}
  */
 export function generatePositions( {
 	horizontalOffset = BalloonPanelView.arrowHorizontalOffset,

packages/ckeditor5-upload/src/filerepository.js

@@ -17,7 +17,7 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
 
 import FileReader from './filereader.js';
 
-import uid from '@ckeditor/ckeditor5-utils/src/uid.js';
+import uid from '@ckeditor/ckeditor5-utils/src/uid';
 
 /**
  * File repository plugin. A central point for managing file upload.

packages/ckeditor5-utils/package.json

@@ -9,16 +9,21 @@
     "ckeditor5-lib",
     "ckeditor5-dll"
   ],
-  "main": "src/index.js",
+  "main": "src/index.ts",
   "dependencies": {
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
     "@ckeditor/ckeditor5-build-classic": "^34.1.0",
     "@ckeditor/ckeditor5-editor-classic": "^34.1.0",
     "@ckeditor/ckeditor5-core": "^34.1.0",
-    "@ckeditor/ckeditor5-engine": "^34.1.0"
+    "@ckeditor/ckeditor5-engine": "^34.1.0",
+    "@types/lodash-es": "^4.17.6",
+    "typescript": "^4.6.4"
   },
+  "depcheckIgnore": [
+	  "typescript"
+  ],
   "engines": {
     "node": ">=14.0.0",
     "npm": ">=5.7.1"

packages/ckeditor5-utils/src/areconnectedthroughproperties.js → packages/ckeditor5-utils/src/areconnectedthroughproperties.ts

@@ -14,8 +14,9 @@
  *
  * @param {Object|Array} obj1
  * @param {Object|Array} obj2
+ * @returns {Boolean}
  */
-export default function areConnectedThroughProperties( obj1, obj2 ) {
+export default function areConnectedThroughProperties( obj1: object, obj2: object ): boolean {
 	if ( obj1 === obj2 && isObject( obj1 ) ) {
 		return true;
 	}
@@ -35,7 +36,7 @@ export default function areConnectedThroughProperties( obj1, obj2 ) {
 // 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 ) {
+function getSubNodes( head: unknown ): Set<unknown> {
 	const nodes = [ head ];
 
 	// Nodes are stored to prevent infinite looping.
@@ -51,22 +52,22 @@ function getSubNodes( head ) {
 		subNodes.add( node );
 
 		// Handle arrays, maps, sets, custom collections that implements `[ Symbol.iterator ]()`, etc.
-		if ( node[ Symbol.iterator ] ) {
+		if ( ( node as Iterable<unknown> )[ Symbol.iterator ] ) {
 			// The custom editor iterators might cause some problems if the editor is crashed.
 			try {
-				nodes.push( ...node );
+				nodes.push( ...( node as Iterable<unknown> ) );
 			} catch ( err ) {
 				// eslint-disable-line no-empty
 			}
 		} else {
-			nodes.push( ...Object.values( node ) );
+			nodes.push( ...Object.values( node as any ) );
 		}
 	}
 
 	return subNodes;
 }
 
-function shouldNodeBeSkipped( node ) {
+function shouldNodeBeSkipped( node: unknown ): boolean {
 	const type = Object.prototype.toString.call( node );
 
 	return (
@@ -87,6 +88,6 @@ function shouldNodeBeSkipped( node ) {
 	);
 }
 
-function isObject( structure ) {
+function isObject( structure: unknown ): boolean {
 	return typeof structure === 'object' && structure !== null;
 }

packages/ckeditor5-utils/src/ckeditorerror.js → packages/ckeditor5-utils/src/ckeditorerror.ts

@@ -43,6 +43,9 @@ export const DOCUMENTATION_URL = 'https://ckeditor.com/docs/ckeditor5/latest/sup
  * @extends Error
  */
 export default class CKEditorError extends Error {
+	readonly context: object | null;
+	readonly data?: object;
+
 	/**
 	 * Creates an instance of the CKEditorError class.
 	 *
@@ -57,7 +60,7 @@ export default class CKEditorError extends Error {
 	 * 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 ) {
+	constructor( errorName: string, context: object | null, data?: object ) {
 		super( getErrorMessage( errorName, data ) );
 
 		/**
@@ -84,7 +87,7 @@ export default class CKEditorError extends Error {
 	 * Checks if the error is of the `CKEditorError` type.
 	 * @returns {Boolean}
 	 */
-	is( type ) {
+	is( type: string ): boolean {
 		return type === 'CKEditorError';
 	}
 
@@ -98,8 +101,8 @@ export default class CKEditorError extends 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' ) ) {
+	static rethrowUnexpectedError( err: Error, context: object ): never {
+		if ( ( err as any ).is && ( err as any ).is( 'CKEditorError' ) ) {
 			throw err;
 		}
 
@@ -141,7 +144,7 @@ export default class CKEditorError extends Error {
  * @param {String} errorName The error name to be logged.
  * @param {Object} [data] Additional data to be logged.
  */
-export function logWarning( errorName, data ) {
+export function logWarning( errorName: string, data?: object ): void {
 	console.warn( ...formatConsoleArguments( errorName, data ) );
 }
 
@@ -165,7 +168,7 @@ export function logWarning( errorName, data ) {
  * @param {String} errorName The error name to be logged.
  * @param {Object} [data] Additional data to be logged.
  */
-export function logError( errorName, data ) {
+export function logError( errorName: string, data?: object ): void {
 	console.error( ...formatConsoleArguments( errorName, data ) );
 }
 
@@ -174,7 +177,7 @@ export function logError( errorName, data ) {
 // @private
 // @param {String} errorName
 // @returns {string}
-function getLinkToDocumentationMessage( errorName ) {
+function getLinkToDocumentationMessage( errorName: string ): string {
 	return `\nRead more: ${ DOCUMENTATION_URL }#error-${ errorName }`;
 }
 
@@ -184,9 +187,9 @@ function getLinkToDocumentationMessage( errorName ) {
 // @param {String} errorName
 // @param {Object} [data]
 // @returns {string}
-function getErrorMessage( errorName, data ) {
+function getErrorMessage( errorName: string, data?: object ): string {
 	const processedObjects = new WeakSet();
-	const circularReferencesReplacer = ( key, value ) => {
+	const circularReferencesReplacer = ( key: string, value: unknown ) => {
 		if ( typeof value === 'object' && value !== null ) {
 			if ( processedObjects.has( value ) ) {
 				return `[object ${ value.constructor.name }]`;
@@ -210,7 +213,7 @@ function getErrorMessage( errorName, data ) {
 // @param {String} errorName
 // @param {Object} [data]
 // @returns {Array}
-function formatConsoleArguments( errorName, data ) {
+function formatConsoleArguments( errorName: string, data?: object ): unknown[] {
 	const documentationMessage = getLinkToDocumentationMessage( errorName );
 
 	return data ? [ errorName, data, documentationMessage ] : [ errorName, documentationMessage ];