collection.js 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module utils/collection
  7. */
  8. import EmitterMixin from './emittermixin';
  9. import CKEditorError from './ckeditorerror';
  10. import uid from './uid';
  11. import isIterable from './isiterable';
  12. import mix from './mix';
  13. /**
  14. * Collections are ordered sets of objects. Items in the collection can be retrieved by their indexes
  15. * in the collection (like in an array) or by their ids.
  16. *
  17. * If an object without an `id` property is being added to the collection, the `id` property will be generated
  18. * automatically. Note that the automatically generated id is unique only within this single collection instance.
  19. *
  20. * By default an item in the collection is identified by its `id` property. The name of the identifier can be
  21. * configured through the constructor of the collection.
  22. *
  23. * @mixes module:utils/emittermixin~EmitterMixin
  24. */
  25. export default class Collection {
  26. /**
  27. * Creates a new Collection instance.
  28. *
  29. * You can provide an iterable of initial items the collection will be created with:
  30. *
  31. * const collection = new Collection( [ { id: 'John' }, { id: 'Mike' } ] );
  32. *
  33. * console.log( collection.get( 0 ) ); // -> { id: 'John' }
  34. * console.log( collection.get( 1 ) ); // -> { id: 'Mike' }
  35. * console.log( collection.get( 'Mike' ) ); // -> { id: 'Mike' }
  36. *
  37. * Or you can first create a collection and then add new items using the {@link #add} method:
  38. *
  39. * const collection = new Collection();
  40. *
  41. * collection.add( { id: 'John' } );
  42. * console.log( collection.get( 0 ) ); // -> { id: 'John' }
  43. *
  44. * Whatever option you choose, you can always pass a configuration object as the last argument
  45. * of the constructor:
  46. *
  47. * const emptyCollection = new Collection( { idProperty: 'name' } );
  48. * emptyCollection.add( { name: 'John' } );
  49. * console.log( collection.get( 'John' ) ); // -> { name: 'John' }
  50. *
  51. * const nonEmptyCollection = new Collection( [ { name: 'John' } ], { idProperty: 'name' } );
  52. * nonEmptyCollection.add( { name: 'George' } );
  53. * console.log( collection.get( 'George' ) ); // -> { name: 'George' }
  54. * console.log( collection.get( 'John' ) ); // -> { name: 'John' }
  55. *
  56. * @param {Iterable.<Object>|Object} initialItemsOrOptions The initial items of the collection or
  57. * the options object.
  58. * @param {Object} [options={}] The options object, when the first argument is an array of initial items.
  59. * @param {String} [options.idProperty='id'] The name of the property which is used to identify an item.
  60. * Items that do not have such a property will be assigned one when added to the collection.
  61. */
  62. constructor( initialItemsOrOptions = {}, options = {} ) {
  63. const hasInitialItems = isIterable( initialItemsOrOptions );
  64. if ( !hasInitialItems ) {
  65. options = initialItemsOrOptions;
  66. }
  67. /**
  68. * The internal list of items in the collection.
  69. *
  70. * @private
  71. * @member {Object[]}
  72. */
  73. this._items = [];
  74. /**
  75. * The internal map of items in the collection.
  76. *
  77. * @private
  78. * @member {Map}
  79. */
  80. this._itemMap = new Map();
  81. /**
  82. * The name of the property which is considered to identify an item.
  83. *
  84. * @private
  85. * @member {String}
  86. */
  87. this._idProperty = options.idProperty || 'id';
  88. /**
  89. * A helper mapping external items of a bound collection ({@link #bindTo})
  90. * and actual items of this collection. It provides information
  91. * necessary to properly remove items bound to another collection.
  92. *
  93. * See {@link #_bindToInternalToExternalMap}.
  94. *
  95. * @protected
  96. * @member {WeakMap}
  97. */
  98. this._bindToExternalToInternalMap = new WeakMap();
  99. /**
  100. * A helper mapping items of this collection to external items of a bound collection
  101. * ({@link #bindTo}). It provides information necessary to manage the bindings, e.g.
  102. * to avoid loops in two–way bindings.
  103. *
  104. * See {@link #_bindToExternalToInternalMap}.
  105. *
  106. * @protected
  107. * @member {WeakMap}
  108. */
  109. this._bindToInternalToExternalMap = new WeakMap();
  110. /**
  111. * Stores indexes of skipped items from bound external collection.
  112. *
  113. * @private
  114. * @member {Array}
  115. */
  116. this._skippedIndexesFromExternal = [];
  117. // Set the initial content of the collection (if provided in the constructor).
  118. if ( hasInitialItems ) {
  119. for ( const item of initialItemsOrOptions ) {
  120. this._items.push( item );
  121. this._itemMap.set( this._getItemIdBeforeAdding( item ), item );
  122. }
  123. }
  124. /**
  125. * A collection instance this collection is bound to as a result
  126. * of calling {@link #bindTo} method.
  127. *
  128. * @protected
  129. * @member {module:utils/collection~Collection} #_bindToCollection
  130. */
  131. }
  132. /**
  133. * The number of items available in the collection.
  134. *
  135. * @member {Number} #length
  136. */
  137. get length() {
  138. return this._items.length;
  139. }
  140. /**
  141. * Returns the first item from the collection or null when collection is empty.
  142. *
  143. * @returns {Object|null} The first item or `null` if collection is empty.
  144. */
  145. get first() {
  146. return this._items[ 0 ] || null;
  147. }
  148. /**
  149. * Returns the last item from the collection or null when collection is empty.
  150. *
  151. * @returns {Object|null} The last item or `null` if collection is empty.
  152. */
  153. get last() {
  154. return this._items[ this.length - 1 ] || null;
  155. }
  156. /**
  157. * Adds an item into the collection.
  158. *
  159. * If the item does not have an id, then it will be automatically generated and set on the item.
  160. *
  161. * @chainable
  162. * @param {Object} item
  163. * @param {Number} [index] The position of the item in the collection. The item
  164. * is pushed to the collection when `index` not specified.
  165. * @fires add
  166. * @fires change
  167. */
  168. add( item, index ) {
  169. return this.addMany( [ item ], index );
  170. }
  171. /**
  172. * Adds multiple items into the collection.
  173. *
  174. * Any item not containing an id will get an automatically generated one.
  175. *
  176. * @chainable
  177. * @param {Iterable.<Object>} item
  178. * @param {Number} [index] The position of the insertion. Items will be appended if no `index` is specified.
  179. * @fires add
  180. * @fires change
  181. */
  182. addMany( items, index ) {
  183. if ( index === undefined ) {
  184. index = this._items.length;
  185. } else if ( index > this._items.length || index < 0 ) {
  186. /**
  187. * The `index` passed to {@link module:utils/collection~Collection#addMany `Collection#addMany()`}
  188. * is invalid. It must be a number between 0 and the collection's length.
  189. *
  190. * @error collection-add-item-bad-index
  191. */
  192. throw new CKEditorError( 'collection-add-item-invalid-index: The index passed to Collection#addMany() is invalid.', this );
  193. }
  194. for ( let offset = 0; offset < items.length; offset++ ) {
  195. const item = items[ offset ];
  196. const itemId = this._getItemIdBeforeAdding( item );
  197. const currentItemIndex = index + offset;
  198. this._items.splice( currentItemIndex, 0, item );
  199. this._itemMap.set( itemId, item );
  200. this.fire( 'add', item, currentItemIndex );
  201. }
  202. this.fire( 'change', {
  203. added: items,
  204. removed: [],
  205. index
  206. } );
  207. return this;
  208. }
  209. /**
  210. * Gets an item by its ID or index.
  211. *
  212. * @param {String|Number} idOrIndex The item ID or index in the collection.
  213. * @returns {Object|null} The requested item or `null` if such item does not exist.
  214. */
  215. get( idOrIndex ) {
  216. let item;
  217. if ( typeof idOrIndex == 'string' ) {
  218. item = this._itemMap.get( idOrIndex );
  219. } else if ( typeof idOrIndex == 'number' ) {
  220. item = this._items[ idOrIndex ];
  221. } else {
  222. /**
  223. * An index or ID must be given.
  224. *
  225. * @error collection-get-invalid-arg
  226. */
  227. throw new CKEditorError( 'collection-get-invalid-arg: An index or ID must be given.', this );
  228. }
  229. return item || null;
  230. }
  231. /**
  232. * Returns a Boolean indicating whether the collection contains an item.
  233. *
  234. * @param {Object|String} itemOrId The item or its ID in the collection.
  235. * @returns {Boolean} `true` if the collection contains the item, `false` otherwise.
  236. */
  237. has( itemOrId ) {
  238. if ( typeof itemOrId == 'string' ) {
  239. return this._itemMap.has( itemOrId );
  240. } else { // Object
  241. const idProperty = this._idProperty;
  242. const id = itemOrId[ idProperty ];
  243. return this._itemMap.has( id );
  244. }
  245. }
  246. /**
  247. * Gets an index of an item in the collection.
  248. * When an item is not defined in the collection, the index will equal -1.
  249. *
  250. * @param {Object|String} itemOrId The item or its ID in the collection.
  251. * @returns {Number} The index of a given item.
  252. */
  253. getIndex( itemOrId ) {
  254. let item;
  255. if ( typeof itemOrId == 'string' ) {
  256. item = this._itemMap.get( itemOrId );
  257. } else {
  258. item = itemOrId;
  259. }
  260. return this._items.indexOf( item );
  261. }
  262. /**
  263. * Removes an item from the collection.
  264. *
  265. * @param {Object|Number|String} subject The item to remove, its ID or index in the collection.
  266. * @returns {Object} The removed item.
  267. * @fires remove
  268. * @fires change
  269. */
  270. remove( subject ) {
  271. const [ item, index ] = this._remove( subject );
  272. this.fire( 'change', {
  273. added: [],
  274. removed: [ item ],
  275. index
  276. } );
  277. return item;
  278. }
  279. /**
  280. * Executes the callback for each item in the collection and composes an array or values returned by this callback.
  281. *
  282. * @param {Function} callback
  283. * @param {Object} callback.item
  284. * @param {Number} callback.index
  285. * @param {Object} ctx Context in which the `callback` will be called.
  286. * @returns {Array} The result of mapping.
  287. */
  288. map( callback, ctx ) {
  289. return this._items.map( callback, ctx );
  290. }
  291. /**
  292. * Finds the first item in the collection for which the `callback` returns a true value.
  293. *
  294. * @param {Function} callback
  295. * @param {Object} callback.item
  296. * @param {Number} callback.index
  297. * @param {Object} ctx Context in which the `callback` will be called.
  298. * @returns {Object} The item for which `callback` returned a true value.
  299. */
  300. find( callback, ctx ) {
  301. return this._items.find( callback, ctx );
  302. }
  303. /**
  304. * Returns an array with items for which the `callback` returned a true value.
  305. *
  306. * @param {Function} callback
  307. * @param {Object} callback.item
  308. * @param {Number} callback.index
  309. * @param {Object} ctx Context in which the `callback` will be called.
  310. * @returns {Object[]} The array with matching items.
  311. */
  312. filter( callback, ctx ) {
  313. return this._items.filter( callback, ctx );
  314. }
  315. /**
  316. * Removes all items from the collection and destroys the binding created using
  317. * {@link #bindTo}.
  318. *
  319. * @fires remove
  320. * @fires change
  321. */
  322. clear() {
  323. if ( this._bindToCollection ) {
  324. this.stopListening( this._bindToCollection );
  325. this._bindToCollection = null;
  326. }
  327. const removedItems = Array.from( this._items );
  328. while ( this.length ) {
  329. this._remove( 0 );
  330. }
  331. this.fire( 'change', {
  332. added: [],
  333. removed: removedItems,
  334. index: 0
  335. } );
  336. }
  337. /**
  338. * Binds and synchronizes the collection with another one.
  339. *
  340. * The binding can be a simple factory:
  341. *
  342. * class FactoryClass {
  343. * constructor( data ) {
  344. * this.label = data.label;
  345. * }
  346. * }
  347. *
  348. * const source = new Collection( { idProperty: 'label' } );
  349. * const target = new Collection();
  350. *
  351. * target.bindTo( source ).as( FactoryClass );
  352. *
  353. * source.add( { label: 'foo' } );
  354. * source.add( { label: 'bar' } );
  355. *
  356. * console.log( target.length ); // 2
  357. * console.log( target.get( 1 ).label ); // 'bar'
  358. *
  359. * source.remove( 0 );
  360. * console.log( target.length ); // 1
  361. * console.log( target.get( 0 ).label ); // 'bar'
  362. *
  363. * or the factory driven by a custom callback:
  364. *
  365. * class FooClass {
  366. * constructor( data ) {
  367. * this.label = data.label;
  368. * }
  369. * }
  370. *
  371. * class BarClass {
  372. * constructor( data ) {
  373. * this.label = data.label;
  374. * }
  375. * }
  376. *
  377. * const source = new Collection( { idProperty: 'label' } );
  378. * const target = new Collection();
  379. *
  380. * target.bindTo( source ).using( ( item ) => {
  381. * if ( item.label == 'foo' ) {
  382. * return new FooClass( item );
  383. * } else {
  384. * return new BarClass( item );
  385. * }
  386. * } );
  387. *
  388. * source.add( { label: 'foo' } );
  389. * source.add( { label: 'bar' } );
  390. *
  391. * console.log( target.length ); // 2
  392. * console.log( target.get( 0 ) instanceof FooClass ); // true
  393. * console.log( target.get( 1 ) instanceof BarClass ); // true
  394. *
  395. * or the factory out of property name:
  396. *
  397. * const source = new Collection( { idProperty: 'label' } );
  398. * const target = new Collection();
  399. *
  400. * target.bindTo( source ).using( 'label' );
  401. *
  402. * source.add( { label: { value: 'foo' } } );
  403. * source.add( { label: { value: 'bar' } } );
  404. *
  405. * console.log( target.length ); // 2
  406. * console.log( target.get( 0 ).value ); // 'foo'
  407. * console.log( target.get( 1 ).value ); // 'bar'
  408. *
  409. * It's possible to skip specified items by returning falsy value:
  410. *
  411. * const source = new Collection();
  412. * const target = new Collection();
  413. *
  414. * target.bindTo( source ).using( item => {
  415. * if ( item.hidden ) {
  416. * return null;
  417. * }
  418. *
  419. * return item;
  420. * } );
  421. *
  422. * source.add( { hidden: true } );
  423. * source.add( { hidden: false } );
  424. *
  425. * console.log( source.length ); // 2
  426. * console.log( target.length ); // 1
  427. *
  428. * **Note**: {@link #clear} can be used to break the binding.
  429. *
  430. * @param {module:utils/collection~Collection} externalCollection A collection to be bound.
  431. * @returns {Object}
  432. * @returns {module:utils/collection~CollectionBindToChain} The binding chain object.
  433. */
  434. bindTo( externalCollection ) {
  435. if ( this._bindToCollection ) {
  436. /**
  437. * The collection cannot be bound more than once.
  438. *
  439. * @error collection-bind-to-rebind
  440. */
  441. throw new CKEditorError( 'collection-bind-to-rebind: The collection cannot be bound more than once.', this );
  442. }
  443. this._bindToCollection = externalCollection;
  444. return {
  445. as: Class => {
  446. this._setUpBindToBinding( item => new Class( item ) );
  447. },
  448. using: callbackOrProperty => {
  449. if ( typeof callbackOrProperty == 'function' ) {
  450. this._setUpBindToBinding( item => callbackOrProperty( item ) );
  451. } else {
  452. this._setUpBindToBinding( item => item[ callbackOrProperty ] );
  453. }
  454. }
  455. };
  456. }
  457. /**
  458. * Finalizes and activates a binding initiated by {#bindTo}.
  459. *
  460. * @protected
  461. * @param {Function} factory A function which produces collection items.
  462. */
  463. _setUpBindToBinding( factory ) {
  464. const externalCollection = this._bindToCollection;
  465. // Adds the item to the collection once a change has been done to the external collection.
  466. //
  467. // @private
  468. const addItem = ( evt, externalItem, index ) => {
  469. const isExternalBoundToThis = externalCollection._bindToCollection == this;
  470. const externalItemBound = externalCollection._bindToInternalToExternalMap.get( externalItem );
  471. // If an external collection is bound to this collection, which makes it a 2–way binding,
  472. // and the particular external collection item is already bound, don't add it here.
  473. // The external item has been created **out of this collection's item** and (re)adding it will
  474. // cause a loop.
  475. if ( isExternalBoundToThis && externalItemBound ) {
  476. this._bindToExternalToInternalMap.set( externalItem, externalItemBound );
  477. this._bindToInternalToExternalMap.set( externalItemBound, externalItem );
  478. } else {
  479. const item = factory( externalItem );
  480. // When there is no item we need to remember skipped index first and then we can skip this item.
  481. if ( !item ) {
  482. this._skippedIndexesFromExternal.push( index );
  483. return;
  484. }
  485. // Lets try to put item at the same index as index in external collection
  486. // but when there are a skipped items in one or both collections we need to recalculate this index.
  487. let finalIndex = index;
  488. // When we try to insert item after some skipped items from external collection we need
  489. // to include this skipped items and decrease index.
  490. //
  491. // For the following example:
  492. // external -> [ 'A', 'B - skipped for internal', 'C - skipped for internal' ]
  493. // internal -> [ A ]
  494. //
  495. // Another item is been added at the end of external collection:
  496. // external.add( 'D' )
  497. // external -> [ 'A', 'B - skipped for internal', 'C - skipped for internal', 'D' ]
  498. //
  499. // We can't just add 'D' to internal at the same index as index in external because
  500. // this will produce empty indexes what is invalid:
  501. // internal -> [ 'A', empty, empty, 'D' ]
  502. //
  503. // So we need to include skipped items and decrease index
  504. // internal -> [ 'A', 'D' ]
  505. for ( const skipped of this._skippedIndexesFromExternal ) {
  506. if ( index > skipped ) {
  507. finalIndex--;
  508. }
  509. }
  510. // We need to take into consideration that external collection could skip some items from
  511. // internal collection.
  512. //
  513. // For the following example:
  514. // internal -> [ 'A', 'B - skipped for external', 'C - skipped for external' ]
  515. // external -> [ A ]
  516. //
  517. // Another item is been added at the end of external collection:
  518. // external.add( 'D' )
  519. // external -> [ 'A', 'D' ]
  520. //
  521. // We need to include skipped items and place new item after them:
  522. // internal -> [ 'A', 'B - skipped for external', 'C - skipped for external', 'D' ]
  523. for ( const skipped of externalCollection._skippedIndexesFromExternal ) {
  524. if ( finalIndex >= skipped ) {
  525. finalIndex++;
  526. }
  527. }
  528. this._bindToExternalToInternalMap.set( externalItem, item );
  529. this._bindToInternalToExternalMap.set( item, externalItem );
  530. this.add( item, finalIndex );
  531. // After adding new element to internal collection we need update indexes
  532. // of skipped items in external collection.
  533. for ( let i = 0; i < externalCollection._skippedIndexesFromExternal.length; i++ ) {
  534. if ( finalIndex <= externalCollection._skippedIndexesFromExternal[ i ] ) {
  535. externalCollection._skippedIndexesFromExternal[ i ]++;
  536. }
  537. }
  538. }
  539. };
  540. // Load the initial content of the collection.
  541. for ( const externalItem of externalCollection ) {
  542. addItem( null, externalItem, externalCollection.getIndex( externalItem ) );
  543. }
  544. // Synchronize the with collection as new items are added.
  545. this.listenTo( externalCollection, 'add', addItem );
  546. // Synchronize the with collection as new items are removed.
  547. this.listenTo( externalCollection, 'remove', ( evt, externalItem, index ) => {
  548. const item = this._bindToExternalToInternalMap.get( externalItem );
  549. if ( item ) {
  550. this.remove( item );
  551. }
  552. // After removing element from external collection we need update/remove indexes
  553. // of skipped items in internal collection.
  554. this._skippedIndexesFromExternal = this._skippedIndexesFromExternal.reduce( ( result, skipped ) => {
  555. if ( index < skipped ) {
  556. result.push( skipped - 1 );
  557. }
  558. if ( index > skipped ) {
  559. result.push( skipped );
  560. }
  561. return result;
  562. }, [] );
  563. } );
  564. }
  565. /**
  566. * Returns an unique id property for a given `item`.
  567. *
  568. * The method will generate new id and assign it to the `item` if it doesn't have any.
  569. *
  570. * @private
  571. * @param {Object} item Item to be added.
  572. * @returns {String}
  573. */
  574. _getItemIdBeforeAdding( item ) {
  575. const idProperty = this._idProperty;
  576. let itemId;
  577. if ( ( idProperty in item ) ) {
  578. itemId = item[ idProperty ];
  579. if ( typeof itemId != 'string' ) {
  580. /**
  581. * This item's ID should be a string.
  582. *
  583. * @error collection-add-invalid-id
  584. */
  585. throw new CKEditorError( 'collection-add-invalid-id: This item\'s ID should be a string.', this );
  586. }
  587. if ( this.get( itemId ) ) {
  588. /**
  589. * This item already exists in the collection.
  590. *
  591. * @error collection-add-item-already-exists
  592. */
  593. throw new CKEditorError( 'collection-add-item-already-exists: This item already exists in the collection.', this );
  594. }
  595. } else {
  596. item[ idProperty ] = itemId = uid();
  597. }
  598. return itemId;
  599. }
  600. /**
  601. * Core {@link #remove} method implementation shared in other functions.
  602. *
  603. * In contrast this method **does not** fire the {@link #event:change} event.
  604. *
  605. * @private
  606. * @param {Object} subject The item to remove, its id or index in the collection.
  607. * @returns {Array} Returns an array with the removed item and its index.
  608. * @fires remove
  609. */
  610. _remove( subject ) {
  611. let index, id, item;
  612. let itemDoesNotExist = false;
  613. const idProperty = this._idProperty;
  614. if ( typeof subject == 'string' ) {
  615. id = subject;
  616. item = this._itemMap.get( id );
  617. itemDoesNotExist = !item;
  618. if ( item ) {
  619. index = this._items.indexOf( item );
  620. }
  621. } else if ( typeof subject == 'number' ) {
  622. index = subject;
  623. item = this._items[ index ];
  624. itemDoesNotExist = !item;
  625. if ( item ) {
  626. id = item[ idProperty ];
  627. }
  628. } else {
  629. item = subject;
  630. id = item[ idProperty ];
  631. index = this._items.indexOf( item );
  632. itemDoesNotExist = ( index == -1 || !this._itemMap.get( id ) );
  633. }
  634. if ( itemDoesNotExist ) {
  635. /**
  636. * Item not found.
  637. *
  638. * @error collection-remove-404
  639. */
  640. throw new CKEditorError( 'collection-remove-404: Item not found.', this );
  641. }
  642. this._items.splice( index, 1 );
  643. this._itemMap.delete( id );
  644. const externalItem = this._bindToInternalToExternalMap.get( item );
  645. this._bindToInternalToExternalMap.delete( item );
  646. this._bindToExternalToInternalMap.delete( externalItem );
  647. this.fire( 'remove', item, index );
  648. return [ item, index ];
  649. }
  650. /**
  651. * Iterable interface.
  652. *
  653. * @returns {Iterable.<*>}
  654. */
  655. [ Symbol.iterator ]() {
  656. return this._items[ Symbol.iterator ]();
  657. }
  658. /**
  659. * Fired when an item is added to the collection.
  660. *
  661. * @event add
  662. * @param {Object} item The added item.
  663. */
  664. /**
  665. * Fired when the collection was changed due to adding or removing items.
  666. *
  667. * @event change
  668. * @param {Iterable.<Object>} added A list of added items.
  669. * @param {Iterable.<Object>} removed A list of removed items.
  670. * @param {Number} index An index where the addition or removal occurred.
  671. */
  672. /**
  673. * Fired when an item is removed from the collection.
  674. *
  675. * @event remove
  676. * @param {Object} item The removed item.
  677. * @param {Number} index Index from which item was removed.
  678. */
  679. }
  680. mix( Collection, EmitterMixin );
  681. /**
  682. * An object returned by the {@link module:utils/collection~Collection#bindTo `bindTo()`} method
  683. * providing functions that specify the type of the binding.
  684. *
  685. * See the {@link module:utils/collection~Collection#bindTo `bindTo()`} documentation for examples.
  686. *
  687. * @interface module:utils/collection~CollectionBindToChain
  688. */
  689. /**
  690. * Creates a callback or a property binding.
  691. *
  692. * @method #using
  693. * @param {Function|String} callbackOrProperty When the function is passed, it should return
  694. * the collection items. When the string is provided, the property value is used to create the bound collection items.
  695. */
  696. /**
  697. * Creates the class factory binding in which items of the source collection are passed to
  698. * the constructor of the specified class.
  699. *
  700. * @method #as
  701. * @param {Function} Class The class constructor used to create instances in the factory.
  702. */