@ptolemy2002/rgx 2.8.0 → 3.0.0

package/README.md

@@ -19,7 +19,7 @@ const validVanillaRegexFlagsSymbol = Symbol('rgx.ValidVanillaRegexFlags');
 type ValidVanillaRegexFlagsBrandSymbol = typeof validVanillaRegexFlagsSymbol;
 type ValidVanillaRegexFlags = Branded<string, [ValidVanillaRegexFlagsBrandSymbol]>;
 
-type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];
+type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | RGXTokenType[];
 type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
 type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXTokenTypeGuardInput[];
 type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
@@ -140,6 +140,8 @@ Standard array properties and methods like `length`, `push`, `pop`, etc. are imp
 ### RGXClassToken (abstract)
 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() => 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).
 
@@ -153,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
@@ -307,10 +309,12 @@ Asserts that the given value is an array of RGX tokens. When `contentCheck` is `
 
 ### rgxTokenType
 ```typescript
-function rgxTokenType(value: unknown): RGXTokenType
+function rgxTokenType(value: unknown, recognizeClass?: boolean): RGXTokenType
 ```
 
-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.
+Determines the type of a given RGX token value (`no-op`, `literal`, `native`, `convertible`, `class`, or an array of the former) or throws an error if the value is not a valid RGX token.
+
+When `recognizeClass` is `true` (the default), `RGXClassToken` instances are identified as `'class'` rather than `'convertible'`. When `recognizeClass` is `false`, class tokens are identified as `'convertible'` instead. The `recognizeClass` preference is passed through to recursive calls for array elements.
 
 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.
 
@@ -326,15 +330,18 @@ if (type === 'native') {
 
 #### Parameters
   - `value` (`unknown`): The value to check.
+  - `recognizeClass` (`boolean`, optional): Whether to recognize `RGXClassToken` instances as `'class'` instead of `'convertible'`. Defaults to `true`.
 
 #### Returns
 - `RGXTokenType`: The type of the RGX token.
 
 ### rgxTokenTypeFlat
 ```typescript
-function rgxTokenTypeFlat(value: unknown): RGXTokenTypeFlat
+function rgxTokenTypeFlat(value: unknown, recognizeClass?: boolean): RGXTokenTypeFlat
 ```
-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.
+Determines the flat type of a given RGX token value (`no-op`, `literal`, `native`, `convertible`, `class`, 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.
+
+When `recognizeClass` is `true` (the default), `RGXClassToken` instances are identified as `'class'` rather than `'convertible'`. This distinction is important because class tokens are also convertible tokens, but the `'class'` type is more specific. When `recognizeClass` is `false`, class tokens are identified as `'convertible'` instead.
 
 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.
 
@@ -349,6 +356,7 @@ if (type === 'array') {
 
 #### Parameters
   - `value` (`unknown`): The value to check.
+  - `recognizeClass` (`boolean`, optional): Whether to recognize `RGXClassToken` instances as `'class'` instead of `'convertible'`. Defaults to `true`.
 
 #### Returns
 - `RGXTokenTypeFlat`: The flat type of the RGX token.
@@ -398,7 +406,7 @@ Converts an `RGXTokenTypeGuardInput` to its flat equivalent. If the type is `nul
 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.
+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. The `'class'` type matches `RGXClassToken` instances specifically, while `'convertible'` also matches class tokens since they implement the convertible interface.
 
 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.
 
@@ -415,7 +423,7 @@ When `type` is an array, it checks that every element of the value array is a va
 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.
+Asserts that the given value is a valid RGX token, optionally narrowed to a specific token type (including `'class'` for `RGXClassToken` instances). Uses the same logic as `isRGXToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
 
 #### Parameters
   - `value` (`unknown`): The value to assert.

package/dist/class/base.d.ts

@@ -7,3 +7,5 @@ export declare abstract class RGXClassToken {
     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,12 +3,14 @@ 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'],
     'native': ['string', 'number', 'boolean', 'null', 'undefined'],
     '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': ['instance of RGXClassToken']
 };
 class RGXInvalidTokenError extends errors_1.RGXError {
     setExpected(expected) {
@@ -44,7 +46,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/typeGuards.d.ts

@@ -9,8 +9,8 @@ export declare function isRGXConvertibleToken(value: unknown, returnCheck?: bool
 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 rgxTokenTypeFlat(value: unknown, recognizeClass?: boolean): t.RGXTokenTypeFlat;
+export declare function rgxTokenType(value: unknown, recognizeClass?: boolean): 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

@@ -58,6 +58,7 @@ exports.assertValidRegexString = assertValidRegexString;
 exports.isValidVanillaRegexFlags = isValidVanillaRegexFlags;
 exports.assertValidVanillaRegexFlags = assertValidVanillaRegexFlags;
 const e = __importStar(require("./errors"));
+const class_1 = require("./class");
 const is_callable_1 = __importDefault(require("is-callable"));
 function isRGXNoOpToken(value) {
     return value === null || value === undefined;
@@ -112,25 +113,28 @@ function assertRGXArrayToken(value, contentCheck = true) {
         throw new e.RGXInvalidTokenError("Invalid array token", { type: "tokenType", values: ['array'] }, value);
     }
 }
-function rgxTokenTypeFlat(value) {
+function rgxTokenTypeFlat(value, recognizeClass = true) {
     if (isRGXNoOpToken(value))
         return 'no-op';
     if (isRGXLiteralToken(value))
         return 'literal';
     if (isRGXNativeToken(value))
         return 'native';
+    // We have to check class before convertible because class tokens are also convertible.
+    if (recognizeClass && (0, class_1.isRgxClassToken)(value))
+        return 'class';
     if (isRGXConvertibleToken(value))
         return 'convertible';
     if (isRGXArrayToken(value))
         return 'array';
     throw new e.RGXInvalidTokenError("Invalid RGX token", null, value);
 }
-function rgxTokenType(value) {
-    const flatType = rgxTokenTypeFlat(value);
+function rgxTokenType(value, recognizeClass = true) {
+    const flatType = rgxTokenTypeFlat(value, recognizeClass);
     if (flatType !== 'array')
         return flatType;
     else
-        return value.map(rgxTokenType);
+        return value.map(item => rgxTokenType(item, recognizeClass));
 }
 function rgxTokenFromType(type, value) {
     // Ignoring this line because the function is entirely a TypeScript utility that doesn't need to be tested at runtime.
@@ -157,6 +161,9 @@ function isRGXToken(value, type = null, matchLength = true) {
         return true;
     if (typeMatches('native') && isRGXNativeToken(value))
         return true;
+    // We have to check class before convertible because class tokens are also convertible.
+    if (typeMatches('class') && (0, class_1.isRgxClassToken)(value))
+        return true;
     if (typeMatches('convertible') && isRGXConvertibleToken(value))
         return true;
     if (typeMatches('array') && isRGXArrayToken(value))

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import { Branded } from "@ptolemy2002/ts-brand-utils";
+import type { RGXClassToken } from "./class";
 export type RGXNoOpToken = null | undefined;
 export type RGXLiteralToken = RegExp;
 export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
@@ -6,10 +7,10 @@ export type RGXConvertibleToken = {
     toRgx: () => RGXToken;
 };
 export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
-export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];
+export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | RGXTokenType[];
 export type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
 export type RGXTokenTypeGuardInput = 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[] ? {
+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 'class' ? RGXClassToken : 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;

package/package.json

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