1 | // Last module patch version validated against: 1.0.7
|
2 |
|
3 | /**
|
4 | * Reference type things that can be coerced to string implicitly
|
5 | */
|
6 | export interface Stringifiable {
|
7 | toString(): string;
|
8 | }
|
9 |
|
10 | // ---------------------------------------------------------------------
|
11 | // Objects
|
12 | // ---------------------------------------------------------------------
|
13 |
|
14 | /**
|
15 | * Returns an array containing the property names of the specified object (an associative array).
|
16 | * The order of the returned array is undefined.
|
17 | *
|
18 | * @param obj An object.
|
19 | */
|
20 | export function keys(obj: object): string[];
|
21 |
|
22 | /**
|
23 | * Returns an array containing the property values of the specified object (an associative array).
|
24 | * The order of the returned array is undefined.
|
25 | *
|
26 | * The generic refers to the data type of the values.
|
27 | *
|
28 | * @param obj An object.
|
29 | */
|
30 | export function values<T>(obj: { [key: string]: T } | ArrayLike<T>): T[];
|
31 | /**
|
32 | * Returns an array containing the property values of the specified object (an associative array).
|
33 | * The order of the returned array is undefined.
|
34 | *
|
35 | * @param obj An object.
|
36 | */
|
37 | export function values(obj: object): any[];
|
38 |
|
39 | /**
|
40 | * Returns an array containing the property keys and values of the specified object (an associative array).
|
41 | * Each entry is an object with a key and value attribute.The order of the returned array is undefined.
|
42 | *
|
43 | * The generic refers to the data type of the values.
|
44 | *
|
45 | * @param obj An object.
|
46 | */
|
47 | export function entries<T>(obj: { [key: string]: T } | ArrayLike<T>): Array<{ key: string; value: T }>;
|
48 | /**
|
49 | * Returns an array containing the property keys and values of the specified object (an associative array).
|
50 | * Each entry is an object with a key and value attribute.The order of the returned array is undefined.
|
51 | *
|
52 | * @param obj An object.
|
53 | */
|
54 | export function entries(obj: object): Array<{ key: string; value: any }>;
|
55 |
|
56 | // ---------------------------------------------------------------------
|
57 | // map / Map
|
58 | // ---------------------------------------------------------------------
|
59 |
|
60 | /**
|
61 | * A data structure similar to ES6 Maps, but with a few differences:
|
62 | * - Keys are coerced to strings.
|
63 | * - map.each, not map.forEach. (Also, no thisArg.)
|
64 | * - map.remove, not map.delete.
|
65 | * - map.entries returns an array of {key, value} objects, not an iterator of [key, value].
|
66 | * - map.size is a method, not a property; also, there’s map.empty.
|
67 | *
|
68 | * The generic refers to the data type of the map entry values.
|
69 | */
|
70 | export interface Map<T> {
|
71 | /**
|
72 | * Returns true if and only if this map has an entry for the specified key string.
|
73 | * Note: the value may be null or undefined.
|
74 | *
|
75 | * @param key Key of map entry to access.
|
76 | */
|
77 | has(key: string): boolean;
|
78 | /**
|
79 | * Returns the value for the specified key string.
|
80 | * If the map does not have an entry for the specified key, returns undefined.
|
81 | *
|
82 | * @param key Key of map entry to access.
|
83 | */
|
84 | get(key: string): T | undefined;
|
85 | /**
|
86 | * Sets the value for the specified key string and returns the updated map.
|
87 | * If the map previously had an entry for the same key string, the old entry is replaced with the new value.
|
88 | *
|
89 | * @param key Key of map entry to access.
|
90 | * @param value Value to set for entry at key.
|
91 | */
|
92 | set(key: string, value: T): this;
|
93 | /**
|
94 | * If the map has an entry for the specified key string, removes the entry and returns true.
|
95 | * Otherwise, this method does nothing and returns false.
|
96 | *
|
97 | * @param key Map key for which to remove the entry.
|
98 | */
|
99 | remove(key: string): boolean;
|
100 | /**
|
101 | * Removes all entries from this map.
|
102 | */
|
103 | clear(): void;
|
104 | /**
|
105 | * Returns an array of string keys for every entry in this map.
|
106 | * The order of the returned keys is arbitrary.
|
107 | */
|
108 | keys(): string[];
|
109 | /**
|
110 | * Returns an array of values for every entry in this map.
|
111 | * The order of the returned values is arbitrary.
|
112 | */
|
113 | values(): T[];
|
114 | /**
|
115 | * Returns an array of key-value objects for each entry in this map. The order of the returned entries is arbitrary.
|
116 | * Each entry’s key is a string, but the value can have arbitrary type.
|
117 | */
|
118 | entries(): Array<{ key: string; value: T }>;
|
119 | /**
|
120 | * Calls the specified function for each entry in this map and returns undefined.
|
121 | * The iteration order is arbitrary.
|
122 | *
|
123 | * @param func Function to call for each entry. The function is passed the entry’s value and key as arguments,
|
124 | * followed by the map itself.
|
125 | */
|
126 | each(func: (value: T, key: string, map: Map<T>) => void): void;
|
127 | /**
|
128 | * Returns true if and only if this map has zero entries.
|
129 | */
|
130 | empty(): boolean;
|
131 | /**
|
132 | * Returns the number of entries in this map.
|
133 | */
|
134 | size(): number;
|
135 | }
|
136 |
|
137 | /**
|
138 | * Constructs a new empty map.
|
139 | *
|
140 | * The generic refers to the data type of the map entry values.
|
141 | */
|
142 | export function map<T = any>(): Map<T>;
|
143 | /**
|
144 | * Constructs a new map by copying another map.
|
145 | *
|
146 | * The generic refers to the data type of the map entry values.
|
147 | *
|
148 | * @param d3Map A D3 Map.
|
149 | */
|
150 | export function map<T>(d3Map: Map<T>): Map<T>;
|
151 | /**
|
152 | * Constructs a new map by copying all enumerable properties from the specified object into this map.
|
153 | *
|
154 | * The generic refers to the data type of the map entry values.
|
155 | *
|
156 | * @param obj Object to construct the map from.
|
157 | */
|
158 | export function map<T>(obj: { [key: string]: T }): Map<T>;
|
159 | /**
|
160 | * Constructs a new map by copying all enumerable properties from the specified object into this map.
|
161 | *
|
162 | * The generic refers to the data type of the map entry values.
|
163 | *
|
164 | * @param obj Object to construct the map from.
|
165 | */
|
166 | export function map<T>(obj: { [key: number]: T }): Map<T>;
|
167 | /**
|
168 | * Constructs a new map from the elements of an array.
|
169 | * An optional key function may be specified to compute the key for each value in the array.
|
170 | *
|
171 | * The generic refers to the data type of the map entry values.
|
172 | *
|
173 | * @param array Array to convert into a map
|
174 | * @param key An optional key function. The functions is invoked for each element in the array being passed
|
175 | * the element's value , it's zero-based index in the array, and the array itself. The function must return a unique string
|
176 | * to be used as the map entry's key.
|
177 | */
|
178 | export function map<T>(array: T[], key?: (value: T, i?: number, array?: T[]) => string): Map<T>;
|
179 | /**
|
180 | * Constructs a new map by copying all enumerable properties from the specified object into this map.
|
181 | *
|
182 | * @param obj Object to construct the map from.
|
183 | */
|
184 | export function map(obj: object): Map<any>;
|
185 |
|
186 | // ---------------------------------------------------------------------
|
187 | // set / Set
|
188 | // ---------------------------------------------------------------------
|
189 |
|
190 | /**
|
191 | * A data structure similar to ES6 Sets, but with a few differences:
|
192 | *
|
193 | * - Values are coerced to strings.
|
194 | * - set.each, not set.forEach. (Also, no thisArg.)
|
195 | * - set.remove, not set.delete.
|
196 | * - set.size is a method, not a property; also, there’s set.empty.
|
197 | */
|
198 | export interface Set {
|
199 | /**
|
200 | * Returns true if and only if this set has an entry for the specified value string.
|
201 | *
|
202 | * @param value Value whose membership in the class to test.
|
203 | */
|
204 | has(value: string | Stringifiable): boolean;
|
205 | /**
|
206 | * Adds the specified value string to this set and returns the set.
|
207 | *
|
208 | * @param value Value to add to set.
|
209 | */
|
210 | add(value: string | Stringifiable): this;
|
211 | /**
|
212 | * If the set contains the specified value string, removes it and returns true.
|
213 | * Otherwise, this method does nothing and returns false.
|
214 | *
|
215 | * @param value Value to remove from set.
|
216 | */
|
217 | remove(value: string | Stringifiable): boolean;
|
218 | /**
|
219 | * Removes all values from this set.
|
220 | */
|
221 | clear(): void;
|
222 | /**
|
223 | * Returns an array of the string values in this set. The order of the returned values is arbitrary.
|
224 | * Can be used as a convenient way of computing the unique values for a set of strings.
|
225 | */
|
226 | values(): string[];
|
227 | /**
|
228 | * Calls the specified function for each value in this set, passing the value as the first two arguments (for symmetry with map.each),
|
229 | * followed by the set itself. Returns undefined.
|
230 | * The iteration order is arbitrary.
|
231 | *
|
232 | * @param func Function to call for each set element. The first and second argument of the function are both passed
|
233 | * the 'value' of the set entry for consistency with the map.each(...) signature, as a third argument the entire set is passed in.
|
234 | */
|
235 | each(func: (value: string, valueRepeat: string, set: Set) => void): void;
|
236 | /**
|
237 | * Returns true if and only if this set has zero values.
|
238 | */
|
239 | empty(): boolean;
|
240 | /**
|
241 | * Returns the number of values in this set.
|
242 | */
|
243 | size(): number;
|
244 | }
|
245 |
|
246 | /**
|
247 | * Constructs a new empty set.
|
248 | */
|
249 | export function set(): Set;
|
250 | /**
|
251 | * Constructs a new set by copying an existing set.
|
252 | *
|
253 | * @param set A D3 set.
|
254 | */
|
255 | export function set(d3Set: Set): Set;
|
256 | /**
|
257 | * Constructs a new set by adding the given array of string values to the returned set.
|
258 | *
|
259 | * @param array An array of strings of values which can be implicitly converted to strings.
|
260 | */
|
261 | export function set(array: Array<string | Stringifiable>): Set;
|
262 | /**
|
263 | * Constructs a new set from an array, adds an array of mapped string values to the returned set.
|
264 | * The specified accessor function is invoked equivalent to calling array.map(accessor) before constructing the set.
|
265 | *
|
266 | * The generic refers to the data type of the array elements.
|
267 | *
|
268 | * @param array An Array of values to map and add as set elements.
|
269 | * @param key An accessor function used to map the original array elements to string elements to be added to the set.
|
270 | * The function is invoked for each array element, being passed the element's value, it's zero-based index in the array, and the array itself.
|
271 | */
|
272 | export function set<T>(array: T[], key: (value: T, index: number, array: T[]) => string): Set;
|
273 |
|
274 | // ---------------------------------------------------------------------
|
275 | // nest / Nest
|
276 | // ---------------------------------------------------------------------
|
277 |
|
278 | /**
|
279 | * A more formal definition of the nested array returned by Nest.entries(...). This data structure is intended as a reference only.
|
280 | *
|
281 | * As the union types cannot be ex ante simplified without knowledge
|
282 | * of the nesting level (number of key(...) operations) and whether the data were rolled-up, this data structure becomes cumbersome
|
283 | * to use in practice. This is particularly true for discrimination of array element types.
|
284 | * The use of the rollup function, or lack thereof, also determines whether NestedArray has the 'values' property
|
285 | * with an array of type Datum at leaf level, or has a rolled-up 'value' property.
|
286 | */
|
287 | export interface NestedArray<Datum, RollupType> extends
|
288 | Array<
|
289 | { key: string; values: NestedArray<Datum, RollupType> | Datum[] | undefined; value: RollupType | undefined }
|
290 | >
|
291 | {}
|
292 |
|
293 | /**
|
294 | * A more formal definition of the nested array returned by Nest.map(...). This data structure is intended as a reference only.
|
295 | *
|
296 | * As the union types cannot be ex ante simplified without knowledge
|
297 | * of the nesting level (number of key(...) operations) and whether the data were rolled-up, this data structure becomes cumbersome
|
298 | * to use in practice.
|
299 | */
|
300 | export interface NestedMap<Datum, RollupType> extends Map<NestedMap<Datum, RollupType> | Datum[] | RollupType> {}
|
301 |
|
302 | /**
|
303 | * A more formal definition of the nested array returned by Nest.object(...). This data structure is intended as a reference only.
|
304 | *
|
305 | * As the union types cannot be ex ante simplified without knowledge
|
306 | * of the nesting level (number of key(...) operations) and whether the data were rolled-up, this data structure becomes cumbersome
|
307 | * to use in practice.
|
308 | */
|
309 | export interface NestedObject<Datum, RollupType> {
|
310 | [key: string]: NestedObject<Datum, RollupType> | Datum[] | RollupType;
|
311 | }
|
312 |
|
313 | /**
|
314 | * A nest operator for generating nested data structures from arrays.
|
315 | *
|
316 | * Nesting allows elements in an array to be grouped into a hierarchical tree structure;
|
317 | * think of it like the GROUP BY operator in SQL, except you can have multiple levels of grouping, and the resulting output is a tree rather than a flat table.
|
318 | * The levels in the tree are specified by key functions. The leaf nodes of the tree can be sorted by value, while the internal nodes can be sorted by key.
|
319 | * An optional rollup function will collapse the elements in each leaf node using a summary function.
|
320 | * The nest operator is reusable, and does not retain any references to the data that is nested.
|
321 | *
|
322 | * The first generic refers to the data type of the array elements on which the nest operator will
|
323 | * be invoked.
|
324 | *
|
325 | * The second generic refers to the data type returned by the roll-up function to be used with the
|
326 | * nest operator.
|
327 | */
|
328 | export interface Nest<Datum, RollupType> {
|
329 | /**
|
330 | * Registers a new key function and returns this nest operator.
|
331 | * The key function will be invoked for each element in the input array and must return a string identifier to assign the element to its group.
|
332 | * Most often, the function is a simple accessor. (Keys functions are not passed the input array index.)
|
333 | *
|
334 | * Each time a key is registered, it is pushed onto the end of the internal array of keys,
|
335 | * and the nest operator applies an additional level of nesting.
|
336 | *
|
337 | * @param func A key accessor function being invoked for each element.
|
338 | */
|
339 | key(func: (datum: Datum) => string): this;
|
340 | /**
|
341 | * Sorts key values for the current key using the specified comparator function, such as d3.ascending or d3.descending.
|
342 | *
|
343 | * If no comparator is specified for the current key, the order in which keys will be returned is undefined.
|
344 | *
|
345 | * Note that this only affects the result of nest.entries;
|
346 | * the order of keys returned by nest.map and nest.object is always undefined, regardless of comparator.
|
347 | *
|
348 | * @param comparator A comparator function which returns a negative value if, according to the sorting criterion,
|
349 | * a is less than b, or a positive value if a is greater than b, or 0 if the two values are the same under the sorting criterion.
|
350 | */
|
351 | sortKeys(comparator: (a: string, b: string) => number): this;
|
352 | /**
|
353 | * Sorts leaf elements using the specified comparator function, such as d3.ascending or d3.descending.
|
354 | * This is roughly equivalent to sorting the input array before applying the nest operator;
|
355 | * however it is typically more efficient as the size of each group is smaller.
|
356 | *
|
357 | * If no value comparator is specified, elements will be returned in the order they appeared in the input array.
|
358 | * This applies to nest.map, nest.entries and nest.object.
|
359 | *
|
360 | * @param comparator A comparator function which returns a negative value if, according to the sorting criterion,
|
361 | * a is less than b, or a positive value if a is greater than b, or 0 if the two values are the same under the sorting criterion.
|
362 | */
|
363 | sortValues(comparator: (a: Datum, b: Datum) => number): this;
|
364 | /**
|
365 | * Specifies a rollup function to be applied on each group of leaf elements and returns this nest operator.
|
366 | * The return value of the rollup function will replace the array of leaf values in either the associative array returned by nest.map or nest.object;
|
367 | * for nest.entries, it replaces the leaf entry.values with entry.value.
|
368 | *
|
369 | * If a leaf comparator is specified, the leaf elements are sorted prior to invoking the rollup function.
|
370 | *
|
371 | * @param func A function computing the rollup value for a group of leaf elements.
|
372 | */
|
373 | rollup(func: (values: Datum[]) => RollupType): this;
|
374 | /**
|
375 | * Applies the nest operator to the specified array, returning a nested map.
|
376 | *
|
377 | * Each entry in the returned map corresponds to a distinct key value returned by the first key function.
|
378 | * The entry value depends on the number of registered key functions: if there is an additional key, the value is another map;
|
379 | * otherwise, the value is the array of elements filtered from the input array that have the given key value.
|
380 | *
|
381 | * NOTE:
|
382 | *
|
383 | * Strictly speaking the return type of this method is:
|
384 | *
|
385 | * (1) NestedMap<Datum, RollupType>, if at least one key function was defined,
|
386 | *
|
387 | * (2) Datum[], if neither a key nor a rollup function were defined, and
|
388 | *
|
389 | * (3) RollupType, if no keys, but a rollup function were defined.
|
390 | *
|
391 | * Since (2) and (3) are edge cases with little to no practical relevance, they have been omitted in favour of ease-of-use.
|
392 | *
|
393 | * Should you determine that this simplification creates an issue in practice, please file an issue on
|
394 | * https://github.com/DefinitelyTyped/DefinitelyTyped.
|
395 | *
|
396 | * The formal, generalized return type under (1) is cumbersome to work with in practice. The recommended approach
|
397 | * is to define the type of the variable being assigned the return value using knowledge specific to the use-case at hand.
|
398 | * I.e. making use of knowing how many keys are applied, and the nature of any roll-up function will make working with
|
399 | * the variable more meaningful, despite the compromise in type-safety.
|
400 | *
|
401 | * @param array An array to create a nested data structure from.
|
402 | */
|
403 | map(array: Datum[]): Map<any>;
|
404 | /**
|
405 | * Applies the nest operator to the specified array, returning a nested object.
|
406 | * Each entry in the returned associative array corresponds to a distinct key value returned by the first key function.
|
407 | * The entry value depends on the number of registered key functions: if there is an additional key, the value is another associative array;
|
408 | * otherwise, the value is the array of elements filtered from the input array that have the given key value.
|
409 | *
|
410 | * WARNING: this method is unsafe if any of the keys conflict with built-in JavaScript properties, such as __proto__.
|
411 | * If you cannot guarantee that the keys will be safe, you should use nest.map instead.
|
412 | *
|
413 | * NOTE:
|
414 | *
|
415 | * Strictly speaking the return type of this method is:
|
416 | *
|
417 | * (1) NestedObject<Datum, RollupType>, if at least one key function was defined,
|
418 | *
|
419 | * (2) Datum[], if neither a key nor a rollup function were defined, and
|
420 | *
|
421 | * (3) RollupType, if no keys, but a rollup function were defined.
|
422 | *
|
423 | * Since (2) and (3) are edge cases with little to no practical relevance, they have been omitted in favour of ease-of-use.
|
424 | *
|
425 | * Should you determine that this simplification creates an issue in practice, please file an issue on
|
426 | * https://github.com/DefinitelyTyped/DefinitelyTyped.
|
427 | *
|
428 | * The formal, generalized return type under (1) is cumbersome to work with in practice. The recommended approach
|
429 | * is to define the type of the variable being assigned the return value using knowledge specific to the use-case at hand.
|
430 | * I.e. making use of knowing how many keys are applied, and the nature of any roll-up function will make working with
|
431 | * the variable more meaningful, despite the compromise in type-safety.
|
432 | *
|
433 | * @param array An array to create a nested data structure from.
|
434 | */
|
435 | object(array: Datum[]): { [key: string]: any };
|
436 | /**
|
437 | * Applies the nest operator to the specified array, returning an array of key-values entries.
|
438 | * Conceptually, this is similar to applying map.entries to the associative array returned by nest.map,
|
439 | * but it applies to every level of the hierarchy rather than just the first (outermost) level.
|
440 | * Each entry in the returned array corresponds to a distinct key value returned by the first key function.
|
441 | * The entry value depends on the number of registered key functions: if there is an additional key, the value is another nested array of entries;
|
442 | * otherwise, the value is the array of elements filtered from the input array that have the given key value.
|
443 | *
|
444 | * NOTE:
|
445 | *
|
446 | * Strictly speaking the return type of this method is:
|
447 | *
|
448 | * (1) NestedArray<Datum, RollupType>, if at least one key function was defined,
|
449 | *
|
450 | * (2) Datum[], if neither a key nor a rollup function were defined, and
|
451 | *
|
452 | * (3) RollupType, if no keys, but a rollup function were defined.
|
453 | *
|
454 | * Since (2) and (3) are edge cases with little to no practical relevance, they have been omitted in favour of ease-of-use.
|
455 | *
|
456 | * Should you determine that this simplification creates an issue in practice, please file an issue on
|
457 | * https://github.com/DefinitelyTyped/DefinitelyTyped.
|
458 | *
|
459 | * The formal, generalized return type under (1) is cumbersome to work with in practice. The recommended approach
|
460 | * is to define the type of the variable being assigned the return value using knowledge specific to the use-case at hand.
|
461 | * I.e. making use of knowing how many keys are applied, and the nature of any roll-up function will make working with
|
462 | * the variable more meaningful, despite the compromise in type-safety.
|
463 | *
|
464 | * @param array An array to create a nested data structure from.
|
465 | */
|
466 | entries(array: Datum[]): Array<{ key: string; values: any; value: RollupType | undefined }>;
|
467 | }
|
468 |
|
469 | /**
|
470 | * Creates a new nest operator.
|
471 | *
|
472 | * The first generic refers to the data type of the array elements on which the nest operator will
|
473 | * be invoked.
|
474 | *
|
475 | * The second generic refers to the data type returned by the roll-up function to be used with the
|
476 | * nest operator. If not explicitly set, this generic parameter defaults to undefined, implying that
|
477 | * no rollup function will be applied.
|
478 | */
|
479 | export function nest<Datum, RollupType = undefined>(): Nest<Datum, RollupType>;
|