| 1 |
<!-- Canonical source: AGENTS.md — keep this file in sync --> |
| 2 |
# AGENTS.md — node-re2 |
| 3 |
|
| 4 |
> `node-re2` provides Node.js bindings for [RE2](https://github.com/google/re2): a fast, safe alternative to backtracking regular expression engines. The npm package name is `re2`. It is a C++ native addon built with `node-gyp` and `nan`. |
| 5 |
|
| 6 |
For project structure, module dependencies, and the architecture overview see [ARCHITECTURE.md](./ARCHITECTURE.md). |
| 7 |
For detailed usage docs see the [README](./README.md) and the [wiki](https://github.com/uhop/node-re2/wiki). |
| 8 |
|
| 9 |
## Setup |
| 10 |
|
| 11 |
This project uses git submodules for vendored dependencies (RE2 and Abseil): |
| 12 |
|
| 13 |
```bash |
| 14 |
git clone --recursive https://github.com/uhop/node-re2.git |
| 15 |
cd node-re2 |
| 16 |
npm install |
| 17 |
``` |
| 18 |
|
| 19 |
If the native addon fails to download a prebuilt artifact, it builds locally via `node-gyp`. |
| 20 |
|
| 21 |
**Supported Node.js versions:** `^22.22.2 || ^24.15.0 || >=26.0.0` (the `engines` field). Narrowed in 1.25.0 to mirror `node-gyp` 13 — Node 25.x and the older 22.0–22.22.1 / 24.0–24.14 patch ranges are no longer supported. |
| 22 |
|
| 23 |
## Commands |
| 24 |
|
| 25 |
- **Install:** `npm install` (downloads prebuilt artifact or builds from source) |
| 26 |
- **Build (release):** `npm run rebuild` (or `node-gyp -j max rebuild`) |
| 27 |
- **Build (debug):** `npm run rebuild:dev` (or `node-gyp -j max rebuild --debug`) |
| 28 |
- **Test:** `npm test` (runs `tape6 --flags FO`, worker threads) |
| 29 |
- **Test (sequential):** `npm run test:seq` |
| 30 |
- **Test (multi-process):** `npm run test:proc` |
| 31 |
- **Test (single file):** `node tests/test-<name>.mjs` |
| 32 |
- **TypeScript check:** `npm run ts-check` |
| 33 |
- **Lint:** `npm run lint` (Prettier check) |
| 34 |
- **Lint fix:** `npm run lint:fix` (Prettier write) |
| 35 |
- **Verify build:** `npm run verify-build` |
| 36 |
|
| 37 |
## Project structure |
| 38 |
|
| 39 |
``` |
| 40 |
node-re2/ |
| 41 |
├── package.json # Package config; "tape6" section configures test discovery |
| 42 |
├── binding.gyp # node-gyp build configuration for the C++ addon |
| 43 |
├── re2.js # Main entry point: loads native addon, sets up Symbol aliases |
| 44 |
├── re2.d.ts # TypeScript declarations for the public API |
| 45 |
├── tsconfig.json # TypeScript config (noEmit, strict, types: ["node"]) |
| 46 |
├── lib/ # C++ source code (native addon) |
| 47 |
│ ├── addon.cc # Node.js addon initialization, method registration |
| 48 |
│ ├── wrapped_re2.h # WrappedRE2 class definition (core C++ wrapper) |
| 49 |
│ ├── wrapped_re2_set.h # WrappedRE2Set class definition (RE2.Set wrapper) |
| 50 |
│ ├── isolate_data.h # Per-isolate data struct for thread-safe addon state |
| 51 |
│ ├── new.cc # Constructor: parse pattern/flags, create RE2 instance |
| 52 |
│ ├── exec.cc # RE2.prototype.exec() implementation |
| 53 |
│ ├── test.cc # RE2.prototype.test() implementation |
| 54 |
│ ├── match.cc # RE2.prototype.match() implementation |
| 55 |
│ ├── replace.cc # RE2.prototype.replace() implementation |
| 56 |
│ ├── search.cc # RE2.prototype.search() implementation |
| 57 |
│ ├── split.cc # RE2.prototype.split() implementation |
| 58 |
│ ├── to_string.cc # RE2.prototype.toString() implementation |
| 59 |
│ ├── accessors.cc # Property accessors (source, flags, lastIndex, etc.) |
| 60 |
│ ├── pattern.cc # Pattern translation (RegExp → RE2 syntax, Unicode classes) |
| 61 |
│ ├── set.cc # RE2.Set implementation (multi-pattern matching) |
| 62 |
│ ├── util.cc # Shared utilities (UTF-8/UTF-16 conversion, buffer helpers) |
| 63 |
│ ├── util.h # Utility declarations |
| 64 |
│ └── pattern.h # Pattern translation declarations |
| 65 |
├── scripts/ |
| 66 |
│ └── verify-build.js # Quick smoke test for the built addon |
| 67 |
├── tests/ # Test files (test-*.mjs using tape-six) |
| 68 |
├── ts-tests/ # TypeScript type-checking tests |
| 69 |
│ └── test-types.ts # Verifies type declarations compile correctly |
| 70 |
├── bench/ # Benchmarks |
| 71 |
├── vendor/ # Vendored C++ dependencies (git submodules) |
| 72 |
│ ├── re2/ # Google RE2 library source |
| 73 |
│ └── abseil-cpp/ # Abseil C++ library (RE2 dependency) |
| 74 |
└── .github/ # CI workflows, Dependabot config, actions |
| 75 |
``` |
| 76 |
|
| 77 |
## Code style |
| 78 |
|
| 79 |
- **CommonJS** throughout (`"type": "commonjs"` in package.json). |
| 80 |
- **No transpilation** — JavaScript code runs directly. |
| 81 |
- **C++ code** uses tabs for indentation, 4-wide. JavaScript uses 2-space indentation. |
| 82 |
- **Prettier** for JS/TS formatting (see `.prettierrc`): 80 char width, single quotes, no bracket spacing, no trailing commas, arrow parens "avoid". |
| 83 |
- **nan** (Native Abstractions for Node.js) for the C++ addon API. |
| 84 |
- Semicolons are enforced by Prettier (default `semi: true`). |
| 85 |
- Imports use `require()` syntax in source, `import` in tests (`.mjs`). |
| 86 |
|
| 87 |
## Critical rules |
| 88 |
|
| 89 |
- **Do not modify vendored code.** Never edit files under `vendor/`. They are git submodules. |
| 90 |
- **Do not modify or delete test expectations** without understanding why they changed. |
| 91 |
- **Do not add comments or remove comments** unless explicitly asked. |
| 92 |
- **Keep `re2.js` and `re2.d.ts` in sync.** All public API exposed from `re2.js` must be typed in `re2.d.ts`. |
| 93 |
- **The addon must build on all supported platforms:** Linux (x64, arm64, Alpine), macOS (x64, arm64), Windows (x64, arm64). |
| 94 |
- **RE2 is always Unicode-mode.** The `u` flag is always added implicitly. |
| 95 |
- **Buffer support is a first-class feature.** All methods that accept strings must also accept Buffers, returning Buffers when given Buffer input. |
| 96 |
|
| 97 |
## Architecture |
| 98 |
|
| 99 |
- `re2.js` is the main entry point. It loads the native C++ addon from `build/Release/re2.node` and sets up `Symbol.match`, `Symbol.search`, `Symbol.replace`, `Symbol.split`, and `Symbol.matchAll` on the prototype. |
| 100 |
- The C++ addon (`lib/*.cc`) wraps Google's RE2 library via nan. Each RegExp method has its own `.cc` file. |
| 101 |
- `lib/new.cc` handles construction: parsing patterns, translating RegExp syntax to RE2 syntax (via `lib/pattern.cc`), and creating the underlying `re2::RE2` instance. |
| 102 |
- `lib/pattern.cc` translates JavaScript RegExp features to RE2 equivalents. General_Category and Script are mapped to RE2-native names (`\p{Letter}` → `\p{L}`, `\p{Script=Latin}` → `\p{Latin}`); binary properties (Emoji, Alphabetic, ASCII, ID_Start, …) and Script_Extensions are expanded inline to codepoint-range character classes using tables in `lib/unicode_properties.h`. The full accepted set matches [MDN's Unicode character class escape reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape) (excluding `v`-flag Properties of Strings). Tables are auto-generated from `@unicode/unicode-17.0.0` via `node scripts/gen-unicode-properties.mjs`. |
| 103 |
- `lib/set.cc` implements `RE2.Set` for multi-pattern matching using `re2::RE2::Set`. |
| 104 |
- `lib/util.cc` provides UTF-8 ↔ UTF-16 conversion helpers and buffer utilities. |
| 105 |
- Prebuilt native artifacts are hosted on GitHub Releases and downloaded at install time via `install-artifact-from-github`. |
| 106 |
|
| 107 |
## Writing tests |
| 108 |
|
| 109 |
```js |
| 110 |
import test from 'tape-six'; |
| 111 |
import {RE2} from '../re2.js'; |
| 112 |
|
| 113 |
test('example', t => { |
| 114 |
const re = new RE2('a(b*)', 'i'); |
| 115 |
const result = re.exec('aBbC'); |
| 116 |
t.ok(result); |
| 117 |
t.equal(result[0], 'aBb'); |
| 118 |
t.equal(result[1], 'Bb'); |
| 119 |
}); |
| 120 |
``` |
| 121 |
|
| 122 |
- Test files use `tape-six`: `.mjs` for runtime tests, `.ts` for TypeScript typing tests. |
| 123 |
- Test file naming convention: `test-*.mjs` in `tests/`, `test-*.ts` in `ts-tests/`. |
| 124 |
- Tests are configured in `package.json` under the `"tape6"` section. |
| 125 |
- Test files should be directly executable: `node tests/test-foo.mjs`. |
| 126 |
|
| 127 |
## Key conventions |
| 128 |
|
| 129 |
- The library is a drop-in replacement for `RegExp` — the `RE2` object emulates the standard `RegExp` API. |
| 130 |
- `RE2.Set` provides multi-pattern matching: `new RE2.Set(patterns, flags, options)`. |
| 131 |
- Static helpers: `RE2.getUtf8Length(str)`, `RE2.getUtf16Length(buf)`. |
| 132 |
- `RE2.unicodeWarningLevel` controls behavior when non-Unicode regexps are created. |
| 133 |
- The `install` script tries to download a prebuilt `.node` artifact before falling back to `node-gyp rebuild`. |
| 134 |
- All C++ source is in `lib/`, all vendored third-party C++ is in `vendor/`. |