@ptolemy2002/rgx 4.10.0 → 5.0.0

package/README.md

@@ -1,19 +1,23 @@
 # RGX
 A library for easy construction and validation of regular expressions in TypeScript. You can use `rgx` to concatenate various types of tokens into a valid regular expression string, with type safety and validation.
 
+**Note**: This library is tested with nearly 100% coverage, but any override of `RGXClassToken.clone()` does not have the depth parameter fully tested, as that is ultimately part of `@ptolemy2002/immutability-utils`, which is tested, and setting up tests for that functionality is exceedingly complex.
+
 ## Type Reference
 ```typescript
 import { Branded } from "@ptolemy2002/ts-brand-utils";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+// type CloneDepth = number | "max";
 
 type RGXNoOpToken = null | undefined;
 type RGXLiteralToken = RegExp;
 type RGXNativeToken = string | number | boolean | RGXNoOpToken;
-type RGXConvertibleToken = { toRgx: () => RGXToken, readonly rgxGroupWrap?: boolean };
+type RGXConvertibleToken = { toRgx: () => RGXToken, readonly rgxGroupWrap?: boolean, readonly rgxIsGroup?: boolean, readonly rgxIsRepeatable?: 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 };
+type RGXGroupedToken = RGXToken[] | RGXLiteralToken | RGXGroupedConvertibleToken;
+type RGXGroupedConvertibleToken = (RGXConvertibleToken & { readonly rgxIsGroup: true }) | (Omit<RGXConvertibleToken, "toRGX"> & { toRgx: () => RGXGroupedToken, readonly rgxGroupWrap: true  });
 
 const validRegexSymbol = Symbol('rgx.ValidRegex');
 type ValidRegexBrandSymbol = typeof validRegexSymbol;
@@ -35,7 +39,7 @@ 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 | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
+type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof RegExp | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
 type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // Maps token type strings to their corresponding types, e.g.:
     // 'no-op' -> RGXNoOpToken, 'literal' -> RGXLiteralToken, etc.
@@ -253,7 +257,7 @@ constructor(tokens: RGXTokenCollectionInput = [], mode: RGXTokenCollectionMode =
 - `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.
-- `clone() => RGXTokenCollection`: A method that creates and returns a deep clone of the RGXTokenCollection instance. This is useful for creating a new collection with the same tokens and mode without affecting the original collection.
+- `clone(depth: CloneDepth = "max") => RGXTokenCollection`: A method that creates and returns a deep clone of the RGXTokenCollection instance. This is useful for creating a new collection with the same tokens and mode without affecting the original collection. The `depth` parameter controls how deeply nested collections are cloned: `0` for no clone, `1` for a shallow clone of the top-level collection, any other number for that many levels down, and `"max"` (the default) for a full deep clone.
 - `asConcat() => RGXTokenCollection`: If this collection is in 'union' mode, this method returns a new RGXTokenCollection instance with the same tokens but in 'concat' mode. If the collection is already in 'concat' mode, it simply returns itself.
 - `asUnion() => RGXTokenCollection`: If this collection is in 'concat' mode, this method returns a new RGXTokenCollection instance with the same tokens but in 'union' mode. If the collection is already in 'union' mode, it simply returns itself.
 
@@ -272,17 +276,18 @@ An abstract base class for creating custom RGX token classes. Subclasses must im
 
 #### 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).
+- `clone(depth: CloneDepth = "max") => RGXClassToken`: Must be implemented by subclasses to return a deep clone of the token instance. The `depth` parameter controls how deeply nested tokens are cloned: `0` for no clone, `1` for a shallow clone of the top-level token, any other number for that many levels down, and `"max"` (the default) for a full deep clone.
 
 #### 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`.
+- `rgxIsGroup` (`boolean`): Returns `false` by default. Subclasses can override this to indicate whether the token represents a group.
+- `rgxIsRepeatable` (`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. 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.
+- `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 a token with `rgxIsRepeatable` set to `false` (e.g., `RGXLookaroundToken`).
+- `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 a token with `rgxIsRepeatable` set to `false` (e.g., `RGXLookaroundToken`).
 - `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`.
@@ -332,7 +337,7 @@ 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` (`true`): Returns `true` as a constant, indicating this token represents a group.
+- `rgxIsGroup` (`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
@@ -356,7 +361,7 @@ constructor(token: RGXToken, min?: number, max?: number | null)
 - `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` (`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`.
+- `token` (`RGXGroupedToken`): The token being repeated. Setting this will throw `RGXNotSupportedError` if the value is a convertible token with `rgxIsRepeatable` 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).
@@ -383,8 +388,8 @@ constructor(tokens?: RGXTokenCollectionInput, positive?: boolean)
 - `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.
+- `rgxIsGroup` (`true`): Returns `true` as a constant, indicating this token represents a group.
+- `rgxIsRepeatable` (`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
@@ -420,7 +425,7 @@ A function `rgxLookbehind` is provided with the same parameters as this class' c
 - `toRgx() => RegExp`: Resolves the lookbehind to a `RegExp`. Positive lookbehinds produce `(?<=...)` and negative lookbehinds produce `(?<!...)`.
 
 ### RGXClassWrapperToken extends RGXClassToken
-A class that wraps any `RGXToken` as an `RGXClassToken`, giving you access to the extended API class tokens provide. It delegates `isGroup` and `isRepeatable` to the wrapped token where possible.
+A class that wraps any `RGXToken` as an `RGXClassToken`, giving you access to the extended API class tokens provide. It delegates `rgxIsGroup` and `rgxIsRepeatable` to the wrapped token where possible.
 
 A function `rgxClassWrapper` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
 
@@ -436,8 +441,8 @@ constructor(token: RGXToken)
 
 #### Properties
 - `token` (`RGXToken`): The wrapped token.
-- `isGroup` (`boolean`): Delegates to the wrapped token's group status via `isRGXGroupedToken`. Returns `true` if the wrapped token is a grouped token, otherwise `false`.
-- `isRepeatable` (`boolean`): If the wrapped token is an `RGXClassToken`, delegates to its `isRepeatable` property. Otherwise, returns `true`.
+- `rgxIsGroup` (`boolean`): Delegates to the wrapped token's group status via `isRGXGroupedToken`. Returns `true` if the wrapped token is a grouped token, otherwise `false`.
+- `rgxIsRepeatable` (`boolean`): If the wrapped token is an `RGXClassToken`, delegates to its `rgxIsRepeatable` property. Otherwise, returns `true`.
 
 #### Methods
 - `unwrap() => RGXToken`: Returns the original wrapped token.
@@ -547,7 +552,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). 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).
+Checks if the given value is a convertible token (an object with a `toRgx` method). If the `rgxGroupWrap`, `rgxIsRepeatable`, or `rgxIsGroup` properties are present, they must be booleans; 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.
@@ -560,7 +565,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). 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.
+Asserts that the given value is a convertible token (an object with a `toRgx` method). If the `rgxGroupWrap`, `rgxIsRepeatable`, or `rgxIsGroup` properties are present, they must be booleans; 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.
@@ -696,7 +701,7 @@ function isRGXToken<T extends RGXTokenTypeGuardInput = null>(value: unknown, typ
 
 Checks if the given value is a valid RGX token, optionally narrowed to a specific token type. When `type` is `null` (the default), it checks against all token types. When `type` is a specific token type string, it checks only against that type. The `'class'` type matches `RGXClassToken` instances specifically, while `'convertible'` also matches class tokens since they implement the convertible interface.
 
-When `type` is an `RGXClassTokenConstructor` (a constructor for an `RGXClassToken` subclass), it performs an `instanceof` check against that specific constructor, allowing you to narrow to a specific class token subclass rather than all class tokens. In this case, `RGXTokenFromType` resolves to `InstanceType<T>`, giving you the specific subclass type.
+When `type` is a constructor, it performs an `instanceof` check against that specific constructor, allowing you to narrow to a specific class token subclass rather than all class tokens. In this case, `RGXTokenFromType` resolves to `InstanceType<T>`, giving you the specific subclass type.
 
 When `type` is an array, it checks that every element of the value array is a valid RGX token matching the corresponding type in the `type` array. If `matchLength` is `true` (the default), it also requires that the value array has the same length as the type array; if `false`, it allows the value array to be longer than the type array, as long as all elements up to the length of the type array match and all elements after that are still valid RGX tokens of any type.
 
@@ -728,11 +733,11 @@ Asserts that the given value is a valid RGX token, optionally narrowed to a spec
 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.
+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. Convertible tokens (including class tokens) are groups if they have `rgxIsGroup` set to `true`, or 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.
+  - `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. This has no effect on the `rgxIsGroup` check, which always accepts the token as grouped regardless of `contentCheck`.
 
 #### Returns
 - `boolean`: `true` if the value is a grouped token, otherwise `false`.
@@ -746,7 +751,7 @@ Asserts that the given value is a grouped token. Uses the same logic as `isRGXGr
 
 #### 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.
+  - `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. This has no effect on the `rgxIsGroup` check, which always accepts the token as grouped regardless of `contentCheck`.
 
 #### Returns
 - `void`: This function does not return a value, but will throw an error if the assertion fails.
@@ -1208,6 +1213,19 @@ Tests whether the given regular expression matches at a specific position in the
 #### Returns
 - `boolean`: `true` if the regex matches at the specified position, otherwise `false`.
 
+### cloneRGXToken
+```typescript
+function cloneRGXTokeN<T extends RGXToken>(token: T, depth: CloneDepth="max"): T
+```
+Creates a clone of the given RGX token to the given depth, provided that the token is not a no-op or native token.
+
+#### Parameters
+  - `token` (`T`): The RGX token to clone. Must not be a no-op or native token, or an error will be thrown.
+  - `depth` (`CloneDepth`, optional): The depth to which to clone the token. Can be a number (with 0 resulting in no clone at all and 1 resulting in a shallow clone) or the string `"max"` for a full deep clone. Defaults to `"max"`.
+
+#### Returns
+- `T`: The cloned token.
+
 ## Peer Dependencies
 - `@ptolemy2002/immutability-utils` ^2.0.0
 - `@ptolemy2002/js-utils` ^3.2.2

package/dist/class/base.d.ts

@@ -1,16 +1,18 @@
-import { RGXToken, ValidRegexString } from "../types";
+import { RGXConvertibleToken, RGXToken, ValidRegexString } from "../types";
 import { RGXTokenCollectionInput } from "../collection";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 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 {
+export declare abstract class RGXClassToken implements RGXConvertibleToken {
     abstract toRgx(): RGXToken;
+    abstract clone(depth?: CloneDepth): ThisType<this>;
     static check: (value: unknown) => value is RGXClassToken;
     static assert: (value: unknown) => asserts value is RGXClassToken;
-    get isGroup(): boolean;
-    get isRepeatable(): boolean;
+    get rgxIsGroup(): boolean;
+    get rgxIsRepeatable(): boolean;
     get rgxGroupWrap(): boolean;
     or(...others: RGXTokenCollectionInput[]): RGXClassUnionToken;
     group(args?: RGXGroupTokenArgs): RGXGroupToken;

package/dist/class/base.js

@@ -4,10 +4,10 @@ exports.RGXClassToken = void 0;
 const errors_1 = require("../errors");
 const resolve_1 = require("../resolve");
 class RGXClassToken {
-    get isGroup() {
+    get rgxIsGroup() {
         return false;
     }
-    get isRepeatable() {
+    get rgxIsRepeatable() {
         return true;
     }
     get rgxGroupWrap() {

package/dist/class/group.d.ts

@@ -1,5 +1,6 @@
 import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
 import { RGXClassToken } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 export type RGXGroupTokenArgs = {
     name?: string | null;
     capturing?: boolean;
@@ -14,9 +15,10 @@ export declare class RGXGroupToken extends RGXClassToken {
     set name(value: string | null);
     get capturing(): boolean;
     set capturing(value: boolean);
-    get isGroup(): true;
+    get rgxIsGroup(): true;
     get rgxGroupWrap(): false;
     constructor({ name, capturing }?: RGXGroupTokenArgs, tokens?: RGXTokenCollectionInput);
     toRgx(): RegExp;
+    clone(depth?: CloneDepth): RGXGroupToken;
 }
 export declare const rgxGroup: (args_0?: RGXGroupTokenArgs | undefined, tokens?: RGXTokenCollectionInput) => RGXGroupToken;

package/dist/class/group.js

@@ -5,6 +5,7 @@ const collection_1 = require("../collection");
 const base_1 = require("./base");
 const internal_1 = require("../internal");
 const typeGuards_1 = require("../typeGuards");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
 class RGXGroupToken extends base_1.RGXClassToken {
     get name() {
         return this._name;
@@ -23,7 +24,7 @@ class RGXGroupToken extends base_1.RGXClassToken {
             this.name = null; // Non-capturing groups cannot have names
         this._capturing = value;
     }
-    get isGroup() {
+    get rgxIsGroup() {
         return true;
     }
     get rgxGroupWrap() {
@@ -52,6 +53,11 @@ class RGXGroupToken extends base_1.RGXClassToken {
             result = `(${result})`;
         return new RegExp(result);
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXGroupToken({ name: this.name, capturing: this._capturing }, this.tokens.clone((0, immutability_utils_1.depthDecrement)(depth, 1)));
+    }
 }
 exports.RGXGroupToken = RGXGroupToken;
 RGXGroupToken.check = (0, internal_1.createClassGuardFunction)(RGXGroupToken);

package/dist/class/init.js

@@ -36,11 +36,15 @@ function rgxClassInit() {
     base_1.RGXClassToken.prototype.asLookahead = function (positive = true) {
         if (lookahead_1.RGXLookaheadToken.check(this))
             return this;
+        if (lookbehind_1.RGXLookbehindToken.check(this))
+            return this.negate();
         return new lookahead_1.RGXLookaheadToken([this], positive);
     };
     base_1.RGXClassToken.prototype.asLookbehind = function (positive = true) {
         if (lookbehind_1.RGXLookbehindToken.check(this))
             return this;
+        if (lookahead_1.RGXLookaheadToken.check(this))
+            return this.negate();
         return new lookbehind_1.RGXLookbehindToken([this], positive);
     };
 }

package/dist/class/lookahead.d.ts

@@ -1,11 +1,13 @@
 import { RGXToken } from "../types";
 import { RGXLookaroundToken } from "./lookaround";
 import { RGXLookbehindToken } from "./lookbehind";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 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;
+    clone(depth?: CloneDepth): RGXLookaheadToken;
 }
 export declare const rgxLookahead: (tokens?: import("..").RGXTokenCollectionInput, positive?: boolean | undefined) => RGXLookaheadToken;

package/dist/class/lookahead.js

@@ -4,6 +4,7 @@ exports.rgxLookahead = exports.RGXLookaheadToken = void 0;
 const internal_1 = require("../internal");
 const lookaround_1 = require("./lookaround");
 const lookbehind_1 = require("./lookbehind");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
 class RGXLookaheadToken extends lookaround_1.RGXLookaroundToken {
     negate() {
         return new RGXLookaheadToken(this.tokens, !this.positive);
@@ -19,6 +20,11 @@ class RGXLookaheadToken extends lookaround_1.RGXLookaroundToken {
             result = `(?!${result})`;
         return new RegExp(result);
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXLookaheadToken(this.tokens.clone((0, immutability_utils_1.depthDecrement)(depth, 1)), this.positive);
+    }
 }
 exports.RGXLookaheadToken = RGXLookaheadToken;
 RGXLookaheadToken.check = (0, internal_1.createClassGuardFunction)(RGXLookaheadToken);

package/dist/class/lookaround.d.ts

@@ -5,8 +5,8 @@ export declare abstract class RGXLookaroundToken extends RGXClassToken {
     _negative: boolean;
     static check: (value: unknown) => value is RGXLookaroundToken;
     static assert: (value: unknown) => asserts value is RGXLookaroundToken;
-    get isGroup(): true;
-    get isRepeatable(): false;
+    get rgxIsGroup(): true;
+    get rgxIsRepeatable(): false;
     get rgxGroupWrap(): false;
     set negative(value: boolean);
     get negative(): boolean;

package/dist/class/lookaround.js

@@ -5,10 +5,10 @@ const collection_1 = require("../collection");
 const base_1 = require("./base");
 const errors_1 = require("../errors");
 class RGXLookaroundToken extends base_1.RGXClassToken {
-    get isGroup() {
+    get rgxIsGroup() {
         return true;
     }
-    get isRepeatable() {
+    get rgxIsRepeatable() {
         return false;
     }
     get rgxGroupWrap() {

package/dist/class/lookbehind.d.ts

@@ -1,12 +1,13 @@
-import { RGXTokenCollectionInput } from "../collection";
 import { RGXToken } from "../types";
 import { RGXLookaheadToken } from "./lookahead";
 import { RGXLookaroundToken } from "./lookaround";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 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;
+    clone(depth?: CloneDepth): RGXLookbehindToken;
 }
-export declare const rgxLookbehind: (tokens?: RGXTokenCollectionInput, positive?: boolean | undefined) => RGXLookbehindToken;
+export declare const rgxLookbehind: (tokens?: import("..").RGXTokenCollectionInput, positive?: boolean | undefined) => RGXLookbehindToken;

package/dist/class/lookbehind.js

@@ -4,6 +4,7 @@ exports.rgxLookbehind = exports.RGXLookbehindToken = void 0;
 const internal_1 = require("../internal");
 const lookahead_1 = require("./lookahead");
 const lookaround_1 = require("./lookaround");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
 class RGXLookbehindToken extends lookaround_1.RGXLookaroundToken {
     negate() {
         return new RGXLookbehindToken(this.tokens, !this.positive);
@@ -19,6 +20,11 @@ class RGXLookbehindToken extends lookaround_1.RGXLookaroundToken {
             result = `(?<!${result})`;
         return new RegExp(result);
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXLookbehindToken(this.tokens.clone((0, immutability_utils_1.depthDecrement)(depth, 1)), this.positive);
+    }
 }
 exports.RGXLookbehindToken = RGXLookbehindToken;
 RGXLookbehindToken.check = (0, internal_1.createClassGuardFunction)(RGXLookbehindToken);

package/dist/class/repeat.d.ts

@@ -1,5 +1,6 @@
 import { RGXGroupedToken, RGXToken } from "../types";
 import { RGXClassToken } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 export declare class RGXRepeatToken extends RGXClassToken {
     _token: RGXGroupedToken;
     _min: number;
@@ -10,11 +11,12 @@ export declare class RGXRepeatToken extends RGXClassToken {
     set min(value: number);
     get max(): number | null;
     set max(value: number | null);
-    get token(): RGXToken;
+    get token(): RGXGroupedToken;
     set token(value: RGXToken);
     get rgxGroupWrap(): false;
     constructor(token: RGXToken, min?: number, max?: number | null);
     get repeaterSuffix(): string;
     toRgx(): RGXToken;
+    clone(depth?: CloneDepth): RGXRepeatToken;
 }
 export declare const rgxRepeat: (token: RGXToken, min?: number | undefined, max?: number | null | undefined) => RGXRepeatToken;

package/dist/class/repeat.js

@@ -7,6 +7,8 @@ const typeGuards_1 = require("../typeGuards");
 const errors_1 = require("../errors");
 const resolve_1 = require("../resolve");
 const internal_1 = require("../internal");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+const clone_1 = require("../clone");
 class RGXRepeatToken extends base_1.RGXClassToken {
     get min() {
         return this._min;
@@ -30,8 +32,13 @@ class RGXRepeatToken extends base_1.RGXClassToken {
         return this._token;
     }
     set token(value) {
-        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.");
+        if ((0, typeGuards_1.isRGXToken)(value, "convertible") && !value.rgxIsRepeatable) {
+            if ((0, typeGuards_1.isRGXToken)(value, "class")) {
+                throw new errors_1.RGXNotSupportedError(`Repeating ${value.constructor.name} tokens`, "The token was manually marked as non-repeatable.");
+            }
+            else {
+                throw new errors_1.RGXNotSupportedError("Repeating tokens with {rgxIsRepeatable: false}", "The token was manually marked as non-repeatable.");
+            }
         }
         // Make sure we are always working with a grouped token.
         if ((0, typeGuards_1.isRGXGroupedToken)(value))
@@ -76,6 +83,11 @@ class RGXRepeatToken extends base_1.RGXClassToken {
         const resolvedSource = (0, resolve_1.resolveRGXToken)(this.token);
         return new RegExp(`${resolvedSource}${this.repeaterSuffix}`);
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXRepeatToken((0, clone_1.cloneRGXToken)(this.token, (0, immutability_utils_1.depthDecrement)(depth, 1)), this.min, this.max);
+    }
 }
 exports.RGXRepeatToken = RGXRepeatToken;
 RGXRepeatToken.check = (0, internal_1.createClassGuardFunction)(RGXRepeatToken);

package/dist/class/union.d.ts

@@ -1,6 +1,7 @@
 import { RGXToken } from "../types";
 import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
 import { RGXClassToken } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 export type RGXUnionInsertionPosition = 'prefix' | 'suffix';
 export declare class RGXClassUnionToken extends RGXClassToken {
     tokens: RGXTokenCollection;
@@ -11,6 +12,7 @@ export declare class RGXClassUnionToken extends RGXClassToken {
     add(token: RGXToken, pos?: RGXUnionInsertionPosition): this;
     concat(pos?: RGXUnionInsertionPosition, ...others: RGXTokenCollectionInput[]): this;
     toRgx(): RegExp;
+    clone(depth?: CloneDepth): RGXClassUnionToken;
 }
 export declare function expandRgxUnionTokens(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection;
 export declare function removeRgxUnionDuplicates(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection;

package/dist/class/union.js

@@ -6,6 +6,7 @@ exports.removeRgxUnionDuplicates = removeRgxUnionDuplicates;
 const internal_1 = require("../internal");
 const collection_1 = require("../collection");
 const base_1 = require("./base");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
 class RGXClassUnionToken extends base_1.RGXClassToken {
     constructor(tokens = []) {
         super();
@@ -44,6 +45,11 @@ class RGXClassUnionToken extends base_1.RGXClassToken {
     toRgx() {
         return this.tokens.toRgx();
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXClassUnionToken(this.tokens.clone((0, immutability_utils_1.depthDecrement)(depth, 1)));
+    }
 }
 exports.RGXClassUnionToken = RGXClassUnionToken;
 RGXClassUnionToken.check = (0, internal_1.createClassGuardFunction)(RGXClassUnionToken);

package/dist/class/wrapper.d.ts

@@ -1,13 +1,15 @@
 import { RGXToken } from "../types";
 import { RGXClassToken } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 export declare class RGXClassWrapperToken extends RGXClassToken {
     token: RGXToken;
     static check: (value: unknown) => value is RGXClassWrapperToken;
     static assert: (value: unknown) => asserts value is RGXClassWrapperToken;
     constructor(token: RGXToken);
-    get isGroup(): boolean;
-    get isRepeatable(): boolean;
+    get rgxIsGroup(): boolean;
+    get rgxIsRepeatable(): boolean;
     unwrap(): RGXToken;
     toRgx(): RGXToken;
+    clone(depth?: CloneDepth): RGXClassWrapperToken;
 }
 export declare const rgxClassWrapper: (token: RGXToken) => RGXClassWrapperToken;

package/dist/class/wrapper.js

@@ -4,17 +4,19 @@ exports.rgxClassWrapper = exports.RGXClassWrapperToken = void 0;
 const base_1 = require("./base");
 const typeGuards_1 = require("../typeGuards");
 const internal_1 = require("../internal");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+const clone_1 = require("../clone");
 class RGXClassWrapperToken extends base_1.RGXClassToken {
     constructor(token) {
         super();
         this.token = token;
     }
-    get isGroup() {
+    get rgxIsGroup() {
         return (0, typeGuards_1.isRGXGroupedToken)(this.token);
     }
-    get isRepeatable() {
+    get rgxIsRepeatable() {
         if ((0, typeGuards_1.isRGXToken)(this.token, 'class'))
-            return this.token.isRepeatable;
+            return this.token.rgxIsRepeatable;
         // Assume any other token is repeatable, since we don't know its implementation.
         return true;
     }
@@ -24,6 +26,11 @@ class RGXClassWrapperToken extends base_1.RGXClassToken {
     toRgx() {
         return this.unwrap();
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXClassWrapperToken((0, clone_1.cloneRGXToken)(this.token, (0, immutability_utils_1.depthDecrement)(depth, 1)));
+    }
 }
 exports.RGXClassWrapperToken = RGXClassWrapperToken;
 RGXClassWrapperToken.check = (0, internal_1.createClassGuardFunction)(RGXClassWrapperToken);

package/dist/clone.d.ts

@@ -0,0 +1,3 @@
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+import { RGXToken } from "./types";
+export declare function cloneRGXToken<T extends RGXToken>(token: T, depth?: CloneDepth): T;

package/dist/clone.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloneRGXToken = cloneRGXToken;
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+const typeGuards_1 = require("./typeGuards");
+function cloneRGXToken(token, depth = "max") {
+    if (depth === 0)
+        return token;
+    if ((0, typeGuards_1.isRGXToken)(token, "no-op") || (0, typeGuards_1.isRGXToken)(token, "native"))
+        return token;
+    return (0, immutability_utils_1.extClone)(token, (0, immutability_utils_1.depthDecrement)(depth, 1));
+}

package/dist/index.d.ts

@@ -10,5 +10,6 @@ export * from "./concat";
 export * from "./utils";
 export * from "./ExtRegExp";
 export * from "./flag-transformer";
+export * from "./clone";
 export declare function rgxa(tokens: t.RGXToken[], flags?: string): ExtRegExp;
 export default function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => ExtRegExp;

package/dist/index.js

@@ -31,6 +31,7 @@ __exportStar(require("./concat"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./ExtRegExp"), exports);
 __exportStar(require("./flag-transformer"), exports);
+__exportStar(require("./clone"), exports);
 // Call this for certain class methods to work correctly
 (0, class_1.rgxClassInit)();
 // Call this for our custom flags to work correctly

package/dist/typeGuards.js

@@ -91,9 +91,13 @@ 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.
+        // The rgxGroupWrap, rgxIsRepeatable, and rgxIsGroup properties are optional, but if they exist they must be booleans.
         if ('rgxGroupWrap' in value && typeof value.rgxGroupWrap !== 'boolean')
             return false;
+        if ('rgxIsRepeatable' in value && typeof value.rgxIsRepeatable !== 'boolean')
+            return false;
+        if ('rgxIsGroup' in value && typeof value.rgxIsGroup !== 'boolean')
+            return false;
         if ((0, is_callable_1.default)(value.toRgx)) {
             if (!returnCheck)
                 return true;
@@ -200,8 +204,8 @@ function isRGXGroupedToken(value, contentCheck = true) {
     // 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()))));
+        (isRGXConvertibleToken(value, false) && (value.rgxIsGroup ||
+            (value.rgxGroupWrap === true && (!contentCheck || isRGXGroupedToken(value.toRgx()))))));
 }
 function assertRGXGroupedToken(value, contentCheck = true) {
     if (!isRGXGroupedToken(value, contentCheck)) {

package/dist/types.d.ts

@@ -8,19 +8,21 @@ export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
 export type RGXConvertibleToken = {
     toRgx: () => RGXToken;
     readonly rgxGroupWrap?: boolean;
+    readonly rgxIsGroup?: boolean;
+    readonly rgxIsRepeatable?: boolean;
 };
 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 = {
+export type RGXGroupedToken = RGXToken[] | RGXLiteralToken | RGXGroupedConvertibleToken;
+export type RGXGroupedConvertibleToken = (RGXConvertibleToken & {
+    readonly rgxIsGroup: true;
+}) | (Omit<RGXConvertibleToken, "toRGX"> & {
     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[];
+export type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof RegExp | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
 export type RGXTokenFromType<T extends RGXTokenTypeGuardInput> = T extends null ? RGXToken : T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? RGXLiteralToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends 'class' ? RGXClassToken : T extends 'array' ? RGXToken[] : T extends new (...args: unknown[]) => infer R ? R : T extends RGXTokenTypeGuardInput[] ? {
     [K in keyof T]: T[K] extends RGXTokenTypeGuardInput ? RGXTokenFromType<T[K]> : never;
 } : never;

package/package.json

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