re2js 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,8 @@
 # RE2JS is the JavaScript port of RE2, a regular expression engine that provides linear time matching
 [![Test/Build/Deploy](https://github.com/le0pard/re2js/actions/workflows/tests.yml/badge.svg)](https://github.com/le0pard/re2js/actions/workflows/tests.yml)
 
+## [Playground](https://re2js.leopard.in.ua/)
+
 ## TLDR
 
 The built-in JavaScript regular expression engine can, under certain special combinations, run in exponential time. This situation can trigger what's referred to as a [Regular Expression Denial of Service (ReDoS)](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS). RE2, a different regular expression engine, can effectively safeguard your Node.js applications from ReDoS attacks. With RE2JS, this protective feature extends to browser environments as well, enabling you to utilize the RE2 engine more comprehensively.
@@ -23,7 +25,7 @@ This document provides a series of examples demonstrating how to use RE2JS in yo
 
 ### Compiling Patterns
 
-You can compile a regex pattern using the `RE2JS.compile()` function:
+You can compile a regex pattern using the `compile()` function:
 
 ```js
 import { RE2JS } from 're2js'
@@ -33,7 +35,7 @@ console.log(p.pattern()); // Outputs: 'abc'
 console.log(p.flags()); // Outputs: 0
 ```
 
-The `RE2JS.compile()` function also supports flags:
+The `compile()` function also supports flags:
 
 ```js
 import { RE2JS } from 're2js'
@@ -64,14 +66,14 @@ RE2JS.MULTILINE
  */
 RE2JS.DISABLE_UNICODE_GROUPS
 /**
- * Flag: matches longest possible string.
+ * Flag: matches longest possible string (changes the match semantics to leftmost-longest).
  */
 RE2JS.LONGEST_MATCH
 ```
 
 ### Checking for Matches
 
-RE2JS allows you to check if a string matches a given regex pattern using the `RE2JS.matches()` function
+RE2JS allows you to check if a string matches a given regex pattern using the `matches()` function
 
 ```js
 import { RE2JS } from 're2js'
@@ -83,6 +85,10 @@ RE2JS.compile('ab+c').matches('abbbc') // true
 RE2JS.compile('ab+c').matches('cbbba') // false
 // with flags
 RE2JS.compile('ab+c', RE2JS.CASE_INSENSITIVE).matches('AbBBc') // true
+RE2JS.compile(
+  '^ab.*c$',
+  RE2JS.DOTALL | RE2JS.MULTILINE | RE2JS.CASE_INSENSITIVE
+).matches('AB\nc') // true
 ```
 
 ### Finding Matches
@@ -114,6 +120,19 @@ matchString.group() // 'e'
 matchString.find(7) // false
 ```
 
+### Checking Initial Match
+
+The `lookingAt()` method determines whether the start of the given string matches the pattern
+
+```js
+import { RE2JS } from 're2js'
+
+RE2JS.compile('abc').matcher('abcdef').lookingAt() // true
+RE2JS.compile('abc').matcher('ab').lookingAt() // false
+```
+
+Note that the `lookingAt` method only checks the start of the string. It does not search the entire string for a match
+
 ### Splitting Strings
 
 You can split a string based on a regex pattern using the `split()` function
@@ -225,6 +244,33 @@ RE2JS.compile('(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)')
 
 Note that the replacement string can include references to capturing groups from the pattern
 
+Parameters:
+- `replacement (String)`: The string that replaces the substrings found. Capture groups and special characters in the replacement string have special behavior. For example:
+  - `$0` refers to the entire matched substring
+  - `$1, $2, ...` refer to the corresponding capture groups in the pattern
+  - `\$` inserts a literal `$`
+  - `${name}` can be used to reference named capture groups
+  - on invalid group - throw exception
+- `perlMode (Boolean)`: If set to `true`, the replacement follows Perl/JS's rules for replacement. Defaults to `false`. If `perlMode = true`, changed rules for capture groups and special characters:
+  - `$&` refers to the entire matched substring
+  - `$1, $2, ...` refer to the corresponding capture groups in the pattern
+  - `$$` inserts a literal `$`
+  - `$<name>` can be used to reference named capture groups
+  - on invalid group - ignore it
+
+Examples:
+
+```js
+import { RE2JS } from 're2js'
+
+RE2JS.compile('(\\w+) (\\w+)')
+  .matcher('Hello World')
+  .replaceAll('$0 - $0') // 'Hello World - Hello World'
+RE2JS.compile('(\\w+) (\\w+)')
+  .matcher('Hello World')
+  .replaceAll('$& - $&', true) // 'Hello World - Hello World'
+```
+
 #### Replacing the First Occurrence
 
 The `replaceFirst()` method replaces the first occurrence of a pattern match in a string with the given replacement
@@ -240,18 +286,59 @@ RE2JS.compile('(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)(.)')
   .replaceFirst('$10$20') // 'jb0nopqrstuvwxyz123'
 ```
 
-## Performance
+Function support second argument `perlMode`, which work in the same way, as for `replaceAll` function
+
+### Escaping Special Characters
+
+The `quote()` method returns a literal pattern string for the specified string. This can be useful if you want to search for a literal string pattern that may contain special characters
+
+```js
+import { RE2JS } from 're2js'
+
+const regexp = RE2JS.quote('ab+c') // 'ab\\+c'
 
-The RE2JS engine runs more slowly compared to native RegExp objects. This reduced speed is also noticeable when comparing RE2JS to the original RE2 engine. The primary reason behind this is the lack of a synchronous threads solution within the browser environment. This deficiency is significant because the regex engine requires a synchronous API to operate optimally.
+RE2JS.matches(regexp, 'ab+c') // true
+RE2JS.matches(regexp, 'abc') // false
+```
+
+## Performance
 
-The C++ implementation of the RE2 engine includes both NFA (Nondeterministic Finite Automaton) and DFA (Deterministic Finite Automaton) engines, as well as a variety of optimizations. Russ Cox ported a simplified version of the NFA engine to Go. Later, Alan Donovan ported the NFA-based Go implementation to Java. I then ported the NFA-based Java implementation to a pure JS version. This is another reason why the pure JS version will perform more slowly compared to the original RE2 engine.
+The RE2JS engine runs more slowly compared to native RegExp objects. This reduced speed is also noticeable when comparing RE2JS to the original RE2 engine. The C++ implementation of the RE2 engine includes both NFA (Nondeterministic Finite Automaton) and DFA (Deterministic Finite Automaton) engines, as well as a variety of optimizations. Russ Cox ported a simplified version of the NFA engine to Go. Later, Alan Donovan ported the NFA-based Go implementation to Java. I then ported the NFA-based Java implementation to a pure JS version. This is another reason why the pure JS version will perform more slowly compared to the original RE2 engine.
 
 Should you require high performance on the server side when using RE2, it would be beneficial to consider the following packages for JS:
 
  - [Node-RE2](https://github.com/uhop/node-re2/): A powerful RE2 package for Node.js
  - [RE2-WASM](https://github.com/google/re2-wasm/): This package is a WASM wrapper for RE2. Please note, as of now, it does not work in browsers
 
-## Justification for this JS port existence
+### RE2JS vs JavaScript's native RegExp
+
+These examples illustrate the performance comparison between the RE2JS library and JavaScript's native RegExp for both a simple case and a ReDoS (Regular Expression Denial of Service) scenario
+
+```js
+const regex = 'a+'
+const string = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa!'
+
+RE2JS.compile(regex).matcher(string).find() // avg: 5.657783601 ms
+new RegExp(regex).test(string) // avg: 1.504824999 ms
+```
+
+The result shows that the RE2JS library took around **5.66 ms** on average to find a match, while the native RegExp took around **1.50 ms**. This indicates that, in this case, RegExp performed faster than RE2JS
+
+```js
+const regex = '([a-z]+)+$'
+const string = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa!'
+
+RE2JS.compile(regex).matcher(string).find() // avg: 3.6155000030994415 ms
+new RegExp(regex).test(string) // avg: 103768.25712499022 ms
+```
+
+In the second example, a ReDoS scenario is depicted. The regular expression `([a-z]+)+$` is a potentially problematic one, as it has a nested quantifier. Nested quantifiers can cause catastrophic backtracking, which results in high processing time, leading to a potential Denial of Service (DoS) attack if a malicious user inputs a carefully crafted string.
+
+The string is the same as in the first example, which does not pose a problem for either RE2JS or RegExp under normal circumstances. However, when dealing with the nested quantifier, RE2JS took around **3.62 ms** to find a match, while RegExp took significantly longer, around **103768.26 ms (~103 seconds)**. This demonstrates that RE2JS is much more efficient in handling potentially harmful regular expressions, thus preventing ReDoS attacks.
+
+In conclusion, while JavaScript's native RegExp might be faster for simple regular expressions, RE2JS offers significant performance advantages when dealing with complex or potentially dangerous regular expressions. RE2JS provides protection against excessive backtracking that could lead to performance issues or ReDoS attacks.
+
+## Rationale for RE2 JavaScript port
 
 There are several reasons that underscore the importance of having an RE2 vanilla JavaScript (JS) port.
 
@@ -271,3 +358,5 @@ yarn node ./tools/scripts/genUnicodeTable.js > src/UnicodeTables.js
 ```
 
 To run `make_perl_groups.pl` you need to have install perl (version inside `.tool-versions`)
+
+[Playground website](https://re2js.leopard.in.ua/) maintained in `www` branch