index.d.ts 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312
  1. /**
  2. * Debounce fn, calling it only once if
  3. * the given time elapsed between calls.
  4. *
  5. * @param {Function} fn
  6. * @param {Number} timeout
  7. *
  8. * @return {Function} debounced function
  9. */
  10. export function debounce(fn: Function, timeout: number): (...args: any[]) => void;
  11. /**
  12. * Throttle fn, calling at most once
  13. * in the given interval.
  14. *
  15. * @param {Function} fn
  16. * @param {Number} interval
  17. *
  18. * @return {Function} throttled function
  19. */
  20. export function throttle(fn: Function, interval: number): (...args: any[]) => void;
  21. /**
  22. * Bind function against target <this>.
  23. *
  24. * @param {Function} fn
  25. * @param {Object} target
  26. *
  27. * @return {Function} bound function
  28. */
  29. export function bind<T extends Function>(fn: T, target: object): T;
  30. /**
  31. * Copy the values of all of the enumerable own properties from one or more source objects to a
  32. * target object. Returns the target object.
  33. * @param target The target object to copy to.
  34. * @param source The source object from which to copy properties.
  35. */
  36. export function assign<T, U>(target: T, source: U): T & U;
  37. /**
  38. * Copy the values of all of the enumerable own properties from one or more source objects to a
  39. * target object. Returns the target object.
  40. * @param target The target object to copy to.
  41. * @param source1 The first source object from which to copy properties.
  42. * @param source2 The second source object from which to copy properties.
  43. */
  44. export function assign<T, U, V>(target: T, source1: U, source2: V): T & U & V;
  45. /**
  46. * Copy the values of all of the enumerable own properties from one or more source objects to a
  47. * target object. Returns the target object.
  48. * @param target The target object to copy to.
  49. * @param source1 The first source object from which to copy properties.
  50. * @param source2 The second source object from which to copy properties.
  51. * @param source3 The third source object from which to copy properties.
  52. */
  53. export function assign<T, U, V, W>(target: T, source1: U, source2: V, source3: W): T & U & V & W;
  54. /**
  55. * Copy the values of all of the enumerable own properties from one or more source objects to a
  56. * target object. Returns the target object.
  57. * @param target The target object to copy to.
  58. * @param sources One or more source objects from which to copy properties
  59. */
  60. export function assign<T>(target: T, ...sources: any[]): T;
  61. /**
  62. * Gets a nested property of a given object, with an optional default value.
  63. *
  64. * @param target The target of the get operation.
  65. * @param path The path to the nested value.
  66. * @param defaultValue The result to return if the property does not exist.
  67. */
  68. export function get(target: any, path: (string|number)[], defaultValue?: any): any;
  69. /**
  70. * Sets a nested property of a given object to the specified value.
  71. *
  72. * This mutates the object and returns it.
  73. *
  74. * @param target The target of the set operation.
  75. * @param path The path to the nested value.
  76. * @param value The value to set.
  77. */
  78. export function set<T>(target: T, path: (string|number)[], value: any): T;
  79. export function pick<T>(target: T, properties: (keyof T)[]): Pick<T, keyof T>;
  80. /**
  81. * Pick all target properties, excluding the given ones.
  82. *
  83. * @param {Object} target
  84. * @param {Array} properties
  85. *
  86. * @return {Object} target
  87. */
  88. export function omit<T>(target: T, properties: (keyof T)[]): Exclude<T, keyof T>;
  89. /**
  90. * Copy the values of all of the enumerable own properties from one or more source objects to a
  91. * target object. Returns the target object.
  92. * @param target The target object to copy to.
  93. * @param sources One or more source objects from which to copy properties
  94. */
  95. export function merge(target: object, ...sources: any[]): any;
  96. export function isUndefined(obj: any): obj is null | undefined;
  97. export function isDefined(obj: any): obj is Exclude<any, null | undefined>;
  98. export function isNil(obj: any): obj is object;
  99. export function isArray(obj: any): obj is Array<any>;
  100. export function isObject(obj: any): obj is object;
  101. export function isNumber(obj: any): obj is number;
  102. export function isFunction(obj: any): obj is Function;
  103. export function isString(obj: any): obj is string;
  104. /**
  105. * Ensure collection is an array.
  106. *
  107. * @param {Object} obj
  108. */
  109. export function ensureArray<T>(obj: Collection<T>): void | never;
  110. /**
  111. * Return true, if target owns a property with the given key.
  112. *
  113. * @param {Object} target
  114. * @param {String} key
  115. *
  116. * @return {Boolean}
  117. */
  118. export function has(target: any, key: string): boolean;
  119. export type Matcher<T> = ((e: T) => boolean) | ((e: T, idx: number) => boolean) | keyof T;
  120. export type Extractor<T, U=T[keyof T]> = ((e: T) => U) | keyof T;
  121. export type ArrayCollection<T> = Array<T>;
  122. export type StringKeyValueCollection<T> = { [key: string]: T };
  123. export type NumberKeyValueCollection<T> = { [key: number]: T };
  124. export type KeyValueCollection<T> = StringKeyValueCollection<T> | NumberKeyValueCollection<T>;
  125. export type Collection<T> = KeyValueCollection<T> | ArrayCollection<T>;
  126. /**
  127. * Find element in collection.
  128. *
  129. * @param {Array|Object} collection
  130. * @param {Function|Object} matcher
  131. *
  132. * @return {Object}
  133. */
  134. export function find<T>(collection: Collection<T>, matcher: Matcher<T>): T | undefined;
  135. /**
  136. * Find element index in collection.
  137. *
  138. * @param {Array|Object} collection
  139. * @param {Function} matcher
  140. *
  141. * @return {Object}
  142. */
  143. export function findIndex<T>(collection: Collection<T>, matcher: Matcher<T>): number | undefined;
  144. /**
  145. * Find element in collection.
  146. *
  147. * @param {Array|Object} collection
  148. * @param {Function} matcher
  149. *
  150. * @return {Array} result
  151. */
  152. export function filter<T>(collection: Collection<T>, matcher: Matcher<T>): T[];
  153. /**
  154. * Iterate over collection; returning something
  155. * (non-undefined) will stop iteration.
  156. *
  157. * @param {Array|Object} collection
  158. * @param {Function} iterator
  159. *
  160. * @return {Object} return result that stopped the iteration
  161. */
  162. export function forEach<T>(collection: Collection<T>, iterator: (item: T, convertKey: any /* TODO */) => boolean | void): T;
  163. /**
  164. * Return collection without element.
  165. *
  166. * @param {Array} arr
  167. * @param {Function} matcher
  168. *
  169. * @return {Array}
  170. */
  171. export function without<T>(arr: T[], matcher: Matcher<T>): T[];
  172. /**
  173. * Reduce collection, returning a single result.
  174. *
  175. * @param {Object|Array} collection
  176. * @param {Function} iterator
  177. * @param {Any} result
  178. *
  179. * @return {Any} result returned from last iterator
  180. */
  181. export function reduce<T>(collection: Collection<T>, iterator: (...args: any[]) => T, result: T): T;
  182. /**
  183. * Return true if every element in the collection
  184. * matches the criteria.
  185. *
  186. * @param {Object|Array} collection
  187. * @param {Function} matcher
  188. *
  189. * @return {Boolean}
  190. */
  191. export function every<T>(collection: Collection<T>, matcher: Matcher<T>): boolean;
  192. /**
  193. * Return true if some elements in the collection
  194. * match the criteria.
  195. *
  196. * @param {Object|Array} collection
  197. * @param {Function} matcher
  198. *
  199. * @return {Boolean}
  200. */
  201. export function some<T>(collection: Collection<T>, matcher: Matcher<T>): boolean;
  202. /**
  203. * Transform a collection into another collection
  204. * by piping each member through the given fn.
  205. *
  206. * @param {Object|Array} collection
  207. * @param {Function} fn
  208. *
  209. * @return {Array} transformed collection
  210. */
  211. export function map<T, U>(collection: Collection<T>, fn: (value: T, key: number) => U): U[];
  212. /**
  213. * Get the collections keys.
  214. *
  215. * @param {Object|Array} collection
  216. *
  217. * @return {Array}
  218. */
  219. export function keys<T>(collection: Collection<T>): T extends Array<any> ? number[] : (keyof T)[];
  220. /**
  221. * Shorthand for `keys(o).length`.
  222. *
  223. * @param {Object|Array} collection
  224. *
  225. * @return {Number}
  226. */
  227. export function size<T>(collection: Collection<T>): number;
  228. /**
  229. * Get the values in the collection.
  230. *
  231. * @param {Object|Array} collection
  232. *
  233. * @return {Array}
  234. */
  235. export function values<T>(collection: Collection<T>): T[];
  236. /**
  237. * Group collection members by attribute.
  238. *
  239. * @param {Object|Array} collection
  240. * @param {Function} extractor
  241. *
  242. * @return {Object} map with { attrValue => [ a, b, c ] }
  243. */
  244. export function groupBy<T>(collection: Collection<T>, extractor: Extractor<T>, grouped?: any): { [attrValue: string]: any[] };
  245. export function uniqueBy<T>(extractor: Extractor<T>, ...collections: Collection<T>[]): T[];
  246. export function unionBy<T>(extractor: Extractor<T>, ...collections: Collection<T>[]): T[];
  247. /**
  248. * Sort collection by criteria.
  249. *
  250. * @param {Object|Array} collection
  251. * @param {String|Function} extractor
  252. *
  253. * @return {Array}
  254. */
  255. export function sortBy<T>(collection: Collection<T>, extractor: Extractor<T, number | string>): T[];
  256. /**
  257. * Create an object pattern matcher.
  258. *
  259. * @example
  260. *
  261. * const matcher = matchPattern({ id: 1 });
  262. *
  263. * let element = find(elements, matcher);
  264. *
  265. * @param {Object} pattern
  266. *
  267. * @return {Function} matcherFn
  268. */
  269. export function matchPattern<T>(pattern: T): (e: Partial<T>) => boolean;
  270. /**
  271. * Flatten array, one level deep.
  272. *
  273. * @param {Array<?>} arr
  274. *
  275. * @return {Array<?>}
  276. */
  277. export function flatten<T>(arr: T[][]): T[];