| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785 |
- /**
- * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
- /**
- * @module utils/collection
- */
- import EmitterMixin from './emittermixin';
- import CKEditorError from './ckeditorerror';
- import uid from './uid';
- import isIterable from './isiterable';
- import mix from './mix';
- /**
- * 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.
- *
- * @mixes module:utils/emittermixin~EmitterMixin
- */
- export default class Collection {
- /**
- * Creates a new Collection instance.
- *
- * You can provide an iterable of initial items the collection will be created with:
- *
- * const collection = new Collection( [ { 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' }
- *
- * Or you can first create a collection and then add new items using the {@link #add} method:
- *
- * const collection = new Collection();
- *
- * collection.add( { id: 'John' } );
- * console.log( collection.get( 0 ) ); // -> { id: 'John' }
- *
- * Whatever option you choose, you can always pass a configuration object as the last argument
- * of the constructor:
- *
- * const emptyCollection = new Collection( { idProperty: 'name' } );
- * emptyCollection.add( { name: 'John' } );
- * console.log( collection.get( 'John' ) ); // -> { name: 'John' }
- *
- * const nonEmptyCollection = new Collection( [ { name: 'John' } ], { idProperty: 'name' } );
- * nonEmptyCollection.add( { name: 'George' } );
- * console.log( collection.get( 'George' ) ); // -> { name: 'George' }
- * console.log( collection.get( 'John' ) ); // -> { name: 'John' }
- *
- * @param {Iterable.<Object>|Object} initialItemsOrOptions The initial items of the collection or
- * the options object.
- * @param {Object} [options={}] The options object, when the first argument is an array of initial items.
- * @param {String} [options.idProperty='id'] 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( initialItemsOrOptions = {}, options = {} ) {
- const hasInitialItems = isIterable( initialItemsOrOptions );
- if ( !hasInitialItems ) {
- options = initialItemsOrOptions;
- }
- /**
- * The internal list of items in the collection.
- *
- * @private
- * @member {Object[]}
- */
- this._items = [];
- /**
- * The internal map of items in the collection.
- *
- * @private
- * @member {Map}
- */
- this._itemMap = new Map();
- /**
- * The name of the property which is considered to identify an item.
- *
- * @private
- * @member {String}
- */
- this._idProperty = options.idProperty || 'id';
- /**
- * 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}.
- *
- * @protected
- * @member {WeakMap}
- */
- this._bindToExternalToInternalMap = new WeakMap();
- /**
- * 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}.
- *
- * @protected
- * @member {WeakMap}
- */
- this._bindToInternalToExternalMap = new WeakMap();
- /**
- * Stores indexes of skipped items from bound external collection.
- *
- * @private
- * @member {Array}
- */
- this._skippedIndexesFromExternal = [];
- // Set the initial content of the collection (if provided in the constructor).
- if ( hasInitialItems ) {
- for ( const item of initialItemsOrOptions ) {
- this._items.push( item );
- this._itemMap.set( this._getItemIdBeforeAdding( item ), item );
- }
- }
- /**
- * A collection instance this collection is bound to as a result
- * of calling {@link #bindTo} method.
- *
- * @protected
- * @member {module:utils/collection~Collection} #_bindToCollection
- */
- }
- /**
- * The number of items available in the collection.
- *
- * @member {Number} #length
- */
- get length() {
- return this._items.length;
- }
- /**
- * Returns the first item from the collection or null when collection is empty.
- *
- * @returns {Object|null} The first item or `null` if collection is empty.
- */
- get first() {
- return this._items[ 0 ] || null;
- }
- /**
- * Returns the last item from the collection or null when collection is empty.
- *
- * @returns {Object|null} The last item or `null` if collection is empty.
- */
- get last() {
- return this._items[ this.length - 1 ] || 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.
- *
- * @chainable
- * @param {Object} item
- * @param {Number} [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, index ) {
- return this.addMany( [ item ], index );
- }
- /**
- * Adds multiple items into the collection.
- *
- * Any item not containing an id will get an automatically generated one.
- *
- * @chainable
- * @param {Iterable.<Object>} item
- * @param {Number} [index] The position of the insertion. Items will be appended if no `index` is specified.
- * @fires add
- * @fires change
- */
- addMany( items, index ) {
- if ( index === undefined ) {
- index = this._items.length;
- } else if ( index > this._items.length || index < 0 ) {
- /**
- * The `index` passed to {@link module:utils/collection~Collection#addMany `Collection#addMany()`}
- * is invalid. It must be a number between 0 and the collection's length.
- *
- * @error collection-add-item-bad-index
- */
- throw new CKEditorError( 'collection-add-item-invalid-index: The index passed to Collection#addMany() is invalid.', this );
- }
- for ( let offset = 0; offset < items.length; offset++ ) {
- const item = items[ offset ];
- const itemId = this._getItemIdBeforeAdding( item );
- const currentItemIndex = index + offset;
- this._items.splice( currentItemIndex, 0, item );
- this._itemMap.set( itemId, item );
- this.fire( 'add', item, currentItemIndex );
- }
- this.fire( 'change', {
- added: items,
- removed: [],
- index
- } );
- return this;
- }
- /**
- * Gets an item by its ID or index.
- *
- * @param {String|Number} idOrIndex The item ID or index in the collection.
- * @returns {Object|null} The requested item or `null` if such item does not exist.
- */
- get( idOrIndex ) {
- let item;
- if ( typeof idOrIndex == 'string' ) {
- item = this._itemMap.get( idOrIndex );
- } else if ( typeof idOrIndex == 'number' ) {
- item = this._items[ idOrIndex ];
- } else {
- /**
- * An index or ID must be given.
- *
- * @error collection-get-invalid-arg
- */
- throw new CKEditorError( 'collection-get-invalid-arg: An index or ID must be given.', this );
- }
- return item || null;
- }
- /**
- * Returns a Boolean indicating whether the collection contains an item.
- *
- * @param {Object|String} itemOrId The item or its ID in the collection.
- * @returns {Boolean} `true` if the collection contains the item, `false` otherwise.
- */
- has( itemOrId ) {
- if ( typeof itemOrId == 'string' ) {
- return this._itemMap.has( itemOrId );
- } else { // Object
- const idProperty = this._idProperty;
- const id = itemOrId[ idProperty ];
- return this._itemMap.has( id );
- }
- }
- /**
- * Gets an index of an item in the collection.
- * When an item is not defined in the collection, the index will equal -1.
- *
- * @param {Object|String} itemOrId The item or its ID in the collection.
- * @returns {Number} The index of a given item.
- */
- getIndex( itemOrId ) {
- let item;
- if ( typeof itemOrId == 'string' ) {
- item = this._itemMap.get( itemOrId );
- } else {
- item = itemOrId;
- }
- return this._items.indexOf( item );
- }
- /**
- * Removes an item from the collection.
- *
- * @param {Object|Number|String} subject The item to remove, its ID or index in the collection.
- * @returns {Object} The removed item.
- * @fires remove
- * @fires change
- */
- remove( subject ) {
- const [ item, index ] = this._remove( subject );
- this.fire( 'change', {
- added: [],
- removed: [ item ],
- index
- } );
- return item;
- }
- /**
- * Executes the callback for each item in the collection and composes an array or values returned by this callback.
- *
- * @param {Function} callback
- * @param {Object} callback.item
- * @param {Number} callback.index
- * @param {Object} ctx Context in which the `callback` will be called.
- * @returns {Array} The result of mapping.
- */
- map( callback, ctx ) {
- return this._items.map( callback, ctx );
- }
- /**
- * Finds the first item in the collection for which the `callback` returns a true value.
- *
- * @param {Function} callback
- * @param {Object} callback.item
- * @param {Number} callback.index
- * @param {Object} ctx Context in which the `callback` will be called.
- * @returns {Object} The item for which `callback` returned a true value.
- */
- find( callback, ctx ) {
- return this._items.find( callback, ctx );
- }
- /**
- * Returns an array with items for which the `callback` returned a true value.
- *
- * @param {Function} callback
- * @param {Object} callback.item
- * @param {Number} callback.index
- * @param {Object} ctx Context in which the `callback` will be called.
- * @returns {Object[]} The array with matching items.
- */
- filter( callback, ctx ) {
- return this._items.filter( callback, ctx );
- }
- /**
- * Removes all items from the collection and destroys the binding created using
- * {@link #bindTo}.
- *
- * @fires remove
- * @fires change
- */
- clear() {
- if ( this._bindToCollection ) {
- this.stopListening( this._bindToCollection );
- this._bindToCollection = null;
- }
- const removedItems = Array.from( this._items );
- while ( this.length ) {
- this._remove( 0 );
- }
- this.fire( 'change', {
- added: [],
- removed: removedItems,
- index: 0
- } );
- }
- /**
- * Binds and synchronizes the collection with another one.
- *
- * The binding can be a simple factory:
- *
- * class FactoryClass {
- * constructor( data ) {
- * this.label = data.label;
- * }
- * }
- *
- * const source = new Collection( { idProperty: 'label' } );
- * const target = new Collection();
- *
- * 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:
- *
- * class FooClass {
- * constructor( data ) {
- * this.label = data.label;
- * }
- * }
- *
- * class BarClass {
- * constructor( data ) {
- * this.label = data.label;
- * }
- * }
- *
- * const source = new Collection( { idProperty: 'label' } );
- * const target = new Collection();
- *
- * 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:
- *
- * const source = new Collection( { idProperty: 'label' } );
- * const target = new Collection();
- *
- * target.bindTo( source ).using( 'label' );
- *
- * source.add( { label: { value: 'foo' } } );
- * source.add( { label: { 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 falsy value:
- *
- * const source = new Collection();
- * const target = new Collection();
- *
- * 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.
- *
- * @param {module:utils/collection~Collection} externalCollection A collection to be bound.
- * @returns {Object}
- * @returns {module:utils/collection~CollectionBindToChain} The binding chain object.
- */
- bindTo( externalCollection ) {
- if ( this._bindToCollection ) {
- /**
- * The collection cannot be bound more than once.
- *
- * @error collection-bind-to-rebind
- */
- throw new CKEditorError( 'collection-bind-to-rebind: The collection cannot be bound more than once.', this );
- }
- this._bindToCollection = externalCollection;
- return {
- as: Class => {
- this._setUpBindToBinding( item => new Class( item ) );
- },
- using: callbackOrProperty => {
- if ( typeof callbackOrProperty == 'function' ) {
- this._setUpBindToBinding( item => callbackOrProperty( item ) );
- } else {
- this._setUpBindToBinding( item => item[ callbackOrProperty ] );
- }
- }
- };
- }
- /**
- * Finalizes and activates a binding initiated by {#bindTo}.
- *
- * @protected
- * @param {Function} factory A function which produces collection items.
- */
- _setUpBindToBinding( factory ) {
- const externalCollection = this._bindToCollection;
- // Adds the item to the collection once a change has been done to the external collection.
- //
- // @private
- const addItem = ( evt, externalItem, index ) => {
- const isExternalBoundToThis = externalCollection._bindToCollection == this;
- const externalItemBound = externalCollection._bindToInternalToExternalMap.get( externalItem );
- // If an external collection is bound to this collection, which makes it a 2–way binding,
- // and the particular external collection item is already bound, don't add it here.
- // The external item has been created **out of this collection's item** and (re)adding it will
- // cause a loop.
- if ( isExternalBoundToThis && externalItemBound ) {
- this._bindToExternalToInternalMap.set( externalItem, externalItemBound );
- this._bindToInternalToExternalMap.set( externalItemBound, externalItem );
- } else {
- const item = factory( externalItem );
- // When there is no item we need to remember skipped index first and then we can skip this item.
- if ( !item ) {
- this._skippedIndexesFromExternal.push( index );
- return;
- }
- // Lets try to put item at the same index as index in external collection
- // but when there are a skipped items in one or both collections we need to recalculate this index.
- let finalIndex = index;
- // When we try to insert item after some skipped items from external collection we need
- // to include this skipped items and decrease index.
- //
- // For the following example:
- // external -> [ 'A', 'B - skipped for internal', 'C - skipped for internal' ]
- // internal -> [ A ]
- //
- // Another item is been added at the end of external collection:
- // external.add( 'D' )
- // external -> [ 'A', 'B - skipped for internal', 'C - skipped for internal', 'D' ]
- //
- // We can't just add 'D' to internal at the same index as index in external because
- // this will produce empty indexes what is invalid:
- // internal -> [ 'A', empty, empty, 'D' ]
- //
- // So we need to include skipped items and decrease index
- // internal -> [ 'A', 'D' ]
- for ( const skipped of this._skippedIndexesFromExternal ) {
- if ( index > skipped ) {
- finalIndex--;
- }
- }
- // We need to take into consideration that external collection could skip some items from
- // internal collection.
- //
- // For the following example:
- // internal -> [ 'A', 'B - skipped for external', 'C - skipped for external' ]
- // external -> [ A ]
- //
- // Another item is been added at the end of external collection:
- // external.add( 'D' )
- // external -> [ 'A', 'D' ]
- //
- // We need to include skipped items and place new item after them:
- // internal -> [ 'A', 'B - skipped for external', 'C - skipped for external', 'D' ]
- for ( const skipped of externalCollection._skippedIndexesFromExternal ) {
- if ( finalIndex >= skipped ) {
- finalIndex++;
- }
- }
- this._bindToExternalToInternalMap.set( externalItem, item );
- this._bindToInternalToExternalMap.set( item, externalItem );
- this.add( item, finalIndex );
- // After adding new element to internal collection we need update indexes
- // of skipped items in external collection.
- for ( let i = 0; i < externalCollection._skippedIndexesFromExternal.length; i++ ) {
- if ( finalIndex <= externalCollection._skippedIndexesFromExternal[ i ] ) {
- externalCollection._skippedIndexesFromExternal[ i ]++;
- }
- }
- }
- };
- // Load the initial content of the collection.
- for ( const externalItem of externalCollection ) {
- addItem( null, externalItem, externalCollection.getIndex( externalItem ) );
- }
- // Synchronize the with collection as new items are added.
- this.listenTo( externalCollection, 'add', addItem );
- // Synchronize the with collection as new items are removed.
- this.listenTo( externalCollection, 'remove', ( evt, externalItem, index ) => {
- const item = this._bindToExternalToInternalMap.get( externalItem );
- if ( item ) {
- this.remove( item );
- }
- // After removing element from external collection we need update/remove indexes
- // of skipped items in internal collection.
- this._skippedIndexesFromExternal = this._skippedIndexesFromExternal.reduce( ( result, skipped ) => {
- if ( index < skipped ) {
- result.push( skipped - 1 );
- }
- if ( index > skipped ) {
- result.push( skipped );
- }
- return result;
- }, [] );
- } );
- }
- /**
- * 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.
- *
- * @private
- * @param {Object} item Item to be added.
- * @returns {String}
- */
- _getItemIdBeforeAdding( item ) {
- const idProperty = this._idProperty;
- let itemId;
- if ( ( idProperty in item ) ) {
- itemId = item[ idProperty ];
- if ( typeof itemId != 'string' ) {
- /**
- * This item's ID should be a string.
- *
- * @error collection-add-invalid-id
- */
- throw new CKEditorError( 'collection-add-invalid-id: This item\'s ID should be a string.', this );
- }
- if ( this.get( itemId ) ) {
- /**
- * This item already exists in the collection.
- *
- * @error collection-add-item-already-exists
- */
- throw new CKEditorError( 'collection-add-item-already-exists: This item already exists in the collection.', this );
- }
- } else {
- item[ idProperty ] = itemId = uid();
- }
- return itemId;
- }
- /**
- * Core {@link #remove} method implementation shared in other functions.
- *
- * In contrast this method **does not** fire the {@link #event:change} event.
- *
- * @private
- * @param {Object} subject The item to remove, its id or index in the collection.
- * @returns {Array} Returns an array with the removed item and its index.
- * @fires remove
- */
- _remove( subject ) {
- let index, id, item;
- let itemDoesNotExist = false;
- const idProperty = this._idProperty;
- if ( typeof subject == 'string' ) {
- id = subject;
- item = this._itemMap.get( id );
- itemDoesNotExist = !item;
- if ( item ) {
- index = this._items.indexOf( item );
- }
- } else if ( typeof subject == 'number' ) {
- index = subject;
- item = this._items[ index ];
- itemDoesNotExist = !item;
- if ( item ) {
- id = item[ idProperty ];
- }
- } else {
- item = subject;
- id = item[ idProperty ];
- index = this._items.indexOf( item );
- itemDoesNotExist = ( index == -1 || !this._itemMap.get( id ) );
- }
- if ( itemDoesNotExist ) {
- /**
- * Item not found.
- *
- * @error collection-remove-404
- */
- throw new CKEditorError( 'collection-remove-404: Item not found.', this );
- }
- this._items.splice( index, 1 );
- this._itemMap.delete( id );
- const externalItem = this._bindToInternalToExternalMap.get( item );
- this._bindToInternalToExternalMap.delete( item );
- this._bindToExternalToInternalMap.delete( externalItem );
- this.fire( 'remove', item, index );
- return [ item, index ];
- }
- /**
- * Iterable interface.
- *
- * @returns {Iterable.<*>}
- */
- [ Symbol.iterator ]() {
- return this._items[ Symbol.iterator ]();
- }
- /**
- * Fired when an item is added to the collection.
- *
- * @event add
- * @param {Object} item The added item.
- */
- /**
- * Fired when the collection was changed due to adding or removing items.
- *
- * @event change
- * @param {Iterable.<Object>} added A list of added items.
- * @param {Iterable.<Object>} removed A list of removed items.
- * @param {Number} index An index where the addition or removal occurred.
- */
- /**
- * Fired when an item is removed from the collection.
- *
- * @event remove
- * @param {Object} item The removed item.
- * @param {Number} index Index from which item was removed.
- */
- }
- mix( Collection, EmitterMixin );
- /**
- * 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.
- *
- * @interface module:utils/collection~CollectionBindToChain
- */
- /**
- * Creates a callback or a property binding.
- *
- * @method #using
- * @param {Function|String} 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.
- */
- /**
- * Creates the class factory binding in which items of the source collection are passed to
- * the constructor of the specified class.
- *
- * @method #as
- * @param {Function} Class The class constructor used to create instances in the factory.
- */
|