@ptolemy2002/rgx 2.5.2 → 2.7.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 = RGXTokenTypeFlat | null | RGXTokenTypeGuardInput[];
+type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // ... see source for full definition
 ;
 
@@ -278,6 +279,30 @@ Asserts that the given value is a convertible token (an object with a `toRgx` me
 #### 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[]
+```
+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).
+
+#### Parameters
+  - `value` (`unknown`): The value to check.
+
+#### Returns
+- `boolean`: `true` if the value is an array of RGX tokens, otherwise `false`.
+
+### assertRGXArrayToken
+```typescript
+function assertRGXArrayToken(value: unknown): 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.
+
+#### Parameters
+  - `value` (`unknown`): The value to assert.
+
+#### 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
@@ -328,7 +353,7 @@ if (type === 'array') {
 
 ### rgxTokenFromType
 ```typescript
-function rgxTokenFromType<T extends RGXTokenType | RGXTokenTypeFlat>(type: T, value: RGXToken): RGXTokenFromType<T>
+function rgxTokenFromType<T extends RGXTokenTypeGuardInput>(type: T, value: RGXToken): RGXTokenFromType<T>
 ```
 
 Does nothing at runtime, but performs a type assertion to the correct subset of `RGXToken` based on the provided `RGXTokenType`.
@@ -340,6 +365,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

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/index.js

@@ -41,6 +41,7 @@ exports.default = rgx;
 const tg = __importStar(require("./typeGuards"));
 const class_1 = require("./class");
 const concat_1 = require("./concat");
+const internal_1 = require("./internal");
 __exportStar(require("./errors"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./typeGuards"), exports);
@@ -50,16 +51,6 @@ __exportStar(require("./resolve"), exports);
 __exportStar(require("./concat"), exports);
 // Call this for certain class methods to work correctly
 (0, class_1.rgxClassInit)();
-function taggedTemplateToTokenArray(strings, tokens) {
-    const tokenArray = [];
-    for (let i = 0; i < strings.length; i++) {
-        if (strings[i])
-            tokenArray.push(strings[i]);
-        if (i < tokens.length)
-            tokenArray.push(tokens[i]);
-    }
-    return tokenArray;
-}
 function rgxa(tokens, flags = '') {
     tg.assertValidVanillaRegexFlags(flags);
     const pattern = (0, concat_1.rgxConcat)(tokens);
@@ -68,6 +59,6 @@ function rgxa(tokens, flags = '') {
 function rgx(flags = '') {
     tg.assertValidVanillaRegexFlags(flags);
     return (strings, ...tokens) => {
-        return rgxa(taggedTemplateToTokenArray(strings, tokens), flags);
+        return rgxa((0, internal_1.taggedTemplateToArray)(strings, tokens), flags);
     };
 }

package/dist/internal/index.d.ts

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

package/dist/internal/index.js

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

package/dist/internal/taggedTemplateToArray.d.ts

@@ -0,0 +1 @@
+export declare function taggedTemplateToArray<T>(strings: TemplateStringsArray, tokens: T[]): (string | T)[];

package/dist/internal/taggedTemplateToArray.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taggedTemplateToArray = taggedTemplateToArray;
+function taggedTemplateToArray(strings, tokens) {
+    function isNullOrUndefined(value) {
+        return value === null || value === undefined;
+    }
+    const array = [];
+    for (let i = 0; i < Math.max(strings.length, tokens.length); i++) {
+        const string = strings[i];
+        const token = tokens[i];
+        // Strings always come before tokens
+        if (!isNullOrUndefined(string))
+            array.push(string);
+        if (!isNullOrUndefined(token))
+            array.push(token);
+    }
+    return array;
+}

package/dist/typeGuards.d.ts

@@ -7,9 +7,15 @@ export declare function isRGXNativeToken(value: unknown): value is t.RGXNativeTo
 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 rgxTokenFromType<T extends t.RGXTokenType | t.RGXTokenTypeFlat>(type: T, value: t.RGXToken): t.RGXTokenFromType<T>;
+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;
+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

@@ -44,9 +44,15 @@ exports.isRGXNativeToken = isRGXNativeToken;
 exports.assertRGXNativeToken = assertRGXNativeToken;
 exports.isRGXConvertibleToken = isRGXConvertibleToken;
 exports.assertRGXConvertibleToken = assertRGXConvertibleToken;
+exports.isRGXArrayToken = isRGXArrayToken;
+exports.assertRGXArrayToken = assertRGXArrayToken;
 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;
@@ -95,6 +101,16 @@ function assertRGXConvertibleToken(value) {
         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) ||
+        isRGXNativeToken(item) ||
+        isRGXConvertibleToken(item) || isRGXArrayToken(item));
+}
+function assertRGXArrayToken(value) {
+    if (!isRGXArrayToken(value)) {
+        throw new e.RGXInvalidTokenError("Invalid array token", { type: "tokenType", values: ['array'] }, value);
+    }
+}
 function rgxTokenTypeFlat(value) {
     if (isRGXNoOpToken(value))
         return 'no-op';
@@ -125,6 +141,45 @@ 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') && isRGXArrayToken(value))
+        return true;
+    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 = 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.2",
+    "version": "2.7.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",