@ptolemy2002/rgx 1.0.0 → 1.1.0

package/README.md

@@ -6,6 +6,7 @@ A library for easy construction and validation of regular expressions in TypeScr
 import { Branded } from "@ptolemy2002/ts-brand-utils";
 
 type RGXNoOpToken = null | undefined;
+type RGXLiteralToken = RegExp;
 type RGXNativeToken = string | number | boolean | RGXNoOpToken;
 type RGXConvertibleToken = { toRgx: () => RGXNativeToken | RGXNativeToken[] };
 type RGXToken = RGXNativeToken | RGXConvertibleToken | RGXToken[];
@@ -36,6 +37,19 @@ Checks if the given value is a no-op token (`null` or `undefined`).
 #### Returns
 - `boolean`: `true` if the value is a no-op token, otherwise `false`.
 
+### isRGXLiteralToken
+```typescript
+function isRGXLiteralToken(value: unknown): value is RGXLiteralToken
+```
+
+Checks if the given value is a literal token (a `RegExp` object).
+
+#### Parameters
+  - `value` (`unknown`): The value to check.
+
+#### Returns
+- `boolean`: `true` if the value is a literal token, otherwise `false`.
+
 ### isRGXNativeToken
 ```typescript
 function isRGXNativeToken(value: unknown): value is RGXNativeToken
@@ -132,7 +146,7 @@ Escapes special regex characters in the given string and brands the result as a
 function resolveRGXToken(token: RGXToken): string
 ```
 
-Resolves an RGX token to a string. No-op tokens resolve to an empty string, native tokens are converted to strings and escaped, convertible tokens are converted using their `toRgx` method and then resolved recursively, and arrays of tokens are resolved as unions of their resolved elements (placed in a non-capturing group).
+Resolves an RGX token to a string. No-op tokens resolve to an empty string, literal tokens are included as-is (wrapped in a non-capturing group), native tokens are converted to strings and escaped, convertible tokens are converted using their `toRgx` method and then resolved recursively, and arrays of tokens are resolved as unions of their resolved elements (placed in a non-capturing group).
 
 #### Parameters
   - `token` (`RGXToken`): The RGX token to resolve.
@@ -140,6 +154,19 @@ Resolves an RGX token to a string. No-op tokens resolve to an empty string, nati
 #### Returns
 - `string`: The resolved string representation of the RGX token.
 
+### rgxConcat
+```typescript
+function rgxConcat(tokens: RGXToken[]): string
+```
+
+A helper function that resolves an array of RGX tokens and concatenates their resolved string representations together. This is useful for cases where you want to concatenate multiple tokens without creating a union between them.
+
+#### Parameters
+  - `tokens` (`RGXToken[]`): The array of RGX tokens to resolve and concatenate.
+
+#### Returns
+- `string`: The concatenated string representation of the resolved RGX tokens.
+
 ### rgx
 ```typescript
 function rgx(strings: TemplateStringsArray, ...tokens: RGXToken[]): RegExp

package/dist/index.d.ts

@@ -1,18 +1,20 @@
 import { Branded } from "@ptolemy2002/ts-brand-utils";
 export type RGXNoOpToken = null | undefined;
+export type RGXLiteralToken = RegExp;
 export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
 export type RGXConvertibleToken = {
     toRgx: () => RGXNativeToken | RGXNativeToken[];
 };
-export type RGXToken = RGXNativeToken | RGXConvertibleToken | RGXToken[];
-export type RGXTokenType = 'no-op' | 'native' | 'convertible' | RGXTokenType[];
-export type RGXTokenFromType<T extends RGXTokenType> = T extends 'no-op' ? RGXNoOpToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends RGXTokenType[] ? {
+export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
+export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];
+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;
 export declare const validRegexSymbol: unique symbol;
 export type ValidRegexBrandSymbol = typeof validRegexSymbol;
 export type ValidRegexString = Branded<string, [ValidRegexBrandSymbol]>;
 export declare function isRGXNoOpToken(value: unknown): value is RGXNoOpToken;
+export declare function isRGXLiteralToken(value: unknown): value is RGXLiteralToken;
 export declare function isRGXNativeToken(value: unknown): value is RGXNativeToken;
 export declare function isRGXConvertibleToken(value: unknown): value is RGXConvertibleToken;
 export declare function rgxTokenType(value: RGXToken): RGXTokenType;
@@ -20,4 +22,5 @@ export declare function rgxTokenFromType<T extends RGXTokenType>(type: T, value:
 export declare function isValidRegex(value: string): value is ValidRegexString;
 export declare function escapeRegex(value: string): ValidRegexString;
 export declare function resolveRGXToken(token: RGXToken): string;
+export declare function rgxConcat(tokens: RGXToken[]): string;
 export default function rgx(strings: TemplateStringsArray, ...tokens: RGXToken[]): RegExp;

package/dist/index.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validRegexSymbol = void 0;
 exports.isRGXNoOpToken = isRGXNoOpToken;
+exports.isRGXLiteralToken = isRGXLiteralToken;
 exports.isRGXNativeToken = isRGXNativeToken;
 exports.isRGXConvertibleToken = isRGXConvertibleToken;
 exports.rgxTokenType = rgxTokenType;
@@ -12,12 +13,16 @@ exports.rgxTokenFromType = rgxTokenFromType;
 exports.isValidRegex = isValidRegex;
 exports.escapeRegex = escapeRegex;
 exports.resolveRGXToken = resolveRGXToken;
+exports.rgxConcat = rgxConcat;
 exports.default = rgx;
 const is_callable_1 = __importDefault(require("is-callable"));
 exports.validRegexSymbol = Symbol('ValidRegex');
 function isRGXNoOpToken(value) {
     return value === null || value === undefined;
 }
+function isRGXLiteralToken(value) {
+    return value instanceof RegExp;
+}
 function isRGXNativeToken(value) {
     return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || isRGXNoOpToken(value);
 }
@@ -37,6 +42,8 @@ function isRGXConvertibleToken(value) {
 function rgxTokenType(value) {
     if (isRGXNoOpToken(value))
         return 'no-op';
+    if (isRGXLiteralToken(value))
+        return 'literal';
     if (isRGXNativeToken(value))
         return 'native';
     if (isRGXConvertibleToken(value))
@@ -67,6 +74,8 @@ function escapeRegex(value) {
 function resolveRGXToken(token) {
     if (isRGXNoOpToken(token))
         return '';
+    if (isRGXLiteralToken(token))
+        return '(?:' + token.source + ')';
     if (isRGXNativeToken(token))
         return escapeRegex(String(token));
     if (isRGXConvertibleToken(token)) {
@@ -85,6 +94,10 @@ function resolveRGXToken(token) {
     /* istanbul ignore next */
     throw new TypeError(`Invalid RGX token: ${token}`);
 }
+// Wrapper for letting an array of tokens be resolved as a concatenation instead of a union.
+function rgxConcat(tokens) {
+    return tokens.map(resolveRGXToken).join('');
+}
 function rgx(strings, ...tokens) {
     let pattern = '';
     const resolvedTokens = tokens.map(resolveRGXToken);

package/package.json

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