collection.js 6.9 KB

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