eslint-plugin-constructors 1.1.0 → 1.2.0

package/README.md

@@ -10,6 +10,8 @@ ESLint rules to enforce best practices for constructor usage.
 
 <img src="https://cdn.staticdelivr.com/gl/adamlui/eslint-plugin-constructors/6eeba7b2cb/assets/images/screenshots/vs-code/squiggles.png">
 
+---
+
 ## Installation
 
 From your project root:
@@ -18,6 +20,8 @@ From your project root:
 npm i -D eslint-plugin-constructors
 ```
 
+---
+
 ## Usage
 
 Add `constructors` to your flat config:
@@ -32,7 +36,7 @@ export default [
         rules: {
             'constructors/no-explicit-return': 'error',
             'constructors/require-error-subclass-name': 'error',
-            'constructors/require-new': ['error', 'error-only']
+            'constructors/require-new': ['error', 'errors']
         }
     }
 ]
@@ -53,19 +57,19 @@ export default [
 ]
 ```
 
+---
+
 ## Supported rules
 
-<!-- eslint-disable markdown/no-missing-link-fragments -->
 | ID | Description | Auto-fixable | Recommended |
 | --- | --- | :-: | :-: |
 | [`no-explicit-return`](#no-explicit-return) | Disallows explicit `return` statements in class constructors | ❌ | ✅ |
 | [`require-error-subclass-name`](#require-error-subclass-name) | Requires classes extending `Error` to have names ending in `Error` | ❌ | ✅ |
 | [`require-new`](#require-new-auto-fixable) | Requires `new` when calling error constructors | ✅ | ✅ |
-<!-- eslint-enable markdown/no-missing-link-fragments -->
 
 ---
 
-### 𝄃𝄃𝄂𝄂𝄀𝄁𝄃𝄂𝄂𝄃 `no-explicit-return`
+### `no-explicit-return`
 
 > Disallows explicit `return` statements inside class constructors.
 
@@ -107,7 +111,7 @@ If you need to return a different object from a constructor.
 
 ---
 
-### 𝄃𝄃𝄂𝄂𝄀𝄁𝄃𝄂𝄂𝄃 `require-error-subclass-name`
+### `require-error-subclass-name`
 
 > Requires classes extending `Error` have a name ending in `Error`.
 
@@ -137,40 +141,44 @@ If you don't follow the convention of suffixing custom error classes w/ `Error`.
 
 ---
 
-### 𝄃𝄃𝄂𝄂𝄀𝄁𝄃𝄂𝄂𝄃 `require-new` (auto-fixable)
+### `require-new` (auto-fixable)
 
-> Requires `new` when calling error constructors (and optionally other built-in constructors).
+> Requires `new` when calling error constructors (and optionally other built-ins).
 
 #### Options
 
-- `'error-only'` (default) – only error constructors (`AggregateError`, `Error`, `EvalError`, `RangeError`, `ReferenceError`, `SyntaxError`, `TypeError`, `URIError`)
-- `'builtins'` – also includes `Array`, `BigInt`, `Boolean`, `Date`, `Function`, `Map`, `Number`, `Object`, `RegExp`, `Set`, `String`, `Symbol`, `WeakMap`, `WeakSet`
+- `'errors'` (default) — require for error constructors.
+- `'throwing'` — require for errors + constructors that throw a `TypeError` when called without `new`.
+- `'all'` — require for errors + throwing constructors + constructors where `new` is optional.
+
+Excluded: `Boolean`, `Number`, `String` (calling w/ `new` returns wrapper objects), and `Symbol`, `BigInt` (cannot be called w/ `new`).
 
 #### Incorrect code
 
 ```js
+// 'errors' (default)
 throw Error('boom')
-throw TypeError('bad')
 
-// w/ builtins:
-const arr = Array(),
-      m = Map()
+// 'throwing'
+const m = Map()
+
+// 'all'
+const arr = Array()
 ```
 
 #### Correct code
 
 ```js
 throw new Error('boom')
-throw new TypeError('bad')
 
-// w/ builtins:
-const arr = new Array(),
-      m = new Map()
+const m = new Map()
+
+const arr = new Array()
 ```
 
 #### When not to use it
 
-If you prefer the convenience of calling built-ins without `new` (which is allowed for some of them).
+If you prefer calling built-ins w/o `new` (which the runtime allows for some of them) and don't want to enforce it for consistency.
 
 <div align="center">
 
@@ -198,17 +206,15 @@ If you prefer the convenience of calling built-ins without `new` (which is allow
 [![Linted by eslint-plugin-constructors](https://img.shields.io/badge/Linted_by-eslint--plugin--constructors-4b32c3?logo=eslint&logoColor=white&labelColor=464646&style=for-the-badge)](https://codeberg.org/adamlui/eslint-plugin-constructors/#readme)
 ```
 
+---
+
 ## License
 
 [<img height=62 src="https://cdn.staticdelivr.com/gl/adamlui/eslint-plugin-constructors/af5fe76586/assets/images/logos/mit-license/red-pixelated.png">][epc-license]
 
 <details>
 
-<summary>
-
-Copyright © 2026 [Adam Lui][adamlui-cb] under the [MIT license][epc-license].
-
-</summary><br>
+<summary>Copyright © 2026 <a href="https://codeberg.org/adamlui">Adam Lui</a> under the <a href="https://codeberg.org/adamlui/eslint-plugin-constructors/src/branch/main/docs/LICENSE.md">MIT license</a>.</summary><br>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
@@ -218,6 +224,8 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 </details>
 
+---
+
 ## Related
 
  <!-- eslint-plugin-greasemonkey -->
@@ -251,7 +259,6 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 <!-- Links -->
 
-[adamlui-cb]: https://codeberg.org/adamlui
 [adamlui-npmx]: https://npmx.dev/org/adamlui
 [epc-bugs]: https://codeberg.org/adamlui/eslint-plugin-constructors/issues/new
 [epc-license]: https://codeberg.org/adamlui/eslint-plugin-constructors/src/branch/main/docs/LICENSE.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-constructors",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "ESLint rules for constructor usage",
   "type": "module",
   "engines": {
@@ -40,7 +40,7 @@
     "lint:fix": "eslint . --fix --cache && yamllint .",
     "lint:fix-all": "eslint . --fix && yamllint .",
     "test": "node tests/run.js",
-    "demo": "eslint --config demo/eslint.config.js demo/buggy-script.js",
+    "demo": "node demo/run.js",
     "bump:patch": "bash utils/bump.sh patch",
     "bump:minor": "bash utils/bump.sh minor",
     "bump:feat": "npm run bump:minor",
@@ -59,6 +59,9 @@
     "eslintplugin",
     "security"
   ],
+  "dependencies": {
+    "globals": "^17.12.0"
+  },
   "peerDependencies": {
     "eslint": ">=9.0.0"
   },
@@ -77,7 +80,6 @@
     "eslint-plugin-promise": "^7.3.0",
     "eslint-plugin-regexp": "^3.3.0",
     "eslint-plugin-security": "^4.0.1",
-    "globals": "^17.12.0",
     "husky": "^9.1.7",
     "yamllint-js": "^0.2.4"
   }

package/src/index.js

@@ -1,12 +1,12 @@
-import requireNew from './rules/require-new.js'
-import requireErrorSubclassName from './rules/require-error-subclass-name.js'
 import noExplicitReturn from './rules/no-explicit-return.js'
+import requireErrorSubclassName from './rules/require-error-subclass-name.js'
+import requireNew from './rules/require-new.js'
 
 const plugin = {
     rules: {
-        'require-new': requireNew,
+        'no-explicit-return': noExplicitReturn,
         'require-error-subclass-name': requireErrorSubclassName,
-        'no-explicit-return': noExplicitReturn
+        'require-new': requireNew
     }
 }
 
@@ -14,9 +14,9 @@ plugin.configs = {
     recommended: {
         plugins: { constructors: plugin },
         rules: {
-            'constructors/require-new': 'error',
+            'constructors/no-explicit-return': 'error',
             'constructors/require-error-subclass-name': 'error',
-            'constructors/no-explicit-return': 'error'
+            'constructors/require-new': 'error'
         }
     }
 }

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

@@ -1,9 +1,9 @@
-const reFuncNodeType = /^(?:Arrow)?Function(?:Declaration|Expression)$/
+const re = { funcNodeType: /^(?:Arrow)?Function(?:Declaration|Expression)$/ }
 
 function isInsideConstructorFunc(node) {
     let current = node.parent
     while (current) {
-        if (reFuncNodeType.test(current.type))
+        if (re.funcNodeType.test(current.type))
             return ( // whether this func is constructor's val
                    current.parent?.type == 'MethodDefinition'
                 && current.parent.kind == 'constructor'

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

@@ -11,16 +11,16 @@ export default {
     },
 
     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 checkName(name, node) {
+            if (!name || name.endsWith('Error')) return
+            context.report({ node, messageId: 'endWithError' })
+        }
+
         function checkVariableDeclarator(node) {
             const classExpr = node.init
             if (classExpr?.type != 'ClassExpression'

package/src/rules/require-new.js

@@ -1,13 +1,20 @@
-const errors = new Set([
-    'AggregateError', 'Error', 'EvalError', 'RangeError', 'ReferenceError', 'SyntaxError', 'TypeError', 'URIError'])
+import globals from 'globals'
 
-const builtins = new Set([
+const errorConstructors = new Set(Object.keys(globals.builtin).filter(name => name.endsWith('Error')))
+
+const throwingConstructors = new Set([
+    'ArrayBuffer', 'BigInt64Array', 'BigUint64Array', 'DataView', 'FinalizationRegistry', 'Float32Array',
+    'Float64Array', 'Int8Array', 'Int16Array', 'Int32Array', 'Map', 'Promise', 'Proxy', 'Set', 'SharedArrayBuffer',
+    'Uint8Array', 'Uint8ClampedArray', 'Uint16Array', 'Uint32Array', 'WeakMap', 'WeakRef', 'WeakSet'
+])
+
+const lenientConstructors = new Set(['Array', 'Date', 'Function', 'Object', 'RegExp'])
+
+const legacyBuiltins = new Set([
     'Array', 'BigInt', 'Boolean', 'Date', 'Function', 'Map', 'Number', 'Object', 'RegExp', 'Set', 'String', 'Symbol',
     'WeakMap', 'WeakSet'
 ])
 
-function isErrConstructor(name) { return errors.has(name) }
-
 export default {
     meta: {
         type: 'problem',
@@ -19,22 +26,41 @@ export default {
         fixable: 'code',
         schema: [{
             type: 'string',
-            enum: ['error-only', 'builtins'],
-            description: 'Constructor categories to check: "error-only" (default) or "builtins".'
+            enum: ['errors', 'throwing', 'all', 'error-only', 'builtins'],
+            description: 'Constructor categories to check'
         }],
-        defaultOptions: ['error-only'],
-        messages: { requireNew: 'Use `new {{name}}()` instead of `{{name}}()`' }
+        defaultOptions: ['errors'],
+        messages: {
+            requireNew: 'Use `new {{name}}()` instead of `{{name}}()`',
+            deprecatedMode: `'{{old}}' is deprecated. Use '{{new}}' instead.`
+        }
     },
 
     create(context) {
-        const mode = context.options[0] || 'error-only'
+        const rawMode = context.options[0] || 'errors'
+        let mode = rawMode, deprecation
+        if (rawMode == 'error-only') { mode = 'errors' ; deprecation = { old: 'error-only', new: 'errors' }}
+        else if (rawMode == 'builtins') mode = 'legacy-builtins'
+
+        function shouldReportName(name) {
+            return mode == 'errors' ? errorConstructors.has(name)
+                 : mode == 'throwing' ? errorConstructors.has(name) || throwingConstructors.has(name)
+                 : mode == 'all' ? errorConstructors.has(name) || throwingConstructors.has(name)
+                                || lenientConstructors.has(name)
+                 : mode == 'legacy-builtins' ? errorConstructors.has(name) || legacyBuiltins.has(name)
+                 : false
+        }
+
         return {
+            Program(node) {
+                if (deprecation)
+                    context.report({
+                        node, messageId: 'deprecatedMode', data: { old: deprecation.old, new: deprecation.new }})
+            },
             CallExpression(node) {
                 if (node.new) return
                 const calleeName = node.callee.name ; if (!calleeName) return
-                const shouldReport = mode == 'error-only' ? isErrConstructor(calleeName)
-                                   : isErrConstructor(calleeName) || builtins.has(calleeName)
-                if (shouldReport)
+                if (shouldReportName(calleeName))
                     context.report({
                         node, messageId: 'requireNew', data: { name: calleeName },
                         fix(fixer) { return fixer.insertTextBefore(node, 'new ') }