npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2022 – Pkg Stats / Ryan Hefner

eslint-plugin-functional

v4.2.1

Published

ESLint rules to disable mutation and promote fp in TypeScript.

Downloads

485,233

Readme

eslint-logo

eslint-plugin-functional

npm version CI Coverage Status semantic-release code style: prettier MIT license GitHub Discussions

An ESLint plugin to disable mutation and promote functional programming in JavaScript and TypeScript.

:wave: If you previously used the rules in tslint-immutable, this package is the ESLint version of those rules. Please see the migration guide for how to migrate.

Features

No mutations

One aim of this project is to leverage the type system in TypeScript to enforce immutability at compile-time while still using regular objects and arrays. Additionally, this project will also aim to support disabling mutability for vanilla JavaScript where possible.

No object-orientation

JavaScript is multi-paradigm, allowing both object-oriented and functional programming styles. In order to promote a functional style, the object oriented features of JavaScript need to be disabled.

No statements

In functional programming everything is an expression that produces a value. JavaScript has a lot of syntax that is just statements that does not produce a value. That syntax has to be disabled to promote a functional style.

No exceptions

Functional programming style does not use run-time exceptions. Instead expressions produces values to indicate errors.

Currying

JavaScript functions support syntax that is not compatible with curried functions. To enable currying this syntax has to be disabled.

Stylistic

Enforce code to be written in a more functional style.

Installation

JavaScript

# Install with npm
npm install -D eslint eslint-plugin-functional

# Install with yarn
yarn add -D eslint eslint-plugin-functional

TypeScript

# Install with npm
npm install -D eslint @typescript-eslint/parser tsutils eslint-plugin-functional

# Install with yarn
yarn add -D eslint @typescript-eslint/parser tsutils eslint-plugin-functional

Usage

Add functional to the plugins section of your .eslintrc configuration file. Then configure the rules you want to use under the rules section.

{
  "plugins": ["functional"],
  "rules": {
    "functional/rule-name": "error"
  }
}

There are several rulesets provided by this plugin. See below for what they are and what rules are including in each. Enable rulesets via the "extends" property of your .eslintrc configuration file.

{
  // ...
  "extends": [
    "plugin:functional/external-recommended",
    "plugin:functional/recommended",
    "plugin:functional/stylistic"
  ]
}

With TypeScript

Add @typescript-eslint/parser to the "parser" filed in your .eslintrc configuration file. To use type information, you will need to specify a path to your tsconfig.json file in the "project" property of "parserOptions".

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": "./tsconfig.json"
  }
}

See @typescript-eslint/parser's README.md for more information on the available parser options.

Example Config

{
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": "tsconfig.json"
  },
  "env": {
    "es6": true
  },
  "plugins": [
    "@typescript-eslint",
    "functional"
  ],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/eslint-recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking",
    "plugin:functional/external-recommended",
    "plugin:functional/recommended",
    "plugin:functional/stylistic"
  ]
}

Rulesets

The following rulesets are made available by this plugin:

Presets:

  • Recommended (plugin:functional/recommended)
  • Lite (plugin:functional/lite)
  • Off (plugin:functional/off)

Categorized:

  • No Mutations (plugin:functional/no-mutations)
  • No Object Orientation (plugin:functional/no-object-orientation)
  • No Statements (plugin:functional/no-statements)
  • No Exceptions (plugin:functional/no-exceptions)
  • Currying (plugin:functional/currying)
  • Stylistic (plugin:functional/stylistic)

Other:

  • All (plugin:functional/all) - Enables all rules defined in this plugin.
  • External Recommended (plugin:functional/external-recommended) - Configures recommended rules not defined by this plugin.

The below section gives details on which rules are enabled by each ruleset.

Supported Rules

Key:

| Symbol | Meaning | | :---------------: | -------------------------------------------------------------------------------------------------------------------------------------- | | :hear_no_evil: | Ruleset: LiteThis ruleset is designed to enforce a somewhat functional programming code style. | | :speak_no_evil: | Ruleset: RecommendedThis ruleset is designed to enforce a functional programming code style. | | :wrench: | FixableProblems found by this rule are potentially fixable with the --fix option. | | :thought_balloon: | Only Available for TypeScriptThe rule either requires Type Information or only works with TypeScript syntax. | | :blue_heart: | Works better with TypeScriptType Information will be used if available making the rule work in more cases. |

No Mutations Rules

:see_no_evil: = no-mutations Ruleset.

| Name | Description | :see_no_evil: | :hear_no_evil: | :speak_no_evil: | :wrench: | :blue_heart: | | -------------------------------------------------------------- | -------------------------------------------------------------------------- | :---------------------------------------------: | :--------------------------------------: | :----------------------------------------------: | :------: | :---------------: | | immutable-data | Disallow mutating objects and arrays | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | :blue_heart: | | no-let | Disallow mutable variables | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | | no-method-signature | Enforce property signatures with readonly modifiers over method signatures | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | :thought_balloon: | | prefer-readonly-type | Use readonly types and readonly modifiers where possible | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :wrench: | :thought_balloon: |

No Object-Orientation Rules

:see_no_evil: = no-object-orientation Ruleset.

| Name | Description | :see_no_evil: | :hear_no_evil: | :speak_no_evil: | :wrench: | :blue_heart: | | ---------------------------------------------------------- | ------------------------------------------------------------------------ | :------------------------------------------------------: | :--------------------------------------: | :----------------------------------------------: | :------: | :---------------: | | no-class | Disallow classes | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | | no-mixed-type | Restrict types so that only members of the same kind are allowed in them | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | :thought_balloon: | | no-this-expression | Disallow this access | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | |

No Statements Rules

:see_no_evil: = no-statements Ruleset.

| Name | Description | :see_no_evil: | :hear_no_evil: | :speak_no_evil: | :wrench: | :blue_heart: | | ---------------------------------------------------------------------- | ---------------------------------------------------------- | :----------------------------------------------: | :--------------------------------------: | :----------------------------------------------: | :------: | :---------------: | | no-conditional-statement | Disallow conditional statements (if and switch statements) | :heavy_check_mark: | | :heavy_check_mark: | | :thought_balloon: | | no-expression-statement | Disallow expressions to cause side-effects | :heavy_check_mark: | | :heavy_check_mark: | | :thought_balloon: | | no-loop-statement | Disallow imperative loops | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | | no-return-void | Disallow functions that return nothing | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | :thought_balloon: |

No Exceptions Rules

:see_no_evil: = no-exceptions Ruleset.

| Name | Description | :see_no_evil: | :hear_no_evil: | :speak_no_evil: | :wrench: | :blue_heart: | | ---------------------------------------------------------- | ----------------------------------------------------- | :----------------------------------------------: | :--------------------------------------: | :----------------------------------------------: | :------: | :----------: | | no-promise-reject | Disallow rejecting Promises | | | | | | | no-throw-statement | Disallow throwing exceptions | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | | no-try-statement | Disallow try-catch[-finally] and try-finally patterns | :heavy_check_mark: | | :heavy_check_mark: | | |

Currying Rules

:see_no_evil: = currying Ruleset.

| Name | Description | :see_no_evil: | :hear_no_evil: | :speak_no_evil: | :wrench: | :blue_heart: | | ---------------------------------------------------------------- | ----------------------------------------- | :-----------------------------------------: | :--------------------------------------: | :----------------------------------------------: | :------: | :----------: | | functional-parameters | Functions must have functional parameters | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | |

Stylistic Rules

:see_no_evil: = stylistic Ruleset.

| Name | Description | :see_no_evil: | :hear_no_evil: | :speak_no_evil: | :wrench: | :blue_heart: | | ---------------------------------------------- | ----------------------- | :------------------------------------------: | :--------------------------------------: | :----------------------------------------------: | :------: | :---------------: | | prefer-tacit | Tacit/Point-Free style. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :wrench: | :thought_balloon: |

Recommended standard rules

In addition to the immutability rules above, there are a few standard rules that need to be enabled to achieve immutability.

These rules are all included in the external-recommended rulesets.

no-var

Without this rule, it is still possible to create var variables that are mutable.

no-param-reassign

Without this rule, function parameters are mutable.

prefer-const

This rule is helpful when converting from an imperative code style to a functional one.

@typescript-eslint/prefer-readonly

This rule is helpful when working with classes.

@typescript-eslint/prefer-readonly-parameter-types

Functional functions must not modify any data passed into them. This rule marks mutable parameters as a violation as they prevent readonly versions of that data from being passed in.

However, due to many 3rd-party libraries only providing mutable versions of their types, often it can not be easy to satisfy this rule. Thus by default we only enable this rule with the "warn" severity rather than "error".

@typescript-eslint/switch-exhaustiveness-check

Although our no-conditional-statement rule also performs this check, this rule has a fixer that will implement the unimplemented cases which can be useful.

How to contribute

For new features file an issue. For bugs, file an issue and optionally file a PR with a failing test.

How to develop

To execute the tests run yarn test.

To learn about ESLint plugin development see the relevant section of the ESLint docs. You can also checkout the typescript-eslint repo which has some more information specific to TypeScript.

In order to know which AST nodes are created for a snippet of TypeScript code you can use AST explorer with options JavaScript and @typescript-eslint/parser.

Commit Messages

tl;dr: use npx cz instead of git commit.

Commit messages must follow Conventional Commit messages guidelines. You can use npx cz instead of git commit to run a interactive prompt to generate the commit message. We've customize the prompt specifically for this project. For more information see commitizen.

How to publish

Publishing is handled by semantic release - there shouldn't be any need to publish manually.

Prior work

This project started off as a port of tslint-immutable which was originally inspired by eslint-plugin-immutable.