@ptolemy2002/rgx 2.2.0 → 2.3.0

package/README.md

@@ -9,7 +9,8 @@ import { MaybeArray } from "@ptolemy2002/ts-utils";
 type RGXNoOpToken = null | undefined;
 type RGXLiteralToken = RegExp;
 type RGXNativeToken = string | number | boolean | RGXNoOpToken;
-type RGXConvertibleToken = { toRgx: () => MaybeArray<RGXNativeToken | RGXLiteralToken> };
+type RGXConvertibleTokenOutput = MaybeArray<RGXNativeToken | RGXLiteralToken>;
+type RGXConvertibleToken = { toRgx: () => RGXConvertibleTokenOutput };
 type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 
 const validRegexSymbol = Symbol('rgx.ValidRegex');
@@ -34,6 +35,7 @@ type ExpectedTokenType = {
     type: "custom";
     values: string[];
 };
+type RGXTokenCollectionMode = 'union' | 'concat';
 ```
 
 ## Classes
@@ -49,17 +51,24 @@ 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'.
 
+#### Properties
+- `code` (`RGXErrorCode`): The error code associated with the error, which can be used to identify the type of error that occurred.
+
 ### 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. The error code is set to `INVALID_RGX_TOKEN` on instantiation.
 
 #### Constructor
 ```typescript
-constructor(message: string, expected: string | null, got: unknown)
+constructor(message: string, expected: ExpectedTokenType | null, got: unknown)
 ```
 - `message` (`string`): The error message.
 - `expected` (`ExpectedTokenType | null`): Either an object describing the expected token type(s) or `null` if all token types are expected. This is used to generate a human-readable description of what was expected.
 - `got` (`unknown`): The actual value that was received, which failed validation.
 
+#### Properties
+- `expected` (`string`): A human-readable description of the expected token type(s), generated from the `expected` parameter in the constructor. This can be used to provide more informative error messages.
+- `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. The error code is set to `INVALID_REGEX_STRING` on instantiation.
 
@@ -70,6 +79,9 @@ constructor(message: string, got: string)
 - `message` (`string`): The error message.
 - `got` (`string`): The actual string that was received, which failed validation.
 
+#### Properties
+- `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. The error code is set to `INVALID_VANILLA_REGEX_FLAGS` on instantiation.
 
@@ -80,6 +92,30 @@ constructor(message: string, got: string)
 - `message` (`string`): The error message.
 - `got` (`string`): The actual string that was received, which failed validation.
 
+#### Properties
+- `got` (`string`): The actual string that was received, which failed validation.
+
+### RGXTokenCollection
+A class representing a collection of RGX tokens. This is not used internally, but may be useful for users who want to easily manage collections of RGX tokens like an array, but with additional metadata about the collection mode (union or concat).
+
+#### Constructor
+```typescript
+constructor(tokens: RGXToken[] = [], mode: RGXTokenCollectionMode = 'concat')
+```
+- `tokens` (`RGXToken[]`, optional): An array of RGX tokens to be managed by the collection. Defaults to an empty array.
+- `mode` (`RGXTokenCollectionMode`, optional): The mode of the collection, either 'union' or 'concat'. Defaults to 'concat'.
+
+#### Properties
+- `tokens` (`RGXToken[]`): The array of RGX tokens managed by the collection. In almost all cases, use `getTokens()` instead of accessing this property directly, as it will be copied to prevent external mutation.
+- `mode` (`RGXTokenCollectionMode`): The mode of the collection, either 'union' or 'concat'. This determines how the tokens in the collection will be resolved when `toRgx()` is called.
+- `toRgx()` (`() => RGXToken`): A method that resolves the collection to a single RGX token based on the collection mode. In both modes, a string is ultimately returned, but in 'union' mode, the tokens are resolved as alternatives (using the `|` operator), while in 'concat' mode, the tokens are resolved as concatenated together.
+- `getTokens()` (`() => RGXToken[]`): A method that returns a copy of the array of RGX tokens managed by the collection. This is used to prevent external mutation of the internal `tokens` array.
+- `clone()` (`() => RGXTokenCollection`): A method that creates and returns a deep clone of the RGXTokenCollection instance. This is useful for creating a new collection with the same tokens and mode without affecting the original collection.
+- `asConcat()` (`() => RGXTokenCollection`): If this collection is in 'union' mode, this method returns a new RGXTokenCollection instance with the same tokens but in 'concat' mode. If the collection is already in 'concat' mode, it simply returns itself.
+- `asUnion()` (`() => RGXTokenCollection`): If this collection is in 'concat' mode, this method returns a new RGXTokenCollection instance with the same tokens but in 'union' mode. If the collection is already in 'union' mode, it simply returns itself.
+
+Standard array properties and methods like `length`, `push`, `pop`, etc. are implemented to work with the internal `tokens` array, but providing collection instances instead of raw arrays when relevant (e.g., `map` has the third parameter typed as `RGXTokenCollection` instead of `RGXToken[]`).
+
 ## Functions
 The following functions are exported by the library:
 
@@ -359,9 +395,12 @@ As an alternative to using the `rgx` template tag, you can directly call `rgxa`
 - `RegExp`: A `RegExp` object constructed from the resolved tokens and the provided flags.
 
 ## Peer Dependencies
+- `@ptolemy2002/immutability-utils` ^1.2.1
+- `@ptolemy2002/js-utils` ^3.2.2
 - `@ptolemy2002/ts-brand-utils` ^1.0.0
 - `@ptolemy2002/ts-utils` ^3.4.0
 - `is-callable` ^1.2.7
+- `lodash.clonedeep` ^4.5.0
 
 ## Commands
 The following commands exist in the project:

package/dist/collection.d.ts

@@ -0,0 +1,41 @@
+import { RGXConvertibleTokenOutput, RGXToken } from "./types";
+export type RGXTokenCollectionMode = 'union' | 'concat';
+export declare class RGXTokenCollection {
+    mode: RGXTokenCollectionMode;
+    tokens: RGXToken[];
+    constructor(tokens?: RGXToken[], mode?: RGXTokenCollectionMode);
+    toRgx(): RGXConvertibleTokenOutput;
+    getTokens(): RGXToken[];
+    clone(): RGXTokenCollection;
+    asConcat(): RGXTokenCollection;
+    asUnion(): RGXTokenCollection;
+    get length(): number;
+    at(index: number): RGXToken | undefined;
+    find(predicate: (token: RGXToken, index: number, array: RGXToken[]) => boolean): RGXToken | undefined;
+    findIndex(predicate: (token: RGXToken, index: number, array: RGXToken[]) => boolean): number;
+    indexOf(token: RGXToken, fromIndex?: number): number;
+    includes(token: RGXToken, fromIndex?: number): boolean;
+    some(predicate: (token: RGXToken, index: number, array: RGXToken[]) => boolean): boolean;
+    every(predicate: (token: RGXToken, index: number, array: RGXToken[]) => boolean): boolean;
+    forEach(callback: (token: RGXToken, index: number, array: RGXToken[]) => void): void;
+    map(callback: (token: RGXToken, index: number, array: RGXToken[]) => RGXToken): RGXTokenCollection;
+    filter(predicate: (token: RGXToken, index: number, array: RGXToken[]) => boolean): RGXTokenCollection;
+    reduce<T>(callback: (accumulator: T, token: RGXToken, index: number, array: RGXToken[]) => T, initialValue: T): T;
+    reduce(callback: (accumulator: RGXToken, token: RGXToken, index: number, array: RGXToken[]) => RGXToken): RGXToken;
+    flat(depth?: number): RGXTokenCollection;
+    flatMap(callback: (token: RGXToken, index: number, array: RGXToken[]) => RGXToken | RGXToken[]): RGXTokenCollection;
+    slice(start?: number, end?: number): RGXTokenCollection;
+    concat(...others: (RGXToken | RGXTokenCollection)[]): RGXTokenCollection;
+    push(...tokens: RGXToken[]): void;
+    pop(): RGXToken | undefined;
+    shift(): RGXToken | undefined;
+    unshift(...tokens: RGXToken[]): number;
+    splice(start: number, deleteCount?: number, ...items: RGXToken[]): RGXTokenCollection;
+    reverse(): this;
+    sort(compareFn?: (a: RGXToken, b: RGXToken) => number): this;
+    fill(value: RGXToken, start?: number, end?: number): this;
+    [Symbol.iterator](): Iterator<RGXToken>;
+    entries(): IterableIterator<[number, RGXToken]>;
+    keys(): IterableIterator<number>;
+    values(): IterableIterator<RGXToken>;
+}

package/dist/collection.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXTokenCollection = void 0;
+const lodash_clonedeep_1 = __importDefault(require("lodash.clonedeep"));
+const index_1 = require("./index");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+class RGXTokenCollection {
+    constructor(tokens = [], mode = 'concat') {
+        this.tokens = [];
+        this.tokens = (0, lodash_clonedeep_1.default)(tokens);
+        this.mode = mode;
+    }
+    toRgx() {
+        if (this.mode === 'union') {
+            return (0, index_1.resolveRGXToken)(this.tokens.map(index_1.resolveRGXToken));
+        }
+        else {
+            return (0, index_1.rgxConcat)(this.tokens);
+        }
+    }
+    getTokens() {
+        return (0, lodash_clonedeep_1.default)(this.tokens);
+    }
+    clone() {
+        return new RGXTokenCollection(this.tokens, this.mode);
+    }
+    asConcat() {
+        if (this.mode === 'concat')
+            return this;
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            clone.mode = 'concat';
+        });
+    }
+    asUnion() {
+        if (this.mode === 'union')
+            return this;
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            clone.mode = 'union';
+        });
+    }
+    // ------------------ Standard array properties and methods ------------------
+    get length() {
+        return this.tokens.length;
+    }
+    at(index) {
+        return this.tokens[index];
+    }
+    find(predicate) {
+        return this.tokens.find(predicate);
+    }
+    findIndex(predicate) {
+        return this.tokens.findIndex(predicate);
+    }
+    indexOf(token, fromIndex) {
+        return this.tokens.indexOf(token, fromIndex);
+    }
+    includes(token, fromIndex) {
+        return this.tokens.includes(token, fromIndex);
+    }
+    some(predicate) {
+        return this.tokens.some(predicate);
+    }
+    every(predicate) {
+        return this.tokens.every(predicate);
+    }
+    forEach(callback) {
+        this.tokens.forEach(callback);
+    }
+    map(callback) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            clone.tokens = clone.tokens.map(callback);
+        });
+    }
+    filter(predicate) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            clone.tokens = clone.tokens.filter(predicate);
+        });
+    }
+    reduce(callback, ...rest) {
+        if (rest.length > 0) {
+            return this.tokens.reduce(callback, rest[0]);
+        }
+        return this.tokens.reduce(callback);
+    }
+    flat(depth = 1) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            // Fixing TypeScript complaining about possible infinite recursion here.
+            clone.tokens = clone.tokens.flat(depth);
+        });
+    }
+    flatMap(callback) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            // Fixing TypeScript complaining about possible infinite recursion here.
+            clone.tokens = clone.tokens.flatMap(callback);
+        });
+    }
+    slice(start, end) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            clone.tokens = clone.tokens.slice(start, end);
+        });
+    }
+    concat(...others) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            const arrays = others.map(o => o instanceof RGXTokenCollection ? o.tokens : [o]);
+            clone.tokens = clone.tokens.concat(...arrays.flat());
+        });
+    }
+    push(...tokens) {
+        this.tokens.push(...tokens);
+    }
+    pop() {
+        return this.tokens.pop();
+    }
+    shift() {
+        return this.tokens.shift();
+    }
+    unshift(...tokens) {
+        return this.tokens.unshift(...tokens);
+    }
+    splice(start, deleteCount, ...items) {
+        return (0, immutability_utils_1.immutableMut)(this, clone => {
+            const removed = deleteCount === undefined
+                ? this.tokens.splice(start)
+                : this.tokens.splice(start, deleteCount, ...items);
+            clone.tokens = removed;
+        });
+    }
+    reverse() {
+        this.tokens.reverse();
+        return this;
+    }
+    sort(compareFn) {
+        this.tokens.sort(compareFn);
+        return this;
+    }
+    fill(value, start, end) {
+        this.tokens.fill(value, start, end);
+        return this;
+    }
+    [Symbol.iterator]() {
+        return this.tokens[Symbol.iterator]();
+    }
+    entries() {
+        return this.tokens.entries();
+    }
+    keys() {
+        return this.tokens.keys();
+    }
+    values() {
+        return this.tokens.values();
+    }
+}
+exports.RGXTokenCollection = RGXTokenCollection;

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import * as t from "./types";
 export * from "./errors";
 export * from "./types";
 export * from "./typeGuards";
+export * from "./collection";
 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;

package/dist/index.js

@@ -46,6 +46,7 @@ const tg = __importStar(require("./typeGuards"));
 __exportStar(require("./errors"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./typeGuards"), exports);
+__exportStar(require("./collection"), exports);
 function escapeRegex(value) {
     return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/dist/types.d.ts

@@ -3,8 +3,9 @@ import { MaybeArray } from "@ptolemy2002/ts-utils";
 export type RGXNoOpToken = null | undefined;
 export type RGXLiteralToken = RegExp;
 export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
+export type RGXConvertibleTokenOutput = MaybeArray<RGXNativeToken | RGXLiteralToken>;
 export type RGXConvertibleToken = {
-    toRgx: () => MaybeArray<RGXNativeToken | RGXLiteralToken>;
+    toRgx: () => RGXConvertibleTokenOutput;
 };
 export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | RGXTokenType[];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/rgx",
-    "version": "2.2.0",
+    "version": "2.3.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -29,21 +29,27 @@
         "release-major": "bash ./scripts/release.sh major"
     },
     "devDependencies": {
+        "@ptolemy2002/immutability-utils": "^1.2.1",
         "@ptolemy2002/js-utils": "^3.2.2",
         "@ptolemy2002/ts-brand-utils": "^1.0.0",
         "@ptolemy2002/ts-utils": "^3.4.0",
         "@types/is-callable": "^1.1.2",
         "@types/jest": "^29.5.0",
+        "@types/lodash.clonedeep": "^4.5.9",
         "is-callable": "^1.2.7",
         "jest": "^29.5.0",
+        "lodash.clonedeep": "^4.5.0",
         "ts-jest": "^29.1.0",
         "ts-patch": "^3.3.0",
         "tsconfig-paths": "^4.2.0",
         "typescript-transform-paths": "^3.5.3"
     },
     "peerDependencies": {
+        "@ptolemy2002/immutability-utils": "^1.2.1",
+        "@ptolemy2002/js-utils": "^3.2.2",
         "@ptolemy2002/ts-brand-utils": "^1.0.0",
         "@ptolemy2002/ts-utils": "^3.4.0",
-        "is-callable": "^1.2.7"
+        "is-callable": "^1.2.7",
+        "lodash.clonedeep": "^4.5.0"
     }
 }