Skip to content

Commit f70ed07

Browse files
Planeshifterkgryte
Planeshifter
and
kgryte
authored
build: add lint rule to enforce functions are moved to outermost scopes
PR-URL: #8006 Co-authored-by: Athan Reines <[email protected]> Reviewed-by: Athan Reines <[email protected]>
1 parent fe269e2 commit f70ed07

File tree

12 files changed

+1501
-1
lines changed

12 files changed

+1501
-1
lines changed

‎etc/eslint/overrides/index.js‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,8 @@ var overrides = [
9191
'no-restricted-syntax': restrictedSyntaxConfig,
9292
'require-jsdoc': 'off',
9393
'stdlib/jsdoc-private-annotation': 'off',
94-
'stdlib/jsdoc-doctest': 'off'
94+
'stdlib/jsdoc-doctest': 'off',
95+
'stdlib/no-unnecessary-nested-functions': 'off'
9596
}
9697
},
9798
{
@@ -103,6 +104,7 @@ var overrides = [
103104
'require-jsdoc': 'off',
104105
'stdlib/jsdoc-private-annotation': 'off',
105106
'stdlib/jsdoc-doctest': 'off',
107+
'stdlib/no-unnecessary-nested-functions': 'off',
106108
'stdlib/vars-order': 'off'
107109
}
108110
},
@@ -120,6 +122,7 @@ var overrides = [
120122
'require-jsdoc': 'off',
121123
'stdlib/jsdoc-private-annotation': 'off',
122124
'stdlib/jsdoc-doctest': 'off',
125+
'stdlib/no-unnecessary-nested-functions': 'off',
123126
'no-undefined': 'off'
124127
}
125128
},
@@ -155,6 +158,7 @@ var overrides = [
155158
'require-jsdoc': 'off',
156159
'stdlib/jsdoc-private-annotation': 'off',
157160
'stdlib/jsdoc-return-annotations-values': 'off',
161+
'stdlib/no-unnecessary-nested-functions': 'off',
158162
'stdlib/return-annotations-values': 'off',
159163
'strict': 'off',
160164
'vars-on-top': 'off',

‎etc/eslint/rules/stdlib.js‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4334,6 +4334,45 @@ rules[ 'stdlib/no-dynamic-exports' ] = 'error';
43344334
*/
43354335
rules[ 'stdlib/no-nested-require' ] = 'error';
43364336

4337+
/**
4338+
* Enforce moving inner function declarations to the highest possible scope.
4339+
*
4340+
* @name no-unnecessary-nested-functions
4341+
* @memberof rules
4342+
* @type {string}
4343+
* @default 'error'
4344+
*
4345+
* @example
4346+
* // Bad...
4347+
* function outer() {
4348+
* function inner() {
4349+
* return 42;
4350+
* }
4351+
* return inner();
4352+
* }
4353+
*
4354+
* @example
4355+
* // Good...
4356+
* function inner() {
4357+
* return 42;
4358+
* }
4359+
*
4360+
* function outer() {
4361+
* return inner();
4362+
* }
4363+
*
4364+
* @example
4365+
* // Good (uses outer scope variable)...
4366+
* function outer( x ) {
4367+
* var multiplier = 2;
4368+
* function inner() {
4369+
* return x * multiplier;
4370+
* }
4371+
* return inner();
4372+
* }
4373+
*/
4374+
rules[ 'stdlib/no-unnecessary-nested-functions' ] = 'error';
4375+
43374376
/**
43384377
* Disallow the use of the `new Array()` constructor.
43394378
*

‎lib/node_modules/@stdlib/_tools/eslint/rules/lib/index.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -972,6 +972,15 @@ setReadOnly( rules, 'no-self-require', require( '@stdlib/_tools/eslint/rules/no-
972972
*/
973973
setReadOnly( rules, 'no-unassigned-require', require( '@stdlib/_tools/eslint/rules/no-unassigned-require' ) );
974974

975+
/**
976+
* @name no-unnecessary-nested-functions
977+
* @memberof rules
978+
* @readonly
979+
* @type {Function}
980+
* @see {@link module:@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions}
981+
*/
982+
setReadOnly( rules, 'no-unnecessary-nested-functions', require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' ) );
983+
975984
/**
976985
* @name repl-namespace-order
977986
* @memberof rules

‎lib/node_modules/@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions/README.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 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+
# no-unnecessary-nested-functions
22+
23+
> [ESLint rule][eslint-rules] to prevent unnecessary function nesting when inner functions don't depend on outer scope variables.
24+
25+
<section class="intro">
26+
27+
This rule enforces a best practice to only have functions defined inside of other functions if they need access to variables defined in the outer function scope. Otherwise, functions should always be elevated to the highest level (ideally module scope) to avoid redefining the functions per invocation.
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<section class="usage">
34+
35+
## Usage
36+
37+
```javascript
38+
var rule = require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' );
39+
```
40+
41+
#### rule
42+
43+
[ESLint rule][eslint-rules] to prevent unnecessary function nesting when inner functions don't depend on outer scope variables.
44+
45+
**Bad**:
46+
47+
<!-- eslint-disable stdlib/no-unnecessary-nested-functions -->
48+
49+
```javascript
50+
var PI = require( '@stdlib/constants/float64/pi' );
51+
52+
function outer( x ) {
53+
var result;
54+
55+
function helper() {
56+
return PI; // doesn't use any variables from outer scope...
57+
}
58+
59+
result = x * helper();
60+
return result;
61+
}
62+
```
63+
64+
**Good**:
65+
66+
```javascript
67+
var PI = require( '@stdlib/constants/float64/pi' );
68+
69+
// Helper moved to module scope...
70+
function helper() {
71+
return PI;
72+
}
73+
74+
function outer( x ) {
75+
var result;
76+
result = x * helper();
77+
return result;
78+
}
79+
```
80+
81+
**Good** (function uses outer scope variables):
82+
83+
```javascript
84+
function outer( x ) {
85+
var multiplier = 2;
86+
87+
function helper() {
88+
return x * multiplier; // uses 'multiplier' from outer scope...
89+
}
90+
91+
return helper();
92+
}
93+
```
94+
95+
</section>
96+
97+
<!-- /.usage -->
98+
99+
<section class="notes">
100+
101+
## Notes
102+
103+
- The rule only checks function **declarations**, not function expressions or arrow functions.
104+
- Functions already at module or global scope are ignored.
105+
- Functions that reference variables from outer scopes are not flagged (closures are preserved).
106+
- Functions inside IIFEs (Immediately Invoked Function Expressions) are not flagged, as IIFEs are intentionally used for scope isolation.
107+
108+
</section>
109+
110+
<!-- /.notes -->
111+
112+
<section class="examples">
113+
114+
## Examples
115+
116+
<!-- eslint no-undef: "error" -->
117+
118+
```javascript
119+
var Linter = require( 'eslint' ).Linter;
120+
var rule = require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' );
121+
122+
var linter = new Linter();
123+
124+
// Generate source code containing nested function without dependencies:
125+
var code = [
126+
'function outer() {',
127+
' function inner() {',
128+
' return 42;',
129+
' }',
130+
' return inner();',
131+
'}'
132+
].join( '\n' );
133+
134+
// Define the ESLint configuration:
135+
var config = {
136+
'rules': {
137+
'no-unnecessary-nested-functions': 'error'
138+
}
139+
};
140+
141+
// Register the rule:
142+
linter.defineRule( 'no-unnecessary-nested-functions', rule );
143+
144+
// Lint the code:
145+
var out = linter.verify( code, config );
146+
console.log( out );
147+
/* =>
148+
[
149+
{
150+
'ruleId': 'no-unnecessary-nested-functions',
151+
'severity': 2,
152+
'message': 'Function \'inner\' should be moved to module scope.',
153+
'line': 2,
154+
'column': 3,
155+
'nodeType': 'FunctionDeclaration',
156+
'endLine': 4,
157+
'endColumn': 4
158+
}
159+
]
160+
*/
161+
```
162+
163+
</section>
164+
165+
<!-- /.examples -->
166+
167+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
168+
169+
<section class="related">
170+
171+
</section>
172+
173+
<!-- /.related -->
174+
175+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
176+
177+
<section class="links">
178+
179+
[eslint-rules]: https://eslint.org/docs/developer-guide/working-with-rules
180+
181+
</section>
182+
183+
<!-- /.links -->

‎lib/node_modules/@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions/examples/index.js‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 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+
'use strict';
20+
21+
var Linter = require( 'eslint' ).Linter;
22+
var rule = require( './../lib' );
23+
24+
var linter = new Linter();
25+
26+
// Generate source code containing nested function without dependencies:
27+
var code = [
28+
'function outer() {',
29+
' function inner() {',
30+
' return 42;',
31+
' }',
32+
' return inner();',
33+
'}'
34+
].join( '\n' );
35+
36+
// Define the ESLint configuration:
37+
var config = {
38+
'rules': {
39+
'no-unnecessary-nested-functions': 'error'
40+
}
41+
};
42+
43+
// Register the rule:
44+
linter.defineRule( 'no-unnecessary-nested-functions', rule );
45+
46+
// Lint the code:
47+
var out = linter.verify( code, config );
48+
console.log( out );
49+
/* =>
50+
[
51+
{
52+
'ruleId': 'no-unnecessary-nested-functions',
53+
'severity': 2,
54+
'message': 'Function declaration \'inner\' does not use outer scope variables and should be moved to module scope.',
55+
'line': 2,
56+
'column': 3,
57+
'nodeType': 'FunctionDeclaration',
58+
...
59+
}
60+
]
61+
*/

‎lib/node_modules/@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions/lib/index.js‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 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+
'use strict';
20+
21+
/**
22+
* ESLint rule to prevent unnecessary function nesting when inner functions don't depend on outer scope variables.
23+
*
24+
* @module @stdlib/_tools/eslint/rules/no-unnecessary-nested-functions
25+
*
26+
* @example
27+
* var rule = require( '@stdlib/_tools/eslint/rules/no-unnecessary-nested-functions' );
28+
*
29+
* console.log( rule );
30+
*/
31+
32+
// MODULES //
33+
34+
var main = require( './main.js' );
35+
36+
37+
// EXPORTS //
38+
39+
module.exports = main;

0 commit comments

Comments
 (0)