@ckeditor/ckeditor5-utils 40.0.0 → 40.2.0

package/src/priorities.d.ts

@@ -1,33 +1,33 @@
-/**
- * @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/priorities
- */
-/**
- * String representing a priority value.
- */
-export type PriorityString = 'highest' | 'high' | 'normal' | 'low' | 'lowest' | number;
-/**
- * Provides group of constants to use instead of hardcoding numeric priority values.
- */
-export interface PrioritiesType {
-    /**
-     * Converts a string with priority name to it's numeric value. If `Number` is given, it just returns it.
-     *
-     * @param priority Priority to convert.
-     * @returns Converted priority.
-     */
-    get(priority?: PriorityString): number;
-    readonly highest: number;
-    readonly high: number;
-    readonly normal: number;
-    readonly low: number;
-    readonly lowest: number;
-}
-/**
- * Provides group of constants to use instead of hardcoding numeric priority values.
- */
-declare const priorities: PrioritiesType;
-export default priorities;
+/**
+ * @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/priorities
+ */
+/**
+ * String representing a priority value.
+ */
+export type PriorityString = 'highest' | 'high' | 'normal' | 'low' | 'lowest' | number;
+/**
+ * Provides group of constants to use instead of hardcoding numeric priority values.
+ */
+export interface PrioritiesType {
+    /**
+     * Converts a string with priority name to it's numeric value. If `Number` is given, it just returns it.
+     *
+     * @param priority Priority to convert.
+     * @returns Converted priority.
+     */
+    get(priority?: PriorityString): number;
+    readonly highest: number;
+    readonly high: number;
+    readonly normal: number;
+    readonly low: number;
+    readonly lowest: number;
+}
+/**
+ * Provides group of constants to use instead of hardcoding numeric priority values.
+ */
+declare const priorities: PrioritiesType;
+export default priorities;

package/src/priorities.js

@@ -1,23 +1,23 @@
-/**
- * @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
- */
-/**
- * Provides group of constants to use instead of hardcoding numeric priority values.
- */
-const priorities = {
-    get(priority = 'normal') {
-        if (typeof priority != 'number') {
-            return this[priority] || this.normal;
-        }
-        else {
-            return priority;
-        }
-    },
-    highest: 100000,
-    high: 1000,
-    normal: 0,
-    low: -1000,
-    lowest: -100000
-};
-export default priorities;
+/**
+ * @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
+ */
+/**
+ * Provides group of constants to use instead of hardcoding numeric priority values.
+ */
+const priorities = {
+    get(priority = 'normal') {
+        if (typeof priority != 'number') {
+            return this[priority] || this.normal;
+        }
+        else {
+            return priority;
+        }
+    },
+    highest: 100000,
+    high: 1000,
+    normal: 0,
+    low: -1000,
+    lowest: -100000
+};
+export default priorities;

package/src/retry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @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
+ */
+/**
+ * Tries calling the given callback until it sucessfully resolves.
+ *
+ * If the callback fails `maxRetries` times, the returned promise is rejected with the last error.
+ *
+ * @typeParam TResult The result of a successful callback invocation.
+ * @param callback The function to call until it succeeds.
+ * @param options.maxRetries Maximum number of retries.
+ * @param options.retryDelay The time in milliseconds between attempts. By default it implements exponential back-off policy.
+ * @param options.signal The signal to abort further retries. The callback itself is not aborted automatically.
+ */
+export default function retry<TResult>(callback: () => Promise<TResult>, options?: {
+    maxAttempts?: number;
+    retryDelay?: (attempt: number) => number;
+    signal?: AbortSignal;
+}): Promise<TResult>;
+/**
+ * Creates a function that calculates exponential back-off delay. Pass it as `options.retryDelay` to {@link ~retry}.
+ *
+ * @param options.delay Base delay between invocations. Defaults to 1s.
+ * @param options.factor How much to increase the delay. Defaults to 2x.
+ * @param options.maxDelay Maximum timeout. Even if higher timeout is calculated, it cannot get higher than this value. Default to 10s.
+ * @returns The function calculating the delay.
+ */
+export declare function exponentialDelay(options?: {
+    delay?: number;
+    factor?: number;
+    maxDelay?: number;
+}): (attempt: number) => number;

package/src/retry.js

@@ -0,0 +1,47 @@
+/**
+ * @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/retry
+ */
+import wait from './wait';
+/**
+ * Tries calling the given callback until it sucessfully resolves.
+ *
+ * If the callback fails `maxRetries` times, the returned promise is rejected with the last error.
+ *
+ * @typeParam TResult The result of a successful callback invocation.
+ * @param callback The function to call until it succeeds.
+ * @param options.maxRetries Maximum number of retries.
+ * @param options.retryDelay The time in milliseconds between attempts. By default it implements exponential back-off policy.
+ * @param options.signal The signal to abort further retries. The callback itself is not aborted automatically.
+ */
+export default async function retry(callback, options = {}) {
+    const { maxAttempts = 4, retryDelay = exponentialDelay(), signal = (new AbortController()).signal } = options;
+    signal.throwIfAborted();
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await callback();
+        }
+        catch (err) {
+            const isLast = attempt + 1 >= maxAttempts;
+            if (isLast) {
+                throw err;
+            }
+        }
+        await wait(retryDelay(attempt), { signal });
+    }
+}
+/**
+ * Creates a function that calculates exponential back-off delay. Pass it as `options.retryDelay` to {@link ~retry}.
+ *
+ * @param options.delay Base delay between invocations. Defaults to 1s.
+ * @param options.factor How much to increase the delay. Defaults to 2x.
+ * @param options.maxDelay Maximum timeout. Even if higher timeout is calculated, it cannot get higher than this value. Default to 10s.
+ * @returns The function calculating the delay.
+ */
+export function exponentialDelay(options = {}) {
+    const { delay = 1000, factor = 2, maxDelay = 10000 } = options;
+    return attempt => Math.min(factor ** attempt * delay, maxDelay);
+}

package/src/splicearray.d.ts

@@ -1,26 +1,26 @@
-/**
- * @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
- */
-/**
- * Splices one array into another. To be used instead of `Array.prototype.splice` as the latter may
- * throw "Maximum call stack size exceeded" when passed huge number of items to insert.
- *
- * Note: in contrary to Array.splice, this function does not modify the original `target`.
- *
- * ```ts
- * spliceArray( [ 1, 2 ], [ 3, 4 ], 0, 0 );	// [ 3, 4, 1, 2 ]
- * spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 1 );	// [ 1, 3, 4 ]
- * spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 0 );	// [ 1, 3, 4, 2 ]
- * spliceArray( [ 1, 2 ], [ 3, 4 ], 2, 0 );	// [ 1, 2, 3, 4 ]
- * spliceArray( [ 1, 2 ], [],       0, 1 );	// [ 2 ]
- * ```
- *
- * @param target Array to be spliced.
- * @param source Array of elements to be inserted to target.
- * @param start Index at which nodes should be inserted/removed.
- * @param count Number of items.
- *
- * @returns New spliced array.
- */
-export default function spliceArray<T>(target: Array<T>, source: Array<T>, start: number, count: number): Array<T>;
+/**
+ * @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
+ */
+/**
+ * Splices one array into another. To be used instead of `Array.prototype.splice` as the latter may
+ * throw "Maximum call stack size exceeded" when passed huge number of items to insert.
+ *
+ * Note: in contrary to Array.splice, this function does not modify the original `target`.
+ *
+ * ```ts
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 0, 0 );	// [ 3, 4, 1, 2 ]
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 1 );	// [ 1, 3, 4 ]
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 0 );	// [ 1, 3, 4, 2 ]
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 2, 0 );	// [ 1, 2, 3, 4 ]
+ * spliceArray( [ 1, 2 ], [],       0, 1 );	// [ 2 ]
+ * ```
+ *
+ * @param target Array to be spliced.
+ * @param source Array of elements to be inserted to target.
+ * @param start Index at which nodes should be inserted/removed.
+ * @param count Number of items.
+ *
+ * @returns New spliced array.
+ */
+export default function spliceArray<T>(target: ReadonlyArray<T>, source: ReadonlyArray<T>, start: number, count: number): Array<T>;

package/src/splicearray.js

@@ -1,40 +1,40 @@
-/**
- * @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/splicearray
- */
-const BIG_CHUNK_SIZE = 10000;
-/**
- * Splices one array into another. To be used instead of `Array.prototype.splice` as the latter may
- * throw "Maximum call stack size exceeded" when passed huge number of items to insert.
- *
- * Note: in contrary to Array.splice, this function does not modify the original `target`.
- *
- * ```ts
- * spliceArray( [ 1, 2 ], [ 3, 4 ], 0, 0 );	// [ 3, 4, 1, 2 ]
- * spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 1 );	// [ 1, 3, 4 ]
- * spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 0 );	// [ 1, 3, 4, 2 ]
- * spliceArray( [ 1, 2 ], [ 3, 4 ], 2, 0 );	// [ 1, 2, 3, 4 ]
- * spliceArray( [ 1, 2 ], [],       0, 1 );	// [ 2 ]
- * ```
- *
- * @param target Array to be spliced.
- * @param source Array of elements to be inserted to target.
- * @param start Index at which nodes should be inserted/removed.
- * @param count Number of items.
- *
- * @returns New spliced array.
- */
-export default function spliceArray(target, source, start, count) {
-    // In case of performance problems, see: https://github.com/ckeditor/ckeditor5/pull/12429/files#r965850568
-    if (Math.max(source.length, target.length) > BIG_CHUNK_SIZE) {
-        return target.slice(0, start).concat(source).concat(target.slice(start + count, target.length));
-    }
-    else {
-        const newTarget = Array.from(target);
-        newTarget.splice(start, count, ...source);
-        return newTarget;
-    }
-}
+/**
+ * @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/splicearray
+ */
+const BIG_CHUNK_SIZE = 10000;
+/**
+ * Splices one array into another. To be used instead of `Array.prototype.splice` as the latter may
+ * throw "Maximum call stack size exceeded" when passed huge number of items to insert.
+ *
+ * Note: in contrary to Array.splice, this function does not modify the original `target`.
+ *
+ * ```ts
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 0, 0 );	// [ 3, 4, 1, 2 ]
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 1 );	// [ 1, 3, 4 ]
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 1, 0 );	// [ 1, 3, 4, 2 ]
+ * spliceArray( [ 1, 2 ], [ 3, 4 ], 2, 0 );	// [ 1, 2, 3, 4 ]
+ * spliceArray( [ 1, 2 ], [],       0, 1 );	// [ 2 ]
+ * ```
+ *
+ * @param target Array to be spliced.
+ * @param source Array of elements to be inserted to target.
+ * @param start Index at which nodes should be inserted/removed.
+ * @param count Number of items.
+ *
+ * @returns New spliced array.
+ */
+export default function spliceArray(target, source, start, count) {
+    // In case of performance problems, see: https://github.com/ckeditor/ckeditor5/pull/12429/files#r965850568
+    if (Math.max(source.length, target.length) > BIG_CHUNK_SIZE) {
+        return target.slice(0, start).concat(source).concat(target.slice(start + count, target.length));
+    }
+    else {
+        const newTarget = Array.from(target);
+        newTarget.splice(start, count, ...source);
+        return newTarget;
+    }
+}

package/src/spy.d.ts

@@ -1,21 +1,21 @@
-/**
- * @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/spy
- */
-/**
- * Creates a spy function (ala Sinon.js) that can be used to inspect call to it.
- *
- * The following are the present features:
- *
- * * spy.called: property set to `true` if the function has been called at least once.
- *
- * @returns The spy function.
- */
-declare function spy(): {
-    (): void;
-    called?: boolean;
-};
-export default spy;
+/**
+ * @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/spy
+ */
+/**
+ * Creates a spy function (ala Sinon.js) that can be used to inspect call to it.
+ *
+ * The following are the present features:
+ *
+ * * spy.called: property set to `true` if the function has been called at least once.
+ *
+ * @returns The spy function.
+ */
+declare function spy(): {
+    (): void;
+    called?: boolean;
+};
+export default spy;

package/src/spy.js

@@ -1,22 +1,22 @@
-/**
- * @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/spy
- */
-/**
- * Creates a spy function (ala Sinon.js) that can be used to inspect call to it.
- *
- * The following are the present features:
- *
- * * spy.called: property set to `true` if the function has been called at least once.
- *
- * @returns The spy function.
- */
-function spy() {
-    return function spy() {
-        spy.called = true;
-    };
-}
-export default spy;
+/**
+ * @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/spy
+ */
+/**
+ * Creates a spy function (ala Sinon.js) that can be used to inspect call to it.
+ *
+ * The following are the present features:
+ *
+ * * spy.called: property set to `true` if the function has been called at least once.
+ *
+ * @returns The spy function.
+ */
+function spy() {
+    return function spy() {
+        spy.called = true;
+    };
+}
+export default spy;

package/src/toarray.d.ts

@@ -1,25 +1,25 @@
-/**
- * @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/toarray
- */
-/**
- * Transforms any value to an array. If the provided value is already an array, it is returned unchanged.
- *
- * @label MUTABLE
- * @param data The value to transform to an array.
- * @returns An array created from data.
- */
-export default function toArray<T>(data: ArrayOrItem<T>): Array<T>;
-/**
- * Transforms any value to an array. If the provided value is already an array, it is returned unchanged.
- *
- * @label IMMUTABLE
- * @param data The value to transform to an array.
- * @returns An array created from data.
- */
-export default function toArray<T>(data: ReadonlyArrayOrItem<T>): ReadonlyArray<T>;
-export type ArrayOrItem<T> = T | Array<T>;
-export type ReadonlyArrayOrItem<T> = T | ReadonlyArray<T>;
+/**
+ * @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/toarray
+ */
+/**
+ * Transforms any value to an array. If the provided value is already an array, it is returned unchanged.
+ *
+ * @label MUTABLE
+ * @param data The value to transform to an array.
+ * @returns An array created from data.
+ */
+export default function toArray<T>(data: ArrayOrItem<T>): Array<T>;
+/**
+ * Transforms any value to an array. If the provided value is already an array, it is returned unchanged.
+ *
+ * @label IMMUTABLE
+ * @param data The value to transform to an array.
+ * @returns An array created from data.
+ */
+export default function toArray<T>(data: ReadonlyArrayOrItem<T>): ReadonlyArray<T>;
+export type ArrayOrItem<T> = T | Array<T>;
+export type ReadonlyArrayOrItem<T> = T | ReadonlyArray<T>;

package/src/toarray.js

@@ -1,7 +1,7 @@
-/**
- * @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
- */
-export default function toArray(data) {
-    return Array.isArray(data) ? data : [data];
-}
+/**
+ * @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
+ */
+export default function toArray(data) {
+    return Array.isArray(data) ? data : [data];
+}

package/src/tomap.d.ts

@@ -1,19 +1,19 @@
-/**
- * @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
- */
-/**
- * Transforms object or iterable to map. Iterable needs to be in the format acceptable by the `Map` constructor.
- *
- * ```ts
- * map = toMap( { 'foo': 1, 'bar': 2 } );
- * map = toMap( [ [ 'foo', 1 ], [ 'bar', 2 ] ] );
- * map = toMap( anotherMap );
- * ```
- *
- * @param data Object or iterable to transform.
- * @returns Map created from data.
- */
-export default function toMap<T>(data: {
-    readonly [key: string]: T;
-} | Iterable<readonly [string, T]> | null | undefined): Map<string, T>;
+/**
+ * @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
+ */
+/**
+ * Transforms object or iterable to map. Iterable needs to be in the format acceptable by the `Map` constructor.
+ *
+ * ```ts
+ * map = toMap( { 'foo': 1, 'bar': 2 } );
+ * map = toMap( [ [ 'foo', 1 ], [ 'bar', 2 ] ] );
+ * map = toMap( anotherMap );
+ * ```
+ *
+ * @param data Object or iterable to transform.
+ * @returns Map created from data.
+ */
+export default function toMap<T>(data: {
+    readonly [key: string]: T;
+} | Iterable<readonly [string, T]> | null | undefined): Map<string, T>;

package/src/tomap.js

@@ -1,29 +1,29 @@
-/**
- * @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/tomap
- */
-import objectToMap from './objecttomap';
-import isIterable from './isiterable';
-/**
- * Transforms object or iterable to map. Iterable needs to be in the format acceptable by the `Map` constructor.
- *
- * ```ts
- * map = toMap( { 'foo': 1, 'bar': 2 } );
- * map = toMap( [ [ 'foo', 1 ], [ 'bar', 2 ] ] );
- * map = toMap( anotherMap );
- * ```
- *
- * @param data Object or iterable to transform.
- * @returns Map created from data.
- */
-export default function toMap(data) {
-    if (isIterable(data)) {
-        return new Map(data);
-    }
-    else {
-        return objectToMap(data);
-    }
-}
+/**
+ * @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/tomap
+ */
+import objectToMap from './objecttomap';
+import isIterable from './isiterable';
+/**
+ * Transforms object or iterable to map. Iterable needs to be in the format acceptable by the `Map` constructor.
+ *
+ * ```ts
+ * map = toMap( { 'foo': 1, 'bar': 2 } );
+ * map = toMap( [ [ 'foo', 1 ], [ 'bar', 2 ] ] );
+ * map = toMap( anotherMap );
+ * ```
+ *
+ * @param data Object or iterable to transform.
+ * @returns Map created from data.
+ */
+export default function toMap(data) {
+    if (isIterable(data)) {
+        return new Map(data);
+    }
+    else {
+        return objectToMap(data);
+    }
+}