@twin.org/tools-core 0.0.3-next.2 → 0.0.3-next.21

package/dist/es/utils/mappedTypeSchemaResolver.js

@@ -0,0 +1,231 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/* eslint-disable jsdoc/require-param, jsdoc/require-returns */
+import { Is, JsonHelper } from "@twin.org/core";
+import * as ts from "typescript";
+import { JsonSchemaBuilder } from "./jsonSchemaBuilder.js";
+/**
+ * Static mapped-type schema transformation helpers.
+ */
+export class MappedTypeSchemaResolver {
+    /**
+     * Resolve mapped type output keys, including remapped key names via `as`.
+     */
+    static resolveMappedTypePropertyEntries(context, typeNode, mappedKeys, mappedTypeParameterName) {
+        if (!typeNode.nameType) {
+            return mappedKeys.map(mappedKey => ({ sourceKey: mappedKey, mappedKey }));
+        }
+        const mappedEntries = [];
+        for (const sourceKey of mappedKeys) {
+            const mappedKey = MappedTypeSchemaResolver.resolveMappedTypeRemappedKey(context, typeNode.nameType, sourceKey, mappedTypeParameterName);
+            if (mappedKey !== null && !Is.stringValue(mappedKey)) {
+                return undefined;
+            }
+            if (Is.stringValue(mappedKey)) {
+                mappedEntries.push({ sourceKey, mappedKey });
+            }
+        }
+        return mappedEntries;
+    }
+    /**
+     * Resolve a remapped mapped-type key expression for a concrete source key.
+     */
+    static resolveMappedTypeRemappedKey(context, nameTypeNode, sourceKey, mappedTypeParameterName) {
+        if (ts.isParenthesizedTypeNode(nameTypeNode)) {
+            return MappedTypeSchemaResolver.resolveMappedTypeRemappedKey(context, nameTypeNode.type, sourceKey, mappedTypeParameterName);
+        }
+        if (nameTypeNode.kind === ts.SyntaxKind.NeverKeyword) {
+            return null;
+        }
+        if (JsonSchemaBuilder.isMappedTypeParameterReference(nameTypeNode, mappedTypeParameterName)) {
+            return sourceKey;
+        }
+        if (ts.isLiteralTypeNode(nameTypeNode)) {
+            if (ts.isStringLiteral(nameTypeNode.literal) || ts.isNumericLiteral(nameTypeNode.literal)) {
+                return nameTypeNode.literal.text;
+            }
+            if (nameTypeNode.literal.kind === ts.SyntaxKind.TrueKeyword) {
+                return "true";
+            }
+            if (nameTypeNode.literal.kind === ts.SyntaxKind.FalseKeyword) {
+                return "false";
+            }
+        }
+        if (ts.isIntersectionTypeNode(nameTypeNode)) {
+            const hasMappedKeyReference = nameTypeNode.types.some(type => JsonSchemaBuilder.isMappedTypeParameterReference(type, mappedTypeParameterName));
+            const hasStringKeyword = nameTypeNode.types.some(type => type.kind === ts.SyntaxKind.StringKeyword);
+            if (hasMappedKeyReference && hasStringKeyword) {
+                return sourceKey;
+            }
+            return undefined;
+        }
+        if (ts.isTemplateLiteralTypeNode(nameTypeNode)) {
+            let remappedKey = nameTypeNode.head.text;
+            for (const span of nameTypeNode.templateSpans) {
+                const spanValue = MappedTypeSchemaResolver.resolveMappedTypeRemappedKey(context, span.type, sourceKey, mappedTypeParameterName);
+                if (!Is.stringValue(spanValue)) {
+                    return undefined;
+                }
+                remappedKey += `${spanValue}${span.literal.text}`;
+            }
+            return remappedKey;
+        }
+        if (ts.isTypeReferenceNode(nameTypeNode) && ts.isIdentifier(nameTypeNode.typeName)) {
+            const intrinsicName = nameTypeNode.typeName.text;
+            if (nameTypeNode.typeArguments?.length === 1) {
+                const intrinsicInput = MappedTypeSchemaResolver.resolveMappedTypeRemappedKey(context, nameTypeNode.typeArguments[0], sourceKey, mappedTypeParameterName);
+                if (!Is.stringValue(intrinsicInput)) {
+                    return undefined;
+                }
+                return MappedTypeSchemaResolver.applyIntrinsicMappedTypeKeyRemap(intrinsicName, intrinsicInput);
+            }
+        }
+        if (ts.isConditionalTypeNode(nameTypeNode)) {
+            if (!JsonSchemaBuilder.isMappedTypeParameterReference(nameTypeNode.checkType, mappedTypeParameterName)) {
+                return undefined;
+            }
+            const satisfies = MappedTypeSchemaResolver.evaluateMappedKeyExtendsCondition(context, sourceKey, nameTypeNode.extendsType);
+            if (satisfies === undefined) {
+                return undefined;
+            }
+            const branchType = satisfies ? nameTypeNode.trueType : nameTypeNode.falseType;
+            return MappedTypeSchemaResolver.resolveMappedTypeRemappedKey(context, branchType, sourceKey, mappedTypeParameterName);
+        }
+        return undefined;
+    }
+    /**
+     * Evaluate whether a concrete mapped key satisfies an `extends` condition.
+     */
+    static evaluateMappedKeyExtendsCondition(context, sourceKey, extendsTypeNode) {
+        if (ts.isParenthesizedTypeNode(extendsTypeNode)) {
+            return MappedTypeSchemaResolver.evaluateMappedKeyExtendsCondition(context, sourceKey, extendsTypeNode.type);
+        }
+        if (extendsTypeNode.kind === ts.SyntaxKind.StringKeyword ||
+            extendsTypeNode.kind === ts.SyntaxKind.AnyKeyword ||
+            extendsTypeNode.kind === ts.SyntaxKind.UnknownKeyword) {
+            return true;
+        }
+        if (extendsTypeNode.kind === ts.SyntaxKind.NeverKeyword ||
+            extendsTypeNode.kind === ts.SyntaxKind.NumberKeyword ||
+            extendsTypeNode.kind === ts.SyntaxKind.BooleanKeyword ||
+            extendsTypeNode.kind === ts.SyntaxKind.ObjectKeyword) {
+            return false;
+        }
+        if (ts.isLiteralTypeNode(extendsTypeNode)) {
+            if (ts.isStringLiteral(extendsTypeNode.literal) ||
+                ts.isNumericLiteral(extendsTypeNode.literal)) {
+                return sourceKey === extendsTypeNode.literal.text;
+            }
+            return false;
+        }
+        if (ts.isUnionTypeNode(extendsTypeNode)) {
+            let hasUndetermined = false;
+            for (const memberType of extendsTypeNode.types) {
+                const result = MappedTypeSchemaResolver.evaluateMappedKeyExtendsCondition(context, sourceKey, memberType);
+                if (result === true) {
+                    return true;
+                }
+                if (result === undefined) {
+                    hasUndetermined = true;
+                }
+            }
+            return hasUndetermined ? undefined : false;
+        }
+        if (ts.isTypeOperatorNode(extendsTypeNode) &&
+            extendsTypeNode.operator === ts.SyntaxKind.KeyOfKeyword) {
+            const keys = JsonSchemaBuilder.extractKeyofTypeKeys(context, extendsTypeNode.type);
+            if (keys.length > 0) {
+                return keys.includes(sourceKey);
+            }
+            return undefined;
+        }
+        if (ts.isTypeReferenceNode(extendsTypeNode)) {
+            const resolved = JsonSchemaBuilder.resolveReferencedTypeNodeFromLocalDeclaration(context, extendsTypeNode);
+            if (resolved) {
+                return MappedTypeSchemaResolver.evaluateMappedKeyExtendsCondition(context, sourceKey, resolved);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Build a conservative fallback schema for mapped types whose key remapping cannot be resolved.
+     */
+    static buildMappedTypeFallbackSchema(context, typeNode, mappedKeys, mappedTypeParameterName, sourceObjectSchema) {
+        const additionalProperties = MappedTypeSchemaResolver.buildMappedTypeFallbackAdditionalProperties(context, typeNode, mappedKeys, mappedTypeParameterName, sourceObjectSchema);
+        return {
+            type: "object",
+            additionalProperties: additionalProperties ?? {}
+        };
+    }
+    /**
+     * Build fallback additionalProperties for unresolved mapped key remapping.
+     */
+    static buildMappedTypeFallbackAdditionalProperties(context, typeNode, mappedKeys, mappedTypeParameterName, sourceObjectSchema) {
+        const resolvedPropertySchemas = mappedKeys
+            .map(mappedKey => JsonSchemaBuilder.mapMappedTypePropertySchema(context, typeNode, mappedKey, mappedTypeParameterName, sourceObjectSchema))
+            .filter((mappedType) => mappedType !== undefined);
+        if (resolvedPropertySchemas.length === 0) {
+            return undefined;
+        }
+        const uniqueSchemas = resolvedPropertySchemas.filter((schema, index, allSchemas) => {
+            const schemaKey = JsonHelper.canonicalize(schema);
+            return allSchemas.findIndex(s => JsonHelper.canonicalize(s) === schemaKey) === index;
+        });
+        if (uniqueSchemas.length === 1) {
+            return uniqueSchemas[0];
+        }
+        return {
+            anyOf: uniqueSchemas
+        };
+    }
+    /**
+     * Merge mapped property schemas when multiple source keys remap to the same output key.
+     */
+    static mergeMappedTypePropertySchemas(existingSchema, nextSchema) {
+        const schemaVariants = [
+            ...(existingSchema.anyOf ?? [existingSchema]),
+            ...(nextSchema.anyOf ?? [nextSchema])
+        ];
+        const uniqueSchemas = schemaVariants.filter((schema, index, allSchemas) => {
+            const schemaKey = JsonHelper.canonicalize(schema);
+            return allSchemas.findIndex(s => JsonHelper.canonicalize(s) === schemaKey) === index;
+        });
+        if (uniqueSchemas.length === 1) {
+            return uniqueSchemas[0];
+        }
+        return {
+            anyOf: uniqueSchemas
+        };
+    }
+    /**
+     * Resolve required remapped keys from the source object's required key set.
+     */
+    static resolveMappedTypeSourceRequiredPropertyKeys(mappedEntries, sourceObjectSchema) {
+        if (!Is.array(sourceObjectSchema.required)) {
+            return undefined;
+        }
+        const sourceRequiredKeys = new Set(sourceObjectSchema.required);
+        const remappedRequiredKeys = mappedEntries
+            .filter(mappedEntry => sourceRequiredKeys.has(mappedEntry.sourceKey))
+            .map(mappedEntry => mappedEntry.mappedKey);
+        return [...new Set(remappedRequiredKeys)];
+    }
+    /**
+     * Apply TypeScript intrinsic string remapping helpers to a key.
+     */
+    static applyIntrinsicMappedTypeKeyRemap(intrinsicName, value) {
+        switch (intrinsicName) {
+            case "Uppercase":
+                return value.toUpperCase();
+            case "Lowercase":
+                return value.toLowerCase();
+            case "Capitalize":
+                return value.length > 0 ? `${value[0].toUpperCase()}${value.slice(1)}` : value;
+            case "Uncapitalize":
+                return value.length > 0 ? `${value[0].toLowerCase()}${value.slice(1)}` : value;
+            default:
+                return undefined;
+        }
+    }
+}
+//# sourceMappingURL=mappedTypeSchemaResolver.js.map

package/dist/es/utils/mappedTypeSchemaResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappedTypeSchemaResolver.js","sourceRoot":"","sources":["../../../src/utils/mappedTypeSchemaResolver.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n/* eslint-disable jsdoc/require-param, jsdoc/require-returns */\nimport { Is, JsonHelper } from \"@twin.org/core\";\nimport type { IJsonSchema } from \"@twin.org/tools-models\";\nimport * as ts from \"typescript\";\nimport { JsonSchemaBuilder } from \"./jsonSchemaBuilder.js\";\nimport type { ITypeScriptToSchemaContext } from \"../models/ITypeScriptToSchemaContext.js\";\n\n/**\n * Static mapped-type schema transformation helpers.\n */\nexport class MappedTypeSchemaResolver {\n\t/**\n\t * Resolve mapped type output keys, including remapped key names via `as`.\n\t */\n\tpublic static resolveMappedTypePropertyEntries(\n\t\tcontext: ITypeScriptToSchemaContext,\n\t\ttypeNode: ts.MappedTypeNode,\n\t\tmappedKeys: string[],\n\t\tmappedTypeParameterName: string\n\t): { sourceKey: string; mappedKey: string }[] | undefined {\n\t\tif (!typeNode.nameType) {\n\t\t\treturn mappedKeys.map(mappedKey => ({ sourceKey: mappedKey, mappedKey }));\n\t\t}\n\n\t\tconst mappedEntries: { sourceKey: string; mappedKey: string }[] = [];\n\n\t\tfor (const sourceKey of mappedKeys) {\n\t\t\tconst mappedKey = MappedTypeSchemaResolver.resolveMappedTypeRemappedKey(\n\t\t\t\tcontext,\n\t\t\t\ttypeNode.nameType,\n\t\t\t\tsourceKey,\n\t\t\t\tmappedTypeParameterName\n\t\t\t);\n\t\t\tif (mappedKey !== null && !Is.stringValue(mappedKey)) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\t\t\tif (Is.stringValue(mappedKey)) {\n\t\t\t\tmappedEntries.push({ sourceKey, mappedKey });\n\t\t\t}\n\t\t}\n\n\t\treturn mappedEntries;\n\t}\n\n\t/**\n\t * Resolve a remapped mapped-type key expression for a concrete source key.\n\t */\n\tpublic static resolveMappedTypeRemappedKey(\n\t\tcontext: ITypeScriptToSchemaContext,\n\t\tnameTypeNode: ts.TypeNode,\n\t\tsourceKey: string,\n\t\tmappedTypeParameterName: string\n\t): string | null | undefined {\n\t\tif (ts.isParenthesizedTypeNode(nameTypeNode)) {\n\t\t\treturn MappedTypeSchemaResolver.resolveMappedTypeRemappedKey(\n\t\t\t\tcontext,\n\t\t\t\tnameTypeNode.type,\n\t\t\t\tsourceKey,\n\t\t\t\tmappedTypeParameterName\n\t\t\t);\n\t\t}\n\n\t\tif (nameTypeNode.kind === ts.SyntaxKind.NeverKeyword) {\n\t\t\treturn null;\n\t\t}\n\n\t\tif (JsonSchemaBuilder.isMappedTypeParameterReference(nameTypeNode, mappedTypeParameterName)) {\n\t\t\treturn sourceKey;\n\t\t}\n\n\t\tif (ts.isLiteralTypeNode(nameTypeNode)) {\n\t\t\tif (ts.isStringLiteral(nameTypeNode.literal) || ts.isNumericLiteral(nameTypeNode.literal)) {\n\t\t\t\treturn nameTypeNode.literal.text;\n\t\t\t}\n\t\t\tif (nameTypeNode.literal.kind === ts.SyntaxKind.TrueKeyword) {\n\t\t\t\treturn \"true\";\n\t\t\t}\n\t\t\tif (nameTypeNode.literal.kind === ts.SyntaxKind.FalseKeyword) {\n\t\t\t\treturn \"false\";\n\t\t\t}\n\t\t}\n\n\t\tif (ts.isIntersectionTypeNode(nameTypeNode)) {\n\t\t\tconst hasMappedKeyReference = nameTypeNode.types.some(type =>\n\t\t\t\tJsonSchemaBuilder.isMappedTypeParameterReference(type, mappedTypeParameterName)\n\t\t\t);\n\t\t\tconst hasStringKeyword = nameTypeNode.types.some(\n\t\t\t\ttype => type.kind === ts.SyntaxKind.StringKeyword\n\t\t\t);\n\t\t\tif (hasMappedKeyReference && hasStringKeyword) {\n\t\t\t\treturn sourceKey;\n\t\t\t}\n\t\t\treturn undefined;\n\t\t}\n\n\t\tif (ts.isTemplateLiteralTypeNode(nameTypeNode)) {\n\t\t\tlet remappedKey = nameTypeNode.head.text;\n\t\t\tfor (const span of nameTypeNode.templateSpans) {\n\t\t\t\tconst spanValue = MappedTypeSchemaResolver.resolveMappedTypeRemappedKey(\n\t\t\t\t\tcontext,\n\t\t\t\t\tspan.type,\n\t\t\t\t\tsourceKey,\n\t\t\t\t\tmappedTypeParameterName\n\t\t\t\t);\n\t\t\t\tif (!Is.stringValue(spanValue)) {\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\t\t\t\tremappedKey += `${spanValue}${span.literal.text}`;\n\t\t\t}\n\n\t\t\treturn remappedKey;\n\t\t}\n\n\t\tif (ts.isTypeReferenceNode(nameTypeNode) && ts.isIdentifier(nameTypeNode.typeName)) {\n\t\t\tconst intrinsicName = nameTypeNode.typeName.text;\n\t\t\tif (nameTypeNode.typeArguments?.length === 1) {\n\t\t\t\tconst intrinsicInput = MappedTypeSchemaResolver.resolveMappedTypeRemappedKey(\n\t\t\t\t\tcontext,\n\t\t\t\t\tnameTypeNode.typeArguments[0],\n\t\t\t\t\tsourceKey,\n\t\t\t\t\tmappedTypeParameterName\n\t\t\t\t);\n\t\t\t\tif (!Is.stringValue(intrinsicInput)) {\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\n\t\t\t\treturn MappedTypeSchemaResolver.applyIntrinsicMappedTypeKeyRemap(\n\t\t\t\t\tintrinsicName,\n\t\t\t\t\tintrinsicInput\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\tif (ts.isConditionalTypeNode(nameTypeNode)) {\n\t\t\tif (\n\t\t\t\t!JsonSchemaBuilder.isMappedTypeParameterReference(\n\t\t\t\t\tnameTypeNode.checkType,\n\t\t\t\t\tmappedTypeParameterName\n\t\t\t\t)\n\t\t\t) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst satisfies = MappedTypeSchemaResolver.evaluateMappedKeyExtendsCondition(\n\t\t\t\tcontext,\n\t\t\t\tsourceKey,\n\t\t\t\tnameTypeNode.extendsType\n\t\t\t);\n\t\t\tif (satisfies === undefined) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst branchType = satisfies ? nameTypeNode.trueType : nameTypeNode.falseType;\n\t\t\treturn MappedTypeSchemaResolver.resolveMappedTypeRemappedKey(\n\t\t\t\tcontext,\n\t\t\t\tbranchType,\n\t\t\t\tsourceKey,\n\t\t\t\tmappedTypeParameterName\n\t\t\t);\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Evaluate whether a concrete mapped key satisfies an `extends` condition.\n\t */\n\tpublic static evaluateMappedKeyExtendsCondition(\n\t\tcontext: ITypeScriptToSchemaContext,\n\t\tsourceKey: string,\n\t\textendsTypeNode: ts.TypeNode\n\t): boolean | undefined {\n\t\tif (ts.isParenthesizedTypeNode(extendsTypeNode)) {\n\t\t\treturn MappedTypeSchemaResolver.evaluateMappedKeyExtendsCondition(\n\t\t\t\tcontext,\n\t\t\t\tsourceKey,\n\t\t\t\textendsTypeNode.type\n\t\t\t);\n\t\t}\n\n\t\tif (\n\t\t\textendsTypeNode.kind === ts.SyntaxKind.StringKeyword ||\n\t\t\textendsTypeNode.kind === ts.SyntaxKind.AnyKeyword ||\n\t\t\textendsTypeNode.kind === ts.SyntaxKind.UnknownKeyword\n\t\t) {\n\t\t\treturn true;\n\t\t}\n\n\t\tif (\n\t\t\textendsTypeNode.kind === ts.SyntaxKind.NeverKeyword ||\n\t\t\textendsTypeNode.kind === ts.SyntaxKind.NumberKeyword ||\n\t\t\textendsTypeNode.kind === ts.SyntaxKind.BooleanKeyword ||\n\t\t\textendsTypeNode.kind === ts.SyntaxKind.ObjectKeyword\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\n\t\tif (ts.isLiteralTypeNode(extendsTypeNode)) {\n\t\t\tif (\n\t\t\t\tts.isStringLiteral(extendsTypeNode.literal) ||\n\t\t\t\tts.isNumericLiteral(extendsTypeNode.literal)\n\t\t\t) {\n\t\t\t\treturn sourceKey === extendsTypeNode.literal.text;\n\t\t\t}\n\t\t\treturn false;\n\t\t}\n\n\t\tif (ts.isUnionTypeNode(extendsTypeNode)) {\n\t\t\tlet hasUndetermined = false;\n\t\t\tfor (const memberType of extendsTypeNode.types) {\n\t\t\t\tconst result = MappedTypeSchemaResolver.evaluateMappedKeyExtendsCondition(\n\t\t\t\t\tcontext,\n\t\t\t\t\tsourceKey,\n\t\t\t\t\tmemberType\n\t\t\t\t);\n\t\t\t\tif (result === true) {\n\t\t\t\t\treturn true;\n\t\t\t\t}\n\t\t\t\tif (result === undefined) {\n\t\t\t\t\thasUndetermined = true;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn hasUndetermined ? undefined : false;\n\t\t}\n\n\t\tif (\n\t\t\tts.isTypeOperatorNode(extendsTypeNode) &&\n\t\t\textendsTypeNode.operator === ts.SyntaxKind.KeyOfKeyword\n\t\t) {\n\t\t\tconst keys = JsonSchemaBuilder.extractKeyofTypeKeys(context, extendsTypeNode.type);\n\t\t\tif (keys.length > 0) {\n\t\t\t\treturn keys.includes(sourceKey);\n\t\t\t}\n\t\t\treturn undefined;\n\t\t}\n\n\t\tif (ts.isTypeReferenceNode(extendsTypeNode)) {\n\t\t\tconst resolved = JsonSchemaBuilder.resolveReferencedTypeNodeFromLocalDeclaration(\n\t\t\t\tcontext,\n\t\t\t\textendsTypeNode\n\t\t\t);\n\t\t\tif (resolved) {\n\t\t\t\treturn MappedTypeSchemaResolver.evaluateMappedKeyExtendsCondition(\n\t\t\t\t\tcontext,\n\t\t\t\t\tsourceKey,\n\t\t\t\t\tresolved\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Build a conservative fallback schema for mapped types whose key remapping cannot be resolved.\n\t */\n\tpublic static buildMappedTypeFallbackSchema(\n\t\tcontext: ITypeScriptToSchemaContext,\n\t\ttypeNode: ts.MappedTypeNode,\n\t\tmappedKeys: string[],\n\t\tmappedTypeParameterName: string,\n\t\tsourceObjectSchema?: IJsonSchema\n\t): IJsonSchema {\n\t\tconst additionalProperties =\n\t\t\tMappedTypeSchemaResolver.buildMappedTypeFallbackAdditionalProperties(\n\t\t\t\tcontext,\n\t\t\t\ttypeNode,\n\t\t\t\tmappedKeys,\n\t\t\t\tmappedTypeParameterName,\n\t\t\t\tsourceObjectSchema\n\t\t\t);\n\n\t\treturn {\n\t\t\ttype: \"object\",\n\t\t\tadditionalProperties: additionalProperties ?? {}\n\t\t};\n\t}\n\n\t/**\n\t * Build fallback additionalProperties for unresolved mapped key remapping.\n\t */\n\tpublic static buildMappedTypeFallbackAdditionalProperties(\n\t\tcontext: ITypeScriptToSchemaContext,\n\t\ttypeNode: ts.MappedTypeNode,\n\t\tmappedKeys: string[],\n\t\tmappedTypeParameterName: string,\n\t\tsourceObjectSchema?: IJsonSchema\n\t): IJsonSchema | undefined {\n\t\tconst resolvedPropertySchemas = mappedKeys\n\t\t\t.map(mappedKey =>\n\t\t\t\tJsonSchemaBuilder.mapMappedTypePropertySchema(\n\t\t\t\t\tcontext,\n\t\t\t\t\ttypeNode,\n\t\t\t\t\tmappedKey,\n\t\t\t\t\tmappedTypeParameterName,\n\t\t\t\t\tsourceObjectSchema\n\t\t\t\t)\n\t\t\t)\n\t\t\t.filter((mappedType): mappedType is IJsonSchema => mappedType !== undefined);\n\n\t\tif (resolvedPropertySchemas.length === 0) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst uniqueSchemas = resolvedPropertySchemas.filter((schema, index, allSchemas) => {\n\t\t\tconst schemaKey = JsonHelper.canonicalize(schema);\n\t\t\treturn allSchemas.findIndex(s => JsonHelper.canonicalize(s) === schemaKey) === index;\n\t\t});\n\n\t\tif (uniqueSchemas.length === 1) {\n\t\t\treturn uniqueSchemas[0];\n\t\t}\n\n\t\treturn {\n\t\t\tanyOf: uniqueSchemas\n\t\t};\n\t}\n\n\t/**\n\t * Merge mapped property schemas when multiple source keys remap to the same output key.\n\t */\n\tpublic static mergeMappedTypePropertySchemas(\n\t\texistingSchema: IJsonSchema,\n\t\tnextSchema: IJsonSchema\n\t): IJsonSchema {\n\t\tconst schemaVariants = [\n\t\t\t...(existingSchema.anyOf ?? [existingSchema]),\n\t\t\t...(nextSchema.anyOf ?? [nextSchema])\n\t\t];\n\n\t\tconst uniqueSchemas = schemaVariants.filter((schema, index, allSchemas) => {\n\t\t\tconst schemaKey = JsonHelper.canonicalize(schema);\n\t\t\treturn allSchemas.findIndex(s => JsonHelper.canonicalize(s) === schemaKey) === index;\n\t\t});\n\n\t\tif (uniqueSchemas.length === 1) {\n\t\t\treturn uniqueSchemas[0];\n\t\t}\n\n\t\treturn {\n\t\t\tanyOf: uniqueSchemas\n\t\t};\n\t}\n\n\t/**\n\t * Resolve required remapped keys from the source object's required key set.\n\t */\n\tpublic static resolveMappedTypeSourceRequiredPropertyKeys(\n\t\tmappedEntries: { sourceKey: string; mappedKey: string }[],\n\t\tsourceObjectSchema: IJsonSchema\n\t): string[] | undefined {\n\t\tif (!Is.array<string>(sourceObjectSchema.required)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst sourceRequiredKeys = new Set(sourceObjectSchema.required);\n\t\tconst remappedRequiredKeys = mappedEntries\n\t\t\t.filter(mappedEntry => sourceRequiredKeys.has(mappedEntry.sourceKey))\n\t\t\t.map(mappedEntry => mappedEntry.mappedKey);\n\n\t\treturn [...new Set(remappedRequiredKeys)];\n\t}\n\n\t/**\n\t * Apply TypeScript intrinsic string remapping helpers to a key.\n\t */\n\tprivate static applyIntrinsicMappedTypeKeyRemap(\n\t\tintrinsicName: string,\n\t\tvalue: string\n\t): string | undefined {\n\t\tswitch (intrinsicName) {\n\t\t\tcase \"Uppercase\":\n\t\t\t\treturn value.toUpperCase();\n\t\t\tcase \"Lowercase\":\n\t\t\t\treturn value.toLowerCase();\n\t\t\tcase \"Capitalize\":\n\t\t\t\treturn value.length > 0 ? `${value[0].toUpperCase()}${value.slice(1)}` : value;\n\t\t\tcase \"Uncapitalize\":\n\t\t\t\treturn value.length > 0 ? `${value[0].toLowerCase()}${value.slice(1)}` : value;\n\t\t\tdefault:\n\t\t\t\treturn undefined;\n\t\t}\n\t}\n}\n"]}

package/dist/es/utils/objectTransformer.js

@@ -0,0 +1,162 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Is, ObjectHelper } from "@twin.org/core";
+/**
+ * Applies common object-schema transformations used by the builder.
+ */
+export class ObjectTransformer {
+    /**
+     * Resolve a property schema from an object schema by property key.
+     * @param baseSchema The source object schema.
+     * @param propertyKey The property key to resolve.
+     * @returns The resolved property schema.
+     */
+    static resolvePropertySchemaFromObjectSchema(baseSchema, propertyKey) {
+        if (!baseSchema.properties || !Is.object(baseSchema.properties)) {
+            return undefined;
+        }
+        const propertySchema = baseSchema.properties[propertyKey];
+        return propertySchema ? ObjectHelper.clone(propertySchema) : undefined;
+    }
+    /**
+     * Remove keys from an object schema.
+     * @param baseSchema The source object schema.
+     * @param omittedKeys The keys to remove.
+     * @returns The transformed object schema.
+     */
+    static omitKeysFromObjectSchema(baseSchema, omittedKeys) {
+        const omittedKeySet = new Set(omittedKeys);
+        const mappedSchema = ObjectTransformer.toInlineUtilityObjectSchema(baseSchema);
+        if (Is.object(mappedSchema.properties)) {
+            for (const key of Object.keys(mappedSchema.properties)) {
+                if (omittedKeySet.has(key)) {
+                    delete mappedSchema.properties[key];
+                }
+            }
+            if (Object.keys(mappedSchema.properties).length === 0) {
+                delete mappedSchema.properties;
+            }
+        }
+        if (Is.array(mappedSchema.required)) {
+            mappedSchema.required = mappedSchema.required.filter(key => !omittedKeySet.has(key));
+            if (mappedSchema.required.length === 0) {
+                delete mappedSchema.required;
+            }
+        }
+        return mappedSchema;
+    }
+    /**
+     * Keep only keys from an object schema.
+     * @param baseSchema The source object schema.
+     * @param pickedKeys The keys to keep.
+     * @returns The transformed object schema.
+     */
+    static pickKeysFromObjectSchema(baseSchema, pickedKeys) {
+        const pickedKeySet = new Set(pickedKeys);
+        const mappedSchema = ObjectTransformer.toInlineUtilityObjectSchema(baseSchema);
+        if (Is.object(mappedSchema.properties)) {
+            for (const key of Object.keys(mappedSchema.properties)) {
+                if (!pickedKeySet.has(key)) {
+                    delete mappedSchema.properties[key];
+                }
+            }
+            if (Object.keys(mappedSchema.properties).length === 0) {
+                delete mappedSchema.properties;
+            }
+        }
+        if (Is.array(mappedSchema.required)) {
+            mappedSchema.required = mappedSchema.required.filter(key => pickedKeySet.has(key));
+            if (mappedSchema.required.length === 0) {
+                delete mappedSchema.required;
+            }
+        }
+        return mappedSchema;
+    }
+    /**
+     * Normalize utility-derived object schemas for inline property usage.
+     * When the schema contains an allOf, flatten it by merging properties from all branches.
+     * @param schema The source object schema.
+     * @returns The normalized inline schema.
+     * @internal
+     */
+    static toInlineUtilityObjectSchema(schema) {
+        const mappedSchema = ObjectHelper.clone(schema);
+        delete mappedSchema.$schema;
+        delete mappedSchema.$id;
+        delete mappedSchema.title;
+        // Flatten allOf by merging properties and required arrays from all branches
+        // This handles inheritance cases where a type extends another type
+        if (Is.array(mappedSchema.allOf) && mappedSchema.allOf.length > 0) {
+            const mergedProperties = {};
+            const mergedRequired = new Set();
+            // Collect properties and required fields from all allOf branches
+            for (const branch of mappedSchema.allOf) {
+                if (Is.object(branch)) {
+                    const branchRecord = branch;
+                    // Merge properties
+                    if (Is.object(branchRecord.properties)) {
+                        Object.assign(mergedProperties, branchRecord.properties);
+                    }
+                    // Collect required fields
+                    if (Is.array(branchRecord.required)) {
+                        for (const field of branchRecord.required) {
+                            if (Is.stringValue(field)) {
+                                mergedRequired.add(field);
+                            }
+                        }
+                    }
+                }
+            }
+            // Remove allOf and set merged properties at the top level
+            delete mappedSchema.allOf;
+            if (Object.keys(mergedProperties).length > 0) {
+                mappedSchema.properties = Object.assign(mappedSchema.properties ?? {}, mergedProperties);
+            }
+            if (mergedRequired.size > 0) {
+                const existingRequired = Is.array(mappedSchema.required) ? mappedSchema.required : [];
+                mappedSchema.required = [...new Set([...existingRequired, ...mergedRequired])];
+            }
+        }
+        return mappedSchema;
+    }
+    /**
+     * Normalize schema description whitespace while preserving intentional line breaks.
+     * @param schema The schema to normalize.
+     * @returns The normalized schema.
+     */
+    static normalizeSchemaDescriptions(schema) {
+        const normalizedSchema = ObjectHelper.clone(schema);
+        const normalizeObject = (value) => {
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    normalizeObject(item);
+                }
+                return;
+            }
+            if (Is.object(value)) {
+                const valueRecord = value;
+                if (Is.stringValue(valueRecord.description)) {
+                    valueRecord.description = ObjectTransformer.normalizeSchemaDescriptionText(valueRecord.description);
+                }
+                for (const nestedValue of Object.values(valueRecord)) {
+                    normalizeObject(nestedValue);
+                }
+            }
+        };
+        normalizeObject(normalizedSchema);
+        return normalizedSchema;
+    }
+    /**
+     * Normalize a description string while preserving explicit line breaks from source comments.
+     * @param description The description to normalize.
+     * @returns The normalized description.
+     * @internal
+     */
+    static normalizeSchemaDescriptionText(description) {
+        return description
+            .split(/\r?\n/)
+            .map(line => line.replace(/\s{2,}/g, " ").trim())
+            .join("\n");
+    }
+}
+//# sourceMappingURL=objectTransformer.js.map

package/dist/es/utils/objectTransformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectTransformer.js","sourceRoot":"","sources":["../../../src/utils/objectTransformer.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is, ObjectHelper } from \"@twin.org/core\";\nimport type { IJsonSchema } from \"@twin.org/tools-models\";\n\n/**\n * Applies common object-schema transformations used by the builder.\n */\nexport class ObjectTransformer {\n\t/**\n\t * Resolve a property schema from an object schema by property key.\n\t * @param baseSchema The source object schema.\n\t * @param propertyKey The property key to resolve.\n\t * @returns The resolved property schema.\n\t */\n\tpublic static resolvePropertySchemaFromObjectSchema(\n\t\tbaseSchema: IJsonSchema,\n\t\tpropertyKey: string\n\t): IJsonSchema | undefined {\n\t\tif (!baseSchema.properties || !Is.object(baseSchema.properties)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst propertySchema = baseSchema.properties[propertyKey];\n\t\treturn propertySchema ? ObjectHelper.clone(propertySchema) : undefined;\n\t}\n\n\t/**\n\t * Remove keys from an object schema.\n\t * @param baseSchema The source object schema.\n\t * @param omittedKeys The keys to remove.\n\t * @returns The transformed object schema.\n\t */\n\tpublic static omitKeysFromObjectSchema(\n\t\tbaseSchema: IJsonSchema,\n\t\tomittedKeys: string[]\n\t): IJsonSchema {\n\t\tconst omittedKeySet = new Set(omittedKeys);\n\t\tconst mappedSchema = ObjectTransformer.toInlineUtilityObjectSchema(baseSchema);\n\n\t\tif (Is.object(mappedSchema.properties)) {\n\t\t\tfor (const key of Object.keys(mappedSchema.properties)) {\n\t\t\t\tif (omittedKeySet.has(key)) {\n\t\t\t\t\tdelete mappedSchema.properties[key];\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (Object.keys(mappedSchema.properties).length === 0) {\n\t\t\t\tdelete mappedSchema.properties;\n\t\t\t}\n\t\t}\n\n\t\tif (Is.array(mappedSchema.required)) {\n\t\t\tmappedSchema.required = mappedSchema.required.filter(key => !omittedKeySet.has(key));\n\t\t\tif (mappedSchema.required.length === 0) {\n\t\t\t\tdelete mappedSchema.required;\n\t\t\t}\n\t\t}\n\n\t\treturn mappedSchema;\n\t}\n\n\t/**\n\t * Keep only keys from an object schema.\n\t * @param baseSchema The source object schema.\n\t * @param pickedKeys The keys to keep.\n\t * @returns The transformed object schema.\n\t */\n\tpublic static pickKeysFromObjectSchema(\n\t\tbaseSchema: IJsonSchema,\n\t\tpickedKeys: string[]\n\t): IJsonSchema {\n\t\tconst pickedKeySet = new Set(pickedKeys);\n\t\tconst mappedSchema = ObjectTransformer.toInlineUtilityObjectSchema(baseSchema);\n\n\t\tif (Is.object(mappedSchema.properties)) {\n\t\t\tfor (const key of Object.keys(mappedSchema.properties)) {\n\t\t\t\tif (!pickedKeySet.has(key)) {\n\t\t\t\t\tdelete mappedSchema.properties[key];\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (Object.keys(mappedSchema.properties).length === 0) {\n\t\t\t\tdelete mappedSchema.properties;\n\t\t\t}\n\t\t}\n\n\t\tif (Is.array(mappedSchema.required)) {\n\t\t\tmappedSchema.required = mappedSchema.required.filter(key => pickedKeySet.has(key));\n\t\t\tif (mappedSchema.required.length === 0) {\n\t\t\t\tdelete mappedSchema.required;\n\t\t\t}\n\t\t}\n\n\t\treturn mappedSchema;\n\t}\n\n\t/**\n\t * Normalize utility-derived object schemas for inline property usage.\n\t * When the schema contains an allOf, flatten it by merging properties from all branches.\n\t * @param schema The source object schema.\n\t * @returns The normalized inline schema.\n\t * @internal\n\t */\n\tpublic static toInlineUtilityObjectSchema(schema: IJsonSchema): IJsonSchema {\n\t\tconst mappedSchema = ObjectHelper.clone(schema);\n\t\tdelete mappedSchema.$schema;\n\t\tdelete mappedSchema.$id;\n\t\tdelete mappedSchema.title;\n\n\t\t// Flatten allOf by merging properties and required arrays from all branches\n\t\t// This handles inheritance cases where a type extends another type\n\t\tif (Is.array(mappedSchema.allOf) && mappedSchema.allOf.length > 0) {\n\t\t\tconst mergedProperties: { [key: string]: unknown } = {};\n\t\t\tconst mergedRequired = new Set<string>();\n\n\t\t\t// Collect properties and required fields from all allOf branches\n\t\t\tfor (const branch of mappedSchema.allOf) {\n\t\t\t\tif (Is.object(branch)) {\n\t\t\t\t\tconst branchRecord = branch as { [key: string]: unknown };\n\t\t\t\t\t// Merge properties\n\t\t\t\t\tif (Is.object(branchRecord.properties)) {\n\t\t\t\t\t\tObject.assign(mergedProperties, branchRecord.properties);\n\t\t\t\t\t}\n\t\t\t\t\t// Collect required fields\n\t\t\t\t\tif (Is.array(branchRecord.required)) {\n\t\t\t\t\t\tfor (const field of branchRecord.required) {\n\t\t\t\t\t\t\tif (Is.stringValue(field)) {\n\t\t\t\t\t\t\t\tmergedRequired.add(field);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Remove allOf and set merged properties at the top level\n\t\t\tdelete mappedSchema.allOf;\n\n\t\t\tif (Object.keys(mergedProperties).length > 0) {\n\t\t\t\tmappedSchema.properties = Object.assign(mappedSchema.properties ?? {}, mergedProperties);\n\t\t\t}\n\n\t\t\tif (mergedRequired.size > 0) {\n\t\t\t\tconst existingRequired = Is.array(mappedSchema.required) ? mappedSchema.required : [];\n\t\t\t\tmappedSchema.required = [...new Set([...existingRequired, ...mergedRequired])];\n\t\t\t}\n\t\t}\n\n\t\treturn mappedSchema;\n\t}\n\n\t/**\n\t * Normalize schema description whitespace while preserving intentional line breaks.\n\t * @param schema The schema to normalize.\n\t * @returns The normalized schema.\n\t */\n\tpublic static normalizeSchemaDescriptions(schema: IJsonSchema): IJsonSchema {\n\t\tconst normalizedSchema = ObjectHelper.clone(schema);\n\t\tconst normalizeObject = (value: unknown): void => {\n\t\t\tif (Array.isArray(value)) {\n\t\t\t\tfor (const item of value) {\n\t\t\t\t\tnormalizeObject(item);\n\t\t\t\t}\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tif (Is.object(value)) {\n\t\t\t\tconst valueRecord = value as { [key: string]: unknown };\n\t\t\t\tif (Is.stringValue(valueRecord.description)) {\n\t\t\t\t\tvalueRecord.description = ObjectTransformer.normalizeSchemaDescriptionText(\n\t\t\t\t\t\tvalueRecord.description\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\tfor (const nestedValue of Object.values(valueRecord)) {\n\t\t\t\t\tnormalizeObject(nestedValue);\n\t\t\t\t}\n\t\t\t}\n\t\t};\n\n\t\tnormalizeObject(normalizedSchema);\n\t\treturn normalizedSchema;\n\t}\n\n\t/**\n\t * Normalize a description string while preserving explicit line breaks from source comments.\n\t * @param description The description to normalize.\n\t * @returns The normalized description.\n\t * @internal\n\t */\n\tprivate static normalizeSchemaDescriptionText(description: string): string {\n\t\treturn description\n\t\t\t.split(/\\r?\\n/)\n\t\t\t.map(line => line.replace(/\\s{2,}/g, \" \").trim())\n\t\t\t.join(\"\\n\");\n\t}\n}\n"]}

package/dist/es/utils/regEx.js

@@ -0,0 +1,128 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Utility methods for pattern matching and regex construction.
+ */
+export class RegEx {
+    /**
+     * Determine whether a reference mapping pattern matches an external reference.
+     * @param pattern The mapping pattern.
+     * @param packageName The external package name.
+     * @param typeName The imported type name.
+     * @param schemaTitle The derived schema title.
+     * @returns True if matched.
+     */
+    static isReferencePatternMatch(pattern, packageName, typeName, schemaTitle) {
+        const regex = RegEx.toRegexFromReferencePattern(pattern);
+        return regex
+            ? regex.test(packageName) || regex.test(typeName) || regex.test(schemaTitle)
+            : false;
+    }
+    /**
+     * Apply a reference mapping replacement to the first matching candidate.
+     * @param pattern The mapping pattern.
+     * @param replacement The replacement template.
+     * @param packageName The external package name.
+     * @param typeName The imported type name.
+     * @param schemaTitle The derived schema title.
+     * @returns The replaced value if a candidate matches.
+     */
+    static applyReferencePatternReplacement(pattern, replacement, packageName, typeName, schemaTitle) {
+        const regex = RegEx.toRegexFromReferencePattern(pattern);
+        if (!regex) {
+            return undefined;
+        }
+        for (const candidate of [packageName, typeName, schemaTitle]) {
+            regex.lastIndex = 0;
+            if (regex.test(candidate)) {
+                regex.lastIndex = 0;
+                return candidate.replace(regex, replacement);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Determine if a mapping pattern is a regex literal surrounded by forward slashes.
+     * Example pattern: /^foo.*bar$/
+     * @param pattern The mapping pattern.
+     * @returns True if the pattern looks like a regex literal.
+     * @internal
+     */
+    static isRegexLiteralPattern(pattern) {
+        return pattern.length > 2 && pattern.startsWith("/") && pattern.endsWith("/");
+    }
+    /**
+     * Determine if a mapping pattern should be treated as a raw regex expression.
+     * Any pattern that contains at least one regex meta character is treated as a raw expression.
+     * @param pattern The mapping pattern.
+     * @returns True if the pattern contains regex syntax.
+     * @internal
+     */
+    static isRegexExpressionPattern(pattern) {
+        return /[()[\]{}+?|^$\\]/u.test(pattern);
+    }
+    /**
+     * Convert a regex literal mapping pattern to a RegExp.
+     * The surrounding forward slashes are stripped before compiling.
+     * @param pattern The regex literal pattern, e.g. /^foo.*bar$/
+     * @returns The RegExp instance, or undefined when the inner expression is invalid.
+     * @internal
+     */
+    static toRegexFromLiteralPattern(pattern) {
+        try {
+            return new RegExp(pattern.slice(1, -1));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Convert a raw regex expression mapping pattern to a RegExp anchored to full-string match.
+     * The expression is wrapped with ^ and $ so that partial matches are not accepted.
+     * @param pattern The raw regex expression.
+     * @returns The RegExp instance, or undefined when the expression is invalid.
+     * @internal
+     */
+    static toRegexFromExpressionPattern(pattern) {
+        try {
+            return new RegExp(`^${pattern}$`);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Select and compile the appropriate RegExp for a reference mapping pattern.
+     * Evaluation order: regex literal -> raw regex expression -> wildcard glob.
+     * Plain strings with none of these characteristics return undefined.
+     * @param pattern The mapping pattern.
+     * @returns The RegExp instance, or undefined when the pattern is not pattern-based.
+     * @internal
+     */
+    static toRegexFromReferencePattern(pattern) {
+        if (RegEx.isRegexLiteralPattern(pattern)) {
+            return RegEx.toRegexFromLiteralPattern(pattern);
+        }
+        if (RegEx.isRegexExpressionPattern(pattern)) {
+            return RegEx.toRegexFromExpressionPattern(pattern);
+        }
+        if (pattern.includes("*")) {
+            return RegEx.toRegexFromWildcardPattern(pattern);
+        }
+        return undefined;
+    }
+    /**
+     * Convert a glob wildcard pattern to a RegExp.
+     * All regex metacharacters in the pattern are escaped first, then each * is replaced with .*.
+     * The resulting expression is anchored with ^ and $ for full-string matching.
+     * @param pattern The wildcard pattern, e.g. *Operation or @twin.org/*.
+     * @returns The compiled RegExp.
+     * @internal
+     */
+    static toRegexFromWildcardPattern(pattern) {
+        const escapedPattern = pattern.replace(/[$()+./?[\\\]^{|}-]/g, "\\$&");
+        const regexPattern = `^${escapedPattern.replace(/\*/g, ".*")}$`;
+        return new RegExp(regexPattern);
+    }
+}
+//# sourceMappingURL=regEx.js.map

package/dist/es/utils/regEx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"regEx.js","sourceRoot":"","sources":["../../../src/utils/regEx.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Utility methods for pattern matching and regex construction.\n */\nexport class RegEx {\n\t/**\n\t * Determine whether a reference mapping pattern matches an external reference.\n\t * @param pattern The mapping pattern.\n\t * @param packageName The external package name.\n\t * @param typeName The imported type name.\n\t * @param schemaTitle The derived schema title.\n\t * @returns True if matched.\n\t */\n\tpublic static isReferencePatternMatch(\n\t\tpattern: string,\n\t\tpackageName: string,\n\t\ttypeName: string,\n\t\tschemaTitle: string\n\t): boolean {\n\t\tconst regex = RegEx.toRegexFromReferencePattern(pattern);\n\t\treturn regex\n\t\t\t? regex.test(packageName) || regex.test(typeName) || regex.test(schemaTitle)\n\t\t\t: false;\n\t}\n\n\t/**\n\t * Apply a reference mapping replacement to the first matching candidate.\n\t * @param pattern The mapping pattern.\n\t * @param replacement The replacement template.\n\t * @param packageName The external package name.\n\t * @param typeName The imported type name.\n\t * @param schemaTitle The derived schema title.\n\t * @returns The replaced value if a candidate matches.\n\t */\n\tpublic static applyReferencePatternReplacement(\n\t\tpattern: string,\n\t\treplacement: string,\n\t\tpackageName: string,\n\t\ttypeName: string,\n\t\tschemaTitle: string\n\t): string | undefined {\n\t\tconst regex = RegEx.toRegexFromReferencePattern(pattern);\n\t\tif (!regex) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tfor (const candidate of [packageName, typeName, schemaTitle]) {\n\t\t\tregex.lastIndex = 0;\n\t\t\tif (regex.test(candidate)) {\n\t\t\t\tregex.lastIndex = 0;\n\t\t\t\treturn candidate.replace(regex, replacement);\n\t\t\t}\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Determine if a mapping pattern is a regex literal surrounded by forward slashes.\n\t * Example pattern: /^foo.*bar$/\n\t * @param pattern The mapping pattern.\n\t * @returns True if the pattern looks like a regex literal.\n\t * @internal\n\t */\n\tprivate static isRegexLiteralPattern(pattern: string): boolean {\n\t\treturn pattern.length > 2 && pattern.startsWith(\"/\") && pattern.endsWith(\"/\");\n\t}\n\n\t/**\n\t * Determine if a mapping pattern should be treated as a raw regex expression.\n\t * Any pattern that contains at least one regex meta character is treated as a raw expression.\n\t * @param pattern The mapping pattern.\n\t * @returns True if the pattern contains regex syntax.\n\t * @internal\n\t */\n\tprivate static isRegexExpressionPattern(pattern: string): boolean {\n\t\treturn /[()[\\]{}+?|^$\\\\]/u.test(pattern);\n\t}\n\n\t/**\n\t * Convert a regex literal mapping pattern to a RegExp.\n\t * The surrounding forward slashes are stripped before compiling.\n\t * @param pattern The regex literal pattern, e.g. /^foo.*bar$/\n\t * @returns The RegExp instance, or undefined when the inner expression is invalid.\n\t * @internal\n\t */\n\tprivate static toRegexFromLiteralPattern(pattern: string): RegExp | undefined {\n\t\ttry {\n\t\t\treturn new RegExp(pattern.slice(1, -1));\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t}\n\n\t/**\n\t * Convert a raw regex expression mapping pattern to a RegExp anchored to full-string match.\n\t * The expression is wrapped with ^ and $ so that partial matches are not accepted.\n\t * @param pattern The raw regex expression.\n\t * @returns The RegExp instance, or undefined when the expression is invalid.\n\t * @internal\n\t */\n\tprivate static toRegexFromExpressionPattern(pattern: string): RegExp | undefined {\n\t\ttry {\n\t\t\treturn new RegExp(`^${pattern}$`);\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t}\n\n\t/**\n\t * Select and compile the appropriate RegExp for a reference mapping pattern.\n\t * Evaluation order: regex literal -> raw regex expression -> wildcard glob.\n\t * Plain strings with none of these characteristics return undefined.\n\t * @param pattern The mapping pattern.\n\t * @returns The RegExp instance, or undefined when the pattern is not pattern-based.\n\t * @internal\n\t */\n\tprivate static toRegexFromReferencePattern(pattern: string): RegExp | undefined {\n\t\tif (RegEx.isRegexLiteralPattern(pattern)) {\n\t\t\treturn RegEx.toRegexFromLiteralPattern(pattern);\n\t\t}\n\n\t\tif (RegEx.isRegexExpressionPattern(pattern)) {\n\t\t\treturn RegEx.toRegexFromExpressionPattern(pattern);\n\t\t}\n\n\t\tif (pattern.includes(\"*\")) {\n\t\t\treturn RegEx.toRegexFromWildcardPattern(pattern);\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Convert a glob wildcard pattern to a RegExp.\n\t * All regex metacharacters in the pattern are escaped first, then each * is replaced with .*.\n\t * The resulting expression is anchored with ^ and $ for full-string matching.\n\t * @param pattern The wildcard pattern, e.g. *Operation or @twin.org/*.\n\t * @returns The compiled RegExp.\n\t * @internal\n\t */\n\tprivate static toRegexFromWildcardPattern(pattern: string): RegExp {\n\t\tconst escapedPattern = pattern.replace(/[$()+./?[\\\\\\]^{|}-]/g, \"\\\\$&\");\n\t\tconst regexPattern = `^${escapedPattern.replace(/\\*/g, \".*\")}$`;\n\t\treturn new RegExp(regexPattern);\n\t}\n}\n"]}