@ptolemy2002/rgx 13.8.0 → 13.9.0

package/dist/typeGuards.js

@@ -46,6 +46,18 @@ exports.isRGXConvertibleToken = isRGXConvertibleToken;
 exports.assertRGXConvertibleToken = assertRGXConvertibleToken;
 exports.isRGXArrayToken = isRGXArrayToken;
 exports.assertRGXArrayToken = assertRGXArrayToken;
+exports.isRGXJSONValue = isRGXJSONValue;
+exports.assertRGXJSONValue = assertRGXJSONValue;
+exports.isRGXJSONNativeToken = isRGXJSONNativeToken;
+exports.assertRGXJSONNativeToken = assertRGXJSONNativeToken;
+exports.isRGXJSONLiteralToken = isRGXJSONLiteralToken;
+exports.assertRGXJSONLiteralToken = assertRGXJSONLiteralToken;
+exports.isRGXJSONClassToken = isRGXJSONClassToken;
+exports.assertRGXJSONClassToken = assertRGXJSONClassToken;
+exports.isRGXJSONObjectToken = isRGXJSONObjectToken;
+exports.assertRGXJSONObjectToken = assertRGXJSONObjectToken;
+exports.isRGXJSONToken = isRGXJSONToken;
+exports.assertRGXJSONToken = assertRGXJSONToken;
 exports.rgxTokenTypeFlat = rgxTokenTypeFlat;
 exports.rgxTokenType = rgxTokenType;
 exports.rgxTokenFromType = rgxTokenFromType;
@@ -70,12 +82,22 @@ exports.castValidRegexLocalizableFlagDiff = castValidRegexLocalizableFlagDiff;
 exports.isValidRegexLocalizableFlags = isValidRegexLocalizableFlags;
 exports.assertValidRegexLocalizableFlags = assertValidRegexLocalizableFlags;
 exports.castValidRegexLocalizableFlags = castValidRegexLocalizableFlags;
+const t = __importStar(require("./types"));
 const e = __importStar(require("./errors"));
 const is_callable_1 = __importDefault(require("is-callable"));
 const internal_1 = require("./internal");
 const class_1 = require("./class");
 const ExtRegExp_1 = require("./ExtRegExp");
 const collection_1 = require("./collection");
+const json_1 = require("./json");
+const createRegex_1 = require("./utils/createRegex");
+const ExtRegExp_2 = require("./ExtRegExp");
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
 function isRGXNoOpToken(value) {
     return value === null || value === undefined;
 }
@@ -100,7 +122,7 @@ function assertRGXNativeToken(value) {
         throw new e.RGXInvalidTokenError("Invalid native token", { type: "tokenType", values: ['native'] }, value);
     }
 }
-function isRGXConvertibleToken(value, returnCheck = true) {
+function isRGXConvertibleToken(value, returnCheck = true, acceptJSON = true) {
     if (typeof value === 'object' && value !== null && 'toRgx' in value) {
         // The rgxGroupWrap, interpolate, rgxIsRepeatable, and rgxIsGroup properties are optional, but if they exist they must be booleans.
         if ('rgxGroupWrap' in value && typeof value.rgxGroupWrap !== 'boolean')
@@ -126,29 +148,129 @@ function isRGXConvertibleToken(value, returnCheck = true) {
                 return true;
             const rv = value.toRgx();
             return isRGXNativeToken(rv) || isRGXLiteralToken(rv) ||
-                isRGXNoOpToken(rv) || isRGXArrayToken(rv) ||
-                isRGXConvertibleToken(rv);
+                isRGXNoOpToken(rv) || isRGXArrayToken(rv, true, acceptJSON) ||
+                (acceptJSON && isRGXJSONObjectToken(rv)) ||
+                isRGXConvertibleToken(rv, true, acceptJSON);
         }
         return false;
     }
     return false;
 }
-function assertRGXConvertibleToken(value, returnCheck = true) {
-    if (!isRGXConvertibleToken(value, returnCheck)) {
+function assertRGXConvertibleToken(value, returnCheck = true, acceptJSON = true) {
+    if (!isRGXConvertibleToken(value, returnCheck, acceptJSON)) {
         throw new e.RGXInvalidTokenError(`Invalid convertible token`, { type: "tokenType", values: ['convertible'] }, value);
     }
 }
-function isRGXArrayToken(value, contentCheck = true) {
+function isRGXArrayToken(value, contentCheck = true, acceptJSON = true) {
     return Array.isArray(value) && (!contentCheck || value.every(item => isRGXNoOpToken(item) || isRGXLiteralToken(item) ||
         isRGXNativeToken(item) ||
-        isRGXConvertibleToken(item) || isRGXArrayToken(item)));
+        (acceptJSON && isRGXJSONObjectToken(item)) ||
+        isRGXConvertibleToken(item, true, acceptJSON) || isRGXArrayToken(item, true, acceptJSON)));
 }
-function assertRGXArrayToken(value, contentCheck = true) {
-    if (!isRGXArrayToken(value, contentCheck)) {
+function assertRGXArrayToken(value, contentCheck = true, acceptJSON = true) {
+    if (!isRGXArrayToken(value, contentCheck, acceptJSON)) {
         throw new e.RGXInvalidTokenError("Invalid array token", { type: "tokenType", values: ['array'] }, value);
     }
 }
-function rgxTokenTypeFlat(value, recognizeClass = true) {
+function isRGXJSONValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(item => isRGXJSONValue(item));
+    // undefined values are dropped by JSON.stringify, so they are allowed inside objects.
+    if (isPlainObject(value))
+        return Object.values(value).every(item => item === undefined || isRGXJSONValue(item));
+    return false;
+}
+function assertRGXJSONValue(value) {
+    if (!isRGXJSONValue(value)) {
+        throw new e.RGXInvalidJSONTokenError("Invalid JSON value", { type: "custom", values: ["null", "string", "finite number", "boolean", "array of JSON values", "plain object of JSON values"] }, value);
+    }
+}
+function isRGXJSONNativeToken(value) {
+    return value === null || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
+}
+function assertRGXJSONNativeToken(value) {
+    if (!isRGXJSONNativeToken(value)) {
+        throw new e.RGXInvalidJSONTokenError("Invalid JSON native token", { type: "custom", values: ["string", "finite number", "boolean", "null"] }, value);
+    }
+}
+function hasRGXJSONFlag(value) {
+    return isPlainObject(value) && value[t.RGX_JSON_FLAG] === true;
+}
+function isRGXJSONLiteralToken(value, contentCheck = true) {
+    if (!hasRGXJSONFlag(value))
+        return false;
+    if (typeof value.source !== 'string' || 'class' in value)
+        return false;
+    if ('flags' in value && value.flags !== undefined && typeof value.flags !== 'string')
+        return false;
+    if (!contentCheck)
+        return true;
+    const flags = value.flags ?? '';
+    if (!(0, ExtRegExp_2.isValidRegexFlags)(flags))
+        return false;
+    try {
+        (0, createRegex_1.createRegex)(value.source, (0, ExtRegExp_2.extractVanillaRegexFlags)(flags));
+        return true;
+    }
+    catch (err) {
+        if (err instanceof e.RGXInvalidRegexStringError)
+            return false;
+        // This is ignored because I don't know what kind of
+        // unexpected errors might happen.
+        /* istanbul ignore next */
+        throw err;
+    }
+}
+function assertRGXJSONLiteralToken(value, contentCheck = true) {
+    if (!isRGXJSONLiteralToken(value, contentCheck)) {
+        throw new e.RGXInvalidJSONTokenError("Invalid JSON literal token", { type: "custom", values: ["object with $rgx set to true, a valid regex source string, and optional valid flags"] }, value);
+    }
+}
+function isRGXJSONClassToken(value, registryCheck = true) {
+    if (!hasRGXJSONFlag(value))
+        return false;
+    if (typeof value.class !== 'string' || 'source' in value)
+        return false;
+    if ('args' in value && value.args !== undefined && !(Array.isArray(value.args) && isRGXJSONValue(value.args)))
+        return false;
+    if (!registryCheck)
+        return true;
+    if (!(0, json_1.hasRGXJSONClass)(value.class))
+        return false;
+    return (0, json_1.validateRGXJSONClassArgs)(value.class, value.args ?? []) === true;
+}
+function assertRGXJSONClassToken(value, registryCheck = true) {
+    if (!isRGXJSONClassToken(value, registryCheck)) {
+        throw new e.RGXInvalidJSONTokenError("Invalid JSON class token", { type: "custom", values: ["object with $rgx set to true, a registered class name, and optional args that pass the class' validator"] }, value);
+    }
+}
+function isRGXJSONObjectToken(value, contentCheck = true) {
+    return isRGXJSONLiteralToken(value, contentCheck) || isRGXJSONClassToken(value, contentCheck);
+}
+function assertRGXJSONObjectToken(value, contentCheck = true) {
+    if (!isRGXJSONObjectToken(value, contentCheck)) {
+        throw new e.RGXInvalidJSONTokenError("Invalid JSON object token", { type: "custom", values: ["JSON literal token", "JSON class token"] }, value);
+    }
+}
+function isRGXJSONToken(value, contentCheck = true) {
+    if (isRGXJSONNativeToken(value))
+        return true;
+    if (isRGXJSONObjectToken(value, contentCheck))
+        return true;
+    if (Array.isArray(value))
+        return !contentCheck || value.every(item => isRGXJSONToken(item, contentCheck));
+    return false;
+}
+function assertRGXJSONToken(value, contentCheck = true) {
+    if (!isRGXJSONToken(value, contentCheck)) {
+        throw new e.RGXInvalidJSONTokenError("Invalid JSON token", { type: "tokenType", values: ["json"] }, value);
+    }
+}
+function rgxTokenTypeFlat(value, recognizeClass = true, acceptJSON = true) {
     if (isRGXNoOpToken(value))
         return 'no-op';
     if (isRGXLiteralToken(value))
@@ -158,18 +280,21 @@ function rgxTokenTypeFlat(value, recognizeClass = true) {
     // We have to check class before convertible because class tokens are also convertible.
     if (recognizeClass && class_1.RGXClassToken.check(value))
         return 'class';
-    if (isRGXConvertibleToken(value))
+    // JSON object tokens are checked before convertible tokens, since the flag signals explicit intent.
+    if (acceptJSON && isRGXJSONObjectToken(value))
+        return 'json';
+    if (isRGXConvertibleToken(value, true, acceptJSON))
         return 'convertible';
-    if (isRGXArrayToken(value))
+    if (isRGXArrayToken(value, true, acceptJSON))
         return 'array';
     throw new e.RGXInvalidTokenError("Invalid RGX token", null, value);
 }
-function rgxTokenType(value, recognizeClass = true) {
-    const flatType = rgxTokenTypeFlat(value, recognizeClass);
+function rgxTokenType(value, recognizeClass = true, acceptJSON = true) {
+    const flatType = rgxTokenTypeFlat(value, recognizeClass, acceptJSON);
     if (flatType !== 'array')
         return flatType;
     else
-        return value.map(item => rgxTokenType(item, recognizeClass));
+        return value.map(item => rgxTokenType(item, recognizeClass, acceptJSON));
 }
 function rgxTokenFromType(type, value) {
     // Ignoring this line because the function is entirely a TypeScript utility that doesn't need to be tested at runtime.
@@ -194,9 +319,12 @@ function rgxTokenTypeGuardInputToFlat(type) {
         return null;
     return type;
 }
-function isRGXToken(value, type = null, matchLength = true) {
-    if ((0, internal_1.isConstructor)(type))
-        return value instanceof type;
+function isRGXToken(value, type = null, matchLength = true, acceptJSON = true) {
+    if ((0, internal_1.isConstructor)(type)) {
+        if (value instanceof type)
+            return true;
+        return acceptJSON && isRGXJSONClassToken(value) && (0, json_1.rgxTokenFromJSON)(value) instanceof type;
+    }
     function typeMatches(s) {
         return type === null || type === s;
     }
@@ -204,50 +332,69 @@ function isRGXToken(value, type = null, matchLength = true) {
         return true;
     if (typeMatches('literal') && isRGXLiteralToken(value))
         return true;
+    if (typeMatches('literal') && acceptJSON && isRGXJSONLiteralToken(value))
+        return true;
     if (typeMatches('native') && isRGXNativeToken(value))
         return true;
     // We have to check class before convertible because class tokens are also convertible.
     if (typeMatches('class') && class_1.RGXClassToken.check(value))
         return true;
-    if (typeMatches('convertible') && isRGXConvertibleToken(value))
+    if (typeMatches('class') && acceptJSON && isRGXJSONClassToken(value))
         return true;
+    if (typeMatches('convertible') && isRGXConvertibleToken(value, true, acceptJSON))
+        return true;
+    // JSON class tokens become class tokens (which are convertible) when converted.
+    if (typeMatches('convertible') && acceptJSON && isRGXJSONClassToken(value))
+        return true;
+    // The 'json' type is explicit, so it ignores acceptJSON.
+    if (type === 'json' && isRGXJSONToken(value))
+        return true;
+    if (type === 'repeatable' && isRGXJSONObjectToken(value)) {
+        if (!acceptJSON)
+            return false;
+        // Converting a JSON token yields a literal or class token, so we can check that instead.
+        return isRGXToken((0, json_1.rgxTokenFromJSON)(value), 'repeatable', true, false);
+    }
     // Non-covertible tokens are repeatable by default. Convertible tokens are only non-repeatable if they have the rgxIsRepeatable property set to false.
     if (type === 'repeatable' && !isRGXConvertibleToken(value, false))
         return true;
-    if (type === 'repeatable' && isRGXConvertibleToken(value))
+    if (type === 'repeatable' && isRGXConvertibleToken(value, true, acceptJSON))
         return value.rgxIsRepeatable ?? true;
-    if (typeMatches('array') && isRGXArrayToken(value))
+    if (typeMatches('array') && isRGXArrayToken(value, true, acceptJSON))
         return true;
     if (Array.isArray(type) && Array.isArray(value) && (!matchLength || type.length === value.length)) {
         // This will always be false.
         if (value.length < type.length)
             return false;
         // @ts-ignore Excessively deep type is not a problem here.
-        return value.every((item, i) => isRGXToken(item, type[i] ?? null));
+        return value.every((item, i) => isRGXToken(item, type[i] ?? null, true, acceptJSON));
     }
     return false;
 }
-function assertRGXToken(value, type = null, matchLength = true) {
-    if (!isRGXToken(value, type, matchLength)) {
+function assertRGXToken(value, type = null, matchLength = true, acceptJSON = true) {
+    // Captured before narrowing, since the narrowed type of `value` in the failure branch is excessively deep for TypeScript.
+    const got = value;
+    if (!isRGXToken(value, type, matchLength, acceptJSON)) {
         const flatType = rgxTokenTypeGuardInputToFlat(type);
-        /*
-            ts-ignore
-            This line sometimes throws a weird error in VSCode, but it doesn't prevent a build, and I don't know how to fix it.
-            It's an excessively deep type error on the `value` variable, which is typed as `unknown`.
-        */
-        throw new e.RGXInvalidTokenError("Invalid RGX token", flatType === null ? null : { type: "tokenType", values: [flatType] }, value);
+        throw new e.RGXInvalidTokenError("Invalid RGX token", flatType === null ? null : { type: "tokenType", values: [flatType] }, got);
     }
 }
-function isRGXGroupedToken(value, contentCheck = true) {
+function isRGXGroupedToken(value, contentCheck = true, acceptJSON = true) {
+    // JSON literal tokens are literals once converted, so they are implicitly groups.
+    // JSON class tokens are groups if the class token they convert to is a group.
+    if (acceptJSON && isRGXJSONLiteralToken(value, contentCheck))
+        return true;
+    if (acceptJSON && isRGXJSONClassToken(value))
+        return isRGXGroupedToken((0, json_1.rgxTokenFromJSON)(value), contentCheck, false);
     // Arrays and Literals are implicitly groups.
     // Classes are only groups if they have the isGroup property set to true.
-    return (isRGXArrayToken(value, contentCheck) ||
-        isRGXToken(value, "literal") ||
+    return (isRGXArrayToken(value, contentCheck, acceptJSON) ||
+        isRGXToken(value, "literal", true, false) ||
         (isRGXConvertibleToken(value, false) && (value.rgxIsGroup ||
-            (value.rgxGroupWrap === true && (!contentCheck || isRGXGroupedToken(value.toRgx()))))));
+            (value.rgxGroupWrap === true && (!contentCheck || isRGXGroupedToken(value.toRgx(), true, acceptJSON))))));
 }
-function assertRGXGroupedToken(value, contentCheck = true) {
-    if (!isRGXGroupedToken(value, contentCheck)) {
+function assertRGXGroupedToken(value, contentCheck = true, acceptJSON = true) {
+    if (!isRGXGroupedToken(value, contentCheck, acceptJSON)) {
         throw new e.RGXInvalidTokenError("Invalid group token, class token is not group, or convertible token is not group wrapped.", { type: "custom", values: ['array', 'literal', 'class', 'convertible'] }, value);
     }
 }

package/dist/types.d.ts

@@ -14,9 +14,30 @@ export type RGXConvertibleToken = {
     readonly rgxIsRepeatable?: boolean;
     readonly rgxInterpolate?: boolean;
 };
-export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
+export declare const RGX_JSON_FLAG = "$rgx";
+export type RGXJSONFlag = typeof RGX_JSON_FLAG;
+export type RGXJSONPrimitive = string | number | boolean | null;
+export type RGXJSONObject = {
+    [key: string]: RGXJSONValue | undefined;
+};
+export type RGXJSONValue = RGXJSONPrimitive | RGXJSONValue[] | RGXJSONObject;
+export type RGXJSONNativeToken = Exclude<RGXNativeToken, undefined>;
+export type RGXJSONLiteralToken = {
+    $rgx: true;
+    source: string;
+    flags?: string;
+};
+export type RGXJSONClassToken = {
+    $rgx: true;
+    class: string;
+    args?: RGXJSONValue[];
+};
+export type RGXJSONObjectToken = RGXJSONLiteralToken | RGXJSONClassToken;
+export type RGXJSONToken = RGXJSONNativeToken | RGXJSONObjectToken | RGXJSONToken[];
+export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXJSONObjectToken | RGXToken[];
+export type RGXNonJSONToken = Exclude<RGXToken, RGXJSONObjectToken>;
 export type RGXClassTokenConstructor = new (...args: unknown[]) => RGXClassToken;
-export type RGXGroupedToken = RGXToken[] | RGXLiteralToken | RGXGroupedConvertibleToken;
+export type RGXGroupedToken = RGXToken[] | RGXLiteralToken | RGXGroupedConvertibleToken | RGXJSONObjectToken;
 export type RGXGroupedConvertibleToken = (RGXConvertibleToken & {
     readonly rgxIsGroup: true;
 }) | (Omit<RGXConvertibleToken, "toRgx"> & {
@@ -26,11 +47,11 @@ export type RGXGroupedConvertibleToken = (RGXConvertibleToken & {
 export type RGXRepeatableConvertibleToken = RGXConvertibleToken & {
     readonly rgxIsRepeatable: true | undefined;
 };
-export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | RGXTokenType[];
+export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | 'json' | RGXTokenType[];
 export type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
 export type RGXTokenTypeGuardInput = "repeatable" | RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof RegExp | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
-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 'repeatable' ? Exclude<RGXToken, RGXConvertibleToken> | RGXRepeatableConvertibleToken : T extends new (...args: unknown[]) => infer R ? R : T extends RGXTokenTypeGuardInput[] ? {
-    [K in keyof T]: T[K] extends RGXTokenTypeGuardInput ? RGXTokenFromType<T[K]> : never;
+export type RGXTokenFromType<T extends RGXTokenTypeGuardInput, J extends boolean = true> = T extends null ? (J extends true ? RGXToken : RGXNonJSONToken) : T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? (J extends true ? RGXLiteralToken | RGXJSONLiteralToken : RGXLiteralToken) : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? (J extends true ? RGXConvertibleToken | RGXJSONClassToken : RGXConvertibleToken) : T extends 'class' ? (J extends true ? RGXClassToken | RGXJSONClassToken : RGXClassToken) : T extends 'json' ? RGXJSONToken : T extends 'array' ? RGXToken[] : T extends 'repeatable' ? Exclude<RGXToken, RGXConvertibleToken | RGXJSONClassToken> | RGXRepeatableConvertibleToken | (J extends true ? RGXJSONClassToken : never) : T extends new (...args: unknown[]) => infer R ? (J extends true ? R | RGXJSONClassToken : R) : T extends RGXTokenTypeGuardInput[] ? {
+    [K in keyof T]: T[K] extends RGXTokenTypeGuardInput ? RGXTokenFromType<T[K], J> : never;
 } : never;
 export type RangeObject = {
     min?: number | null;

package/dist/types.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validRegexLocalizableFlagDiffSymbol = exports.validRegexLocalizableFlagsSymbol = exports.validIdentifierSymbol = exports.validRegexFlagsSymbol = exports.validVanillaRegexFlagsSymbol = exports.validRegexSymbol = void 0;
+exports.validRegexLocalizableFlagDiffSymbol = exports.validRegexLocalizableFlagsSymbol = exports.validIdentifierSymbol = exports.validRegexFlagsSymbol = exports.validVanillaRegexFlagsSymbol = exports.validRegexSymbol = exports.RGX_JSON_FLAG = void 0;
+// The key that signals that a plain object is intended to be an RGX token in JSON form.
+exports.RGX_JSON_FLAG = "$rgx";
 exports.validRegexSymbol = Symbol('rgx.ValidRegex');
 exports.validVanillaRegexFlagsSymbol = Symbol('rgx.ValidVanillaRegexFlags');
 exports.validRegexFlagsSymbol = Symbol('rgx.ValidRegexFlags');

package/dist/walker/base.d.ts

@@ -15,6 +15,14 @@ export type RGXTryWalkOptions = {
     revertCaptures?: boolean;
 };
 export type RGXWalkerSnapshotKey = "sourcePosition" | "tokenPosition" | "reduced" | "share" | "captures" | "namedCaptures";
+export type RGXWalkerSnapshot<R, S> = Partial<{
+    sourcePosition: number;
+    tokenPosition: number;
+    reduced: R;
+    share: S;
+    captures: RGXCapture[];
+    namedCaptures: Record<string, RGXCapture[]>;
+}>;
 export type RGXTokenOrPart<R, S = unknown, T = any> = RGXToken | RGXPart<R, S, T>;
 export type RGXWalkerStepDirective = "stop" | "skip" | "silent";
 export declare class RGXWalker<R, S = unknown> {

package/package.json

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