8
0

collection.js 7.0 KB

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