@ptolemy2002/rgx 2.4.0 → 2.5.1

package/README.md

@@ -23,11 +23,11 @@ type ValidVanillaRegexFlags = Branded<string, [ValidVanillaRegexFlagsBrandSymbol
 
 type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];
 type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
-type RGXTokenFromType<T extends RGXTokenType> =
+type RGXTokenFromType<T extends RGXTokenType | RGXTokenTypeFlat> =
     // ... see source for full definition
 ;
 
-type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS';
+type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED';
 type ExpectedTokenType = {
     type: "tokenType";
     values: RGXTokenTypeFlat[];
@@ -36,6 +36,9 @@ type ExpectedTokenType = {
     values: string[];
 };
 type RGXTokenCollectionMode = 'union' | 'concat';
+type RGXTokenCollectionInput = RGXToken | RGXTokenCollection;
+
+type RGXUnionInsertionPosition = 'prefix' | 'suffix';
 ```
 
 ## Classes
@@ -95,22 +98,38 @@ constructor(message: string, got: string)
 #### Properties
 - `got` (`string`): The actual string that was received, which failed validation.
 
+### RGXNotImplementedError extends RGXError
+A specific error class for unimplemented functionality. This error is thrown when a feature or method has not been implemented yet. The error code is set to `NOT_IMPLEMENTED` on instantiation.
+
+#### Constructor
+```typescript
+constructor(functionality: string, message?: string | null)
+```
+- `functionality` (`string`): A description of the functionality that is not yet implemented.
+- `message` (`string | null`, optional): An optional additional message providing more context. Defaults to `null`.
+
+#### Properties
+- `functionality` (`string`): The description of the unimplemented functionality.
+
+#### Methods
+- `toString()` (`() => string`): Returns a formatted string indicating the unimplemented functionality and any additional message.
+
 ### RGXTokenCollection
-A class representing a collection of RGX tokens. This is not used internally, but may be useful for users who want to easily manage collections of RGX tokens like an array, but with additional metadata about the collection mode (union or concat).
+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.
 
 A function `rgxTokenCollection` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
 
 #### Constructor
 ```typescript
-constructor(tokens: RGXToken[] = [], mode: RGXTokenCollectionMode = 'concat')
+constructor(tokens: RGXTokenCollectionInput = [], mode: RGXTokenCollectionMode = 'concat')
 ```
-- `tokens` (`RGXToken[]`, optional): An array of RGX tokens to be managed by the collection. Defaults to an empty array.
+- `tokens` (`RGXTokenCollectionInput`, optional): The tokens to be managed by the collection. This can be an array of RGX tokens, a single RGX token (which will be wrapped in an array), or another `RGXTokenCollection` (whose tokens will be copied). Defaults to an empty array.
 - `mode` (`RGXTokenCollectionMode`, optional): The mode of the collection, either 'union' or 'concat'. Defaults to 'concat'.
 
 #### 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.
-- `toRgx()` (`() => ValidRegexString`): A method that resolves the collection to a single RGX token based on the collection mode. In both modes, a string is ultimately returned, but in 'union' mode, the tokens are resolved as alternatives (using the `|` operator), while in 'concat' mode, the tokens are resolved as concatenated together.
+- `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.
 - `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.
 - `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.
@@ -118,6 +137,40 @@ constructor(tokens: RGXToken[] = [], mode: RGXTokenCollectionMode = 'concat')
 
 Standard array properties and methods like `length`, `push`, `pop`, etc. are implemented to work with the internal `tokens` array, but providing collection instances instead of raw arrays when relevant (e.g., `map` has the third parameter typed as `RGXTokenCollection` instead of `RGXToken[]`).
 
+### RGXClassToken (abstract)
+An abstract base class for creating custom RGX token classes. Subclasses must implement the `toRgx()` method, which returns a value compatible with `RGXConvertibleTokenOutput`.
+
+#### Abstract Methods
+- `toRgx()` (`() => RGXConvertibleTokenOutput`): Must be implemented by subclasses to return the token's regex representation as a native/literal token or array of native/literal tokens.
+
+#### Properties
+- `isGroup` (`boolean`): Returns `false` by default. Subclasses can override this to indicate whether the token represents a group.
+
+#### Methods
+- `or(...others: RGXTokenCollectionInput[])` (`(...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`.
+
+### RGXClassUnionToken extends RGXClassToken
+A class representing a union (alternation) of RGX tokens. This is typically created via the `or()` method on `RGXClassToken`, but can also be instantiated directly.
+
+A function `rgxClassUnion` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Constructor
+```typescript
+constructor(tokens: RGXTokenCollectionInput = [])
+```
+- `tokens` (`RGXTokenCollectionInput`, optional): The tokens to include in the union. Internally stored as an `RGXTokenCollection` in 'union' mode. Defaults to an empty array.
+
+#### Properties
+- `tokens` (`RGXTokenCollection`): The internal collection of tokens managed in 'union' mode.
+- `isGroup` (`boolean`): Returns `true`, indicating this token represents a group.
+
+#### Methods
+- `add(token: RGXToken, pos?: RGXUnionInsertionPosition)` (`(token: RGXToken, pos?: RGXUnionInsertionPosition) => this`): Adds a token to the union. The `pos` parameter controls where the token is inserted: `'prefix'` inserts at the beginning, `'suffix'` (default) appends to the end. Returns `this` for chaining.
+- `concat(pos?: RGXUnionInsertionPosition, ...others: RGXTokenCollectionInput[])` (`(pos?: RGXUnionInsertionPosition, ...others: RGXTokenCollectionInput[]) => this`): Concatenates additional tokens into the union. The `pos` parameter controls insertion position: `'suffix'` (default) appends to the end, `'prefix'` prepends to the beginning. Returns `this` for chaining.
+- `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`.
+
 ## Functions
 The following functions are exported by the library:
 
@@ -249,9 +302,32 @@ if (type === 'native') {
 #### Returns
 - `RGXTokenType`: The type of the RGX token.
 
+### rgxTokenTypeFlat
+```typescript
+function rgxTokenTypeFlat(value: RGXToken): RGXTokenTypeFlat
+```
+Determines the flat type of a given RGX token (`no-op`, `literal`, `native`, `convertible`, or `array`). The `array` type represents any array of RGX tokens, regardless of the types of the individual tokens within the array.
+
+If you narrow the result of this function to something more specific, you can then convert these string literals into their corresponding token types using the `RGXTokenFromType` utility type or `rgxTokenFromType` function.
+
+```typescript
+const token: RGXToken = ...;
+const type = rgxTokenTypeFlat(token);
+if (type === 'array') {
+    const narrowedToken1 = token as RGXTokenFromType<typeof type>; // narrowedToken is RGXToken[]
+    const narrowedToken2 = rgxTokenFromType(type, token); // same as above
+}
+```
+
+#### Parameters
+  - `value` (`RGXToken`): The RGX token to check.
+
+#### Returns
+- `RGXTokenTypeFlat`: The flat type of the RGX token.
+
 ### rgxTokenFromType
 ```typescript
-function rgxTokenFromType<T extends RGXTokenType>(type: T, value: RGXToken): RGXTokenFromType<T>
+function rgxTokenFromType<T extends RGXTokenType | RGXTokenTypeFlat>(type: T, value: RGXToken): RGXTokenFromType<T>
 ```
 
 Does nothing at runtime, but performs a type assertion to the correct subset of `RGXToken` based on the provided `RGXTokenType`.
@@ -328,26 +404,28 @@ Escapes special regex characters in the given string and brands the result as a
 
 ### resolveRGXToken
 ```typescript
-function resolveRGXToken(token: RGXToken): ValidRegexString
+function resolveRGXToken(token: RGXToken, groupWrap?: 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), 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 (placed in a non-capturing group).
+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`).
 
 #### 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.
 
 #### 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.
 
 ### rgxConcat
 ```typescript
-function rgxConcat(tokens: RGXToken[]): ValidRegexString
+function rgxConcat(tokens: RGXToken[], groupWrap?: boolean): ValidRegexString
 ```
 
 A helper function that resolves an array of RGX tokens and concatenates their resolved string representations together. This is useful for cases where you want to concatenate multiple tokens without creating a union between them.
 
 #### Parameters
   - `tokens` (`RGXToken[]`): The array of RGX tokens to resolve and concatenate.
+  - `groupWrap` (`boolean`, optional): Whether to wrap individual resolved tokens in non-capturing groups. Passed through to `resolveRGXToken`. Defaults to `true`.
 
 #### Returns
 - `ValidRegexString`: The concatenated string representation of the resolved RGX tokens. This is guaranteed to be a valid regex string, as it is composed of the resolved forms of RGX tokens, which are all valid regex strings.
@@ -396,6 +474,39 @@ As an alternative to using the `rgx` template tag, you can directly call `rgxa`
 #### Returns
 - `RegExp`: A `RegExp` object constructed from the resolved tokens and the provided flags.
 
+### expandRgxUnionTokens
+```typescript
+function expandRgxUnionTokens(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection
+```
+
+Recursively expands nested union tokens (arrays, `RGXTokenCollection` instances in union mode, and `RGXClassUnionToken` instances) into a flat `RGXTokenCollection`. This is useful for normalizing a set of union alternatives before deduplication.
+
+#### Parameters
+  - `tokens` (`...RGXTokenCollectionInput[]`): The tokens to expand.
+
+#### Returns
+- `RGXTokenCollection`: A flat collection containing all expanded tokens.
+
+### removeRgxUnionDuplicates
+```typescript
+function removeRgxUnionDuplicates(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection
+```
+
+Removes duplicate tokens from the provided list using `Set` equality and returns a new `RGXTokenCollection` in union mode containing only the unique tokens.
+
+#### Parameters
+  - `tokens` (`...RGXTokenCollectionInput[]`): The tokens to deduplicate.
+
+#### Returns
+- `RGXTokenCollection`: A union-mode collection with duplicates removed.
+
+### rgxClassInit
+```typescript
+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.
+
 ## Peer Dependencies
 - `@ptolemy2002/immutability-utils` ^2.0.0
 - `@ptolemy2002/js-utils` ^3.2.2

package/dist/class/base.d.ts

@@ -0,0 +1,9 @@
+import { RGXConvertibleTokenOutput, ValidRegexString } from "../types";
+import { RGXTokenCollectionInput } from "../collection";
+import type { RGXClassUnionToken } from "./union";
+export declare abstract class RGXClassToken {
+    abstract toRgx(): RGXConvertibleTokenOutput;
+    get isGroup(): boolean;
+    or(...others: RGXTokenCollectionInput[]): RGXClassUnionToken;
+    resolve(): ValidRegexString;
+}

package/dist/class/base.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXClassToken = void 0;
+const errors_1 = require("../errors");
+const resolve_1 = require("../resolve");
+class RGXClassToken {
+    get isGroup() {
+        return false;
+    }
+    or(...others) {
+        throw new errors_1.RGXNotImplementedError('RGXClassToken.or(...others)', 'call rgxClassInit() first.');
+    }
+    resolve() {
+        return (0, resolve_1.resolveRGXToken)(this);
+    }
+}
+exports.RGXClassToken = RGXClassToken;

package/dist/class/index.d.ts

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

package/dist/class/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("./init"), exports);
+__exportStar(require("./base"), exports);
+__exportStar(require("./union"), exports);

package/dist/class/init.d.ts

@@ -0,0 +1 @@
+export declare function rgxClassInit(): void;

package/dist/class/init.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxClassInit = rgxClassInit;
+const base_1 = require("./base");
+const union_1 = require("./union");
+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.
+    base_1.RGXClassToken.prototype.or = function (...others) {
+        if (others.length === 0)
+            return new union_1.RGXClassUnionToken([this]);
+        const expandedOthers = (0, union_1.expandRgxUnionTokens)(...others);
+        // Remove any instances of this token itself
+        const filteredOthers = expandedOthers.tokens.filter(token => token !== this);
+        if (this instanceof union_1.RGXClassUnionToken) {
+            return new union_1.RGXClassUnionToken([...this.tokens, ...filteredOthers]);
+        }
+        else {
+            return new union_1.RGXClassUnionToken([this, ...filteredOthers]);
+        }
+    };
+}

package/dist/class/union.d.ts

@@ -0,0 +1,16 @@
+import { RGXToken } from "../types";
+import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
+import { RGXClassToken } from "./base";
+export type RGXUnionInsertionPosition = 'prefix' | 'suffix';
+export declare class RGXClassUnionToken extends RGXClassToken {
+    tokens: RGXTokenCollection;
+    get isGroup(): boolean;
+    constructor(tokens?: RGXTokenCollectionInput);
+    cleanTokens(): this;
+    add(token: RGXToken, pos?: RGXUnionInsertionPosition): this;
+    concat(pos?: RGXUnionInsertionPosition, ...others: RGXTokenCollectionInput[]): this;
+    toRgx(): RegExp;
+}
+export declare function expandRgxUnionTokens(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection;
+export declare function removeRgxUnionDuplicates(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection;
+export declare const rgxClassUnion: (tokens?: RGXTokenCollectionInput) => RGXClassUnionToken;

package/dist/class/union.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxClassUnion = exports.RGXClassUnionToken = void 0;
+exports.expandRgxUnionTokens = expandRgxUnionTokens;
+exports.removeRgxUnionDuplicates = removeRgxUnionDuplicates;
+const internal_1 = require("../internal");
+const collection_1 = require("../collection");
+const base_1 = require("./base");
+class RGXClassUnionToken extends base_1.RGXClassToken {
+    get isGroup() {
+        return true;
+    }
+    constructor(tokens = []) {
+        super();
+        if (tokens instanceof collection_1.RGXTokenCollection && tokens.mode === 'concat')
+            this.tokens = new collection_1.RGXTokenCollection([tokens], 'union');
+        else
+            this.tokens = new collection_1.RGXTokenCollection(tokens, 'union');
+        this.cleanTokens();
+    }
+    cleanTokens() {
+        this.tokens = removeRgxUnionDuplicates(...expandRgxUnionTokens(...this.tokens));
+        return this;
+    }
+    add(token, pos = 'suffix') {
+        if (token instanceof collection_1.RGXTokenCollection && token.mode === 'union')
+            return this.concat(pos, ...token);
+        if (token instanceof RGXClassUnionToken)
+            return this.concat(pos, ...token.tokens);
+        if (pos === 'prefix') {
+            this.tokens.unshift(token);
+        }
+        else {
+            this.tokens.push(token);
+        }
+        return this.cleanTokens();
+    }
+    concat(pos = 'suffix', ...others) {
+        if (pos === 'suffix') {
+            this.tokens = this.tokens.clone().concat(...others);
+        }
+        else {
+            this.tokens = new collection_1.RGXTokenCollection([...others, ...this.tokens], 'union');
+        }
+        return this.cleanTokens();
+    }
+    toRgx() {
+        return this.tokens.toRgx();
+    }
+}
+exports.RGXClassUnionToken = RGXClassUnionToken;
+function expandRgxUnionTokens(...tokens) {
+    const result = new collection_1.RGXTokenCollection();
+    for (const token of tokens) {
+        if (token instanceof collection_1.RGXTokenCollection && token.mode === 'union') {
+            result.push(...expandRgxUnionTokens(...token));
+        }
+        else if (Array.isArray(token)) {
+            result.push(...expandRgxUnionTokens(...token));
+        }
+        else if (token instanceof RGXClassUnionToken) {
+            result.push(...expandRgxUnionTokens(...token.tokens));
+        }
+        else {
+            result.push(token);
+        }
+    }
+    return result;
+}
+function removeRgxUnionDuplicates(...tokens) {
+    let uniqueTokens = [...new Set(tokens)];
+    // Handle RegExp objects separately since they are not considered equal even if they have the same pattern and flags
+    const seenRegexes = new Set();
+    uniqueTokens = uniqueTokens.filter(token => {
+        if (token instanceof RegExp) {
+            const regexString = token.toString();
+            if (seenRegexes.has(regexString)) {
+                return false;
+            }
+            else {
+                seenRegexes.add(regexString);
+                return true;
+            }
+        }
+        return true;
+    });
+    return new collection_1.RGXTokenCollection(uniqueTokens, 'union');
+}
+exports.rgxClassUnion = (0, internal_1.createConstructFunction)(RGXClassUnionToken);

package/dist/collection.d.ts

@@ -1,12 +1,13 @@
-import { RGXToken, ValidRegexString } from "./types";
+import { RGXToken } from "./types";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import { Collection } from "@ptolemy2002/ts-utils";
 export type RGXTokenCollectionMode = 'union' | 'concat';
+export type RGXTokenCollectionInput = RGXToken | RGXTokenCollection;
 export declare class RGXTokenCollection implements Collection<RGXToken> {
     mode: RGXTokenCollectionMode;
     tokens: RGXToken[];
-    constructor(tokens?: RGXToken[], mode?: RGXTokenCollectionMode);
-    toRgx(): ValidRegexString;
+    constructor(tokens?: RGXTokenCollectionInput, mode?: RGXTokenCollectionMode);
+    toRgx(): RegExp;
     getTokens(): RGXToken[];
     clone(depth?: CloneDepth): RGXTokenCollection;
     asConcat(): RGXTokenCollection;
@@ -28,7 +29,7 @@ export declare class RGXTokenCollection implements Collection<RGXToken> {
     flat(depth?: number): RGXTokenCollection;
     flatMap<T>(callback: (token: RGXToken, index: number, array: RGXTokenCollection) => T | T[], depth?: number): T[];
     slice(start?: number, end?: number): RGXTokenCollection;
-    concat(...others: (RGXToken | RGXToken[] | RGXTokenCollection)[]): RGXTokenCollection;
+    concat(...others: (RGXToken | RGXTokenCollection)[]): RGXTokenCollection;
     push(...tokens: RGXToken[]): void;
     pop(): RGXToken | undefined;
     shift(): RGXToken | undefined;
@@ -42,4 +43,4 @@ export declare class RGXTokenCollection implements Collection<RGXToken> {
     keys(): IterableIterator<number>;
     values(): IterableIterator<RGXToken>;
 }
-export declare const rgxTokenCollection: (tokens?: RGXToken[] | undefined, mode?: RGXTokenCollectionMode | undefined) => RGXTokenCollection;
+export declare const rgxTokenCollection: (tokens?: RGXTokenCollectionInput, mode?: RGXTokenCollectionMode | undefined) => RGXTokenCollection;

package/dist/collection.js

@@ -1,22 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rgxTokenCollection = exports.RGXTokenCollection = void 0;
-const index_1 = require("./index");
+const resolve_1 = require("./resolve");
+const concat_1 = require("./concat");
 const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
 const internal_1 = require("./internal");
 class RGXTokenCollection {
     constructor(tokens = [], mode = 'concat') {
         this.tokens = [];
-        this.tokens = tokens;
+        if (tokens instanceof RGXTokenCollection) {
+            this.tokens = tokens.tokens;
+        }
+        else if (Array.isArray(tokens)) {
+            this.tokens = tokens;
+        }
+        else {
+            this.tokens = [tokens];
+        }
         this.mode = mode;
     }
     toRgx() {
+        let pattern;
         if (this.mode === 'union') {
-            return (0, index_1.resolveRGXToken)(this.tokens);
+            // The RegExp will already be wrapped with resolveRGXToken,
+            // so we don't need to wrap it again here.
+            pattern = (0, resolve_1.resolveRGXToken)(this.tokens, false);
         }
         else {
-            return (0, index_1.rgxConcat)(this.tokens);
+            pattern = (0, concat_1.rgxConcat)(this.tokens);
         }
+        return new RegExp(pattern);
     }
     getTokens() {
         return (0, immutability_utils_1.extClone)(this.tokens, "max");
@@ -101,7 +114,7 @@ class RGXTokenCollection {
     }
     concat(...others) {
         return (0, immutability_utils_1.immutableMut)(this, clone => {
-            const arrays = others.map(o => o instanceof RGXTokenCollection ? o.tokens : Array.isArray(o) ? o : [o]);
+            const arrays = others.map(o => o instanceof RGXTokenCollection && o.mode === this.mode ? o.tokens : Array.isArray(o) ? o : [o]);
             clone.tokens = clone.tokens.concat(...arrays.flat());
         });
     }

package/dist/concat.d.ts

@@ -0,0 +1,2 @@
+import * as t from "./types";
+export declare function rgxConcat(tokens: t.RGXToken[], groupWrap?: boolean): t.ValidRegexString;

package/dist/concat.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxConcat = rgxConcat;
+const resolve_1 = require("./resolve");
+// Wrapper for letting an array of tokens be resolved as a concatenation instead of a union.
+function rgxConcat(tokens, groupWrap = true) {
+    return tokens.map(t => (0, resolve_1.resolveRGXToken)(t, groupWrap)).join('');
+}

package/dist/errors/base.d.ts

@@ -1,4 +1,4 @@
-export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS';
+export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED';
 export declare class RGXError extends Error {
     code: RGXErrorCode;
     constructor(message: string, code?: RGXErrorCode);

package/dist/errors/index.d.ts

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

package/dist/errors/index.js

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

package/dist/errors/notImplemented.d.ts

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

package/dist/errors/notImplemented.js

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

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export * from "./errors";
 export * from "./types";
 export * from "./typeGuards";
 export * from "./collection";
-export declare function escapeRegex(value: string): t.ValidRegexString;
-export declare function resolveRGXToken(token: t.RGXToken): t.ValidRegexString;
-export declare function rgxConcat(tokens: t.RGXToken[]): t.ValidRegexString;
+export * from "./class";
+export * from "./resolve";
+export * from "./concat";
 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

@@ -36,62 +36,38 @@ 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 });
-exports.escapeRegex = escapeRegex;
-exports.resolveRGXToken = resolveRGXToken;
-exports.rgxConcat = rgxConcat;
 exports.rgxa = rgxa;
 exports.default = rgx;
-const e = __importStar(require("./errors"));
 const tg = __importStar(require("./typeGuards"));
+const class_1 = require("./class");
+const concat_1 = require("./concat");
 __exportStar(require("./errors"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./typeGuards"), exports);
 __exportStar(require("./collection"), exports);
-function escapeRegex(value) {
-    return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
-}
-function resolveRGXToken(token) {
-    if (tg.isRGXNoOpToken(token))
-        return '';
-    if (tg.isRGXLiteralToken(token))
-        return '(?:' + token.source + ')';
-    if (tg.isRGXNativeToken(token))
-        return escapeRegex(String(token));
-    if (tg.isRGXConvertibleToken(token)) {
-        return resolveRGXToken(token.toRgx());
-    }
-    // Interpret arrays as unions
-    if (Array.isArray(token)) {
-        if (token.length === 0)
-            return '';
-        if (token.length > 1) {
-            return '(?:' + token.map(resolveRGXToken).join('|') + ')';
-        }
-        return resolveRGXToken(token[0]);
+__exportStar(require("./class"), exports);
+__exportStar(require("./resolve"), exports);
+__exportStar(require("./concat"), exports);
+// Call this for certain class methods to work correctly
+(0, class_1.rgxClassInit)();
+function taggedTemplateToTokenArray(strings, tokens) {
+    const tokenArray = [];
+    for (let i = 0; i < strings.length; i++) {
+        if (strings[i])
+            tokenArray.push(strings[i]);
+        if (i < tokens.length)
+            tokenArray.push(tokens[i]);
     }
-    // Ignoring this line since it should be impossible to reach if the types are correct, but we need it to satisfy the return type
-    /* istanbul ignore next */
-    throw new e.RGXInvalidTokenError(`Invalid RGX token: ${token}`, null, token);
-}
-// Wrapper for letting an array of tokens be resolved as a concatenation instead of a union.
-function rgxConcat(tokens) {
-    return tokens.map(resolveRGXToken).join('');
+    return tokenArray;
 }
 function rgxa(tokens, flags = '') {
     tg.assertValidVanillaRegexFlags(flags);
-    const pattern = rgxConcat(tokens);
+    const pattern = (0, concat_1.rgxConcat)(tokens);
     return new RegExp(pattern, flags);
 }
 function rgx(flags = '') {
     tg.assertValidVanillaRegexFlags(flags);
     return (strings, ...tokens) => {
-        const tokenArray = [];
-        for (let i = 0; i < strings.length; i++) {
-            if (strings[i])
-                tokenArray.push(strings[i]);
-            if (i < tokens.length)
-                tokenArray.push(tokens[i]);
-        }
-        return rgxa(tokenArray, flags);
+        return rgxa(taggedTemplateToTokenArray(strings, tokens), flags);
     };
 }

package/dist/resolve.d.ts

@@ -0,0 +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;

package/dist/resolve.js

@@ -0,0 +1,76 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeRegex = escapeRegex;
+exports.resolveRGXToken = resolveRGXToken;
+const class_1 = require("./class");
+const e = __importStar(require("./errors"));
+const tg = __importStar(require("./typeGuards"));
+function escapeRegex(value) {
+    return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function resolveRGXToken(token, groupWrap = true) {
+    if (tg.isRGXNoOpToken(token))
+        return '';
+    if (tg.isRGXLiteralToken(token)) {
+        if (groupWrap)
+            return '(?:' + token.source + ')';
+        else
+            return token.source;
+    }
+    if (tg.isRGXNativeToken(token))
+        return escapeRegex(String(token));
+    if (tg.isRGXConvertibleToken(token)) {
+        return resolveRGXToken(token.toRgx(), groupWrap);
+    }
+    // Interpret arrays as unions
+    if (Array.isArray(token)) {
+        if (token.length === 0)
+            return '';
+        if (token.length > 1) {
+            // Remove duplicates
+            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('|') + ')';
+            else
+                return token.map(t => resolveRGXToken(t, true)).join('|');
+        }
+        return resolveRGXToken(token[0]);
+    }
+    // Ignoring this line since it should be impossible to reach if the types are correct, but we need it to satisfy the return type
+    /* istanbul ignore next */
+    throw new e.RGXInvalidTokenError(`Invalid RGX token: ${token}`, null, token);
+}

package/dist/typeGuards.d.ts

@@ -7,8 +7,9 @@ export declare function isRGXNativeToken(value: unknown): value is t.RGXNativeTo
 export declare function assertRGXNativeToken(value: unknown): asserts value is t.RGXNativeToken;
 export declare function isRGXConvertibleToken(value: unknown): value is t.RGXConvertibleToken;
 export declare function assertRGXConvertibleToken(value: unknown): asserts value is t.RGXConvertibleToken;
+export declare function rgxTokenTypeFlat(value: t.RGXToken): t.RGXTokenTypeFlat;
 export declare function rgxTokenType(value: t.RGXToken): t.RGXTokenType;
-export declare function rgxTokenFromType<T extends t.RGXTokenType>(type: T, value: t.RGXToken): t.RGXTokenFromType<T>;
+export declare function rgxTokenFromType<T extends t.RGXTokenType | t.RGXTokenTypeFlat>(type: T, value: t.RGXToken): t.RGXTokenFromType<T>;
 export declare function isValidRegexString(value: string): value is t.ValidRegexString;
 export declare function assertValidRegexString(value: string): asserts value is t.ValidRegexString;
 export declare function isValidVanillaRegexFlags(value: string): value is t.ValidVanillaRegexFlags;

package/dist/typeGuards.js

@@ -44,6 +44,7 @@ exports.isRGXNativeToken = isRGXNativeToken;
 exports.assertRGXNativeToken = assertRGXNativeToken;
 exports.isRGXConvertibleToken = isRGXConvertibleToken;
 exports.assertRGXConvertibleToken = assertRGXConvertibleToken;
+exports.rgxTokenTypeFlat = rgxTokenTypeFlat;
 exports.rgxTokenType = rgxTokenType;
 exports.rgxTokenFromType = rgxTokenFromType;
 exports.isValidRegexString = isValidRegexString;
@@ -94,7 +95,7 @@ function assertRGXConvertibleToken(value) {
         throw new e.RGXInvalidTokenError(`Invalid convertible token`, { type: "tokenType", values: ['convertible'] }, value);
     }
 }
-function rgxTokenType(value) {
+function rgxTokenTypeFlat(value) {
     if (isRGXNoOpToken(value))
         return 'no-op';
     if (isRGXLiteralToken(value))
@@ -104,6 +105,16 @@ function rgxTokenType(value) {
     if (isRGXConvertibleToken(value))
         return 'convertible';
     if (Array.isArray(value))
+        return 'array';
+    // Ignoring this line since it should be impossible to reach if the types are correct, but we need it to satisfy the return type
+    /* istanbul ignore next */
+    throw new e.RGXInvalidTokenError("Invalid RGX token", null, value);
+}
+function rgxTokenType(value) {
+    const flatType = rgxTokenTypeFlat(value);
+    if (flatType !== 'array')
+        return flatType;
+    if (flatType === 'array')
         return value.map(rgxTokenType);
     // Ignoring this line since it should be impossible to reach if the types are correct, but we need it to satisfy the return type
     /* istanbul ignore next */

package/dist/types.d.ts

@@ -10,7 +10,7 @@ export type RGXConvertibleToken = {
 export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];
 export type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
-export type RGXTokenFromType<T extends RGXTokenType> = T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? RGXLiteralToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends RGXTokenType[] ? {
+export type RGXTokenFromType<T extends RGXTokenType | RGXTokenTypeFlat> = T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? RGXLiteralToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends 'array' ? RGXToken[] : T extends RGXTokenType[] ? {
     [K in keyof T]: T[K] extends RGXTokenType ? RGXTokenFromType<T[K]> : never;
 } : never;
 export declare const validRegexSymbol: unique symbol;

package/package.json

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