@ptolemy2002/rgx 4.6.1 → 4.8.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;
@@ -41,7 +44,7 @@ type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // ... see source for full definition
 ;
 
-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 RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT';
 
 type RangeObject = {
     min?: number | null;
@@ -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,8 +143,18 @@ 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.
+### RGXNotSupportedError extends RGXError
+A specific error class for unsupported functionality. This error is thrown when a feature or method is intentionally not supported (as opposed to simply not yet implemented). The error code is set to `NOT_SUPPORTED` on instantiation.
+
+#### Constructor
+```typescript
+constructor(functionality: string, message?: string | null)
+```
+- `functionality` (`string`): A description of the functionality that is not supported.
+- `message` (`string | null`, optional): An optional additional message providing more context. Defaults to `null`.
+
+#### Properties
+- `functionality` (`string`): The description of the unsupported functionality.
 
 ### 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 +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 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 +182,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 +195,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 +208,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 +233,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.
@@ -272,14 +275,17 @@ An abstract base class for creating custom RGX token classes. Subclasses must im
 
 #### Properties
 - `isGroup` (`boolean`): Returns `false` by default. Subclasses can override this to indicate whether the token represents a group.
+- `isRepeatable` (`boolean`): Returns `true` by default. Subclasses can override this to indicate that the token cannot be wrapped in an `RGXRepeatToken`. When `false`, attempting to set this token as the `token` property of an `RGXRepeatToken` (including via `repeat()` or `optional()`) will throw an `RGXNotSupportedError`.
 - `rgxGroupWrap` (`boolean`): Returns `true` by default. Controls whether the resolver wraps this token's resolved output in a non-capturing group. Subclasses can override this to prevent double-wrapping (e.g., when the token already wraps itself in a group).
 
 #### Methods
 - `or(...others: RGXTokenCollectionInput[]) => RGXClassUnionToken`: Creates an `RGXClassUnionToken` that represents a union (alternation) of this token with the provided others. If any of the `others` are `RGXClassUnionToken` instances, their tokens are flattened into the union rather than nested. If `this` is already an `RGXClassUnionToken`, its existing tokens are preserved and the others are appended.
 - `group(args?: RGXGroupTokenArgs) => RGXGroupToken`: Wraps this token in an `RGXGroupToken` with the provided arguments. The `args` parameter defaults to `{}`, which creates a capturing group with no name. This is a convenience method that creates a new `RGXGroupToken` with `this` as the sole token.
-- `repeat(min?: number, max?: number | null) => RGXRepeatToken`: Wraps this token in an `RGXRepeatToken` with the given repetition bounds. `min` defaults to `1`, `max` defaults to `min`. Pass `null` for `max` to allow unlimited repetitions. This is a convenience method that creates a new `RGXRepeatToken` with `this` as the token.
-- `optional() => RGXRepeatToken`: Shorthand for `repeat(0, 1)`. Wraps this token in an `RGXRepeatToken` that matches the token zero or one times.
-- `resolve() => ValidRegexString`: A convenience method that resolves this token by calling `resolveRGXToken(this)`, returning the resolved regex string representation. Since this method is defined on `RGXClassToken`, it is available on all subclasses including `RGXClassUnionToken`, `RGXGroupToken`, and `RGXRepeatToken`.
+- `repeat(min?: number, max?: number | null) => RGXRepeatToken`: Wraps this token in an `RGXRepeatToken` with the given repetition bounds. `min` defaults to `1`, `max` defaults to `min`. Pass `null` for `max` to allow unlimited repetitions. This is a convenience method that creates a new `RGXRepeatToken` with `this` as the token. Throws `RGXNotSupportedError` if called on an `RGXLookaroundToken`, as lookaround assertions cannot be repeated.
+- `optional() => RGXRepeatToken`: Shorthand for `repeat(0, 1)`. Wraps this token in an `RGXRepeatToken` that matches the token zero or one times. Throws `RGXNotSupportedError` if called on an `RGXLookaroundToken`, as lookaround assertions cannot be made optional.
+- `asLookahead(positive?: boolean) => RGXLookaheadToken`: Wraps this token in an `RGXLookaheadToken`. `positive` defaults to `true`. If this token is already an `RGXLookaheadToken`, it is returned as-is without re-wrapping.
+- `asLookbehind(positive?: boolean) => RGXLookbehindToken`: Wraps this token in an `RGXLookbehindToken`. `positive` defaults to `true`. If this token is already an `RGXLookbehindToken`, it is returned as-is without re-wrapping.
+- `resolve() => ValidRegexString`: A convenience method that resolves this token by calling `resolveRGXToken(this)`, returning the resolved regex string representation. Since this method is defined on `RGXClassToken`, it is available on all subclasses including `RGXClassUnionToken`, `RGXGroupToken`, `RGXRepeatToken`, and `RGXLookaroundToken`.
 
 ### RGXClassUnionToken extends RGXClassToken
 A class representing a union (alternation) of RGX tokens. This is typically created via the `or()` method on `RGXClassToken`, but can also be instantiated directly.
@@ -326,8 +332,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,20 +351,74 @@ 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 throw `RGXNotSupportedError` if the value is a class token with `isRepeatable` set to `false`, and 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`.
 
+### RGXLookaroundToken extends RGXClassToken (abstract)
+An abstract base class for lookaround assertion tokens (lookahead and lookbehind). Lookaround assertions match a pattern without consuming characters in the string. Subclasses must implement the `toRgx()`, `negate()`, and `reverse()` methods.
+
+#### Static Properties
+- `check(value: unknown): value is RGXLookaroundToken`: A type guard that checks if the given value is an instance of `RGXLookaroundToken`.
+- `assert(value: unknown): asserts value is RGXLookaroundToken`: An assertion that checks if the given value is an instance of `RGXLookaroundToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(tokens?: RGXTokenCollectionInput, positive?: boolean)
+```
+- `tokens` (`RGXTokenCollectionInput`, optional): The tokens to include in the lookaround. Internally stored as an `RGXTokenCollection` in 'concat' mode. Defaults to an empty array.
+- `positive` (`boolean`, optional): Whether the lookaround is positive (matches if the pattern is present) or negative (matches if the pattern is absent). Defaults to `true`.
+
+#### Properties
+- `tokens` (`RGXTokenCollection`): The internal collection of tokens managed in 'concat' mode.
+- `positive` (`boolean`): Whether the lookaround is positive. Setting this updates `negative` accordingly.
+- `negative` (`boolean`): Whether the lookaround is negative. Setting this updates `positive` accordingly.
+- `isGroup` (`true`): Returns `true` as a constant, indicating this token represents a group.
+- `isRepeatable` (`false`): Returns `false` as a constant, since lookaround assertions cannot be repeated.
+- `rgxGroupWrap` (`false`): Returns `false` as a constant, since the lookaround already wraps itself in a group.
+
+#### Abstract Methods
+- `negate() => RGXLookaroundToken`: Returns a new lookaround token of the same type with the opposite positivity, preserving the original tokens.
+- `reverse() => RGXLookaroundToken`: Returns a new lookaround token of the opposite direction (lookahead becomes lookbehind and vice versa), preserving the original tokens and positivity.
+
+### RGXLookaheadToken extends RGXLookaroundToken
+A class representing a lookahead assertion. Positive lookaheads (`(?=...)`) match if the pattern is present ahead, while negative lookaheads (`(?!...)`) match if the pattern is absent. This is typically created via the `asLookahead()` method on `RGXClassToken`, but can also be instantiated directly.
+
+A function `rgxLookahead` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Static Properties
+- `check(value: unknown): value is RGXLookaheadToken`: A type guard that checks if the given value is an instance of `RGXLookaheadToken`.
+- `assert(value: unknown): asserts value is RGXLookaheadToken`: An assertion that checks if the given value is an instance of `RGXLookaheadToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Methods
+- `negate() => RGXLookaheadToken`: Returns a new `RGXLookaheadToken` with the opposite positivity, preserving the original tokens.
+- `reverse() => RGXLookbehindToken`: Returns a new `RGXLookbehindToken` with the same tokens and positivity.
+- `toRgx() => RegExp`: Resolves the lookahead to a `RegExp`. Positive lookaheads produce `(?=...)` and negative lookaheads produce `(?!...)`.
+
+### RGXLookbehindToken extends RGXLookaroundToken
+A class representing a lookbehind assertion. Positive lookbehinds (`(?<=...)`) match if the pattern is present behind, while negative lookbehinds (`(?<!...)`) match if the pattern is absent. This is typically created via the `asLookbehind()` method on `RGXClassToken`, but can also be instantiated directly.
+
+A function `rgxLookbehind` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Static Properties
+- `check(value: unknown): value is RGXLookbehindToken`: A type guard that checks if the given value is an instance of `RGXLookbehindToken`.
+- `assert(value: unknown): asserts value is RGXLookbehindToken`: An assertion that checks if the given value is an instance of `RGXLookbehindToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Methods
+- `negate() => RGXLookbehindToken`: Returns a new `RGXLookbehindToken` with the opposite positivity, preserving the original tokens.
+- `reverse() => RGXLookaheadToken`: Returns a new `RGXLookaheadToken` with the same tokens and positivity.
+- `toRgx() => RegExp`: Resolves the lookbehind to a `RegExp`. Positive lookbehinds produce `(?<=...)` and negative lookbehinds produce `(?<!...)`.
+
 ### 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.
 
@@ -639,6 +699,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
@@ -832,7 +920,7 @@ Removes duplicate tokens from the provided list using `Set` equality and returns
 function rgxClassInit(): void
 ```
 
-Initializes internal method patches required for `RGXClassToken` subclass methods (such as `or`, `group`, and `repeat`) to work correctly. This function is called automatically when importing from the main module entry point, so you typically do not need to call it yourself. It only needs to be called manually if you import directly from sub-modules.
+Initializes internal method patches required for `RGXClassToken` subclass methods (such as `or`, `group`, `repeat`, `asLookahead`, and `asLookbehind`) to work correctly. This function is called automatically when importing from the main module entry point, so you typically do not need to call it yourself. It only needs to be called manually if you import directly from sub-modules.
 
 ### isInRange
 ```typescript

package/dist/class/base.d.ts

@@ -3,15 +3,20 @@ import { RGXTokenCollectionInput } from "../collection";
 import type { RGXClassUnionToken } from "./union";
 import type { RGXGroupToken, RGXGroupTokenArgs } from "./group";
 import type { RGXRepeatToken } from "./repeat";
+import type { RGXLookaheadToken } from "./lookahead";
+import type { RGXLookbehindToken } from "./lookbehind";
 export declare abstract class RGXClassToken {
     abstract toRgx(): RGXToken;
     static check: (value: unknown) => value is RGXClassToken;
     static assert: (value: unknown) => asserts value is RGXClassToken;
     get isGroup(): boolean;
+    get isRepeatable(): boolean;
     get rgxGroupWrap(): boolean;
     or(...others: RGXTokenCollectionInput[]): RGXClassUnionToken;
     group(args?: RGXGroupTokenArgs): RGXGroupToken;
     repeat(min?: number, max?: number | null): RGXRepeatToken;
     optional(): RGXRepeatToken;
+    asLookahead(positive?: boolean): RGXLookaheadToken;
+    asLookbehind(positive?: boolean): RGXLookbehindToken;
     resolve(): ValidRegexString;
 }

package/dist/class/base.js

@@ -7,6 +7,9 @@ class RGXClassToken {
     get isGroup() {
         return false;
     }
+    get isRepeatable() {
+        return true;
+    }
     get rgxGroupWrap() {
         return true;
     }
@@ -22,6 +25,12 @@ class RGXClassToken {
     optional() {
         return this.repeat(0, 1);
     }
+    asLookahead(positive = true) {
+        throw new errors_1.RGXNotImplementedError('RGXClassToken.asLookahead(positive)', 'call rgxClassInit() first.');
+    }
+    asLookbehind(positive = true) {
+        throw new errors_1.RGXNotImplementedError('RGXClassToken.asLookbehind(positive)', 'call rgxClassInit() first.');
+    }
     resolve() {
         return (0, resolve_1.resolveRGXToken)(this);
     }

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/index.d.ts

@@ -3,3 +3,6 @@ export * from "./base";
 export * from "./union";
 export * from "./group";
 export * from "./repeat";
+export * from "./lookaround";
+export * from "./lookahead";
+export * from "./lookbehind";

package/dist/class/index.js

@@ -19,3 +19,6 @@ __exportStar(require("./base"), exports);
 __exportStar(require("./union"), exports);
 __exportStar(require("./group"), exports);
 __exportStar(require("./repeat"), exports);
+__exportStar(require("./lookaround"), exports);
+__exportStar(require("./lookahead"), exports);
+__exportStar(require("./lookbehind"), exports);

package/dist/class/init.js

@@ -5,6 +5,10 @@ const base_1 = require("./base");
 const union_1 = require("./union");
 const group_1 = require("./group");
 const repeat_1 = require("./repeat");
+const lookaround_1 = require("./lookaround");
+const errors_1 = require("../errors");
+const lookahead_1 = require("./lookahead");
+const lookbehind_1 = require("./lookbehind");
 function rgxClassInit() {
     // Patch RGXClassToken here, Since classes like RGXClassUnionToken are instances of RGXClassToken
     // themselves. If we tried to import RGXClassUnionToken in base.ts, it would cause a circular dependency.
@@ -25,6 +29,18 @@ function rgxClassInit() {
         return new group_1.RGXGroupToken(args, [this]);
     };
     base_1.RGXClassToken.prototype.repeat = function (min = 1, max = min) {
+        if (lookaround_1.RGXLookaroundToken.check(this))
+            throw new errors_1.RGXNotSupportedError("RGXLookaroundToken.repeat()", "Lookaround tokens cannot be repeated or made optional.");
         return new repeat_1.RGXRepeatToken(this, min, max);
     };
+    base_1.RGXClassToken.prototype.asLookahead = function (positive = true) {
+        if (lookahead_1.RGXLookaheadToken.check(this))
+            return this;
+        return new lookahead_1.RGXLookaheadToken([this], positive);
+    };
+    base_1.RGXClassToken.prototype.asLookbehind = function (positive = true) {
+        if (lookbehind_1.RGXLookbehindToken.check(this))
+            return this;
+        return new lookbehind_1.RGXLookbehindToken([this], positive);
+    };
 }

package/dist/class/lookahead.d.ts

@@ -0,0 +1,11 @@
+import { RGXToken } from "../types";
+import { RGXLookaroundToken } from "./lookaround";
+import { RGXLookbehindToken } from "./lookbehind";
+export declare class RGXLookaheadToken extends RGXLookaroundToken {
+    static check: (value: unknown) => value is RGXLookaheadToken;
+    static assert: (value: unknown) => asserts value is RGXLookaheadToken;
+    negate(): RGXLookaheadToken;
+    reverse(): RGXLookbehindToken;
+    toRgx(): RGXToken;
+}
+export declare const rgxLookahead: (tokens?: import("..").RGXTokenCollectionInput, positive?: boolean | undefined) => RGXLookaheadToken;

package/dist/class/lookahead.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxLookahead = exports.RGXLookaheadToken = void 0;
+const internal_1 = require("../internal");
+const lookaround_1 = require("./lookaround");
+const lookbehind_1 = require("./lookbehind");
+class RGXLookaheadToken extends lookaround_1.RGXLookaroundToken {
+    negate() {
+        return new RGXLookaheadToken(this.tokens, !this.positive);
+    }
+    reverse() {
+        return new lookbehind_1.RGXLookbehindToken(this.tokens, this.positive);
+    }
+    toRgx() {
+        let result = this.tokens.toRgx().source;
+        if (this.positive)
+            result = `(?=${result})`;
+        else
+            result = `(?!${result})`;
+        return new RegExp(result);
+    }
+}
+exports.RGXLookaheadToken = RGXLookaheadToken;
+RGXLookaheadToken.check = (0, internal_1.createClassGuardFunction)(RGXLookaheadToken);
+RGXLookaheadToken.assert = (0, internal_1.createAssertClassGuardFunction)(RGXLookaheadToken);
+exports.rgxLookahead = (0, internal_1.createConstructFunction)(RGXLookaheadToken);

package/dist/class/lookaround.d.ts

@@ -0,0 +1,18 @@
+import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
+import { RGXClassToken } from "./base";
+export declare abstract class RGXLookaroundToken extends RGXClassToken {
+    tokens: RGXTokenCollection;
+    _negative: boolean;
+    static check: (value: unknown) => value is RGXLookaroundToken;
+    static assert: (value: unknown) => asserts value is RGXLookaroundToken;
+    get isGroup(): true;
+    get isRepeatable(): false;
+    get rgxGroupWrap(): false;
+    set negative(value: boolean);
+    get negative(): boolean;
+    set positive(value: boolean);
+    get positive(): boolean;
+    constructor(tokens?: RGXTokenCollectionInput, positive?: boolean);
+    abstract negate(): RGXLookaroundToken;
+    abstract reverse(): RGXLookaroundToken;
+}

package/dist/class/lookaround.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXLookaroundToken = void 0;
+const collection_1 = require("../collection");
+const base_1 = require("./base");
+const errors_1 = require("../errors");
+class RGXLookaroundToken extends base_1.RGXClassToken {
+    get isGroup() {
+        return true;
+    }
+    get isRepeatable() {
+        return false;
+    }
+    get rgxGroupWrap() {
+        return false;
+    }
+    set negative(value) {
+        this._negative = value;
+    }
+    get negative() {
+        return this._negative;
+    }
+    set positive(value) {
+        this.negative = !value;
+    }
+    get positive() {
+        return !this.negative;
+    }
+    constructor(tokens = [], positive = true) {
+        super();
+        this._negative = false;
+        this.positive = positive;
+        if (tokens instanceof collection_1.RGXTokenCollection && tokens.mode === 'union')
+            this.tokens = new collection_1.RGXTokenCollection(tokens, 'concat');
+        else
+            this.tokens = new collection_1.RGXTokenCollection(tokens, 'concat');
+    }
+}
+exports.RGXLookaroundToken = RGXLookaroundToken;
+// The createClassGuard function only accepts non-abstract classes, so we 
+// manually define the guard and assertion functions for RGXLookaroundToken here.
+RGXLookaroundToken.check = (value) => value instanceof RGXLookaroundToken;
+RGXLookaroundToken.assert = (value) => {
+    if (!(value instanceof RGXLookaroundToken)) {
+        throw new errors_1.RGXInvalidTokenError("Invalid token type", { type: "custom", values: ["instance of RGXLookaroundToken"] }, value);
+    }
+};

package/dist/class/lookbehind.d.ts

@@ -0,0 +1,12 @@
+import { RGXTokenCollectionInput } from "../collection";
+import { RGXToken } from "../types";
+import { RGXLookaheadToken } from "./lookahead";
+import { RGXLookaroundToken } from "./lookaround";
+export declare class RGXLookbehindToken extends RGXLookaroundToken {
+    static check: (value: unknown) => value is RGXLookbehindToken;
+    static assert: (value: unknown) => asserts value is RGXLookbehindToken;
+    negate(): RGXLookbehindToken;
+    reverse(): RGXLookaheadToken;
+    toRgx(): RGXToken;
+}
+export declare const rgxLookbehind: (tokens?: RGXTokenCollectionInput, positive?: boolean | undefined) => RGXLookbehindToken;

package/dist/class/lookbehind.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxLookbehind = exports.RGXLookbehindToken = void 0;
+const internal_1 = require("../internal");
+const lookahead_1 = require("./lookahead");
+const lookaround_1 = require("./lookaround");
+class RGXLookbehindToken extends lookaround_1.RGXLookaroundToken {
+    negate() {
+        return new RGXLookbehindToken(this.tokens, !this.positive);
+    }
+    reverse() {
+        return new lookahead_1.RGXLookaheadToken(this.tokens, this.positive);
+    }
+    toRgx() {
+        let result = this.tokens.toRgx().source;
+        if (this.positive)
+            result = `(?<=${result})`;
+        else
+            result = `(?<!${result})`;
+        return new RegExp(result);
+    }
+}
+exports.RGXLookbehindToken = RGXLookbehindToken;
+RGXLookbehindToken.check = (0, internal_1.createClassGuardFunction)(RGXLookbehindToken);
+RGXLookbehindToken.assert = (0, internal_1.createAssertClassGuardFunction)(RGXLookbehindToken);
+exports.rgxLookbehind = (0, internal_1.createConstructFunction)(RGXLookbehindToken);

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,11 @@ 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)
+        if ((0, typeGuards_1.isRGXToken)(value, "class") && !value.isRepeatable) {
+            throw new errors_1.RGXNotSupportedError(`Repeating ${value.constructor.name} tokens`, "The token was manually marked as non-repeatable.");
+        }
+        // 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 type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | '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/index.d.ts

@@ -8,3 +8,4 @@ export * from './invalidIdentifier';
 export * from './outOfBounds';
 export * from './invalidFlagTransformerKey';
 export * from './flagTransformerConflict';
+export * from './notSupported';

package/dist/errors/index.js

@@ -24,3 +24,4 @@ __exportStar(require("./invalidIdentifier"), exports);
 __exportStar(require("./outOfBounds"), exports);
 __exportStar(require("./invalidFlagTransformerKey"), exports);
 __exportStar(require("./flagTransformerConflict"), exports);
+__exportStar(require("./notSupported"), exports);

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/notSupported.d.ts

@@ -0,0 +1,6 @@
+import { RGXError } from "./base";
+export declare class RGXNotSupportedError extends RGXError {
+    functionality: string;
+    constructor(functionality: string, message?: string | null);
+    calcMessage(message: string): string;
+}

package/dist/errors/notSupported.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXNotSupportedError = void 0;
+const base_1 = require("./base");
+class RGXNotSupportedError extends base_1.RGXError {
+    constructor(functionality, message = null) {
+        super(message || "", "NOT_SUPPORTED");
+        this.functionality = functionality;
+        this.name = "RGXNotSupportedError";
+    }
+    calcMessage(message) {
+        const result = `${this.functionality} is not supported.`;
+        if (message)
+            return result + ` Additional info: ${message}`;
+        else
+            return result;
+    }
+}
+exports.RGXNotSupportedError = RGXNotSupportedError;

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.8.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",