diff --git a/lib/node_modules/@stdlib/utils/group-own/docs/types/index.d.ts b/lib/node_modules/@stdlib/utils/group-own/docs/types/index.d.ts index fc10b592ee3c..3cdcc72fda61 100644 --- a/lib/node_modules/@stdlib/utils/group-own/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/utils/group-own/docs/types/index.d.ts @@ -38,7 +38,7 @@ interface Options { * * @returns group key */ -type Nullary = () => string | symbol; +type Nullary = () => K; /** * Specifies which group a property belongs to. @@ -46,7 +46,7 @@ type Nullary = () => string | symbol; * @param value - object value * @returns group key */ -type Unary = ( value: any ) => string | symbol; +type Unary = ( value: V ) => K; /** * Specifies which group a property belongs to. @@ -55,7 +55,7 @@ type Unary = ( value: any ) => string | symbol; * @param key - object key * @returns group key */ -type Binary = ( value: any, key: string | symbol ) => string | symbol; +type Binary = ( value: V, key: string ) => K; /** * Specifies which group a property belongs to. @@ -64,7 +64,7 @@ type Binary = ( value: any, key: string | symbol ) => string | symbol; * @param key - object key * @returns group key */ -type Indicator = Nullary | Unary | Binary; +type Indicator = Nullary | Unary | Binary; /** * Groups an object's own property values according to an indicator function. @@ -93,15 +93,18 @@ type Indicator = Nullary | Unary | Binary; * return v[ 0 ]; * } * var obj = { -* 'a': 'beep', -* 'b': 'boop', -* 'c': 'foo', -* 'd': 'bar' +* 'a': 'apple', +* 'b': 'banana', +* 'c': 'cherry', +* 'd': 'date' * }; * var out = groupOwn( obj, indicator ); -* // e.g., returns { 'b': [ 'beep', 'boop', 'bar' ], 'f': [ 'foo' ] } +* // e.g., returns { 'a': [ 'apple' ], 'b': [ 'banana' ], 'c': [ 'cherry' ], 'd': [ 'date' ] } */ -declare function groupOwn( obj: any, indicator: Indicator ): any; +declare function groupOwn( + obj: T, + indicator: Indicator +): { [P in K]: Array }; /** * Groups an object's own property values according to an indicator function. @@ -124,7 +127,7 @@ declare function groupOwn( obj: any, indicator: Indicator ): any; * @param obj - input object * @param options - function options * @param options.thisArg - execution context -* @param options.returns - if `values`, values are returned; if `keys`, keys are returned; if `*`, both keys and values are returned (default: 'values') +* @param options.returns - if `'values'`, values are returned; if `'indices'`, indices are returned; if `'*'`, both indices and values are returned (default: 'values') * @param indicator - indicator function indicating which group an element in the input object belongs to * @returns group results * @@ -133,47 +136,116 @@ declare function groupOwn( obj: any, indicator: Indicator ): any; * return v[ 0 ]; * } * var obj = { -* 'a': 'beep', -* 'b': 'boop', -* 'c': 'foo', -* 'd': 'bar' +* 'a': 'apple', +* 'b': 'banana', +* 'c': 'cherry', +* 'd': 'date' * }; -* var out = groupOwn( obj, indicator ); -* // e.g., returns { 'b': [ 'beep', 'boop', 'bar' ], 'f': [ 'foo' ] } +* var opts = { +* 'returns': 'indices' +* }; +* var out = groupOwn( obj, opts, indicator ); +* // e.g., returns { 'a': [ 'a' ], 'b': [ 'b' ], 'c': [ 'c' ], 'd': [ 'd' ] } +*/ +declare function groupOwn( + obj: T, + options: Options & { returns: 'indices' }, + indicator: Indicator +): { [P in K]: Array }; + +/** +* Groups an object's own property values according to an indicator function. +* +* ## Notes +* +* - When invoked, the indicator function is provided two arguments: +* +* - `value`: object value +* - `key`: object key +* +* - The value returned by an indicator function should be a value which can be serialized as an object key. +* +* - If provided an empty object, the function returns an empty object. +* +* - The function iterates over an object's own properties. +* +* - Key iteration order is **not** guaranteed, and, thus, result order is **not** guaranteed. +* +* @param obj - input object +* @param options - function options +* @param options.thisArg - execution context +* @param options.returns - if `'values'`, values are returned; if `'indices'`, indices are returned; if `'*'`, both indices and values are returned (default: 'values') +* @param indicator - indicator function indicating which group an element in the input object belongs to +* @returns group results * * @example * function indicator( v ) { * return v[ 0 ]; * } * var obj = { -* 'a': 'beep', -* 'b': 'boop', -* 'c': 'foo', -* 'd': 'bar' +* 'a': 'apple', +* 'b': 'banana', +* 'c': 'cherry', +* 'd': 'date' * }; * var opts = { -* 'returns': 'keys' +* 'returns': '*' * }; * var out = groupOwn( obj, opts, indicator ); -* // e.g., returns { 'b': [ 'a', 'b', 'd' ], 'f': [ 'c' ] } +* // e.g., returns { 'a': [ [ 'a', 'apple' ] ], 'b': [ [ 'b', 'banana' ] ], 'c': [ [ 'c', 'cherry' ] ], 'd': [ [ 'd', 'date' ] ] } +*/ +declare function groupOwn( + obj: T, + options: Options & { returns: '*' }, + indicator: Indicator +): { [P in K]: Array<[keyof T, T[keyof T]]> }; + +/** +* Groups an object's own property values according to an indicator function. +* +* ## Notes +* +* - When invoked, the indicator function is provided two arguments: +* +* - `value`: object value +* - `key`: object key +* +* - The value returned by an indicator function should be a value which can be serialized as an object key. +* +* - If provided an empty object, the function returns an empty object. +* +* - The function iterates over an object's own properties. +* +* - Key iteration order is **not** guaranteed, and, thus, result order is **not** guaranteed. +* +* @param obj - input object +* @param options - function options +* @param options.thisArg - execution context +* @param options.returns - if `'values'`, values are returned; if `'indices'`, indices are returned; if `'*'`, both indices and values are returned (default: 'values') +* @param indicator - indicator function indicating which group an element in the input object belongs to +* @returns group results * * @example * function indicator( v ) { * return v[ 0 ]; * } * var obj = { -* 'a': 'beep', -* 'b': 'boop', -* 'c': 'foo', -* 'd': 'bar' +* 'a': 'apple', +* 'b': 'banana', +* 'c': 'cherry', +* 'd': 'date' * }; * var opts = { -* 'returns': '*' +* 'returns': 'values' * }; * var out = groupOwn( obj, opts, indicator ); -* // e.g., returns { 'b': [ [ 'a', 'beep' ], [ 'b', 'boop' ], [ 'd', 'bar' ] ], 'f': [ [ 'c', 'foo' ] ] } +* // e.g., returns { 'a': [ 'apple' ], 'b': [ 'banana' ], 'c': [ 'cherry' ], 'd': [ 'date' ] } */ -declare function groupOwn( obj: any, options: Options, indicator: Indicator ): any; +declare function groupOwn( + obj: T, + options: Options & { returns?: 'values' }, + indicator: Indicator +): { [P in K]: Array }; // EXPORTS // diff --git a/lib/node_modules/@stdlib/utils/group-own/docs/types/test.ts b/lib/node_modules/@stdlib/utils/group-own/docs/types/test.ts index 65e2c9cf75a3..4b2a72c3b2bd 100644 --- a/lib/node_modules/@stdlib/utils/group-own/docs/types/test.ts +++ b/lib/node_modules/@stdlib/utils/group-own/docs/types/test.ts @@ -46,12 +46,31 @@ class Foo { // The function returns an object... { const obj = new Foo(); - groupOwn( obj, indicator ); // $ExpectType any - groupOwn( {}, indicator ); // $ExpectType any + groupOwn( obj, indicator ); // $ExpectType { [x: string]: string[]; } + groupOwn( {}, indicator ); // $ExpectType { [x: string]: never[]; } const opts = { - 'returns': 'indices' as 'indices' + 'returns': 'indices' as const }; - groupOwn( obj, opts, indicator ); // $ExpectType any + groupOwn( obj, opts, indicator ); // $ExpectType { [x: string]: (keyof Foo)[]; } + + const opts2 = { + 'returns': 'values' as const + }; + groupOwn( obj, opts2, indicator ); // $ExpectType { [x: string]: string[]; } + + const opts3 = { + 'returns': '*' as const + }; + groupOwn( obj, opts3, indicator ); // $ExpectType { [x: string]: [keyof Foo, string][]; } + + const obj2 = { + 'beep': 'boop', + 'foo': 'bar' + } as const; + + groupOwn( obj2, opts, indicator ); // $ExpectType { [x: string]: ("beep" | "foo")[]; } + groupOwn( obj2, opts2, indicator ); // $ExpectType { [x: string]: ("boop" | "bar")[]; } + groupOwn( obj2, opts3, indicator ); // $ExpectType { [x: string]: ["beep" | "foo", "boop" | "bar"][]; } } // The compiler throws an error if the function is provided a last argument which is not a function...