@ptolemy2002/rgx 4.7.0 → 4.10.0

package/README.md

@@ -44,7 +44,7 @@ type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // ... see source for full definition
 ;
 
-type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT';
+type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT';
 
 type RangeObject = {
     min?: number | null;
@@ -143,6 +143,19 @@ constructor(functionality: string, message?: string | null)
 #### Properties
 - `functionality` (`string`): The description of the unimplemented functionality.
 
+### RGXNotSupportedError extends RGXError
+A specific error class for unsupported functionality. This error is thrown when a feature or method is intentionally not supported (as opposed to simply not yet implemented). The error code is set to `NOT_SUPPORTED` on instantiation.
+
+#### Constructor
+```typescript
+constructor(functionality: string, message?: string | null)
+```
+- `functionality` (`string`): A description of the functionality that is not supported.
+- `message` (`string | null`, optional): An optional additional message providing more context. Defaults to `null`.
+
+#### Properties
+- `functionality` (`string`): The description of the unsupported functionality.
+
 ### RGXInvalidIdentifierError extends RGXError
 A specific error class for invalid identifiers. This error is thrown when a string fails validation as a valid identifier. The error code is set to `INVALID_IDENTIFIER` on instantiation.
 
@@ -262,14 +275,17 @@ An abstract base class for creating custom RGX token classes. Subclasses must im
 
 #### Properties
 - `isGroup` (`boolean`): Returns `false` by default. Subclasses can override this to indicate whether the token represents a group.
+- `isRepeatable` (`boolean`): Returns `true` by default. Subclasses can override this to indicate that the token cannot be wrapped in an `RGXRepeatToken`. When `false`, attempting to set this token as the `token` property of an `RGXRepeatToken` (including via `repeat()` or `optional()`) will throw an `RGXNotSupportedError`.
 - `rgxGroupWrap` (`boolean`): Returns `true` by default. Controls whether the resolver wraps this token's resolved output in a non-capturing group. Subclasses can override this to prevent double-wrapping (e.g., when the token already wraps itself in a group).
 
 #### Methods
 - `or(...others: RGXTokenCollectionInput[]) => RGXClassUnionToken`: Creates an `RGXClassUnionToken` that represents a union (alternation) of this token with the provided others. If any of the `others` are `RGXClassUnionToken` instances, their tokens are flattened into the union rather than nested. If `this` is already an `RGXClassUnionToken`, its existing tokens are preserved and the others are appended.
 - `group(args?: RGXGroupTokenArgs) => RGXGroupToken`: Wraps this token in an `RGXGroupToken` with the provided arguments. The `args` parameter defaults to `{}`, which creates a capturing group with no name. This is a convenience method that creates a new `RGXGroupToken` with `this` as the sole token.
-- `repeat(min?: number, max?: number | null) => RGXRepeatToken`: Wraps this token in an `RGXRepeatToken` with the given repetition bounds. `min` defaults to `1`, `max` defaults to `min`. Pass `null` for `max` to allow unlimited repetitions. This is a convenience method that creates a new `RGXRepeatToken` with `this` as the token.
-- `optional() => RGXRepeatToken`: Shorthand for `repeat(0, 1)`. Wraps this token in an `RGXRepeatToken` that matches the token zero or one times.
-- `resolve() => ValidRegexString`: A convenience method that resolves this token by calling `resolveRGXToken(this)`, returning the resolved regex string representation. Since this method is defined on `RGXClassToken`, it is available on all subclasses including `RGXClassUnionToken`, `RGXGroupToken`, and `RGXRepeatToken`.
+- `repeat(min?: number, max?: number | null) => RGXRepeatToken`: Wraps this token in an `RGXRepeatToken` with the given repetition bounds. `min` defaults to `1`, `max` defaults to `min`. Pass `null` for `max` to allow unlimited repetitions. This is a convenience method that creates a new `RGXRepeatToken` with `this` as the token. Throws `RGXNotSupportedError` if called on an `RGXLookaroundToken`, as lookaround assertions cannot be repeated.
+- `optional() => RGXRepeatToken`: Shorthand for `repeat(0, 1)`. Wraps this token in an `RGXRepeatToken` that matches the token zero or one times. Throws `RGXNotSupportedError` if called on an `RGXLookaroundToken`, as lookaround assertions cannot be made optional.
+- `asLookahead(positive?: boolean) => RGXLookaheadToken`: Wraps this token in an `RGXLookaheadToken`. `positive` defaults to `true`. If this token is already an `RGXLookaheadToken`, it is returned as-is without re-wrapping.
+- `asLookbehind(positive?: boolean) => RGXLookbehindToken`: Wraps this token in an `RGXLookbehindToken`. `positive` defaults to `true`. If this token is already an `RGXLookbehindToken`, it is returned as-is without re-wrapping.
+- `resolve() => ValidRegexString`: A convenience method that resolves this token by calling `resolveRGXToken(this)`, returning the resolved regex string representation. Since this method is defined on `RGXClassToken`, it is available on all subclasses including `RGXClassUnionToken`, `RGXGroupToken`, `RGXRepeatToken`, and `RGXLookaroundToken`.
 
 ### RGXClassUnionToken extends RGXClassToken
 A class representing a union (alternation) of RGX tokens. This is typically created via the `or()` method on `RGXClassToken`, but can also be instantiated directly.
@@ -340,7 +356,7 @@ constructor(token: RGXToken, min?: number, max?: number | null)
 - `max` (`number | null`, optional): The maximum number of repetitions. Must be >= `min` when not `null`. Non-integer values are floored. Pass `null` for unlimited repetitions. Defaults to `min`.
 
 #### Properties
-- `token` (`RGXGroupedToken`): The token being repeated. Setting this will automatically wrap non-grouped tokens in a non-capturing `RGXGroupToken`.
+- `token` (`RGXGroupedToken`): The token being repeated. Setting this will throw `RGXNotSupportedError` if the value is a class token with `isRepeatable` set to `false`, and will automatically wrap non-grouped tokens in a non-capturing `RGXGroupToken`.
 - `min` (`number`): The minimum number of repetitions. Setting this validates that the value is >= 0 and <= `max` (when `max` is not `null`), and floors non-integer values. Throws `RGXOutOfBoundsError` if validation fails.
 - `max` (`number | null`): The maximum number of repetitions. Setting this validates that the value is >= `min` when not `null`, and floors non-integer values. Pass `null` for unlimited. Throws `RGXOutOfBoundsError` if validation fails.
 - `repeaterSuffix` (`string`): Returns the regex quantifier suffix based on the current `min` and `max` values: `*` for `{0,}`, `+` for `{1,}`, `?` for `{0,1}`, `{n}` for exact repetitions, `{n,}` for minimum-only, `{n,m}` for a range, or an empty string for `{1,1}` (exactly once, no quantifier needed).
@@ -349,6 +365,84 @@ constructor(token: RGXToken, min?: number, max?: number | null)
 #### Methods
 - `toRgx() => RGXToken`: Resolves the repeat token to a `RegExp` by resolving the inner token and appending the `repeaterSuffix`. Returns `null` (a no-op) when both `min` and `max` are `0`.
 
+### RGXLookaroundToken extends RGXClassToken (abstract)
+An abstract base class for lookaround assertion tokens (lookahead and lookbehind). Lookaround assertions match a pattern without consuming characters in the string. Subclasses must implement the `toRgx()`, `negate()`, and `reverse()` methods.
+
+#### Static Properties
+- `check(value: unknown): value is RGXLookaroundToken`: A type guard that checks if the given value is an instance of `RGXLookaroundToken`.
+- `assert(value: unknown): asserts value is RGXLookaroundToken`: An assertion that checks if the given value is an instance of `RGXLookaroundToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(tokens?: RGXTokenCollectionInput, positive?: boolean)
+```
+- `tokens` (`RGXTokenCollectionInput`, optional): The tokens to include in the lookaround. Internally stored as an `RGXTokenCollection` in 'concat' mode. Defaults to an empty array.
+- `positive` (`boolean`, optional): Whether the lookaround is positive (matches if the pattern is present) or negative (matches if the pattern is absent). Defaults to `true`.
+
+#### Properties
+- `tokens` (`RGXTokenCollection`): The internal collection of tokens managed in 'concat' mode.
+- `positive` (`boolean`): Whether the lookaround is positive. Setting this updates `negative` accordingly.
+- `negative` (`boolean`): Whether the lookaround is negative. Setting this updates `positive` accordingly.
+- `isGroup` (`true`): Returns `true` as a constant, indicating this token represents a group.
+- `isRepeatable` (`false`): Returns `false` as a constant, since lookaround assertions cannot be repeated.
+- `rgxGroupWrap` (`false`): Returns `false` as a constant, since the lookaround already wraps itself in a group.
+
+#### Abstract Methods
+- `negate() => RGXLookaroundToken`: Returns a new lookaround token of the same type with the opposite positivity, preserving the original tokens.
+- `reverse() => RGXLookaroundToken`: Returns a new lookaround token of the opposite direction (lookahead becomes lookbehind and vice versa), preserving the original tokens and positivity.
+
+### RGXLookaheadToken extends RGXLookaroundToken
+A class representing a lookahead assertion. Positive lookaheads (`(?=...)`) match if the pattern is present ahead, while negative lookaheads (`(?!...)`) match if the pattern is absent. This is typically created via the `asLookahead()` method on `RGXClassToken`, but can also be instantiated directly.
+
+A function `rgxLookahead` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Static Properties
+- `check(value: unknown): value is RGXLookaheadToken`: A type guard that checks if the given value is an instance of `RGXLookaheadToken`.
+- `assert(value: unknown): asserts value is RGXLookaheadToken`: An assertion that checks if the given value is an instance of `RGXLookaheadToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Methods
+- `negate() => RGXLookaheadToken`: Returns a new `RGXLookaheadToken` with the opposite positivity, preserving the original tokens.
+- `reverse() => RGXLookbehindToken`: Returns a new `RGXLookbehindToken` with the same tokens and positivity.
+- `toRgx() => RegExp`: Resolves the lookahead to a `RegExp`. Positive lookaheads produce `(?=...)` and negative lookaheads produce `(?!...)`.
+
+### RGXLookbehindToken extends RGXLookaroundToken
+A class representing a lookbehind assertion. Positive lookbehinds (`(?<=...)`) match if the pattern is present behind, while negative lookbehinds (`(?<!...)`) match if the pattern is absent. This is typically created via the `asLookbehind()` method on `RGXClassToken`, but can also be instantiated directly.
+
+A function `rgxLookbehind` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Static Properties
+- `check(value: unknown): value is RGXLookbehindToken`: A type guard that checks if the given value is an instance of `RGXLookbehindToken`.
+- `assert(value: unknown): asserts value is RGXLookbehindToken`: An assertion that checks if the given value is an instance of `RGXLookbehindToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Methods
+- `negate() => RGXLookbehindToken`: Returns a new `RGXLookbehindToken` with the opposite positivity, preserving the original tokens.
+- `reverse() => RGXLookaheadToken`: Returns a new `RGXLookaheadToken` with the same tokens and positivity.
+- `toRgx() => RegExp`: Resolves the lookbehind to a `RegExp`. Positive lookbehinds produce `(?<=...)` and negative lookbehinds produce `(?<!...)`.
+
+### RGXClassWrapperToken extends RGXClassToken
+A class that wraps any `RGXToken` as an `RGXClassToken`, giving you access to the extended API class tokens provide. It delegates `isGroup` and `isRepeatable` to the wrapped token where possible.
+
+A function `rgxClassWrapper` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Static Properties
+- `check(value: unknown): value is RGXClassWrapperToken`: A type guard that checks if the given value is an instance of `RGXClassWrapperToken`.
+- `assert(value: unknown): asserts value is RGXClassWrapperToken`: An assertion that checks if the given value is an instance of `RGXClassWrapperToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(token: RGXToken)
+```
+- `token` (`RGXToken`): The token to wrap.
+
+#### Properties
+- `token` (`RGXToken`): The wrapped token.
+- `isGroup` (`boolean`): Delegates to the wrapped token's group status via `isRGXGroupedToken`. Returns `true` if the wrapped token is a grouped token, otherwise `false`.
+- `isRepeatable` (`boolean`): If the wrapped token is an `RGXClassToken`, delegates to its `isRepeatable` property. Otherwise, returns `true`.
+
+#### Methods
+- `unwrap() => RGXToken`: Returns the original wrapped token.
+- `toRgx() => RGXToken`: Returns the original wrapped token (alias for `unwrap()`).
+
 ### ExtRegExp extends RegExp
 A subclass of `RegExp` that supports custom flag transformers in addition to the standard vanilla regex flags (g, i, m, s, u, y). When constructed, custom flags are extracted, their corresponding transformers are applied to the pattern and vanilla flags, and the resulting transformed `RegExp` is created. The `flags` getter returns both the vanilla flags and any custom flags.
 
@@ -746,24 +840,27 @@ Escapes special regex characters in the given string and brands the result as a
 
 ### resolveRGXToken
 ```typescript
-function resolveRGXToken(token: RGXToken, groupWrap?: boolean, topLevel?: boolean): ValidRegexString
+function resolveRGXToken(token: RGXToken, groupWrap?: boolean, topLevel?: boolean, currentFlags?: string): ValidRegexString
 ```
 
 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 when `groupWrap` is `true`), 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 (repeats removed, placed in a non-capturing group when `groupWrap` is `true`).
 
+For literal tokens (`RegExp` instances), if the token's flags differ from `currentFlags` in any of the localizable flags (`i`, `m`, `s`), the token is wrapped in an inline modifier group (e.g., `(?i:...)`, `(?-i:...)`, `(?ms-i:...)`) instead of a plain non-capturing group. Non-localizable flags (such as `g`, `u`, `y`, `d`, `v`) are ignored when computing the diff. When an inline modifier group is used, it always wraps the token regardless of the `groupWrap` setting, since the modifier group itself serves as a group.
+
 For convertible tokens, if the token has an `rgxGroupWrap` property, that value always takes precedence. If `rgxGroupWrap` is not present, the behavior depends on whether the call is top-level: at the top level, the `groupWrap` parameter is passed through; in recursive calls, it falls back to `true` regardless of the `groupWrap` parameter. This ensures that the caller's `groupWrap` preference only affects the outermost convertible token and does not leak into deeply nested resolution.
 
 #### Parameters
   - `token` (`RGXToken`): The RGX token to resolve.
-  - `groupWrap` (`boolean`, optional): Whether to wrap literal tokens and array unions in non-capturing groups (`(?:...)`). Defaults to `true`. When `false`, literals use their raw source and array unions omit the wrapping group. For convertible tokens, the token's `rgxGroupWrap` property always takes precedence; otherwise, this value is only passed through at the top level (in recursive calls it falls back to `true`). Array union elements always use `groupWrap=true` internally.
+  - `groupWrap` (`boolean`, optional): Whether to wrap literal tokens and array unions in non-capturing groups (`(?:...)`). Defaults to `true`. When `false`, literals use their raw source and array unions omit the wrapping group. For convertible tokens, the token's `rgxGroupWrap` property always takes precedence; otherwise, this value is only passed through at the top level (in recursive calls it falls back to `true`). Array union elements always use `groupWrap=true` internally. Note that when a literal token requires an inline modifier group due to a localizable flag diff, it is always wrapped regardless of this setting.
   - `topLevel` (`boolean`, optional): Tracks whether the current call is the initial (top-level) invocation. Defaults to `true`. **Warning**: This parameter is intended for internal use by the resolver's own recursion. External callers should not set this parameter, as doing so may produce unexpected wrapping behavior.
+  - `currentFlags` (`string`, optional): The flags of the current regex context, used to compute inline modifier groups for literal tokens. Defaults to `''`. When a literal token's localizable flags (`i`, `m`, `s`) differ from this value, the resolver wraps the token in an inline modifier group that adds or removes the differing flags locally.
 
 #### Returns
 - `ValidRegexString`: The resolved string representation of the RGX token. This is guaranteed to be a valid regex string, as convertible tokens are validated to only produce valid regex strings or arrays of valid regex strings.
 
 ### rgxConcat
 ```typescript
-function rgxConcat(tokens: RGXToken[], groupWrap?: boolean): ValidRegexString
+function rgxConcat(tokens: RGXToken[], groupWrap?: boolean, currentFlags?: string): ValidRegexString
 ```
 
 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.
@@ -771,6 +868,7 @@ A helper function that resolves an array of RGX tokens and concatenates their re
 #### Parameters
   - `tokens` (`RGXToken[]`): The array of RGX tokens to resolve and concatenate.
   - `groupWrap` (`boolean`, optional): Whether to wrap individual resolved tokens in non-capturing groups. Passed through to `resolveRGXToken`. Defaults to `true`.
+  - `currentFlags` (`string`, optional): The flags of the current regex context, passed through to `resolveRGXToken` as its `currentFlags` parameter. Used to compute inline modifier groups for literal tokens whose localizable flags differ. Defaults to `''`.
 
 #### Returns
 - `ValidRegexString`: The concatenated string representation of the resolved RGX tokens. This is guaranteed to be a valid regex string, as it is composed of the resolved forms of RGX tokens, which are all valid regex strings.
@@ -782,6 +880,8 @@ function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: RGXToke
 
 Creates and returns a template tag function that constructs an `ExtRegExp` 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.
 
+The provided `flags` are passed as `currentFlags` to the resolver, enabling inline modifier groups for any `RegExp` literal tokens whose localizable flags (`i`, `m`, `s`) differ from the parent flags. For example, embedding `/foo/i` in a no-flag context produces `(?i:foo)`, while embedding `/bar/` in an `i`-flag context produces `(?-i:bar)`.
+
 Example usages:
 ```typescript
 const beginning = /^/;
@@ -793,6 +893,9 @@ 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 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 caseInsensitiveWord = /hello/i;
+const pattern4 = rgx()`${beginning}${caseInsensitiveWord} world${end}`; // /^(?i:hello) world$/ - "hello" matches case-insensitively via an inline modifier group, while " world" remains case-sensitive
 ```
 
 #### Parameters
@@ -810,7 +913,7 @@ const pattern3 = rgx()`${beginning}value: ${[word, optionalDigit]}${end}`; // /^
 ```typescript
 function rgxa(tokens: RGXToken[], flags?: string): ExtRegExp
 ```
-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 an `ExtRegExp` object. This is useful in cases where you don't want to use a template literal.
+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 an `ExtRegExp` object. This is useful in cases where you don't want to use a template literal. Like `rgx`, the provided `flags` are passed as `currentFlags` to the resolver, enabling inline modifier groups for `RegExp` literal tokens whose localizable flags differ.
 
 #### Parameters
   - `tokens` (`RGXToken[]`): The RGX tokens to be resolved and concatenated to form the regex pattern.
@@ -850,7 +953,23 @@ Removes duplicate tokens from the provided list using `Set` equality and returns
 function rgxClassInit(): void
 ```
 
-Initializes internal method patches required for `RGXClassToken` subclass methods (such as `or`, `group`, and `repeat`) to work correctly. This function is called automatically when importing from the main module entry point, so you typically do not need to call it yourself. It only needs to be called manually if you import directly from sub-modules.
+Initializes internal method patches required for `RGXClassToken` subclass methods (such as `or`, `group`, `repeat`, `asLookahead`, and `asLookbehind`) to work correctly. This function is called automatically when importing from the main module entry point, so you typically do not need to call it yourself. It only needs to be called manually if you import directly from sub-modules.
+
+### toRGXClassToken
+```typescript
+function toRGXClassToken(token: RGXToken): RGXClassToken
+```
+
+Converts any `RGXToken` into an appropriate `RGXClassToken` subclass, giving you access to the extended API that class tokens provide. Tokens that are already class tokens are returned as-is. Array tokens and `RGXTokenCollection` instances in union mode are converted to `RGXClassUnionToken`. `RGXTokenCollection` instances in concat mode are converted to a non-capturing `RGXGroupToken`. All other tokens are wrapped in an `RGXClassWrapperToken`.
+
+#### Parameters
+  - `token` (`RGXToken`): The token to convert.
+
+#### Returns
+- `RGXClassToken`: The corresponding class token:
+  - `RGXClassUnionToken` for array tokens and union-mode `RGXTokenCollection` instances.
+  - `RGXGroupToken` (non-capturing) for concat-mode `RGXTokenCollection` instances.
+  - `RGXClassWrapperToken` for all other tokens.
 
 ### isInRange
 ```typescript

package/dist/class/base.d.ts

@@ -3,15 +3,20 @@ import { RGXTokenCollectionInput } from "../collection";
 import type { RGXClassUnionToken } from "./union";
 import type { RGXGroupToken, RGXGroupTokenArgs } from "./group";
 import type { RGXRepeatToken } from "./repeat";
+import type { RGXLookaheadToken } from "./lookahead";
+import type { RGXLookbehindToken } from "./lookbehind";
 export declare abstract class RGXClassToken {
     abstract toRgx(): RGXToken;
     static check: (value: unknown) => value is RGXClassToken;
     static assert: (value: unknown) => asserts value is RGXClassToken;
     get isGroup(): boolean;
+    get isRepeatable(): boolean;
     get rgxGroupWrap(): boolean;
     or(...others: RGXTokenCollectionInput[]): RGXClassUnionToken;
     group(args?: RGXGroupTokenArgs): RGXGroupToken;
     repeat(min?: number, max?: number | null): RGXRepeatToken;
     optional(): RGXRepeatToken;
+    asLookahead(positive?: boolean): RGXLookaheadToken;
+    asLookbehind(positive?: boolean): RGXLookbehindToken;
     resolve(): ValidRegexString;
 }

package/dist/class/base.js

@@ -7,6 +7,9 @@ class RGXClassToken {
     get isGroup() {
         return false;
     }
+    get isRepeatable() {
+        return true;
+    }
     get rgxGroupWrap() {
         return true;
     }
@@ -22,6 +25,12 @@ class RGXClassToken {
     optional() {
         return this.repeat(0, 1);
     }
+    asLookahead(positive = true) {
+        throw new errors_1.RGXNotImplementedError('RGXClassToken.asLookahead(positive)', 'call rgxClassInit() first.');
+    }
+    asLookbehind(positive = true) {
+        throw new errors_1.RGXNotImplementedError('RGXClassToken.asLookbehind(positive)', 'call rgxClassInit() first.');
+    }
     resolve() {
         return (0, resolve_1.resolveRGXToken)(this);
     }

package/dist/class/index.d.ts

@@ -3,3 +3,8 @@ export * from "./base";
 export * from "./union";
 export * from "./group";
 export * from "./repeat";
+export * from "./lookaround";
+export * from "./lookahead";
+export * from "./lookbehind";
+export * from "./wrapper";
+export * from "./toRGXClassToken";

package/dist/class/index.js

@@ -19,3 +19,8 @@ __exportStar(require("./base"), exports);
 __exportStar(require("./union"), exports);
 __exportStar(require("./group"), exports);
 __exportStar(require("./repeat"), exports);
+__exportStar(require("./lookaround"), exports);
+__exportStar(require("./lookahead"), exports);
+__exportStar(require("./lookbehind"), exports);
+__exportStar(require("./wrapper"), exports);
+__exportStar(require("./toRGXClassToken"), exports);

package/dist/class/init.js

@@ -5,6 +5,10 @@ const base_1 = require("./base");
 const union_1 = require("./union");
 const group_1 = require("./group");
 const repeat_1 = require("./repeat");
+const lookaround_1 = require("./lookaround");
+const errors_1 = require("../errors");
+const lookahead_1 = require("./lookahead");
+const lookbehind_1 = require("./lookbehind");
 function rgxClassInit() {
     // Patch RGXClassToken here, Since classes like RGXClassUnionToken are instances of RGXClassToken
     // themselves. If we tried to import RGXClassUnionToken in base.ts, it would cause a circular dependency.
@@ -25,6 +29,18 @@ function rgxClassInit() {
         return new group_1.RGXGroupToken(args, [this]);
     };
     base_1.RGXClassToken.prototype.repeat = function (min = 1, max = min) {
+        if (lookaround_1.RGXLookaroundToken.check(this))
+            throw new errors_1.RGXNotSupportedError("RGXLookaroundToken.repeat()", "Lookaround tokens cannot be repeated or made optional.");
         return new repeat_1.RGXRepeatToken(this, min, max);
     };
+    base_1.RGXClassToken.prototype.asLookahead = function (positive = true) {
+        if (lookahead_1.RGXLookaheadToken.check(this))
+            return this;
+        return new lookahead_1.RGXLookaheadToken([this], positive);
+    };
+    base_1.RGXClassToken.prototype.asLookbehind = function (positive = true) {
+        if (lookbehind_1.RGXLookbehindToken.check(this))
+            return this;
+        return new lookbehind_1.RGXLookbehindToken([this], positive);
+    };
 }

package/dist/class/lookahead.d.ts

@@ -0,0 +1,11 @@
+import { RGXToken } from "../types";
+import { RGXLookaroundToken } from "./lookaround";
+import { RGXLookbehindToken } from "./lookbehind";
+export declare class RGXLookaheadToken extends RGXLookaroundToken {
+    static check: (value: unknown) => value is RGXLookaheadToken;
+    static assert: (value: unknown) => asserts value is RGXLookaheadToken;
+    negate(): RGXLookaheadToken;
+    reverse(): RGXLookbehindToken;
+    toRgx(): RGXToken;
+}
+export declare const rgxLookahead: (tokens?: import("..").RGXTokenCollectionInput, positive?: boolean | undefined) => RGXLookaheadToken;

package/dist/class/lookahead.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxLookahead = exports.RGXLookaheadToken = void 0;
+const internal_1 = require("../internal");
+const lookaround_1 = require("./lookaround");
+const lookbehind_1 = require("./lookbehind");
+class RGXLookaheadToken extends lookaround_1.RGXLookaroundToken {
+    negate() {
+        return new RGXLookaheadToken(this.tokens, !this.positive);
+    }
+    reverse() {
+        return new lookbehind_1.RGXLookbehindToken(this.tokens, this.positive);
+    }
+    toRgx() {
+        let result = this.tokens.toRgx().source;
+        if (this.positive)
+            result = `(?=${result})`;
+        else
+            result = `(?!${result})`;
+        return new RegExp(result);
+    }
+}
+exports.RGXLookaheadToken = RGXLookaheadToken;
+RGXLookaheadToken.check = (0, internal_1.createClassGuardFunction)(RGXLookaheadToken);
+RGXLookaheadToken.assert = (0, internal_1.createAssertClassGuardFunction)(RGXLookaheadToken);
+exports.rgxLookahead = (0, internal_1.createConstructFunction)(RGXLookaheadToken);

package/dist/class/lookaround.d.ts

@@ -0,0 +1,18 @@
+import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
+import { RGXClassToken } from "./base";
+export declare abstract class RGXLookaroundToken extends RGXClassToken {
+    tokens: RGXTokenCollection;
+    _negative: boolean;
+    static check: (value: unknown) => value is RGXLookaroundToken;
+    static assert: (value: unknown) => asserts value is RGXLookaroundToken;
+    get isGroup(): true;
+    get isRepeatable(): false;
+    get rgxGroupWrap(): false;
+    set negative(value: boolean);
+    get negative(): boolean;
+    set positive(value: boolean);
+    get positive(): boolean;
+    constructor(tokens?: RGXTokenCollectionInput, positive?: boolean);
+    abstract negate(): RGXLookaroundToken;
+    abstract reverse(): RGXLookaroundToken;
+}

package/dist/class/lookaround.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXLookaroundToken = void 0;
+const collection_1 = require("../collection");
+const base_1 = require("./base");
+const errors_1 = require("../errors");
+class RGXLookaroundToken extends base_1.RGXClassToken {
+    get isGroup() {
+        return true;
+    }
+    get isRepeatable() {
+        return false;
+    }
+    get rgxGroupWrap() {
+        return false;
+    }
+    set negative(value) {
+        this._negative = value;
+    }
+    get negative() {
+        return this._negative;
+    }
+    set positive(value) {
+        this.negative = !value;
+    }
+    get positive() {
+        return !this.negative;
+    }
+    constructor(tokens = [], positive = true) {
+        super();
+        this._negative = false;
+        this.positive = positive;
+        if (tokens instanceof collection_1.RGXTokenCollection && tokens.mode === 'union')
+            this.tokens = new collection_1.RGXTokenCollection(tokens, 'concat');
+        else
+            this.tokens = new collection_1.RGXTokenCollection(tokens, 'concat');
+    }
+}
+exports.RGXLookaroundToken = RGXLookaroundToken;
+// The createClassGuard function only accepts non-abstract classes, so we 
+// manually define the guard and assertion functions for RGXLookaroundToken here.
+RGXLookaroundToken.check = (value) => value instanceof RGXLookaroundToken;
+RGXLookaroundToken.assert = (value) => {
+    if (!(value instanceof RGXLookaroundToken)) {
+        throw new errors_1.RGXInvalidTokenError("Invalid token type", { type: "custom", values: ["instance of RGXLookaroundToken"] }, value);
+    }
+};

package/dist/class/lookbehind.d.ts

@@ -0,0 +1,12 @@
+import { RGXTokenCollectionInput } from "../collection";
+import { RGXToken } from "../types";
+import { RGXLookaheadToken } from "./lookahead";
+import { RGXLookaroundToken } from "./lookaround";
+export declare class RGXLookbehindToken extends RGXLookaroundToken {
+    static check: (value: unknown) => value is RGXLookbehindToken;
+    static assert: (value: unknown) => asserts value is RGXLookbehindToken;
+    negate(): RGXLookbehindToken;
+    reverse(): RGXLookaheadToken;
+    toRgx(): RGXToken;
+}
+export declare const rgxLookbehind: (tokens?: RGXTokenCollectionInput, positive?: boolean | undefined) => RGXLookbehindToken;

package/dist/class/lookbehind.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxLookbehind = exports.RGXLookbehindToken = void 0;
+const internal_1 = require("../internal");
+const lookahead_1 = require("./lookahead");
+const lookaround_1 = require("./lookaround");
+class RGXLookbehindToken extends lookaround_1.RGXLookaroundToken {
+    negate() {
+        return new RGXLookbehindToken(this.tokens, !this.positive);
+    }
+    reverse() {
+        return new lookahead_1.RGXLookaheadToken(this.tokens, this.positive);
+    }
+    toRgx() {
+        let result = this.tokens.toRgx().source;
+        if (this.positive)
+            result = `(?<=${result})`;
+        else
+            result = `(?<!${result})`;
+        return new RegExp(result);
+    }
+}
+exports.RGXLookbehindToken = RGXLookbehindToken;
+RGXLookbehindToken.check = (0, internal_1.createClassGuardFunction)(RGXLookbehindToken);
+RGXLookbehindToken.assert = (0, internal_1.createAssertClassGuardFunction)(RGXLookbehindToken);
+exports.rgxLookbehind = (0, internal_1.createConstructFunction)(RGXLookbehindToken);

package/dist/class/repeat.js

@@ -30,6 +30,9 @@ class RGXRepeatToken extends base_1.RGXClassToken {
         return this._token;
     }
     set token(value) {
+        if ((0, typeGuards_1.isRGXToken)(value, "class") && !value.isRepeatable) {
+            throw new errors_1.RGXNotSupportedError(`Repeating ${value.constructor.name} tokens`, "The token was manually marked as non-repeatable.");
+        }
         // Make sure we are always working with a grouped token.
         if ((0, typeGuards_1.isRGXGroupedToken)(value))
             this._token = value;

package/dist/class/toRGXClassToken.d.ts

@@ -0,0 +1,3 @@
+import { RGXToken } from "../types";
+import { RGXClassToken } from "./base";
+export declare function toRGXClassToken(token: RGXToken): RGXClassToken;

package/dist/class/toRGXClassToken.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRGXClassToken = toRGXClassToken;
+const base_1 = require("./base");
+const typeGuards_1 = require("../typeGuards");
+const union_1 = require("./union");
+const collection_1 = require("../collection");
+const group_1 = require("./group");
+const wrapper_1 = require("./wrapper");
+function toRGXClassToken(token) {
+    if (base_1.RGXClassToken.check(token))
+        return token;
+    if ((0, typeGuards_1.isRGXArrayToken)(token))
+        return new union_1.RGXClassUnionToken(token);
+    if (collection_1.RGXTokenCollection.check(token) && token.mode === 'union')
+        return new union_1.RGXClassUnionToken(token.tokens);
+    if (collection_1.RGXTokenCollection.check(token) && token.mode === 'concat')
+        return new group_1.RGXGroupToken({ capturing: false }, token);
+    return new wrapper_1.RGXClassWrapperToken(token);
+}

package/dist/class/wrapper.d.ts

@@ -0,0 +1,13 @@
+import { RGXToken } from "../types";
+import { RGXClassToken } from "./base";
+export declare class RGXClassWrapperToken extends RGXClassToken {
+    token: RGXToken;
+    static check: (value: unknown) => value is RGXClassWrapperToken;
+    static assert: (value: unknown) => asserts value is RGXClassWrapperToken;
+    constructor(token: RGXToken);
+    get isGroup(): boolean;
+    get isRepeatable(): boolean;
+    unwrap(): RGXToken;
+    toRgx(): RGXToken;
+}
+export declare const rgxClassWrapper: (token: RGXToken) => RGXClassWrapperToken;

package/dist/class/wrapper.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxClassWrapper = exports.RGXClassWrapperToken = void 0;
+const base_1 = require("./base");
+const typeGuards_1 = require("../typeGuards");
+const internal_1 = require("../internal");
+class RGXClassWrapperToken extends base_1.RGXClassToken {
+    constructor(token) {
+        super();
+        this.token = token;
+    }
+    get isGroup() {
+        return (0, typeGuards_1.isRGXGroupedToken)(this.token);
+    }
+    get isRepeatable() {
+        if ((0, typeGuards_1.isRGXToken)(this.token, 'class'))
+            return this.token.isRepeatable;
+        // Assume any other token is repeatable, since we don't know its implementation.
+        return true;
+    }
+    unwrap() {
+        return this.token;
+    }
+    toRgx() {
+        return this.unwrap();
+    }
+}
+exports.RGXClassWrapperToken = RGXClassWrapperToken;
+RGXClassWrapperToken.check = (0, internal_1.createClassGuardFunction)(RGXClassWrapperToken);
+RGXClassWrapperToken.assert = (0, internal_1.createAssertClassGuardFunction)(RGXClassWrapperToken);
+exports.rgxClassWrapper = (0, internal_1.createConstructFunction)(RGXClassWrapperToken);

package/dist/concat.d.ts

@@ -1,2 +1,2 @@
 import * as t from "./types";
-export declare function rgxConcat(tokens: t.RGXToken[], groupWrap?: boolean): t.ValidRegexString;
+export declare function rgxConcat(tokens: t.RGXToken[], groupWrap?: boolean, currentFlags?: string): t.ValidRegexString;

package/dist/concat.js

@@ -3,6 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.rgxConcat = rgxConcat;
 const resolve_1 = require("./resolve");
 // Wrapper for letting an array of tokens be resolved as a concatenation instead of a union.
-function rgxConcat(tokens, groupWrap = true) {
-    return tokens.map(t => (0, resolve_1.resolveRGXToken)(t, groupWrap)).join('');
+function rgxConcat(tokens, groupWrap = true, currentFlags = '') {
+    return tokens.map(t => (0, resolve_1.resolveRGXToken)(t, groupWrap, true, currentFlags)).join('');
 }

package/dist/errors/base.d.ts

@@ -1,4 +1,4 @@
-export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT';
+export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT';
 export declare class RGXError extends Error {
     _message: string;
     code: RGXErrorCode;

package/dist/errors/index.d.ts

@@ -8,3 +8,4 @@ export * from './invalidIdentifier';
 export * from './outOfBounds';
 export * from './invalidFlagTransformerKey';
 export * from './flagTransformerConflict';
+export * from './notSupported';

package/dist/errors/index.js

@@ -24,3 +24,4 @@ __exportStar(require("./invalidIdentifier"), exports);
 __exportStar(require("./outOfBounds"), exports);
 __exportStar(require("./invalidFlagTransformerKey"), exports);
 __exportStar(require("./flagTransformerConflict"), exports);
+__exportStar(require("./notSupported"), exports);

package/dist/errors/notSupported.d.ts

@@ -0,0 +1,6 @@
+import { RGXError } from "./base";
+export declare class RGXNotSupportedError extends RGXError {
+    functionality: string;
+    constructor(functionality: string, message?: string | null);
+    calcMessage(message: string): string;
+}

package/dist/errors/notSupported.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXNotSupportedError = void 0;
+const base_1 = require("./base");
+class RGXNotSupportedError extends base_1.RGXError {
+    constructor(functionality, message = null) {
+        super(message || "", "NOT_SUPPORTED");
+        this.functionality = functionality;
+        this.name = "RGXNotSupportedError";
+    }
+    calcMessage(message) {
+        const result = `${this.functionality} is not supported.`;
+        if (message)
+            return result + ` Additional info: ${message}`;
+        else
+            return result;
+    }
+}
+exports.RGXNotSupportedError = RGXNotSupportedError;

package/dist/index.js

@@ -37,7 +37,7 @@ __exportStar(require("./flag-transformer"), exports);
 (0, flag_transformer_1.registerCustomFlagTransformers)();
 function rgxa(tokens, flags = '') {
     (0, ExtRegExp_1.assertValidRegexFlags)(flags);
-    const pattern = (0, concat_1.rgxConcat)(tokens);
+    const pattern = (0, concat_1.rgxConcat)(tokens, true, flags);
     return (0, ExtRegExp_1.extRegExp)(pattern, flags);
 }
 function rgx(flags = '') {

package/dist/resolve.d.ts

@@ -1,3 +1,3 @@
 import * as t from "./types";
 export declare function escapeRegex(value: string): t.ValidRegexString;
-export declare function resolveRGXToken(token: t.RGXToken, groupWrap?: boolean, topLevel?: boolean): t.ValidRegexString;
+export declare function resolveRGXToken(token: t.RGXToken, groupWrap?: boolean, topLevel?: boolean, currentFlags?: string): t.ValidRegexString;

package/dist/resolve.js

@@ -41,21 +41,42 @@ const tg = __importStar(require("./typeGuards"));
 function escapeRegex(value) {
     return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function resolveRGXToken(token, groupWrap = true, topLevel = true) {
+function localizableVanillaRegexFlagDiff(prev, next) {
+    // Remove anything other than the "ims" flags from both strings, as
+    // other flags are not localizable (including our custom flags).
+    prev = prev.replaceAll(/[^ims]/g, '');
+    next = next.replaceAll(/[^ims]/g, '');
+    // Format <added flags>-<removed flags>
+    const added = [...new Set(next.split(''))].filter(flag => !prev.includes(flag)).join('');
+    const removed = [...new Set(prev.split(''))].filter(flag => !next.includes(flag)).join('');
+    if (added === '' && removed === '')
+        return '';
+    if (removed === '')
+        return `${added}`;
+    return `${added}-${removed}`;
+}
+function resolveRGXToken(token, groupWrap = true, topLevel = true, currentFlags = '') {
     if (tg.isRGXNoOpToken(token))
         return '';
     if (tg.isRGXLiteralToken(token)) {
-        if (groupWrap)
-            return '(?:' + token.source + ')';
-        else
-            return token.source;
+        const localizableFlagDiff = localizableVanillaRegexFlagDiff(currentFlags, token.flags);
+        currentFlags = token.flags;
+        if (!localizableFlagDiff) {
+            if (groupWrap)
+                return '(?:' + token.source + ')';
+            else
+                return token.source;
+        }
+        else {
+            return `(?${localizableFlagDiff}:${token.source})`;
+        }
     }
     if (tg.isRGXNativeToken(token))
         return escapeRegex(String(token));
     if (tg.isRGXConvertibleToken(token)) {
         // The top-level group-wrapping preference propogates to a direct convertible token, but after that
         // the preference falls back to true whenever a token doesn't explicitly specify a preference.
-        return resolveRGXToken(token.toRgx(), token.rgxGroupWrap ?? (topLevel ? groupWrap : true), false);
+        return resolveRGXToken(token.toRgx(), token.rgxGroupWrap ?? (topLevel ? groupWrap : true), false, currentFlags);
     }
     // Interpret arrays as unions
     if (tg.isRGXArrayToken(token, false)) {
@@ -66,11 +87,11 @@ function resolveRGXToken(token, groupWrap = true, topLevel = true) {
             token = [...(0, class_1.removeRgxUnionDuplicates)(...token)];
             // Don't preserve group wrapping preference for the recursive calls
             if (groupWrap)
-                return '(?:' + token.map(t => resolveRGXToken(t, true, false)).join('|') + ')';
+                return '(?:' + token.map(t => resolveRGXToken(t, true, false, currentFlags)).join('|') + ')';
             else
-                return token.map(t => resolveRGXToken(t, true, false)).join('|');
+                return token.map(t => resolveRGXToken(t, true, false, currentFlags)).join('|');
         }
-        return resolveRGXToken(token[0]);
+        return resolveRGXToken(token[0], true, false, currentFlags);
     }
     // 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 */

package/dist/typeGuards.js

@@ -223,7 +223,7 @@ function assertValidRegexString(value) {
     }
 }
 function isValidVanillaRegexFlags(value) {
-    const patternMatch = /^[gimsuy]*$/.test(value);
+    const patternMatch = /^[gimsuydv]*$/.test(value);
     if (!patternMatch)
         return false;
     // No repeated flags allowed

package/package.json

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