@ptolemy2002/rgx 13.9.0 → 13.11.0

package/README.md

@@ -41,6 +41,9 @@ Because there is so much to document, it has been broken up into multiple files.
       - [lookahead](./docs/class/token/lookaround/lookahead.md) - The `RGXLookaheadToken` class, which represents a lookahead assertion in a regular expression.
       - [lookbehind](./docs/class/token/lookaround/lookbehind.md) - The `RGXLookbehindToken` class, which represents a lookbehind assertion in a regular expression.
 
+## Pending Breaking Changes
+Breaking changes that would improve the library, but are not worth a major release by themselves, are tracked in [PENDING_BREAKING_CHANGES.md](./PENDING_BREAKING_CHANGES.md) along with the non-breaking workarounds currently in place for them. They will be made in the next major release.
+
 ## Peer Dependencies
 N/A
 

package/dist/class/base.d.ts

@@ -1,4 +1,4 @@
-import { RGXConvertibleToken, RGXJSONClassToken, RGXJSONValue, RGXToken, ValidRegexFlags, ValidRegexString } from "../types";
+import { RGXConvertibleToken, RGXJSONClassToken, RGXJSONObjectToken, RGXJSONValue, RGXToken, ValidRegexFlags, ValidRegexString } from "../types";
 import { RGXTokenCollectionInput } from "../collection";
 import { ResolveRGXTokenOptions } from "../resolve";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
@@ -11,7 +11,7 @@ import type { RGXExclusionToken } from "./exclusion";
 export declare abstract class RGXClassToken implements RGXConvertibleToken {
     abstract toRgx(): RGXToken;
     abstract clone(depth?: CloneDepth): ThisType<this>;
-    toJSON(): RGXJSONClassToken;
+    toJSON(): RGXJSONObjectToken;
     static validateJSONArgs(args: RGXJSONValue[]): boolean | string;
     static fromJSON(json: RGXJSONClassToken): RGXClassToken;
     rgxAcceptInsertion(tokens: RGXToken[], flags: ValidRegexFlags): string | boolean;

package/dist/class/base.js

@@ -1,21 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RGXClassToken = void 0;
+const types_1 = require("../types");
 const errors_1 = require("../errors");
 const resolve_1 = require("../resolve");
 class RGXClassToken {
-    // Subclasses are expected to override toJSON and both static methods below. They are not marked abstract
-    // (so existing subclasses keep compiling), so they throw RGXNotImplementedError by default.
-    // toJSON must return a JSON class token whose args, when given to the registered constructor for the
-    // class, reconstruct an equivalent token.
+    // Subclasses that want lossless JSON serialization (i.e. to be part of the JSON class registry) should override
+    // toJSON and both static methods below. They are not marked abstract, since subclasses that are not registered
+    // remain serializable through the toJSON fallback. The static methods throw RGXNotImplementedError by default.
+    // When overridden, toJSON must return a JSON class token whose args, when given to the registered constructor for the
+    // class, reconstruct an equivalent token. By default, it falls back to resolving the token into a
+    // JSON literal token, the same way plain convertible tokens are handled by rgxTokenToJSON. This is lossy.
     toJSON() {
-        throw new errors_1.RGXNotImplementedError(`${this.constructor.name}.toJSON()`, 'subclasses must override this method.');
+        return { [types_1.RGX_JSON_FLAG]: true, source: (0, resolve_1.resolveRGXToken)(this, { groupWrap: false }) };
     }
     static validateJSONArgs(args) {
-        throw new errors_1.RGXNotImplementedError('RGXClassToken.validateJSONArgs(args)', 'subclasses must override this static method.');
+        throw new errors_1.RGXNotImplementedError('RGXClassToken.validateJSONArgs(args)', 'subclasses must override this static method in order to be registered in the JSON class registry.');
     }
     static fromJSON(json) {
-        throw new errors_1.RGXNotImplementedError('RGXClassToken.fromJSON(json)', 'subclasses must override this static method.');
+        throw new errors_1.RGXNotImplementedError('RGXClassToken.fromJSON(json)', 'subclasses must override this static method in order to be registered in the JSON class registry.');
     }
     rgxAcceptInsertion(tokens, flags) {
         return true;

package/dist/json.js

@@ -59,6 +59,22 @@ const collection_1 = require("./collection");
 const ExtRegExp_1 = require("./ExtRegExp");
 const resolve_1 = require("./resolve");
 const rgxJSONClasses = {};
+// Maps args arrays that have already passed the validator of the class they are mapped to and are currently
+// being constructed. rgxJSONClassArgs uses this to skip validating them a second time.
+const validatedRGXJSONClassArgs = new WeakMap();
+function constructValidatedRGXJSONClass(name, raw, args) {
+    validatedRGXJSONClassArgs.set(args, name);
+    try {
+        return raw.construct(args);
+    }
+    finally {
+        validatedRGXJSONClassArgs.delete(args);
+    }
+}
+function getRGXJSONClassRecord(name) {
+    assertHasRGXJSONClass(name);
+    return rgxJSONClasses[name];
+}
 // ------------------ Registry ------------------
 function listRGXJSONClasses() {
     return Object.keys(rgxJSONClasses);
@@ -78,8 +94,17 @@ function assertNotHasRGXJSONClass(name) {
 }
 function registerRGXJSONClass(name, entry) {
     assertNotHasRGXJSONClass(name);
-    rgxJSONClasses[name] = entry;
-    return entry;
+    // Copied so that later changes to the given entry cannot bypass the guard.
+    const raw = { validateArgs: entry.validateArgs, construct: entry.construct };
+    const guarded = Object.freeze({
+        validateArgs: raw.validateArgs,
+        construct: (args) => {
+            assertValidRGXJSONClassArgs(name, args);
+            return constructValidatedRGXJSONClass(name, raw, args);
+        }
+    });
+    rgxJSONClasses[name] = { raw, guarded };
+    return guarded;
 }
 function registerRGXJSONClassToken(name, constructor) {
     return registerRGXJSONClass(name, {
@@ -88,15 +113,14 @@ function registerRGXJSONClassToken(name, constructor) {
     });
 }
 function getRGXJSONClass(name) {
-    assertHasRGXJSONClass(name);
-    return rgxJSONClasses[name];
+    return getRGXJSONClassRecord(name).guarded;
 }
 function unregisterRGXJSONClass(name) {
     assertHasRGXJSONClass(name);
     delete rgxJSONClasses[name];
 }
 function validateRGXJSONClassArgs(name, args) {
-    const result = getRGXJSONClass(name).validateArgs(args);
+    const result = getRGXJSONClassRecord(name).raw.validateArgs(args);
     if (result === true)
         return true;
     if (result === false)
@@ -129,6 +153,9 @@ function assertRGXJSONClassTokenOf(json, name) {
 function rgxJSONClassArgs(json, name, validate) {
     assertRGXJSONClassTokenOf(json, name);
     const args = json.args ?? [];
+    // The registry already validated these args against this class before constructing.
+    if (validatedRGXJSONClassArgs.get(args) === name)
+        return args;
     const result = validate(args);
     if (result === true)
         return args;
@@ -153,13 +180,14 @@ function rgxTokenToJSON(token, { resolveConvertible = true } = {}) {
         tg.assertRGXJSONObjectToken(token);
         return token;
     }
-    if (class_1.RGXClassToken.check(token))
+    if (class_1.RGXClassToken.check(token) && token.toJSON !== class_1.RGXClassToken.prototype.toJSON)
         return token.toJSON();
     if (collection_1.RGXTokenCollection.check(token))
         return (0, class_1.toRGXClassToken)(token).toJSON();
+    // Class tokens without a custom toJSON fall through to here, since they are also convertible tokens.
     if (tg.isRGXConvertibleToken(token, false)) {
         if (!resolveConvertible) {
-            throw new e.RGXNotJSONSerializableError("Cannot convert token to JSON", token, "Convertible tokens that are not class tokens can only be converted by resolving them, but resolveConvertible is false.");
+            throw new e.RGXNotJSONSerializableError("Cannot convert token to JSON", token, "Convertible tokens that are not class tokens with a custom toJSON method can only be converted by resolving them, but resolveConvertible is false.");
         }
         return createRGXJSONLiteralToken((0, resolve_1.resolveRGXToken)(token, { groupWrap: false }));
     }
@@ -178,9 +206,8 @@ function rgxTokenFromJSON(json) {
         return new ExtRegExp_1.ExtRegExp(json.source, json.flags ?? '');
     }
     if (tg.isRGXJSONClassToken(json, false)) {
-        const args = json.args ?? [];
-        assertValidRGXJSONClassArgs(json.class, args);
-        return getRGXJSONClass(json.class).construct(args);
+        // The guarded construct validates the args before constructing.
+        return getRGXJSONClass(json.class).construct(json.args ?? []);
     }
     if (Array.isArray(json))
         return json.map(item => rgxTokenFromJSON(item));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/rgx",
-    "version": "13.9.0",
+    "version": "13.11.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -43,13 +43,14 @@
         "ts-jest": "^29.1.0",
         "ts-patch": "^3.3.0",
         "tsconfig-paths": "^4.2.0",
+        "typescript": "^5.9.3",
         "typescript-transform-paths": "^3.5.3"
     },
     "dependencies": {
         "@ptolemy2002/immutability-utils": "^2.0.0",
         "@ptolemy2002/js-utils": "^3.2.2",
         "@ptolemy2002/ts-brand-utils": "^1.0.0",
-        "@ptolemy2002/ts-utils": "^3.4.0",
+        "@ptolemy2002/ts-utils": "^4.0.0",
         "is-callable": "^1.2.7",
         "lodash.clonedeep": "^4.5.0"
     }