@ptolemy2002/rgx 2.1.0 → 2.3.0

package/README.md

@@ -9,7 +9,8 @@ import { MaybeArray } from "@ptolemy2002/ts-utils";
 type RGXNoOpToken = null | undefined;
 type RGXLiteralToken = RegExp;
 type RGXNativeToken = string | number | boolean | RGXNoOpToken;
-type RGXConvertibleToken = { toRgx: () => MaybeArray<RGXNativeToken | RGXLiteralToken> };
+type RGXConvertibleTokenOutput = MaybeArray<RGXNativeToken | RGXLiteralToken>;
+type RGXConvertibleToken = { toRgx: () => RGXConvertibleTokenOutput };
 type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 
 const validRegexSymbol = Symbol('rgx.ValidRegex');
@@ -21,11 +22,20 @@ type ValidVanillaRegexFlagsBrandSymbol = typeof validVanillaRegexFlagsSymbol;
 type ValidVanillaRegexFlags = Branded<string, [ValidVanillaRegexFlagsBrandSymbol]>;
 
 type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];
+type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
 type RGXTokenFromType<T extends RGXTokenType> =
     // ... see source for full definition
 ;
 
 type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS';
+type ExpectedTokenType = {
+    type: "tokenType";
+    values: RGXTokenTypeFlat[];
+} | {
+    type: "custom";
+    values: string[];
+};
+type RGXTokenCollectionMode = 'union' | 'concat';
 ```
 
 ## Classes
@@ -41,15 +51,22 @@ constructor(message: string, code?: RGXErrorCode)
 - `message` (`string`): The error message.
 - `code` (`RGXErrorCode`, optional): An optional error code that can be used to categorize the error. If not provided, it defaults to 'UNKNOWN'.
 
+#### Properties
+- `code` (`RGXErrorCode`): The error code associated with the error, which can be used to identify the type of error that occurred.
+
 ### RGXInvalidTokenError extends RGXError
 A specific error class for invalid RGX tokens. This error is thrown when a value fails validation as a specific RGX token type. The error code is set to `INVALID_RGX_TOKEN` on instantiation.
 
 #### Constructor
 ```typescript
-constructor(message: string, expected: string | null, got: unknown)
+constructor(message: string, expected: ExpectedTokenType | null, got: unknown)
 ```
 - `message` (`string`): The error message.
-- `expected` (`string` | `null`): A description of the expected token type. If `null`, will use a default message indicating the expected types of any RGX token.
+- `expected` (`ExpectedTokenType | null`): Either an object describing the expected token type(s) or `null` if all token types are expected. This is used to generate a human-readable description of what was expected.
+- `got` (`unknown`): The actual value that was received, which failed validation.
+
+#### Properties
+- `expected` (`string`): A human-readable description of the expected token type(s), generated from the `expected` parameter in the constructor. This can be used to provide more informative error messages.
 - `got` (`unknown`): The actual value that was received, which failed validation.
 
 ### RGXInvalidRegexStringError extends RGXError
@@ -62,6 +79,9 @@ 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.
+
 ### RGXInvalidVanillaRegexFlagsError extends RGXError
 A specific error class for invalid vanilla regex flags. This error is thrown when a string fails validation as valid vanilla regex flags. The error code is set to `INVALID_VANILLA_REGEX_FLAGS` on instantiation.
 
@@ -72,6 +92,30 @@ 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.
+
+### 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).
+
+#### Constructor
+```typescript
+constructor(tokens: RGXToken[] = [], mode: RGXTokenCollectionMode = 'concat')
+```
+- `tokens` (`RGXToken[]`, optional): An array of RGX tokens to be managed by the collection. 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()` (`() => RGXToken`): 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.
+- `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.
+- `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.
+
+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[]`).
+
 ## Functions
 The following functions are exported by the library:
 
@@ -351,9 +395,12 @@ As an alternative to using the `rgx` template tag, you can directly call `rgxa`
 - `RegExp`: A `RegExp` object constructed from the resolved tokens and the provided flags.
 
 ## Peer Dependencies
+- `@ptolemy2002/immutability-utils` ^1.2.1
+- `@ptolemy2002/js-utils` ^3.2.2
 - `@ptolemy2002/ts-brand-utils` ^1.0.0
 - `@ptolemy2002/ts-utils` ^3.4.0
 - `is-callable` ^1.2.7
+- `lodash.clonedeep` ^4.5.0
 
 ## Commands
 The following commands exist in the project:

package/dist/collection.d.ts

@@ -0,0 +1,41 @@
+import { RGXConvertibleTokenOutput, RGXToken } from "./types";
+export type RGXTokenCollectionMode = 'union' | 'concat';
+export declare class RGXTokenCollection {
+    mode: RGXTokenCollectionMode;
+    tokens: RGXToken[];
+    constructor(tokens?: RGXToken[], mode?: RGXTokenCollectionMode);
+    toRgx(): RGXConvertibleTokenOutput;
+    getTokens(): RGXToken[];
+    clone(): RGXTokenCollection;
+    asConcat(): RGXTokenCollection;
+    asUnion(): RGXTokenCollection;
+    get length(): number;
+    at(index: number): RGXToken | undefined;
+    find(predicate: (token: RGXToken, index: number, array: RGXToken[]) => boolean): RGXToken | undefined;
+    findIndex(predicate: (token: RGXToken, index: number, array: RGXToken[]) => boolean): number;
+    indexOf(token: RGXToken, fromIndex?: number): number;
+    includes(token: RGXToken, fromIndex?: number): boolean;
+    some(predicate: (token: RGXToken, index: number, array: RGXToken[]) => boolean): boolean;
+    every(predicate: (token: RGXToken, index: number, array: RGXToken[]) => boolean): boolean;
+    forEach(callback: (token: RGXToken, index: number, array: RGXToken[]) => void): void;
+    map(callback: (token: RGXToken, index: number, array: RGXToken[]) => RGXToken): RGXTokenCollection;
+    filter(predicate: (token: RGXToken, index: number, array: RGXToken[]) => boolean): RGXTokenCollection;
+    reduce<T>(callback: (accumulator: T, token: RGXToken, index: number, array: RGXToken[]) => T, initialValue: T): T;
+    reduce(callback: (accumulator: RGXToken, token: RGXToken, index: number, array: RGXToken[]) => RGXToken): RGXToken;
+    flat(depth?: number): RGXTokenCollection;
+    flatMap(callback: (token: RGXToken, index: number, array: RGXToken[]) => RGXToken | RGXToken[]): RGXTokenCollection;
+    slice(start?: number, end?: number): RGXTokenCollection;
+    concat(...others: (RGXToken | RGXTokenCollection)[]): RGXTokenCollection;
+    push(...tokens: RGXToken[]): void;
+    pop(): RGXToken | undefined;
+    shift(): RGXToken | undefined;
+    unshift(...tokens: RGXToken[]): number;
+    splice(start: number, deleteCount?: number, ...items: RGXToken[]): RGXTokenCollection;
+    reverse(): this;
+    sort(compareFn?: (a: RGXToken, b: RGXToken) => number): this;
+    fill(value: RGXToken, start?: number, end?: number): this;
+    [Symbol.iterator](): Iterator<RGXToken>;
+    entries(): IterableIterator<[number, RGXToken]>;
+    keys(): IterableIterator<number>;
+    values(): IterableIterator<RGXToken>;
+}

package/dist/collection.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXTokenCollection = void 0;
+const lodash_clonedeep_1 = __importDefault(require("lodash.clonedeep"));
+const index_1 = require("./index");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+class RGXTokenCollection {
+    constructor(tokens = [], mode = 'concat') {
+        this.tokens = [];
+        this.tokens = (0, lodash_clonedeep_1.default)(tokens);
+        this.mode = mode;
+    }
+    toRgx() {
+        if (this.mode === 'union') {
+            return (0, index_1.resolveRGXToken)(this.tokens.map(index_1.resolveRGXToken));
+        }
+        else {
+            return (0, index_1.rgxConcat)(this.tokens);
+        }
+    }
+    getTokens() {
+        return (0, lodash_clonedeep_1.default)(this.tokens);
+    }
+    clone() {
+        return new RGXTokenCollection(this.tokens, this.mode);
+    }
+    asConcat() {
+        if (this.mode === 'concat')
+            return this;
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            clone.mode = 'concat';
+        });
+    }
+    asUnion() {
+        if (this.mode === 'union')
+            return this;
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            clone.mode = 'union';
+        });
+    }
+    // ------------------ Standard array properties and methods ------------------
+    get length() {
+        return this.tokens.length;
+    }
+    at(index) {
+        return this.tokens[index];
+    }
+    find(predicate) {
+        return this.tokens.find(predicate);
+    }
+    findIndex(predicate) {
+        return this.tokens.findIndex(predicate);
+    }
+    indexOf(token, fromIndex) {
+        return this.tokens.indexOf(token, fromIndex);
+    }
+    includes(token, fromIndex) {
+        return this.tokens.includes(token, fromIndex);
+    }
+    some(predicate) {
+        return this.tokens.some(predicate);
+    }
+    every(predicate) {
+        return this.tokens.every(predicate);
+    }
+    forEach(callback) {
+        this.tokens.forEach(callback);
+    }
+    map(callback) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            clone.tokens = clone.tokens.map(callback);
+        });
+    }
+    filter(predicate) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            clone.tokens = clone.tokens.filter(predicate);
+        });
+    }
+    reduce(callback, ...rest) {
+        if (rest.length > 0) {
+            return this.tokens.reduce(callback, rest[0]);
+        }
+        return this.tokens.reduce(callback);
+    }
+    flat(depth = 1) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            // Fixing TypeScript complaining about possible infinite recursion here.
+            clone.tokens = clone.tokens.flat(depth);
+        });
+    }
+    flatMap(callback) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            // Fixing TypeScript complaining about possible infinite recursion here.
+            clone.tokens = clone.tokens.flatMap(callback);
+        });
+    }
+    slice(start, end) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            clone.tokens = clone.tokens.slice(start, end);
+        });
+    }
+    concat(...others) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            const arrays = others.map(o => o instanceof RGXTokenCollection ? o.tokens : [o]);
+            clone.tokens = clone.tokens.concat(...arrays.flat());
+        });
+    }
+    push(...tokens) {
+        this.tokens.push(...tokens);
+    }
+    pop() {
+        return this.tokens.pop();
+    }
+    shift() {
+        return this.tokens.shift();
+    }
+    unshift(...tokens) {
+        return this.tokens.unshift(...tokens);
+    }
+    splice(start, deleteCount, ...items) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            const removed = deleteCount === undefined
+                ? this.tokens.splice(start)
+                : this.tokens.splice(start, deleteCount, ...items);
+            clone.tokens = removed;
+        });
+    }
+    reverse() {
+        this.tokens.reverse();
+        return this;
+    }
+    sort(compareFn) {
+        this.tokens.sort(compareFn);
+        return this;
+    }
+    fill(value, start, end) {
+        this.tokens.fill(value, start, end);
+        return this;
+    }
+    [Symbol.iterator]() {
+        return this.tokens[Symbol.iterator]();
+    }
+    entries() {
+        return this.tokens.entries();
+    }
+    keys() {
+        return this.tokens.keys();
+    }
+    values() {
+        return this.tokens.values();
+    }
+}
+exports.RGXTokenCollection = RGXTokenCollection;

package/dist/errors/base.d.ts

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

package/dist/errors/base.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXError = void 0;
+class RGXError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = 'UNKNOWN';
+        this.name = 'RGXError';
+        if (code) {
+            this.code = code;
+        }
+    }
+}
+exports.RGXError = RGXError;

package/dist/errors/index.d.ts

@@ -0,0 +1,4 @@
+export * from './base';
+export * from './invalidToken';
+export * from './invalidRegexString';
+export * from './invalidVanillaRegexFlags';

package/dist/errors/index.js

@@ -0,0 +1,20 @@
+"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("./base"), exports);
+__exportStar(require("./invalidToken"), exports);
+__exportStar(require("./invalidRegexString"), exports);
+__exportStar(require("./invalidVanillaRegexFlags"), exports);

package/dist/errors/invalidRegexString.d.ts

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

package/dist/errors/invalidRegexString.js

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

package/dist/errors/invalidToken.d.ts

@@ -0,0 +1,16 @@
+import { RGXError } from "./";
+import { RGXTokenTypeFlat } from "../types";
+export type ExpectedTokenType = {
+    type: "tokenType";
+    values: RGXTokenTypeFlat[];
+} | {
+    type: "custom";
+    values: string[];
+};
+export declare class RGXInvalidTokenError extends RGXError {
+    expected: string;
+    got: unknown;
+    setExpected(expected: ExpectedTokenType | null): string;
+    constructor(message: string, expected: ExpectedTokenType | null, got: unknown);
+    toString(): string;
+}

package/dist/errors/invalidToken.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXInvalidTokenError = void 0;
+const errors_1 = require("./");
+const js_utils_1 = require("@ptolemy2002/js-utils");
+const tokenExpectationMap = {
+    'no-op': ['null', 'undefined'],
+    'literal': ['RegExp'],
+    'native': ['string', 'number', 'boolean', 'null', 'undefined'],
+    'convertible': ['object with a toRgx method that returns a valid token'],
+    'array': ['array of native/literal tokens'],
+};
+class RGXInvalidTokenError extends errors_1.RGXError {
+    setExpected(expected) {
+        let result;
+        if (expected === null) {
+            // Add them all
+            const uniqueValues = new Set();
+            for (const tokenType in tokenExpectationMap) {
+                tokenExpectationMap[tokenType].forEach(e => uniqueValues.add(e));
+            }
+            result = (0, js_utils_1.listInPlainEnglish)(Array.from(uniqueValues), { conjunction: 'or' });
+        }
+        else if (expected.type === 'tokenType') {
+            const uniqueValues = new Set();
+            for (const tokenType of expected.values) {
+                const expectations = tokenExpectationMap[tokenType];
+                if (expectations) {
+                    expectations.forEach(e => uniqueValues.add(e));
+                }
+            }
+            result = (0, js_utils_1.listInPlainEnglish)(Array.from(uniqueValues), { conjunction: 'or' });
+        }
+        else {
+            result = (0, js_utils_1.listInPlainEnglish)(expected.values, { conjunction: 'or' });
+        }
+        this.expected = `[${result}]`;
+        return this.expected;
+    }
+    constructor(message, expected, got) {
+        super(message, 'INVALID_RGX_TOKEN');
+        this.name = 'RGXInvalidTokenError';
+        this.got = got;
+        this.setExpected(expected);
+    }
+    toString() {
+        return `${this.name}: ${this.message}; Expected: ${this.expected}; Got: ${JSON.stringify(this.got)}`;
+    }
+}
+exports.RGXInvalidTokenError = RGXInvalidTokenError;

package/dist/errors/invalidVanillaRegexFlags.d.ts

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

package/dist/errors/invalidVanillaRegexFlags.js

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

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import * as t from "./types";
 export * from "./errors";
 export * from "./types";
-export * from "./type-guards";
+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;

package/dist/index.js

@@ -42,10 +42,11 @@ exports.rgxConcat = rgxConcat;
 exports.rgxa = rgxa;
 exports.default = rgx;
 const e = __importStar(require("./errors"));
-const tg = __importStar(require("./type-guards"));
+const tg = __importStar(require("./typeGuards"));
 __exportStar(require("./errors"), exports);
 __exportStar(require("./types"), exports);
-__exportStar(require("./type-guards"), exports);
+__exportStar(require("./typeGuards"), exports);
+__exportStar(require("./collection"), exports);
 function escapeRegex(value) {
     return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/dist/{type-guards.js → typeGuards.js}

@@ -57,7 +57,7 @@ function isRGXNoOpToken(value) {
 }
 function assertRGXNoOpToken(value) {
     if (!isRGXNoOpToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid no-op token`, 'null or undefined', value);
+        throw new e.RGXInvalidTokenError(`Invalid no-op token`, { type: "tokenType", values: ['no-op'] }, value);
     }
 }
 function isRGXLiteralToken(value) {
@@ -65,7 +65,7 @@ function isRGXLiteralToken(value) {
 }
 function assertRGXLiteralToken(value) {
     if (!isRGXLiteralToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid literal token`, 'RegExp', value);
+        throw new e.RGXInvalidTokenError("Invalid literal token", { type: "tokenType", values: ['literal'] }, value);
     }
 }
 function isRGXNativeToken(value) {
@@ -73,7 +73,7 @@ function isRGXNativeToken(value) {
 }
 function assertRGXNativeToken(value) {
     if (!isRGXNativeToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid native token`, 'string, number, boolean, null, or undefined', value);
+        throw new e.RGXInvalidTokenError("Invalid native token", { type: "tokenType", values: ['native'] }, value);
     }
 }
 function isRGXConvertibleToken(value) {
@@ -91,7 +91,7 @@ function isRGXConvertibleToken(value) {
 }
 function assertRGXConvertibleToken(value) {
     if (!isRGXConvertibleToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid convertible token`, 'object with a toRgx method that returns a valid token', value);
+        throw new e.RGXInvalidTokenError(`Invalid convertible token`, { type: "tokenType", values: ['convertible'] }, value);
     }
 }
 function rgxTokenType(value) {
@@ -107,7 +107,7 @@ function rgxTokenType(value) {
         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 */
-    throw new e.RGXInvalidTokenError(`Invalid RGX token: ${value}`, null, value);
+    throw new e.RGXInvalidTokenError("Invalid RGX token", null, value);
 }
 function rgxTokenFromType(type, value) {
     // Ignoring this line because the function is entirely a TypeScript utility that doesn't need to be tested at runtime.
@@ -125,7 +125,7 @@ function isValidRegexString(value) {
 }
 function assertValidRegexString(value) {
     if (!isValidRegexString(value)) {
-        throw new e.RGXInvalidRegexStringError(`Invalid regex string: ${value}`, value);
+        throw new e.RGXInvalidRegexStringError("Invalid regex string", value);
     }
 }
 function isValidVanillaRegexFlags(value) {
@@ -138,6 +138,6 @@ function isValidVanillaRegexFlags(value) {
 }
 function assertValidVanillaRegexFlags(value) {
     if (!isValidVanillaRegexFlags(value)) {
-        throw new e.RGXInvalidVanillaRegexFlagsError(`Invalid vanilla regex flags: ${value}`, value);
+        throw new e.RGXInvalidVanillaRegexFlagsError("Invalid vanilla regex flags", value);
     }
 }

package/dist/types.d.ts

@@ -3,11 +3,13 @@ import { MaybeArray } from "@ptolemy2002/ts-utils";
 export type RGXNoOpToken = null | undefined;
 export type RGXLiteralToken = RegExp;
 export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
+export type RGXConvertibleTokenOutput = MaybeArray<RGXNativeToken | RGXLiteralToken>;
 export type RGXConvertibleToken = {
-    toRgx: () => MaybeArray<RGXNativeToken | RGXLiteralToken>;
+    toRgx: () => RGXConvertibleTokenOutput;
 };
 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[] ? {
     [K in keyof T]: T[K] extends RGXTokenType ? RGXTokenFromType<T[K]> : never;
 } : never;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/rgx",
-    "version": "2.1.0",
+    "version": "2.3.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -29,20 +29,27 @@
         "release-major": "bash ./scripts/release.sh major"
     },
     "devDependencies": {
+        "@ptolemy2002/immutability-utils": "^1.2.1",
+        "@ptolemy2002/js-utils": "^3.2.2",
         "@ptolemy2002/ts-brand-utils": "^1.0.0",
         "@ptolemy2002/ts-utils": "^3.4.0",
         "@types/is-callable": "^1.1.2",
         "@types/jest": "^29.5.0",
+        "@types/lodash.clonedeep": "^4.5.9",
         "is-callable": "^1.2.7",
         "jest": "^29.5.0",
+        "lodash.clonedeep": "^4.5.0",
         "ts-jest": "^29.1.0",
         "ts-patch": "^3.3.0",
         "tsconfig-paths": "^4.2.0",
         "typescript-transform-paths": "^3.5.3"
     },
     "peerDependencies": {
+        "@ptolemy2002/immutability-utils": "^1.2.1",
+        "@ptolemy2002/js-utils": "^3.2.2",
         "@ptolemy2002/ts-brand-utils": "^1.0.0",
         "@ptolemy2002/ts-utils": "^3.4.0",
-        "is-callable": "^1.2.7"
+        "is-callable": "^1.2.7",
+        "lodash.clonedeep": "^4.5.0"
     }
 }

package/dist/errors.d.ts

@@ -1,21 +0,0 @@
-export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS';
-export declare class RGXError extends Error {
-    code: RGXErrorCode;
-    constructor(message: string, code?: RGXErrorCode);
-}
-export declare class RGXInvalidTokenError extends RGXError {
-    expected: string;
-    got: unknown;
-    constructor(message: string, expected: string | null, got: unknown);
-    toString(): string;
-}
-export declare class RGXInvalidRegexStringError extends RGXError {
-    got: string;
-    constructor(message: string, got: string);
-    toString(): string;
-}
-export declare class RGXInvalidVanillaRegexFlagsError extends RGXError {
-    got: string;
-    constructor(message: string, got: string);
-    toString(): string;
-}

package/dist/errors.js

@@ -1,50 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RGXInvalidVanillaRegexFlagsError = exports.RGXInvalidRegexStringError = exports.RGXInvalidTokenError = exports.RGXError = void 0;
-class RGXError extends Error {
-    constructor(message, code) {
-        super(message);
-        this.code = 'UNKNOWN';
-        this.name = 'RGXError';
-        if (code) {
-            this.code = code;
-        }
-    }
-}
-exports.RGXError = RGXError;
-class RGXInvalidTokenError extends RGXError {
-    constructor(message, expected, got) {
-        super(message, 'INVALID_RGX_TOKEN');
-        this.expected = '[null, undefined, string, number, boolean, RegExp, convertible object, or array of native/literal tokens]';
-        this.name = 'RGXInvalidTokenError';
-        if (expected !== null)
-            this.expected = "[" + expected + "]";
-        this.got = got;
-    }
-    toString() {
-        return `${this.name}: ${this.message}; Expected: ${this.expected}; Got: ${JSON.stringify(this.got)}`;
-    }
-}
-exports.RGXInvalidTokenError = RGXInvalidTokenError;
-class RGXInvalidRegexStringError extends RGXError {
-    constructor(message, got) {
-        super(message, 'INVALID_REGEX_STRING');
-        this.name = 'RGXInvalidRegexStringError';
-        this.got = got;
-    }
-    toString() {
-        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
-    }
-}
-exports.RGXInvalidRegexStringError = RGXInvalidRegexStringError;
-class RGXInvalidVanillaRegexFlagsError extends RGXError {
-    constructor(message, got) {
-        super(message, 'INVALID_VANILLA_REGEX_FLAGS');
-        this.name = 'RGXInvalidVanillaRegexFlagsError';
-        this.got = got;
-    }
-    toString() {
-        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
-    }
-}
-exports.RGXInvalidVanillaRegexFlagsError = RGXInvalidVanillaRegexFlagsError;