trilonio/eslint-plugin

Official Trilon ESLint Plugin for NestJS

Trilon ESLint Plugin

---

Made with ❤️ by Trilon.io

---

At Trilon, our goal is to help elevate teams - giving them the push they need to continuously succeed in today's ever-changing tech world.

As part of that, we focus on developing tools that make your dev experience easier, enjoyable, and safer.

The official Trilon ESLint Plugin is part of that toolbelt to help your team to thrive, applying best practices for NestJS, curated by our key contributors and core team.

Installation

npm install @trilon/eslint-plugin

And add these the plugin to your .eslintrc:

{
  plugins: ['@trilon/eslint-plugin'],
  extends: ['plugin:@trilon/recommended'],
}

The "recommended" preset contains the rules listed below. If you need custom configuration, please refer to the documentation of the individual linting rules.

Rules

Rule	Description	Type
@trilon/enforce-close-testing-module	Ensures NestJS testing modules are closed properly after tests	Recommended ✅
@trilon/check-inject-decorator	Detects incorrect usage of @Inject(TOKEN) decorator	Recommended ✅
@trilon/detect-circular-reference	Detects usage of forwardRef() method	Recommended ✅
@trilon/enforce-custom-provider-type	Enforces a styleguide for provider types	Strict ⚠️

---

Trilon Consulting

JavaScript, Node, NestJS Consulting from Open-Source Fanatics and Key Contributors!

Check out Trilon.io for more info!

Contact us at [email protected], and let's talk about your projects needs.

Made with ❤️ by Trilon.io

eslint-plugin's Issues

Feat: Enforce custom provider types

Description

We want to allow users to prefer one type of custom provider over the others. For instance, factory providers over value providers can significantly increase performance.

Acceptance Criteria

Given the options below:

// ...
rules: {
  '@trilon/enforce-custom-provider-type': [ 
   'warn', {  
     prefer: 'factory'
   }
  ]
}

Then, the following code will be considered Invalid:

const customValueProvider: Provider = {
  provide: 'TOKEN',
  useValue: 'some-value' // ⚠️ provider is not of type "factory"
}

const customClassProvider: Provider = {
  provide: AbstractClass,
  useClass: SomeClass  // ⚠️ provider is not of type "factory"
}

And the following code is considered Valid:

const factoryProvider: Provider = {
  provide: 'TOKEN',
  useFactory: () => 'some-value'
}

Configure GitHub actions to run tests before a PR is merged

Description

We must configure GitHub actions to ensure PR's don't break any existing test or lining rules. The requirements are:

• It must run the unit tests
• It must run eslint in the project and ensure there are no warnings or errors

Feat: Add custom method name to enforce-close-testing-module

Description

The enforce-close-testing-module rule doesn't support custom method names that could replace the testingModule.close() and Test.createTestingModule() calls. We need to add that option so users can create utility methods that are proxies for those calls.

Acceptance Criteria

The user can define an option with the enforce-close-testing-module rule so that ESLint recognizes custom functions:

// ...
rules: {
  '@trilon/enforce-close-testing-module': [ 
   'warn', {  
     closeAliases: [ 
       { kind: 'function', name: 'close' } 
     ],
     createAliases: [ 
       { kind: 'function', name: 'setupTest' } 
     ]  
   }
  ]
}

The configuration above defines:

• close() as a custom function that should be interpreted the same as testingModule.close()
• setupTest() as a custom function that should be interpreted the same as Test.createTestingModule()

Feat: warn about usage of `forwardRef`

Description

Circular dependencies are a clear sign of code that should be refactored because e.g. a class has grown too big or separation of concerns is violated.

Acceptance Criteria

Invalid code:

import { forwardRef } from '@nestjs/common';

@Injectable()
export class CatsService {
  constructor(
    @Inject(forwardRef(() => CommonService)) // ⚠️ Circular-dependency detected
    private commonService: CommonService,
  ) {}
}


@Module({
  imports: [forwardRef(() => CatsModule)], // ⚠️ Circular-dependency detected
})
export class CommonModule {}

Would we also be able to detect this attempt to dodge detection? 🤔

import { forwardRef as silentForwardRef } from '@nestjs/common';

Feat: Create custom ESLint Rule to avoid lingering modules

Description

We need a Rule that enforces closing a TestingModule. When we create a module in tests and don't close it we potentially leak memory and/or database connections.

Acceptance Criteria

The ESLint rule should warn when:

• A Test.createTestingModule() is executed in the beforeEach() hook, but then the module isn’t closed in the afterEach()
• A Test.createTestingModule() is executed in the beforeAll() hook, but isn’t closed in the afterAll() one.
• A Test.createTestingModule() is executed within a test, or it block, but isn't closed.

The ESLint rule should consider valid:

• When a Test.createTestingModule() is executed in the beforeEach() and the module is then closed in the afterEach() hook
• When a Test.createTestingModule() is executed in the beforeAll() and the module is then closed in the afterAll() hook
• When a Test.createTestingModule() is executed, followed by a module.createNestApp(), and then the application is closed in the correct hook

Feat: Add lint rule to enforce modules to have `register/registerAsync` and/or `forRoot/forRootAsync`

Description

We should detect whether module classes that return a DynamicModule are named register, registerAsync, forRoot or forRootAsync.

Acceptance Criteria

Incorrect:

@Module({})
export class ProductsModule {
  static create(options): DynamicModule { // ⚠️ `Dynamic module methods must be named `register/registerAsync` or `forRoot/forRootAsync`
    return {
      module: ProductsModule,
      imports: [TypeOrmModule.forFeature([Product]),
      providers: [/* ... */],
    }
  }

  static registerAsync(options): DynamicModule { // ✅ 
    return {
      module: ProductsModule,
      imports: [TypeOrmModule.forFeature([Product]),
      providers: [/* ... */],
    }
  }
}

Correct:

@Module({})
export class ProductsModule {
  static register(options): DynamicModule { // ✅ 
    return {
      module: ProductsModule,
      imports: [TypeOrmModule.forFeature([Product]),
      providers: [/* ... */],
    }
  }

  static registerAsync(options): DynamicModule { // ✅ 
    return {
      module: ProductsModule,
      imports: [TypeOrmModule.forFeature([Product]),
      providers: [/* ... */],
    }
  }
}

Define bundler tool

Description

We should define which bundler tool we want to use to publish this package. A few things to take into consideration:

• How do we configure that bundler to map the tsconfig.paths so we can use path aliases?
• Is it possible to bundle/compile our code for both CJS and ESM? (Example: pkgroll)

Acceptance Criteria

A bundler and its configuration are created so that the requirements above are answered/met.

ESLint couldn't find the plugin "@trilon/eslint-plugin".

ESLint: 8.56.0

ESLint couldn't find the plugin "@trilon/eslint-plugin".

(The package "@trilon/eslint-plugin" was not found when loaded as a Node module from the directory "/Users/igormakowski/Documents/repositories/rigtch/rigtch-music-api".)

It's likely that the plugin isn't installed correctly. Try reinstalling by running the following:

    npm install @trilon/eslint-plugin@latest --save-dev

The plugin "@trilon/eslint-plugin" was referenced from the config file in ".eslintrc.cjs".

If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.

.eslintrc.cjs

{
  plugins: [
    '@typescript-eslint',
    '@trilon/eslint-plugin',
    'import',
    'nestjs',
    'eslint-plugin-import-helpers',
    'prettier',
  ],
  extends: [
    'plugin:@typescript-eslint/strict-type-checked',
    'plugin:@typescript-eslint/stylistic-type-checked',
    'plugin:@trilon/recommended',
    'plugin:sonarjs/recommended',
    'plugin:unicorn/recommended',
    'plugin:nestjs/recommended',
    'plugin:eslint-comments/recommended',
    'prettier',
  ],
}

package.json

{
  "devDependencies": {
    "@trilon/eslint-plugin": "^0.2.0",
  }
}

Protect Main Branch and configure pipeline

Description

We must protect the main branch and ensure PRs run a basic CI Pipeline (required) before merging.

Create documentation for encorce-close-testing-module

Description

We need to create the documentation for our first rule #1. It has to present the valid and invalid codes, along with any additional options.

Acceptance Criteria

A public page / link describing the rule following the template below:

---
description: '<Description from rule metadata here>'
---

> 🛑 This file is source code, not the primary documentation location! 🛑
>
> See **https://typescript-eslint.io/rules/RULE_NAME_REPLACEME** for documentation.

## Examples

To fill out: tell us more about this rule.

<!--tabs-->

### ❌ Incorrect

```ts
// To fill out: incorrect code

✅ Correct

// To fill out: correct code

When Not To Use It

To fill out: why wouldn't you want to use this rule?
For example if this rule requires a feature released in a certain TS version.

Docs: Fix Trilon Icon for dark mode

When browsing github in Dark Mode, Trilon's logo gets obscured:

We need to fix the bg-color to be visible.

Feat: how to install this plugin?

how to install this plugin?

Feat: create styleguide rule for providers

Description

Large teams can have the desire to limit or enforce a particular style of creating providers; e.g. banning request-scoped providers.

Acceptance Criteria

tbd needs more refinement

Create rule for correct usage of @Inject

Description

We should create a rule for code that detects incorrect usage of @Inject(TOKEN)

Acceptance criteria

The following code would be considered invalid:

class FooBarController {
	private readonly fooService: FooService; // ⚠️ Did you want to `@Inject(FooService)`?

	constructor(
		// 🚫 Type is an interface and cannot be injected
		private readonly barService: IService<Bar>,

		@Inject(BazService) // ⚠️ Token duplicates type
		private readonly bazService: BazService,
	) {}
}

The following code would be considered valid:

class FooBarController {
	@Inject(FooService) // ✅ Token duplicates type, but class properties don't have type metadata
	private readonly fooService: FooService;

	constructor(
		@Inject('BAR_SERVICE') // ✅ Token differs from type
		private readonly barService: IService<Bar>,

		// ✅ Type metadata is sufficient to inject
		private readonly bazService: BazService,
	) {}
}

Feat: Add lint rule to enforce module naming

Description

A rule to ensure that any class decorated with @Module() should have their class name end with Module.

Acceptance criteria

Incorrect:

@Module({
  imports: [TypeOrmModule.forFeature([Product]),
})
export class Products {} // ⚠️ `Module classes should have a name that ends with the word `Module`

Correct:

@Module({
  imports: [TypeOrmModule.forFeature([Product]),
})
export class ProductsModule {}

Wrong docs link in vscode error message

Refactor: Create a matcher utility to facilitate rule creation

Description

Manipulating and querying ASTs is inherently a complex problem. Often, we need to perform consecutive checks for children's properties, including their type and value. This leads to repetitive, not-so-readable code. Here's an example of such code:

if (ASTUtils.isVariableDeclarator(parent)) {
    const init = parent.init;
    let type: ProviderType | undefined;
    if (init?.type === AST_NODE_TYPES.ObjectExpression) {
      const properties = init.properties;
      for (const property of properties) {
        if (property.type === AST_NODE_TYPES.Property) {
          type = providerTypeOfProperty(property);
        }
      }
    }

    return type;
  }

And here's how this could be replaced with TS-Pattern

  return match(node)
    .with(
      {
        parent: {
          init: {
            type: AST_NODE_TYPES.ObjectExpression,
            properties: P.select(),
          },
          type: P.when(ASTUtils.isVariableDeclarator),
        },
      },
      (properties) => {
        for (const property of properties) {
          if (property.type === AST_NODE_TYPES.Property) {
            const type = providerTypeOfProperty(property);
            if (type) {
              return type;
            }
          }
        }
      }
    )
    .otherwise(() => undefined);

This second approach is more declarative and makes it easier to grasp the expected node structure. Moreover, we can select parts of the matched node with the P.select() function and make use of it in the following callback function.

Acceptance Criteria

Initially, it would suffice to implement a match(node) function that accepts two additional methods:

with(structure, callback | value) - matches with given object structure, and returns either the value or the callback's returned value
when(function, callback | value) - matches with the given matching function, and returns either the value or the callback's returned value