@ptolemy2002/rgx 4.6.1 → 4.7.0

package/README.md

@@ -10,7 +10,10 @@ type RGXLiteralToken = RegExp;
 type RGXNativeToken = string | number | boolean | RGXNoOpToken;
 type RGXConvertibleToken = { toRgx: () => RGXToken, readonly rgxGroupWrap?: boolean };
 type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
+
 type RGXClassTokenConstructor = new (...args: unknown[]) => RGXClassToken;
+type RGXGroupedToken = RGXToken[] | RGXLiteralToken | (RGXClassToken & { isGroup: true }) | RGXGroupedConvertibleToken;
+type RGXGroupedConvertibleToken = { toRgx: () => RGXGroupedToken, readonly rgxGroupWrap: true };
 
 const validRegexSymbol = Symbol('rgx.ValidRegex');
 type ValidRegexBrandSymbol = typeof validRegexSymbol;
@@ -83,6 +86,9 @@ constructor(message: string, code?: RGXErrorCode)
 #### Properties
 - `code` (`RGXErrorCode`): The error code associated with the error, which can be used to identify the type of error that occurred.
 
+#### Methods
+- `toString() => string`: Returns a formatted string in the format `${name}: ${message}`. Subclasses customize the message portion via internal formatting rather than overriding `toString()` directly, so all `RGXError` subclasses produce consistently formatted strings through this single method.
+
 ### RGXInvalidTokenError extends RGXError
 A specific error class for invalid RGX tokens. This error is thrown when a value fails validation as a specific RGX token type. The error code is set to `INVALID_RGX_TOKEN` on instantiation.
 
@@ -137,9 +143,6 @@ constructor(functionality: string, message?: string | null)
 #### Properties
 - `functionality` (`string`): The description of the unimplemented functionality.
 
-#### Methods
-- `toString() => string`: Returns a formatted string indicating the unimplemented functionality and any additional message.
-
 ### RGXInvalidIdentifierError extends RGXError
 A specific error class for invalid identifiers. This error is thrown when a string fails validation as a valid identifier. The error code is set to `INVALID_IDENTIFIER` on instantiation.
 
@@ -153,9 +156,6 @@ constructor(message: string, got: string)
 #### Properties
 - `got` (`string`): The actual string that was received, which failed validation.
 
-#### 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.
 
@@ -169,9 +169,6 @@ constructor(message: string, got: string)
 #### 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.
 
@@ -185,9 +182,6 @@ constructor(message: string, got: string)
 #### 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.
 
@@ -201,9 +195,6 @@ constructor(message: string, got: 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.
 
@@ -229,7 +220,6 @@ constructor(message: string, got: number, { min, max, inclusiveLeft, inclusiveRi
 - `failedAtMin() => boolean`: Returns `true` if the `got` value is below the minimum bound (respecting `inclusiveLeft`), otherwise `false`. Returns `false` if `min` is `null`.
 - `failedAtMax() => boolean`: Returns `true` if the `got` value is above the maximum bound (respecting `inclusiveRight`), otherwise `false`. Returns `false` if `max` is `null`.
 - `failedAtAny() => boolean`: Returns `true` if the value failed at either the minimum or maximum bound.
-- `toString() => string`: Returns a formatted string indicating the out-of-bounds value, the expected range, and which bound was violated.
 
 ### RGXTokenCollection
 A class representing a collection of RGX tokens. This class manages collections of RGX tokens like an array, but with additional metadata about the collection mode (union or concat). Since `toRgx()` returns a `RegExp`, instances of this class satisfy the `RGXConvertibleToken` interface and can be used directly as tokens in `rgx`, `rgxa`, and other token-accepting functions.
@@ -326,8 +316,8 @@ constructor(args?: RGXGroupTokenArgs, tokens?: RGXTokenCollectionInput)
 - `tokens` (`RGXTokenCollection`): The internal collection of tokens managed in 'concat' mode.
 - `name` (`string | null`): The name of the group. Setting this to a non-null value validates it as a valid identifier via `assertValidIdentifier`.
 - `capturing` (`boolean`): Whether the group is capturing. Any named group is automatically capturing (returns `true` when `name` is not `null`). Setting this to `false` also clears `name` to `null`.
-- `isGroup` (`boolean`): Returns `true`, indicating this token represents a group.
-- `rgxGroupWrap` (`boolean`): Returns `false`, since the group already wraps itself, preventing the resolver from double-wrapping.
+- `isGroup` (`true`): Returns `true` as a constant, indicating this token represents a group.
+- `rgxGroupWrap` (`false`): Returns `false` as a constant, since the group already wraps itself, preventing the resolver from double-wrapping.
 
 #### 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.
@@ -345,16 +335,16 @@ A function `rgxRepeat` is provided with the same parameters as this class' const
 ```typescript
 constructor(token: RGXToken, min?: number, max?: number | null)
 ```
-- `token` (`RGXToken`): The token to repeat. If the token is not already a group (i.e., not an array, `RegExp`, or an `RGXClassToken` with `isGroup` set to `true`), it will be automatically wrapped in an `RGXGroupToken` that is non-capturing.
+- `token` (`RGXToken`): The token to repeat. If the token is not already a grouped token, it will be automatically wrapped in a non-capturing `RGXGroupToken`.
 - `min` (`number`, optional): The minimum number of repetitions. Must be >= 0 and <= `max` (when `max` is not `null`). Non-integer values are floored. Defaults to `1`.
 - `max` (`number | null`, optional): The maximum number of repetitions. Must be >= `min` when not `null`. Non-integer values are floored. Pass `null` for unlimited repetitions. Defaults to `min`.
 
 #### Properties
-- `token` (`RGXToken`): The token being repeated. Setting this will automatically wrap non-group tokens in an `RGXGroupToken`.
+- `token` (`RGXGroupedToken`): The token being repeated. Setting this will automatically wrap non-grouped tokens in a non-capturing `RGXGroupToken`.
 - `min` (`number`): The minimum number of repetitions. Setting this validates that the value is >= 0 and <= `max` (when `max` is not `null`), and floors non-integer values. Throws `RGXOutOfBoundsError` if validation fails.
 - `max` (`number | null`): The maximum number of repetitions. Setting this validates that the value is >= `min` when not `null`, and floors non-integer values. Pass `null` for unlimited. Throws `RGXOutOfBoundsError` if validation fails.
 - `repeaterSuffix` (`string`): Returns the regex quantifier suffix based on the current `min` and `max` values: `*` for `{0,}`, `+` for `{1,}`, `?` for `{0,1}`, `{n}` for exact repetitions, `{n,}` for minimum-only, `{n,m}` for a range, or an empty string for `{1,1}` (exactly once, no quantifier needed).
-- `rgxGroupWrap` (`boolean`): Returns `false`, since the quantifier suffix binds tightly to the preceding group and does not need additional wrapping.
+- `rgxGroupWrap` (`false`): Returns `false` as a constant, since the quantifier suffix binds tightly to the preceding group and does not need additional wrapping.
 
 #### Methods
 - `toRgx() => RGXToken`: Resolves the repeat token to a `RegExp` by resolving the inner token and appending the `repeaterSuffix`. Returns `null` (a no-op) when both `min` and `max` are `0`.
@@ -639,6 +629,34 @@ Asserts that the given value is a valid RGX token, optionally narrowed to a spec
 #### Returns
 - `void`: This function does not return a value, but will throw an error if the assertion fails.
 
+### isRGXGroupedToken
+```typescript
+function isRGXGroupedToken(value: unknown, contentCheck?: boolean): value is RGXGroupedToken
+```
+
+Checks if the given value is a grouped token — a token that is implicitly or explicitly a group. Arrays and literal tokens (`RegExp`) are implicitly groups. Class tokens are only groups if they have the `isGroup` property set to `true`. Convertible tokens are groups if they have `rgxGroupWrap` set to `true` and their `toRgx()` method returns a grouped token.
+
+#### Parameters
+  - `value` (`unknown`): The value to check.
+  - `contentCheck` (`boolean`, optional): Whether to validate the contents of array tokens and the return values of convertible tokens. Defaults to `true`. When `false`, arrays are accepted without checking their elements, and convertible tokens with `rgxGroupWrap` set to `true` are accepted without checking their `toRgx()` return value.
+
+#### Returns
+- `boolean`: `true` if the value is a grouped token, otherwise `false`.
+
+### assertRGXGroupedToken
+```typescript
+function assertRGXGroupedToken(value: unknown, contentCheck?: boolean): asserts value is RGXGroupedToken
+```
+
+Asserts that the given value is a grouped token. Uses the same logic as `isRGXGroupedToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Parameters
+  - `value` (`unknown`): The value to assert.
+  - `contentCheck` (`boolean`, optional): Whether to validate the contents of array tokens and the return values of convertible tokens. Defaults to `true`. When `false`, arrays are accepted without checking their elements, and convertible tokens with `rgxGroupWrap` set to `true` are accepted without checking their `toRgx()` return value.
+
+#### Returns
+- `void`: This function does not return a value, but will throw an error if the assertion fails.
+
 ### isValidRegexString
 ```typescript
 function isValidRegexString(value: string): value is ValidRegexString

package/dist/class/group.d.ts

@@ -14,8 +14,8 @@ export declare class RGXGroupToken extends RGXClassToken {
     set name(value: string | null);
     get capturing(): boolean;
     set capturing(value: boolean);
-    get isGroup(): boolean;
-    get rgxGroupWrap(): boolean;
+    get isGroup(): true;
+    get rgxGroupWrap(): false;
     constructor({ name, capturing }?: RGXGroupTokenArgs, tokens?: RGXTokenCollectionInput);
     toRgx(): RegExp;
 }

package/dist/class/repeat.d.ts

@@ -1,7 +1,7 @@
-import { RGXToken } from "../types";
+import { RGXGroupedToken, RGXToken } from "../types";
 import { RGXClassToken } from "./base";
 export declare class RGXRepeatToken extends RGXClassToken {
-    _token: RGXToken;
+    _token: RGXGroupedToken;
     _min: number;
     _max: number | null;
     static check: (value: unknown) => value is RGXRepeatToken;
@@ -12,7 +12,7 @@ export declare class RGXRepeatToken extends RGXClassToken {
     set max(value: number | null);
     get token(): RGXToken;
     set token(value: RGXToken);
-    get rgxGroupWrap(): boolean;
+    get rgxGroupWrap(): false;
     constructor(token: RGXToken, min?: number, max?: number | null);
     get repeaterSuffix(): string;
     toRgx(): RGXToken;

package/dist/class/repeat.js

@@ -30,12 +30,8 @@ class RGXRepeatToken extends base_1.RGXClassToken {
         return this._token;
     }
     set token(value) {
-        // Arrays and Literals are implicitly grouped.
-        const isGroup = (0, typeGuards_1.isRGXToken)(value, "array") ||
-            (0, typeGuards_1.isRGXToken)(value, "literal") ||
-            ((0, typeGuards_1.isRGXToken)(value, "class") && value.isGroup);
-        // Make sure we are always working with a group token.
-        if (isGroup)
+        // Make sure we are always working with a grouped token.
+        if ((0, typeGuards_1.isRGXGroupedToken)(value))
             this._token = value;
         else
             this._token = new group_1.RGXGroupToken({ capturing: false }, value);

package/dist/errors/base.d.ts

@@ -1,5 +1,10 @@
 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 {
+    _message: string;
     code: RGXErrorCode;
+    get message(): string;
+    set message(value: string);
     constructor(message: string, code?: RGXErrorCode);
+    calcMessage(message: string): string;
+    toString(): string;
 }

package/dist/errors/base.js

@@ -2,13 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RGXError = void 0;
 class RGXError extends Error {
+    get message() {
+        return this.calcMessage(this._message);
+    }
+    set message(value) {
+        this._message = value;
+    }
     constructor(message, code) {
-        super(message);
+        super();
         this.code = 'UNKNOWN';
         this.name = 'RGXError';
+        this.message = message;
         if (code) {
             this.code = code;
         }
     }
+    calcMessage(message) {
+        return message;
+    }
+    toString() {
+        return `${this.name}: ${this.message}`;
+    }
 }
 exports.RGXError = RGXError;

package/dist/errors/flagTransformerConflict.d.ts

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

package/dist/errors/flagTransformerConflict.js

@@ -8,8 +8,8 @@ class RGXFlagTransformerConflictError extends errors_1.RGXError {
         this.name = 'RGXFlagTransformerConflictError';
         this.got = got;
     }
-    toString() {
-        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    calcMessage(message) {
+        return `${message}; Got: ${JSON.stringify(this.got)}`;
     }
 }
 exports.RGXFlagTransformerConflictError = RGXFlagTransformerConflictError;

package/dist/errors/invalidFlagTransformerKey.d.ts

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

package/dist/errors/invalidFlagTransformerKey.js

@@ -8,8 +8,8 @@ class RGXInvalidFlagTransformerKeyError extends errors_1.RGXError {
         this.name = 'RGXInvalidFlagTransformerKeyError';
         this.got = got;
     }
-    toString() {
-        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    calcMessage(message) {
+        return `${message}; Got: ${JSON.stringify(this.got)}`;
     }
 }
 exports.RGXInvalidFlagTransformerKeyError = RGXInvalidFlagTransformerKeyError;

package/dist/errors/invalidIdentifier.d.ts

@@ -2,5 +2,5 @@ import { RGXError } from "./";
 export declare class RGXInvalidIdentifierError extends RGXError {
     got: string;
     constructor(message: string, got: string);
-    toString(): string;
+    calcMessage(message: string): string;
 }

package/dist/errors/invalidIdentifier.js

@@ -8,8 +8,8 @@ class RGXInvalidIdentifierError extends errors_1.RGXError {
         this.name = 'RGXInvalidIdentifierError';
         this.got = got;
     }
-    toString() {
-        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    calcMessage(message) {
+        return `${message}; Got: ${JSON.stringify(this.got)}`;
     }
 }
 exports.RGXInvalidIdentifierError = RGXInvalidIdentifierError;

package/dist/errors/invalidRegexFlags.d.ts

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

package/dist/errors/invalidRegexFlags.js

@@ -8,8 +8,8 @@ class RGXInvalidRegexFlagsError extends errors_1.RGXError {
         this.name = 'RGXInvalidRegexFlagsError';
         this.got = got;
     }
-    toString() {
-        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    calcMessage(message) {
+        return `${message}; Got: ${JSON.stringify(this.got)}`;
     }
 }
 exports.RGXInvalidRegexFlagsError = RGXInvalidRegexFlagsError;

package/dist/errors/invalidRegexString.d.ts

@@ -2,5 +2,5 @@ import { RGXError } from "./";
 export declare class RGXInvalidRegexStringError extends RGXError {
     got: string;
     constructor(message: string, got: string);
-    toString(): string;
+    calcMessage(message: string): string;
 }

package/dist/errors/invalidRegexString.js

@@ -8,8 +8,8 @@ class RGXInvalidRegexStringError extends errors_1.RGXError {
         this.name = 'RGXInvalidRegexStringError';
         this.got = got;
     }
-    toString() {
-        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    calcMessage(message) {
+        return `${message}; Got: ${JSON.stringify(this.got)}`;
     }
 }
 exports.RGXInvalidRegexStringError = RGXInvalidRegexStringError;

package/dist/errors/invalidToken.d.ts

@@ -12,5 +12,5 @@ export declare class RGXInvalidTokenError extends RGXError {
     got: unknown;
     setExpected(expected: ExpectedTokenType | null): string;
     constructor(message: string, expected: ExpectedTokenType | null, got: unknown);
-    toString(): string;
+    calcMessage(message: string): string;
 }

package/dist/errors/invalidToken.js

@@ -6,7 +6,7 @@ const js_utils_1 = require("@ptolemy2002/js-utils");
 const class_1 = require("../class");
 const tokenExpectationMap = {
     'no-op': ['null', 'undefined'],
-    'literal': ['RegExp'],
+    'literal': ['RegExp', 'ExtRegExp'],
     'native': ['string', 'number', 'boolean', 'null', 'undefined'],
     'convertible': ['object with a toRgx method that returns a valid native/literal token or an array of valid native/literal tokens'],
     'array': ['array of native/literal/convertible tokens'],
@@ -45,9 +45,9 @@ class RGXInvalidTokenError extends errors_1.RGXError {
         this.got = got;
         this.setExpected(expected);
     }
-    toString() {
+    calcMessage(message) {
         const gotString = class_1.RGXClassToken.check(this.got) ? `instance of ${this.got.constructor.name}` : JSON.stringify(this.got);
-        return `${this.name}: ${this.message}; Expected: ${this.expected}; Got: [${gotString}]`;
+        return `${message}; Expected: ${this.expected}; Got: [${gotString}]`;
     }
 }
 exports.RGXInvalidTokenError = RGXInvalidTokenError;

package/dist/errors/invalidVanillaRegexFlags.d.ts

@@ -2,5 +2,5 @@ import { RGXError } from "./";
 export declare class RGXInvalidVanillaRegexFlagsError extends RGXError {
     got: string;
     constructor(message: string, got: string);
-    toString(): string;
+    calcMessage(message: string): string;
 }

package/dist/errors/invalidVanillaRegexFlags.js

@@ -8,8 +8,8 @@ class RGXInvalidVanillaRegexFlagsError extends errors_1.RGXError {
         this.name = 'RGXInvalidVanillaRegexFlagsError';
         this.got = got;
     }
-    toString() {
-        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    calcMessage(message) {
+        return `${message}; Got: ${JSON.stringify(this.got)}`;
     }
 }
 exports.RGXInvalidVanillaRegexFlagsError = RGXInvalidVanillaRegexFlagsError;

package/dist/errors/notImplemented.d.ts

@@ -2,5 +2,5 @@ import { RGXError } from "./base";
 export declare class RGXNotImplementedError extends RGXError {
     functionality: string;
     constructor(functionality: string, message?: string | null);
-    toString(): string;
+    calcMessage(message: string): string;
 }

package/dist/errors/notImplemented.js

@@ -8,10 +8,10 @@ class RGXNotImplementedError extends base_1.RGXError {
         this.functionality = functionality;
         this.name = "RGXNotImplementedError";
     }
-    toString() {
-        const result = `${this.name}: ${this.functionality} is not implemented yet.`;
-        if (this.message)
-            return result + ` Additional info: ${this.message}`;
+    calcMessage(message) {
+        const result = `${this.functionality} is not implemented yet.`;
+        if (message)
+            return result + ` Additional info: ${message}`;
         else
             return result;
     }

package/dist/errors/outOfBounds.d.ts

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

package/dist/errors/outOfBounds.js

@@ -41,7 +41,7 @@ class RGXOutOfBoundsError extends base_1.RGXError {
     failedAtAny() {
         return this.failedAtMin() || this.failedAtMax();
     }
-    toString() {
+    calcMessage(message) {
         const rangeParts = [];
         if (this.min !== null) {
             if (this.inclusiveLeft)
@@ -58,7 +58,7 @@ class RGXOutOfBoundsError extends base_1.RGXError {
         const rangeStr = rangeParts.join(" and ");
         // Determine which one was failed
         if (!this.failedAtAny()) {
-            return `${this.name}: ${this.message}; Got: [${this.got}]; Expected: [${rangeStr}]`;
+            return `${message}; Got: [${this.got}]; Expected: [${rangeStr}]`;
         }
         else if (this.failedAtMin()) {
             let thirdPart;
@@ -66,7 +66,7 @@ class RGXOutOfBoundsError extends base_1.RGXError {
                 thirdPart = `${this.got} == ${this.min}`;
             else
                 thirdPart = `${this.got} < ${this.min}`;
-            return `${this.name}: ${this.message}; Got: [${this.got}]; Expected: [${rangeStr}]; ${thirdPart}`;
+            return `${message}; Got: [${this.got}]; Expected: [${rangeStr}]; ${thirdPart}`;
         }
         else {
             let thirdPart;
@@ -74,7 +74,7 @@ class RGXOutOfBoundsError extends base_1.RGXError {
                 thirdPart = `${this.got} == ${this.max}`;
             else
                 thirdPart = `${this.got} > ${this.max}`;
-            return `${this.name}: ${this.message}; Got: [${this.got}]; Expected: [${rangeStr}]; ${thirdPart}`;
+            return `${message}; Got: [${this.got}]; Expected: [${rangeStr}]; ${thirdPart}`;
         }
     }
 }

package/dist/typeGuards.d.ts

@@ -16,6 +16,8 @@ export declare function rgxTokenTypeToFlat(type: t.RGXTokenType): t.RGXTokenType
 export declare function rgxTokenTypeGuardInputToFlat(type: t.RGXTokenTypeGuardInput): t.RGXTokenTypeFlat | null;
 export declare function isRGXToken<T extends t.RGXTokenTypeGuardInput = null>(value: unknown, type?: T, matchLength?: boolean): value is t.RGXTokenFromType<T>;
 export declare function assertRGXToken<T extends t.RGXTokenTypeGuardInput = null>(value: unknown, type?: T, matchLength?: boolean): asserts value is t.RGXTokenFromType<T>;
+export declare function isRGXGroupedToken(value: unknown, contentCheck?: boolean): value is t.RGXGroupedToken;
+export declare function assertRGXGroupedToken(value: unknown, contentCheck?: boolean): asserts value is t.RGXGroupedToken;
 export declare function isValidRegexString(value: string): value is t.ValidRegexString;
 export declare function assertValidRegexString(value: string): asserts value is t.ValidRegexString;
 export declare function isValidVanillaRegexFlags(value: string): value is t.ValidVanillaRegexFlags;

package/dist/typeGuards.js

@@ -53,6 +53,8 @@ exports.rgxTokenTypeToFlat = rgxTokenTypeToFlat;
 exports.rgxTokenTypeGuardInputToFlat = rgxTokenTypeGuardInputToFlat;
 exports.isRGXToken = isRGXToken;
 exports.assertRGXToken = assertRGXToken;
+exports.isRGXGroupedToken = isRGXGroupedToken;
+exports.assertRGXGroupedToken = assertRGXGroupedToken;
 exports.isValidRegexString = isValidRegexString;
 exports.assertValidRegexString = assertValidRegexString;
 exports.isValidVanillaRegexFlags = isValidVanillaRegexFlags;
@@ -193,6 +195,19 @@ function assertRGXToken(value, type = null, matchLength = true) {
         throw new e.RGXInvalidTokenError("Invalid RGX token", flatType === null ? null : { type: "tokenType", values: [flatType] }, value);
     }
 }
+function isRGXGroupedToken(value, contentCheck = true) {
+    // Arrays and Literals are implicitly groups.
+    // Classes are only groups if they have the isGroup property set to true.
+    return (isRGXArrayToken(value, contentCheck) ||
+        isRGXToken(value, "literal") ||
+        (isRGXToken(value, "class") && value.isGroup) ||
+        (isRGXConvertibleToken(value, false) && value.rgxGroupWrap === true && (!contentCheck || isRGXGroupedToken(value.toRgx()))));
+}
+function assertRGXGroupedToken(value, contentCheck = true) {
+    if (!isRGXGroupedToken(value, contentCheck)) {
+        throw new e.RGXInvalidTokenError("Invalid group token, class token is not group, or convertible token is not group wrapped.", { type: "custom", values: ['array', 'literal', 'class', 'convertible'] }, value);
+    }
+}
 function isValidRegexString(value) {
     try {
         new RegExp(value);

package/dist/types.d.ts

@@ -11,6 +11,13 @@ export type RGXConvertibleToken = {
 };
 export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 export type RGXClassTokenConstructor = new (...args: unknown[]) => RGXClassToken;
+export type RGXGroupedToken = RGXToken[] | RGXLiteralToken | (RGXClassToken & {
+    isGroup: true;
+}) | RGXGroupedConvertibleToken;
+export type RGXGroupedConvertibleToken = {
+    toRgx: () => RGXGroupedToken;
+    readonly rgxGroupWrap: true;
+};
 export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | RGXTokenType[];
 export type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
 export type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];

package/package.json

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