From 57f5e9fa2352d64f59f660265b6b7211c5436e5d Mon Sep 17 00:00:00 2001 From: stdlib-bot <82920195+stdlib-bot@users.noreply.github.com> Date: Mon, 19 Jan 2026 02:55:01 +0000 Subject: [PATCH] feat: update `object` TypeScript declarations Signed-off-by: stdlib-bot <82920195+stdlib-bot@users.noreply.github.com> --- .../@stdlib/object/docs/types/index.d.ts | 717 ++++++++++++++++++ 1 file changed, 717 insertions(+) diff --git a/lib/node_modules/@stdlib/object/docs/types/index.d.ts b/lib/node_modules/@stdlib/object/docs/types/index.d.ts index 337aec14cde6..b8797f9bccad 100644 --- a/lib/node_modules/@stdlib/object/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/object/docs/types/index.d.ts @@ -20,18 +20,100 @@ /* eslint-disable max-lines */ +import anyInBy = require( '@stdlib/object/any-in-by' ); +import anyOwnBy = require( '@stdlib/object/any-own-by' ); import assign = require( '@stdlib/object/assign' ); import assignIn = require( '@stdlib/object/assign-in' ); +import bifurcateIn = require( '@stdlib/object/bifurcate-in' ); +import bifurcateOwn = require( '@stdlib/object/bifurcate-own' ); +import capitalizeKeys = require( '@stdlib/object/capitalize-keys' ); +import commonKeys = require( '@stdlib/object/common-keys' ); +import commonKeysIn = require( '@stdlib/object/common-keys-in' ); import Object = require( '@stdlib/object/ctor' ); +import deepGet = require( '@stdlib/object/deep-get' ); +import deepSet = require( '@stdlib/object/deep-set' ); import everyInBy = require( '@stdlib/object/every-in-by' ); import everyOwnBy = require( '@stdlib/object/every-own-by' ); +import forIn = require( '@stdlib/object/for-in' ); +import forOwn = require( '@stdlib/object/for-own' ); +import inverse = require( '@stdlib/object/inverse' ); +import inverseBy = require( '@stdlib/object/inverse-by' ); +import lowercaseKeys = require( '@stdlib/object/lowercase-keys' ); +import moveProperty = require( '@stdlib/object/move-property' ); import noneInBy = require( '@stdlib/object/none-in-by' ); +import noneOwnBy = require( '@stdlib/object/none-own-by' ); import someInBy = require( '@stdlib/object/some-in-by' ); +import someOwnBy = require( '@stdlib/object/some-own-by' ); +import uncapitalizeKeys = require( '@stdlib/object/uncapitalize-keys' ); +import uppercaseKeys = require( '@stdlib/object/uppercase-keys' ); /** * Interface describing the `object` namespace. */ interface Namespace { + /** + * Tests whether at least one property in an object passes a test implemented by a predicate function. + * + * ## Notes + * + * - The predicate function is provided three arguments: + * + * - `value`: property value + * - `key`: property key + * - `obj`: the input object + * + * - The function immediately returns upon encountering a truthy return value. + * + * - If provided an empty object, the function returns `false`. + * + * @param obj - input object + * @param predicate - test function + * @param thisArg - execution context + * @returns boolean indicating whether at least one property passes a test + * + * @example + * function isNegative( v ) { + * return ( v < 0 ); + * } + * + * var obj = { 'a': 1, 'b': -2, 'c': 3 }; + * + * var bool = ns.anyInBy( obj, isNegative ); + * // returns true + */ + anyInBy: typeof anyInBy; + + /** + * Tests whether any property of an object passes a test implemented by a predicate function. + * + * ## Notes + * + * - The predicate function is provided three arguments: + * + * - `value`: property value + * - `key`: property key + * - `object`: the input object + * + * - The function immediately returns upon encountering a truthy return value. + * - If provided an empty object, the function returns `false`. + * + * @param object - input object + * @param predicate - test function + * @param thisArg - execution context + * @returns boolean indicating whether any own property pass a test + * + * @example + * function isPositive( v ) { + * return ( v > 0 ); + * } + * + * var obj = { 'a': -1, 'b': 2, 'c': -3 }; + * + * var bool = ns.anyOwnBy( obj, isPositive ); + * // returns true + */ + anyOwnBy: typeof anyOwnBy; + /** * Copies own enumerable properties from one or more source objects to a target object. * @@ -93,6 +175,246 @@ interface Namespace { */ assignIn: typeof assignIn; + /** + * Splits an object's own and inherited property values into two groups according to a predicate function. + * + * ## Notes + * + * - When invoked, the predicate function is provided two arguments: + * + * - `value`: object value + * - `key`: object key + * + * - If a predicate function returns a truthy value, a value is placed in the first group; otherwise, a value is placed in the second group. + * + * - If provided an empty object with no prototype, the function returns an empty array. + * + * - The function iterates over an object's own and inherited 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 `'keys'`, keys are returned; if `'*'`, both keys and values are returned (default: 'values') + * @param predicate - predicate function indicating which group an element in the input object belongs to + * @returns group results + * + * @example + * function predicate( v ) { + * return v[ 0 ] === 'b'; + * } + * + * function Foo() { + * this.a = 'beep'; + * this.b = 'boop'; + * return this; + * } + * + * Foo.prototype = Object.create( null ); + * Foo.prototype.c = 'foo'; + * Foo.prototype.d = 'bar'; + * + * var obj = new Foo(); + * + * var opts = { + * 'returns': 'keys' + * }; + * var out = ns.bifurcateIn( obj, opts, predicate ); + * // e.g., returns [ [ 'a', 'b', 'd' ], [ 'c' ] ] + * + * @example + * function predicate( v ) { + * return v[ 0 ] === 'b'; + * } + * + * function Foo() { + * this.a = 'beep'; + * this.b = 'boop'; + * return this; + * } + * + * Foo.prototype = Object.create( null ); + * Foo.prototype.c = 'foo'; + * Foo.prototype.d = 'bar'; + * + * var obj = new Foo(); + * + * var opts = { + * 'returns': '*' + * }; + * var out = ns.bifurcateIn( obj, opts, predicate ); + * // e.g., returns [ [ [ 'a', 'beep' ], [ 'b', 'boop' ], [ 'd', 'bar' ] ], [ [ 'c', 'foo' ] ] ] + */ + bifurcateIn: typeof bifurcateIn; + + /** + * Splits an object's own property values into two groups according to a predicate function. + * + * @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 + * @param predicate - predicate function indicating which group an element in the input object belongs to + * @returns group results + * + * @example + * function predicate( v ) { + * return v[ 0 ] === 'b'; + * } + * var obj = { + * 'a': 'beep', + * 'b': 'boop', + * 'c': 'foo', + * 'd': 'bar' + * }; + * var out = ns.bifurcateOwn( obj, predicate ); + * // e.g., returns [ [ 'beep', 'boop', 'bar' ], [ 'foo' ] ] + * + * @example + * function predicate( v ) { + * return v[ 0 ] === 'b'; + * } + * var obj = { + * 'a': 'beep', + * 'b': 'boop', + * 'c': 'foo', + * 'd': 'bar' + * }; + * var opts = { + * 'returns': 'keys' + * }; + * var out = ns.bifurcateOwn( obj, opts, predicate ); + * // e.g., returns [ [ 'a', 'b', 'd' ], [ 'c' ] ] + * + * @example + * function predicate( v ) { + * return v[ 0 ] === 'b'; + * } + * var obj = { + * 'a': 'beep', + * 'b': 'boop', + * 'c': 'foo', + * 'd': 'bar' + * }; + * var opts = { + * 'returns': '*' + * }; + * var out = ns.bifurcateOwn( obj, opts, predicate ); + * // e.g., returns [ [ [ 'a', 'beep' ], [ 'b', 'boop' ], [ 'd', 'bar' ] ], [ [ 'c', 'foo' ] ] ] + */ + bifurcateOwn: typeof bifurcateOwn; + + /** + * Converts the first letter of each object key to uppercase. + * + * ## Notes + * + * - The function only transforms own properties. Hence, the function does not transform inherited properties. + * - The function shallow copies key values. + * + * @param obj - source object + * @returns new object + * + * @example + * var obj1 = { + * 'aa': 1, + * 'bb': 2 + * }; + * + * var obj2 = ns.capitalizeKeys( obj1 ); + * // returns { 'Aa': 1, 'Bb': 2 } + */ + capitalizeKeys: typeof capitalizeKeys; + + /** + * Returns the common own property names of two or more objects. + * + * @param obj1 - first object + * @param obj2 - second object + * @param obj - additional objects + * @returns common keys of objects + * + * @example + * var obj = { + * 'a': 1, + * 'b': 2, + * 'c': 3 + * }; + * + * var obj2 = { + * 'a': 1, + * 'b': 2 + * }; + * + * var keys = ns.commonKeys( obj, obj2 ); + * // returns [ 'a', 'b' ] + * + * @example + * var obj1 = { + * 'a': 1, + * 'b': 2, + * 'c': 3 + * }; + * + * var obj2 = { + * 'a': 1, + * 'b': 2 + * }; + * + * var obj3 = { + * 'a': 1, + * }; + * + * var keys = ns.commonKeys( obj1, obj2, obj3 ); + * // returns [ 'a' ] + */ + commonKeys: typeof commonKeys; + + /** + * Returns the common own and inherited property names of two or more objects. + * + * @param obj1 - first object + * @param obj2 - second object + * @param obj - additional objects + * @returns common keys + * + * @example + * var obj = { + * 'a': 1, + * 'b': 2, + * 'c': 3 + * }; + * + * var obj2 = { + * 'a': 1, + * 'b': 2 + * }; + * + * var keys = ns.commonKeysIn( obj, obj2 ); + * // returns [ 'a', 'b' ] + * + * @example + * var obj1 = { + * 'a': 1, + * 'b': 2, + * 'c': 3 + * }; + * + * var obj2 = { + * 'a': 1, + * 'b': 2 + * }; + * + * var obj3 = { + * 'a': 1, + * }; + * + * var keys = ns.commonKeysIn( obj1, obj2, obj3 ); + * // returns [ 'a' ] + */ + commonKeysIn: typeof commonKeysIn; + /** * Returns an object. * @@ -128,6 +450,88 @@ interface Namespace { */ Object: typeof Object; + /** + * Returns a nested property value. + * + * @param obj - input object + * @param path - key path + * @param options - function options + * @param options.sep - key path separator (default: '.') + * @returns nested property value + * + * @example + * var obj = { 'a': { 'b': { 'c': 'd' } } }; + * + * var val = ns.deepGet( obj, 'a.b.c' ); + * // returns 'd' + * + * @example + * var dget = ns.deepGet.factory( 'a/b/c', { + * 'sep': '/' + * }); + * + * var obj = { 'a': { 'b': { 'c': 'd' } } }; + * + * var val = dget( obj ); + * // returns 'd' + */ + deepGet: typeof deepGet; + + /** + * Sets a nested property value. + * + * @param obj - input object + * @param path - key path + * @param value - value to set + * @param options - function options + * @param options.create - boolean indicating whether to create a path if the key path does not already exist (default: false) + * @param options.sep - key path separator (default: '.') + * @returns boolean indicating if the property was successfully set + * + * @example + * var obj = { 'a': { 'b': { 'c': 'd' } } }; + * var bool = ns.deepSet( obj, 'a.b.c', 'woot' ); + * // returns true + * + * @example + * var obj = { 'a': { 'b': { 'c': 'd' } } }; + * var bool = ns.deepSet( obj, 'a.beep.c', 'boop' ); + * // returns false + * + * @example + * var obj = { 'a': { 'b': { 'c': 'd' } } }; + * var bool = ns.deepSet( null, 'a.beep.c', 'boop' ); + * // returns false + * + * @example + * var obj = { 'a': { 'b': { 'c': 'd' } } }; + * bool = ns.deepSet( 'bap', 'a.beep.c', 'boop' ); + * // returns false + * + * @example + * var arr = [ + * { 'a': [ {'x': 5} ] }, + * { 'a': [ {'x': 10} ] } + * ]; + * var bool = ns.deepSet( arr, '1.a.0.x', 25 ); + * // returns true + * + * @example + * var obj = { 'a': { 'b': { 'c': 'd' } } }; + * var bool = ns.deepSet( obj, 'a/b/c', 'beep', { + * 'sep': '/' + * }); + * // returns true + * + * @example + * var obj = { 'a': { 'b': { 'c': 'd' } } }; + * var bool = ns.deepSet( obj, 'a.e.c', 'boop', { + * 'create': true + * }); + * // returns true + */ + deepSet: typeof deepSet; + /** * Checks whether all own and inherited properties in an object pass a test implemented by a predicate function. * @@ -170,6 +574,211 @@ interface Namespace { */ everyOwnBy: typeof everyOwnBy; + /** + * Invokes a function once for each own and inherited enumerable property of an object. + * + * ## Notes + * + * - When invoked, the function is provided three arguments: + * + * - `value`: object property value + * - `key`: object property + * - `obj`: the input object + * + * - To terminate iteration before visiting all properties, the provided function must explicitly return `false`. + * + * - Iteration order is **not** guaranteed. + * + * + * @param obj - input object + * @param fcn - function to invoke + * @param thisArg - execution context + * @returns obj - input object + * + * @example + * function log( v, key ) { + * console.log( '%s: %d', key, v ); + * } + * + * function Foo() { + * this.a = 1; + * this.b = 2; + * return this; + * } + * + * Foo.prototype.c = 3; + * Foo.prototype.d = 4; + * + * var obj = new Foo(); + * + * ns.forIn( obj, log ); + */ + forIn: typeof forIn; + + /** + * Invokes a function once for each own enumerable property of an object. + * + * ## Notes + * + * - When invoked, the function is provided three arguments: + * + * - `value`: object property value + * - `key`: object property + * - `obj`: the input object + * + * - To terminate iteration before visiting all properties, the provided function must explicitly return `false`. + * + * - The function determines the list of own enumerable properties *before* invoking the provided function. Hence, any modifications made to the input object *after* calling this function (such as adding and removing properties) will *not* affect the list of visited properties. + * + * - Iteration order is **not** guaranteed. + * + * + * @param obj - input object + * @param fcn - function to invoke + * @param thisArg - execution context + * @returns obj - input object + * + * @example + * function log( v, key ) { + * console.log( '%s: %d', key, v ); + * } + * + * var obj = { + * 'a': 1, + * 'b': 2, + * 'c': 3, + * 'd': 4 + * }; + * + * ns.forOwn( obj, log ); + */ + forOwn: typeof forOwn; + + /** + * Inverts an object, such that keys become values and values become keys. + * + * @param obj - input object + * @param options - function options + * @param options.duplicates - boolean indicating whether to store duplicate keys (default: true) + * @returns inverted object + * + * @example + * var out = ns.inverse({ + * 'a': 'beep', + * 'b': 'boop' + * }); + * // returns { 'beep': 'a', 'boop': 'b' } + * + * @example + * var out = ns.inverse({ + * 'a': 'beep', + * 'b': 'beep' + * }); + * // returns { 'beep': [ 'a', 'b' ] } + * + * @example + * var obj = {}; + * obj.a = 'beep'; + * obj.b = 'boop'; + * obj.c = 'beep'; // inserted after `a` + * + * var out = ns.inverse( obj, { + * 'duplicates': false + * }); + * // returns { 'beep': 'c', 'boop': 'b' } + */ + inverse: typeof inverse; + + /** + * Inverts an object, such that keys become values and values become keys, according to a transform function. + * + * ## Notes + * + * - The transform function is provided three arguments: + * + * - `key`: object key. + * - `value`: object value corresponding to `key`. + * - `obj`: the input object. + * + * - The value returned by a transform function should be a value which can be serialized as an object key. Hence, beware when providing objects having values which are themselves objects. The function relies on native object serialization (`#toString`) when converting transform function return values to keys. + * + * - In older JavaScript engines, insertion order is not guaranteed, as object key enumeration was not specified according to the ECMAScript specification in earlier editions. In practice, however, most older engines use insertion order to sort an object's keys, thus allowing for deterministic inversion. + * + * @param obj - input object + * @param opts - function options + * @param opts.duplicates - boolean indicating whether to store duplicate keys (default: true) + * @param transform - transform function + * @returns inverted object + * + * @example + * function transform( key, value ) { + * return value; + * } + * + * var obj = {}; + * obj.a = 'beep'; + * obj.b = 'boop'; + * obj.c = 'beep'; // inserted after `a` + * + * var opts = { + * 'duplicates': false + * }; + * var out = ns.inverseBy( obj, opts, transform ); + * // returns { 'beep': 'c', 'boop': 'b' } + */ + inverseBy: typeof inverseBy; + + /** + * Converts each object key to lowercase. + * + * ## Notes + * + * - The function only transforms own properties. Hence, the function does not transform inherited properties. + * - The function shallow copies key values. + * + * @param obj - source object + * @returns new object + * + * @example + * var obj1 = { + * 'A': 1, + * 'B': 2 + * }; + * + * var obj2 = ns.lowercaseKeys( obj1 ); + * // returns { 'a': 1, 'b': 2 } + */ + lowercaseKeys: typeof lowercaseKeys; + + /** + * Moves a property from one object to another object. + * + * ## Notes + * + * - The property is deleted from the source object and the property's descriptor is preserved during transfer. + * - If a source property is not configurable, the function throws an error, as the property cannot be deleted from the source object. + * + * @param source - source object + * @param prop - property to move + * @param target - target object + * @returns boolean indicating whether operation was successful + * + * @example + * var obj1 = { 'a': 'b' }; + * var obj2 = {}; + * + * var bool = ns.moveProperty( obj1, 'a', obj2 ); + * // returns true + * + * @example + * var obj1 = { 'a': 'b' }; + * var obj2 = {}; + * + * var bool = ns.moveProperty( obj1, 'c', obj2 ); + * // returns false + */ + moveProperty: typeof moveProperty; + /** * Tests whether every property in a object fail a test implemented by a predicate function. * @@ -201,6 +810,37 @@ interface Namespace { */ noneInBy: typeof noneInBy; + /** + * Tests whether every property of an object fails a test implemented by a predicate function. + * + * ## Notes + * + * - The predicate function is provided three arguments: + * + * - `value`: property value + * - `key`: property key + * - `object`: the input object + * + * - The function immediately returns upon encountering a truthy return value. + * - If provided an empty object, the function returns `true`. + * + * @param object - input object + * @param predicate - test function + * @param thisArg - execution context + * @returns boolean indicating whether every property fails a test + * + * @example + * function isUnderage( v ) { + * return ( v < 18 ); + * } + * + * var obj = { 'a': 20, 'b': 22, 'c': 25 }; + * + * var bool = ns.noneOwnBy( obj, isUnderage ); + * // returns true + */ + noneOwnBy: typeof noneOwnBy; + /** * Tests whether an object contains at least `n` properties (own and inherited) which pass a test implemented by a predicate function. * @@ -234,6 +874,83 @@ interface Namespace { * // returns true */ someInBy: typeof someInBy; + + /** + * Tests whether an object contains at least `n` own properties which pass a test implemented by a predicate function. + * + * ## Notes + * + * - The predicate function is provided three arguments: + * + * - `value`: object value + * - `key`: object key + * - `obj`: the input object + * + * - The function immediately returns upon finding `n` successful properties. + * + * - If provided an empty object, the function returns `false`. + * + * @param obj - input object + * @param n - number of properties + * @param predicate - test function + * @param thisArg - execution context + * @returns boolean indicating whether an object contains at least `n` own properties which pass a test + * + * @example + * function isNegative( v ) { + * return ( v < 0 ); + * } + * + * var obj = { a: 1, b: 2, c: -3, d: 4, e: -1 }; + * + * var bool = ns.someOwnBy( obj, 2, isNegative ); + * // returns true + */ + someOwnBy: typeof someOwnBy; + + /** + * Converts the first letter of each object key to lowercase. + * + * ## Notes + * + * - The function only transforms own properties. Hence, the function does not transform inherited properties. + * - The function shallow copies key values. + * + * @param obj - source object + * @returns new object + * + * @example + * var obj1 = { + * 'AA': 1, + * 'BB': 2 + * }; + * + * var obj2 = ns.uncapitalizeKeys( obj1 ); + * // returns { 'aA': 1, 'bB': 2 } + */ + uncapitalizeKeys: typeof uncapitalizeKeys; + + /** + * Converts each object key to uppercase. + * + * ## Notes + * + * - The function only transforms own properties. Hence, the function does not transform inherited properties. + * - The function shallow copies key values. + * + * @param obj - source object + * @returns new object + * + * @example + * var obj1 = { + * 'a': 1, + * 'b': 2 + * }; + * + * var obj2 = ns.uppercaseKeys( obj1 ); + * // returns { 'A': 1, 'B': 2 } + */ + uppercaseKeys: typeof uppercaseKeys; } /**