@ptolemy2002/rgx 2.7.1 → 2.9.0

package/README.md

@@ -4,13 +4,11 @@ A library for easy construction and validation of regular expressions in TypeScr
 ## Type Reference
 ```typescript
 import { Branded } from "@ptolemy2002/ts-brand-utils";
-import { MaybeArray } from "@ptolemy2002/ts-utils";
 
 type RGXNoOpToken = null | undefined;
 type RGXLiteralToken = RegExp;
 type RGXNativeToken = string | number | boolean | RGXNoOpToken;
-type RGXConvertibleTokenOutput = MaybeArray<RGXNativeToken | RGXLiteralToken>;
-type RGXConvertibleToken = { toRgx: () => RGXConvertibleTokenOutput };
+type RGXConvertibleToken = { toRgx: () => RGXToken };
 type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 
 const validRegexSymbol = Symbol('rgx.ValidRegex');
@@ -140,10 +138,12 @@ constructor(tokens: RGXTokenCollectionInput = [], mode: RGXTokenCollectionMode =
 Standard array properties and methods like `length`, `push`, `pop`, etc. are implemented to work with the internal `tokens` array, but providing collection instances instead of raw arrays when relevant (e.g., `map` has the third parameter typed as `RGXTokenCollection` instead of `RGXToken[]`).
 
 ### 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`.
+An abstract base class for creating custom RGX token classes. Subclasses must implement the `toRgx()` method, which returns any valid `RGXToken` (including other convertible tokens, allowing for recursive structures).
+
+Two type guards are provided for this class: `isRgxClassToken` to check if a value is an instance of `RGXClassToken`, and `assertRgxClassToken` to assert that a value is an instance of `RGXClassToken` (throwing an `InvalidTokenError` if the assertion fails). Both of these take a single parameter of type `unknown` for the value.
 
 #### 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.
+- `toRgx() => RGXToken`: Must be implemented by subclasses to return the token's regex representation as any valid RGX token (native, literal, convertible, or array of tokens).
 
 #### Properties
 - `isGroup` (`boolean`): Returns `false` by default. Subclasses can override this to indicate whether the token represents a group.
@@ -155,7 +155,7 @@ An abstract base class for creating custom RGX token classes. Subclasses must im
 ### 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.
+A function `rgxClassUnion` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword. Two type guards are provided for this class: `isRgxClassUnionToken` to check if a value is an instance of `RGXClassUnionToken`, and `assertRgxClassUnionToken` to assert that a value is an instance of `RGXClassUnionToken` (throwing an `InvalidTokenError` if the assertion fails). Both of these take a single parameter of type `unknown` for the value.
 
 #### Constructor
 ```typescript
@@ -256,49 +256,53 @@ Asserts that the given value is a native token (string, number, boolean, or no-o
 
 ### isRGXConvertibleToken
 ```typescript
-function isRGXConvertibleToken(value: unknown): value is RGXConvertibleToken
+function isRGXConvertibleToken(value: unknown, returnCheck?: boolean): value is RGXConvertibleToken
 ```
 
-Checks if the given value is a convertible token (an object with a `toRgx` method). Validates that `toRgx` is callable and returns a valid RGX native or literal token, or an array of native/literal tokens.
+Checks if the given value is a convertible token (an object with a `toRgx` method). When `returnCheck` is `true` (the default), also validates that `toRgx` is callable and returns a valid `RGXToken` (which can be any RGX token type, including other convertible tokens, allowing for recursive structures).
 
 #### Parameters
   - `value` (`unknown`): The value to check.
+  - `returnCheck` (`boolean`, optional): Whether to validate the return value of the `toRgx` method. Defaults to `true`. When `false`, only checks that `toRgx` exists and is callable. **Note**: Setting this to `false` makes the type guard assertion strictly unsafe, as it doesn't verify that the `toRgx` method actually returns a valid `RGXToken`. However, depending on the type of the value you're checking, you might not need that safety (e.g., when checking values that you know are valid based on other context).
 
 #### Returns
 - `boolean`: `true` if the value is a convertible token, otherwise `false`.
 
 ### assertRGXConvertibleToken
 ```typescript
-function assertRGXConvertibleToken(value: unknown): asserts value is RGXConvertibleToken
+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). Validates that `toRgx` is callable and returns a valid RGX native or literal token, or an array of native/literal tokens. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+Asserts that the given value is a convertible token (an object with a `toRgx` method). When `returnCheck` is `true` (the default), also validates that `toRgx` is callable and returns a valid `RGXToken` (which can be any RGX token type, including other convertible tokens, allowing for recursive structures). If the assertion fails, an `RGXInvalidTokenError` will be thrown.
 
 #### Parameters
   - `value` (`unknown`): The value to assert.
+  - `returnCheck` (`boolean`, optional): Whether to validate the return value of the `toRgx` method. Defaults to `true`. When `false`, only checks that `toRgx` exists and is callable. **Note**: Setting this to `false` makes the type guard assertion strictly unsafe, as it doesn't verify that the `toRgx` method actually returns a valid `RGXToken`. However, depending on the type of the value you're asserting, you might not need that safety (e.g., when asserting values that you know are valid based on other context).
 
 #### Returns
 - `void`: This function does not return a value, but will throw an error if the assertion fails.
 
 ### isRGXArrayToken
 ```typescript
-function isRGXArrayToken(value: unknown): value is RGXToken[]
+function isRGXArrayToken(value: unknown, contentCheck?: boolean): value is RGXToken[]
 ```
-Checks if the given value is an array of RGX tokens. Validates that the value is an array and that every element is a valid RGX token (of any type, including nested arrays).
+Checks if the given value is an array of RGX tokens. When `contentCheck` is `true` (the default), validates that the value is an array and that every element is a valid RGX token (of any type, including nested arrays). When `contentCheck` is `false`, only checks that the value is an array without validating the contents.
 
 #### Parameters
   - `value` (`unknown`): The value to check.
+  - `contentCheck` (`boolean`, optional): Whether to validate that every element is a valid RGX token. Defaults to `true`. When `false`, only checks that the value is an array. **Note**: Setting this to `false` makes the type guard assertion strictly unsafe, as it doesn't verify that the array elements are actually valid `RGXToken` values. However, depending on the context, you might not need that safety (e.g., when checking arrays that you know are valid based on other validation).
 
 #### Returns
-- `boolean`: `true` if the value is an array of RGX tokens, otherwise `false`.
+- `boolean`: `true` if the value is an array of RGX tokens (or just an array when `contentCheck` is `false`), otherwise `false`.
 
 ### assertRGXArrayToken
 ```typescript
-function assertRGXArrayToken(value: unknown): asserts value is RGXToken[]
+function assertRGXArrayToken(value: unknown, contentCheck?: boolean): asserts value is RGXToken[]
 ```
-Asserts that the given value is an array of RGX tokens. Validates that the value is an array and that every element is a valid RGX token (of any type, including nested arrays). If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+Asserts that the given value is an array of RGX tokens. When `contentCheck` is `true` (the default), validates that the value is an array and that every element is a valid RGX token (of any type, including nested arrays). When `contentCheck` is `false`, only checks that the value is an array without validating the contents. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
 
 #### Parameters
   - `value` (`unknown`): The value to assert.
+  - `contentCheck` (`boolean`, optional): Whether to validate that every element is a valid RGX token. Defaults to `true`. When `false`, only checks that the value is an array. **Note**: Setting this to `false` makes the type guard assertion strictly unsafe, as it doesn't verify that the array elements are actually valid `RGXToken` values. However, depending on the context, you might not need that safety (e.g., when asserting arrays that you know are valid based on other validation).
 
 #### Returns
 - `void`: This function does not return a value, but will throw an error if the assertion fails.

package/dist/class/base.d.ts

@@ -1,9 +1,11 @@
-import { RGXConvertibleTokenOutput, ValidRegexString } from "../types";
+import { RGXToken, ValidRegexString } from "../types";
 import { RGXTokenCollectionInput } from "../collection";
 import type { RGXClassUnionToken } from "./union";
 export declare abstract class RGXClassToken {
-    abstract toRgx(): RGXConvertibleTokenOutput;
+    abstract toRgx(): RGXToken;
     get isGroup(): boolean;
     or(...others: RGXTokenCollectionInput[]): RGXClassUnionToken;
     resolve(): ValidRegexString;
 }
+export declare const isRgxClassToken: (value: unknown) => value is RGXClassToken;
+export declare const assertRgxClassToken: (value: unknown) => asserts value is RGXClassToken;

package/dist/class/base.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RGXClassToken = void 0;
+exports.assertRgxClassToken = exports.isRgxClassToken = exports.RGXClassToken = void 0;
 const errors_1 = require("../errors");
 const resolve_1 = require("../resolve");
 class RGXClassToken {
@@ -15,3 +15,13 @@ class RGXClassToken {
     }
 }
 exports.RGXClassToken = RGXClassToken;
+// The createClassGuard function only accepts non-abstract classes, so we 
+// manually define the guard and assertion functions for RGXClassToken here.
+const isRgxClassToken = (value) => value instanceof RGXClassToken;
+exports.isRgxClassToken = isRgxClassToken;
+const assertRgxClassToken = (value) => {
+    if (!(value instanceof RGXClassToken)) {
+        throw new errors_1.RGXInvalidTokenError("Invalid token type", { type: "custom", values: ["instance of RGXClassToken"] }, value);
+    }
+};
+exports.assertRgxClassToken = assertRgxClassToken;

package/dist/class/union.d.ts

@@ -14,3 +14,5 @@ export declare class RGXClassUnionToken extends RGXClassToken {
 export declare function expandRgxUnionTokens(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection;
 export declare function removeRgxUnionDuplicates(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection;
 export declare const rgxClassUnion: (tokens?: RGXTokenCollectionInput) => RGXClassUnionToken;
+export declare const isRgxClassUnionToken: (value: unknown) => value is RGXClassUnionToken;
+export declare const assertRgxClassUnionToken: (value: unknown) => asserts value is RGXClassUnionToken;

package/dist/class/union.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.rgxClassUnion = exports.RGXClassUnionToken = void 0;
+exports.assertRgxClassUnionToken = exports.isRgxClassUnionToken = exports.rgxClassUnion = exports.RGXClassUnionToken = void 0;
 exports.expandRgxUnionTokens = expandRgxUnionTokens;
 exports.removeRgxUnionDuplicates = removeRgxUnionDuplicates;
 const internal_1 = require("../internal");
@@ -87,3 +87,5 @@ function removeRgxUnionDuplicates(...tokens) {
     return new collection_1.RGXTokenCollection(uniqueTokens, 'union');
 }
 exports.rgxClassUnion = (0, internal_1.createConstructFunction)(RGXClassUnionToken);
+exports.isRgxClassUnionToken = (0, internal_1.createClassGuardFunction)(RGXClassUnionToken);
+exports.assertRgxClassUnionToken = (0, internal_1.createAssertClassGuardFunction)(RGXClassUnionToken);

package/dist/errors/invalidToken.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RGXInvalidTokenError = void 0;
 const errors_1 = require("./");
 const js_utils_1 = require("@ptolemy2002/js-utils");
+const class_1 = require("../class");
 const tokenExpectationMap = {
     'no-op': ['null', 'undefined'],
     'literal': ['RegExp'],
@@ -44,7 +45,8 @@ class RGXInvalidTokenError extends errors_1.RGXError {
         this.setExpected(expected);
     }
     toString() {
-        return `${this.name}: ${this.message}; Expected: ${this.expected}; Got: ${JSON.stringify(this.got)}`;
+        const gotString = (0, class_1.isRgxClassToken)(this.got) ? `instance of ${this.got.constructor.name}` : JSON.stringify(this.got);
+        return `${this.name}: ${this.message}; Expected: ${this.expected}; Got: [${gotString}]`;
     }
 }
 exports.RGXInvalidTokenError = RGXInvalidTokenError;

package/dist/internal/createClassGuardFunction.d.ts

@@ -0,0 +1,2 @@
+export declare function createClassGuardFunction<T extends new (...args: unknown[]) => unknown>(constructor: T): (value: unknown) => value is InstanceType<T>;
+export declare function createAssertClassGuardFunction<T extends new (...args: unknown[]) => unknown>(constructor: T): (value: unknown) => asserts value is InstanceType<T>;

package/dist/internal/createClassGuardFunction.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClassGuardFunction = createClassGuardFunction;
+exports.createAssertClassGuardFunction = createAssertClassGuardFunction;
+const errors_1 = require("../errors");
+function createClassGuardFunction(constructor) {
+    return (value) => value instanceof constructor;
+}
+function createAssertClassGuardFunction(constructor) {
+    return (value) => {
+        if (!(value instanceof constructor)) {
+            throw new errors_1.RGXInvalidTokenError("Invalid token type", { type: "custom", values: [`instance of ${constructor.name}`] }, value);
+        }
+    };
+}

package/dist/internal/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./createConstructFunction";
+export * from "./createClassGuardFunction";
 export * from "./taggedTemplateToArray";

package/dist/internal/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./createConstructFunction"), exports);
+__exportStar(require("./createClassGuardFunction"), exports);
 __exportStar(require("./taggedTemplateToArray"), exports);

package/dist/resolve.js

@@ -56,7 +56,7 @@ function resolveRGXToken(token, groupWrap = true) {
         return resolveRGXToken(token.toRgx(), groupWrap);
     }
     // Interpret arrays as unions
-    if (Array.isArray(token)) {
+    if (tg.isRGXArrayToken(token, false)) {
         if (token.length === 0)
             return '';
         if (token.length > 1) {

package/dist/typeGuards.d.ts

@@ -5,10 +5,10 @@ export declare function isRGXLiteralToken(value: unknown): value is t.RGXLiteral
 export declare function assertRGXLiteralToken(value: unknown): asserts value is t.RGXLiteralToken;
 export declare function isRGXNativeToken(value: unknown): value is t.RGXNativeToken;
 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 isRGXArrayToken(value: unknown): value is t.RGXToken[];
-export declare function assertRGXArrayToken(value: unknown): asserts value is t.RGXToken[];
+export declare function isRGXConvertibleToken(value: unknown, returnCheck?: boolean): value is t.RGXConvertibleToken;
+export declare function assertRGXConvertibleToken(value: unknown, returnCheck?: boolean): asserts value is t.RGXConvertibleToken;
+export declare function isRGXArrayToken(value: unknown, contentCheck?: boolean): value is t.RGXToken[];
+export declare function assertRGXArrayToken(value: unknown, contentCheck?: boolean): asserts value is t.RGXToken[];
 export declare function rgxTokenTypeFlat(value: unknown): t.RGXTokenTypeFlat;
 export declare function rgxTokenType(value: unknown): t.RGXTokenType;
 export declare function rgxTokenFromType<T extends t.RGXTokenTypeGuardInput>(type: T, value: t.RGXToken): t.RGXTokenFromType<T>;

package/dist/typeGuards.js

@@ -83,31 +83,32 @@ function assertRGXNativeToken(value) {
         throw new e.RGXInvalidTokenError("Invalid native token", { type: "tokenType", values: ['native'] }, value);
     }
 }
-function isRGXConvertibleToken(value) {
+function isRGXConvertibleToken(value, returnCheck = true) {
     if (typeof value === 'object' && value !== null && 'toRgx' in value) {
         if ((0, is_callable_1.default)(value.toRgx)) {
-            const returnValue = value.toRgx();
-            if (Array.isArray(returnValue)) {
-                return returnValue.every(value => isRGXNativeToken(value) || isRGXLiteralToken(value));
-            }
-            return isRGXNativeToken(returnValue) || isRGXLiteralToken(returnValue);
+            if (!returnCheck)
+                return true;
+            const rv = value.toRgx();
+            return isRGXNativeToken(rv) || isRGXLiteralToken(rv) ||
+                isRGXNoOpToken(rv) || isRGXArrayToken(rv) ||
+                isRGXConvertibleToken(rv);
         }
         return false;
     }
     return false;
 }
-function assertRGXConvertibleToken(value) {
-    if (!isRGXConvertibleToken(value)) {
+function assertRGXConvertibleToken(value, returnCheck = true) {
+    if (!isRGXConvertibleToken(value, returnCheck)) {
         throw new e.RGXInvalidTokenError(`Invalid convertible token`, { type: "tokenType", values: ['convertible'] }, value);
     }
 }
-function isRGXArrayToken(value) {
-    return Array.isArray(value) && value.every(item => isRGXNoOpToken(item) || isRGXLiteralToken(item) ||
+function isRGXArrayToken(value, contentCheck = true) {
+    return Array.isArray(value) && (!contentCheck || value.every(item => isRGXNoOpToken(item) || isRGXLiteralToken(item) ||
         isRGXNativeToken(item) ||
-        isRGXConvertibleToken(item) || isRGXArrayToken(item));
+        isRGXConvertibleToken(item) || isRGXArrayToken(item)));
 }
-function assertRGXArrayToken(value) {
-    if (!isRGXArrayToken(value)) {
+function assertRGXArrayToken(value, contentCheck = true) {
+    if (!isRGXArrayToken(value, contentCheck)) {
         throw new e.RGXInvalidTokenError("Invalid array token", { type: "tokenType", values: ['array'] }, value);
     }
 }

package/dist/types.d.ts

@@ -1,11 +1,9 @@
 import { Branded } from "@ptolemy2002/ts-brand-utils";
-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: () => RGXConvertibleTokenOutput;
+    toRgx: () => RGXToken;
 };
 export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];

package/package.json

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