@ericcornelissen/lregexp 1.0.5 → 1.0.7

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Eric Cornelissen
+Copyright (c) 2025-2026 Eric Cornelissen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,21 +1,35 @@
+<!-- SPDX-License-Identifier: CC0-1.0 -->
+
 # lRegExp
 
-Transparently create linear-time ([non-backtracking]) regular expressions.
+Transparent linear-time ([non-backtracking]) regular expressions for libraries.
 
 [non-backtracking]: https://v8.dev/blog/non-backtracking-regexp
 
 ## Usage
 
-This library exports a drop-in replacement for the built-in RegExp.
+This library exports a drop-in replacement for the built-in RegExp ([caveats]
+apply).
 
-```shell
-npm install @ericcornelissen/lregexp
-```
+1. Install
 
-```javascript
-import RegExp from "@ericcornelissen/lregexp";
-new RegExp("[linear]{6}");
-```
+   ```shell
+   npm install @ericcornelissen/lregexp
+   ```
+
+2. Import
+
+   ```javascript
+   import RegExp from "@ericcornelissen/lregexp";
+   ```
+
+3. Use
+
+   ```javascript
+   new RegExp("[linear]{6}");
+   ```
+
+[caveats]: #caveats
 
 ## Why
 
@@ -23,9 +37,51 @@ Backtracking regular expressions can take exponential time to evaluate, leading
 to the dreaded _ReDoS_ vulnerability. Linear-time regular expressions avoid this
 by not backtracking.
 
+In Node.js, linear-time regular expressions can be created using the `l` flag
+provided the `--enable-experimental-regexp-engine` CLI option is used. This
+makes it difficult for library authors to tap into. Using this package, a
+library can use the RegExp constructor as usual and benefit from the linear time
+regular expression engine when its users enable it. If they don't, it gracefully
+falls back to the default constructor.
+
 ## Caveats
 
-Not all regular expression constructs are valid in a linear-time regular
-expression and this library won't tell you your regular expression is
-incompatible unless you run it with the non-backtracking engine, in which
-case it throws an error.
+Not all valid JavaScript regular expressions are supported when using the
+`--enable-experimental-regexp-engine` CLI option. This library won't tell you if
+your regular expressions are incompatible, unless you run it with that CLI
+option. If a regular expression is incompatible the constructor will throw a
+SyntaxError.
+
+To support users of this package in writing compatible regular expressions we're
+interested in:
+
+- an ESLint plugin to lint regular expressions and raise warnings for the use of
+  regex features not supported by the non-backtracing engine; ([#4])
+- a tool (CLI/web) to check a given regular expression for compatibility with
+  the non-backtracing engine. ([#21])
+
+[#4]: https://github.com/ericcornelissen/lregexp/issues/4
+[#21]: https://github.com/ericcornelissen/lregexp/issues/21
+
+## How
+
+If `--enable-experimental-regexp-engine` is used, the RegExp constructor from
+this package automatically adds the `l` flag to all regular expressions it
+constructs. If not, the RegExp constructor behavior is unchanged.
+
+## Example
+
+A classic example of a ReDoS-vulnerable regular expression is `(a*)*b`. Using
+this with vanilla Node.js on a pathological input string takes some time, test
+it for yourself with (add an `a` and the runtime doubles):
+
+```shell
+node -e '/(a*)*b/.test("aaaaaaaaaaaaaaaaaaaaaaaaac")'
+```
+
+When the non-backtracking regular expression engine is enabled, the expression
+evaluates instantly:
+
+```shell
+node -e '/(a*)*b/l.test("aaaaaaaaaaaaaaaaaaaaaaaaac")' --enable-experimental-regexp-engine
+```

package/SECURITY.md

@@ -0,0 +1,11 @@
+<!-- SPDX-License-Identifier: CC0-1.0 -->
+
+# Security Policy
+
+All security issues in `@ericcornelissen/lregexp` should be reported publicly as
+bugs. Private reports will be made public by the maintainers after 7 days with
+best-effort attribution.
+
+This document should be considered expired after 2026-06-01. If you are reading
+this after that date you should try to find an up-to-date version in the source
+repository.

package/index.cjs

@@ -1,11 +1,27 @@
+// SPDX-License-Identifier: MIT
+
 const isSupportedRegexpFlag = require("./is-supported-regexp-flag.cjs");
 
+/**
+ * The `RegExp()` constructor creates {@link RegExp} objects.
+ *
+ * @param {string|RegExp} pattern The text of the regular expression. This can also be another RegExp object.
+ * @param {string} [flags] If specified, flags is a string that contains the flags to add. Alternatively, if a RegExp object is supplied for the pattern, the flags string will replace any of that object's flags.
+ * @returns {RegExp} A {@link RegExp} object constructed from `pattern` and `flags`.
+ * @throws {SyntaxError} Thrown in one of the following cases: `pattern` cannot be parsed as a valid regular expression, or `flags` contains repeated characters or any character outside of those allowed.
+ */
 let lRegExp = RegExp;
 
 if (isSupportedRegexpFlag("l")) {
-	const RegExp_ = globalThis.RegExp;
-	lRegExp = function(pattern, flags="") {
-		return new RegExp_(pattern, `${flags}l`);
+	lRegExp = function(pattern, flags) {
+		if (flags === undefined) {
+			flags = "";
+			if (pattern instanceof RegExp && pattern.flags) {
+				flags = pattern.flags.replace(/l/g, "");
+			}
+		}
+
+		return new RegExp(pattern, `${flags}l`);
 	};
 }
 

package/index.d.ts

@@ -1,3 +1,3 @@
-export default class lRegExp {
-  constructor(pattern: string, flags?: string);
-}
+// SPDX-License-Identifier: MIT
+
+export default RegExp;

package/index.js

@@ -1,11 +1,27 @@
+// SPDX-License-Identifier: MIT
+
 import isSupportedRegexpFlag from "is-supported-regexp-flag";
 
+/**
+ * The `RegExp()` constructor creates {@link RegExp} objects.
+ *
+ * @param {string|RegExp} pattern The text of the regular expression. This can also be another RegExp object.
+ * @param {string} [flags] If specified, flags is a string that contains the flags to add. Alternatively, if a RegExp object is supplied for the pattern, the flags string will replace any of that object's flags.
+ * @returns {RegExp} A {@link RegExp} object constructed from `pattern` and `flags`.
+ * @throws {SyntaxError} Thrown in one of the following cases: `pattern` cannot be parsed as a valid regular expression, or `flags` contains repeated characters or any character outside of those allowed.
+ */
 let lRegExp = RegExp;
 
 if (isSupportedRegexpFlag("l")) {
-	const RegExp_ = globalThis.RegExp;
-	lRegExp = function(pattern, flags="") {
-		return new RegExp_(pattern, `${flags}l`);
+	lRegExp = function(pattern, flags) {
+		if (flags === undefined) {
+			flags = "";
+			if (pattern instanceof RegExp && pattern.flags) {
+				flags = pattern.flags.replace(/l/g, "");
+			}
+		}
+
+		return new RegExp(pattern, `${flags}l`);
 	};
 }
 

package/is-supported-regexp-flag.cjs

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: MIT
+
 /**
  * MIT License
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ericcornelissen/lregexp",
-  "description": "Transparently create linear-time regular expressions",
-  "version": "1.0.5",
+  "description": "Transparent linear-time (non-backtracking) regular expressions for libraries",
+  "version": "1.0.7",
   "license": "MIT",
   "type": "module",
   "exports": {