@ericcornelissen/lregexp 1.0.5 → 1.0.6

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,33 @@
 # 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 +35,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,9 @@
+# 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/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.6",
   "license": "MIT",
   "type": "module",
   "exports": {