literate-regex 0.6.2 → 0.6.9

package/dist/cjs/index.js

@@ -38,4 +38,4 @@ const compilePCREStyleRegExpLiteral = (src) => {
     return new RegExp(pattern, flags);
 };
 exports.compilePCREStyleRegExpLiteral = compilePCREStyleRegExpLiteral;
-exports.version = "v0.6.2";
+exports.version = "v0.6.9";

package/dist/esm/index.mjs

@@ -32,4 +32,4 @@ export const compilePCREStyleRegExpLiteral = (src) => {
     const { pattern, flags } = extractJsRegexPartsFromPCREStyleRegExpLiteral(src);
     return new RegExp(pattern, flags);
 };
-export const version = "v0.6.2";
+export const version = "v0.6.9";

package/dist/global.d.ts

@@ -18,6 +18,7 @@
  */
 import type {
   TypedRegExp,
+  TypedRegExpCore,
   StringReplacerType,
   RegExpExecArrayFixedPretty,
 } from "./index.d.ts";
@@ -31,7 +32,7 @@ declare global {
      * @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 extends RegExp = TypedRegExp<P, F>>(this: This, str: string): RegExpExecArrayFixedPretty< This > | null;
+    exec<const P extends string, const F extends string = "", This extends RegExp = TypedRegExpCore<P, F>>(this: This, str: string): RegExpExecArrayFixedPretty< This > | null;
   }
   interface String {
     /**
@@ -40,7 +41,7 @@ declare global {
      * @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: StringReplacerType<SV>): string;
+    replace<SV extends RegExp>(this: string, searchValue: SV, replaceValue: StringReplacerType<SV>): string;
   }
   interface RegExpConstructor {
     /**

package/dist/index.d.ts

@@ -19,6 +19,7 @@
  */
 export * from "./types/common";
 export * from "./types/regex";
+export * from "./types/regex-util";
 export * from "./types/pcre";
 export * from "./types/captures";
 export * from "./types/parser";

package/dist/types/captures.d.ts

@@ -20,9 +20,9 @@ import type {
   TupleOf,
   IsEmptyRecord,
 } from "./common.d.ts";
-import type { RegExpSource } from "./regex.d.ts";
 import type {
   RegExpFlags,
+  RegExpSource,
   HasStrictRegExpFlag,
 } from "./regex-util.d.ts";
 /*!
@@ -30,7 +30,10 @@ import type {
 //                            Named Capture Groups
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
-type FirstChar<S extends string> = S extends `${infer F}${infer _}` ? F : never;
+/**
+ * @internal
+ */
+export 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.
@@ -131,17 +134,17 @@ export type CaptureOptTuple<N extends number, T = string | undefined> =
 /**
  * @internal
  */
-type TIndicesItem = [index: number, lastIndex: number];
+export type TIndicesItem = [index: number, lastIndex: number];
 /**
  * @internal
  */
-type RegExpIndicesGroups<NamedGroups> = IsEmptyRecord<NamedGroups> extends true
+export type RegExpIndicesGroups<NamedGroups> = IsEmptyRecord<NamedGroups> extends true
   ? undefined
   : { [P in keyof NamedGroups & string]: TIndicesItem | undefined };
 /**
  * @internal
  */
-type RegExpIndicesTuple<GroupCount extends number> = [
+export type RegExpIndicesTuple<GroupCount extends number> = [
   match: TIndicesItem,
   ...BuildCaptureTuple<GroupCount, TIndicesItem | undefined>
 ];
@@ -183,6 +186,11 @@ export type RegExpExecArrayFixed<
   GroupCount extends number = CountCaptureGroups<S>,
   NamedGroups = RegExpNamedGroups<R>
 > = RegExpExecArrayFixedBase<R, GroupCount, NamedGroups>;
+/**
+ * Represents a fixed version of RegExpExecArray that includes the matched string,  
+ * captures (with named parameters for better readability), and optionally named groups.
+ * @template R - A RegExp type.
+ */
 export type RegExpExecArrayFixedPretty<
   R extends RegExp,
   S extends RegExpSource<R> = RegExpSource<R>,

package/dist/types/common.d.ts

@@ -16,12 +16,34 @@
 /**
  * @file types/common.d.ts
  */
+/**
+ * Combines an intersection of object types into a single object type.
+ * 
+ * @template IS The intersection of object types to combine.
+ * @returns {Record<string, unknown>} A single object type with all properties from the intersection.
+ * 
+ * @example
+ * type Combined = CombineIntersection<{ a: string } & { b: number }>;
+ * // Result: { a: string; b: number }
+ */
+export type CombineIntersection<IS> =
+  true extends 0 ? { [K in keyof IS]: IS[K] } : { [K in keyof IS]: IS[K] };
+/**
+ * Creates a tuple type of a specified length, with all elements being of a given type.
+ * @template Count - The desired length of the tuple.
+ * @template ArrayType - The type of each element in the tuple.
+ */
 export type TupleOf<
   Count extends number, ArrayType,
   Result extends ArrayType[] = []
 > = Result["length"] extends Count
   ? Result
   : TupleOf<Count, ArrayType, [...Result, ArrayType]>;
+/**
+ * Checks if a given type `T` represents an empty record or `undefined`.
+ * @template T - The type to check.
+ * @returns `true` if `T` is `undefined` or has no keys, otherwise `false`.
+ */
 export type IsEmptyRecord<T> =
   [T] extends [undefined] ? true :
   [keyof T] extends [never] ? true : false;

package/dist/types/parser.d.ts

@@ -24,9 +24,25 @@ import type { PCREStyleToJsRegExpSource } from "./pcre.d.ts";
 //                    Parse PCRE Style Regex Literal
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
+/**
+ * Represents the complete set of valid JavaScript regular expression flags.  
+ * This type is a string literal containing all possible flags: `d`, `g`, `i`, `m`, `s`, `u`, `v`, `y`.
+ */
 export type TRegexpFlag = "dgimsuvy";
+/**
+ * Represents a union of individual valid JavaScript regular expression flags,  
+ * including an empty string for cases where no flag is present.
+ */
 export type TValidRegExpFlag = StringToUnion<TRegexpFlag> | "";
-type StripFlagsFromEnd<S extends string, Acc extends string = ""> =
+/** 
+ * Recursively strips valid RegExp flags from the end of a string literal. 
+ * This type is designed to avoid TypeScript's backtracking limitations by processing one character at a time. 
+ * 
+ * @template S - The input string literal from which to strip flags. 
+ * @template Acc - An accumulator for the stripped flags, built in reverse order. 
+ * @internal
+ */
+export 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}`> :
@@ -35,6 +51,12 @@ type StripFlagsFromEnd<S extends string, Acc extends string = ""> =
   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 };
+/** 
+ * Extracts the pattern and flags from a JavaScript-style regular expression literal string (e.g., `/pattern/flags`). 
+ * 
+ * @template L - The RegExp literal string. 
+ * @returns An object type with `pattern` and `flags` properties. 
+ */
 export type RegExpLiteralParts<L extends string> =
   StripFlagsFromEnd<L> extends { body: infer B extends string; flags: infer F extends string }
     ? B extends `/${infer AfterStart}`
@@ -43,9 +65,32 @@ export type RegExpLiteralParts<L extends string> =
         : never
       : never
     : never;
+/** 
+ * Extracts the pattern and flags from a PCRE-style regular expression literal string, 
+ * after it has been normalized to a JavaScript-style literal. 
+ * 
+ * @template S - The PCRE-style RegExp literal string. 
+ * @returns An object type with `pattern` and `flags` properties. 
+ */
 export type PCREStyleRegExpParts<S extends string> = RegExpLiteralParts<PCREStyleToJsRegExpSource<S>>;
+/** 
+ * Extracts the pattern string from a PCRE-style regular expression literal. 
+ * 
+ * @template S - The PCRE-style RegExp literal string. 
+ */
 export type PCREStyleRegExpPattern<S extends string> = PCREStyleRegExpParts<S>["pattern"];
+/** 
+ * Extracts the flags string from a PCRE-style regular expression literal. 
+ * 
+ * @template S - The PCRE-style RegExp literal string. 
+ */
 export type PCREStyleRegExpFlags<S extends string> = PCREStyleRegExpParts<S>["flags"];
+/** 
+ * Extracts the pattern and flags from a PCRE-style regular expression literal string at runtime. 
+ * 
+ * @template S - The PCRE-style RegExp literal string. 
+ * @param src - The PCRE-style regular expression literal string. 
+ */
 export declare const extractJsRegexPartsFromPCREStyleRegExpLiteral: <const S extends string>(src: S) => PCREStyleRegExpParts<S>;
 export declare const compilePCREStyleRegExpLiteral: <
   const S extends string,

package/dist/types/pcre.d.ts

@@ -48,12 +48,13 @@
 /**
  * Union of whitespace characters used by this library.
  * 
- * + A set aligned with ECMAScript RegExp **`\s`** (WhiteSpace ∪ LineTerminator)
+ * + 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 =
+export type TWhiteSpace =
   | "\x09"
   | "\x0A"
   | "\x0B"
@@ -76,6 +77,18 @@ type TWhiteSpace =
   | "\u2028" | "\u2029"
   | "\u202F" | "\u205F" | "\u3000"
   | "\uFEFF";
+/**
+ * A looser definition of whitespace characters compared to {@link TWhiteSpace}.  
+ * This type is used internally for certain normalization processes where a more restricted set of whitespace is considered.
+ * @internal
+ */
+export type TWhiteSpaceLoose =
+  | "\x09"
+  | "\x0A"
+  | "\x0B"
+  | "\x0C"
+  | "\x0D"
+  | "\x20"
 /**
  * Normalize newline sequences for line-based parsing.
  * 
@@ -115,17 +128,17 @@ type NormalizeNewlines<S extends string> =
  * - 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 = ""> =
+type StripLine<S extends string, WS extends TWhiteSpace = TWhiteSpace, Acc extends string = ""> =
   S extends `\\#${infer Rest}`
-    ? StripLine<Rest, `${Acc}#`>
+    ? StripLine<Rest, WS, `${Acc}#`>
     : S extends `\\${infer C}${infer Rest}`
-      ? StripLine<Rest, `${Acc}\\${C}`>
+      ? StripLine<Rest, WS, `${Acc}\\${C}`>
       : S extends `#${string}`
         ? Acc
         : S extends `${infer C}${infer Rest}`
-          ? C extends TWhiteSpace
-            ? StripLine<Rest, Acc>
-            : StripLine<Rest, `${Acc}${C}`>
+          ? C extends WS
+            ? StripLine<Rest, WS, Acc>
+            : StripLine<Rest, WS, `${Acc}${C}`>
           : Acc;
 /**
  * Convert a multi-line PCRE-style regex source into a compact JS `RegExp.source`.
@@ -150,11 +163,18 @@ type StripLine<S extends string, Acc extends string = ""> =
  */
 export type PCREStyleToJsRegExpSource<
   Input extends string,
+  WS extends string = TWhiteSpace,
   Acc extends string = "",
   S extends string = NormalizeNewlines<Input>,
 > =
   S extends `${infer Line}\n${infer Rest}`
-    ? PCREStyleToJsRegExpSource<Input, `${Acc}${StripLine<Line>}`, Rest>
+    ? PCREStyleToJsRegExpSource<Input, WS, `${Acc}${StripLine<Line>}`, Rest>
     : `${Acc}${StripLine<S>}`;
+/**
+ * Normalizes a PCRE-style regular expression source string by removing comments and whitespace.  
+ * This function is intended for use at runtime.
+ *
+ * @param src The PCRE-style regular expression source string.
+ */
 export declare const normalizePCREStyleSource: <const S extends string>(src: S) => PCREStyleToJsRegExpSource<S>;
 export {};

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

@@ -17,26 +17,49 @@
  * @file types/regex-util.d.ts
  */
 import type {
-  StringLength,
-  StringToUnion,
+  StringLength, StringToUnion
 } from "./common.d.ts";
 import type {
-  TRegexpFlag,
-  TValidRegExpFlag,
+  TRegexpFlag, TValidRegExpFlag
 } from "./parser.d.ts";
+/**
+ * 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;
+/**
+ * Extracts the literal type from the flags property of a RegExp.
+ * @template R - A RegExp type.
+ */
+export type RegExpFlags<R extends RegExp> =
+  R extends RegExp & { readonly flags: infer F extends string }
+    ? ValidateFlags<F> extends true
+      ? F : string
+    : string;
 /**
  * @internal
  */
 type ExceedsMaxRegExpFlagCount<N extends number> =
   number extends N ? boolean :  N extends 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 ? false : true;
-/**
- * @internal
+/** 
+ * Checks if all characters in a string `S` are unique. 
+ * 
+ * @template S - The input string. 
+ * @template Seen - An accumulator for characters encountered so far. 
+ * @returns `true` if all characters in `S` are unique, `false` otherwise. 
+ * @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;
 /**
+ * Normalizes a string of RegExp flags by sorting them into a predefined order (`dgimsuvy`).  
+ * This type is used internally after flags have been validated for uniqueness and allowed characters.
+ *
+ * @template F - The input string of flags to normalize.
+ * @template Order - The desired order of flags (defaults to `TRegexpFlag`).
+ * @template Out - An accumulator for the normalized flags.
  * @internal
  */
 type NormalizeFlags<
@@ -45,6 +68,12 @@ type NormalizeFlags<
   ? NormalizeFlags<
     F, Rest, F extends `${string}${C}${string}` ? `${Out}${C}` : Out
   > : Out;
+/**
+ * Canonicalizes a string of RegExp flags by validating them, removing duplicates,  
+ * and sorting them into a predefined order (`dgimsuvy`).
+ *
+ * @template F - The input string of flags.
+ */
 export type CanonicalFlags<F extends string> =
   [string] extends [F] ? string :
   Exclude<StringToUnion<F>, TValidRegExpFlag> extends never
@@ -54,26 +83,43 @@ export type CanonicalFlags<F extends string> =
         : NormalizeFlags<F>
       : never
     : never;
+/**
+ * Checks if a string of RegExp flags is "strict", meaning it contains only valid, unique, and non-excessive flags.
+ *
+ * @template F - The input string of flags.
+ * @returns `true` if the flags are strict, `false` otherwise.
+ * @internal
+ */
 export type IsStrictFlags<F extends string> =
   CanonicalFlags<F> extends never ? false : true;
-type ValidateFlags<F extends string, Seen extends string = ""> =
+/**
+ * Validates a string of RegExp flags for correctness, including uniqueness and allowed characters.  
+ * This type performs a strict validation, ensuring that each flag is valid and appears only once.
+ *
+ * @template F - The input string of flags to validate.
+ * @template Seen - An accumulator for flags encountered so far (used internally to check for duplicates).
+ * @returns `true` if the flags are valid and unique, `false` otherwise.
+ * @internal
+ */
+export 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
+    : F extends `${infer OneCh}${infer Rest}`
+      ? OneCh extends TValidRegExpFlag
+        ? OneCh extends Seen
           ? false
-          : ValidateFlags<Rest, `${Seen}${C}`>
+          : ValidateFlags<Rest, `${Seen}${OneCh}`>
         : false
       : false;
-export type RegExpFlags<R extends RegExp> =
-  R extends RegExp & { readonly flags: infer F extends string }
-    ? ValidateFlags<F> extends true
-      ? F : string
-    : string;
 /**
+ * Checks if a given RegExp flag string `F` contains a specific flag character `C`.  
+ * This type performs a strict validation of `F` first.
+ *
+ * @template F - The input string of RegExp flags.
+ * @template C - The specific flag character to check for (e.g., `"g"`, `"i"`).
+ * @returns `true` if `F` is valid and contains `C`, `false` otherwise.
  * @internal
  */
 export type HasStrictRegExpFlag<F extends string, C extends TValidRegExpFlag> =

package/dist/types/regex.d.ts

@@ -16,50 +16,57 @@
 /**
  * @file types/regex.d.ts
  */
+import type { CombineIntersection } from "./common.d.ts";
 import type {
   CountCaptureGroups,
   RegExpNamedGroups,
   RegExpIndicesArray,
   RegExpExecArrayFixedPretty,
 } from "./captures.d.ts";
-import type { RegExpFlags, HasStrictRegExpFlag } from "./regex-util.d.ts";
-import type { StringReplacerType } from "./replacer.d.ts";
+import type {
+  RegExpFlags, RegExpSource,　HasStrictRegExpFlag
+} from "./regex-util.d.ts";
+import type {
+  StringReplacerParams,
+} from "./replacer.d.ts";
 declare const __typedRegExpBrand: unique symbol;
 /**
  * DO NOT USE CONSUMER
  * @internal
  */
-type TypedRegExpBrand = { readonly [__typedRegExpBrand]: true };
+export type TypedRegExpBrand = { readonly [__typedRegExpBrand]: true };
 /**
  * + v0.3.0 feature
+ *
+ * Represents the detailed type information extracted from a `TypedRegExp` instance.  
+ * This includes types for named capture groups, `exec` method results,  
+ * `replace` method replacer functions, and `indices` array (if the 'd' flag is present).
  * 
  * @since v0.3.0
  */
 export type TypedRegExpTypes<
   R extends RegExp,
-  S extends RegExpSource<R> = RegExpSource<R>,
+  SOURCE extends RegExpSource<R> = RegExpSource<R>,
+  FLAGS extends RegExpFlags<R> = RegExpFlags<R>,
   NamedGroups = RegExpNamedGroups<R>,
-  GroupCount extends number = CountCaptureGroups<S>,
+  GroupCount extends number = CountCaptureGroups<SOURCE>,
   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 ? StringReplacerType<R> : never,
+  EXEC = true extends IsTypedRegExp ? RegExpExecArrayFixedPretty<R, SOURCE, GroupCount, NamedGroups> : never,
+  REPLACER = true extends IsTypedRegExp ? (...args: StringReplacerParams<TypedRegExpCore<SOURCE, FLAGS>>) => string : never,
   INDICES = true extends IsTypedRegExp ? RegExpIndicesArray<GroupCount, NamedGroups> : never,
 > = true extends IsTypedRegExp ? {
   groups: GROUPS;
   exec: EXEC | null;
   replacer: REPLACER;
-  indices: HasStrictRegExpFlag<RegExpFlags<R>, "d"> extends true ? INDICES : never;
+  indices: HasStrictRegExpFlag<FLAGS, "d"> extends true ? INDICES : never;
+  typeSystemMessage: "healthy";
 } : never;
 /**
- * @since 2025/12/24 12:27:39
- * @commit js-dev-tool@6ff89180acfb53c1a0bf9aebadfa12b210bfb3f8
+ * Watch the regex flags (If flags are statically defined, the state of the flag is bound)
  */
-export type TypedRegExp<P extends string, F extends string = ""> = RegExp & {
-  readonly source: P;
-  readonly flags: F;
-} & TypedRegExpBrand & {
-  types: TypedRegExpTypes<TypedRegExp<P, F>>;
+export type RegExpFlagPart<R extends RegExp> = Pick<R, "global" | "dotAll" | "hasIndices" | "ignoreCase" | "multiline" | "sticky" | "unicode" | "unicodeSets">;
+export type TypedRegExpFlagPart<F extends string> = {
   global: HasStrictRegExpFlag<F, "g">;
   dotAll: HasStrictRegExpFlag<F, "s">;
   hasIndices: HasStrictRegExpFlag<F, "d">;
@@ -70,12 +77,64 @@ export type TypedRegExp<P extends string, F extends string = ""> = RegExp & {
   unicodeSets: HasStrictRegExpFlag<F, "v">;
 };
 /**
- * Extracts the literal type from the source property of a RegExp.
- * @template R - A RegExp type.
+ * Represents the combined properties of a `TypedRegExp` instance,  
+ * including its detailed type information (`types`) and type-level flag properties.
+ *
+ * @template P - The pattern string of the RegExp.
+ * @template F - The flags string of the RegExp.
+ * @returns A type that combines `TypedRegExpTypes` and `TypedRegExpFlagPart`.
+ * @internal
+ */
+export type TypedRegExpProperties<
+  P extends string, F extends string = "",
+> = [F] extends [never]
+  ? CombineIntersection<{ types: never; } & TypedRegExpFlagPart<F>/*, {}*/>
+  : CombineIntersection<{ types: TypedRegExpTypes<TypedRegExpCore<P, F>> } & TypedRegExpFlagPart<F>/*, {}*/>;
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//                      Primary Types
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * __`TypedRegExp` base type (core)__
+ * 
+ * + Can extend extra props from this type
+ * 
+ * @template P - The literal type of the regular expression pattern.
+ * @template F - The literal type of the regular expression flags.
+ * @property {P} source - The literal pattern string of the regular expression.
+ * @property {F} flags - The literal flags string of the regular expression.
+ * @internal
+ */
+export type TypedRegExpCore<P extends string, F extends string = ""> = RegExp & {
+  readonly source: P;
+  readonly flags: F;
+} & TypedRegExpBrand;
+/**
+ * Represents a regular expression with enhanced type information,  
+ * including literal types for its pattern and flags, and detailed types  
+ * for its `exec` method results, named capture groups, and replacer functions.
+ *
+ * @template P - The literal type of the regular expression pattern.
+ * @template F - The literal type of the regular expression flags.
+ * 
+ * @since 2025/12/24 12:27:39
+ * @commit js-dev-tool@6ff89180acfb53c1a0bf9aebadfa12b210bfb3f8
  */
-export type RegExpSource<R extends RegExp> = R extends RegExp & { readonly source: infer T } ? T : never;
+export type TypedRegExp<
+  P extends string,
+  F extends string = "",
+> = TypedRegExpCore<P, F> & TypedRegExpProperties<P, F>;
 /**
- * @deprecated description
+ * ### __`Type-only signature`__: no runtime implementation is provided.
+ *
+ * Creates a TypedRegExp type from a pattern and optional flags.
+ *
+ * @template P - The regex pattern (string literal).
+ * @template F - The regex flags (string literal).
+ * @param pattern The regex pattern.
+ * @param flags Optional regex flags.
+ * @see {@link TypedRegExp}
  */
 export declare function createRegExp<
   const P extends string,

package/dist/types/replacer.d.ts

@@ -16,10 +16,8 @@
 /**
  * @file types/replacer.d.ts
  */
-import type {
-  TypedRegExp,
-  RegExpSource,
-} from "./regex.d.ts";
+import type { TypedRegExp } from "./regex.d.ts";
+import type { RegExpSource } from "./regex-util.d.ts";
 import type { IsEmptyRecord } from "./common.d.ts";
 import type { CountCaptureGroups, RegExpNamedGroups, CaptureOptTuple } from "./captures.d.ts";
 /*!
@@ -28,36 +26,62 @@ import type { CountCaptureGroups, RegExpNamedGroups, CaptureOptTuple } from "./c
 // ============================================================================
 */
 /**
- * Creates the parameter types for String.replace callback function.
- * 
- * @example
- * type Params = StringReplacerParams<typeof myRegex>;
- * // [match: string, ...captures: string[], offset: number, string: string, groups?: {...}]
+ * Represents the rest parameters for the `String.prototype.replace()` replacer function,  
+ * excluding the `match` parameter.
+ *
+ * @template R - The `RegExp` type.
+ * @template S - The source string of the `RegExp`.
+ * @template GroupCount - The number of capture groups in the `RegExp`.
+ * @template NamedGroups - The type of named capture groups in the `RegExp`.
+ * @returns A tuple type representing the rest parameters of the replacer function.
  */
-export type StringReplacerParams<
+export type StringReplacerRestArgs<
   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
 ];
 /**
- * string replacer is function or string
+ * 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>
+> = [
+  /** The matched substring. */
+  matched: string,
+  /**
+   * The rest parameters of the replacer function, including captures, offset, input string, and optionally named groups.
+   */
+  ...StringReplacerRestArgs<R, S, GroupCount, NamedGroups>
+];
+/**
+ * Represents the type of the replacer function used in `String.prototype.replace()`.
+ *
+ * This type is designed to provide precise type inference for the replacer function's parameters,
+ * including `match`, capture groups (both indexed and named), `offset`, `input`, and `groups`.
+ *
+ * @template R - The `RegExp` type for which the replacer function is being defined.
  */
-export type StringReplacerType<R> =
+export type StringReplacerType<R extends RegExp> =
   R extends TypedRegExp<infer P extends string, infer F extends string>
-    ? (...args: StringReplacerParams<TypedRegExp<P, F>, P>) => string
+    ? (...args: StringReplacerParams<R>) => string
     : R extends RegExp
-      ? (match: string, ...rest: any[]) => string
+      ? (match: string, ...restArgs: any[]) => string
       : string;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "literate-regex",
-  "version": "0.6.2",
+  "version": "0.6.9",
   "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,