@ptolemy2002/rgx 2.0.1 → 2.1.0

package/README.md

@@ -42,7 +42,7 @@ 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
@@ -53,7 +53,7 @@ constructor(message: string, expected: string | null, got: unknown)
 - `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 +63,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 +328,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/index.d.ts

@@ -1,21 +1,9 @@
 import * as t from "./types";
 export * from "./errors";
 export * from "./types";
-export declare function isRGXNoOpToken(value: unknown): value is t.RGXNoOpToken;
-export declare function assertRGXNoOpToken(value: unknown): asserts value is t.RGXNoOpToken;
-export declare function isRGXLiteralToken(value: unknown): value is t.RGXLiteralToken;
-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 rgxTokenType(value: t.RGXToken): t.RGXTokenType;
-export declare function rgxTokenFromType<T extends t.RGXTokenType>(type: T, value: t.RGXToken): 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;
-export declare function assertValidVanillaRegexFlags(value: string): asserts value is t.ValidVanillaRegexFlags;
+export * from "./type-guards";
 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

@@ -35,132 +35,28 @@ var __importStar = (this && this.__importStar) || (function () {
 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);
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isRGXNoOpToken = isRGXNoOpToken;
-exports.assertRGXNoOpToken = assertRGXNoOpToken;
-exports.isRGXLiteralToken = isRGXLiteralToken;
-exports.assertRGXLiteralToken = assertRGXLiteralToken;
-exports.isRGXNativeToken = isRGXNativeToken;
-exports.assertRGXNativeToken = assertRGXNativeToken;
-exports.isRGXConvertibleToken = isRGXConvertibleToken;
-exports.assertRGXConvertibleToken = assertRGXConvertibleToken;
-exports.rgxTokenType = rgxTokenType;
-exports.rgxTokenFromType = rgxTokenFromType;
-exports.isValidRegexString = isValidRegexString;
-exports.assertValidRegexString = assertValidRegexString;
-exports.isValidVanillaRegexFlags = isValidVanillaRegexFlags;
-exports.assertValidVanillaRegexFlags = assertValidVanillaRegexFlags;
 exports.escapeRegex = escapeRegex;
 exports.resolveRGXToken = resolveRGXToken;
 exports.rgxConcat = rgxConcat;
+exports.rgxa = rgxa;
 exports.default = rgx;
-const is_callable_1 = __importDefault(require("is-callable"));
 const e = __importStar(require("./errors"));
+const tg = __importStar(require("./type-guards"));
 __exportStar(require("./errors"), exports);
 __exportStar(require("./types"), exports);
-function isRGXNoOpToken(value) {
-    return value === null || value === undefined;
-}
-function assertRGXNoOpToken(value) {
-    if (!isRGXNoOpToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid no-op token`, 'null or undefined', value);
-    }
-}
-function isRGXLiteralToken(value) {
-    return value instanceof RegExp;
-}
-function assertRGXLiteralToken(value) {
-    if (!isRGXLiteralToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid literal token`, 'RegExp', value);
-    }
-}
-function isRGXNativeToken(value) {
-    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || isRGXNoOpToken(value);
-}
-function assertRGXNativeToken(value) {
-    if (!isRGXNativeToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid native token`, 'string, number, boolean, null, or undefined', value);
-    }
-}
-function isRGXConvertibleToken(value) {
-    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);
-        }
-        return false;
-    }
-    return false;
-}
-function assertRGXConvertibleToken(value) {
-    if (!isRGXConvertibleToken(value)) {
-        throw new e.RGXInvalidTokenError(`Invalid convertible token`, 'object with a toRgx method that returns a valid token', value);
-    }
-}
-function rgxTokenType(value) {
-    if (isRGXNoOpToken(value))
-        return 'no-op';
-    if (isRGXLiteralToken(value))
-        return 'literal';
-    if (isRGXNativeToken(value))
-        return 'native';
-    if (isRGXConvertibleToken(value))
-        return 'convertible';
-    if (Array.isArray(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);
-}
-function rgxTokenFromType(type, value) {
-    // Ignoring this line because the function is entirely a TypeScript utility that doesn't need to be tested at runtime.
-    /* istanbul ignore next */
-    return value;
-}
-function isValidRegexString(value) {
-    try {
-        new RegExp(value);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function assertValidRegexString(value) {
-    if (!isValidRegexString(value)) {
-        throw new e.RGXInvalidRegexStringError(`Invalid regex string: ${value}`, value);
-    }
-}
-function isValidVanillaRegexFlags(value) {
-    const patternMatch = /^[gimsuy]*$/.test(value);
-    if (!patternMatch)
-        return false;
-    // No repeated flags allowed
-    const flagsSet = new Set(value);
-    return flagsSet.size === value.length;
-}
-function assertValidVanillaRegexFlags(value) {
-    if (!isValidVanillaRegexFlags(value)) {
-        throw new e.RGXInvalidVanillaRegexFlagsError(`Invalid vanilla regex flags: ${value}`, value);
-    }
-}
+__exportStar(require("./type-guards"), exports);
 function escapeRegex(value) {
     return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
 }
 function resolveRGXToken(token) {
-    if (isRGXNoOpToken(token))
+    if (tg.isRGXNoOpToken(token))
         return '';
-    if (isRGXLiteralToken(token))
+    if (tg.isRGXLiteralToken(token))
         return '(?:' + token.source + ')';
-    if (isRGXNativeToken(token))
+    if (tg.isRGXNativeToken(token))
         return escapeRegex(String(token));
-    if (isRGXConvertibleToken(token)) {
+    if (tg.isRGXConvertibleToken(token)) {
         return resolveRGXToken(token.toRgx());
     }
     // Interpret arrays as unions
@@ -180,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 = '') {
-    assertValidVanillaRegexFlags(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.d.ts

@@ -0,0 +1,15 @@
+import * as t from "./types";
+export declare function isRGXNoOpToken(value: unknown): value is t.RGXNoOpToken;
+export declare function assertRGXNoOpToken(value: unknown): asserts value is t.RGXNoOpToken;
+export declare function isRGXLiteralToken(value: unknown): value is t.RGXLiteralToken;
+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 rgxTokenType(value: t.RGXToken): t.RGXTokenType;
+export declare function rgxTokenFromType<T extends t.RGXTokenType>(type: T, value: t.RGXToken): 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;
+export declare function assertValidVanillaRegexFlags(value: string): asserts value is t.ValidVanillaRegexFlags;

package/dist/type-guards.js

@@ -0,0 +1,143 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRGXNoOpToken = isRGXNoOpToken;
+exports.assertRGXNoOpToken = assertRGXNoOpToken;
+exports.isRGXLiteralToken = isRGXLiteralToken;
+exports.assertRGXLiteralToken = assertRGXLiteralToken;
+exports.isRGXNativeToken = isRGXNativeToken;
+exports.assertRGXNativeToken = assertRGXNativeToken;
+exports.isRGXConvertibleToken = isRGXConvertibleToken;
+exports.assertRGXConvertibleToken = assertRGXConvertibleToken;
+exports.rgxTokenType = rgxTokenType;
+exports.rgxTokenFromType = rgxTokenFromType;
+exports.isValidRegexString = isValidRegexString;
+exports.assertValidRegexString = assertValidRegexString;
+exports.isValidVanillaRegexFlags = isValidVanillaRegexFlags;
+exports.assertValidVanillaRegexFlags = assertValidVanillaRegexFlags;
+const e = __importStar(require("./errors"));
+const is_callable_1 = __importDefault(require("is-callable"));
+function isRGXNoOpToken(value) {
+    return value === null || value === undefined;
+}
+function assertRGXNoOpToken(value) {
+    if (!isRGXNoOpToken(value)) {
+        throw new e.RGXInvalidTokenError(`Invalid no-op token`, 'null or undefined', value);
+    }
+}
+function isRGXLiteralToken(value) {
+    return value instanceof RegExp;
+}
+function assertRGXLiteralToken(value) {
+    if (!isRGXLiteralToken(value)) {
+        throw new e.RGXInvalidTokenError(`Invalid literal token`, 'RegExp', value);
+    }
+}
+function isRGXNativeToken(value) {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || isRGXNoOpToken(value);
+}
+function assertRGXNativeToken(value) {
+    if (!isRGXNativeToken(value)) {
+        throw new e.RGXInvalidTokenError(`Invalid native token`, 'string, number, boolean, null, or undefined', value);
+    }
+}
+function isRGXConvertibleToken(value) {
+    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);
+        }
+        return false;
+    }
+    return false;
+}
+function assertRGXConvertibleToken(value) {
+    if (!isRGXConvertibleToken(value)) {
+        throw new e.RGXInvalidTokenError(`Invalid convertible token`, 'object with a toRgx method that returns a valid token', value);
+    }
+}
+function rgxTokenType(value) {
+    if (isRGXNoOpToken(value))
+        return 'no-op';
+    if (isRGXLiteralToken(value))
+        return 'literal';
+    if (isRGXNativeToken(value))
+        return 'native';
+    if (isRGXConvertibleToken(value))
+        return 'convertible';
+    if (Array.isArray(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);
+}
+function rgxTokenFromType(type, value) {
+    // Ignoring this line because the function is entirely a TypeScript utility that doesn't need to be tested at runtime.
+    /* istanbul ignore next */
+    return value;
+}
+function isValidRegexString(value) {
+    try {
+        new RegExp(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function assertValidRegexString(value) {
+    if (!isValidRegexString(value)) {
+        throw new e.RGXInvalidRegexStringError(`Invalid regex string: ${value}`, value);
+    }
+}
+function isValidVanillaRegexFlags(value) {
+    const patternMatch = /^[gimsuy]*$/.test(value);
+    if (!patternMatch)
+        return false;
+    // No repeated flags allowed
+    const flagsSet = new Set(value);
+    return flagsSet.size === value.length;
+}
+function assertValidVanillaRegexFlags(value) {
+    if (!isValidVanillaRegexFlags(value)) {
+        throw new e.RGXInvalidVanillaRegexFlagsError(`Invalid vanilla regex flags: ${value}`, value);
+    }
+}

package/package.json

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