@ckeditor/ckeditor5-utils 44.1.0 → 44.2.0-alpha.0

package/dist/collection.d.ts

@@ -1,437 +0,0 @@
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-declare const Collection_base: {
-    new (): import("./emittermixin.js").Emitter;
-    prototype: import("./emittermixin.js").Emitter;
-};
-/**
- * Collections are ordered sets of objects. Items in the collection can be retrieved by their indexes
- * in the collection (like in an array) or by their ids.
- *
- * If an object without an `id` property is being added to the collection, the `id` property will be generated
- * automatically. Note that the automatically generated id is unique only within this single collection instance.
- *
- * By default an item in the collection is identified by its `id` property. The name of the identifier can be
- * configured through the constructor of the collection.
- *
- * @typeParam T The type of the collection element.
- */
-export default class Collection<T extends Record<string, any>> extends /* #__PURE__ */ Collection_base implements Iterable<T> {
-    /**
-     * The internal list of items in the collection.
-     */
-    private readonly _items;
-    /**
-     * The internal map of items in the collection.
-     */
-    private readonly _itemMap;
-    /**
-     * The name of the property which is considered to identify an item.
-     */
-    private readonly _idProperty;
-    /**
-     * A collection instance this collection is bound to as a result
-     * of calling {@link #bindTo} method.
-     */
-    private _bindToCollection?;
-    /**
-     * A helper mapping external items of a bound collection ({@link #bindTo})
-     * and actual items of this collection. It provides information
-     * necessary to properly remove items bound to another collection.
-     *
-     * See {@link #_bindToInternalToExternalMap}.
-     */
-    private readonly _bindToExternalToInternalMap;
-    /**
-     * A helper mapping items of this collection to external items of a bound collection
-     * ({@link #bindTo}). It provides information necessary to manage the bindings, e.g.
-     * to avoid loops in two–way bindings.
-     *
-     * See {@link #_bindToExternalToInternalMap}.
-     */
-    private readonly _bindToInternalToExternalMap;
-    /**
-     * Stores indexes of skipped items from bound external collection.
-     */
-    private _skippedIndexesFromExternal;
-    /**
-     * Creates a new Collection instance.
-     *
-     * You can pass a configuration object as the argument of the constructor:
-     *
-     * ```ts
-     * const emptyCollection = new Collection<{ name: string }>( { idProperty: 'name' } );
-     * emptyCollection.add( { name: 'John' } );
-     * console.log( collection.get( 'John' ) ); // -> { name: 'John' }
-     * ```
-     *
-     * The collection is empty by default. You can add new items using the {@link #add} method:
-     *
-     * ```ts
-     * const collection = new Collection<{ id: string }>();
-     *
-     * collection.add( { id: 'John' } );
-     * console.log( collection.get( 0 ) ); // -> { id: 'John' }
-     * ```
-     *
-     * @label NO_ITEMS
-     * @param options The options object.
-     * @param options.idProperty The name of the property which is used to identify an item.
-     * Items that do not have such a property will be assigned one when added to the collection.
-     */
-    constructor(options?: {
-        readonly idProperty?: string;
-    });
-    /**
-     * Creates a new Collection instance with specified initial items.
-     *
-     * ```ts
-     * const collection = new Collection<{ id: string }>( [ { id: 'John' }, { id: 'Mike' } ] );
-     *
-     * console.log( collection.get( 0 ) ); // -> { id: 'John' }
-     * console.log( collection.get( 1 ) ); // -> { id: 'Mike' }
-     * console.log( collection.get( 'Mike' ) ); // -> { id: 'Mike' }
-     * ```
-     *
-     * You can always pass a configuration object as the last argument of the constructor:
-     *
-     * ```ts
-     * const nonEmptyCollection = new Collection<{ name: string }>( [ { name: 'John' } ], { idProperty: 'name' } );
-     * nonEmptyCollection.add( { name: 'George' } );
-     * console.log( collection.get( 'George' ) ); // -> { name: 'George' }
-     * console.log( collection.get( 'John' ) ); // -> { name: 'John' }
-     * ```
-     *
-     * @label INITIAL_ITEMS
-     * @param initialItems The initial items of the collection.
-     * @param options The options object.
-     * @param options.idProperty The name of the property which is used to identify an item.
-     * Items that do not have such a property will be assigned one when added to the collection.
-     */
-    constructor(initialItems: Iterable<T>, options?: {
-        readonly idProperty?: string;
-    });
-    /**
-     * The number of items available in the collection.
-     */
-    get length(): number;
-    /**
-     * Returns the first item from the collection or null when collection is empty.
-     */
-    get first(): T | null;
-    /**
-     * Returns the last item from the collection or null when collection is empty.
-     */
-    get last(): T | null;
-    /**
-     * Adds an item into the collection.
-     *
-     * If the item does not have an id, then it will be automatically generated and set on the item.
-     *
-     * @param item
-     * @param index The position of the item in the collection. The item
-     * is pushed to the collection when `index` not specified.
-     * @fires add
-     * @fires change
-     */
-    add(item: T, index?: number): this;
-    /**
-     * Adds multiple items into the collection.
-     *
-     * Any item not containing an id will get an automatically generated one.
-     *
-     * @param items
-     * @param index The position of the insertion. Items will be appended if no `index` is specified.
-     * @fires add
-     * @fires change
-     */
-    addMany(items: Iterable<T>, index?: number): this;
-    /**
-     * Gets an item by its ID or index.
-     *
-     * @param idOrIndex The item ID or index in the collection.
-     * @returns The requested item or `null` if such item does not exist.
-     */
-    get(idOrIndex: string | number): T | null;
-    /**
-     * Returns a Boolean indicating whether the collection contains an item.
-     *
-     * @param itemOrId The item or its ID in the collection.
-     * @returns `true` if the collection contains the item, `false` otherwise.
-     */
-    has(itemOrId: T | string): boolean;
-    /**
-     * Gets an index of an item in the collection.
-     * When an item is not defined in the collection, the index will equal -1.
-     *
-     * @param itemOrId The item or its ID in the collection.
-     * @returns The index of a given item.
-     */
-    getIndex(itemOrId: T | string): number;
-    /**
-     * Removes an item from the collection.
-     *
-     * @param subject The item to remove, its ID or index in the collection.
-     * @returns The removed item.
-     * @fires remove
-     * @fires change
-     */
-    remove(subject: T | number | string): T;
-    /**
-     * Executes the callback for each item in the collection and composes an array or values returned by this callback.
-     *
-     * @typeParam U The result type of the callback.
-     * @param callback
-     * @param ctx Context in which the `callback` will be called.
-     * @returns The result of mapping.
-     */
-    map<U>(callback: (item: T, index: number) => U, ctx?: any): Array<U>;
-    /**
-     * Performs the specified action for each item in the collection.
-     *
-     * @param ctx Context in which the `callback` will be called.
-     */
-    forEach(callback: (item: T, index: number) => unknown, ctx?: any): void;
-    /**
-     * Finds the first item in the collection for which the `callback` returns a true value.
-     *
-     * @param callback
-     * @param ctx Context in which the `callback` will be called.
-     * @returns The item for which `callback` returned a true value.
-     */
-    find(callback: (item: T, index: number) => boolean, ctx?: any): T | undefined;
-    /**
-     * Returns an array with items for which the `callback` returned a true value.
-     *
-     * @param callback
-     * @param ctx Context in which the `callback` will be called.
-     * @returns The array with matching items.
-     */
-    filter(callback: (item: T, index: number) => boolean, ctx?: any): Array<T>;
-    /**
-     * Removes all items from the collection and destroys the binding created using
-     * {@link #bindTo}.
-     *
-     * @fires remove
-     * @fires change
-     */
-    clear(): void;
-    /**
-     * Binds and synchronizes the collection with another one.
-     *
-     * The binding can be a simple factory:
-     *
-     * ```ts
-     * class FactoryClass {
-     * 	public label: string;
-     *
-     * 	constructor( data: { label: string } ) {
-     * 		this.label = data.label;
-     * 	}
-     * }
-     *
-     * const source = new Collection<{ label: string }>( { idProperty: 'label' } );
-     * const target = new Collection<FactoryClass>();
-     *
-     * target.bindTo( source ).as( FactoryClass );
-     *
-     * source.add( { label: 'foo' } );
-     * source.add( { label: 'bar' } );
-     *
-     * console.log( target.length ); // 2
-     * console.log( target.get( 1 ).label ); // 'bar'
-     *
-     * source.remove( 0 );
-     * console.log( target.length ); // 1
-     * console.log( target.get( 0 ).label ); // 'bar'
-     * ```
-     *
-     * or the factory driven by a custom callback:
-     *
-     * ```ts
-     * class FooClass {
-     * 	public label: string;
-     *
-     * 	constructor( data: { label: string } ) {
-     * 		this.label = data.label;
-     * 	}
-     * }
-     *
-     * class BarClass {
-     * 	public label: string;
-     *
-     * 	constructor( data: { label: string } ) {
-     * 		this.label = data.label;
-     * 	}
-     * }
-     *
-     * const source = new Collection<{ label: string }>( { idProperty: 'label' } );
-     * const target = new Collection<FooClass | BarClass>();
-     *
-     * target.bindTo( source ).using( ( item ) => {
-     * 	if ( item.label == 'foo' ) {
-     * 		return new FooClass( item );
-     * 	} else {
-     * 		return new BarClass( item );
-     * 	}
-     * } );
-     *
-     * source.add( { label: 'foo' } );
-     * source.add( { label: 'bar' } );
-     *
-     * console.log( target.length ); // 2
-     * console.log( target.get( 0 ) instanceof FooClass ); // true
-     * console.log( target.get( 1 ) instanceof BarClass ); // true
-     * ```
-     *
-     * or the factory out of property name:
-     *
-     * ```ts
-     * const source = new Collection<{ nested: { value: string } }>();
-     * const target = new Collection<{ value: string }>();
-     *
-     * target.bindTo( source ).using( 'nested' );
-     *
-     * source.add( { nested: { value: 'foo' } } );
-     * source.add( { nested: { value: 'bar' } } );
-     *
-     * console.log( target.length ); // 2
-     * console.log( target.get( 0 ).value ); // 'foo'
-     * console.log( target.get( 1 ).value ); // 'bar'
-     * ```
-     *
-     * It's possible to skip specified items by returning null value:
-     *
-     * ```ts
-     * const source = new Collection<{ hidden: boolean }>();
-     * const target = new Collection<{ hidden: boolean }>();
-     *
-     * target.bindTo( source ).using( item => {
-     * 	if ( item.hidden ) {
-     * 		return null;
-     * 	}
-     *
-     * 	return item;
-     * } );
-     *
-     * source.add( { hidden: true } );
-     * source.add( { hidden: false } );
-     *
-     * console.log( source.length ); // 2
-     * console.log( target.length ); // 1
-     * ```
-     *
-     * **Note**: {@link #clear} can be used to break the binding.
-     *
-     * @typeParam S The type of `externalCollection` element.
-     * @param externalCollection A collection to be bound.
-     * @returns The binding chain object.
-     */
-    bindTo<S extends Record<string, any>>(externalCollection: Collection<S>): CollectionBindToChain<S, T>;
-    /**
-     * Finalizes and activates a binding initiated by {@link #bindTo}.
-     *
-     * @param factory A function which produces collection items.
-     */
-    private _setUpBindToBinding;
-    /**
-     * Returns an unique id property for a given `item`.
-     *
-     * The method will generate new id and assign it to the `item` if it doesn't have any.
-     *
-     * @param item Item to be added.
-     */
-    private _getItemIdBeforeAdding;
-    /**
-     * Core {@link #remove} method implementation shared in other functions.
-     *
-     * In contrast this method **does not** fire the {@link #event:change} event.
-     *
-     * @param subject The item to remove, its id or index in the collection.
-     * @returns Returns an array with the removed item and its index.
-     * @fires remove
-     */
-    private _remove;
-    /**
-     * Iterable interface.
-     */
-    [Symbol.iterator](): Iterator<T>;
-}
-/**
- * Fired when an item is added to the collection.
- *
- * @eventName ~Collection#add
- * @param item The added item.
- * @param index An index where the addition occurred.
- */
-export type CollectionAddEvent<T = any> = {
-    name: 'add';
-    args: [item: T, index: number];
-};
-/**
- * Fired when the collection was changed due to adding or removing items.
- *
- * @eventName ~Collection#change
- * @param data Changed items.
- */
-export type CollectionChangeEvent<T = any> = {
-    name: 'change';
-    args: [data: CollectionChangeEventData<T>];
-};
-/**
- * A structure describing the {@link ~Collection#event:change `Collection#change`} event.
- */
-export type CollectionChangeEventData<T = any> = {
-    /**
-     * A list of added items.
-     */
-    added: Iterable<T>;
-    /**
-     * A list of removed items.
-     */
-    removed: Iterable<T>;
-    /**
-     * An index where the addition or removal occurred.
-     */
-    index: number;
-};
-/**
- * Fired when an item is removed from the collection.
- *
- * @eventName ~Collection#remove
- * @param item The removed item.
- * @param index Index from which item was removed.
- */
-export type CollectionRemoveEvent<T = any> = {
-    name: 'remove';
-    args: [item: T, index: number];
-};
-/**
- * An object returned by the {@link module:utils/collection~Collection#bindTo `bindTo()`} method
- * providing functions that specify the type of the binding.
- *
- * See the {@link module:utils/collection~Collection#bindTo `bindTo()`} documentation for examples.
- */
-export interface CollectionBindToChain<S, T> {
-    /**
-     * Creates the class factory binding in which items of the source collection are passed to
-     * the constructor of the specified class.
-     *
-     * @param Class The class constructor used to create instances in the factory.
-     */
-    as(Class: new (item: S) => T): void;
-    /**
-     * Creates a callback or a property binding.
-     *
-     * @param callbackOrProperty When the function is passed, it should return
-     * the collection items. When the string is provided, the property value is used to create the bound collection items.
-     */
-    using(callbackOrProperty: keyof S | ((item: S) => T | null)): void;
-}
-export {};

package/dist/comparearrays.d.ts

@@ -1,34 +0,0 @@
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module utils/comparearrays
- */
-/**
- * Compares how given arrays relate to each other. One array can be: same as another array, prefix of another array
- * or completely different. If arrays are different, first index at which they differ is returned. Otherwise,
- * a flag specifying the relation is returned. Flags are negative numbers, so whenever a number >= 0 is returned
- * it means that arrays differ.
- *
- * ```ts
- * compareArrays( [ 0, 2 ], [ 0, 2 ] );		// 'same'
- * compareArrays( [ 0, 2 ], [ 0, 2, 1 ] );		// 'prefix'
- * compareArrays( [ 0, 2 ], [ 0 ] );			// 'extension'
- * compareArrays( [ 0, 2 ], [ 1, 2 ] );		// 0
- * compareArrays( [ 0, 2 ], [ 0, 1 ] );		// 1
- * ```
- *
- * @param a Array that is compared.
- * @param b Array to compare with.
- * @returns How array `a` is related to `b`.
- */
-export default function compareArrays(a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>): ArrayRelation | number;
-/**
- * Array relation.
- */
-export type ArrayRelation = 'extension' | 'same' | 'prefix';

package/dist/config.d.ts

@@ -1,167 +0,0 @@
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * Handles a configuration dictionary.
- *
- * @typeParam Cfg A type of the configuration dictionary.
- */
-export default class Config<Cfg> {
-    /**
-     * Store for the whole configuration.
-     */
-    private readonly _config;
-    /**
-     * Creates an instance of the {@link ~Config} class.
-     *
-     * @param configurations The initial configurations to be set. Usually, provided by the user.
-     * @param defaultConfigurations The default configurations. Usually, provided by the system.
-     */
-    constructor(configurations?: Partial<Cfg>, defaultConfigurations?: Partial<Cfg>);
-    /**
-     * Set configuration values.
-     *
-     * It also accepts setting a "deep configuration" by using dots in the name. For example, `'resize.width'` sets
-     * the value for the `width` configuration in the `resize` subset.
-     *
-     * ```ts
-     * config.set( 'resize.width', 500 );
-     * ```
-     *
-     * It accepts both a name/value pair or an object, which properties and values will be used to set
-     * configurations. See {@link #set:CONFIG_OBJECT}.
-     *
-     * @label KEY_VALUE
-     * @param name The configuration name. Configuration names are case-sensitive.
-     * @param value The configuration value.
-     */
-    set<K extends string>(name: K, value: GetSubConfig<Cfg, K>): void;
-    /**
-     * Set configuration values.
-     *
-     * It accepts an object, which properties and values will be used to set configurations.
-     *
-     * ```ts
-     * config.set( {
-     * 	width: 500
-     * 	toolbar: {
-     * 		collapsed: true
-     * 	}
-     * } );
-     *
-     * // Equivalent to:
-     * config.set( 'width', 500 );
-     * config.set( 'toolbar.collapsed', true );
-     * ```
-     *
-     * Passing an object as the value will amend the configuration, not replace it.
-     *
-     * ```ts
-     * config.set( 'toolbar', {
-     * 	collapsed: true,
-     * } );
-     *
-     * config.set( 'toolbar', {
-     * 	color: 'red',
-     * } );
-     *
-     * config.get( 'toolbar.collapsed' ); // true
-     * config.get( 'toolbar.color' ); // 'red'
-     * ```
-     *
-     * It accepts both a name/value pair or an object, which properties and values will be used to set
-     * configurations. See {@link #set:KEY_VALUE}.
-     *
-     * @label CONFIG_OBJECT
-     * @param config The configuration object from which take properties as
-     * configuration entries. Configuration names are case-sensitive.
-     */
-    set(config: Partial<Cfg>): void;
-    /**
-     * Does exactly the same as {@link #set:KEY_VALUE} with one exception – passed configuration extends
-     * existing one, but does not overwrite already defined values.
-     *
-     * This method is supposed to be called by plugin developers to setup plugin's configurations. It would be
-     * rarely used for other needs.
-     *
-     * @label KEY_VALUE
-     * @param name The configuration name. Configuration names are case-sensitive.
-     * @param value The configuration value.
-     */
-    define<K extends string>(name: K, value: GetSubConfig<Cfg, K>): void;
-    /**
-     * Does exactly the same as {@link #set:CONFIG_OBJECT} with one exception – passed configuration extends
-     * existing one, but does not overwrite already defined values.
-     *
-     * This method is supposed to be called by plugin developers to setup plugin's configurations. It would be
-     * rarely used for other needs.
-     *
-     * @label CONFIG_OBJECT
-     * @param config The configuration object from which take properties as
-     * configuration entries. Configuration names are case-sensitive.
-     */
-    define(config: Partial<Cfg>): void;
-    /**
-     * Gets the value for a configuration entry.
-     *
-     * ```ts
-     * config.get( 'name' );
-     * ```
-     *
-     * Deep configurations can be retrieved by separating each part with a dot.
-     *
-     * ```ts
-     * config.get( 'toolbar.collapsed' );
-     * ```
-     *
-     * @param name The configuration name. Configuration names are case-sensitive.
-     * @returns The configuration value or `undefined` if the configuration entry was not found.
-     */
-    get<K extends string>(name: K): GetSubConfig<Cfg, K> | undefined;
-    /**
-     * Iterates over all top level configuration names.
-     */
-    names(): Iterable<string>;
-    /**
-     * Saves passed configuration to the specified target (nested object).
-     *
-     * @param target Nested config object.
-     * @param name The configuration name or an object from which take properties as
-     * configuration entries. Configuration names are case-sensitive.
-     * @param value The configuration value. Used if a name is passed.
-     * @param isDefine Define if passed configuration should overwrite existing one.
-     */
-    private _setToTarget;
-    /**
-     * Get specified configuration from specified source (nested object).
-     *
-     * @param source level of nested object.
-     * @param name The configuration name. Configuration names are case-sensitive.
-     * @returns The configuration value or `undefined` if the configuration entry was not found.
-     */
-    private _getFromSource;
-    /**
-     * Iterates through passed object and calls {@link #_setToTarget} method with object key and value for each property.
-     *
-     * @param target Nested config object.
-     * @param configuration Configuration data set
-     * @param isDefine Defines if passed configuration is default configuration or not.
-     */
-    private _setObjectToTarget;
-}
-/**
- * An utility type excluding primitive values and arrays from the union.
- */
-export type OnlyObject<T> = Exclude<T, undefined | null | string | number | boolean | Array<any>>;
-/**
- * An utility type extracting configuration value from the given name.
- *
- * @typeParam T The type of a configuration dictionary.
- * @typeParam K The literal type of configuration name (dot-separated path).
- */
-export type GetSubConfig<T, K> = K extends keyof T ? T[K] : K extends `${infer K1}.${infer K2}` ? K1 extends keyof T ? GetSubConfig<OnlyObject<T[K1]>, K2> : unknown : unknown;

package/dist/count.d.ts

@@ -1,22 +0,0 @@
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module utils/count
- */
-/**
- * Returns the number of items return by the iterator.
- *
- * ```ts
- * count( [ 1, 2, 3, 4, 5 ] ); // 5;
- * ```
- *
- * @param iterable Any iterable.
- * @returns Number of items returned by that iterable.
- */
-export default function count(iterable: Iterable<unknown>): number;

package/dist/crc32.d.ts

@@ -1,30 +0,0 @@
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * Calculates CRC-32 checksum for a given inputData to verify the integrity of data.
- *
- * @param inputData Accepts a single value (string, number, boolean), an array of strings, or an array of all of the above types.
- * Non-string values are converted to strings before calculating the checksum.
- * The checksum calculation is based on the concatenated string representation of the input values:
- * * `crc32('foo')` is equivalent to `crc32(['foo'])`
- * * `crc32(123)` is equivalent to `crc32(['123'])`
- * * `crc32(true)` is equivalent to `crc32(['true'])`
- * * `crc32(['foo', 123, true])` produces the same result as `crc32('foo123true')`
- * * Nested arrays of strings are flattened, so `crc32([['foo', 'bar'], 'baz'])` is equivalent to `crc32(['foobar', 'baz'])`
- *
- * @returns The CRC-32 checksum, returned as a hexadecimal string.
- */
-export default function crc32(inputData: CRCData): string;
-/**
- * The input data for the CRC-32 checksum calculation.
- * Can be a single value (string, number, boolean), an array of strings, or an array of all of the above types.
- */
-export type CRCData = CRCValue | Array<CRCValue>;
-type CRCValue = string | number | boolean | Array<string>;
-export {};