eslint-plugin-constructors 1.1.1 → 1.2.1

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,7 +20,14 @@ From your project root:
 npm i -D eslint-plugin-constructors
 ```
 
-## Usage
+---
+
+<h2 id="usage">
+    Usage
+    <a title="Copy section URL" target="_blank"
+       href="https://copy-to-clipboard.onrender.com/copy/https%3A%2F%2Fcodeberg.org%2Fadamlui%2Feslint-plugin-constructors%2F%23usage">
+        <img height=17 width=22 alt="[Copy section URL]" src="https://api.iconify.design/mdi/content-copy.svg?color=%23cccccc" align="bottom"></a>
+</h2>
 
 Add `constructors` to your flat config:
 
@@ -32,7 +41,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,44 +62,65 @@ export default [
 ]
 ```
 
-## Supported rules
+---
+
+<h2 id="supported-rules">
+    Supported rules
+    <a title="Copy section URL" target="_blank"
+       href="https://copy-to-clipboard.onrender.com/copy/https%3A%2F%2Fcodeberg.org%2Fadamlui%2Feslint-plugin-constructors%2F%23supported-rules">
+        <img height=17 width=22 alt="[Copy section URL]" src="https://api.iconify.design/mdi/content-copy.svg?color=%23cccccc" align="bottom"></a>
+</h2>
 
 | 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 | ✅ | ✅ |
+| [`require-new`](#require-new) | Requires `new` when calling error constructors | ✅ | ✅ |
 
 ---
 
-### `no-explicit-return`
+<h3 id="no-explicit-return">
+    <code>no-explicit-return</code>
+    <a title="Included in recommended config" href="#usage">
+        <img height=18 alt="[Recommended]" src="https://img.shields.io/badge/Recommended-f1f20a?style=flat-square" align="middle"></a>
+    <a title="Copy rule URL" target="_blank" 
+       href="https://copy-to-clipboard.onrender.com/copy/https%3A%2F%2Fcodeberg.org%2Fadamlui%2Feslint-plugin-constructors%2F%23no-explicit-return">
+        <img height=16 width=21 alt="[Copy rule URL]" src="https://api.iconify.design/mdi/content-copy.svg?color=%23cccccc" align="middle"></a>
+</h3>
 
 > Disallows explicit `return` statements inside class constructors.
 
 #### Incorrect code
 
-```js
-class A {
-    constructor() {
-        return
-    }
-}
-
-class B {
-    constructor() {
-        return this
-    }
-}
+```diff
+  class A {
+      constructor() {
+!         return
+      }
+  }
+
+  class B {
+      constructor() {
+!         return this
+      }
+  }
 ```
 
 #### Correct code
 
-```js
-class A {
-    constructor() {
-        this.x = 1
-    }
-}
+```diff
+  class A {
+      constructor() {
+-         return
++         this.x = 1
+      }
+
+  class B {
+      constructor() {
+-         return this
++         this.x = 1
+      }
+  }
 ```
 
 #### When not to use it
@@ -105,22 +135,31 @@ If you need to return a different object from a constructor.
 
 ---
 
-### `require-error-subclass-name`
+<h3 id="require-error-subclass-name">
+    <code>require-error-subclass-name</code>
+    <a title="Included in recommended config" href="#usage">
+        <img height=18 alt="[Recommended]" src="https://img.shields.io/badge/Recommended-f1f20a?style=flat-square" align="middle"></a>
+    <a title="Copy rule URL" target="_blank" 
+       href="https://copy-to-clipboard.onrender.com/copy/https%3A%2F%2Fcodeberg.org%2Fadamlui%2Feslint-plugin-constructors%2F%23require-error-subclass-name">
+        <img height=16 width=21 alt="[Copy rule URL]" src="https://api.iconify.design/mdi/content-copy.svg?color=%23cccccc" align="middle"></a>
+</h3>
 
 > Requires classes extending `Error` have a name ending in `Error`.
 
 #### Incorrect code
 
-```js
-class My extends Error {}
-const Custom = class extends Error {}
+```diff
+! class My extends Error {}
+! const Custom = class extends Error {}
 ```
 
 #### Correct code
 
-```js
-class MyError extends Error {}
-const CustomError = class extends Error {}
+```diff
+- class My extends Error {}
+- const Custom = class extends Error {}
++ class MyError extends Error {}
++ const CustomError = class extends Error {}
 ```
 
 #### When not to use it
@@ -135,40 +174,59 @@ If you don't follow the convention of suffixing custom error classes w/ `Error`.
 
 ---
 
-### `require-new` (auto-fixable)
+<h3 id="require-new">
+    <code>require-new</code>
+    <a title="Included in recommended config" href="#usage">
+        <img height=18 alt="[Recommended]" src="https://img.shields.io/badge/Recommended-f1f20a?style=flat-square" align="middle"></a>
+    <a title="Accepts eslint --fix" target="_blank" href="https://eslint.org/docs/latest/use/command-line-interface#--fix">
+        <img height=18 alt="[Auto-fixable]" src="https://img.shields.io/badge/Auto--fixable-e8357a?style=flat-square" align="middle"></a>
+    <a title="Copy rule URL" target="_blank" 
+       href="https://copy-to-clipboard.onrender.com/copy/https%3A%2F%2Fcodeberg.org%2Fadamlui%2Feslint-plugin-constructors%2F%23require-new">
+        <img height=16 width=21 alt="[Copy rule URL]" src="https://api.iconify.design/mdi/content-copy.svg?color=%23cccccc" align="middle"></a>
+</h3>
 
-> 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
-throw Error('boom')
-throw TypeError('bad')
+```diff
+/* eslint constructors/require-new: ['error', 'errors'] */
+! throw Error('boom')
 
-// w/ builtins:
-const arr = Array(),
-      m = Map()
+/* eslint constructors/require-new: ['error', 'throwing'] */
+! const m = Map()
+
+/* eslint constructors/require-new: ['error', 'all'] */
+! const arr = Array()
 ```
 
 #### Correct code
 
-```js
-throw new Error('boom')
-throw new TypeError('bad')
+```diff
+/* eslint constructors/require-new: ['error', 'errors'] */
+- throw Error('boom')
++ throw new Error('boom')
+
+/* eslint constructors/require-new: ['error', 'throwing'] */
+- const m = Map()
++ const m = new Map()
 
-// w/ builtins:
-const arr = new Array(),
-      m = new Map()
+/* eslint constructors/require-new: ['error', 'all'] */
+- const arr = Array()
++ 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">
 
@@ -178,35 +236,33 @@ If you prefer the convenience of calling built-ins without `new` (which is allow
 
 ---
 
-## Shield
+## Shield embed
 
 <a href="https://codeberg.org/adamlui/eslint-plugin-constructors/#readme">
-    <img height=32 alt="[Linted by eslint-plugin-constructors]" src="https://img.shields.io/badge/Linted_by-eslint--plugin--constructors-4b32c3?logo=eslint&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+    <img height=32 alt="[Linted by eslint-plugin-constructors]" src="https://img.shields.io/badge/Linted_by-eslint--plugin--constructors-black?logo=eslint&logoColor=white&labelColor=4B32C3&style=for-the-badge"></a>
 
 #### HTML
 
 ```html
 <a href="https://codeberg.org/adamlui/eslint-plugin-constructors/#readme">
-    <img height=32 alt="[Linted by eslint-plugin-constructors]" src="https://img.shields.io/badge/Linted_by-eslint--plugin--constructors-4b32c3?logo=eslint&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+    <img height=32 alt="[Linted by eslint-plugin-constructors]" src="https://img.shields.io/badge/Linted_by-eslint--plugin--constructors-black?logo=eslint&logoColor=white&labelColor=4B32C3&style=for-the-badge"></a>
 ```
 
 #### Markdown
 
 ```md
-[![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)
+[![Linted by eslint-plugin-constructors](https://img.shields.io/badge/Linted_by-eslint--plugin--constructors-black?logo=eslint&logoColor=white&labelColor=4B32C3&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"><b>Adam Lui</b></a> under the <a href="https://codeberg.org/adamlui/eslint-plugin-constructors/src/branch/main/docs/LICENSE.md"><b>MIT license</b></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:
 
@@ -216,6 +272,8 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 </details>
 
+---
+
 ## Related
 
  <!-- eslint-plugin-greasemonkey -->
@@ -249,7 +307,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.1",
+  "version": "1.2.1",
   "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/data/deprecations.js

@@ -0,0 +1,3 @@
+export const options = { 'require-new': { 'error-only': 'errors' }} // 2026-9-13
+
+export default { options }

package/src/index.js

@@ -1,22 +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'
+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
     }
 }
 
+const docsURL = 'https://codeberg.org/adamlui/eslint-plugin-constructors/#'
+for (const [ruleId, rule] of Object.entries(plugin.rules))
+    rule.meta.docs.url = `${docsURL}${ruleId}${ rule.meta.fixable ? '-auto-fixable' : '' }`
+
 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,21 @@
-const errors = new Set([
-    'AggregateError', 'Error', 'EvalError', 'RangeError', 'ReferenceError', 'SyntaxError', 'TypeError', 'URIError'])
+import deprecations from '../data/deprecations.js'
+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 +27,46 @@ 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 optionAliases = deprecations.options['require-new'] || {},
+              rawMode = context.options[0] || 'errors'
+        /* eslint-disable security/detect-object-injection */
+        let mode = optionAliases[rawMode] || rawMode, deprecation
+        if (optionAliases[rawMode])
+            deprecation = { old: rawMode, new: optionAliases[rawMode] }
+        /* eslint-enable security/detect-object-injection */
+        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 ') }