@ptolemy2002/rgx 3.1.1 → 4.1.0

package/README.md

@@ -8,7 +8,7 @@ import { Branded } from "@ptolemy2002/ts-brand-utils";
 type RGXNoOpToken = null | undefined;
 type RGXLiteralToken = RegExp;
 type RGXNativeToken = string | number | boolean | RGXNoOpToken;
-type RGXConvertibleToken = { toRgx: () => RGXToken };
+type RGXConvertibleToken = { toRgx: () => RGXToken, readonly rgxGroupWrap?: boolean };
 type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 type RGXClassTokenConstructor = new (...args: unknown[]) => RGXClassToken;
 
@@ -20,6 +20,10 @@ const validVanillaRegexFlagsSymbol = Symbol('rgx.ValidVanillaRegexFlags');
 type ValidVanillaRegexFlagsBrandSymbol = typeof validVanillaRegexFlagsSymbol;
 type ValidVanillaRegexFlags = Branded<string, [ValidVanillaRegexFlagsBrandSymbol]>;
 
+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[];
@@ -30,7 +34,7 @@ type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // ... see source for full definition
 ;
 
-type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED';
+type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'INVALID_IDENTIFIER';
 type ExpectedTokenType = {
     type: "tokenType";
     values: RGXTokenTypeFlat[];
@@ -42,6 +46,11 @@ type RGXTokenCollectionMode = 'union' | 'concat';
 type RGXTokenCollectionInput = RGXToken | RGXTokenCollection;
 
 type RGXUnionInsertionPosition = 'prefix' | 'suffix';
+
+type RGXGroupTokenArgs = {
+    name?: string | null;
+    capturing?: boolean;
+};
 ```
 
 ## Classes
@@ -117,6 +126,22 @@ constructor(functionality: string, message?: string | null)
 #### 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.
+
+#### 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 identifier and the reason for failure.
+
 ### 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.
 
@@ -132,6 +157,7 @@ constructor(tokens: RGXTokenCollectionInput = [], mode: RGXTokenCollectionMode =
 #### Properties
 - `tokens` (`RGXToken[]`): The array of RGX tokens managed by the collection. In almost all cases, use `getTokens()` instead of accessing this property directly, as it will be copied to prevent external mutation.
 - `mode` (`RGXTokenCollectionMode`): The mode of the collection, either 'union' or 'concat'. This determines how the tokens in the collection will be resolved when `toRgx()` is called.
+- `resolve() => ValidRegexString`: A convenience method that resolves this collection by calling `resolveRGXToken(this)`, returning the resolved regex string representation.
 - `toRgx() => RegExp`: A method that resolves the collection to a `RegExp` object based on the collection mode. In 'union' mode, the tokens are resolved as alternatives (using the `|` operator), while in 'concat' mode, the tokens are resolved as concatenated together. No flags are applied to the resulting `RegExp`. Since this method returns a `RegExp` (which is `RGXLiteralToken`), `RGXTokenCollection` instances satisfy the `RGXConvertibleToken` interface and can be used directly as tokens in `rgx`, `rgxa`, and other token-accepting functions.
 - `getTokens() => RGXToken[]`: A method that returns a copy of the array of RGX tokens managed by the collection. This is used to prevent external mutation of the internal `tokens` array.
 - `toArray() => RGXToken[]`: An alias for `getTokens()`, provided for convenience.
@@ -141,25 +167,37 @@ constructor(tokens: RGXTokenCollectionInput = [], mode: RGXTokenCollectionMode =
 
 Standard array properties and methods like `length`, `push`, `pop`, etc. are implemented to work with the internal `tokens` array, but providing collection instances instead of raw arrays when relevant (e.g., `map` has the third parameter typed as `RGXTokenCollection` instead of `RGXToken[]`).
 
+#### Static Properties
+- `check(value: unknown): value is RGXTokenCollection`: A type guard that checks if the given value is an instance of `RGXTokenCollection`.
+- `assert(value: unknown): asserts value is RGXTokenCollection`: An assertion that checks if the given value is an instance of `RGXTokenCollection`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
 ### RGXClassToken (abstract)
 An abstract base class for creating custom RGX token classes. Subclasses must implement the `toRgx()` method, which returns any valid `RGXToken` (including other convertible tokens, allowing for recursive structures).
 
-Two type guards are provided for this class: `isRgxClassToken` to check if a value is an instance of `RGXClassToken`, and `assertRgxClassToken` to assert that a value is an instance of `RGXClassToken` (throwing an `InvalidTokenError` if the assertion fails). Both of these take a single parameter of type `unknown` for the value.
+#### Static Properties
+- `check(value: unknown): value is RGXClassToken`: A type guard that checks if the given value is an instance of `RGXClassToken`.
+- `assert(value: unknown): asserts value is RGXClassToken`: An assertion that checks if the given value is an instance of `RGXClassToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
 
 #### Abstract Methods
 - `toRgx() => RGXToken`: Must be implemented by subclasses to return the token's regex representation as any valid RGX token (native, literal, convertible, or array of tokens).
 
 #### Properties
 - `isGroup` (`boolean`): Returns `false` by default. Subclasses can override this to indicate whether the token represents a group.
+- `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.
-- `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`.
+- `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.
+- `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` and `RGXGroupToken`.
 
 ### 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.
 
-A function `rgxClassUnion` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword. Two type guards are provided for this class: `isRgxClassUnionToken` to check if a value is an instance of `RGXClassUnionToken`, and `assertRgxClassUnionToken` to assert that a value is an instance of `RGXClassUnionToken` (throwing an `InvalidTokenError` if the assertion fails). Both of these take a single parameter of type `unknown` for the value.
+A function `rgxClassUnion` 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 RGXClassUnionToken`: A type guard that checks if the given value is an instance of `RGXClassUnionToken`.
+- `assert(value: unknown): asserts value is RGXClassUnionToken`: An assertion that checks if the given value is an instance of `RGXClassUnionToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
 
 #### Constructor
 ```typescript
@@ -177,6 +215,34 @@ constructor(tokens: RGXTokenCollectionInput = [])
 - `cleanTokens() => this`: Expands any nested union tokens and removes duplicates from the internal token collection. Returns `this` for chaining. Called automatically during construction and after `add` or `concat`.
 - `toRgx() => RegExp`: Resolves the union by calling `toRgx()` on the internal `RGXTokenCollection`, returning a `RegExp`.
 
+### RGXGroupToken extends RGXClassToken
+A class representing a group (capturing, non-capturing, or named) wrapping one or more RGX tokens. This is typically created via the `group()` method on `RGXClassToken`, but can also be instantiated directly.
+
+A function `rgxGroup` 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 RGXGroupToken`: A type guard that checks if the given value is an instance of `RGXGroupToken`.
+- `assert(value: unknown): asserts value is RGXGroupToken`: An assertion that checks if the given value is an instance of `RGXGroupToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(args?: RGXGroupTokenArgs, tokens?: RGXTokenCollectionInput)
+```
+- `args` (`RGXGroupTokenArgs`, optional): An object specifying the group configuration. Defaults to `{}`.
+  - `name` (`string | null`, optional): The name of the group for named capture groups. Must be a valid identifier (validated via `assertValidIdentifier`). Defaults to `null`.
+  - `capturing` (`boolean`, optional): Whether the group is capturing. Defaults to `true`. Setting this to `false` also clears any `name`.
+- `tokens` (`RGXTokenCollectionInput`, optional): The tokens to be wrapped by the group. Internally stored as an `RGXTokenCollection` in 'concat' mode. Defaults to an empty array.
+
+#### Properties
+- `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.
+
+#### 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.
+
 ## Functions
 The following functions are exported by the library:
 
@@ -263,7 +329,7 @@ Asserts that the given value is a native token (string, number, boolean, or no-o
 function isRGXConvertibleToken(value: unknown, returnCheck?: boolean): value is RGXConvertibleToken
 ```
 
-Checks if the given value is a convertible token (an object with a `toRgx` method). When `returnCheck` is `true` (the default), also validates that `toRgx` is callable and returns a valid `RGXToken` (which can be any RGX token type, including other convertible tokens, allowing for recursive structures).
+Checks if the given value is a convertible token (an object with a `toRgx` method). If the `rgxGroupWrap` property is present, it must be a boolean; otherwise, the check fails. When `returnCheck` is `true` (the default), also validates that `toRgx` is callable and returns a valid `RGXToken` (which can be any RGX token type, including other convertible tokens, allowing for recursive structures).
 
 #### Parameters
   - `value` (`unknown`): The value to check.
@@ -276,7 +342,7 @@ Checks if the given value is a convertible token (an object with a `toRgx` metho
 ```typescript
 function assertRGXConvertibleToken(value: unknown, returnCheck?: boolean): asserts value is RGXConvertibleToken
 ```
-Asserts that the given value is a convertible token (an object with a `toRgx` method). When `returnCheck` is `true` (the default), also validates that `toRgx` is callable and returns a valid `RGXToken` (which can be any RGX token type, including other convertible tokens, allowing for recursive structures). If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+Asserts that the given value is a convertible token (an object with a `toRgx` method). If the `rgxGroupWrap` property is present, it must be a boolean; otherwise, the assertion fails. When `returnCheck` is `true` (the default), also validates that `toRgx` is callable and returns a valid `RGXToken` (which can be any RGX token type, including other convertible tokens, allowing for recursive structures). If the assertion fails, an `RGXInvalidTokenError` will be thrown.
 
 #### Parameters
   - `value` (`unknown`): The value to assert.
@@ -489,6 +555,30 @@ Asserts that the given string is a valid combination of vanilla regex flags (g,
 #### Returns
 - `void`: This function does not return a value, but will throw an error if the assertion fails.
 
+### isValidIdentifier
+```typescript
+function isValidIdentifier(value: string): value is ValidIdentifier
+```
+Checks if the given string is a valid identifier, used for group names and backreferences. Valid identifiers contain only letters, digits, dollar signs, and underscores, and cannot start with a digit.
+
+#### Parameters
+  - `value` (`string`): The string to check.
+
+#### Returns
+- `boolean`: `true` if the string is a valid identifier, otherwise `false`.
+
+### assertValidIdentifier
+```typescript
+function assertValidIdentifier(value: string): asserts value is ValidIdentifier
+```
+Asserts that the given string is a valid identifier, used for group names and backreferences. Valid identifiers contain only letters, digits, dollar signs, and underscores, and cannot start with a digit. If the assertion fails, an `RGXInvalidIdentifierError` will be thrown.
+
+#### Parameters
+  - `value` (`string`): The string to assert.
+
+#### Returns
+- `void`: This function does not return a value, but will throw an error if the assertion fails.
+
 ### escapeRegex
 ```typescript
 function escapeRegex(value: string): ValidRegexString
@@ -504,14 +594,17 @@ Escapes special regex characters in the given string and brands the result as a
 
 ### resolveRGXToken
 ```typescript
-function resolveRGXToken(token: RGXToken, groupWrap?: boolean): ValidRegexString
+function resolveRGXToken(token: RGXToken, groupWrap?: boolean, topLevel?: boolean): ValidRegexString
 ```
 
 Resolves an RGX token to a string. No-op tokens resolve to an empty string, literal tokens are included as-is (wrapped in a non-capturing group when `groupWrap` is `true`), native tokens are converted to strings and escaped, convertible tokens are converted using their `toRgx` method and then resolved recursively, and arrays of tokens are resolved as unions of their resolved elements (repeats removed, placed in a non-capturing group when `groupWrap` is `true`).
 
+For convertible tokens, if the token has an `rgxGroupWrap` property, that value always takes precedence. If `rgxGroupWrap` is not present, the behavior depends on whether the call is top-level: at the top level, the `groupWrap` parameter is passed through; in recursive calls, it falls back to `true` regardless of the `groupWrap` parameter. This ensures that the caller's `groupWrap` preference only affects the outermost convertible token and does not leak into deeply nested resolution.
+
 #### Parameters
   - `token` (`RGXToken`): The RGX token to resolve.
-  - `groupWrap` (`boolean`, optional): Whether to wrap literal tokens and array unions in non-capturing groups (`(?:...)`). Defaults to `true`. When `false`, literals use their raw source and array unions omit the wrapping group. The `groupWrap` preference is passed through to recursive calls for convertible tokens, but array union elements always use `groupWrap=true` internally.
+  - `groupWrap` (`boolean`, optional): Whether to wrap literal tokens and array unions in non-capturing groups (`(?:...)`). Defaults to `true`. When `false`, literals use their raw source and array unions omit the wrapping group. For convertible tokens, the token's `rgxGroupWrap` property always takes precedence; otherwise, this value is only passed through at the top level (in recursive calls it falls back to `true`). Array union elements always use `groupWrap=true` internally.
+  - `topLevel` (`boolean`, optional): Tracks whether the current call is the initial (top-level) invocation. Defaults to `true`. **Warning**: This parameter is intended for internal use by the resolver's own recursion. External callers should not set this parameter, as doing so may produce unexpected wrapping behavior.
 
 #### Returns
 - `ValidRegexString`: The resolved string representation of the RGX token. This is guaranteed to be a valid regex string, as convertible tokens are validated to only produce valid regex strings or arrays of valid regex strings.
@@ -605,7 +698,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`) 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` and `group`) 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.
 
 ## Peer Dependencies
 - `@ptolemy2002/immutability-utils` ^2.0.0

package/dist/class/base.d.ts

@@ -1,11 +1,14 @@
 import { RGXToken, ValidRegexString } from "../types";
 import { RGXTokenCollectionInput } from "../collection";
 import type { RGXClassUnionToken } from "./union";
+import type { RGXGroupToken, RGXGroupTokenArgs } from "./group";
 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 rgxGroupWrap(): boolean;
     or(...others: RGXTokenCollectionInput[]): RGXClassUnionToken;
+    group(args?: RGXGroupTokenArgs): RGXGroupToken;
     resolve(): ValidRegexString;
 }
-export declare const isRgxClassToken: (value: unknown) => value is RGXClassToken;
-export declare const assertRgxClassToken: (value: unknown) => asserts value is RGXClassToken;

package/dist/class/base.js

@@ -1,15 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertRgxClassToken = exports.isRgxClassToken = exports.RGXClassToken = void 0;
+exports.RGXClassToken = void 0;
 const errors_1 = require("../errors");
 const resolve_1 = require("../resolve");
 class RGXClassToken {
     get isGroup() {
         return false;
     }
+    get rgxGroupWrap() {
+        return true;
+    }
     or(...others) {
         throw new errors_1.RGXNotImplementedError('RGXClassToken.or(...others)', 'call rgxClassInit() first.');
     }
+    group(args = {}) {
+        throw new errors_1.RGXNotImplementedError('RGXClassToken.group(args)', 'call rgxClassInit() first.');
+    }
     resolve() {
         return (0, resolve_1.resolveRGXToken)(this);
     }
@@ -17,11 +23,9 @@ class RGXClassToken {
 exports.RGXClassToken = RGXClassToken;
 // The createClassGuard function only accepts non-abstract classes, so we 
 // manually define the guard and assertion functions for RGXClassToken here.
-const isRgxClassToken = (value) => value instanceof RGXClassToken;
-exports.isRgxClassToken = isRgxClassToken;
-const assertRgxClassToken = (value) => {
+RGXClassToken.check = (value) => value instanceof RGXClassToken;
+RGXClassToken.assert = (value) => {
     if (!(value instanceof RGXClassToken)) {
         throw new errors_1.RGXInvalidTokenError("Invalid token type", { type: "custom", values: ["instance of RGXClassToken"] }, value);
     }
 };
-exports.assertRgxClassToken = assertRgxClassToken;

package/dist/class/group.d.ts

@@ -0,0 +1,22 @@
+import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
+import { RGXClassToken } from "./base";
+export type RGXGroupTokenArgs = {
+    name?: string | null;
+    capturing?: boolean;
+};
+export declare class RGXGroupToken extends RGXClassToken {
+    tokens: RGXTokenCollection;
+    _name: string | null;
+    _capturing: boolean;
+    static check: (value: unknown) => value is RGXGroupToken;
+    static assert: (value: unknown) => asserts value is RGXGroupToken;
+    get name(): string | null;
+    set name(value: string | null);
+    get capturing(): boolean;
+    set capturing(value: boolean);
+    get isGroup(): boolean;
+    get rgxGroupWrap(): boolean;
+    constructor({ name, capturing }?: RGXGroupTokenArgs, tokens?: RGXTokenCollectionInput);
+    toRgx(): RegExp;
+}
+export declare const rgxGroup: (args_0?: RGXGroupTokenArgs | undefined, tokens?: RGXTokenCollectionInput) => RGXGroupToken;

package/dist/class/group.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxGroup = exports.RGXGroupToken = void 0;
+const collection_1 = require("../collection");
+const base_1 = require("./base");
+const internal_1 = require("../internal");
+const typeGuards_1 = require("../typeGuards");
+class RGXGroupToken extends base_1.RGXClassToken {
+    get name() {
+        return this._name;
+    }
+    set name(value) {
+        if (value !== null)
+            (0, typeGuards_1.assertValidIdentifier)(value);
+        this._name = value;
+    }
+    get capturing() {
+        // Any named group is automatically capturing
+        return this.name !== null || this._capturing;
+    }
+    set capturing(value) {
+        if (!value)
+            this.name = null; // Non-capturing groups cannot have names
+        this._capturing = value;
+    }
+    get isGroup() {
+        return true;
+    }
+    get rgxGroupWrap() {
+        // When this token is resolved, it will wrap itself in a group, so we don't want the resolver to group wrap it again.
+        return false;
+    }
+    constructor({ name = null, capturing = true } = {}, tokens = []) {
+        super();
+        this._name = null;
+        this._capturing = true;
+        this.name = name;
+        this.capturing = capturing;
+        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');
+    }
+    toRgx() {
+        // The collection token doesn't group itself, so this is safe.
+        let result = this.tokens.toRgx().source;
+        if (this.name !== null)
+            result = `(?<${this.name}>${result})`;
+        else if (!this.capturing)
+            result = `(?:${result})`;
+        else
+            result = `(${result})`;
+        return new RegExp(result);
+    }
+}
+exports.RGXGroupToken = RGXGroupToken;
+RGXGroupToken.check = (0, internal_1.createClassGuardFunction)(RGXGroupToken);
+RGXGroupToken.assert = (0, internal_1.createAssertClassGuardFunction)(RGXGroupToken);
+exports.rgxGroup = (0, internal_1.createConstructFunction)(RGXGroupToken);

package/dist/class/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./init";
 export * from "./base";
 export * from "./union";
+export * from "./group";

package/dist/class/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./init"), exports);
 __exportStar(require("./base"), exports);
 __exportStar(require("./union"), exports);
+__exportStar(require("./group"), exports);

package/dist/class/init.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.rgxClassInit = rgxClassInit;
 const base_1 = require("./base");
 const union_1 = require("./union");
+const group_1 = require("./group");
 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.
@@ -19,4 +20,7 @@ function rgxClassInit() {
             return new union_1.RGXClassUnionToken([this, ...filteredOthers]);
         }
     };
+    base_1.RGXClassToken.prototype.group = function (args = {}) {
+        return new group_1.RGXGroupToken(args, [this]);
+    };
 }

package/dist/class/union.d.ts

@@ -4,6 +4,8 @@ import { RGXClassToken } from "./base";
 export type RGXUnionInsertionPosition = 'prefix' | 'suffix';
 export declare class RGXClassUnionToken extends RGXClassToken {
     tokens: RGXTokenCollection;
+    static check: (value: unknown) => value is RGXClassUnionToken;
+    static assert: (value: unknown) => asserts value is RGXClassUnionToken;
     get isGroup(): boolean;
     constructor(tokens?: RGXTokenCollectionInput);
     cleanTokens(): this;
@@ -14,5 +16,3 @@ export declare class RGXClassUnionToken extends RGXClassToken {
 export declare function expandRgxUnionTokens(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection;
 export declare function removeRgxUnionDuplicates(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection;
 export declare const rgxClassUnion: (tokens?: RGXTokenCollectionInput) => RGXClassUnionToken;
-export declare const isRgxClassUnionToken: (value: unknown) => value is RGXClassUnionToken;
-export declare const assertRgxClassUnionToken: (value: unknown) => asserts value is RGXClassUnionToken;

package/dist/class/union.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertRgxClassUnionToken = exports.isRgxClassUnionToken = exports.rgxClassUnion = exports.RGXClassUnionToken = void 0;
+exports.rgxClassUnion = exports.RGXClassUnionToken = void 0;
 exports.expandRgxUnionTokens = expandRgxUnionTokens;
 exports.removeRgxUnionDuplicates = removeRgxUnionDuplicates;
 const internal_1 = require("../internal");
@@ -49,6 +49,8 @@ class RGXClassUnionToken extends base_1.RGXClassToken {
     }
 }
 exports.RGXClassUnionToken = RGXClassUnionToken;
+RGXClassUnionToken.check = (0, internal_1.createClassGuardFunction)(RGXClassUnionToken);
+RGXClassUnionToken.assert = (0, internal_1.createAssertClassGuardFunction)(RGXClassUnionToken);
 function expandRgxUnionTokens(...tokens) {
     const result = new collection_1.RGXTokenCollection();
     for (const token of tokens) {
@@ -87,5 +89,3 @@ function removeRgxUnionDuplicates(...tokens) {
     return new collection_1.RGXTokenCollection(uniqueTokens, 'union');
 }
 exports.rgxClassUnion = (0, internal_1.createConstructFunction)(RGXClassUnionToken);
-exports.isRgxClassUnionToken = (0, internal_1.createClassGuardFunction)(RGXClassUnionToken);
-exports.assertRgxClassUnionToken = (0, internal_1.createAssertClassGuardFunction)(RGXClassUnionToken);

package/dist/collection.d.ts

@@ -1,4 +1,4 @@
-import { RGXToken } from "./types";
+import { RGXToken, ValidRegexString } from "./types";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import { Collection } from "@ptolemy2002/ts-utils";
 export type RGXTokenCollectionMode = 'union' | 'concat';
@@ -6,7 +6,10 @@ export type RGXTokenCollectionInput = RGXToken | RGXTokenCollection;
 export declare class RGXTokenCollection implements Collection<RGXToken> {
     mode: RGXTokenCollectionMode;
     tokens: RGXToken[];
+    static check: (value: unknown) => value is RGXTokenCollection;
+    static assert: (value: unknown) => asserts value is RGXTokenCollection;
     constructor(tokens?: RGXTokenCollectionInput, mode?: RGXTokenCollectionMode);
+    resolve(): ValidRegexString;
     toRgx(): RegExp;
     getTokens(): RGXToken[];
     clone(depth?: CloneDepth): RGXTokenCollection;

package/dist/collection.js

@@ -19,6 +19,9 @@ class RGXTokenCollection {
         }
         this.mode = mode;
     }
+    resolve() {
+        return (0, resolve_1.resolveRGXToken)(this);
+    }
     toRgx() {
         let pattern;
         if (this.mode === 'union') {
@@ -164,4 +167,6 @@ class RGXTokenCollection {
     }
 }
 exports.RGXTokenCollection = RGXTokenCollection;
+RGXTokenCollection.check = (0, internal_1.createClassGuardFunction)(RGXTokenCollection);
+RGXTokenCollection.assert = (0, internal_1.createAssertClassGuardFunction)(RGXTokenCollection);
 exports.rgxTokenCollection = (0, internal_1.createConstructFunction)(RGXTokenCollection);

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';
+export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'INVALID_IDENTIFIER';
 export declare class RGXError extends Error {
     code: RGXErrorCode;
     constructor(message: string, code?: RGXErrorCode);

package/dist/errors/index.d.ts

@@ -3,3 +3,4 @@ export * from './invalidToken';
 export * from './invalidRegexString';
 export * from './invalidVanillaRegexFlags';
 export * from './notImplemented';
+export * from './invalidIdentifier';

package/dist/errors/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./invalidToken"), exports);
 __exportStar(require("./invalidRegexString"), exports);
 __exportStar(require("./invalidVanillaRegexFlags"), exports);
 __exportStar(require("./notImplemented"), exports);
+__exportStar(require("./invalidIdentifier"), exports);

package/dist/errors/invalidIdentifier.d.ts

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

package/dist/errors/invalidIdentifier.js

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

package/dist/errors/invalidToken.js

@@ -46,7 +46,7 @@ class RGXInvalidTokenError extends errors_1.RGXError {
         this.setExpected(expected);
     }
     toString() {
-        const gotString = (0, class_1.isRgxClassToken)(this.got) ? `instance of ${this.got.constructor.name}` : JSON.stringify(this.got);
+        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}]`;
     }
 }

package/dist/resolve.d.ts

@@ -1,3 +1,3 @@
 import * as t from "./types";
 export declare function escapeRegex(value: string): t.ValidRegexString;
-export declare function resolveRGXToken(token: t.RGXToken, groupWrap?: boolean): t.ValidRegexString;
+export declare function resolveRGXToken(token: t.RGXToken, groupWrap?: boolean, topLevel?: boolean): t.ValidRegexString;

package/dist/resolve.js

@@ -41,7 +41,7 @@ const tg = __importStar(require("./typeGuards"));
 function escapeRegex(value) {
     return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function resolveRGXToken(token, groupWrap = true) {
+function resolveRGXToken(token, groupWrap = true, topLevel = true) {
     if (tg.isRGXNoOpToken(token))
         return '';
     if (tg.isRGXLiteralToken(token)) {
@@ -53,7 +53,9 @@ function resolveRGXToken(token, groupWrap = true) {
     if (tg.isRGXNativeToken(token))
         return escapeRegex(String(token));
     if (tg.isRGXConvertibleToken(token)) {
-        return resolveRGXToken(token.toRgx(), groupWrap);
+        // The top-level group-wrapping preference propogates to a direct convertible token, but after that
+        // the preference falls back to true whenever a token doesn't explicitly specify a preference.
+        return resolveRGXToken(token.toRgx(), token.rgxGroupWrap ?? (topLevel ? groupWrap : true), false);
     }
     // Interpret arrays as unions
     if (tg.isRGXArrayToken(token, false)) {
@@ -64,9 +66,9 @@ function resolveRGXToken(token, groupWrap = true) {
             token = [...(0, class_1.removeRgxUnionDuplicates)(...token)];
             // Don't preserve group wrapping preference for the recursive calls
             if (groupWrap)
-                return '(?:' + token.map(t => resolveRGXToken(t, true)).join('|') + ')';
+                return '(?:' + token.map(t => resolveRGXToken(t, true, false)).join('|') + ')';
             else
-                return token.map(t => resolveRGXToken(t, true)).join('|');
+                return token.map(t => resolveRGXToken(t, true, false)).join('|');
         }
         return resolveRGXToken(token[0]);
     }

package/dist/typeGuards.d.ts

@@ -20,3 +20,5 @@ export declare function isValidRegexString(value: string): value is t.ValidRegex
 export declare function assertValidRegexString(value: string): asserts value is t.ValidRegexString;
 export declare function isValidVanillaRegexFlags(value: string): value is t.ValidVanillaRegexFlags;
 export declare function assertValidVanillaRegexFlags(value: string): asserts value is t.ValidVanillaRegexFlags;
+export declare function isValidIdentifier(value: string): value is t.ValidIdentifier;
+export declare function assertValidIdentifier(value: string): asserts value is t.ValidIdentifier;

package/dist/typeGuards.js

@@ -57,10 +57,12 @@ exports.isValidRegexString = isValidRegexString;
 exports.assertValidRegexString = assertValidRegexString;
 exports.isValidVanillaRegexFlags = isValidVanillaRegexFlags;
 exports.assertValidVanillaRegexFlags = assertValidVanillaRegexFlags;
+exports.isValidIdentifier = isValidIdentifier;
+exports.assertValidIdentifier = assertValidIdentifier;
 const e = __importStar(require("./errors"));
-const class_1 = require("./class");
 const is_callable_1 = __importDefault(require("is-callable"));
 const internal_1 = require("./internal");
+const class_1 = require("./class");
 function isRGXNoOpToken(value) {
     return value === null || value === undefined;
 }
@@ -87,6 +89,9 @@ function assertRGXNativeToken(value) {
 }
 function isRGXConvertibleToken(value, returnCheck = true) {
     if (typeof value === 'object' && value !== null && 'toRgx' in value) {
+        // The rgxGroupWrap property is optional, but if it exists it must be a boolean.
+        if ('rgxGroupWrap' in value && typeof value.rgxGroupWrap !== 'boolean')
+            return false;
         if ((0, is_callable_1.default)(value.toRgx)) {
             if (!returnCheck)
                 return true;
@@ -122,7 +127,7 @@ function rgxTokenTypeFlat(value, recognizeClass = true) {
     if (isRGXNativeToken(value))
         return 'native';
     // We have to check class before convertible because class tokens are also convertible.
-    if (recognizeClass && (0, class_1.isRgxClassToken)(value))
+    if (recognizeClass && class_1.RGXClassToken.check(value))
         return 'class';
     if (isRGXConvertibleToken(value))
         return 'convertible';
@@ -167,7 +172,7 @@ function isRGXToken(value, type = null, matchLength = true) {
     if (typeMatches('native') && isRGXNativeToken(value))
         return true;
     // We have to check class before convertible because class tokens are also convertible.
-    if (typeMatches('class') && (0, class_1.isRgxClassToken)(value))
+    if (typeMatches('class') && class_1.RGXClassToken.check(value))
         return true;
     if (typeMatches('convertible') && isRGXConvertibleToken(value))
         return true;
@@ -215,3 +220,12 @@ function assertValidVanillaRegexFlags(value) {
         throw new e.RGXInvalidVanillaRegexFlagsError("Invalid vanilla regex flags", value);
     }
 }
+function isValidIdentifier(value) {
+    // This regex checks for valid JavaScript identifiers, which can be used for named capture groups.
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value);
+}
+function assertValidIdentifier(value) {
+    if (!isValidIdentifier(value)) {
+        throw new e.RGXInvalidIdentifierError("Invalid identifier", value);
+    }
+}

package/dist/types.d.ts

@@ -5,6 +5,7 @@ export type RGXLiteralToken = RegExp;
 export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
 export type RGXConvertibleToken = {
     toRgx: () => RGXToken;
+    readonly rgxGroupWrap?: boolean;
 };
 export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 export type RGXClassTokenConstructor = new (...args: unknown[]) => RGXClassToken;
@@ -20,3 +21,6 @@ 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 validIdentifierSymbol: unique symbol;
+export type ValidIdentifierBrandSymbol = typeof validIdentifierSymbol;
+export type ValidIdentifier = Branded<string, [ValidIdentifierBrandSymbol]>;

package/dist/types.js

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

package/package.json

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