literate-regex 0.5.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Modifications Copyright 2025 jeffy-g
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,231 @@
+![LICENSE](https://img.shields.io/badge/Lisence-Apache2.0-blue.svg)
+[![npm version](https://badge.fury.io/js/literate-regex.svg)](https://badge.fury.io/js/literate-regex)
+![npm bundle size](https://img.shields.io/bundlephobia/min/literate-regex?style=plastic)
+![npm](https://img.shields.io/npm/dm/literate-regex.svg?style=plastic)
+![npms.io](https://img.shields.io/npms-io/maintenance-score/literate-regex)
+![Libraries.io dependency status for GitHub repo](https://img.shields.io/librariesio/github/jeffy-g/literate-regex)
+
+# literate-regex
+
+A literate, typed JavaScript regex toolkit — powered by TypeScript.
+
+> Write regex like a human. Ship it like a machine.
+
+
+## ✨ Motivation
+
+Regular expressions are absurdly powerful — a tiny automaton you can carry in your pocket.  
+But once a regex grows beyond “a few tokens and a prayer”, it becomes:
+
+- hard to read
+- easy to break
+- painful to maintain
+
+This library exists to keep regexes **literate**.
+
+Write a multi-line, commented, PCRE-style regex source (with `#` notes), then normalize it into a compact JavaScript `RegExp.source` **while preserving the normalized source as a TypeScript string literal type**.
+
+That gives you two superpowers:
+
+1. **Human-friendly editing** (readable formatting + comments)
+2. **Machine-friendly safety** (typed, normalized sources that flow through your codebase)
+
+In short: fewer regex jump-scares, more confidence.
+
+### Before
+```ts
+const re = /^(?:\s*\/\*\*\s+|\s+\*?\s+)(?:(?=@(...))|...)/gm;
+```
+
+### After
+```ts
+const RE_SOURCE = `
+/^         # start
+(?: ... )  # jsdoc start
+...        # more notes
+/gm` as const;
+
+const re = compilePCREStyleRegExpLiteral(RE_SOURCE);
+```
+
+---
+
+## ✨ Features
+
+- **PCRE-ish style regex source**:
+  - multi-line formatting
+  - `# ...` line comments
+  - `\#` escape for literal `#`
+- **Type-level normalization**:
+  - derive normalized JS `RegExp.source` as a string literal type
+- **Optional global augmentation**:
+  - opt-in only (`import "literate-regex/global"`)
+- Designed to reduce TypeScript instantiation pain:
+  - line-oriented normalization (helps avoid `ts(2589)` compared to naive full-string scanning)
+
+---
+
+## 📦 Install
+
+```bash
+npm i literate-regex
+# or
+pnpm add literate-regex
+# or
+yarn add literate-regex
+```
+
+---
+
+## 🚀 Quick Start
+
+```ts
+import { PCREStyleToJsRegExpSource } from "literate-regex";
+
+// Only those who want to expand globally
+import "literate-regex/global";
+```
+
+---
+
+## 🧠 Type-level normalization
+
+### 1) Write a readable PCRE-style source
+
+* `#` starts a line comment (unless escaped)
+* `\#` is kept as a literal `#`
+* whitespace characters are stripped during normalization
+
+```ts
+import type { PCREStyleToJsRegExpSource } from "./literate-regex";
+
+// sample 1
+const RE_SOURCE = `
+^           # start
+(?:\\#\\w+) # literal "#"
+\\s+        # whitespace
+` as const;
+
+// type JsSource = "^(?:#\\w+)\\s+" 
+type JsSource = PCREStyleToJsRegExpSource<typeof RE_SOURCE>;
+```
+
+> Tip: You must use `as const` to preserve the source as a string literal type.
+
+---
+
+## 🔧 Runtime normalization (optional)
+
+`PCREStyleToJsRegExpSource<...>` is purely type-level.
+If you also normalize at runtime, mirror the same rules:
+
+```ts
+import { normalizePCREStyleSource } from "literate-regex";
+// import type { PCREStyleToJsRegExpSource } from "literate-regex";
+
+// sample 2
+const src = `
+^        # start
+\\#\\w+  # literal
+` as const;
+
+// '^#\\w+'
+// const normalized: "^#\\w+"
+const normalized = normalizePCREStyleSource(src);
+```
+
+## 🔧 Runtime creation Compile PCRE Style RegExpLiteral
+
+```ts
+import {
+  TypedRegExp,
+  // normalizePCREStyleSource,
+  compilePCREStyleRegExpLiteral,
+} from "literate-regex";
+import type {
+  RegExpLiteralParts,
+  PCREStyleToJsRegExpSource,
+  RegExpExecArrayFixedPretty,
+  ReplacerFunctionSignature,
+} from "literate-regex";
+
+//
+// sample of compilePCREStyleRegExpLiteral
+//
+const pcreStyledRegex = `/
+(\\(\\?\#[\\s\\S]*?(?<!\\\\)\\)(?=\\s*$|.))         # multi line comment
+|
+(?:^(?:\\s+|))?(?<![\\\\])(\\#(?:\\s|[\\s\\S])*?$)  # single line comment
+|
+(?<regexFragment>
+  (?:^\\s+)?(?:[^\\s]+)
+)+                                                  # regex flagment
+|
+([\\r|\\r\\n|\\n]+|[\\x20\\t]+(?=$)?)               # whitespaces
+/gm`;
+
+const jsRegex = compilePCREStyleRegExpLiteral(pcreStyledRegex);
+
+type TPcreStyledRegex = typeof pcreStyledRegex;
+type TJsRegexSource = PCREStyleToJsRegExpSource<TPcreStyledRegex>;
+type TJsRegexLiteralParts = RegExpLiteralParts<TJsRegexSource>;
+
+type TJsRegexExecArray = RegExpExecArrayFixedPretty<
+  TypedRegExp<TJsRegexLiteralParts["pattern"]>
+>;
+type TJsRegexStringReplacer = ReplacerFunctionSignature<
+  TypedRegExp<TJsRegexLiteralParts["pattern"]>
+>;
+let m = jsRegex.exec(pcreStyledRegex);
+type Test0 = TJsRegexExecArray extends typeof m ? true : false;
+type Test1 = typeof m extends TJsRegexExecArray ? true : false;
+
+const replacer: TJsRegexStringReplacer = (...args) => "";
+pcreStyledRegex.replace(jsRegex, replacer);
+pcreStyledRegex.replace(jsRegex, "");
+```
+
+---
+
+## 🌍 Global augmentation (opt-in)
+
+This package provides an optional global augmentation entry:
+
+```ts
+import "literate-regex/global";
+```
+
+This is intentionally **opt-in** to avoid unexpected type pollution across projects.
+
+---
+
+## ⚠️ Notes & limitations
+
+* This is **not a full PCRE parser**. It focuses on:
+
+  * line comments (`# ...`)
+  * escaping `\#`
+  * whitespace stripping
+* Very large type-level inputs may still hit TS limits depending on your environment.
+  If that happens, split your regex source into smaller pieces.
+
+---
+
+## 📚 References
+
+This library’s whitespace set is based on the ECMAScript definition used by RegExp `\s`
+(WhiteSpace ∪ LineTerminator).
+
+- ECMA-262: White Space (Table 33)
+  https://tc39.es/ecma262/#sec-white-space
+- ECMA-262: Line Terminators (Table 34)
+  https://tc39.es/ecma262/#sec-line-terminators
+- MDN: RegExp character classes (`\s` equivalence)
+  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions/Character_classes
+
+---
+
+## 📜 License
+
+Released under the `Apache-2.0` License.  
+See [LICENSE](./LICENSE) for details.

package/dist/cjs/index.js

@@ -0,0 +1,41 @@
+"use strict";
+/*!
+// Copyright jeffy-g 2025
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.version = exports.compilePCREStyleRegExpLiteral = exports.extractJsRegexPartsFromPCREStyleRegExpLiteral = exports.normalizePCREStyleSource = void 0;
+const NORMALIZE_PCRE_STYLE_REGEX = /(?<!\\)\#\s*.*$|\s+/gm;
+const normalizePCREStyleSource = (src) => {
+    return src.replace(NORMALIZE_PCRE_STYLE_REGEX, "").replace(/\\#/g, "#");
+};
+exports.normalizePCREStyleSource = normalizePCREStyleSource;
+const extractJsRegexPartsFromPCREStyleRegExpLiteral = (src) => {
+    const normalized = (0, exports.normalizePCREStyleSource)(src);
+    if (normalized[0] !== "/")
+        throw new Error("Expected regex literal to start with '/'");
+    const lastSlash = normalized.lastIndexOf("/");
+    if (lastSlash <= 0)
+        throw new Error("Invalid regex literal: missing trailing '/'");
+    const pattern = normalized.slice(1, lastSlash);
+    const flags = normalized.slice(lastSlash + 1);
+    return { pattern, flags };
+};
+exports.extractJsRegexPartsFromPCREStyleRegExpLiteral = extractJsRegexPartsFromPCREStyleRegExpLiteral;
+const compilePCREStyleRegExpLiteral = (src) => {
+    const { pattern, flags } = (0, exports.extractJsRegexPartsFromPCREStyleRegExpLiteral)(src);
+    return new RegExp(pattern, flags);
+};
+exports.compilePCREStyleRegExpLiteral = compilePCREStyleRegExpLiteral;
+exports.version = "v0.5.0";

package/dist/esm/index.mjs

@@ -0,0 +1,35 @@
+/*!
+// Copyright jeffy-g 2025
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+const NORMALIZE_PCRE_STYLE_REGEX = /(?<!\\)\#\s*.*$|\s+/gm;
+export const normalizePCREStyleSource = (src) => {
+    return src.replace(NORMALIZE_PCRE_STYLE_REGEX, "").replace(/\\#/g, "#");
+};
+export const extractJsRegexPartsFromPCREStyleRegExpLiteral = (src) => {
+    const normalized = normalizePCREStyleSource(src);
+    if (normalized[0] !== "/")
+        throw new Error("Expected regex literal to start with '/'");
+    const lastSlash = normalized.lastIndexOf("/");
+    if (lastSlash <= 0)
+        throw new Error("Invalid regex literal: missing trailing '/'");
+    const pattern = normalized.slice(1, lastSlash);
+    const flags = normalized.slice(lastSlash + 1);
+    return { pattern, flags };
+};
+export const compilePCREStyleRegExpLiteral = (src) => {
+    const { pattern, flags } = extractJsRegexPartsFromPCREStyleRegExpLiteral(src);
+    return new RegExp(pattern, flags);
+};
+export const version = "v0.5.0";

package/dist/global.d.ts

@@ -0,0 +1,67 @@
+/*!
+// Copyright jeffy-g 2025
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+/**
+ * @file literate-regex/global.d.ts
+ */
+import type {
+  TypedRegExp,
+  StringReplacerFunction,
+  RegExpExecArrayFixedPretty,
+} from "./index.d.ts";
+declare global {
+  interface RegExp {
+    /**
+     * Executes a search on a string using a regular expression pattern, and returns an array containing the results of that search.
+     * @template {string} P
+     * @template {string} F
+     * @param {TypedRegExp<P, F>} this The regular expression object.
+     * @param {string} str The String object or string literal on which to perform the search.
+     * @returns {RegExpExecArrayFixedPretty< this > | null} An array of results or null if no match is found.
+     */
+    exec<const P extends string, const F extends string = "">(this: TypedRegExp<P, F>, str: string): RegExpExecArrayFixedPretty< this > | null;
+  }
+  interface String {
+    /**
+     * Replaces occurrences of a pattern in the string with a specified replacement.
+     * @template {RegExp | string} SV
+     * @param searchValue A regular expression object.
+     * @param replaceValue A string or a function to create the new substring.
+     */
+    replace<SV extends RegExp | string>(this: string, searchValue: SV, replaceValue: StringReplacerFunction<SV>): string;
+  }
+  interface RegExpConstructor {
+    /**
+     * Creates a typed RegExp object with literal types for the pattern and flags.
+     * @template {string} P
+     * @template {string} F
+     * @param {P} pattern The regular expression pattern.
+     * @param {F} [flags] The flags for the regular expression.
+     * @returns {TypedRegExp<P, F>} A typed RegExp object.
+     */
+    new <const P extends string, const F extends string = "">(pattern: P, flags?: F): TypedRegExp<P, F>;
+    /**
+     * Creates a typed RegExp object with literal types for the pattern and flags.
+     * @template {string} P
+     * @template {string} F
+     * @param {P} pattern The regular expression pattern.
+     * @param {F} [flags] The flags for the regular expression.
+     * @returns {TypedRegExp<P, F>} A typed RegExp object.
+     */
+    <const P extends string, const F extends string = "">(pattern: P, flags?: F): TypedRegExp<P, F>;
+    readonly prototype: RegExp;
+  }
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/*!
+// Copyright jeffy-g 2025
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+/**
+ * @file literate-regex/index.d.ts
+ * @desc It is recommended to add `"skipLibCheck": true` to your tsconfig.
+ */
+export * from "./types/common";
+export * from "./types/regex";
+export * from "./types/pcre";
+export * from "./types/captures";
+export * from "./types/parser";
+export * from "./types/replacer";
+export as namespace XRegex;

package/dist/types/captures.d.ts

@@ -0,0 +1,192 @@
+/*!
+// Copyright jeffy-g 2025
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+/**
+ * @file types/captures.d.ts
+ */
+import type {
+  TupleOf,
+  IsEmptyRecord,
+} from "./common.d.ts";
+import type { RegExpSource } from "./regex.d.ts";
+import type {
+  RegExpFlags,
+  HasStrictRegExpFlag,
+} from "./regex-util.d.ts";
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//                            Named Capture Groups
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+type FirstChar<S extends string> = S extends `${infer F}${infer _}` ? F : never;
+/**
+ * Recursively extracts parts that match the format (?<GroupName>...) from a string pattern,
+ * without considering nesting, and unions them.
+ * @template S - A string pattern.
+ */
+export type ExtractGroupNames<S extends unknown> =
+  S extends `${infer _Before}(?<${infer Rest}`
+    ? FirstChar<Rest> extends "=" | "!"
+      ? ExtractGroupNames<Rest>
+      : Rest extends `${infer GroupName}>${infer After}`
+        ? GroupName extends ""
+          ? "ExtractGroupNames: regex pattern error!"
+          : GroupName | ExtractGroupNames<After>
+        : never
+    : never;
+/**
+ * Creates an object type with keys as the extracted group names and values as strings.
+ * If no groups are found, it results in an empty object.
+ * @template R - A RegExp type.
+ * @date 2025/12/24 14:46:30 - It may be possible to extract the group name accurately (?)
+ */
+export type RegExpNamedGroups<R extends RegExp> =
+  R extends RegExp & { readonly source: infer S extends string }
+    ? ExtractGroupNames<S> extends infer K
+      ? [K] extends [never]
+        ? undefined
+        : { [P in K & string]: string | undefined }
+      : undefined
+    : undefined;
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//                               Capture Groups
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * Preprocesses escape sequences in a string pattern by replacing escaped backslashes and characters.
+ * 
+ * + NOTE: This type is used to preprocess the pattern string before counting capture groups.
+ * 
+ * @template S - A string pattern.
+ * @template Result - The resulting string after preprocessing. 
+ * @internal
+ */
+export type __PreprocessEscapes<S extends string, Result extends string = ""> =
+  S extends `\\\\${infer Rest}`
+    ? __PreprocessEscapes<Rest, `${Result}__`>
+    : S extends `\\${infer EscapedChar}${infer Rest}`
+      ? __PreprocessEscapes<Rest, `${Result}_!`>
+      : S extends `${infer Char}${infer Rest}`
+        ? __PreprocessEscapes<Rest, `${Result}${Char}`>
+        : Result;
+/**
+ * Counts the exact number of capture groups in a string pattern.
+ * @template S - A string pattern.
+ * @template Counter - An array used to count the capture groups.
+ */
+export type CountCaptureGroups<
+  S extends string,
+  Counter extends unknown[] = []
+> =
+  __PreprocessEscapes<S> extends `${infer _Before}(${infer Rest}`
+    ? Rest extends `${"?:" | "?=" | "?!" | "?<=" | "?<!"}${infer After}`
+      ? CountCaptureGroups<After, Counter>
+      : CountCaptureGroups<Rest, [...Counter, unknown]>
+    : Counter["length"];
+/**
+ * Builds a tuple type whose length equals the number of capture groups.
+ * @template Count - Number of capture groups.
+ * @template Result - Accumulator (internal).
+ */
+export type BuildCaptureTuple<
+  Count extends number, ArrayType = string,
+> = TupleOf<Count, ArrayType>;
+export type CaptureOptTuple<N extends number, T = string | undefined> =
+  N extends 0 ? [] :
+  N extends 1 ? [$1: T] :
+  N extends 2 ? [$1: T, $2: T] :
+  N extends 3 ? [$1: T, $2: T, $3: T] :
+  N extends 4 ? [$1: T, $2: T, $3: T, $4: T] :
+  N extends 5 ? [$1: T, $2: T, $3: T, $4: T, $5: T] :
+  N extends 6 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T] :
+  N extends 7 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T] :
+  N extends 8 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T] :
+  N extends 9 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T] :
+  N extends 10 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T] :
+  N extends 11 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T] :
+  N extends 12 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T, $12: T] :
+  N extends 13 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T, $12: T, $13: T] :
+  N extends 14 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T, $12: T, $13: T, $14: T] :
+  N extends 15 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T, $12: T, $13: T, $14: T, $15: T] :
+  N extends 16 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T, $12: T, $13: T, $14: T, $15: T, $16: T] :
+  BuildCaptureTuple<N, T>;
+/*!
+// - - - - - - - - - - - - - - - - -
+//         Indices (v0.4.0)
+// - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @internal
+ */
+type TIndicesItem = [index: number, lastIndex: number];
+/**
+ * @internal
+ */
+type RegExpIndicesGroups<NamedGroups> = IsEmptyRecord<NamedGroups> extends true
+  ? undefined
+  : { [P in keyof NamedGroups & string]: TIndicesItem | undefined };
+/**
+ * @internal
+ */
+type RegExpIndicesTuple<GroupCount extends number> = [
+  match: TIndicesItem,
+  ...BuildCaptureTuple<GroupCount, TIndicesItem | undefined>
+];
+/**
+ * 
+ */
+export type RegExpIndicesArray<GroupCount extends number, NamedGroups> = RegExpIndicesTuple<GroupCount> & {
+  groups: RegExpIndicesGroups<NamedGroups>;
+};
+/**
+ * @internal
+ */
+type RegExpExecArrayFixedBase<
+  R extends RegExp,
+  GroupCount extends number,
+  NamedGroups,
+  Tuple extends unknown[] = BuildCaptureTuple<GroupCount, string | undefined>
+> = HasStrictRegExpFlag<RegExpFlags<R>, "d"> extends true
+  ? [match: string, ...Tuple] & {
+  groups: IsEmptyRecord<NamedGroups> extends true ? undefined : NamedGroups;
+  index: number;
+  input: string;
+  indices: RegExpIndicesArray<GroupCount, NamedGroups>
+} : [match: string, ...Tuple] & {
+  groups: IsEmptyRecord<NamedGroups> extends true ? undefined : NamedGroups;
+  index: number;
+  input: string;
+}
+/**
+ * Represents a fixed version of RegExpExecArray that includes the matched string,
+ * captures, and optionally named groups.
+ * @template R - A RegExp type.
+ * @template S - The source string of the RegExp.
+ * @template GroupCount - The number of capture groups.
+ */
+export type RegExpExecArrayFixed<
+  R extends RegExp,
+  S extends RegExpSource<R> = RegExpSource<R>,
+  GroupCount extends number = CountCaptureGroups<S>,
+  NamedGroups = RegExpNamedGroups<R>
+> = RegExpExecArrayFixedBase<R, GroupCount, NamedGroups>;
+export type RegExpExecArrayFixedPretty<
+  R extends RegExp,
+  S extends RegExpSource<R> = RegExpSource<R>,
+  GroupCount extends number = CountCaptureGroups<S>,
+  NamedGroups = RegExpNamedGroups<R>
+> = RegExpExecArrayFixedBase<R, GroupCount, NamedGroups, CaptureOptTuple<GroupCount>>;
+export {};

package/dist/types/common.d.ts

@@ -0,0 +1,56 @@
+/*!
+// Copyright jeffy-g 2025
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+/**
+ * @file types/common.d.ts
+ */
+export type TupleOf<
+  Count extends number, ArrayType,
+  Result extends ArrayType[] = []
+> = Result["length"] extends Count
+  ? Result
+  : TupleOf<Count, ArrayType, [...Result, ArrayType]>;
+export type IsEmptyRecord<T> =
+  [T] extends [undefined] ? true :
+  [keyof T] extends [never] ? true : false;
+/**
+ * StringToUnion<"abc"> -> "a" | "b" | "c"
+ * StringToUnion<string> -> string
+ *
+ * Note: splits by UTF-16 code units (like JS `.split("")`).
+ */
+export type StringToUnion<S extends string> =
+  [string] extends [S]
+    ? string
+    : S extends `${infer H}${infer T}`
+      ? H | StringToUnion<T>
+      : never;
+/**
+ * StringLength<S> -> length as a number literal, or `number` if S is not a literal.
+ *
+ * - StringLength<"">            -> 0
+ * - StringLength<"abc">         -> 3
+ * - StringLength<string>        -> number
+ * - StringLength<`a${string}`>  -> number
+ *
+ * Note: counts UTF-16 code units (like JS `.length`).
+ */
+export type StringLength<S extends string, Acc extends unknown[] = []> =
+  [string] extends [S]
+    ? number
+    : S extends `${infer _H}${infer T}`
+      ? StringLength<T, [unknown, ...Acc]>
+      : Acc["length"];
+export {};

package/dist/types/parser.d.ts

@@ -0,0 +1,54 @@
+/*!
+// Copyright jeffy-g 2025
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+/**
+ * @file types/parser.d.ts
+ */
+import type { StringToUnion } from "./common.d.ts";
+import type { TypedRegExp } from "./regex.d.ts";
+import type { PCREStyleToJsRegExpSource } from "./pcre.d.ts";
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//                    Parse PCRE Style Regex Literal
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+export type TRegexpFlag = "dgimsuvy";
+export type TValidRegExpFlag = StringToUnion<TRegexpFlag> | "";
+type StripFlagsFromEnd<S extends string, Acc extends string = ""> =
+  S extends `${infer Rest}y` ? StripFlagsFromEnd<Rest, `y${Acc}`> :
+  S extends `${infer Rest}v` ? StripFlagsFromEnd<Rest, `v${Acc}`> :
+  S extends `${infer Rest}u` ? StripFlagsFromEnd<Rest, `u${Acc}`> :
+  S extends `${infer Rest}s` ? StripFlagsFromEnd<Rest, `s${Acc}`> :
+  S extends `${infer Rest}m` ? StripFlagsFromEnd<Rest, `m${Acc}`> :
+  S extends `${infer Rest}i` ? StripFlagsFromEnd<Rest, `i${Acc}`> :
+  S extends `${infer Rest}g` ? StripFlagsFromEnd<Rest, `g${Acc}`> :
+  S extends `${infer Rest}d` ? StripFlagsFromEnd<Rest, `d${Acc}`> : { body: S; flags: Acc };
+export type RegExpLiteralParts<L extends string> =
+  StripFlagsFromEnd<L> extends { body: infer B extends string; flags: infer F extends string }
+    ? B extends `/${infer AfterStart}`
+      ? AfterStart extends `${infer Pattern}/`
+        ? { pattern: Pattern; flags: F }
+        : never
+      : never
+    : never;
+export type PCREStyleRegExpParts<S extends string> = RegExpLiteralParts<PCREStyleToJsRegExpSource<S>>;
+export type PCREStyleRegExpPattern<S extends string> = PCREStyleRegExpParts<S>["pattern"];
+export type PCREStyleRegExpFlags<S extends string> = PCREStyleRegExpParts<S>["flags"];
+export declare const extractJsRegexPartsFromPCREStyleRegExpLiteral: <const S extends string>(src: S) => PCREStyleRegExpParts<S>;
+export declare const compilePCREStyleRegExpLiteral: <
+  const S extends string,
+  const This = TypedRegExp<PCREStyleRegExpPattern<S>, PCREStyleRegExpFlags<S>>
+>(src: S) => This;
+export {};

package/dist/types/pcre.d.ts

@@ -0,0 +1,160 @@
+/*!
+// Copyright jeffy-g 2025
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+/**
+ * @file types/pcre.d.ts
+ */
+/*! [2025/12/31 13:01:03]
+ * ## Support PCRE-style regex source (type-level)
+ *
+ * @remarks
+ * This module provides **type-level normalization** for "PCRE-ish" regex sources:
+ * you can write a readable multi-line regex with indentation and `# ...` comments,
+ * then derive a compact JavaScript `RegExp` source at compile time.
+ *
+ * Why type-level? Because it lets us:
+ * - keep the regex readable in source code (with comments and formatting)
+ * - ensure the normalized output is stable and verifiable (via type assertions)
+ *
+ * ## Supported rules
+ * - `#` starts a comment and consumes the rest of the **current line**
+ * - `\#` escapes `#` as a literal (comment is NOT started) and normalizes to `#`
+ * - whitespace characters are removed during normalization
+ * - newlines are normalized: `\r\n` and `\r` become `\n`
+ *
+ * ## Design note (ts(2589) survival)
+ * Naively scanning the entire string character-by-character (multiple passes)
+ * can hit TypeScript's instantiation depth limit (`ts(2589)`).
+ * This implementation is **line-oriented**:
+ * it strips each line, then concatenates results.
+ * That tends to scale much better for long, commented regex sources.
+ *
+ * ## Non-goals (for now)
+ * This is not a full PCRE parser. It intentionally focuses on comment + whitespace
+ * normalization for readability and DX.
+ */
+/**
+ * Union of whitespace characters used by this library.
+ * 
+ * + A set aligned with ECMAScript RegExp **`\s`** (WhiteSpace ∪ LineTerminator)
+ * 
+ * The union is used to normalize "PCRE-style" regex sources at the type level.
+ * @internal
+ */
+type TWhiteSpace =
+  | "\x09"
+  | "\x0A"
+  | "\x0B"
+  | "\x0C"
+  | "\x0D"
+  | "\x20"
+  | "\u00A0"
+  | "\u1680"
+  | "\u2000"
+  | "\u2001"
+  | "\u2002"
+  | "\u2003"
+  | "\u2004"
+  | "\u2005"
+  | "\u2006"
+  | "\u2007"
+  | "\u2008"
+  | "\u2009"
+  | "\u200A"
+  | "\u2028" | "\u2029"
+  | "\u202F" | "\u205F" | "\u3000"
+  | "\uFEFF";
+/**
+ * Normalize newline sequences for line-based parsing.
+ * 
+ * + Align **`\r\n`** and **`\r`** to **`\n`** (makes splitting easier)
+ *
+ * @template S - Input string literal.
+ * @returns A new string literal with `\r\n` and `\r` normalized to `\n`.
+ * @internal
+ *
+ * @example
+ * type X = NormalizeNewlines<"a\r\nb\rc\n">; // "a\nb\nc\n"
+ */
+type NormalizeNewlines<S extends string> =
+  S extends `${infer A}\r\n${infer B}` ? NormalizeNewlines<`${A}\n${B}`> :
+  S extends `${infer A}\r${infer B}` ? NormalizeNewlines<`${A}\n${B}`> :
+  S;
+/**
+ * Strip and normalize a single line of a PCRE-style regex source.
+ *
+ * @remarks
+ * Rules:
+ * - `\#` is treated as a literal `#` (the backslash is dropped)
+ * - an unescaped `#` starts a line comment and truncates the rest
+ * - all whitespace characters are removed
+ * - other escapes like `\s`, `\w`, `\/`, `\*` are preserved as-is
+ *
+ * @template S - One line of source (no `\n`).
+ * @template Acc - Accumulator for the normalized output.
+ *
+ * @example
+ * type A = StripLine<"  \\#\\w+   # comment  ">; // "#\\w+"
+ * type B = StripLine<"  abc  # comment">;        // "abc"
+ *
+ * @internal
+ *
+ * @todo
+ * - Handle `\\#` (a literal backslash + literal #) more strictly.
+ * - Do not treat `#` as a comment starter inside character classes (`[...]`).
+ */
+type StripLine<S extends string, Acc extends string = ""> =
+  S extends `\\#${infer Rest}`
+    ? StripLine<Rest, `${Acc}#`>
+    : S extends `\\${infer C}${infer Rest}`
+      ? StripLine<Rest, `${Acc}\\${C}`>
+      : S extends `#${string}`
+        ? Acc
+        : S extends `${infer C}${infer Rest}`
+          ? C extends TWhiteSpace
+            ? StripLine<Rest, Acc>
+            : StripLine<Rest, `${Acc}${C}`>
+          : Acc;
+/**
+ * Convert a multi-line PCRE-style regex source into a compact JS `RegExp.source`.
+ *
+ * @remarks
+ * This type:
+ * 1) normalizes newlines, 2) splits by line, 3) applies {@link StripLine},
+ * then 4) concatenates the results.
+ *
+ * @template Input - A `const` string literal of the PCRE-ish source.
+ * @template Acc - Accumulator for the result.
+ * @template S - Internal normalized newline buffer (do not pass manually).
+ *
+ * @example
+ * const RE_SOURCE = `
+ * ^              # start
+ * (?:\\#\\w+)     # keep literal "#"
+ * ` as const;
+ *
+ * type Src = PCREStyleToJsRegExpSource<typeof RE_SOURCE>;
+ * // "^(:?##\\w+)" ... (depending on your actual input)
+ */
+export type PCREStyleToJsRegExpSource<
+  Input extends string,
+  Acc extends string = "",
+  S extends string = NormalizeNewlines<Input>,
+> =
+  S extends `${infer Line}\n${infer Rest}`
+    ? PCREStyleToJsRegExpSource<Input, `${Acc}${StripLine<Line>}`, Rest>
+    : `${Acc}${StripLine<S>}`;
+export declare const normalizePCREStyleSource: <const S extends string>(src: S) => PCREStyleToJsRegExpSource<S>;
+export {};

package/dist/types/regex-util.d.ts

@@ -0,0 +1,81 @@
+/*!
+// Copyright jeffy-g 2026
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+/**
+ * @file types/regex-util.d.ts
+ */
+import type {
+  StringLength,
+  StringToUnion,
+} from "./common.d.ts";
+import type {
+  TRegexpFlag,
+  TValidRegExpFlag,
+} from "./parser.d.ts";
+/**
+ * @internal
+ */
+type ExceedsMaxRegExpFlagCount<N extends number> =
+  number extends N ? boolean :  N extends 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 ? false : true;
+/**
+ * @internal
+ */
+type IsUniqueChars<S extends string, Seen extends string = never> =
+  S extends `${infer H}${infer T}`
+    ? H extends Seen ? false : IsUniqueChars<T, Seen | H>
+    : true;
+/**
+ * @internal
+ */
+type NormalizeFlags<
+  F extends string, Order extends string = TRegexpFlag, Out extends string = "",
+> = Order extends `${infer C}${infer Rest}`
+  ? NormalizeFlags<
+    F, Rest, F extends `${string}${C}${string}` ? `${Out}${C}` : Out
+  > : Out;
+export type CanonicalFlags<F extends string> =
+  [string] extends [F] ? string :
+  Exclude<StringToUnion<F>, TValidRegExpFlag> extends never
+    ? IsUniqueChars<F> extends true
+      ? ExceedsMaxRegExpFlagCount<StringLength<F>> extends true
+        ? never
+        : NormalizeFlags<F>
+      : never
+    : never;
+export type IsStrictFlags<F extends string> =
+  CanonicalFlags<F> extends never ? false : true;
+type ValidateFlags<F extends string, Seen extends string = ""> =
+  F extends ""
+    ? true
+    : IsStrictFlags<F> extends false
+    ? false
+    : F extends `${infer C}${infer Rest}`
+      ? C extends TValidRegExpFlag
+        ? C extends Seen
+          ? false
+          : ValidateFlags<Rest, `${Seen}${C}`>
+        : false
+      : false;
+export type RegExpFlags<R extends RegExp> =
+  R extends RegExp & { readonly flags: infer F extends string }
+    ? ValidateFlags<F> extends true
+      ? F : string
+    : string;
+/**
+ * @internal
+ */
+export type HasStrictRegExpFlag<F extends string, C extends TValidRegExpFlag> =
+  ValidateFlags<F> extends true ? F extends `${string}${C}${string}` ? true : false : false;
+export {};

package/dist/types/regex.d.ts

@@ -0,0 +1,76 @@
+/*!
+// Copyright jeffy-g 2025
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+/**
+ * @file types/regex.d.ts
+ */
+import type {
+  CountCaptureGroups,
+  RegExpNamedGroups,
+  RegExpIndicesArray,
+  RegExpExecArrayFixedPretty,
+} from "./captures.d.ts";
+import type { RegExpFlags, HasStrictRegExpFlag } from "./regex-util.d.ts";
+import type { StringReplacerFunction } from "./replacer.d.ts";
+declare const __typedRegExpBrand: unique symbol;
+/**
+ * DO NOT USE CONSUMER
+ * @internal
+ */
+type TypedRegExpBrand = { readonly [__typedRegExpBrand]: true };
+/**
+ * + v0.3.0 feature
+ * 
+ * @since v0.3.0
+ */
+export type TypedRegExpTypes<
+  R extends RegExp,
+  S extends RegExpSource<R> = RegExpSource<R>,
+  NamedGroups = RegExpNamedGroups<R>,
+  GroupCount extends number = CountCaptureGroups<S>,
+  IsTypedRegExp = R extends TypedRegExpBrand ? true : false,
+  GROUPS = true extends IsTypedRegExp ? NamedGroups : never,
+  EXEC = true extends IsTypedRegExp ? RegExpExecArrayFixedPretty<R, S, GroupCount, NamedGroups> : never,
+  REPLACER = true extends IsTypedRegExp ? StringReplacerFunction<R> : never,
+  INDICES = true extends IsTypedRegExp ? RegExpIndicesArray<GroupCount, NamedGroups> : never,
+> = true extends IsTypedRegExp ? {
+  groups: GROUPS;
+  exec: EXEC;
+  replacer: REPLACER;
+  indices: HasStrictRegExpFlag<RegExpFlags<R>, "d"> extends true ? INDICES : never;
+} : never;
+/**
+ * @since 2025/12/24 12:27:39
+ * @commit js-dev-tool@6ff89180acfb53c1a0bf9aebadfa12b210bfb3f8
+ */
+export type TypedRegExp<P extends string, F extends string = ""> = RegExp & {
+  readonly source: P;
+  readonly flags: F;
+} & TypedRegExpBrand & {
+  types: TypedRegExpTypes<TypedRegExp<P, F>>;
+};
+/**
+ * Extracts the literal type from the source property of a RegExp.
+ * @template R - A RegExp type.
+ */
+export type RegExpSource<R extends RegExp> = R extends RegExp & { readonly source: infer T } ? T : never;
+/**
+ * @deprecated description
+ */
+export declare function createRegExp<
+  const P extends string,
+  const F extends string = ""
+>(pattern: P, flags?: F): TypedRegExp<P, F>;
+export {};

package/dist/types/replacer.d.ts

@@ -0,0 +1,60 @@
+/*!
+// Copyright jeffy-g 2025
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+*/
+/**
+ * @file types/replacer.d.ts
+ */
+import type {
+  TypedRegExp,
+  RegExpSource,
+} from "./regex.d.ts";
+import type { IsEmptyRecord } from "./common.d.ts";
+import type { CountCaptureGroups, RegExpNamedGroups, CaptureOptTuple } from "./captures.d.ts";
+/*!
+// ============================================================================
+//                          Helper Types for Replacer
+// ============================================================================
+*/
+/**
+ * Creates the parameter types for String.replace callback function.
+ * 
+ * @example
+ * type Params = StringReplacerParams<typeof myRegex>;
+ * // [match: string, ...captures: string[], offset: number, string: string, groups?: {...}]
+ */
+export type StringReplacerParams<
+  R extends RegExp,
+  S extends RegExpSource<R> = RegExpSource<R>,
+  GroupCount extends number = CountCaptureGroups<S>,
+  NamedGroups = RegExpNamedGroups<R>
+> = IsEmptyRecord<NamedGroups> extends true ? [
+  match: string,
+  ...captures: CaptureOptTuple<GroupCount>,
+  offset: number,
+  input: string,
+] : [
+  match: string,
+  ...captures: CaptureOptTuple<GroupCount>,
+  offset: number,
+  input: string,
+  groups: NamedGroups
+];
+export type StringReplacerFunction<R> =
+  R extends TypedRegExp<infer P extends string, infer F extends string>
+    ? (...args: StringReplacerParams<TypedRegExp<P, F>, P>) => string
+    : R extends RegExp
+      ? (match: string, ...rest: any[]) => string
+      : string;
+export {};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "literate-regex",
+  "version": "0.5.1",
+  "description": "Write readable (literate) regex sources with # comments, then normalize them to JS RegExp.source at the type level.",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.js"
+    },
+    "./global": {
+      "types": "./dist/global.d.ts"
+    }
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist"
+  ],
+  "keywords": [
+    "regex",
+    "regexp",
+    "literate",
+    "types",
+    "typescript",
+    "pcre",
+    "jsdoc"
+  ]
+}