@ptolemy2002/rgx 2.5.1 → 2.6.0

package/README.md

@@ -23,7 +23,8 @@ type ValidVanillaRegexFlags = Branded<string, [ValidVanillaRegexFlagsBrandSymbol
 
 type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];
 type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
-type RGXTokenFromType<T extends RGXTokenType | RGXTokenTypeFlat> =
+type RGXTokenTypeGuardInput = Exclude<RGXTokenType, RGXTokenType[]> | RGXTokenTypeFlat | null | RGXTokenTypeGuardInput[];
+type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // ... see source for full definition
 ;
 
@@ -112,7 +113,7 @@ constructor(functionality: string, message?: string | null)
 - `functionality` (`string`): The description of the unimplemented functionality.
 
 #### Methods
-- `toString()` (`() => string`): Returns a formatted string indicating the unimplemented functionality and any additional message.
+- `toString() => string`: Returns a formatted string indicating the unimplemented functionality and any additional message.
 
 ### RGXTokenCollection
 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.
@@ -129,11 +130,12 @@ constructor(tokens: RGXTokenCollectionInput = [], mode: RGXTokenCollectionMode =
 #### 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()` (`() => 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.
-- `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.
+- `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.
+- `toArray() => RGXToken[]`: An alias for `getTokens()`, provided for convenience.
+- `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[]`).
 
@@ -141,14 +143,14 @@ Standard array properties and methods like `length`, `push`, `pop`, etc. are imp
 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.
+- `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`.
+- `or(...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.
@@ -166,10 +168,10 @@ constructor(tokens: RGXTokenCollectionInput = [])
 - `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`.
+- `add(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[]) => 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:
@@ -339,6 +341,64 @@ Does nothing at runtime, but performs a type assertion to the correct subset of
 #### Returns
 - `RGXTokenFromType<T>`: The input value, but with its type asserted to the corresponding token type based on the provided `RGXTokenType`.
 
+### rgxTokenTypeToFlat
+```typescript
+function rgxTokenTypeToFlat(type: RGXTokenType): RGXTokenTypeFlat
+```
+
+Converts an `RGXTokenType` to its flat equivalent `RGXTokenTypeFlat`. If the type is an array, it returns `'array'`; otherwise, it returns the type as-is.
+
+#### Parameters
+  - `type` (`RGXTokenType`): The RGX token type to convert.
+
+#### Returns
+- `RGXTokenTypeFlat`: The flat equivalent of the provided token type.
+
+### rgxTokenTypeGuardInputToFlat
+```typescript
+function rgxTokenTypeGuardInputToFlat(type: RGXTokenTypeGuardInput): RGXTokenTypeFlat | null
+```
+
+Converts an `RGXTokenTypeGuardInput` to its flat equivalent. If the type is `null`, it returns `null`; if it is an array, it returns `'array'`; otherwise, it returns the type as-is.
+
+#### Parameters
+  - `type` (`RGXTokenTypeGuardInput`): The type guard input to convert.
+
+#### Returns
+- `RGXTokenTypeFlat | null`: The flat equivalent of the provided type guard input, or `null` if the input is `null`.
+
+### isRGXToken
+```typescript
+function isRGXToken<T extends RGXTokenTypeGuardInput = null>(value: unknown, type?: T, matchLength?: boolean): value is RGXTokenFromType<T>
+```
+
+Checks if the given value is a valid RGX token, optionally narrowed to a specific token type. When `type` is `null` (the default), it checks against all token types. When `type` is a specific token type string, it checks only against that type.
+
+When `type` is an array, it checks that every element of the value array is a valid RGX token matching the corresponding type in the `type` array. If `matchLength` is `true` (the default), it also requires that the value array has the same length as the type array; if `false`, it allows the value array to be longer than the type array, as long as all elements up to the length of the type array match and all elements after that are still valid RGX tokens of any type.
+
+#### Parameters
+  - `value` (`unknown`): The value to check.
+  - `type` (`T`, optional): The token type to check against. Defaults to `null`, which checks against all token types.
+  - `matchLength` (`boolean`, optional): When `type` is an array, whether to require that the value array has the same length as the type array. Defaults to `true`.
+
+#### Returns
+- `boolean`: `true` if the value is a valid RGX token matching the specified type, otherwise `false`.
+
+### assertRGXToken
+```typescript
+function assertRGXToken<T extends RGXTokenTypeGuardInput = null>(value: unknown, type?: T, matchLength?: boolean): asserts value is RGXTokenFromType<T>
+```
+
+Asserts that the given value is a valid RGX token, optionally narrowed to a specific token type. Uses the same logic as `isRGXToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Parameters
+  - `value` (`unknown`): The value to assert.
+  - `type` (`T`, optional): The token type to assert against. Defaults to `null`, which checks against all token types.
+  - `matchLength` (`boolean`, optional): When `type` is an array, whether to require that the value array has the same length as the type array. Defaults to `true`.
+
+#### Returns
+- `void`: This function does not return a value, but will throw an error if the assertion fails.
+
 ### isValidRegexString
 ```typescript
 function isValidRegexString(value: string): value is ValidRegexString
@@ -432,7 +492,7 @@ A helper function that resolves an array of RGX tokens and concatenates their re
 
 ### rgx
 ```typescript
-function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: RGXToken[]) =>RegExp
+function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: RGXToken[]) => RegExp
 ```
 
 Creates and returns a template tag function that constructs a `RegExp` object from the provided template literal with the provided flags. The template literal can contain RGX tokens, which will be resolved and concatenated with the literal parts to form the final regex pattern.

package/dist/errors/invalidToken.js

@@ -7,8 +7,8 @@ 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'],
+    'convertible': ['object with a toRgx method that returns a valid native/literal token or an array of valid native/literal tokens'],
+    'array': ['array of native/literal/convertible tokens'],
 };
 class RGXInvalidTokenError extends errors_1.RGXError {
     setExpected(expected) {

package/dist/typeGuards.d.ts

@@ -10,6 +10,10 @@ export declare function assertRGXConvertibleToken(value: unknown): asserts value
 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 | t.RGXTokenTypeFlat>(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;
+export declare function isRGXToken<T extends t.RGXTokenTypeGuardInput = null>(value: unknown, type?: T, matchLength?: boolean): value is t.RGXTokenFromType<T>;
+export declare function assertRGXToken<T extends t.RGXTokenTypeGuardInput = null>(value: unknown, type?: T, matchLength?: boolean): asserts value is 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

@@ -47,6 +47,10 @@ exports.assertRGXConvertibleToken = assertRGXConvertibleToken;
 exports.rgxTokenTypeFlat = rgxTokenTypeFlat;
 exports.rgxTokenType = rgxTokenType;
 exports.rgxTokenFromType = rgxTokenFromType;
+exports.rgxTokenTypeToFlat = rgxTokenTypeToFlat;
+exports.rgxTokenTypeGuardInputToFlat = rgxTokenTypeGuardInputToFlat;
+exports.isRGXToken = isRGXToken;
+exports.assertRGXToken = assertRGXToken;
 exports.isValidRegexString = isValidRegexString;
 exports.assertValidRegexString = assertValidRegexString;
 exports.isValidVanillaRegexFlags = isValidVanillaRegexFlags;
@@ -125,6 +129,47 @@ function rgxTokenFromType(type, value) {
     /* istanbul ignore next */
     return value;
 }
+function rgxTokenTypeToFlat(type) {
+    return Array.isArray(type) ? 'array' : type;
+}
+function rgxTokenTypeGuardInputToFlat(type) {
+    if (type === null)
+        return null;
+    if (Array.isArray(type))
+        return 'array';
+    return type;
+}
+function isRGXToken(value, type = null, matchLength = true) {
+    function typeMatches(s) {
+        return type === null || type === s;
+    }
+    if (typeMatches('no-op') && isRGXNoOpToken(value))
+        return true;
+    if (typeMatches('literal') && isRGXLiteralToken(value))
+        return true;
+    if (typeMatches('native') && isRGXNativeToken(value))
+        return true;
+    if (typeMatches('convertible') && isRGXConvertibleToken(value))
+        return true;
+    if (typeMatches('array') && Array.isArray(value)) {
+        // @ts-ignore Excessively deep type is not a problem here.
+        return value.every(item => isRGXToken(item, null));
+    }
+    if (Array.isArray(type) && Array.isArray(value) && (!matchLength || type.length === value.length)) {
+        // This will always be false.
+        if (value.length < type.length)
+            return false;
+        // @ts-ignore Excessively deep type is not a problem here.
+        return value.every((item, i) => isRGXToken(item, type[i] ?? null));
+    }
+    return false;
+}
+function assertRGXToken(value, type = null, matchLength = true) {
+    if (!isRGXToken(value, type, matchLength)) {
+        const flatType = rgxTokenTypeGuardInputToFlat(type);
+        throw new e.RGXInvalidTokenError("Invalid RGX token", flatType === null ? null : { type: "tokenType", values: [flatType] }, value);
+    }
+}
 function isValidRegexString(value) {
     try {
         new RegExp(value);

package/dist/types.d.ts

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

package/package.json

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