Skip to content

Commit 37bd67d

Browse files
Neerajpathak07Neerajpathak07
committed
feat: add object/any-own-by
Ref: stdlib-js#6756
1 parent a41f30e commit 37bd67d

File tree

9 files changed

+837
-0
lines changed

9 files changed

+837
-0
lines changed

‎lib/node_modules/@stdlib/object/any-own-by/README.md

+221
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2024 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# anyOwnBy
22+
23+
> Test whether at least one own property of a provided object passes a test implemented by a predicate function.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var anyOwnBy = require( '@stdlib/object/any-own-by' );
41+
```
42+
43+
#### anyBy( collection, predicate\[, thisArg ] )
44+
45+
Tests whether at least one own property of a provided [`object`][mdn-object] passes a test implemented by a `predicate` function.
46+
47+
```javascript
48+
function isNegative( value ) {
49+
return ( value < 0 );
50+
}
51+
52+
var obj = {
53+
'a': 1,
54+
'b': 2,
55+
'c': 3,
56+
'd': -24,
57+
'e': 12
58+
};
59+
60+
var bool = anyOwnBy( obj, isNegative );
61+
// returns true
62+
```
63+
64+
If a `predicate` function returns a truthy value, the function **immediately** returns `true`.
65+
66+
```javascript
67+
function isPositive( value ) {
68+
if ( value < 0 ) {
69+
throw new Error( 'should never reach this line' );
70+
}
71+
return ( value > 0 );
72+
}
73+
74+
var obj = {
75+
'a': 1,
76+
'b': 2,
77+
'c': 3,
78+
'd': -24,
79+
'e': 12
80+
};
81+
82+
var bool = anyOwnBy( obj, isPositive );
83+
// returns true
84+
```
85+
86+
The invoked `function` is provided three arguments:
87+
88+
- **value**: property value.
89+
- **key**: property key.
90+
- **obj**: input object.
91+
92+
To set the function execution context, provide a `thisArg`.
93+
94+
```javascript
95+
function verify( value ) {
96+
this.sum += value;
97+
this.count += 1;
98+
return ( value > 0 );
99+
}
100+
101+
var obj = {
102+
'a': -1,
103+
'b': -2,
104+
'c': 3,
105+
'd': -14
106+
};
107+
108+
var context = {
109+
'sum': 0,
110+
'count': 0
111+
};
112+
113+
var bool = anyOwnBy( obj, verify, context );
114+
// returns true
115+
116+
var mean = context.sum / context.count;
117+
// returns 0
118+
```
119+
120+
</section>
121+
122+
<!-- /.usage -->
123+
124+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
125+
126+
<section class="notes">
127+
128+
## Notes
129+
130+
- If provided an empty object, the function returns `false`.
131+
132+
```javascript
133+
function verify() {
134+
return true;
135+
}
136+
var bool = anyOwnBy( {}, verify );
137+
// returns false
138+
```
139+
140+
</section>
141+
142+
<!-- /.notes -->
143+
144+
<!-- Package usage examples. -->
145+
146+
<section class="examples">
147+
148+
## Examples
149+
150+
<!-- eslint no-undef: "error" -->
151+
152+
```javascript
153+
var randu = require( '@stdlib/random/base/randu' );
154+
var anyOwnBy = require( '@stdlib/object/any-own-by' );
155+
156+
function threshold( value ) {
157+
return ( value > 0.94 );
158+
}
159+
160+
var bool;
161+
var obj = {};
162+
var keys = [ 'a', 'b', 'c', 'd', 'e' ];
163+
var i;
164+
for ( i = 0; i < keys.length; i++ ) {
165+
obj[ keys[ i ] ] = randu();
166+
}
167+
168+
bool = anyOwnBy( obj, threshold );
169+
// returns <boolean>
170+
```
171+
172+
</section>
173+
174+
<!-- /.examples -->
175+
176+
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
177+
178+
<section class="references">
179+
180+
</section>
181+
182+
<!-- /.references -->
183+
184+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
185+
186+
<section class="related">
187+
188+
* * *
189+
190+
## See Also
191+
192+
- <span class="package-name">[`@stdlib/utils/any-by`][@stdlib/utils/any-by]</span><span class="delimiter">: </span><span class="description">test whether at least one element in a collection passes a test implemented by a predicate function.</span>
193+
- <span class="package-name">[`@stdlib/utils/any-in-by`][@stdlib/utils/any-in-by]</span><span class="delimiter">: </span><span class="description">test whether at least one property in an object passes a test implemented by a predicate function.</span>
194+
- <span class="package-name">[`@stdlib/utils/every-own-by`][@stdlib/utils/every-own-by]</span><span class="delimiter">: </span><span class="description">test whether all own properties of an object pass a test implemented by a predicate function.</span>
195+
- <span class="package-name">[`@stdlib/utils/some-own-by`][@stdlib/utils/some-own-by]</span><span class="delimiter">: </span><span class="description">test whether some `own` properties of a provided object satisfy a predicate function for at least `n` properties.</span>
196+
197+
</section>
198+
199+
<!-- /.related -->
200+
201+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
202+
203+
<section class="links">
204+
205+
[mdn-object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
206+
207+
<!-- <related-links> -->
208+
209+
[@stdlib/utils/any-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/any-by
210+
211+
[@stdlib/utils/any-in-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/any-in-by
212+
213+
[@stdlib/utils/every-own-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/every-own-by
214+
215+
[@stdlib/utils/some-own-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/some-own-by
216+
217+
<!-- </related-links> -->
218+
219+
</section>
220+
221+
<!-- /.links -->

‎lib/node_modules/@stdlib/object/any-own-by/docs/repl.txt

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
2+
{{alias}}( object, predicate[, thisArg ] )
3+
Tests whether at least one own property of an object passes a
4+
test implemented by a predicate function.
5+
6+
The predicate function is provided three arguments:
7+
8+
- value: property value.
9+
- index: property key.
10+
- object: the input object.
11+
12+
The function immediately returns upon encountering a truthy return
13+
value.
14+
15+
If provided an empty object, the function returns `false`.
16+
17+
Parameters
18+
----------
19+
object: Object
20+
Input object.
21+
22+
predicate: Function
23+
Test function.
24+
25+
thisArg: any (optional)
26+
Execution context.
27+
28+
Returns
29+
-------
30+
bool: boolean
31+
The function returns `true` if the predicate function returns a truthy
32+
value for one own property; otherwise, the function returns `false`.
33+
34+
Examples
35+
--------
36+
> function positive( v ) { return ( v > 0 ); };
37+
> var obj = { 'a': -1, 'b': 2, 'c': -3 };
38+
> var bool = {{alias}}( obj, positive )
39+
true
40+
41+
See Also
42+
--------
43+

‎lib/node_modules/@stdlib/object/any-own-by/docs/types/index.d.ts

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2024 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
// TypeScript Version: 4.1
20+
21+
/// <reference types="@stdlib/types"/>
22+
23+
/**
24+
* Checks whether an own property of the object passes the test.
25+
*
26+
* @returns boolean indicating whether an own property of the object passes the test
27+
*/
28+
type Nullary<U> = ( this: U ) => boolean;
29+
30+
/**
31+
* Checks whether an own property of the object passes the test.
32+
*
33+
* @param value - collection value
34+
* @returns boolean indicating whether an own property of the object passes the test
35+
*/
36+
type Unary<T, U> = ( this: U, value: T ) => boolean;
37+
38+
/**
39+
* Checks whether an own property of the object passes the test.
40+
*
41+
* @param value - property value
42+
* @param key - property key
43+
* @returns boolean indicating whether an own property of the object passes the test
44+
*/
45+
type Binary<T, U> = ( this: U, value: T, key: number ) => boolean;
46+
47+
/**
48+
* Checks whether an own property of the object passes the test.
49+
*
50+
* @param value - property value
51+
* @param key - property key
52+
* @param object - input object
53+
* @returns boolean indicating whether an own property of the object passes the test
54+
*/
55+
type Ternary<T, U> = ( this: U, value: T, key: number, object: Object ) => boolean;
56+
57+
/**
58+
* Checks whether an own property of the object passes the test.
59+
*
60+
* @param value - property value
61+
* @param key - property key
62+
* @param object - input object
63+
* @returns boolean indicating whether an own property of the object passes the tests
64+
*/
65+
type Predicate<T, U> = Nullary<U> | Unary<T, U> | Binary<T, U> | Ternary<T, U>;
66+
67+
/**
68+
* Tests whether any property of an object passes a test implemented by a predicate function.
69+
*
70+
* ## Notes
71+
*
72+
* - The predicate function is provided three arguments:
73+
*
74+
* - `value`: property value
75+
* - `key`: property key
76+
* - `object`: the input object
77+
*
78+
* - The function immediately returns upon encountering a truthy return value.
79+
* - If provided an empty object, the function returns `false`.
80+
*
81+
* @param object - input object
82+
* @param predicate - test function
83+
* @param thisArg - execution context
84+
* @returns boolean indicating whether any own property pass a test
85+
*
86+
* @example
87+
* function isPositive( v ) {
88+
* return ( v > 0 );
89+
* }
90+
*
91+
* var obj = { 'a': -1, 'b': 2, 'c': -3 };
92+
*
93+
* var bool = anyOwnBy( obj, isPositive );
94+
* // returns true
95+
*/
96+
declare function anyOwnBy<T = unknown, U = unknown>( object: Record<string, unknown>, predicate: Predicate<T, U>, thisArg?: ThisParameterType<Predicate<T, U>> ): boolean;
97+
98+
99+
// EXPORTS //
100+
101+
export = anyOwnBy;

0 commit comments

Comments
 (0)