@ptolemy2002/rgx 2.7.1 → 2.8.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,10 @@ 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).
 
 #### 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.
@@ -256,49 +254,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,8 +1,8 @@
-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;

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.8.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",