useNamingConvention

Este conteúdo não está disponível em sua língua ainda.

Diagnostic Category: lint/style/useNamingConvention

TypeScript and TSX

Since: v1.0.0

Sources:

Inspired from: @typescript-eslint/naming-convention

Enforce naming conventions for everything across a codebase.

Enforcing naming conventions helps to keep the codebase consistent, and reduces overhead when thinking about the name case of a variable.

The following section describes the default conventions enforced by the rule. You can also enforce custom conventions with the rule options.

Naming conventions

All names can be prefixed and suffixed by underscores _ and dollar signs $.

Variable and parameter names

All variables and function parameters are in camelCase or PascalCase. Catch parameters are in camelCase.

Additionally, global variables declared as const or var may be in CONSTANT_CASE. Global variables are declared at module or script level. Variables declared in a TypeScript namespace are also considered global.

function f(param, _unusedParam) {
    let localValue = 0;
    try {
        /* ... */
    } catch (customError) {
        /* ... */
    }
}

export const A_CONSTANT = 5;

let aVariable = 0;

export namespace ns {
    export const ANOTHER_CONSTANT = "";
}

Examples of incorrect names:

let a_value = 0;

code-block.js:1:5 lint/style/useNamingConvention  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This let name should be in camelCase or PascalCase.
  
  > 1 │ let a_value = 0;
      │     ^^^^^^^
    2 │ 
  
  ℹ Safe fix: Rename this symbol in camelCase.
  
    1   │ - let·a_value·=·0;
      1 │ + let·aValue·=·0;
    2 2 │

const fooYPosition = 0;

code-block.js:1:7 lint/style/useNamingConvention ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Two consecutive uppercase characters are not allowed in camelCase because strictCase is set to true.
  
  > 1 │ const fooYPosition = 0;
      │       ^^^^^^^^^^^^
    2 │ 
  
  ℹ If you want to use consecutive uppercase characters in camelCase, then set the strictCase option to false.
    See the rule options for more details.

function f(FIRST_PARAM) {}

code-block.js:1:12 lint/style/useNamingConvention  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This function parameter name should be in camelCase or PascalCase.
  
  > 1 │ function f(FIRST_PARAM) {}
      │            ^^^^^^^^^^^
    2 │ 
  
  ℹ Safe fix: Rename this symbol in camelCase.
  
    1   │ - function·f(FIRST_PARAM)·{}
      1 │ + function·f(firstParam)·{}
    2 2 │

Function names

A function name is in camelCase or PascalCase.
A global function can also be in UPPERCASE. This allows supporting the frameworks that require some function to use valid HTTP method names.

function trimString(s) { /*...*/ }

function Component() {
    return <div></div>;
}

export function GET() { /*...*/ }

TypeScript `enum` names

A TypeScript enum name is in PascalCase.

enum members are by default in PascalCase. However, you can configure the case of enum members. See options for more details.

enum Status {
    Open,
    Close,
}

Classes

A class name is in PascalCase.
Static property and static getter names are in camelCase or CONSTANT_CASE.
Class property and method names are in camelCase.

class Person {
    static MAX_FRIEND_COUNT = 256;

    static get SPECIAL_PERSON_INSTANCE() { /*...*/ }

    initializedProperty = 0;

    specialMethod() {}
}

TypeScript `type` aliases and `interface`

A type alias or an interface name are in PascalCase.
Member names of a type are in camelCase.
readonly property and getter names can also be in CONSTANT_CASE.

type Named = {
    readonly fullName: string;

    specialMethod(): void;
};

interface Named {
    readonly fullName: string;

    specialMethod(): void;
}

interface PersonConstructor {
    readonly MAX_FRIEND_COUNT: number;

    get SPECIAL_PERSON_INSTANCE(): Person;

    new(): Person;
}

Examples of an incorrect type alias:

type person = { fullName: string };

code-block.ts:1:6 lint/style/useNamingConvention  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This type alias name should be in PascalCase.
  
  > 1 │ type person = { fullName: string };
      │      ^^^^^^
    2 │ 
  
  ℹ Safe fix: Rename this symbol in PascalCase.
  
    1   │ - type·person·=·{·fullName:·string·};
      1 │ + type·Person·=·{·fullName:·string·};
    2 2 │

Literal object member names

Literal object members are in camelCase.

const alice = {
    fullName: "Alice",
}

Example of an incorrect name:

const alice = {
    full_name: "Alice",
}

code-block.js:2:5 lint/style/useNamingConvention ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This object property name should be in camelCase.
  
    1 │ const alice = {
  > 2 │     full_name: “Alice”,
      │     ^^^^^^^^^
    3 │ }
    4 │

Import and export aliases and namespaces

Import and export namespaces are in camelCase or PascalCase.

import * as myLib from "my-lib";
import * as Framework from "framework";

export * as myLib from "my-lib";
export * as Framework from "framework";

import and export aliases are in camelCase, PascalCase, or CONSTANT_CASE:

import assert, {
    deepStrictEqual as deepEqual,
    AssertionError as AssertError
} from "node:assert";

Examples of an incorrect name:

import * as MY_LIB from "my-lib";

code-block.ts:1:13 lint/style/useNamingConvention  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This import namespace name should be in camelCase or PascalCase.
  
  > 1 │ import * as MY_LIB from “my-lib”;
      │             ^^^^^^
    2 │ 
  
  ℹ Safe fix: Rename this symbol in camelCase.
  
    1   │ - import·*·as·MY_LIB·from·“my-lib”;
      1 │ + import·*·as·myLib·from·“my-lib”;
    2 2 │

TypeScript type parameter names

A TypeScript type parameter name is in PascalCase.

function id<Val>(value: Val): Val { /* ... */}

TypeScript `namespace` names

A TypeScript namespace name is in camelCase or in PascalCase.

namespace mathExtra {
    /*...*/
}

namespace MathExtra {
    /*...*/
}

Ignored declarations

Note that some declarations are always ignored. You cannot apply a convention to them. This is the case for:

Member names that are not identifiers

class C {
  ["not an identifier"]() {}
}

Named imports

 import { an_IMPORT } from "mod"

Destructured object properties

const { destructed_PROP } = obj;

Class members marked with override:

class C extends B {
  override overridden_METHOD() {}
}

Declarations inside an external TypeScript module

Bug: Declarations inside external TypeScript modules are currently not ignored. This is a bug, and is tracked under #4545.

Until the bug is fixed, we recommend one of the following workarounds:

Move the type declarations for external modules into separate .d.ts files, and use overrides in your biome.json to disable the useNamingConvention rule for those files:

{
  "linter": {
    "rules": {
      "style": {
        "useNamingConvention": "warn"
      }
      // ...
    }
  },
  // ...
  "overrides": [
    {
      "include": ["typings/*.d.ts"],
      "linter": {
        "rules": {
          "style": {
            "useNamingConvention": "off"
          }
        }
      }
    }
  ]
}

Use // biome-ignore lint/style/useNamingConvention: <explanation> to ignore the problematic lines.

declare module "myExternalModule" {
  export interface my_INTERFACE {}
}

Options

The rule provides several options that are detailed in the following subsections.

{
    "options": {
        "strictCase": false,
        "requireAscii": true,
        "enumMemberCase": "CONSTANT_CASE",
        "conventions": [
            {
                "selector": {
                    "kind": "classMember",
                    "modifiers": ["private"]
                },
                "match": "_(.+)",
                "formats": ["camelCase"]
            }
        ]
    }
}

strictCase

When this option is set to true, it forbids consecutive uppercase characters in camelCase and PascalCase.

Default: true

For instance, HTTPServer or aHTTPServer are not permitted for strictCase: true. These names should be renamed to HttpServer and aHttpServer:

{
    "options": {
        "strictCase": true
    }
}

class HTTPServer {
}

When strictCase is set to false, consecutive uppercase characters are allowed. For example, HTTPServer and aHTTPServer would be considered valid then:

{
    "options": {
        "strictCase": false
    }
}

class HTTPServer {
}

requireAscii

When true, names must only consist of ASCII characters only, forbidding names like café or 안녕하세요 that include non-ASCII characters.

When requireAscii is set to false, names may include non-ASCII characters. For example, café and 안녕하세요 would be considered valid then.

Default: false

This option will be turned on by default in Biome 2.0.

enumMemberCase

By default, the rule enforces the naming convention followed by the TypeScript Compiler team: an enum member is in PascalCase.

You can enforce another convention by setting enumMemberCase option. The supported cases are: PascalCase, CONSTANT_CASE, and camelCase.

This option will be deprecated in the future. Use the conventions option instead.

conventions (Since v1.8.0)

The conventions option allows applying custom conventions. The option takes an array of conventions. Every convention is an object that includes an optional selector and one or more requirements (match and formats).

For example, you can enforce the use of CONSTANT_CASE for global const declarations:

{
    "options": {
        "conventions": [
            {
                "selector": {
                    "kind": "const",
                    "scope": "global"
                },
                "formats": ["CONSTANT_CASE"]
            }
        ]
    }
}

A selector describes which declarations the convention applies to. You can select a declaration based on several criteria:

kind: the kind of the declaration among:
- any (default kind if the kind is unset)
- typeLike: classes, enums, type aliases, and interfaces
- class
- enum
- interface
- typeAlias
- function: named function declarations and expressions
- namespaceLike: TypeScript namespaces, import and export namespaces (import * as namespace from)
- namespace: TypeScript namespaces
- importNamespace
- exportNamespace
- importAlias: default imports and aliases of named imports
- exportAlias: aliases of re-exported names
- variable: const, let, using, and var declarations
- const
- let
- var
- using
- functionParameter
- catchParameter
- indexParameter: parameters of index signatures
- typeParameter: generic type parameter
- classMember: class properties, parameter properties, methods, getters, and setters
- classProperty: class properties, including parameter properties
- classMethod
- classGetter
- classSetter
- objectLiteralMember: literal object properties, methods, getters, and setters
- objectLiteralProperty
- objectLiteralMethod
- objectLiteralGetter
- objectLiteralSetter
- typeMember: properties, methods, getters, and setters declared in type aliases and interfaces
- typeProperty
- typeMethod
- typeGetter
- typeSetter
modifiers: an array of modifiers among:
- abstract: applies to class members and classes
- private: applies to class members
- protected: applies to class members
- readonly: applies to class members and type members
- static: applies to class members
scope: where the declaration appears. Allowed values:
- any: anywhere (default value if the scope is unset)
- global: the global scope (also includes the namespace scopes)

For each declaration, the conventions array is traversed until a selector selects the declaration. The requirements of the convention are so verified on the declaration.

A convention must set at least one requirement among:

match: a regular expression that the name of the declaration must match.
formats: the string case that the name must follow. The supported cases are: PascalCase, CONSTANT_CASE, camelCase, and snake_case.

If both match and formats are set, then formats is checked against the first capture of the regular expression. Only the first capture is tested. Other captures are ignored. If nothing is captured, then formats is ignored.

In the following example, we check the following conventions:

A private property starts with _ and consists of at least two characters
The captured name (the name without the leading _) is in camelCase.

{
    "options": {
        "conventions": [
            {
                "selector": {
                    "kind": "classMember",
                    "modifiers": ["private"]
                },
                "match": "_(.+)",
                "formats": ["camelCase"]
            }
        ]
    }
}

If match is set and formats is unset, then the part of the name captured by the regular expression is forwarded to the next conventions of the array. In the following example, we require that private class members start with _ and all class members are in [“camelCase”].

{
    "options": {
        "conventions": [
            {
                "selector": {
                    "kind": "classMember",
                    "modifiers": ["private"]
                },
                "match": "_(.+)"
                // We don't need to specify `formats` because the capture is forwarded to the next conventions.
            },
            {
                "selector": {
                    "kind": "classMember"
                },
                "formats": ["camelCase"]
            }
        ]
    }
}

If a declaration is not selected or if a capture is forwarded while there are no more conventions, then the declaration name is verified against the default conventions. Because the default conventions already ensure that class members are in [“camelCase”], the previous example can be simplified to:

{
    "options": {
        "conventions": [
            {
                "selector": {
                    "kind": "classMember",
                    "modifiers": ["private"]
                },
                "match": "_(.+)"
                // We don't need to specify `formats` because the capture is forwarded to the next conventions.
            }
            // default conventions
        ]
    }
}

If the capture is identical to the initial name (it is not a part of the initial name), then, leading and trailing underscore and dollar signs are trimmed before being checked against default conventions. In the previous example, the capture is a part of the name because _ is not included in the capture.

You can reset all default conventions by adding a convention at the end of the array that accepts anything:

{
    "options": {
        "conventions": [
            // your conventions
            // ...

            // Otherwise, accept anything
            {
                "match": ".*"
            }
        ]
    }
}

Let’s take a more complex example with the following conventions:

Accept variable names i, j, and check all other names against the next conventions.
All identifiers must contain at least two characters.
We require private class members to start with an underscore _.
We require static readonly class properties to be in CONSTANT_CASE. A private static readonly property must also start with an underscore as dictated by the previous convention.
We require global constants to be in CONSTANT_CASE and we allow these constants to be enclosed by double underscores or to be named _SPECIAL_.
We require interfaces to start with I, except for interfaces ending with Error, and to be in PascalCase.
All other names follow the default conventions

{
    "options": {
        "conventions": [
            {
                "selector": {
                    "kind": "variable"
                },
                "match": "[ij]|(.*)"
            },
            {
                "match": "(.{2,})"
            },
            {
                "selector": {
                    "kind": "classMember",
                    "modifiers": ["private"]
                },
                "match": "_(.+)"
            }, {
                "selector": {
                    "kind": "classProperty",
                    "modifiers": ["static", "readonly"]
                },
                "formats": ["CONSTANT_CASE"]
            }, {
                "selector": {
                    "kind": "const",
                    "scope": "global"
                },
                "match": "__(.+)__|_SPECIAL_|(.+)",
                "formats": ["CONSTANT_CASE"]
            }, {
                "selector": {
                    "kind": "interface"
                },
                "match": "I(.*)|(.*?)Error",
                "formats": ["PascalCase"]
            }
            // default conventions
        ]
    }
}

Regular expression syntax

The match option takes a regular expression that supports the following syntaxes:

Greedy quantifiers *, ?, +, {n}, {n,m}, {n,}, {m}
Non-greedy quantifiers *?, ??, +?, {n}?, {n,m}?, {n,}?, {m}?
Any character matcher .
Character classes [a-z], [xyz], [^a-z]
Alternations |
Capturing groups ()
Non-capturing groups (?:)
Case-insensitive groups (?i:) and case-sensitive groups (?-i:)
A limited set of escaped characters including all special characters and regular string escape characters \f, \n, \r, \t, \v