8000 Move `_.tap` to the "Chaining" category, and deprecate `_(…).chain`, … · lodash/lodash@e5555dd · GitHub
[go: up one dir, main page]
Skip to content

Navigation Menu

Sign in

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit e5555dd

Browse files
jdaltonjdalton
committed
Move _.tap to the "Chaining" category, and deprecate _(…).chain, _.isNull, _.isUndefined, _.result, and _.size.
Former-commit-id: 64ee67758b8730fd70cbb28af4230bb336b91214
1 parent ee2d0dd commit e5555dd

File tree

2 files changed

+70
-65
lines changed

2 files changed

+70
-65
lines changed

‎doc/README.md

Lines changed: 30 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ The `lodash` function.
147147
<!-- div -->
148148

149149
### <a id="_version"></a>`_.VERSION`
150-
<a href="#_version">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3361 "View in source") [&#x24C9;][1]
150+
<a href="#_version">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3366 "View in source") [&#x24C9;][1]
151151

152152
*(String)*: The semantic version number.
153153

@@ -270,15 +270,15 @@ jQuery('#lodash_button').on('click', buttonView.onClick);
270270
<!-- div -->
271271

272272
### <a id="_chainvalue"></a>`_.chain(value)`
273-
<a href="#_chainvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3313 "View in source") [&#x24C9;][1]
273+
<a href="#_chainvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3291 "View in source") [&#x24C9;][1]
274274

275-
Wraps the value in a `lodash` chainable object.
275+
Wraps the value in a `lodash` wrapper object.
276276

277277
#### Arguments
278278
1. `value` *(Mixed)*: The value to wrap.
279279

280280
#### Returns
281-
*(Object)*: Returns the `lodash` chainable object.
281+
*(Object)*: Returns the wrapper object.
282282

283283
#### Example
284284
~~~ js
@@ -432,7 +432,7 @@ jQuery(window).on('resize', lazyLayout);
432432
### <a id="_defaultsobject--defaults1-defaults2-"></a>`_.defaults(object [, defaults1, defaults2, ...])`
433433
<a href="#_defaultsobject--defaults1-defaults2-">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2275 "View in source") [&#x24C9;][1]
434434

435-
Assigns missing properties in `object` with default values from the defaults objects. As soon as a property is set, additional defaults of the same property will be ignored.
435+
Assigns missing properties on `object` with default values from the defaults objects. Once a property is set, additional defaults of the same property will be ignored.
436436

437437
#### Arguments
438438
1. `object` *(Object)*: The object to populate.
@@ -533,7 +533,7 @@ _.difference([1, 2, 3, 4, 5], [5, 2, 10]);
533533
<!-- div -->
534534

535535
### <a id="_escapestring"></a>`_.escape(string)`
536-
<a href="#_escapestring">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2999 "View in source") [&#x24C9;][1]
536+
<a href="#_escapestring">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2976 "View in source") [&#x24C9;][1]
537537

538538
Escapes a string for inclusion in HTML, replacing `&`, `<`, `"`, and `'` characters.
539539

@@ -888,7 +888,7 @@ _.has({ 'a': 1, 'b': 2, 'c': 3 }, 'b');
888888
<!-- div -->
889889

890890
### <a id="_identityvalue"></a>`_.identity(value)`
891-
<a href="#_identityvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3018 "View in source") [&#x24C9;][1]
891+
<a href="#_identityvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2995 "View in source") [&#x24C9;][1]
892892

893893
This function returns the first argument passed to it. Note: It is used throughout Lo-Dash as a default callback.
894894

@@ -1296,7 +1296,7 @@ _.isNaN(undefined);
12961296
<!-- div -->
12971297

12981298
### <a F438 id="_isnullvalue"></a>`_.isNull(value)`
1299-
<a href="#_isnullvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2786 "View in source") [&#x24C9;][1]
1299+
<a href="#_isnullvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2787 "View in source") [&#x24C9;][1]
13001300

13011301
Checks if a `value` is `null`.
13021302

@@ -1323,7 +1323,7 @@ _.isNull(undefined);
13231323
<!-- div -->
13241324

13251325
### <a id="_isnumbervalue"></a>`_.isNumber(value)`
1326-
<a href="#_isnumbervalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2803 "View in source") [&#x24C9;][1]
1326+
<a href="#_isnumbervalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2804 "View in source") [&#x24C9;][1]
13271327

13281328
Checks if a `value` is a number.
13291329

@@ -1374,7 +1374,7 @@ _.isObject(1);
13741374
<!-- div -->
13751375

13761376
### <a id="_isregexpvalue"></a>`_.isRegExp(value)`
1377-
<a href="#_isregexpvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2820 "View in source") [&#x24C9;][1]
1377+
<a href="#_isregexpvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2821 "View in source") [&#x24C9;][1]
13781378

13791379
Checks if a `value` is a regular expression.
13801380

@@ -1398,7 +1398,7 @@ _.isRegExp(/moe/);
13981398
<!-- div -->
13991399

14001400
### <a id="_isstringvalue"></a>`_.isString(value)`
1401-
<a href="#_isstringvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2837 "View in source") [&#x24C9;][1]
1401+
<a href="#_isstringvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2838 "View in source") [&#x24C9;][1]
14021402

14031403
Checks if a `value` is a string.
14041404

@@ -1422,7 +1422,7 @@ _.isString('moe');
14221422
<!-- div -->
14231423

14241424
### <a id="_isundefinedvalue"></a>`_.isUndefined(value)`
1425-
<a href="#_isundefinedvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2854 "View in source") [&#x24C9;][1]
1425+
<a href="#_isundefinedvalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2856 "View in source") [&#x24C9;][1]
14261426

14271427
Checks if a `value` is `undefined`.
14281428

@@ -1446,7 +1446,7 @@ _.isUndefined(void 0);
14461446
<!-- div -->
14471447

14481448
### <a id="_keysobject"></a>`_.keys(object)`
1449-
<a href="#_keysobject">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2871 "View in source") [&#x24C9;][1]
1449+
<a href="#_keysobject">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2873 "View in source") [&#x24C9;][1]
14501450

14511451
Produces an array of object`'s own enumerable property names.
14521452
@@ -1638,7 +1638,7 @@ _.min([10, 5, 100, 2, 1000]);
16381638
<!-- div -->
16391639
16401640
### <a id="_mixinobject"></a>`_.mixin(object)`
1641-
<a href="#_mixinobject">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3044 "View in source") [&#x24C9;][1]
1641+
<a href="#_mixinobject">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3021 "View in source") [&#x24C9;][1]
16421642
16431643
Adds functions properties of `object` to the `lodash` function and chainable wrapper.
16441644
@@ -1668,7 +1668,7 @@ _('larry').capitalize();
16681668
<!-- div -->
16691669
16701670
### <a id="_noconflict"></a>`_.noConflict()`
1671-
<a href="#_noconflict">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3075 "View in source") [&#x24C9;][1]
1671+
<a href="#_noconflict">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3052 "View in source") [&#x24C9;][1]
16721672
16731673
Reverts the '_' variable to its previous value and returns a reference to the `lodash` function.
16741674
@@ -1741,7 +1741,7 @@ hi('moe');
17411741
<!-- div -->
17421742
17431743
### <a id="_pickobject--prop1-prop2-"></a>`_.pick(object [, prop1, prop2, ...])`
1744-
<a href="#_pickobject--prop1-prop2-">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2893 "View in source") [&#x24C9;][1]
1744+
<a href="#_pickobject--prop1-prop2-">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2895 "View in source") [&#x24C9;][1]
17451745
17461746
Creates an object composed of the specified properties. Property names may be specified as individual arguments or as arrays of property names.
17471747
@@ -1942,7 +1942,7 @@ _.rest([3, 2, 1]);
19421942
<!-- div -->
19431943
19441944
### <a id="_resultobject-property"></a>`_.result(object, property)`
1945-
<a href="#_resultobject-property">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3106 "View in source") [&#x24C9;][1]
1945+
<a href="#_resultobject-property">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3084 "View in source") [&#x24C9;][1]
19461946
19471947
Resolves the value of `property` on `object`. If `property` is a function it will be invoked and its result returned, else the property value is returned. If `object` is falsey, then `null` is returned.
19481948
@@ -2001,7 +2001,7 @@ _.shuffle([1, 2, 3, 4, 5, 6]);
20012001
<!-- div -->
20022002
20032003
### <a id="_sizevalue"></a>`_.size(value)`
2004-
<a href="#_sizevalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2931 "View in source") [&#x24C9;][1]
2004+
<a href="#_sizevalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2934 "View in source") [&#x24C9;][1]
20052005
20062006
Gets the size of `value` by returning `value.length` if `value` is a string or array, or the number of own enumerable properties if `value` is an object.
20072007
@@ -2130,9 +2130,9 @@ _.sortedIndex(['twenty', 'thirty', 'fourty'], 'thirty-five', function(word) {
21302130
<!-- div -->
21312131
21322132
### <a id="_tapvalue-interceptor"></a>`_.tap(value, interceptor)`
2133-
<a href="#_tapvalue-interceptor">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2959 "View in source") [&#x24C9;][1]
2133+
<a href="#_tapvalue-interceptor">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3318 "View in source") [&#x24C9;][1]
21342134
2135-
Invokes `interceptor` with the `value` as the first argument, and then returns `value`. The primary purpose of this method is to "tap into" a method chain, in order to performoperations on intermediate results within the chain.
2135+
Invokes `interceptor` with the `value` as the first argument, and then returns `value`. The purpose of this method is to "tap into" a method chain, in order to perform operations on intermediate results within the chain.
21362136
21372137
#### Arguments
21382138
1. `value` *(Mixed)*: The value to pass to `callback`.
@@ -2160,7 +2160,7 @@ _.chain([1,2,3,200])
21602160
<!-- div -->
21612161
21622162
### <a id="_templatetext-data-options"></a>`_.template(text, data, options)`
2163-
<a href="#_templatetext-data-options">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3167 "View in source") [&#x24C9;][1]
2163+
<a href="#_templatetext-data-options">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3145 "View in source") [&#x24C9;][1]
21642164
21652165
A micro-templating method, similar to John Resig's implementation. Lo-Dash templating handles arbitrary delimiters, preserves whitespace, and correctly escapes quotes within interpolated code.
21662166
@@ -2244,7 +2244,7 @@ jQuery(window).on('scroll', throttled);
22442244
<!-- div -->
22452245
22462246
### <a id="_timesn-callback--thisarg"></a>`_.times(n, callback [, thisArg])`
2247-
<a href="#_timesn-callback--thisarg">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3256 "View in source") [&#x24C9;][1]
2247+
<a href="#_timesn-callback--thisarg">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3234 "View in source") [&#x24C9;][1]
22482248
22492249
Executes the `callback` function `n` times. The `callback` is bound to `thisArg` and invoked with `1` argument; *(index)*.
22502250
@@ -2354,7 +2354,7 @@ _.uniq([1, 2, 1.5, 3, 2.5], function(num) { return this.floor(num); }, Math);
23542354
<!-- div -->
23552355
23562356
### <a id="_uniqueidprefix"></a>`_.uniqueId([prefix])`
2357-
<a href="#_uniqueidprefix">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3283 "View in source") [&#x24C9;][1]
2357+
<a href="#_uniqueidprefix">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3261 "View in source") [&#x24C9;][1]
23582358
23592359
Generates a unique id. If `prefix` is passed, the id will be appended to it.
23602360
@@ -2378,7 +2378,7 @@ _.uniqueId('contact_');
23782378
<!-- div -->
23792379
23802380
### <a id="_valuesobject"></a>`_.values(object)`
2381-
<a href="#_valuesobject">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2977 "View in source") [&#x24C9;][1]
2381+
<a href="#_valuesobject">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L2954 "View in source") [&#x24C9;][1]
< 10000 div aria-hidden="true" style="left:-2px" class="position-absolute top-0 d-flex user-select-none DiffLineTableCellParts-module__in-progress-comment-indicator--hx3m3">
23822382
23832383
Produces an array of `object`'s own enumerable property values.
23842384
@@ -2488,12 +2488,12 @@ _.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]);
24882488
<!-- div -->
24892489
24902490
### <a id="_prototypechain"></a>`_.prototype.chain()`
2491-
<a href="#_prototypechain">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3331 "View in source") [&#x24C9;][1]
2491+
<a href="#_prototypechain">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3336 "View in source") [&#x24C9;][1]
24922492
2493-
Extracts the value from a wrapped chainable object.
2493+
Enables method chaining on the wrapper object.
24942494
24952495
#### Returns
2496-
*(Mixed)*: Returns the wrapped object.
2496+
*(Mixed)*: Returns the wrapper object.
24972497
24982498
#### Example
24992499
~~~ js
@@ -2509,12 +2509,12 @@ _([1, 2, 3]).value();
25092509
<!-- div -->
25102510
25112511
### <a id="_prototypevalue"></a>`_.prototype.value()`
2512-
<a href="#_prototypevalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3348 "View in source") [&#x24C9;][1]
2512+
<a href="#_prototypevalue">#</a> [&#x24C8;](https://github.com/bestiejs/lodash/blob/v0.3.1/lodash.js#L3353 "View in source") [&#x24C9;][1]
25132513
2514-
Extracts the value from a wrapped chainable object.
2514+
Extracts the wrapped value.
25152515
25162516
#### Returns
2517-
*(Mixed)*: Returns the wrapped object.
2517+
*(Mixed)*: Returns the wrapped value.
25182518
25192519
#### Example
25202520
~~~ js

‎lodash.js

Lines changed: 40 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -2256,9 +2256,9 @@
22562256
}
22572257

22582258
/**
2259-
* Assigns missing properties in `object` with default values from the defaults
2260-
* objects. As soon as a property is set, additional defaults of the same
2261-
* property will be ignored.
2259+
* Assigns missing properties on `object` with default values from the defaults
2260+
* objects. Once a property is set, additional defaults of the same property
2261+
* will be ignored.
22622262
*
22632263
* @static
22642264
* @memberOf _
@@ -2770,6 +2770,7 @@
27702770
/**
27712771
* Checks if a `value` is `null`.
27722772
*
2773+
* @deprecated
27732774
* @static
27742775
* @memberOf _
27752776
* @category Objects
@@ -2841,6 +2842,7 @@
28412842
/**
28422843
* Checks if a `value` is `undefined`.
28432844
*
2845+
* @deprecated
28442846
* @static
28452847
* @memberOf _
28462848
* @category Objects
@@ -2911,6 +2913,7 @@
29112913
* Gets the size of `value` by returning `value.length` if `value` is a string
29122914
* or array, or the number of own enumerable properties if `value` is an object.
29132915
*
2916+
* @deprecated
29142917
* @static
29152918
* @memberOf _
29162919
* @category Objects
@@ -2935,32 +2938,6 @@
29352938
: keys(value).length;
29362939
}
29372940

2938-
/**
2939-
* Invokes `interceptor` with the `value` as the first argument, and then returns
2940-
* `value`. The primary purpose of this method is to "tap into" a method chain,
2941-
* in order to performoperations on intermediate results within the chain.
2942-
*
2943-
* @static
2944-
* @memberOf _
2945-
* @category Objects
2946-
* @param {Mixed} value The value to pass to `callback`.
2947-
* @param {Function} interceptor The function to invoke.
2948-
* @returns {Mixed} Returns `value`.
2949-
* @example
2950-
*
2951-
* _.chain([1,2,3,200])
2952-
* .filter(function(num) { return num % 2 == 0; })
2953-
* .tap(alert)
2954-
* .map(function(num) { return num * num })
2955-
* .value();
2956-
* // => // [2, 200] (alerted)
2957-
* // => [4, 40000]
2958-
*/
2959-
function tap(value, interceptor) {
2960-
interceptor(value);
2961-
return value;
2962-
}
2963-
29642941
/**
29652942
* Produces an array of `object`'s own enumerable property values.
29662943
*
@@ -3082,6 +3059,7 @@
30823059
* it will be invoked and its result returned, else the property value is
30833060
* returned. If `object` is falsey, then `null` is returned.
30843061
*
3062+
* @deprecated
30853063
* @static
30863064
* @memberOf _
30873065
* @category Utilities
@@ -3288,13 +3266,13 @@
32883266
/*--------------------------------------------------------------------------*/
32893267

32903268
/**
3291-
* Wraps the value in a `lodash` chainable object.
3269+
* Wraps the value in a `lodash` wrapper object.
32923270
*
32933271
* @static
32943272
* @memberOf _
32953273
* @category Chaining
32963274
* @param {Mixed} value The value to wrap.
3297-
* @returns {Object} Returns the `lodash` chainable object.
3275+
* @returns {Object} Returns the wrapper object.
32983276
* @example
32993277
*
33003278
* var stooges = [
@@ -3317,12 +3295,39 @@
33173295
}
33183296

33193297
/**
3320-
* Extracts the value from a wrapped chainable object.
3298+
* Invokes `interceptor` with the `value` as the first argument, and then
3299+
* returns `value`. The purpose of this method is to "tap into" a method chain,
3300+
* in order to perform operations on intermediate results within the chain.
3301+
*
3302+
* @static
3303+
* @memberOf _
3304+
* @category Chaining
3305+
* @param {Mixed} value The value to pass to `callback`.
3306+
* @param {Function} interceptor The function to invoke.
3307+
* @returns {Mixed} Returns `value`.
3308+
* @example
3309+
*
3310+
* _.chain([1,2,3,200])
3311+
* .filter(function(num) { return num % 2 == 0; })
3312+
* .tap(alert)
3313+
* .map(function(num) { return num * num })
3314+
* .value();
3315+
* // => // [2, 200] (alerted)
3316+
* // => [4, 40000]
3317+
*/
3318+
function tap(value, interceptor) {
3319+
interceptor(value);
3320+
return value;
3321+
}
3322+
3323+
/**
3324+
* Enables method chaining on the wrapper object.
33213325
*
33223326
* @name chain
3327+
* @deprecated
33233328
* @memberOf _
33243329
* @category Chaining
3325-
* @returns {Mixed} Returns the wrapped object.
3330+
* @returns {Mixed} Returns the wrapper object.
33263331
* @example
33273332
*
33283333
* _([1, 2, 3]).value();
@@ -3334,12 +3339,12 @@
33343339
}
33353340

33363341
/**
3337-
* Extracts the value from a wrapped chainable object.
3342+
* Extracts the wrapped value.
33383343
*
33393344
* @name value
33403345
* @memberOf _
33413346
* @category Chaining
3342-
* @returns {Mixed} Returns the wrapped object.
3347+
* @returns {Mixed} Returns the wrapped value.
33433348
* @example
33443349
*
33453350
* _([1, 2, 3]).value();

0 commit comments

Comments
 (0)
0