ESLint Plugin for TypeORM-TypeScript Type Consistency

Common errors

• Plugin 'typeorm-typescript' was referenced but not found.

  cause ESLint could not load the plugin, typically due to incorrect installation or an improper path in the configuration.
  fix Ensure `eslint-plugin-typeorm-typescript` is installed as a dev dependency (`npm install -D eslint-plugin-typeorm-typescript`) and correctly referenced in your `.eslintrc.json` (`"plugins": ["typeorm-typescript"]`) or `eslint.config.mjs` (`typeormTypescriptPlugin` or `typeormTypescriptRecommended`).

• Parsing error: 'import' and 'export' may only appear at the top level

  cause This error often occurs when attempting to use ES Module `import` syntax in a file configured as CommonJS, or in an older Node.js environment without full ESM support.
  fix If using an ESLint flat config file (e.g., `eslint.config.mjs`), ensure your environment (e.g., Node.js 20+) supports ESM. If sticking with CommonJS for legacy `.eslintrc.js` files, use `require()` statements instead of `import`.

• Configuration for rule 'typeorm-typescript/enforce-column-types' is invalid: Value must be an object.

  cause An array was provided for rule options where an object was expected, or the object structure for rule options is incorrect.
  fix When providing options for a rule, ensure they are passed as the second element of an array where the first element is the rule's severity level (e.g., `"error"`). The options themselves should be a valid JavaScript object: `["error", { "driver": "sqlite" }]`.

Warnings

• breaking Version `0.5.3` drops official support for Node.js 18.
  Fix: Upgrade your Node.js environment to version 20 or higher to maintain compatibility and receive updates.
• breaking The parsing logic for `bigint` and `decimal` column types changed in `v0.5.0` to correctly align with database driver behavior.
  Fix: Review TypeORM column definitions and their corresponding TypeScript types for `bigint` and `decimal`. For most drivers, these are now parsed as `string` in TypeScript (e.g., `string` instead of `number` for `bigint`). Adjust your TypeScript types accordingly.
• breaking Version `0.4.0` introduced support for ESLint v9 and flat configuration, along with dual ES Module and CommonJS support. This requires updating your ESLint configuration file.
  Fix: Migrate your ESLint configuration to the new flat config format (e.g., `eslint.config.mjs`). Use `typeormTypescriptRecommended` for a quick setup, or manually configure the plugin as detailed in the 'Flat configuration' section of the README. Ensure your Node.js environment supports ESM if using `import` statements.
• gotcha TypeORM relations are nullable by default, unlike regular columns, which can lead to unexpected type inconsistencies if not explicitly handled.
  Fix: Utilize the `typeorm-typescript/enforce-relation-types` rule. Additionally, consider enabling the `typeorm-typescript/enforce-consistent-nullability` rule (introduced in v0.3.0) with `"specifyNullable": "always"` to enforce explicit nullability declarations for all columns and relations.

Install

• npm install eslint-plugin-typeorm-typescript npm
• yarn add eslint-plugin-typeorm-typescript yarn
• pnpm add eslint-plugin-typeorm-typescript pnpm

Imports

• typeormTypescriptRecommended
  wrong:

  const typeormTypescriptRecommended = require('eslint-plugin-typeorm-typescript/recommended');

  correct:

  import typeormTypescriptRecommended from 'eslint-plugin-typeorm-typescript/recommended';

  This is the recommended export for ESLint flat configuration (ESM). Prior to v0.4.0, CommonJS `require` was the primary method.
• typeormTypescriptPlugin
  wrong:

  const typeormTypescriptPlugin = require('eslint-plugin-typeorm-typescript');

  correct:

  import typeormTypescriptPlugin from 'eslint-plugin-typeorm-typescript';

  Use this import for manual rule configuration within ESLint flat config (ESM). The plugin also supports CommonJS `require` for legacy ESLint configs since v0.4.0.
• Rules Object (Legacy)
  wrong:

  import typeormTypescript from 'eslint-plugin-typeorm-typescript';

  correct:

  { "plugins": ["typeorm-typescript"], "rules": { "typeorm-typescript/enforce-column-types": "error" } }

  For legacy `.eslintrc.json` configurations, the plugin is referenced by its package name string within the `plugins` array, and rules are prefixed with `typeorm-typescript/`.

Quickstart

This quickstart demonstrates setting up `eslint-plugin-typeorm-typescript` with ESLint flat configuration in a TypeScript project, including recommended rules and custom options for specific rules.

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import typeormTypescriptRecommended from 'eslint-plugin-typeorm-typescript/recommended';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  typeormTypescriptRecommended,
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parserOptions: {
        project: './tsconfig.json'
      }
    },
    rules: {
      "typeorm-typescript/enforce-column-types": ["error", { "driver": "postgres" }],
      "typeorm-typescript/enforce-relation-types": "warn",
      "typeorm-typescript/enforce-consistent-nullability": ["error", { "specifyNullable": "always" }]
    }
  }
);