@ptolemy2002/rgx 2.7.0 → 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,59 +254,63 @@ 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.
 
 ### rgxTokenType
 ```typescript
-function rgxTokenType(value: RGXToken): RGXTokenType
+function rgxTokenType(value: unknown): RGXTokenType
 ```
 
-Determines the type of a given RGX token (`no-op`, `literal`, `native`, `convertible`, or an array of the former).
+Determines the type of a given RGX token value (`no-op`, `literal`, `native`, `convertible`, or an array of the former) or throws an error if the value is not a valid RGX token.
 
 If you narrow the result of this function to something more specific, you can then convert these string or array literals into their corresponding token types using the `RGXTokenFromType` utility type or `rgxTokenFromType` function.
 
@@ -323,16 +325,16 @@ if (type === 'native') {
 ```
 
 #### Parameters
-  - `value` (`RGXToken`): The RGX token to check.
+  - `value` (`unknown`): The value to check.
 
 #### Returns
 - `RGXTokenType`: The type of the RGX token.
 
 ### rgxTokenTypeFlat
 ```typescript
-function rgxTokenTypeFlat(value: RGXToken): RGXTokenTypeFlat
+function rgxTokenTypeFlat(value: unknown): 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.
+Determines the flat type of a given RGX token value (`no-op`, `literal`, `native`, `convertible`, or `array`) or throws an error if the value is not a valid RGX token. 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.
 
@@ -346,7 +348,7 @@ if (type === 'array') {
 ```
 
 #### Parameters
-  - `value` (`RGXToken`): The RGX token to check.
+  - `value` (`unknown`): The value to check.
 
 #### Returns
 - `RGXTokenTypeFlat`: The flat type of the RGX token.

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,12 +5,12 @@ 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 rgxTokenTypeFlat(value: t.RGXToken): t.RGXTokenTypeFlat;
-export declare function rgxTokenType(value: t.RGXToken): t.RGXTokenType;
+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>;
 export declare function rgxTokenTypeToFlat(type: t.RGXTokenType): t.RGXTokenTypeFlat;
 export declare function rgxTokenTypeGuardInputToFlat(type: t.RGXTokenTypeGuardInput): t.RGXTokenTypeFlat | null;

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);
     }
 }
@@ -120,21 +121,16 @@ function rgxTokenTypeFlat(value) {
         return 'native';
     if (isRGXConvertibleToken(value))
         return 'convertible';
-    if (Array.isArray(value))
+    if (isRGXArrayToken(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')
+    else
         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", 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.

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