@ptolemy2002/rgx 4.1.0 → 4.2.0

package/README.md

@@ -34,7 +34,14 @@ type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // ... see source for full definition
 ;
 
-type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'INVALID_IDENTIFIER';
+type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS';
+
+type RangeObject = {
+    min?: number | null;
+    max?: number | null;
+    inclusiveLeft?: boolean;
+    inclusiveRight?: boolean;
+};
 type ExpectedTokenType = {
     type: "tokenType";
     values: RGXTokenTypeFlat[];
@@ -142,6 +149,33 @@ constructor(message: string, got: string)
 #### Methods
 - `toString() => string`: Returns a formatted string indicating the invalid identifier and the reason for failure.
 
+### RGXOutOfBoundsError extends RGXError
+A specific error class for out-of-bounds values. This error is thrown when a numeric value falls outside an expected range. The error code is set to `OUT_OF_BOUNDS` on instantiation.
+
+#### Constructor
+```typescript
+constructor(message: string, got: number, { min, max, inclusiveLeft, inclusiveRight }?: RangeObject)
+```
+- `message` (`string`): The error message.
+- `got` (`number`): The actual numeric value that was received, which fell outside the expected range.
+- `min` (`number | null`, optional): The minimum bound of the range. Defaults to `null` (no minimum).
+- `max` (`number | null`, optional): The maximum bound of the range. Defaults to `null` (no maximum). Setting `min` to a value greater than `max` will adjust `max` to equal `min`, and vice versa.
+- `inclusiveLeft` (`boolean`, optional): Whether the minimum bound is inclusive. Defaults to `true`.
+- `inclusiveRight` (`boolean`, optional): Whether the maximum bound is inclusive. Defaults to `true`.
+
+#### Properties
+- `got` (`number`): The actual numeric value that was received.
+- `min` (`number | null`): The minimum bound of the range. Setting this to a value greater than `max` will adjust `max` to equal `min`.
+- `max` (`number | null`): The maximum bound of the range. Setting this to a value less than `min` will adjust `min` to equal `max`.
+- `inclusiveLeft` (`boolean`): Whether the minimum bound is inclusive.
+- `inclusiveRight` (`boolean`): Whether the maximum bound is inclusive.
+
+#### Methods
+- `failedAtMin() => boolean`: Returns `true` if the `got` value is below the minimum bound (respecting `inclusiveLeft`), otherwise `false`. Returns `false` if `min` is `null`.
+- `failedAtMax() => boolean`: Returns `true` if the `got` value is above the maximum bound (respecting `inclusiveRight`), otherwise `false`. Returns `false` if `max` is `null`.
+- `failedAtAny() => boolean`: Returns `true` if the value failed at either the minimum or maximum bound.
+- `toString() => string`: Returns a formatted string indicating the out-of-bounds value, the expected range, and which bound was violated.
+
 ### RGXTokenCollection
 A class representing a collection of RGX tokens. This class manages collections of RGX tokens like an array, but with additional metadata about the collection mode (union or concat). Since `toRgx()` returns a `RegExp`, instances of this class satisfy the `RGXConvertibleToken` interface and can be used directly as tokens in `rgx`, `rgxa`, and other token-accepting functions.
 
@@ -700,6 +734,81 @@ function rgxClassInit(): void
 
 Initializes internal method patches required for `RGXClassToken` subclass methods (such as `or` and `group`) 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.
 
+### isInRange
+```typescript
+function isInRange(value: number, { min, max, inclusiveLeft, inclusiveRight }?: RangeObject): boolean
+```
+
+Checks if the given numeric value falls within the specified range.
+
+#### Parameters
+  - `value` (`number`): The value to check.
+  - `min` (`number | null`, optional): The minimum bound of the range. Defaults to `null` (no minimum).
+  - `max` (`number | null`, optional): The maximum bound of the range. Defaults to `null` (no maximum).
+  - `inclusiveLeft` (`boolean`, optional): Whether the minimum bound is inclusive. Defaults to `true`.
+  - `inclusiveRight` (`boolean`, optional): Whether the maximum bound is inclusive. Defaults to `true`.
+
+#### Returns
+- `boolean`: `true` if the value is within the specified range, otherwise `false`.
+
+### assertInRange
+```typescript
+function assertInRange(value: number, range: RangeObject, message?: string): void
+```
+
+Asserts that the given numeric value falls within the specified range. If the assertion fails, an `RGXOutOfBoundsError` will be thrown.
+
+#### Parameters
+  - `value` (`number`): The value to assert.
+  - `range` (`RangeObject`): The range to check against.
+  - `message` (`string`, optional): A custom error message. Defaults to `"Value out of bounds"`.
+
+#### Returns
+- `void`: This function does not return a value, but will throw an error if the assertion fails.
+
+### normalizeVanillaRegexFlags
+```typescript
+function normalizeVanillaRegexFlags(flags: string): string
+```
+
+Normalizes a string of vanilla regex flags by removing duplicate flags while preserving order. If any character in the string is not a valid vanilla regex flag (g, i, m, s, u, y), an `RGXInvalidVanillaRegexFlagsError` will be thrown.
+
+#### Parameters
+  - `flags` (`string`): The flags string to normalize.
+
+#### Returns
+- `string`: The normalized flags string with duplicates removed.
+
+### regexWithFlags
+```typescript
+function regexWithFlags(exp: RegExp, flags: string, replace?: boolean): RegExp
+```
+
+Creates a new `RegExp` from an existing one with additional or replaced flags. When `replace` is `false` (the default), the provided flags are merged with the existing flags and normalized (duplicates removed). When `replace` is `true`, the existing flags are discarded and only the provided flags are used. The provided flags are validated as valid vanilla regex flags via `assertValidVanillaRegexFlags`.
+
+#### Parameters
+  - `exp` (`RegExp`): The source regular expression.
+  - `flags` (`string`): The flags to add or replace with. Must be valid vanilla regex flags, or an `RGXInvalidVanillaRegexFlagsError` will be thrown.
+  - `replace` (`boolean`, optional): Whether to replace the existing flags entirely instead of merging. Defaults to `false`.
+
+#### Returns
+- `RegExp`: A new `RegExp` with the same source pattern and the resulting flags.
+
+### regexMatchAtPosition
+```typescript
+function regexMatchAtPosition(regex: RegExp, str: string, position: number): boolean
+```
+
+Tests whether the given regular expression matches at a specific position in the string. This is done by creating a sticky (`y` flag) copy of the regex and setting its `lastIndex` to the desired position. The position must be within the bounds of the string (>= 0 and < string length), or an `RGXOutOfBoundsError` will be thrown.
+
+#### Parameters
+  - `regex` (`RegExp`): The regular expression to test.
+  - `str` (`string`): The string to test against.
+  - `position` (`number`): The zero-based index in the string at which to test the match. Must be >= 0 and < `str.length`.
+
+#### Returns
+- `boolean`: `true` if the regex matches at the specified position, otherwise `false`.
+
 ## Peer Dependencies
 - `@ptolemy2002/immutability-utils` ^2.0.0
 - `@ptolemy2002/js-utils` ^3.2.2

package/dist/errors/base.d.ts

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

package/dist/errors/index.d.ts

@@ -4,3 +4,4 @@ export * from './invalidRegexString';
 export * from './invalidVanillaRegexFlags';
 export * from './notImplemented';
 export * from './invalidIdentifier';
+export * from './outOfBounds';

package/dist/errors/index.js

@@ -20,3 +20,4 @@ __exportStar(require("./invalidRegexString"), exports);
 __exportStar(require("./invalidVanillaRegexFlags"), exports);
 __exportStar(require("./notImplemented"), exports);
 __exportStar(require("./invalidIdentifier"), exports);
+__exportStar(require("./outOfBounds"), exports);

package/dist/errors/outOfBounds.d.ts

@@ -0,0 +1,20 @@
+import { RGXError } from "./base";
+import { RangeObject } from "../types";
+export declare class RGXOutOfBoundsError extends RGXError {
+    got: number;
+    _min: number | null;
+    _max: number | null;
+    inclusiveLeft: boolean;
+    inclusiveRight: boolean;
+    get min(): number | null;
+    set min(value: number | null);
+    get max(): number | null;
+    set max(value: number | null);
+    constructor(message: string, got: number, { min, max, inclusiveLeft, inclusiveRight }?: RangeObject);
+    failedAtMin(): boolean;
+    failedAtMax(): boolean;
+    failedAtAny(): boolean;
+    toString(): string;
+}
+export declare function isInRange(value: number, { min, max, inclusiveLeft, inclusiveRight }?: RangeObject): boolean;
+export declare function assertInRange(value: number, range: RangeObject, message?: string): void;

package/dist/errors/outOfBounds.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXOutOfBoundsError = void 0;
+exports.isInRange = isInRange;
+exports.assertInRange = assertInRange;
+const base_1 = require("./base");
+class RGXOutOfBoundsError extends base_1.RGXError {
+    get min() {
+        return this._min;
+    }
+    set min(value) {
+        this._min = value;
+        if (this._max !== null && value !== null && value > this._max) {
+            this._max = value;
+        }
+    }
+    get max() {
+        return this._max;
+    }
+    set max(value) {
+        this._max = value;
+        if (this._min !== null && value !== null && value < this._min) {
+            this._min = value;
+        }
+    }
+    constructor(message, got, { min = null, max = null, inclusiveLeft = true, inclusiveRight = true } = {}) {
+        super(message, 'OUT_OF_BOUNDS');
+        this.name = 'RGXOutOfBoundsError';
+        this.got = got;
+        this.min = min;
+        this.max = max;
+        this.inclusiveLeft = inclusiveLeft;
+        this.inclusiveRight = inclusiveRight;
+    }
+    failedAtMin() {
+        return this.min !== null && (this.inclusiveLeft ? this.got < this.min : this.got <= this.min);
+    }
+    failedAtMax() {
+        return this.max !== null && (this.inclusiveRight ? this.got > this.max : this.got >= this.max);
+    }
+    failedAtAny() {
+        return this.failedAtMin() || this.failedAtMax();
+    }
+    toString() {
+        const rangeParts = [];
+        if (this.min !== null) {
+            if (this.inclusiveLeft)
+                rangeParts.push(`>= ${this.min}`);
+            else
+                rangeParts.push(`> ${this.min}`);
+        }
+        if (this.max !== null) {
+            if (this.inclusiveRight)
+                rangeParts.push(`<= ${this.max}`);
+            else
+                rangeParts.push(`< ${this.max}`);
+        }
+        const rangeStr = rangeParts.join(" and ");
+        // Determine which one was failed
+        if (!this.failedAtAny()) {
+            return `${this.name}: ${this.message}; Got: [${this.got}]; Expected: [${rangeStr}]`;
+        }
+        else if (this.failedAtMin()) {
+            let thirdPart;
+            if (!this.inclusiveLeft && this.got === this.min)
+                thirdPart = `${this.got} == ${this.min}`;
+            else
+                thirdPart = `${this.got} < ${this.min}`;
+            return `${this.name}: ${this.message}; Got: [${this.got}]; Expected: [${rangeStr}]; ${thirdPart}`;
+        }
+        else {
+            let thirdPart;
+            if (!this.inclusiveRight && this.got === this.max)
+                thirdPart = `${this.got} == ${this.max}`;
+            else
+                thirdPart = `${this.got} > ${this.max}`;
+            return `${this.name}: ${this.message}; Got: [${this.got}]; Expected: [${rangeStr}]; ${thirdPart}`;
+        }
+    }
+}
+exports.RGXOutOfBoundsError = RGXOutOfBoundsError;
+function isInRange(value, { min = null, max = null, inclusiveLeft = true, inclusiveRight = true } = {}) {
+    if (min !== null) {
+        if (inclusiveLeft) {
+            if (value < min)
+                return false;
+        }
+        else {
+            if (value <= min)
+                return false;
+        }
+    }
+    if (max !== null) {
+        if (inclusiveRight) {
+            if (value > max)
+                return false;
+        }
+        else {
+            if (value >= max)
+                return false;
+        }
+    }
+    return true;
+}
+function assertInRange(value, range, message = "Value out of bounds") {
+    if (!isInRange(value, range)) {
+        throw new RGXOutOfBoundsError(message, value, range);
+    }
+}

package/dist/index.d.ts

@@ -6,5 +6,6 @@ export * from "./collection";
 export * from "./class";
 export * from "./resolve";
 export * from "./concat";
+export * from "./utils";
 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

@@ -49,6 +49,7 @@ __exportStar(require("./collection"), exports);
 __exportStar(require("./class"), exports);
 __exportStar(require("./resolve"), exports);
 __exportStar(require("./concat"), exports);
+__exportStar(require("./utils"), exports);
 // Call this for certain class methods to work correctly
 (0, class_1.rgxClassInit)();
 function rgxa(tokens, flags = '') {

package/dist/types.d.ts

@@ -15,6 +15,12 @@ export type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenCons
 export type RGXTokenFromType<T extends RGXTokenTypeGuardInput> = T extends null ? RGXToken : T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? RGXLiteralToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends 'class' ? RGXClassToken : T extends 'array' ? RGXToken[] : T extends RGXTokenTypeGuardInput[] ? {
     [K in keyof T]: T[K] extends RGXTokenTypeGuardInput ? RGXTokenFromType<T[K]> : never;
 } : T extends RGXClassTokenConstructor ? InstanceType<T> : never;
+export type RangeObject = {
+    min?: number | null;
+    max?: number | null;
+    inclusiveLeft?: boolean;
+    inclusiveRight?: boolean;
+};
 export declare const validRegexSymbol: unique symbol;
 export type ValidRegexBrandSymbol = typeof validRegexSymbol;
 export type ValidRegexString = Branded<string, [ValidRegexBrandSymbol]>;

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./regexMatchAtPosition";
+export * from "./regexWithFlags";
+export * from "./normalizeRegexFlags";

package/dist/utils/index.js

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

package/dist/utils/normalizeRegexFlags.d.ts

@@ -0,0 +1 @@
+export declare function normalizeVanillaRegexFlags(flags: string): string;

package/dist/utils/normalizeRegexFlags.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeVanillaRegexFlags = normalizeVanillaRegexFlags;
+const errors_1 = require("../errors");
+function normalizeVanillaRegexFlags(flags) {
+    const validFlags = ['g', 'i', 'm', 's', 'u', 'y'];
+    const seenFlags = new Set();
+    let normalizedFlags = '';
+    for (const flag of flags) {
+        if (!validFlags.includes(flag)) {
+            throw new errors_1.RGXInvalidVanillaRegexFlagsError(`[${flag}] is not valid.`, flags);
+        }
+        if (!seenFlags.has(flag)) {
+            seenFlags.add(flag);
+            normalizedFlags += flag;
+        }
+    }
+    return normalizedFlags;
+}

package/dist/utils/regexMatchAtPosition.d.ts

@@ -0,0 +1 @@
+export declare function regexMatchAtPosition(regex: RegExp, str: string, position: number): boolean;

package/dist/utils/regexMatchAtPosition.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.regexMatchAtPosition = regexMatchAtPosition;
+const outOfBounds_1 = require("../errors/outOfBounds");
+const regexWithFlags_1 = require("./regexWithFlags");
+function regexMatchAtPosition(regex, str, position) {
+    /*
+        The y flag means sticky mode, which means the next match must start at
+        lastIndex. By setting lastIndex to the position we want to check, we can test
+        if the regex matches at that position.
+    */
+    (0, outOfBounds_1.assertInRange)(position, { min: 0, max: str.length, inclusiveRight: false }, 'String index out of bounds');
+    const stickyRegex = (0, regexWithFlags_1.regexWithFlags)(regex, "y");
+    stickyRegex.lastIndex = position;
+    return stickyRegex.test(str);
+}

package/dist/utils/regexWithFlags.d.ts

@@ -0,0 +1 @@
+export declare function regexWithFlags(exp: RegExp, flags: string, replace?: boolean): RegExp;

package/dist/utils/regexWithFlags.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.regexWithFlags = regexWithFlags;
+const typeGuards_1 = require("../typeGuards");
+const normalizeRegexFlags_1 = require("./normalizeRegexFlags");
+function regexWithFlags(exp, flags, replace = false) {
+    (0, typeGuards_1.assertValidVanillaRegexFlags)(flags);
+    if (replace)
+        return new RegExp(exp.source, flags);
+    const existingFlags = exp.flags;
+    const newFlags = existingFlags + flags;
+    return new RegExp(exp.source, (0, normalizeRegexFlags_1.normalizeVanillaRegexFlags)(newFlags));
+}

package/package.json

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