eslint-plugin-constructors 1.0.0

package/README.md

@@ -0,0 +1,148 @@
+# eslint-plugin-constructors
+
+[![](https://img.shields.io/npm/v/eslint-plugin-constructors?style=for-the-badge&label=Latest%20Build)](https://www.npmjs.com/package/eslint-plugin-constructors)
+[![](https://img.shields.io/badge/Requires-ESLint_%3E%3D9.0.0-4B32C3?style=for-the-badge&logo=eslint)](https://eslint.org/)
+
+ESLint plugin to enforce best practices for constructor usage.
+
+## Installation
+
+```bash
+npm i -D eslint-plugin-constructors
+```
+
+## Usage
+
+Add `constructors` to your flat config:
+
+```js
+import constructors from 'eslint-plugin-constructors'
+
+export default [
+	{
+		files: ['**/*.js'],
+		plugins: { constructors },
+		rules: {
+			'constructors/no-explicit-return': 'error',
+			'constructors/require-error-subclass-name': 'error',
+			'constructors/require-new': 'error'
+		}
+	}
+]
+```
+
+Or use the bundled recommended config:
+
+```js
+import constructors from 'eslint-plugin-constructors'
+
+export default [
+	{
+		files: ['**/*.js'],
+		...constructors.configs.recommended
+	}
+];
+```
+
+## Rules
+
+The plugin has 3 rules.
+
+### `require-new`
+
+Requires `new` when calling error constructors (and optionally other built‑in constructors).
+
+#### Options
+
+- `"error-only"` (default) – only error constructors (`Error`, `TypeError`, `RangeError`, `SyntaxError`, `ReferenceError`, `URIError`, `EvalError`, `AggregateError`)
+- `"builtins"` – also includes `Array`, `Boolean`, `Date`, `Function`, `Number`, `Object`, `RegExp`, `String`, `Symbol`, `BigInt`, `Map`, `Set`, `WeakMap`, `WeakSet`
+
+#### Example incorrect code
+
+```js
+throw Error('boom')
+throw TypeError('bad')
+
+// w/ builtins:
+const arr = Array(),
+      m = Map()
+```
+
+#### Example correct code
+
+```js
+throw new Error('boom')
+throw new TypeError('bad')
+
+// w/ builtins:
+const arr = new Array(),
+      m = new Map()
+```
+
+#### When Not To Use It
+
+If you prefer the convenience of calling built‑ins without `new` (which is allowed by the spec).
+
+---
+
+### `require-error-subclass-name`
+
+Requires classes extending `Error` have a name ending in `Error`.
+
+#### Example incorrect Code
+
+```js
+class My extends Error {}
+const Custom = class extends Error {}
+```
+
+#### Example correct Code
+
+```js
+class MyError extends Error {}
+const CustomError = class extends Error {}
+```
+
+#### When Not To Use It
+
+If you don't follow the common convention of suffixing custom error classes w/ `Error`.
+
+---
+
+### `no-explicit-return`
+
+Disallows explicit `return` statements inside class constructors.
+
+#### Incorrect Code
+
+```js
+class A {
+	constructor() {
+		return
+	}
+}
+
+class B {
+	constructor() {
+		return this
+	}
+}
+```
+
+#### Correct Code
+
+```js
+class A {
+	constructor() {
+		this.x = 1
+	}
+}
+```
+
+#### When Not To Use It
+
+If you need to return a different object from a constructor (a rare but valid pattern).
+
+## License
+
+Copyright © 2026 [Adam Lui](https://codeberg.org/adamlui).

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "eslint-plugin-constructors",
+  "version": "1.0.0",
+  "description": "ESLint rules for constructor usage",
+  "type": "module",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "author": {
+    "name": "Adam Lui",
+    "email": "adam@kudoai.org",
+    "url": "https://codeberg.org/adamlui"
+  },
+  "homepage": "https://codeberg.org/adamlui/eslint-plugin-constructors/#readme",
+  "license": "MIT",
+  "main": "src/index.js",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "prepare": "husky",
+    "lint": "eslint . --cache",
+    "lint:all": "eslint .",
+    "lint:fix": "eslint . --fix --cache",
+    "lint:fix-all": "eslint . --fix",
+    "test": "node tests/run.js",
+    "demo": "eslint --config demo/eslint.config.js demo/buggy-script.js"
+  },
+  "keywords": [
+    "code-quality",
+    "constructor",
+    "error",
+    "eslint",
+    "eslint-plugin",
+    "eslintplugin",
+    "security"
+  ],
+  "devDependencies": {
+    "@e18e/eslint-plugin": "^0.8.0",
+    "@eslint/js": "^10.0.1",
+    "@eslint/json": "^2.1.0",
+    "@eslint/markdown": "^8.0.3",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "eslint": "^10.10.0",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-no-secrets": "^2.3.3",
+    "eslint-plugin-no-unsanitized": "^4.1.5",
+    "eslint-plugin-promise": "^7.3.0",
+    "eslint-plugin-regexp": "^3.3.0",
+    "globals": "^17.12.0",
+    "husky": "^9.1.7"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,26 @@
+import requireNew from './rules/require-new.js'
+import requireErrorSubclassName from './rules/require-error-subclass-name.js'
+import noExplicitReturn from './rules/no-explicit-return.js'
+
+const plugin = {
+    rules: {
+        'require-new': requireNew,
+        'require-error-subclass-name': requireErrorSubclassName,
+        'no-explicit-return': noExplicitReturn
+    }
+}
+
+plugin.configs = {
+    recommended: [
+        {
+            plugins: { constructors: plugin },
+            rules: {
+                'constructors/require-new': 'error',
+                'constructors/require-error-subclass-name': 'error',
+                'constructors/no-explicit-return': 'error'
+            }
+        }
+    ]
+}
+
+export default plugin

package/src/rules/no-explicit-return.js

@@ -0,0 +1,37 @@
+const reFuncNodeType = /^(?:Arrow)?Function(?:Declaration|Expression)$/
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow explicit return statements in class constructors',
+            category: 'Best Practices',
+            recommended: true
+        },
+        schema: [],
+        messages: { unexpectedReturn: 'Unexpected return statement in constructor' }
+    },
+
+    create(context) {
+        function isInsideConstructorFunc(node) {
+            let current = node.parent
+            while (current) {
+                if (reFuncNodeType.test(current.type))
+                    return ( // whether this func is constructor's val
+                            current.parent?.type == 'MethodDefinition'
+                         && current.parent.kind == 'constructor'
+                         && !current.parent.static
+                    )
+                current = current.parent
+            }
+            return false
+        }
+
+        return {
+            ReturnStatement(node) {
+                if (isInsideConstructorFunc(node))
+                    context.report({ node, messageId: 'unexpectedReturn' })
+            }
+        }
+    }
+}

package/src/rules/require-error-subclass-name.js

@@ -0,0 +1,39 @@
+export default {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require that classes extending Error have names ending in "Error"',
+            category: 'Best Practices',
+            recommended: true
+        },
+        schema: [],
+        messages: { endWithError: 'Class extending Error must have a name ending in "Error"' }
+    },
+
+    create(context) {
+        function checkName(name, node) {
+            if (!name || name.endsWith('Error')) return
+            context.report({ node, messageId: 'endWithError' })
+        }
+
+        function checkClassNode(node) {
+            if (!node.id || !node.superClass?.name?.endsWith('Error')) return
+            checkName(node.id.name, node.id)
+        }
+
+        function checkVariableDeclarator(node) {
+            const classExpr = node.init
+            if (classExpr?.type != 'ClassExpression'
+                || !classExpr.superClass?.name?.endsWith('Error')
+                || classExpr.id // named class expression, already checked
+            ) return
+            checkName(node.id.name, node.id)
+        }
+
+        return {
+            ClassDeclaration: checkClassNode,
+            ClassExpression: checkClassNode,
+            VariableDeclarator: checkVariableDeclarator
+        }
+    }
+}

package/src/rules/require-new.js

@@ -0,0 +1,49 @@
+const ERR_CONSTRUCTORS = new Set([
+    'Error',
+    'TypeError',
+    'RangeError',
+    'SyntaxError',
+    'ReferenceError',
+    'URIError',
+    'EvalError',
+    'AggregateError'
+])
+
+const BUILTIN_CONSTRUCTORS = new Set([
+    'Array', 'Boolean', 'Date', 'Function', 'Number', 'Object',
+    'RegExp', 'String', 'Symbol', 'BigInt', 'Map', 'Set',
+    'WeakMap', 'WeakSet'
+])
+
+function isErrConstructor(name) { return ERR_CONSTRUCTORS.has(name) }
+
+export default {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require `new` when calling constructor functions',
+            category: 'Best Practices',
+            recommended: true
+        },
+        fixable: 'code',
+        schema: [{ enum: ['error-only', 'builtins'] }],
+        messages: { requireNew: 'Use `new {{name}}()` instead of `{{name}}()`' }
+    },
+
+    create(context) {
+        const mode = context.options[0] || 'error-only'
+        return {
+            CallExpression(node) {
+                if (node.new) return
+                const calleeName = node.callee.name ; if (!calleeName) return
+                const shouldReport = mode == 'error-only' ? isErrConstructor(calleeName)
+                                   : isErrConstructor(calleeName) || BUILTIN_CONSTRUCTORS.has(calleeName)
+                if (shouldReport)
+                    context.report({
+                        node, messageId: 'requireNew', data: { name: calleeName },
+                        fix(fixer) { return fixer.insertTextBefore(node, 'new ') }
+                    })
+            }
+        }
+    }
+}