8
0

collection.js 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275
  1. /**
  2. * @license Copyright (c) 2003-2015, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. 'use strict';
  6. /**
  7. * Collections are ordered sets of objects. Items in the collection can be retrieved by their indexes
  8. * in the collection (like in an array) or by their ids.
  9. *
  10. * If an object without an `id` property is being added to the collection, the `id` property will be generated
  11. * automatically. Note that the automatically generated id is unique only within this single collection instance.
  12. *
  13. * By default an item in the collection is identified by its `id` property. The name of the identifier can be
  14. * configured through the constructor of the collection.
  15. *
  16. * @class Collection
  17. * @mixins EventEmitter
  18. */
  19. CKEDITOR.define( [ 'emittermixin', 'ckeditorerror', 'utils' ], ( EmitterMixin, CKEditorError, utils ) => {
  20. class Collection {
  21. /**
  22. * Creates a new Collection instance.
  23. *
  24. * @constructor
  25. * @param {Iterale} [items] Items to be added to the collection.
  26. * @param {Object} options The options object.
  27. * @param {String} [options.idProperty='id'] The name of the property which is considered to identify an item.
  28. */
  29. constructor( options ) {
  30. /**
  31. * The internal list of items in the collection.
  32. *
  33. * @private
  34. * @property {Object[]}
  35. */
  36. this._items = [];
  37. /**
  38. * The internal map of items in the collection.
  39. *
  40. * @private
  41. * @property {Map}
  42. */
  43. this._itemMap = new Map();
  44. /**
  45. * Next id which will be assigned to unidentified item while adding it to the collection.
  46. *
  47. * @private
  48. * @property
  49. */
  50. this._nextId = 0;
  51. /**
  52. * The name of the property which is considered to identify an item.
  53. *
  54. * @private
  55. * @property {String}
  56. */
  57. this._idProperty = options && options.idProperty || 'id';
  58. }
  59. /**
  60. * The number of items available in the collection.
  61. *
  62. * @property length
  63. */
  64. get length() {
  65. return this._items.length;
  66. }
  67. /**
  68. * Adds an item into the collection.
  69. *
  70. * If the item does not have an id, then it will be automatically generated and set on the item.
  71. *
  72. * @chainable
  73. * @param {Object} item
  74. */
  75. add( item ) {
  76. let itemId;
  77. const idProperty = this._idProperty;
  78. if ( ( idProperty in item ) ) {
  79. itemId = item[ idProperty ];
  80. if ( typeof itemId != 'string' ) {
  81. /**
  82. * This item's id should be a string.
  83. *
  84. * @error collection-add-invalid-id
  85. */
  86. throw new CKEditorError( 'collection-add-invalid-id' );
  87. }
  88. if ( this.get( itemId ) ) {
  89. /**
  90. * This item already exists in the collection.
  91. *
  92. * @error collection-add-item-already-exists
  93. */
  94. throw new CKEditorError( 'collection-add-item-already-exists' );
  95. }
  96. } else {
  97. itemId = this._getNextId();
  98. item[ idProperty ] = itemId;
  99. }
  100. this._items.push( item );
  101. this._itemMap.set( itemId, item );
  102. this.fire( 'add', item );
  103. return this;
  104. }
  105. /**
  106. * Gets item by its id or index.
  107. *
  108. * @param {String|Number} idOrIndex The item id or index in the collection.
  109. * @returns {Object} The requested item or `null` if such item does not exist.
  110. */
  111. get( idOrIndex ) {
  112. let item;
  113. if ( typeof idOrIndex == 'string' ) {
  114. item = this._itemMap.get( idOrIndex );
  115. } else if ( typeof idOrIndex == 'number' ) {
  116. item = this._items[ idOrIndex ];
  117. } else {
  118. /**
  119. * Index or id must be given.
  120. *
  121. * @error collection-get-invalid-arg
  122. */
  123. throw new CKEditorError( 'collection-get-invalid-arg: Index or id must be given.' );
  124. }
  125. return item || null;
  126. }
  127. /**
  128. * Removes an item from the collection.
  129. *
  130. * @param {Object|Number|String} subject The item to remove, its id or index in the collection.
  131. * @returns {Object} The removed item.
  132. */
  133. remove( subject ) {
  134. let index, id, item;
  135. let itemDoesNotExist = false;
  136. const idProperty = this._idProperty;
  137. if ( typeof subject == 'string' ) {
  138. id = subject;
  139. item = this._itemMap.get( id );
  140. itemDoesNotExist = !item;
  141. if ( item ) {
  142. index = this._items.indexOf( item );
  143. }
  144. } else if ( typeof subject == 'number' ) {
  145. index = subject;
  146. item = this._items[ index ];
  147. itemDoesNotExist = !item;
  148. if ( item ) {
  149. id = item[ idProperty ];
  150. }
  151. } else {
  152. item = subject;
  153. id = item[ idProperty ];
  154. index = this._items.indexOf( item );
  155. itemDoesNotExist = ( index == -1 || !this._itemMap.get( id ) );
  156. }
  157. if ( itemDoesNotExist ) {
  158. /**
  159. * Item not found.
  160. *
  161. * @error collection-remove-404
  162. */
  163. throw new CKEditorError( 'collection-remove-404: Item not found.' );
  164. }
  165. this._items.splice( index, 1 );
  166. this._itemMap.delete( id );
  167. this.fire( 'remove', item );
  168. return item;
  169. }
  170. /**
  171. * Executes the callback for each item in the collection and composes an array or values returned by this callback.
  172. *
  173. * @param {Function} callback
  174. * @param {Item} callback.item
  175. * @param {Number} callback.index
  176. * @params {Object} ctx Context in which the `callback` will be called.
  177. * @returns {Array} The result of mapping.
  178. */
  179. map( callback, ctx ) {
  180. return this._items.map( callback, ctx );
  181. }
  182. /**
  183. * Finds the first item in the collection for which the `callback` returns a true value.
  184. *
  185. * @param {Function} callback
  186. * @param {Object} callback.item
  187. * @param {Number} callback.index
  188. * @returns {Object} The item for which `callback` returned a true value.
  189. * @params {Object} ctx Context in which the `callback` will be called.
  190. */
  191. find( callback, ctx ) {
  192. return this._items.find( callback, ctx );
  193. }
  194. /**
  195. * Returns an array with items for which the `callback` returned a true value.
  196. *
  197. * @param {Function} callback
  198. * @param {Object} callback.item
  199. * @param {Number} callback.index
  200. * @params {Object} ctx Context in which the `callback` will be called.
  201. * @returns {Object[]} The array with matching items.
  202. */
  203. filter( callback, ctx ) {
  204. return this._items.filter( callback, ctx );
  205. }
  206. /**
  207. * Collection iterator.
  208. */
  209. [ Symbol.iterator ]() {
  210. return this._items[ Symbol.iterator ]();
  211. }
  212. /**
  213. * Generates next (not yet used) id for unidentified item being add to the collection.
  214. *
  215. * @returns {String} The next id.
  216. */
  217. _getNextId() {
  218. let id;
  219. do {
  220. id = String( this._nextId++ );
  221. } while ( this._itemMap.has( id ) );
  222. return id;
  223. }
  224. }
  225. utils.extend( Collection.prototype, EmitterMixin );
  226. return Collection;
  227. } );
  228. /**
  229. * Fired when an item is added to the collection.
  230. *
  231. * @event add
  232. * @param {Object} item The added item.
  233. */
  234. /**
  235. * Fired when an item is removed from the collection.
  236. *
  237. * @event remove
  238. * @param {Object} item The removed item.
  239. */