@ptolemy2002/rgx 2.0.2 → 2.2.0

package/README.md

@@ -21,11 +21,19 @@ type ValidVanillaRegexFlagsBrandSymbol = typeof validVanillaRegexFlagsSymbol;
 type ValidVanillaRegexFlags = Branded<string, [ValidVanillaRegexFlagsBrandSymbol]>;
 
 type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];
+type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
 type RGXTokenFromType<T extends RGXTokenType> =
     // ... see source for full definition
 ;
 
 type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS';
+type ExpectedTokenType = {
+    type: "tokenType";
+    values: RGXTokenTypeFlat[];
+} | {
+    type: "custom";
+    values: string[];
+};
 ```
 
 ## Classes
@@ -42,18 +50,18 @@ constructor(message: string, code?: RGXErrorCode)
 - `code` (`RGXErrorCode`, optional): An optional error code that can be used to categorize the error. If not provided, it defaults to 'UNKNOWN'.
 
 ### RGXInvalidTokenError extends RGXError
-A specific error class for invalid RGX tokens. This error is thrown when a value fails validation as a specific RGX token type.
+A specific error class for invalid RGX tokens. This error is thrown when a value fails validation as a specific RGX token type. The error code is set to `INVALID_RGX_TOKEN` on instantiation.
 
 #### Constructor
 ```typescript
 constructor(message: string, expected: string | null, got: unknown)
 ```
 - `message` (`string`): The error message.
-- `expected` (`string` | `null`): A description of the expected token type. If `null`, will use a default message indicating the expected types of any RGX token.
+- `expected` (`ExpectedTokenType | null`): Either an object describing the expected token type(s) or `null` if all token types are expected. This is used to generate a human-readable description of what was expected.
 - `got` (`unknown`): The actual value that was received, which failed validation.
 
 ### RGXInvalidRegexStringError extends RGXError
-A specific error class for invalid regex strings. This error is thrown when a string fails validation as a valid regex string.
+A specific error class for invalid regex strings. This error is thrown when a string fails validation as a valid regex string. The error code is set to `INVALID_REGEX_STRING` on instantiation.
 
 #### Constructor
 ```typescript
@@ -63,7 +71,7 @@ constructor(message: string, got: string)
 - `got` (`string`): The actual string that was received, which failed validation.
 
 ### RGXInvalidVanillaRegexFlagsError extends RGXError
-A specific error class for invalid vanilla regex flags. This error is thrown when a string fails validation as valid vanilla regex flags.
+A specific error class for invalid vanilla regex flags. This error is thrown when a string fails validation as valid vanilla regex flags. The error code is set to `INVALID_VANILLA_REGEX_FLAGS` on instantiation.
 
 #### Constructor
 ```typescript
@@ -328,14 +336,27 @@ const pattern3 = rgx()`${beginning}value: ${[word, optionalDigit]}${end}`; // /^
 
 #### Parameters
 **Direct**
-  - `flags` (`string`, optional): The regex flags to apply to the resulting `RegExp` object (e.g., 'g', 'i', 'm', etc.). If not provided, no flags will be applied. If provided and not valid vanilla regex flags, an `RGXError` with code `INVALID_VANILLA_REGEX_FLAGS` will be thrown.
+  - `flags` (`string`, optional): The regex flags to apply to the resulting `RegExp` object (e.g., 'g', 'i', 'm', etc.). If not provided, no flags will be applied. If provided and not valid vanilla regex flags, an `RGXInvalidVanillaRegexFlagsError` will be thrown.
 
 **Template Tag**
   - `strings` (`TemplateStringsArray`): The literal parts of the template string.
   - `tokens` (`RGXToken[]`): The RGX tokens to be resolved and concatenated with the literal parts.
 
 #### Returns
-- `(strings: TemplateStringsArray, ...tokens: RGXToken[]) => RegExp`: A template tag function that takes a template literal and returns a `RegExp` object constructed from the resolved tokens and literal parts.
+- `(strings: TemplateStringsArray, ...tokens: RGXToken[]) => RegExp`: A template tag function that takes a template literal and returns a `RegExp` object constructed from the resolved tokens, literal parts, and the provided flags.
+
+### rgxa
+```typescript
+function rgxa(tokens: RGXToken[], flags?: string): RegExp
+```
+As an alternative to using the `rgx` template tag, you can directly call `rgxa` with an array of RGX tokens and optional flags to get a `RegExp` object. This is useful in cases where you don't want to use a template literal.
+
+#### Parameters
+  - `tokens` (`RGXToken[]`): The RGX tokens to be resolved and concatenated to form the regex pattern.
+  - `flags` (`string`, optional): The regex flags to apply to the resulting `RegExp` object (e.g., 'g', 'i', 'm', etc.). If not provided, no flags will be applied. If provided and not valid vanilla regex flags, an `RGXInvalidVanillaRegexFlagsError` will be thrown.
+
+#### Returns
+- `RegExp`: A `RegExp` object constructed from the resolved tokens and the provided flags.
 
 ## Peer Dependencies
 - `@ptolemy2002/ts-brand-utils` ^1.0.0

package/dist/errors/base.d.ts

@@ -0,0 +1,5 @@
+export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS';
+export declare class RGXError extends Error {
+    code: RGXErrorCode;
+    constructor(message: string, code?: RGXErrorCode);
+}

package/dist/errors/base.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXError = void 0;
+class RGXError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = 'UNKNOWN';
+        this.name = 'RGXError';
+        if (code) {
+            this.code = code;
+        }
+    }
+}
+exports.RGXError = RGXError;

package/dist/errors/index.d.ts

@@ -0,0 +1,4 @@
+export * from './base';
+export * from './invalidToken';
+export * from './invalidRegexString';
+export * from './invalidVanillaRegexFlags';

package/dist/errors/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base"), exports);
+__exportStar(require("./invalidToken"), exports);
+__exportStar(require("./invalidRegexString"), exports);
+__exportStar(require("./invalidVanillaRegexFlags"), exports);

package/dist/errors/invalidRegexString.d.ts

@@ -0,0 +1,6 @@
+import { RGXError } from "./";
+export declare class RGXInvalidRegexStringError extends RGXError {
+    got: string;
+    constructor(message: string, got: string);
+    toString(): string;
+}

package/dist/errors/invalidRegexString.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXInvalidRegexStringError = void 0;
+const errors_1 = require("./");
+class RGXInvalidRegexStringError extends errors_1.RGXError {
+    constructor(message, got) {
+        super(message, 'INVALID_REGEX_STRING');
+        this.name = 'RGXInvalidRegexStringError';
+        this.got = got;
+    }
+    toString() {
+        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    }
+}
+exports.RGXInvalidRegexStringError = RGXInvalidRegexStringError;

package/dist/errors/invalidToken.d.ts

@@ -0,0 +1,16 @@
+import { RGXError } from "./";
+import { RGXTokenTypeFlat } from "../types";
+export type ExpectedTokenType = {
+    type: "tokenType";
+    values: RGXTokenTypeFlat[];
+} | {
+    type: "custom";
+    values: string[];
+};
+export declare class RGXInvalidTokenError extends RGXError {
+    expected: string;
+    got: unknown;
+    setExpected(expected: ExpectedTokenType | null): string;
+    constructor(message: string, expected: ExpectedTokenType | null, got: unknown);
+    toString(): string;
+}

package/dist/errors/invalidToken.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXInvalidTokenError = void 0;
+const errors_1 = require("./");
+const js_utils_1 = require("@ptolemy2002/js-utils");
+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'],
+};
+class RGXInvalidTokenError extends errors_1.RGXError {
+    setExpected(expected) {
+        let result;
+        if (expected === null) {
+            // Add them all
+            const uniqueValues = new Set();
+            for (const tokenType in tokenExpectationMap) {
+                tokenExpectationMap[tokenType].forEach(e => uniqueValues.add(e));
+            }
+            result = (0, js_utils_1.listInPlainEnglish)(Array.from(uniqueValues), { conjunction: 'or' });
+        }
+        else if (expected.type === 'tokenType') {
+            const uniqueValues = new Set();
+            for (const tokenType of expected.values) {
+                const expectations = tokenExpectationMap[tokenType];
+                if (expectations) {
+                    expectations.forEach(e => uniqueValues.add(e));
+                }
+            }
+            result = (0, js_utils_1.listInPlainEnglish)(Array.from(uniqueValues), { conjunction: 'or' });
+        }
+        else {
+            result = (0, js_utils_1.listInPlainEnglish)(expected.values, { conjunction: 'or' });
+        }
+        this.expected = `[${result}]`;
+        return this.expected;
+    }
+    constructor(message, expected, got) {
+        super(message, 'INVALID_RGX_TOKEN');
+        this.name = 'RGXInvalidTokenError';
+        this.got = got;
+        this.setExpected(expected);
+    }
+    toString() {
+        return `${this.name}: ${this.message}; Expected: ${this.expected}; Got: ${JSON.stringify(this.got)}`;
+    }
+}
+exports.RGXInvalidTokenError = RGXInvalidTokenError;

package/dist/errors/invalidVanillaRegexFlags.d.ts

@@ -0,0 +1,6 @@
+import { RGXError } from "./";
+export declare class RGXInvalidVanillaRegexFlagsError extends RGXError {
+    got: string;
+    constructor(message: string, got: string);
+    toString(): string;
+}

package/dist/errors/invalidVanillaRegexFlags.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXInvalidVanillaRegexFlagsError = void 0;
+const errors_1 = require("./");
+class RGXInvalidVanillaRegexFlagsError extends errors_1.RGXError {
+    constructor(message, got) {
+        super(message, 'INVALID_VANILLA_REGEX_FLAGS');
+        this.name = 'RGXInvalidVanillaRegexFlagsError';
+        this.got = got;
+    }
+    toString() {
+        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
+    }
+}
+exports.RGXInvalidVanillaRegexFlagsError = RGXInvalidVanillaRegexFlagsError;

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import * as t from "./types";
 export * from "./errors";
 export * from "./types";
-export * from "./type-guards";
+export * from "./typeGuards";
 export declare function escapeRegex(value: string): t.ValidRegexString;
 export declare function resolveRGXToken(token: t.RGXToken): t.ValidRegexString;
 export declare function rgxConcat(tokens: t.RGXToken[]): t.ValidRegexString;
+export declare function rgxa(tokens: t.RGXToken[], flags?: string): RegExp;
 export default function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => RegExp;

package/dist/index.js

@@ -39,12 +39,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.escapeRegex = escapeRegex;
 exports.resolveRGXToken = resolveRGXToken;
 exports.rgxConcat = rgxConcat;
+exports.rgxa = rgxa;
 exports.default = rgx;
 const e = __importStar(require("./errors"));
-const tg = __importStar(require("./type-guards"));
+const tg = __importStar(require("./typeGuards"));
 __exportStar(require("./errors"), exports);
 __exportStar(require("./types"), exports);
-__exportStar(require("./type-guards"), exports);
+__exportStar(require("./typeGuards"), exports);
 function escapeRegex(value) {
     return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -75,17 +76,21 @@ function resolveRGXToken(token) {
 function rgxConcat(tokens) {
     return tokens.map(resolveRGXToken).join('');
 }
+function rgxa(tokens, flags = '') {
+    tg.assertValidVanillaRegexFlags(flags);
+    const pattern = rgxConcat(tokens);
+    return new RegExp(pattern, flags);
+}
 function rgx(flags = '') {
     tg.assertValidVanillaRegexFlags(flags);
     return (strings, ...tokens) => {
-        let pattern = '';
-        const resolvedTokens = tokens.map(resolveRGXToken);
+        const tokenArray = [];
         for (let i = 0; i < strings.length; i++) {
-            pattern += strings[i];
-            if (i < resolvedTokens.length) {
-                pattern += resolvedTokens[i];
-            }
+            if (strings[i])
+                tokenArray.push(strings[i]);
+            if (i < tokens.length)
+                tokenArray.push(tokens[i]);
         }
-        return new RegExp(pattern, flags);
+        return rgxa(tokenArray, flags);
     };
 }

package/dist/{type-guards.js → typeGuards.js}

@@ -57,7 +57,7 @@ function isRGXNoOpToken(value) {
 }
 function assertRGXNoOpToken(value) {
     if (!isRGXNoOpToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid no-op token`, 'null or undefined', value);
+        throw new e.RGXInvalidTokenError(`Invalid no-op token`, { type: "tokenType", values: ['no-op'] }, value);
     }
 }
 function isRGXLiteralToken(value) {
@@ -65,7 +65,7 @@ function isRGXLiteralToken(value) {
 }
 function assertRGXLiteralToken(value) {
     if (!isRGXLiteralToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid literal token`, 'RegExp', value);
+        throw new e.RGXInvalidTokenError("Invalid literal token", { type: "tokenType", values: ['literal'] }, value);
     }
 }
 function isRGXNativeToken(value) {
@@ -73,7 +73,7 @@ function isRGXNativeToken(value) {
 }
 function assertRGXNativeToken(value) {
     if (!isRGXNativeToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid native token`, 'string, number, boolean, null, or undefined', value);
+        throw new e.RGXInvalidTokenError("Invalid native token", { type: "tokenType", values: ['native'] }, value);
     }
 }
 function isRGXConvertibleToken(value) {
@@ -91,7 +91,7 @@ function isRGXConvertibleToken(value) {
 }
 function assertRGXConvertibleToken(value) {
     if (!isRGXConvertibleToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid convertible token`, 'object with a toRgx method that returns a valid token', value);
+        throw new e.RGXInvalidTokenError(`Invalid convertible token`, { type: "tokenType", values: ['convertible'] }, value);
     }
 }
 function rgxTokenType(value) {
@@ -107,7 +107,7 @@ function rgxTokenType(value) {
         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: ${value}`, null, value);
+    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.
@@ -125,7 +125,7 @@ function isValidRegexString(value) {
 }
 function assertValidRegexString(value) {
     if (!isValidRegexString(value)) {
-        throw new e.RGXInvalidRegexStringError(`Invalid regex string: ${value}`, value);
+        throw new e.RGXInvalidRegexStringError("Invalid regex string", value);
     }
 }
 function isValidVanillaRegexFlags(value) {
@@ -138,6 +138,6 @@ function isValidVanillaRegexFlags(value) {
 }
 function assertValidVanillaRegexFlags(value) {
     if (!isValidVanillaRegexFlags(value)) {
-        throw new e.RGXInvalidVanillaRegexFlagsError(`Invalid vanilla regex flags: ${value}`, value);
+        throw new e.RGXInvalidVanillaRegexFlagsError("Invalid vanilla regex flags", value);
     }
 }

package/dist/types.d.ts

@@ -8,6 +8,7 @@ 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> = T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? RGXLiteralToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends RGXTokenType[] ? {
     [K in keyof T]: T[K] extends RGXTokenType ? RGXTokenFromType<T[K]> : never;
 } : never;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/rgx",
-    "version": "2.0.2",
+    "version": "2.2.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -29,6 +29,7 @@
         "release-major": "bash ./scripts/release.sh major"
     },
     "devDependencies": {
+        "@ptolemy2002/js-utils": "^3.2.2",
         "@ptolemy2002/ts-brand-utils": "^1.0.0",
         "@ptolemy2002/ts-utils": "^3.4.0",
         "@types/is-callable": "^1.1.2",

package/dist/errors.d.ts

@@ -1,21 +0,0 @@
-export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS';
-export declare class RGXError extends Error {
-    code: RGXErrorCode;
-    constructor(message: string, code?: RGXErrorCode);
-}
-export declare class RGXInvalidTokenError extends RGXError {
-    expected: string;
-    got: unknown;
-    constructor(message: string, expected: string | null, got: unknown);
-    toString(): string;
-}
-export declare class RGXInvalidRegexStringError extends RGXError {
-    got: string;
-    constructor(message: string, got: string);
-    toString(): string;
-}
-export declare class RGXInvalidVanillaRegexFlagsError extends RGXError {
-    got: string;
-    constructor(message: string, got: string);
-    toString(): string;
-}

package/dist/errors.js

@@ -1,50 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RGXInvalidVanillaRegexFlagsError = exports.RGXInvalidRegexStringError = exports.RGXInvalidTokenError = exports.RGXError = void 0;
-class RGXError extends Error {
-    constructor(message, code) {
-        super(message);
-        this.code = 'UNKNOWN';
-        this.name = 'RGXError';
-        if (code) {
-            this.code = code;
-        }
-    }
-}
-exports.RGXError = RGXError;
-class RGXInvalidTokenError extends RGXError {
-    constructor(message, expected, got) {
-        super(message, 'INVALID_RGX_TOKEN');
-        this.expected = '[null, undefined, string, number, boolean, RegExp, convertible object, or array of native/literal tokens]';
-        this.name = 'RGXInvalidTokenError';
-        if (expected !== null)
-            this.expected = "[" + expected + "]";
-        this.got = got;
-    }
-    toString() {
-        return `${this.name}: ${this.message}; Expected: ${this.expected}; Got: ${JSON.stringify(this.got)}`;
-    }
-}
-exports.RGXInvalidTokenError = RGXInvalidTokenError;
-class RGXInvalidRegexStringError extends RGXError {
-    constructor(message, got) {
-        super(message, 'INVALID_REGEX_STRING');
-        this.name = 'RGXInvalidRegexStringError';
-        this.got = got;
-    }
-    toString() {
-        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
-    }
-}
-exports.RGXInvalidRegexStringError = RGXInvalidRegexStringError;
-class RGXInvalidVanillaRegexFlagsError extends RGXError {
-    constructor(message, got) {
-        super(message, 'INVALID_VANILLA_REGEX_FLAGS');
-        this.name = 'RGXInvalidVanillaRegexFlagsError';
-        this.got = got;
-    }
-    toString() {
-        return `${this.name}: ${this.message}; Got: ${JSON.stringify(this.got)}`;
-    }
-}
-exports.RGXInvalidVanillaRegexFlagsError = RGXInvalidVanillaRegexFlagsError;