@ptolemy2002/rgx 1.2.0 → 2.0.1

package/README.md

@@ -10,17 +10,67 @@ type RGXNoOpToken = null | undefined;
 type RGXLiteralToken = RegExp;
 type RGXNativeToken = string | number | boolean | RGXNoOpToken;
 type RGXConvertibleToken = { toRgx: () => MaybeArray<RGXNativeToken | RGXLiteralToken> };
-type RGXToken = RGXNativeToken | RGXConvertibleToken | RGXToken[];
+type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 
-const validRegexSymbol = Symbol('ValidRegex');
+const validRegexSymbol = Symbol('rgx.ValidRegex');
 type ValidRegexBrandSymbol = typeof validRegexSymbol;
 type ValidRegexString = Branded<string, [ValidRegexBrandSymbol]>;
 
-type RGXTokenType = 'no-op' | 'native' | 'convertible' | RGXTokenType[];
+const validVanillaRegexFlagsSymbol = Symbol('rgx.ValidVanillaRegexFlags');
+type ValidVanillaRegexFlagsBrandSymbol = typeof validVanillaRegexFlagsSymbol;
+type ValidVanillaRegexFlags = Branded<string, [ValidVanillaRegexFlagsBrandSymbol]>;
+
+type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];
 type RGXTokenFromType<T extends RGXTokenType> =
     // ... see source for full definition
 ;
+
+type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS';
+```
+
+## Classes
+The library exports the following classes:
+
+### RGXError
+A custom error class for RGX-related errors. This can be used to throw specific errors related to RGX token validation or resolution.
+
+#### Constructor
+```typescript
+constructor(message: string, code?: RGXErrorCode)
+```
+- `message` (`string`): The error message.
+- `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.
+
+#### 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.
+- `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.
+
+#### Constructor
+```typescript
+constructor(message: string, got: string)
+```
+- `message` (`string`): The error message.
+- `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.
+
+#### Constructor
+```typescript
+constructor(message: string, got: string)
 ```
+- `message` (`string`): The error message.
+- `got` (`string`): The actual string that was received, which failed validation.
 
 ## Functions
 The following functions are exported by the library:
@@ -38,6 +88,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`.
 
+### assertRGXNoOpToken
+```typescript
+function assertRGXNoOpToken(value: unknown): asserts value is RGXNoOpToken
+```
+
+Asserts that the given value is a no-op token (`null` or `undefined`). 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.
+
 ### isRGXLiteralToken
 ```typescript
 function isRGXLiteralToken(value: unknown): value is RGXLiteralToken
@@ -51,6 +114,19 @@ Checks if the given value is a literal token (a `RegExp` object).
 #### Returns
 - `boolean`: `true` if the value is a literal token, otherwise `false`.
 
+### assertRGXLiteralToken
+```typescript
+function assertRGXLiteralToken(value: unknown): asserts value is RGXLiteralToken
+```
+
+Asserts that the given value is a literal token (a `RegExp` object). 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.
+
 ### isRGXNativeToken
 ```typescript
 function isRGXNativeToken(value: unknown): value is RGXNativeToken
@@ -64,12 +140,25 @@ Checks if the given value is a native token (string, number, boolean, or no-op).
 #### Returns
 - `boolean`: `true` if the value is a native token, otherwise `false`.
 
+### assertRGXNativeToken
+```typescript
+function assertRGXNativeToken(value: unknown): asserts value is RGXNativeToken
+```
+
+Asserts that the given value is a native token (string, number, boolean, or no-op). 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.
+
 ### isRGXConvertibleToken
 ```typescript
 function isRGXConvertibleToken(value: unknown): value is RGXConvertibleToken
 ```
 
-Checks if the given value is a convertible token (an object with a `toRgx` method). Validates that `toRgx` is callable and returns a valid RGX native token or array of native tokens.
+Checks if the given value is a convertible token (an object with a `toRgx` method). Validates that `toRgx` is callable and returns a valid RGX native or literal token, or an array of native/literal tokens.
 
 #### Parameters
   - `value` (`unknown`): The value to check.
@@ -77,12 +166,24 @@ Checks if the given value is a convertible token (an object with a `toRgx` metho
 #### Returns
 - `boolean`: `true` if the value is a convertible token, otherwise `false`.
 
+### assertRGXConvertibleToken
+```typescript
+function assertRGXConvertibleToken(value: unknown): asserts value is RGXConvertibleToken
+```
+Asserts that the given value is a convertible token (an object with a `toRgx` method). Validates that `toRgx` is callable and returns a valid RGX native or literal token, or an array of native/literal tokens. 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
 ```
 
-Determines the type of a given RGX token (`no-op`, `native`, `convertible`, or an array of the former).
+Determines the type of a given RGX token (`no-op`, `literal`, `native`, `convertible`, or an array of the former).
 
 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.
 
@@ -116,9 +217,9 @@ 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`.
 
-### isValidRegex
+### isValidRegexString
 ```typescript
-function isValidRegex(value: string): value is ValidRegexString
+function isValidRegexString(value: string): value is ValidRegexString
 ```
 
 Checks if the given string is a valid regular expression by attempting to create a new `RegExp` object with it. If it succeeds, the string is branded as a `ValidRegexString`.
@@ -129,6 +230,43 @@ Checks if the given string is a valid regular expression by attempting to create
 #### Returns
 - `boolean`: `true` if the string is a valid regular expression, otherwise `false`.
 
+### assertValidRegexString
+```typescript
+function assertValidRegexString(value: string): asserts value is ValidRegexString
+```
+Asserts that the given string is a valid regular expression by attempting to create a new `RegExp` object with it. If it succeeds, the string is branded as a `ValidRegexString`. If the assertion fails, an `RGXInvalidRegexStringError` will be thrown.
+
+#### Parameters
+  - `value` (`string`): The string to assert.
+
+#### Returns
+- `void`: This function does not return a value, but will throw an error if the assertion fails.
+
+### isValidVanillaRegexFlags
+```typescript
+function isValidVanillaRegexFlags(value: string): value is ValidVanillaRegexFlags
+```
+
+Checks if the given string is a valid combination of vanilla regex flags (g, i, m, s, u, y). Each flag can only appear once.
+
+#### Parameters
+  - `value` (`string`): The string to check.
+
+#### Returns
+- `boolean`: `true` if the string is a valid combination of vanilla regex flags, otherwise `false`.
+
+### assertValidVanillaRegexFlags
+```typescript
+function assertValidVanillaRegexFlags(value: string): asserts value is ValidVanillaRegexFlags
+```
+Asserts that the given string is a valid combination of vanilla regex flags (g, i, m, s, u, y). Each flag can only appear once. If the assertion fails, an `RGXInvalidVanillaRegexFlagsError` will be thrown.
+
+#### Parameters
+  - `value` (`string`): The string to assert.
+
+#### Returns
+- `void`: This function does not return a value, but will throw an error if the assertion fails.
+
 ### escapeRegex
 ```typescript
 function escapeRegex(value: string): ValidRegexString
@@ -170,30 +308,34 @@ A helper function that resolves an array of RGX tokens and concatenates their re
 
 ### rgx
 ```typescript
-function rgx(strings: TemplateStringsArray, ...tokens: RGXToken[]): RegExp
+function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: RGXToken[]) =>RegExp
 ```
 
-A template tag function that constructs a `RegExp` object from the provided template literal. The template literal can contain RGX tokens, which will be resolved and concatenated with the literal parts to form the final regex pattern.
+Creates and returns a template tag function that constructs a `RegExp` object from the provided template literal with the provided flags. The template literal can contain RGX tokens, which will be resolved and concatenated with the literal parts to form the final regex pattern.
 
 Example usages:
 ```typescript
 const beginning = /^/;
 const end = /$/;
 const word = /\w+/;
-const pattern = rgx`${beginning}testing ${word}${end}`; // /^testing \w+$/ - matches the string "testing " followed by a word, anchored to the start and end of the string
+const pattern = rgx()`${beginning}testing ${word}${end}`; // /^testing \w+$/ - matches the string "testing " followed by a word, anchored to the start and end of the string
 
 const optionalDigit = /\d?/;
-const pattern2 = rgx`${beginning}optional digit: ${optionalDigit}${end}`; // /^optional digit: \d?$/ - matches the string "optional digit: " followed by an optional digit, anchored to the start and end of the string
+const pattern2 = rgx()`${beginning}optional digit: ${optionalDigit}${end}`; // /^optional digit: \d?$/ - matches the string "optional digit: " followed by an optional digit, anchored to the start and end of the string
 
-const pattern3 = rgx`${beginning}value: ${[word, optionalDigit]}${end}`; // /^value: (?:\w+|\d?)$/ - matches the string "value: " followed by either a word or an optional digit, anchored to the start and end of the string
+const pattern3 = rgx()`${beginning}value: ${[word, optionalDigit]}${end}`; // /^value: (?:\w+|\d?)$/ - matches the string "value: " followed by either a word or an optional digit, anchored to the start and end of the string
 ```
 
 #### 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.
+
+**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
-- `RegExp`: The resulting regular expression object constructed from the template literal.
+- `(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.
 
 ## Peer Dependencies
 - `@ptolemy2002/ts-brand-utils` ^1.0.0

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,50 @@
+"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;

package/dist/index.d.ts

@@ -1,27 +1,21 @@
-import { Branded } from "@ptolemy2002/ts-brand-utils";
-import { MaybeArray } from "@ptolemy2002/ts-utils";
-export type RGXNoOpToken = null | undefined;
-export type RGXLiteralToken = RegExp;
-export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
-export type RGXConvertibleToken = {
-    toRgx: () => MaybeArray<RGXNativeToken | RGXLiteralToken>;
-};
-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;
-export declare function rgxTokenFromType<T extends RGXTokenType>(type: T, value: RGXToken): RGXTokenFromType<T>;
-export declare function isValidRegex(value: string): value is ValidRegexString;
-export declare function escapeRegex(value: string): ValidRegexString;
-export declare function resolveRGXToken(token: RGXToken): ValidRegexString;
-export declare function rgxConcat(tokens: RGXToken[]): ValidRegexString;
-export default function rgx(strings: TemplateStringsArray, ...tokens: RGXToken[]): RegExp;
+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 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 default function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => RegExp;

package/dist/index.js

@@ -1,31 +1,90 @@
 "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 __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.validRegexSymbol = void 0;
 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.isValidRegex = isValidRegex;
+exports.isValidRegexString = isValidRegexString;
+exports.assertValidRegexString = assertValidRegexString;
+exports.isValidVanillaRegexFlags = isValidVanillaRegexFlags;
+exports.assertValidVanillaRegexFlags = assertValidVanillaRegexFlags;
 exports.escapeRegex = escapeRegex;
 exports.resolveRGXToken = resolveRGXToken;
 exports.rgxConcat = rgxConcat;
 exports.default = rgx;
 const is_callable_1 = __importDefault(require("is-callable"));
-exports.validRegexSymbol = Symbol('ValidRegex');
+const e = __importStar(require("./errors"));
+__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)) {
@@ -39,6 +98,11 @@ function isRGXConvertibleToken(value) {
     }
     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';
@@ -52,14 +116,14 @@ 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 TypeError(`Invalid RGX token: ${value}`);
+    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 isValidRegex(value) {
+function isValidRegexString(value) {
     try {
         new RegExp(value);
         return true;
@@ -68,6 +132,24 @@ function isValidRegex(value) {
         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);
+    }
+}
 function escapeRegex(value) {
     return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -92,20 +174,23 @@ function resolveRGXToken(token) {
     }
     // 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 TypeError(`Invalid RGX token: ${token}`);
+    throw new e.RGXInvalidTokenError(`Invalid RGX token: ${token}`, null, 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);
-    for (let i = 0; i < strings.length; i++) {
-        pattern += strings[i];
-        if (i < resolvedTokens.length) {
-            pattern += resolvedTokens[i];
+function rgx(flags = '') {
+    assertValidVanillaRegexFlags(flags);
+    return (strings, ...tokens) => {
+        let pattern = '';
+        const resolvedTokens = tokens.map(resolveRGXToken);
+        for (let i = 0; i < strings.length; i++) {
+            pattern += strings[i];
+            if (i < resolvedTokens.length) {
+                pattern += resolvedTokens[i];
+            }
         }
-    }
-    return new RegExp(pattern);
+        return new RegExp(pattern, flags);
+    };
 }

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+import { Branded } from "@ptolemy2002/ts-brand-utils";
+import { MaybeArray } from "@ptolemy2002/ts-utils";
+export type RGXNoOpToken = null | undefined;
+export type RGXLiteralToken = RegExp;
+export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
+export type RGXConvertibleToken = {
+    toRgx: () => MaybeArray<RGXNativeToken | RGXLiteralToken>;
+};
+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 const validVanillaRegexFlagsSymbol: unique symbol;
+export type ValidVanillaRegexFlagsBrandSymbol = typeof validVanillaRegexFlagsSymbol;
+export type ValidVanillaRegexFlags = Branded<string, [ValidVanillaRegexFlagsBrandSymbol]>;

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validVanillaRegexFlagsSymbol = exports.validRegexSymbol = void 0;
+exports.validRegexSymbol = Symbol('rgx.ValidRegex');
+exports.validVanillaRegexFlagsSymbol = Symbol('rgx.ValidVanillaRegexFlags');

package/package.json

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