Skip to content

Latest commit

 

History

History
235 lines (145 loc) · 13.7 KB

README.md

File metadata and controls

235 lines (145 loc) · 13.7 KB
Raw

eslint-plugin-func-params-args

Limit the number of function parameters and arguments with ease and flexibility!

This plugin intends to give you control over how many parameters are used in function definitions (declarations), function expressions, arrow function expressions, and TypeScript function type annotations. In addition to this, you can also set limits on how many arguments can be used when calling functions, where you can set a global limit, and have even finer control by providing limits for specific function calls (set by configuring/providing the name of a function).

Travis (.com) branch Coveralls github branch Depfu

Table of contents

Why

This plugin has two rules, one for parameters (when defining functions or expressions), and one for arguments when calling functions (including built-in or 3rd party functions). Why each?

  • Function Parameters: ESLint has its own max-params rule, but it only provides one global setting, and that's not flexible enough. Let's say we need to call array.reduce, where sometimes there is a need to use all of the 4 arguments provided to the reducer callback in an arrow function expression (like array.reduce((acc, val, index, arr) => {}, {}) for example). Using the built-in max-params, we would need to set it to 4 and that would be the global limit. This plugin's rule (func-params) allows for more flexibility when handling such cases. One approach would be to set the global setting for (func-params) to 3, and override this value to allow arrow function expressions to have 4 parameters instead of 3

  • Function Arguments: The role of the first rule ends when defining functions or expressions, but what about calling functions, especially 3rd party or built-in functions? Let's take migrating from Vue v2 to v3 as an example. Vue v3 recommends using a library called mitt as an event bus implementation. Vue v2's own implementation allows more than 2 arguments to be used (passed in) when emitting events ($emit), however, mitt's implementation only accepts 2 arguments. So, to help with doing such migration, we can use this plugin's rule (func-args) to allow only 2 arguments to be used whenever $emit is called. Of course this is only an example, and this rule is flexible to cover any user-configured named function calls - that's in addition to a global limit as well

Installation

If you don't already have ESLint installed, you'll first need to install it:

npm install eslint --save-dev

# or yarn add eslint --dev

Next, install eslint-plugin-func-params-args:

npm install eslint-plugin-func-params-args --save-dev

# or yarn add eslint-plugin-func-params-args --dev

General usage notes

Add func-params-args to the plugins section of your .eslintrc.json configuration file. You can omit the eslint-plugin- prefix:

{
  "plugins": ["func-params-args"]
}

Or .eslintrc.yml

plugins:
  - func-params-args

Then configure the rules you want to use under the rules section.

(json)

{
  "rules": {
    "func-params-args/func-args": [
      "warn",
      {
        "global": 3,
        "$emit": 2
      }
    ]
  }
}

Or (yml)

rules:
  func-params-args/func-args:
    - 'warn'
    - 'global': 3
      '$emit': 2

As shown in the example above, the configuration approach for this plugin's rules uses a simple object structure (no arrays or nested objects), where keys like $emit are the options, and the value of a given key is the limit (like 2). So, in the example above, it means that any calls to $emit function should have no more than 2 arguments, and the global limit for any other function call is 3.

No defaults

By design, this plugin's rules don't have pre-set defaults. So, you've to configure them as shown in the example above and as explained in details in the docs of each rule (Available rules).

Non-JavaScript files

ESLint's eco-system is full of parsers and plugins taking care of non-JavaScript files, like TypeScript and JSX for example. This plugin doesn't provide its own parser (nor does it have a custom AST parsing logic). So, handling non-JS files depends on your existing ESLint setup.

As an example, to use this plugin in TS files, you may configure parsing options in your .eslintrc file as follows:

If you don't have any existing parsers (or other plugins that are already taking care of handling TS files)

"parser": "@typescript-eslint/parser"

Or you may override only the parsing of TS files if you've other parsers or plugins that are doing their own parsing

"overrides": [
  {
    "files": "*.ts",
    "parser": "@typescript-eslint/parser"
  }
]

In both examples above, you would need to install @typescript-eslint/parser from npm.

Available rules

What is next

In general, all feedback is welcome, and I would love to get more ideas and contributions to make this project better. As of now, here are a few items I can think of:

  • Instead of only setting a value as an upper limit when configuring a rule, let's say 3 parameters or arguments max, would setting a min limit as well be a useful addition? Maybe for some function calls you want to allow between 1-3 arguments, but not without any arguments and not with more than 3

  • Add more examples on how to handle non-JS files, like .vue files for instance

  • Currently, in func-params rule, when there is an error reported, in addition to the code location (file and line number), an error message like function has too many parameters (3). Maximum allowed is (2). is reported. An improvement would be to report the name of the function (or the variable name in the case of a function expression) in the message instead of the generic function. For example, a message like function has too many parameters... could be handleSubmit has too many parameters... instead Added in v3

  • Consider adding options for pattern matching. Maybe as a start, support startsWith and endsWith options. Could be useful if you use or have Node-style function names that end with a specific pattern like [whatever]Sync or [whatever]Async

  • Adopt the all-contributors specification for recognizing contributors

Contributing

If you want to report a bug, request a feature, or ask questions, please feel free to open a new issue.

All contributions are welcome and appreciated. If you want to help out, please follow the guidelines outlined below. The objective is to ensure that your time and effort are will spent, and to avoid a situation where you might spend time on something that someone else is already working on. Contributors time is valuable, and I hope these guidelines ensure that we can make the best out of it 🙏

General guidelines

Documentation notes

  • You may sometimes find open issues related to documentation. Such issues will have documentation label

  • For minor documentation updates or fixing typos, it is usually fine to do so directly on GitHub website. For large documentation updates, it is recommended to clone the repo and ensure that the project dependencies are installed (by running npm install or yarn). This is because Prettier is used to ensure consistent style/formatting in the docs (all .md files), and having the dependencies installed will automatically fix style/formatting issues upon committing

Development guidelines

  • If you are new to ESLint plugin development, the resources in Inspiration and credits should help you get started

  • Check open issues to see if an existing one is already addressing what you want to contribute/help with, or if there is one that is interesting for you to work on. If you want to work on (grab) an existing issue, please ensure that it has the label up for grabs, and comment on it to signal your interest. I will then assign the issue to you and add the assigned label to it (will remove up for grabs as well). Here is a link to open issues that are up for grabs

  • If you don't find an existing issue addressing what you want to contribute/help with, create a new issue and include a short description

  • If the changes you are working on require documentation updates, please update the docs accordingly

  • When you are ready to open a PR (all pull requests should be opened against master branch):

    • Add a summary explaining your changes

    • Add Fixes #[issue number] or Closes #[issue number] in the PR description

  • Here is a nice article about code reviews that I found helpful. Knew about it from Automattic's Calypso contributing guide

Development notes

  • Please run npm install or yarn to ensure that the required dev dependencies are properly installed

  • The target for test coverage is 100%. If not met, a PR will fail on CI (Travis Continuous Integration). You can run npm run test locally as well

  • The project uses Prettier for code formatting and style, and there is a pre-commit hook that auto-fixes any code style issues. This is also checked and will fail on CI if there are issues reported by Prettier

Code of conduct

This project adopts Contributor Covenant's Code of Conduct. You can read it in full here, which has my email address included.

Inspiration and credits

This work wouldn't have been possible without the power of open source and people who share their knowledge and experiences. Following are some sources of inspiration and references that helped me while creating this plugin/project.