@ptolemy2002/rgx 4.2.0 → 4.3.0

package/README.md

@@ -20,21 +20,27 @@ const validVanillaRegexFlagsSymbol = Symbol('rgx.ValidVanillaRegexFlags');
 type ValidVanillaRegexFlagsBrandSymbol = typeof validVanillaRegexFlagsSymbol;
 type ValidVanillaRegexFlags = Branded<string, [ValidVanillaRegexFlagsBrandSymbol]>;
 
+const validRegexFlagsSymbol = Symbol('rgx.ValidRegexFlags');
+type ValidRegexFlagsBrandSymbol = typeof validRegexFlagsSymbol;
+type ValidRegexFlags = Branded<string, [ValidRegexFlagsBrandSymbol]> | ValidVanillaRegexFlags;
+
+type RegExpFlagTransformer = (exp: RegExp) => RegExp;
+
 const validIdentifierSymbol = Symbol('rgx.ValidIdentifier');
 type ValidIdentifierBrandSymbol = typeof validIdentifierSymbol;
 type ValidIdentifier = Branded<string, [ValidIdentifierBrandSymbol]>;
 
 type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | RGXTokenType[];
 type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
-type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | RGXTokenTypeGuardInput[];
+type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof ExtRegExp | RGXTokenTypeGuardInput[];
 type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // Maps token type strings to their corresponding types, e.g.:
     // 'no-op' -> RGXNoOpToken, 'literal' -> RGXLiteralToken, etc.
-    // Also maps RGXClassTokenConstructor to InstanceType<T>.
+    // Also maps RGXClassTokenConstructor to InstanceType<T> and typeof ExtRegExp to ExtRegExp.
     // ... see source for full definition
 ;
 
-type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS';
+type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT';
 
 type RangeObject = {
     min?: number | null;
@@ -149,6 +155,54 @@ constructor(message: string, got: string)
 #### Methods
 - `toString() => string`: Returns a formatted string indicating the invalid identifier and the reason for failure.
 
+### RGXInvalidRegexFlagsError extends RGXError
+A specific error class for invalid regex flags (including both vanilla and custom registered flags). This error is thrown when a string fails validation as valid regex flags. The error code is set to `INVALID_REGEX_FLAGS` on instantiation.
+
+#### Constructor
+```typescript
+constructor(message: string, got: string)
+```
+- `message` (`string`): The error message.
+- `got` (`string`): The actual string that was received, which failed validation.
+
+#### Properties
+- `got` (`string`): The actual string that was received, which failed validation.
+
+#### Methods
+- `toString() => string`: Returns a formatted string indicating the invalid flags and the reason for failure.
+
+### RGXInvalidFlagTransformerKeyError extends RGXError
+A specific error class for invalid flag transformer keys. This error is thrown when an invalid key is provided to `registerFlagTransformer` (e.g., a key that is not a single character). The error code is set to `INVALID_FLAG_TRANSFORMER_KEY` on instantiation.
+
+#### Constructor
+```typescript
+constructor(message: string, got: string)
+```
+- `message` (`string`): The error message.
+- `got` (`string`): The actual key string that was received, which failed validation.
+
+#### Properties
+- `got` (`string`): The actual key string that was received, which failed validation.
+
+#### Methods
+- `toString() => string`: Returns a formatted string indicating the invalid key and the reason for failure.
+
+### RGXFlagTransformerConflictError extends RGXError
+A specific error class for flag transformer conflicts. This error is thrown when attempting to register a flag transformer with a key that conflicts with an existing vanilla regex flag or an already-registered transformer. The error code is set to `FLAG_TRANSFORMER_CONFLICT` on instantiation.
+
+#### Constructor
+```typescript
+constructor(message: string, got: string)
+```
+- `message` (`string`): The error message.
+- `got` (`string`): The conflicting key string.
+
+#### Properties
+- `got` (`string`): The conflicting key string.
+
+#### Methods
+- `toString() => string`: Returns a formatted string indicating the conflict and the reason for failure.
+
 ### RGXOutOfBoundsError extends RGXError
 A specific error class for out-of-bounds values. This error is thrown when a numeric value falls outside an expected range. The error code is set to `OUT_OF_BOUNDS` on instantiation.
 
@@ -277,6 +331,24 @@ constructor(args?: RGXGroupTokenArgs, tokens?: RGXTokenCollectionInput)
 #### Methods
 - `toRgx() => RegExp`: Resolves the group by concatenating the internal tokens and wrapping the result in the appropriate group syntax: `(?<name>...)` for named groups, `(?:...)` for non-capturing groups, or `(...)` for capturing groups.
 
+### ExtRegExp extends RegExp
+A subclass of `RegExp` that supports custom flag transformers in addition to the standard vanilla regex flags (g, i, m, s, u, y). When constructed, custom flags are extracted, their corresponding transformers are applied to the pattern and vanilla flags, and the resulting transformed `RegExp` is created. The `flags` getter returns both the vanilla flags and any custom flags.
+
+A function `extRegExp` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Constructor
+```typescript
+constructor(pattern: string | RegExp, flags?: string)
+```
+- `pattern` (`string | RegExp`): The regex pattern. If a `RegExp` is provided, its `source` is used and its existing `flags` are tracked as already-applied flags to avoid re-applying transformers.
+- `flags` (`string`, optional): The flags string, which may include both vanilla regex flags and custom registered flag keys. Validated via `assertValidRegexFlags`. Defaults to `''`.
+
+#### Properties
+- `flags` (`string`): Returns the combination of the vanilla flags (from the underlying `RegExp`) and any custom flags that were applied during construction.
+
+#### Static Properties
+- `[Symbol.species]` (`RegExpConstructor`): Returns `ExtRegExp`, ensuring that derived `RegExp` methods (like those returning new regex instances) produce `ExtRegExp` instances rather than plain `RegExp`.
+
 ## Functions
 The following functions are exported by the library:
 
@@ -659,10 +731,10 @@ A helper function that resolves an array of RGX tokens and concatenates their re
 
 ### rgx
 ```typescript
-function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: RGXToken[]) => RegExp
+function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: RGXToken[]) => ExtRegExp
 ```
 
-Creates and returns a template tag function that constructs a `RegExp` object from the provided template literal with the provided flags. The template literal can contain RGX tokens, which will be resolved and concatenated with the literal parts to form the final regex pattern.
+Creates and returns a template tag function that constructs an `ExtRegExp` object from the provided template literal with the provided flags. The template literal can contain RGX tokens, which will be resolved and concatenated with the literal parts to form the final regex pattern.
 
 Example usages:
 ```typescript
@@ -679,27 +751,27 @@ const pattern3 = rgx()`${beginning}value: ${[word, optionalDigit]}${end}`; // /^
 
 #### Parameters
 **Direct**
-  - `flags` (`string`, optional): The regex flags to apply to the resulting `RegExp` object (e.g., 'g', 'i', 'm', etc.). If not provided, no flags will be applied. If provided and not valid vanilla regex flags, an `RGXInvalidVanillaRegexFlagsError` will be thrown.
+  - `flags` (`string`, optional): The regex flags to apply to the resulting `ExtRegExp` object (e.g., 'g', 'i', 'm', or custom registered flags). If not provided, no flags will be applied. If provided and not valid regex flags (vanilla or registered custom), an `RGXInvalidRegexFlagsError` will be thrown.
 
 **Template Tag**
   - `strings` (`TemplateStringsArray`): The literal parts of the template string.
   - `tokens` (`RGXToken[]`): The RGX tokens to be resolved and concatenated with the literal parts.
 
 #### Returns
-- `(strings: TemplateStringsArray, ...tokens: RGXToken[]) => RegExp`: A template tag function that takes a template literal and returns a `RegExp` object constructed from the resolved tokens, literal parts, and the provided flags.
+- `(strings: TemplateStringsArray, ...tokens: RGXToken[]) => ExtRegExp`: A template tag function that takes a template literal and returns an `ExtRegExp` object constructed from the resolved tokens, literal parts, and the provided flags.
 
 ### rgxa
 ```typescript
-function rgxa(tokens: RGXToken[], flags?: string): RegExp
+function rgxa(tokens: RGXToken[], flags?: string): ExtRegExp
 ```
-As an alternative to using the `rgx` template tag, you can directly call `rgxa` with an array of RGX tokens and optional flags to get a `RegExp` object. This is useful in cases where you don't want to use a template literal.
+As an alternative to using the `rgx` template tag, you can directly call `rgxa` with an array of RGX tokens and optional flags to get an `ExtRegExp` object. This is useful in cases where you don't want to use a template literal.
 
 #### Parameters
   - `tokens` (`RGXToken[]`): The RGX tokens to be resolved and concatenated to form the regex pattern.
-  - `flags` (`string`, optional): The regex flags to apply to the resulting `RegExp` object (e.g., 'g', 'i', 'm', etc.). If not provided, no flags will be applied. If provided and not valid vanilla regex flags, an `RGXInvalidVanillaRegexFlagsError` will be thrown.
+  - `flags` (`string`, optional): The regex flags to apply to the resulting `ExtRegExp` object (e.g., 'g', 'i', 'm', or custom registered flags). If not provided, no flags will be applied. If provided and not valid regex flags (vanilla or registered custom), an `RGXInvalidRegexFlagsError` will be thrown.
 
 #### Returns
-- `RegExp`: A `RegExp` object constructed from the resolved tokens and the provided flags.
+- `ExtRegExp`: An `ExtRegExp` object constructed from the resolved tokens and the provided flags.
 
 ### expandRgxUnionTokens
 ```typescript
@@ -766,12 +838,132 @@ Asserts that the given numeric value falls within the specified range. If the as
 #### Returns
 - `void`: This function does not return a value, but will throw an error if the assertion fails.
 
+### isValidRegexFlags
+```typescript
+function isValidRegexFlags(flags: string): flags is ValidRegexFlags
+```
+
+Checks if the given string is a valid combination of regex flags, including both vanilla flags (g, i, m, s, u, y) and any custom flags registered via `registerFlagTransformer`. Custom flag characters are stripped before validating the remaining characters as vanilla flags.
+
+#### Parameters
+  - `flags` (`string`): The string to check.
+
+#### Returns
+- `boolean`: `true` if the string is a valid combination of regex flags, otherwise `false`.
+
+### assertValidRegexFlags
+```typescript
+function assertValidRegexFlags(flags: string): asserts flags is ValidRegexFlags
+```
+
+Asserts that the given string is a valid combination of regex flags, including both vanilla flags and any custom registered flags. If the assertion fails, an `RGXInvalidRegexFlagsError` will be thrown.
+
+#### Parameters
+  - `flags` (`string`): The string to assert.
+
+#### Returns
+- `void`: This function does not return a value, but will throw an error if the assertion fails.
+
+### isFlagKeyAvailable
+```typescript
+function isFlagKeyAvailable(flags: string): boolean
+```
+
+Checks if the given string is available for use as a custom flag transformer key. Returns `false` if the string is a vanilla regex flag or if any character in the string is already registered as a custom flag transformer.
+
+#### Parameters
+  - `flags` (`string`): The string to check.
+
+#### Returns
+- `boolean`: `true` if the string is available for use as a custom flag key, otherwise `false`.
+
+### registerFlagTransformer
+```typescript
+function registerFlagTransformer(key: string, transformer: RegExpFlagTransformer): void
+```
+
+Registers a custom flag transformer under the given single-character key. The key must be exactly one character, must not be a vanilla regex flag, and must not already be registered. When an `ExtRegExp` is constructed with this flag character in its flags string, the transformer function will be called with the `RegExp` to transform it.
+
+#### Parameters
+  - `key` (`string`): A single-character string to use as the flag key. Must not be a vanilla regex flag or an already-registered key.
+  - `transformer` (`RegExpFlagTransformer`): A function that takes a `RegExp` and returns a transformed `RegExp`.
+
+#### Returns
+- `void`: This function does not return a value, but will throw an `RGXInvalidFlagTransformerKeyError` if the key is not a single character, or an `RGXFlagTransformerConflictError` if the key conflicts with a vanilla flag or an existing transformer.
+
+### unregisterFlagTransformer
+```typescript
+function unregisterFlagTransformer(key: string): void
+```
+
+Unregisters a previously registered custom flag transformer by its key. If the key was not registered, this is a no-op.
+
+#### Parameters
+  - `key` (`string`): The flag key to unregister.
+
+#### Returns
+- `void`: This function does not return a value.
+
+### applyFlagTransformers
+```typescript
+function applyFlagTransformers(regex: RegExp, flags: string, alreadyAppliedFlags?: string): RegExp
+```
+
+Applies all registered flag transformers whose keys appear in the given flags string to the provided `RegExp`, returning the resulting transformed `RegExp`. Flags present in `alreadyAppliedFlags` are skipped to avoid re-applying transformers.
+
+#### Parameters
+  - `regex` (`RegExp`): The regular expression to transform.
+  - `flags` (`string`): The flags string containing custom flag characters to apply.
+  - `alreadyAppliedFlags` (`string`, optional): A string of flag characters that have already been applied and should be skipped. Defaults to `''`.
+
+#### Returns
+- `RegExp`: The transformed `RegExp` after applying all matching flag transformers.
+
+### extractCustomRegexFlags
+```typescript
+function extractCustomRegexFlags(flags: string): string
+```
+
+Extracts the custom (non-vanilla) flag characters from the given flags string by returning only the characters that correspond to registered flag transformers.
+
+#### Parameters
+  - `flags` (`string`): The flags string to extract custom flags from.
+
+#### Returns
+- `string`: A string containing only the custom flag characters found in the input.
+
+### extractVanillaRegexFlags
+```typescript
+function extractVanillaRegexFlags(flags: string): string
+```
+
+Extracts the vanilla regex flag characters from the given flags string by removing all characters that correspond to registered flag transformers.
+
+#### Parameters
+  - `flags` (`string`): The flags string to extract vanilla flags from.
+
+#### Returns
+- `string`: A string with all registered custom flag characters removed, leaving only vanilla flags.
+
+### normalizeRegexFlags
+```typescript
+function normalizeRegexFlags(flags: string): string
+```
+
+Normalizes a string of regex flags (including both vanilla and custom registered flags) by removing duplicate flags while preserving order. If any character in the string is not a valid regex flag (vanilla or registered custom), an `RGXInvalidRegexFlagsError` will be thrown.
+
+#### Parameters
+  - `flags` (`string`): The flags string to normalize.
+
+#### Returns
+- `string`: The normalized flags string with duplicates removed.
+
 ### normalizeVanillaRegexFlags
 ```typescript
 function normalizeVanillaRegexFlags(flags: string): string
 ```
 
-Normalizes a string of vanilla regex flags by removing duplicate flags while preserving order. If any character in the string is not a valid vanilla regex flag (g, i, m, s, u, y), an `RGXInvalidVanillaRegexFlagsError` will be thrown.
+Normalizes a string of vanilla regex flags by removing duplicate flags while preserving order. First validates that all characters are valid vanilla regex flags (g, i, m, s, u, y), throwing an `RGXInvalidVanillaRegexFlagsError` if any are not, then delegates to `normalizeRegexFlags` for deduplication.
 
 #### Parameters
   - `flags` (`string`): The flags string to normalize.
@@ -781,18 +973,18 @@ Normalizes a string of vanilla regex flags by removing duplicate flags while pre
 
 ### regexWithFlags
 ```typescript
-function regexWithFlags(exp: RegExp, flags: string, replace?: boolean): RegExp
+function regexWithFlags(exp: RegExp | ExtRegExp, flags: string, replace?: boolean): ExtRegExp
 ```
 
-Creates a new `RegExp` from an existing one with additional or replaced flags. When `replace` is `false` (the default), the provided flags are merged with the existing flags and normalized (duplicates removed). When `replace` is `true`, the existing flags are discarded and only the provided flags are used. The provided flags are validated as valid vanilla regex flags via `assertValidVanillaRegexFlags`.
+Creates a new `ExtRegExp` from an existing one with additional or replaced flags. When `replace` is `false` (the default), the provided flags are merged with the existing flags and normalized (duplicates removed). When `replace` is `true`, the existing flags are discarded and only the provided flags are used. The provided flags are validated as valid vanilla regex flags via `assertValidVanillaRegexFlags`.
 
 #### Parameters
-  - `exp` (`RegExp`): The source regular expression.
+  - `exp` (`RegExp | ExtRegExp`): The source regular expression.
   - `flags` (`string`): The flags to add or replace with. Must be valid vanilla regex flags, or an `RGXInvalidVanillaRegexFlagsError` will be thrown.
   - `replace` (`boolean`, optional): Whether to replace the existing flags entirely instead of merging. Defaults to `false`.
 
 #### Returns
-- `RegExp`: A new `RegExp` with the same source pattern and the resulting flags.
+- `ExtRegExp`: A new `ExtRegExp` with the same source pattern and the resulting flags.
 
 ### regexMatchAtPosition
 ```typescript
@@ -829,4 +1021,4 @@ The following commands exist in the project:
 - `npm run release-major` - Publishes the library to npm with a major version bump
 - `npm run test` - Runs the tests for the library
 - `npm run test:watch` - Runs the tests for the library in watch mode
-- `npm run test:coverage` - Runs the tests for the library and generates a coverage report
+- `npm run test:coverage` - Runs the tests for the library and generates a coverage report

package/dist/ExtRegExp.d.ts

@@ -0,0 +1,17 @@
+import { ValidRegexFlags } from "./types";
+export type RegExpFlagTransformer = (exp: RegExp) => RegExp;
+export declare class ExtRegExp extends RegExp {
+    private extFlags;
+    constructor(pattern: string | RegExp, flags?: string);
+    get flags(): string;
+    static get [Symbol.species](): RegExpConstructor;
+}
+export declare function isFlagKeyAvailable(flags: string): boolean;
+export declare function registerFlagTransformer(key: string, transformer: RegExpFlagTransformer): void;
+export declare function unregisterFlagTransformer(key: string): void;
+export declare function applyFlagTransformers(regex: RegExp, flags: string, alreadyAppliedFlags?: string): RegExp;
+export declare function extractCustomRegexFlags(flags: string): string;
+export declare function extractVanillaRegexFlags(flags: string): string;
+export declare function isValidRegexFlags(flags: string): flags is ValidRegexFlags;
+export declare function assertValidRegexFlags(flags: string): asserts flags is ValidRegexFlags;
+export declare const extRegExp: (pattern: string | RegExp, flags?: string | undefined) => ExtRegExp;

package/dist/ExtRegExp.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extRegExp = exports.ExtRegExp = void 0;
+exports.isFlagKeyAvailable = isFlagKeyAvailable;
+exports.registerFlagTransformer = registerFlagTransformer;
+exports.unregisterFlagTransformer = unregisterFlagTransformer;
+exports.applyFlagTransformers = applyFlagTransformers;
+exports.extractCustomRegexFlags = extractCustomRegexFlags;
+exports.extractVanillaRegexFlags = extractVanillaRegexFlags;
+exports.isValidRegexFlags = isValidRegexFlags;
+exports.assertValidRegexFlags = assertValidRegexFlags;
+const errors_1 = require("./errors");
+const internal_1 = require("./internal");
+const typeGuards_1 = require("./typeGuards");
+const flagTransformers = {};
+class ExtRegExp extends RegExp {
+    constructor(pattern, flags = '') {
+        assertValidRegexFlags(flags);
+        const vanillaFlags = extractVanillaRegexFlags(flags);
+        const customFlags = extractCustomRegexFlags(flags);
+        const source = pattern instanceof RegExp ? pattern.source : pattern;
+        const alreadyAppliedFlags = pattern instanceof RegExp ? pattern.flags : '';
+        const { source: transformedSource, flags: transformedFlags } = applyFlagTransformers(new RegExp(source, vanillaFlags), customFlags, alreadyAppliedFlags);
+        super(transformedSource, transformedFlags);
+        this.extFlags = customFlags;
+    }
+    get flags() {
+        return super.flags + this.extFlags;
+    }
+    // Ensure that methods like .exec(), split(), etc. return instances
+    // of ExtRegExp rather than plain RegExp (preserves custom flags)
+    static get [Symbol.species]() {
+        return ExtRegExp;
+    }
+}
+exports.ExtRegExp = ExtRegExp;
+function isFlagKeyAvailable(flags) {
+    if ((0, typeGuards_1.isValidVanillaRegexFlags)(flags))
+        return false;
+    for (const flag in flagTransformers) {
+        if (flags.includes(flag))
+            return false;
+    }
+    return true;
+}
+function registerFlagTransformer(key, transformer) {
+    if (key.length !== 1)
+        throw new errors_1.RGXInvalidFlagTransformerKeyError("Flag key must be a single character.", key);
+    if ((0, typeGuards_1.isValidVanillaRegexFlags)(key))
+        throw new errors_1.RGXFlagTransformerConflictError("Transformer key conflicts with a vanilla regex flag.", key);
+    if (!isFlagKeyAvailable(key))
+        throw new errors_1.RGXFlagTransformerConflictError("Transformer already exists under this key.", key);
+    flagTransformers[key] = transformer;
+}
+function unregisterFlagTransformer(key) {
+    delete flagTransformers[key];
+}
+function applyFlagTransformers(regex, flags, alreadyAppliedFlags = '') {
+    for (const flag in flagTransformers) {
+        if (flags.includes(flag) && !alreadyAppliedFlags.includes(flag)) {
+            regex = flagTransformers[flag](regex);
+            alreadyAppliedFlags += flag;
+        }
+    }
+    return regex;
+}
+function extractCustomRegexFlags(flags) {
+    let customFlags = '';
+    for (const flag in flagTransformers) {
+        if (flags.includes(flag)) {
+            customFlags += flag;
+        }
+    }
+    return customFlags;
+}
+function extractVanillaRegexFlags(flags) {
+    for (const flag in flagTransformers) {
+        flags = flags.replaceAll(flag, '');
+    }
+    return flags;
+}
+function isValidRegexFlags(flags) {
+    // Remove all instances of registered flag transformers from the flags string, then
+    // check if the remaining flags are valid vanilla regex flags.
+    flags = extractVanillaRegexFlags(flags);
+    return (0, typeGuards_1.isValidVanillaRegexFlags)(flags);
+}
+function assertValidRegexFlags(flags) {
+    if (!isValidRegexFlags(flags)) {
+        throw new errors_1.RGXInvalidRegexFlagsError("Invalid regex flags", flags);
+    }
+}
+exports.extRegExp = (0, internal_1.createConstructFunction)(ExtRegExp);

package/dist/errors/base.d.ts

@@ -1,4 +1,4 @@
-export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS';
+export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT';
 export declare class RGXError extends Error {
     code: RGXErrorCode;
     constructor(message: string, code?: RGXErrorCode);

package/dist/errors/flagTransformerConflict.d.ts

@@ -0,0 +1,6 @@
+import { RGXError } from "./";
+export declare class RGXFlagTransformerConflictError extends RGXError {
+    got: string;
+    constructor(message: string, got: string);
+    toString(): string;
+}

package/dist/errors/flagTransformerConflict.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXFlagTransformerConflictError = void 0;
+const errors_1 = require("./");
+class RGXFlagTransformerConflictError extends errors_1.RGXError {
+    constructor(message, got) {
+        super(message, 'FLAG_TRANSFORMER_CONFLICT');
+        this.name = 'RGXFlagTransformerConflictError';
+        this.got = got;
+    }
+    toString() {
+        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    }
+}
+exports.RGXFlagTransformerConflictError = RGXFlagTransformerConflictError;

package/dist/errors/index.d.ts

@@ -1,7 +1,10 @@
 export * from './base';
 export * from './invalidToken';
 export * from './invalidRegexString';
+export * from './invalidRegexFlags';
 export * from './invalidVanillaRegexFlags';
 export * from './notImplemented';
 export * from './invalidIdentifier';
 export * from './outOfBounds';
+export * from './invalidFlagTransformerKey';
+export * from './flagTransformerConflict';

package/dist/errors/index.js

@@ -17,7 +17,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./base"), exports);
 __exportStar(require("./invalidToken"), exports);
 __exportStar(require("./invalidRegexString"), exports);
+__exportStar(require("./invalidRegexFlags"), exports);
 __exportStar(require("./invalidVanillaRegexFlags"), exports);
 __exportStar(require("./notImplemented"), exports);
 __exportStar(require("./invalidIdentifier"), exports);
 __exportStar(require("./outOfBounds"), exports);
+__exportStar(require("./invalidFlagTransformerKey"), exports);
+__exportStar(require("./flagTransformerConflict"), exports);

package/dist/errors/invalidFlagTransformerKey.d.ts

@@ -0,0 +1,6 @@
+import { RGXError } from "./";
+export declare class RGXInvalidFlagTransformerKeyError extends RGXError {
+    got: string;
+    constructor(message: string, got: string);
+    toString(): string;
+}

package/dist/errors/invalidFlagTransformerKey.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXInvalidFlagTransformerKeyError = void 0;
+const errors_1 = require("./");
+class RGXInvalidFlagTransformerKeyError extends errors_1.RGXError {
+    constructor(message, got) {
+        super(message, 'INVALID_FLAG_TRANSFORMER_KEY');
+        this.name = 'RGXInvalidFlagTransformerKeyError';
+        this.got = got;
+    }
+    toString() {
+        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    }
+}
+exports.RGXInvalidFlagTransformerKeyError = RGXInvalidFlagTransformerKeyError;

package/dist/errors/invalidRegexFlags.d.ts

@@ -0,0 +1,6 @@
+import { RGXError } from "./";
+export declare class RGXInvalidRegexFlagsError extends RGXError {
+    got: string;
+    constructor(message: string, got: string);
+    toString(): string;
+}

package/dist/errors/invalidRegexFlags.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXInvalidRegexFlagsError = void 0;
+const errors_1 = require("./");
+class RGXInvalidRegexFlagsError extends errors_1.RGXError {
+    constructor(message, got) {
+        super(message, 'INVALID_REGEX_FLAGS');
+        this.name = 'RGXInvalidRegexFlagsError';
+        this.got = got;
+    }
+    toString() {
+        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    }
+}
+exports.RGXInvalidRegexFlagsError = RGXInvalidRegexFlagsError;

package/dist/errors/outOfBounds.d.ts

@@ -17,4 +17,4 @@ export declare class RGXOutOfBoundsError extends RGXError {
     toString(): string;
 }
 export declare function isInRange(value: number, { min, max, inclusiveLeft, inclusiveRight }?: RangeObject): boolean;
-export declare function assertInRange(value: number, range: RangeObject, message?: string): void;
+export declare function assertInRange(value: number, range?: RangeObject, message?: string): void;

package/dist/errors/outOfBounds.js

@@ -102,7 +102,7 @@ function isInRange(value, { min = null, max = null, inclusiveLeft = true, inclus
     }
     return true;
 }
-function assertInRange(value, range, message = "Value out of bounds") {
+function assertInRange(value, range = {}, message = "Value out of bounds") {
     if (!isInRange(value, range)) {
         throw new RGXOutOfBoundsError(message, value, range);
     }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as t from "./types";
+import { ExtRegExp } from "./ExtRegExp";
 export * from "./errors";
 export * from "./types";
 export * from "./typeGuards";
@@ -7,5 +8,6 @@ export * from "./class";
 export * from "./resolve";
 export * from "./concat";
 export * from "./utils";
-export declare function rgxa(tokens: t.RGXToken[], flags?: string): RegExp;
-export default function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => RegExp;
+export * from "./ExtRegExp";
+export declare function rgxa(tokens: t.RGXToken[], flags?: string): ExtRegExp;
+export default function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => ExtRegExp;

package/dist/index.js

@@ -10,38 +10,16 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
 }));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rgxa = rgxa;
 exports.default = rgx;
-const tg = __importStar(require("./typeGuards"));
 const class_1 = require("./class");
 const concat_1 = require("./concat");
 const internal_1 = require("./internal");
+const ExtRegExp_1 = require("./ExtRegExp");
 __exportStar(require("./errors"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./typeGuards"), exports);
@@ -50,15 +28,16 @@ __exportStar(require("./class"), exports);
 __exportStar(require("./resolve"), exports);
 __exportStar(require("./concat"), exports);
 __exportStar(require("./utils"), exports);
+__exportStar(require("./ExtRegExp"), exports);
 // Call this for certain class methods to work correctly
 (0, class_1.rgxClassInit)();
 function rgxa(tokens, flags = '') {
-    tg.assertValidVanillaRegexFlags(flags);
+    (0, ExtRegExp_1.assertValidRegexFlags)(flags);
     const pattern = (0, concat_1.rgxConcat)(tokens);
-    return new RegExp(pattern, flags);
+    return (0, ExtRegExp_1.extRegExp)(pattern, flags);
 }
 function rgx(flags = '') {
-    tg.assertValidVanillaRegexFlags(flags);
+    (0, ExtRegExp_1.assertValidRegexFlags)(flags);
     return (strings, ...tokens) => {
         return rgxa((0, internal_1.taggedTemplateToArray)(strings, tokens), flags);
     };

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import { Branded } from "@ptolemy2002/ts-brand-utils";
 import type { RGXClassToken } from "./class";
+import { ExtRegExp } from "./ExtRegExp";
 export type RGXNoOpToken = null | undefined;
 export type RGXLiteralToken = RegExp;
 export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
@@ -11,10 +12,10 @@ export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken |
 export type RGXClassTokenConstructor = new (...args: unknown[]) => RGXClassToken;
 export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | RGXTokenType[];
 export type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
-export type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | RGXTokenTypeGuardInput[];
+export type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof ExtRegExp | RGXTokenTypeGuardInput[];
 export type RGXTokenFromType<T extends RGXTokenTypeGuardInput> = T extends null ? RGXToken : T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? RGXLiteralToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends 'class' ? RGXClassToken : T extends 'array' ? RGXToken[] : T extends RGXTokenTypeGuardInput[] ? {
     [K in keyof T]: T[K] extends RGXTokenTypeGuardInput ? RGXTokenFromType<T[K]> : never;
-} : T extends RGXClassTokenConstructor ? InstanceType<T> : never;
+} : T extends RGXClassTokenConstructor ? InstanceType<T> : T extends typeof ExtRegExp ? ExtRegExp : never;
 export type RangeObject = {
     min?: number | null;
     max?: number | null;
@@ -27,6 +28,9 @@ export type ValidRegexString = Branded<string, [ValidRegexBrandSymbol]>;
 export declare const validVanillaRegexFlagsSymbol: unique symbol;
 export type ValidVanillaRegexFlagsBrandSymbol = typeof validVanillaRegexFlagsSymbol;
 export type ValidVanillaRegexFlags = Branded<string, [ValidVanillaRegexFlagsBrandSymbol]>;
+export declare const validRegexFlagsSymbol: unique symbol;
+export type ValidRegexFlagsBrandSymbol = typeof validRegexFlagsSymbol;
+export type ValidRegexFlags = Branded<string, [ValidRegexFlagsBrandSymbol]> | ValidVanillaRegexFlags;
 export declare const validIdentifierSymbol: unique symbol;
 export type ValidIdentifierBrandSymbol = typeof validIdentifierSymbol;
 export type ValidIdentifier = Branded<string, [ValidIdentifierBrandSymbol]>;

package/dist/types.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validIdentifierSymbol = exports.validVanillaRegexFlagsSymbol = exports.validRegexSymbol = void 0;
+exports.validIdentifierSymbol = exports.validRegexFlagsSymbol = exports.validVanillaRegexFlagsSymbol = exports.validRegexSymbol = void 0;
 exports.validRegexSymbol = Symbol('rgx.ValidRegex');
 exports.validVanillaRegexFlagsSymbol = Symbol('rgx.ValidVanillaRegexFlags');
+exports.validRegexFlagsSymbol = Symbol('rgx.ValidRegexFlags');
 exports.validIdentifierSymbol = Symbol('rgx.ValidIdentifier');

package/dist/utils/normalizeRegexFlags.d.ts

@@ -1 +1,2 @@
+export declare function normalizeRegexFlags(flags: string): string;
 export declare function normalizeVanillaRegexFlags(flags: string): string;

package/dist/utils/normalizeRegexFlags.js

@@ -1,14 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeRegexFlags = normalizeRegexFlags;
 exports.normalizeVanillaRegexFlags = normalizeVanillaRegexFlags;
 const errors_1 = require("../errors");
-function normalizeVanillaRegexFlags(flags) {
-    const validFlags = ['g', 'i', 'm', 's', 'u', 'y'];
+const ExtRegExp_1 = require("../ExtRegExp");
+const typeGuards_1 = require("../typeGuards");
+function normalizeRegexFlags(flags) {
     const seenFlags = new Set();
     let normalizedFlags = '';
     for (const flag of flags) {
-        if (!validFlags.includes(flag)) {
-            throw new errors_1.RGXInvalidVanillaRegexFlagsError(`[${flag}] is not valid.`, flags);
+        if (!(0, ExtRegExp_1.isValidRegexFlags)(flag)) {
+            throw new errors_1.RGXInvalidRegexFlagsError(`[${flag}] is not valid.`, flags);
         }
         if (!seenFlags.has(flag)) {
             seenFlags.add(flag);
@@ -17,3 +19,12 @@ function normalizeVanillaRegexFlags(flags) {
     }
     return normalizedFlags;
 }
+function normalizeVanillaRegexFlags(flags) {
+    for (const flag of flags) {
+        if (!(0, typeGuards_1.isValidVanillaRegexFlags)(flag)) {
+            throw new errors_1.RGXInvalidVanillaRegexFlagsError(`[${flag}] is not a valid vanilla regex flag.`, flags);
+        }
+    }
+    // This will not throw, as all vanilla flags are valid regex flags.
+    return normalizeRegexFlags(flags);
+}

package/dist/utils/regexWithFlags.d.ts

@@ -1 +1,2 @@
-export declare function regexWithFlags(exp: RegExp, flags: string, replace?: boolean): RegExp;
+import { ExtRegExp } from "../ExtRegExp";
+export declare function regexWithFlags(exp: RegExp | ExtRegExp, flags: string, replace?: boolean): ExtRegExp;

package/dist/utils/regexWithFlags.js

@@ -3,11 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.regexWithFlags = regexWithFlags;
 const typeGuards_1 = require("../typeGuards");
 const normalizeRegexFlags_1 = require("./normalizeRegexFlags");
+const ExtRegExp_1 = require("../ExtRegExp");
 function regexWithFlags(exp, flags, replace = false) {
     (0, typeGuards_1.assertValidVanillaRegexFlags)(flags);
     if (replace)
-        return new RegExp(exp.source, flags);
+        return new ExtRegExp_1.ExtRegExp(exp.source, flags);
     const existingFlags = exp.flags;
     const newFlags = existingFlags + flags;
-    return new RegExp(exp.source, (0, normalizeRegexFlags_1.normalizeVanillaRegexFlags)(newFlags));
+    return new ExtRegExp_1.ExtRegExp(exp.source, (0, normalizeRegexFlags_1.normalizeVanillaRegexFlags)(newFlags));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/rgx",
-    "version": "4.2.0",
+    "version": "4.3.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",