@ptolemy2002/rgx 4.0.0 → 4.2.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,14 @@ 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' | 'OUT_OF_BOUNDS';
+
+type RangeObject = {
+    min?: number | null;
+    max?: number | null;
+    inclusiveLeft?: boolean;
+    inclusiveRight?: boolean;
+};
 type ExpectedTokenType = {
     type: "tokenType";
     values: RGXTokenTypeFlat[];
@@ -42,6 +53,11 @@ type RGXTokenCollectionMode = 'union' | 'concat';
 type RGXTokenCollectionInput = RGXToken | RGXTokenCollection;
 
 type RGXUnionInsertionPosition = 'prefix' | 'suffix';
+
+type RGXGroupTokenArgs = {
+    name?: string | null;
+    capturing?: boolean;
+};
 ```
 
 ## Classes
@@ -117,6 +133,49 @@ 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.
+
+### 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.
+
+#### Constructor
+```typescript
+constructor(message: string, got: number, { min, max, inclusiveLeft, inclusiveRight }?: RangeObject)
+```
+- `message` (`string`): The error message.
+- `got` (`number`): The actual numeric value that was received, which fell outside the expected range.
+- `min` (`number | null`, optional): The minimum bound of the range. Defaults to `null` (no minimum).
+- `max` (`number | null`, optional): The maximum bound of the range. Defaults to `null` (no maximum). Setting `min` to a value greater than `max` will adjust `max` to equal `min`, and vice versa.
+- `inclusiveLeft` (`boolean`, optional): Whether the minimum bound is inclusive. Defaults to `true`.
+- `inclusiveRight` (`boolean`, optional): Whether the maximum bound is inclusive. Defaults to `true`.
+
+#### Properties
+- `got` (`number`): The actual numeric value that was received.
+- `min` (`number | null`): The minimum bound of the range. Setting this to a value greater than `max` will adjust `max` to equal `min`.
+- `max` (`number | null`): The maximum bound of the range. Setting this to a value less than `min` will adjust `min` to equal `max`.
+- `inclusiveLeft` (`boolean`): Whether the minimum bound is inclusive.
+- `inclusiveRight` (`boolean`): Whether the maximum bound is inclusive.
+
+#### Methods
+- `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.
 
@@ -132,6 +191,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.
@@ -157,10 +217,12 @@ 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.
+- `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.
@@ -187,6 +249,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:
 
@@ -273,7 +363,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.
@@ -286,7 +376,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.
@@ -499,6 +589,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
@@ -514,14 +628,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.
@@ -615,7 +732,82 @@ 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.
+
+### isInRange
+```typescript
+function isInRange(value: number, { min, max, inclusiveLeft, inclusiveRight }?: RangeObject): boolean
+```
+
+Checks if the given numeric value falls within the specified range.
+
+#### Parameters
+  - `value` (`number`): The value to check.
+  - `min` (`number | null`, optional): The minimum bound of the range. Defaults to `null` (no minimum).
+  - `max` (`number | null`, optional): The maximum bound of the range. Defaults to `null` (no maximum).
+  - `inclusiveLeft` (`boolean`, optional): Whether the minimum bound is inclusive. Defaults to `true`.
+  - `inclusiveRight` (`boolean`, optional): Whether the maximum bound is inclusive. Defaults to `true`.
+
+#### Returns
+- `boolean`: `true` if the value is within the specified range, otherwise `false`.
+
+### assertInRange
+```typescript
+function assertInRange(value: number, range: RangeObject, message?: string): void
+```
+
+Asserts that the given numeric value falls within the specified range. If the assertion fails, an `RGXOutOfBoundsError` will be thrown.
+
+#### Parameters
+  - `value` (`number`): The value to assert.
+  - `range` (`RangeObject`): The range to check against.
+  - `message` (`string`, optional): A custom error message. Defaults to `"Value out of bounds"`.
+
+#### Returns
+- `void`: This function does not return a value, but will throw an error if the assertion fails.
+
+### normalizeVanillaRegexFlags
+```typescript
+function normalizeVanillaRegexFlags(flags: string): string
+```
+
+Normalizes a string of vanilla regex flags by removing duplicate flags while preserving order. If any character in the string is not a valid vanilla regex flag (g, i, m, s, u, y), an `RGXInvalidVanillaRegexFlagsError` will be thrown.
+
+#### Parameters
+  - `flags` (`string`): The flags string to normalize.
+
+#### Returns
+- `string`: The normalized flags string with duplicates removed.
+
+### regexWithFlags
+```typescript
+function regexWithFlags(exp: RegExp, flags: string, replace?: boolean): RegExp
+```
+
+Creates a new `RegExp` from an existing one with additional or replaced flags. When `replace` is `false` (the default), the provided flags are merged with the existing flags and normalized (duplicates removed). When `replace` is `true`, the existing flags are discarded and only the provided flags are used. The provided flags are validated as valid vanilla regex flags via `assertValidVanillaRegexFlags`.
+
+#### Parameters
+  - `exp` (`RegExp`): The source regular expression.
+  - `flags` (`string`): The flags to add or replace with. Must be valid vanilla regex flags, or an `RGXInvalidVanillaRegexFlagsError` will be thrown.
+  - `replace` (`boolean`, optional): Whether to replace the existing flags entirely instead of merging. Defaults to `false`.
+
+#### Returns
+- `RegExp`: A new `RegExp` with the same source pattern and the resulting flags.
+
+### regexMatchAtPosition
+```typescript
+function regexMatchAtPosition(regex: RegExp, str: string, position: number): boolean
+```
+
+Tests whether the given regular expression matches at a specific position in the string. This is done by creating a sticky (`y` flag) copy of the regex and setting its `lastIndex` to the desired position. The position must be within the bounds of the string (>= 0 and < string length), or an `RGXOutOfBoundsError` will be thrown.
+
+#### Parameters
+  - `regex` (`RegExp`): The regular expression to test.
+  - `str` (`string`): The string to test against.
+  - `position` (`number`): The zero-based index in the string at which to test the match. Must be >= 0 and < `str.length`.
+
+#### Returns
+- `boolean`: `true` if the regex matches at the specified position, otherwise `false`.
 
 ## 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;
 }

package/dist/class/base.js

@@ -7,9 +7,15 @@ 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);
     }

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/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';
@@ -9,6 +9,7 @@ export declare class RGXTokenCollection implements Collection<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') {

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' | 'OUT_OF_BOUNDS';
 export declare class RGXError extends Error {
     code: RGXErrorCode;
     constructor(message: string, code?: RGXErrorCode);

package/dist/errors/index.d.ts

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

package/dist/errors/index.js

@@ -19,3 +19,5 @@ __exportStar(require("./invalidToken"), exports);
 __exportStar(require("./invalidRegexString"), exports);
 __exportStar(require("./invalidVanillaRegexFlags"), exports);
 __exportStar(require("./notImplemented"), exports);
+__exportStar(require("./invalidIdentifier"), exports);
+__exportStar(require("./outOfBounds"), 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/outOfBounds.d.ts

@@ -0,0 +1,20 @@
+import { RGXError } from "./base";
+import { RangeObject } from "../types";
+export declare class RGXOutOfBoundsError extends RGXError {
+    got: number;
+    _min: number | null;
+    _max: number | null;
+    inclusiveLeft: boolean;
+    inclusiveRight: boolean;
+    get min(): number | null;
+    set min(value: number | null);
+    get max(): number | null;
+    set max(value: number | null);
+    constructor(message: string, got: number, { min, max, inclusiveLeft, inclusiveRight }?: RangeObject);
+    failedAtMin(): boolean;
+    failedAtMax(): boolean;
+    failedAtAny(): boolean;
+    toString(): string;
+}
+export declare function isInRange(value: number, { min, max, inclusiveLeft, inclusiveRight }?: RangeObject): boolean;
+export declare function assertInRange(value: number, range: RangeObject, message?: string): void;

package/dist/errors/outOfBounds.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXOutOfBoundsError = void 0;
+exports.isInRange = isInRange;
+exports.assertInRange = assertInRange;
+const base_1 = require("./base");
+class RGXOutOfBoundsError extends base_1.RGXError {
+    get min() {
+        return this._min;
+    }
+    set min(value) {
+        this._min = value;
+        if (this._max !== null && value !== null && value > this._max) {
+            this._max = value;
+        }
+    }
+    get max() {
+        return this._max;
+    }
+    set max(value) {
+        this._max = value;
+        if (this._min !== null && value !== null && value < this._min) {
+            this._min = value;
+        }
+    }
+    constructor(message, got, { min = null, max = null, inclusiveLeft = true, inclusiveRight = true } = {}) {
+        super(message, 'OUT_OF_BOUNDS');
+        this.name = 'RGXOutOfBoundsError';
+        this.got = got;
+        this.min = min;
+        this.max = max;
+        this.inclusiveLeft = inclusiveLeft;
+        this.inclusiveRight = inclusiveRight;
+    }
+    failedAtMin() {
+        return this.min !== null && (this.inclusiveLeft ? this.got < this.min : this.got <= this.min);
+    }
+    failedAtMax() {
+        return this.max !== null && (this.inclusiveRight ? this.got > this.max : this.got >= this.max);
+    }
+    failedAtAny() {
+        return this.failedAtMin() || this.failedAtMax();
+    }
+    toString() {
+        const rangeParts = [];
+        if (this.min !== null) {
+            if (this.inclusiveLeft)
+                rangeParts.push(`>= ${this.min}`);
+            else
+                rangeParts.push(`> ${this.min}`);
+        }
+        if (this.max !== null) {
+            if (this.inclusiveRight)
+                rangeParts.push(`<= ${this.max}`);
+            else
+                rangeParts.push(`< ${this.max}`);
+        }
+        const rangeStr = rangeParts.join(" and ");
+        // Determine which one was failed
+        if (!this.failedAtAny()) {
+            return `${this.name}: ${this.message}; Got: [${this.got}]; Expected: [${rangeStr}]`;
+        }
+        else if (this.failedAtMin()) {
+            let thirdPart;
+            if (!this.inclusiveLeft && this.got === this.min)
+                thirdPart = `${this.got} == ${this.min}`;
+            else
+                thirdPart = `${this.got} < ${this.min}`;
+            return `${this.name}: ${this.message}; Got: [${this.got}]; Expected: [${rangeStr}]; ${thirdPart}`;
+        }
+        else {
+            let thirdPart;
+            if (!this.inclusiveRight && this.got === this.max)
+                thirdPart = `${this.got} == ${this.max}`;
+            else
+                thirdPart = `${this.got} > ${this.max}`;
+            return `${this.name}: ${this.message}; Got: [${this.got}]; Expected: [${rangeStr}]; ${thirdPart}`;
+        }
+    }
+}
+exports.RGXOutOfBoundsError = RGXOutOfBoundsError;
+function isInRange(value, { min = null, max = null, inclusiveLeft = true, inclusiveRight = true } = {}) {
+    if (min !== null) {
+        if (inclusiveLeft) {
+            if (value < min)
+                return false;
+        }
+        else {
+            if (value <= min)
+                return false;
+        }
+    }
+    if (max !== null) {
+        if (inclusiveRight) {
+            if (value > max)
+                return false;
+        }
+        else {
+            if (value >= max)
+                return false;
+        }
+    }
+    return true;
+}
+function assertInRange(value, range, message = "Value out of bounds") {
+    if (!isInRange(value, range)) {
+        throw new RGXOutOfBoundsError(message, value, range);
+    }
+}

package/dist/index.d.ts

@@ -6,5 +6,6 @@ export * from "./collection";
 export * from "./class";
 export * from "./resolve";
 export * from "./concat";
+export * from "./utils";
 export declare function rgxa(tokens: t.RGXToken[], flags?: string): RegExp;
 export default function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => RegExp;

package/dist/index.js

@@ -49,6 +49,7 @@ __exportStar(require("./collection"), exports);
 __exportStar(require("./class"), exports);
 __exportStar(require("./resolve"), exports);
 __exportStar(require("./concat"), exports);
+__exportStar(require("./utils"), exports);
 // Call this for certain class methods to work correctly
 (0, class_1.rgxClassInit)();
 function rgxa(tokens, flags = '') {

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,6 +57,8 @@ exports.isValidRegexString = isValidRegexString;
 exports.assertValidRegexString = assertValidRegexString;
 exports.isValidVanillaRegexFlags = isValidVanillaRegexFlags;
 exports.assertValidVanillaRegexFlags = assertValidVanillaRegexFlags;
+exports.isValidIdentifier = isValidIdentifier;
+exports.assertValidIdentifier = assertValidIdentifier;
 const e = __importStar(require("./errors"));
 const is_callable_1 = __importDefault(require("is-callable"));
 const internal_1 = require("./internal");
@@ -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;
@@ -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;
@@ -14,9 +15,18 @@ export type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenCons
 export type RGXTokenFromType<T extends RGXTokenTypeGuardInput> = T extends null ? RGXToken : T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? RGXLiteralToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends 'class' ? RGXClassToken : T extends 'array' ? RGXToken[] : T extends RGXTokenTypeGuardInput[] ? {
     [K in keyof T]: T[K] extends RGXTokenTypeGuardInput ? RGXTokenFromType<T[K]> : never;
 } : T extends RGXClassTokenConstructor ? InstanceType<T> : never;
+export type RangeObject = {
+    min?: number | null;
+    max?: number | null;
+    inclusiveLeft?: boolean;
+    inclusiveRight?: boolean;
+};
 export declare const validRegexSymbol: unique symbol;
 export type ValidRegexBrandSymbol = typeof validRegexSymbol;
 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/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./regexMatchAtPosition";
+export * from "./regexWithFlags";
+export * from "./normalizeRegexFlags";

package/dist/utils/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./regexMatchAtPosition"), exports);
+__exportStar(require("./regexWithFlags"), exports);
+__exportStar(require("./normalizeRegexFlags"), exports);

package/dist/utils/normalizeRegexFlags.d.ts

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

package/dist/utils/normalizeRegexFlags.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeVanillaRegexFlags = normalizeVanillaRegexFlags;
+const errors_1 = require("../errors");
+function normalizeVanillaRegexFlags(flags) {
+    const validFlags = ['g', 'i', 'm', 's', 'u', 'y'];
+    const seenFlags = new Set();
+    let normalizedFlags = '';
+    for (const flag of flags) {
+        if (!validFlags.includes(flag)) {
+            throw new errors_1.RGXInvalidVanillaRegexFlagsError(`[${flag}] is not valid.`, flags);
+        }
+        if (!seenFlags.has(flag)) {
+            seenFlags.add(flag);
+            normalizedFlags += flag;
+        }
+    }
+    return normalizedFlags;
+}

package/dist/utils/regexMatchAtPosition.d.ts

@@ -0,0 +1 @@
+export declare function regexMatchAtPosition(regex: RegExp, str: string, position: number): boolean;

package/dist/utils/regexMatchAtPosition.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.regexMatchAtPosition = regexMatchAtPosition;
+const outOfBounds_1 = require("../errors/outOfBounds");
+const regexWithFlags_1 = require("./regexWithFlags");
+function regexMatchAtPosition(regex, str, position) {
+    /*
+        The y flag means sticky mode, which means the next match must start at
+        lastIndex. By setting lastIndex to the position we want to check, we can test
+        if the regex matches at that position.
+    */
+    (0, outOfBounds_1.assertInRange)(position, { min: 0, max: str.length, inclusiveRight: false }, 'String index out of bounds');
+    const stickyRegex = (0, regexWithFlags_1.regexWithFlags)(regex, "y");
+    stickyRegex.lastIndex = position;
+    return stickyRegex.test(str);
+}

package/dist/utils/regexWithFlags.d.ts

@@ -0,0 +1 @@
+export declare function regexWithFlags(exp: RegExp, flags: string, replace?: boolean): RegExp;

package/dist/utils/regexWithFlags.js

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

package/package.json

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