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

package/dist/es/utils/jsonSchemaBuilder.js

@@ -34,81 +34,81 @@ export class JsonSchemaBuilder {
      * Dictionary of TypeScript utility type names to their schema mapping handlers.
      */
     static _utilityTypeHandlers = {
-        Partial: (context, typeNode) => JsonSchemaBuilder.mapPartialUtilityType(context, typeNode),
-        Required: (context, typeNode) => JsonSchemaBuilder.mapRequiredUtilityType(context, typeNode),
-        Pick: (context, typeNode) => JsonSchemaBuilder.mapPickUtilityType(context, typeNode),
-        Omit: (context, typeNode) => JsonSchemaBuilder.mapOmitUtilityType(context, typeNode),
-        Exclude: (context, typeNode) => JsonSchemaBuilder.mapExcludeUtilityType(context, typeNode),
-        Extract: (context, typeNode) => JsonSchemaBuilder.mapExtractUtilityType(context, typeNode),
-        NonNullable: (context, typeNode) => JsonSchemaBuilder.mapNonNullableUtilityType(context, typeNode),
-        Record: (context, typeNode) => JsonSchemaBuilder.mapRecordUtilityType(context, typeNode),
-        JsonLdObjectWithId: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        Partial: (context, typeNode) => UtilityTypeSchemaMapper.mapPartialUtilityType(context, typeNode),
+        Required: (context, typeNode) => UtilityTypeSchemaMapper.mapRequiredUtilityType(context, typeNode),
+        Pick: (context, typeNode) => UtilityTypeSchemaMapper.mapPickUtilityType(context, typeNode),
+        Omit: (context, typeNode) => UtilityTypeSchemaMapper.mapOmitUtilityType(context, typeNode),
+        Exclude: (context, typeNode) => UtilityTypeSchemaMapper.mapExcludeUtilityType(context, typeNode),
+        Extract: (context, typeNode) => UtilityTypeSchemaMapper.mapExtractUtilityType(context, typeNode),
+        NonNullable: (context, typeNode) => UtilityTypeSchemaMapper.mapNonNullableUtilityType(context, typeNode),
+        Record: (context, typeNode) => UtilityTypeSchemaMapper.mapRecordUtilityType(context, typeNode),
+        JsonLdObjectWithId: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["id", "@id"],
             keyToAdd: "id",
             isAddedKeyRequired: true
         }),
-        JsonLdObjectWithAtId: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithAtId: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["id", "@id"],
             keyToAdd: "@id",
             isAddedKeyRequired: true
         }),
-        JsonLdObjectWithOptionalId: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithOptionalId: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["id", "@id"],
             keyToAdd: "id",
             isAddedKeyRequired: false
         }),
-        JsonLdObjectWithOptionalAtId: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithOptionalAtId: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["id", "@id"],
             keyToAdd: "@id",
             isAddedKeyRequired: false
         }),
-        JsonLdObjectWithNoId: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithNoId: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["id"]
         }),
-        JsonLdObjectWithNoAtId: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithNoAtId: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["@id"]
         }),
-        JsonLdObjectWithType: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithType: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["type", "@type"],
             keyToAdd: "type",
             isAddedKeyRequired: true
         }),
-        JsonLdObjectWithAtType: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithAtType: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["type", "@type"],
             keyToAdd: "@type",
             isAddedKeyRequired: true
         }),
-        JsonLdObjectWithOptionalType: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithOptionalType: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["type", "@type"],
             keyToAdd: "type",
             isAddedKeyRequired: false
         }),
-        JsonLdObjectWithOptionalAtType: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithOptionalAtType: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["type", "@type"],
             keyToAdd: "@type",
             isAddedKeyRequired: false
         }),
-        JsonLdObjectWithNoType: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithNoType: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["type"]
         }),
-        JsonLdObjectWithNoAtType: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithNoAtType: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["@type"]
         }),
-        JsonLdObjectWithContext: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithContext: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["@context"],
             keyToAdd: "@context",
             isAddedKeyRequired: true
         }),
-        JsonLdObjectWithOptionalContext: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithOptionalContext: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["@context"],
             keyToAdd: "@context",
             isAddedKeyRequired: false
         }),
-        JsonLdObjectWithNoContext: (context, typeNode) => JsonSchemaBuilder.mapJsonLdObjectUtilityType(context, typeNode, {
+        JsonLdObjectWithNoContext: (context, typeNode) => UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, {
             keysToRemove: ["@context"]
         }),
-        SingleOccurrenceArray: (context, typeNode) => JsonSchemaBuilder.mapSingleOccurrenceArrayUtilityType(context, typeNode),
-        ObjectOrArray: (context, typeNode) => JsonSchemaBuilder.mapObjectOrArrayUtilityType(context, typeNode)
+        SingleOccurrenceArray: (context, typeNode) => UtilityTypeSchemaMapper.mapSingleOccurrenceArrayUtilityType(context, typeNode),
+        ObjectOrArray: (context, typeNode) => UtilityTypeSchemaMapper.mapObjectOrArrayUtilityType(context, typeNode)
     };
     /**
      * Parse all object declarations from a source file.
@@ -1337,7 +1337,7 @@ export class JsonSchemaBuilder {
         if (cachedSchemaId) {
             return cachedSchemaId;
         }
-        const declarationResult = Resolver.resolveTypeDeclarationAst(moduleSpecifier, typeName);
+        const declarationResult = Resolver.resolveTypeDeclarationAst(moduleSpecifier, typeName, context.activeSourceFile?.fileName);
         if (!declarationResult) {
             return mappedReference?.schemaId;
         }
@@ -2107,6 +2107,7 @@ export class JsonSchemaBuilder {
      * @param context The generation context.
      * @param schema The schema to expand.
      * @param declaration The interface declaration.
+     * @throws GeneralError when an extended type cannot be resolved to a schema.
      */
     static applyInterfaceExtendsSchema(context, schema, declaration) {
         const extendsClause = declaration.heritageClauses?.find(clause => clause.token === ts.SyntaxKind.ExtendsKeyword);
@@ -2132,10 +2133,22 @@ export class JsonSchemaBuilder {
                 // TypeReferenceNode is constructed here using the same expression + type
                 // arguments so the utility handler receives exactly the AST shape it expects.
                 if (JsonSchemaBuilder._utilityTypeHandlers[typeName] && ts.isIdentifier(expression)) {
-                    const syntheticTypeNode = ts.factory.createTypeReferenceNode(expression, extendedType.typeArguments);
-                    const mappedSchema = JsonSchemaBuilder.mapTypeNodeToSchema(context, syntheticTypeNode);
-                    if (mappedSchema) {
-                        allOfRefs.push(mappedSchema);
+                    const refinedBaseReference = JsonSchemaBuilder.resolveRefinementUtilityBaseRef(context, declaration, extendedType);
+                    if (refinedBaseReference) {
+                        allOfRefs.push(refinedBaseReference);
+                    }
+                    else {
+                        const syntheticTypeNode = ts.factory.createTypeReferenceNode(expression, extendedType.typeArguments);
+                        const mappedSchema = JsonSchemaBuilder.mapTypeNodeToSchema(context, syntheticTypeNode);
+                        if (mappedSchema) {
+                            allOfRefs.push(mappedSchema);
+                        }
+                        else {
+                            throw new GeneralError(JsonSchemaBuilder.CLASS_NAME, "missingTypeReferenceSchema", {
+                                typeName: extendedType.getText(),
+                                importSource: ""
+                            });
+                        }
                     }
                 }
                 else {
@@ -2149,79 +2162,101 @@ export class JsonSchemaBuilder {
         }
         if (allOfRefs.length > 0) {
             schema.allOf = allOfRefs;
+            // Extract properties defined in the derived interface to avoid duplication with expanded utility bases
+            const derivedPropertyNames = new Set();
+            for (const member of declaration.members) {
+                if (ts.isPropertySignature(member) && member.name && ts.isIdentifier(member.name)) {
+                    derivedPropertyNames.add(member.name.text);
+                }
+            }
+            // Remove redefined properties from inlined utility base schemas
+            if (derivedPropertyNames.size > 0) {
+                for (const allOfRef of allOfRefs) {
+                    if (allOfRef.properties && Is.object(allOfRef.properties)) {
+                        for (const propName of derivedPropertyNames) {
+                            delete allOfRef.properties[propName];
+                        }
+                        // Update required array to remove redefined properties
+                        if (Is.array(allOfRef.required)) {
+                            allOfRef.required = allOfRef.required.filter(req => !derivedPropertyNames.has(req));
+                        }
+                    }
+                }
+                // Ensure derived interface members are represented at the root schema level.
+                const { properties: derivedProperties, required: derivedRequired } = JsonSchemaBuilder.buildObjectMembersSchema(context, declaration.members);
+                if (Object.keys(derivedProperties).length > 0) {
+                    schema.properties = {
+                        ...(schema.properties ?? {}),
+                        ...derivedProperties
+                    };
+                }
+                if (derivedRequired.length > 0) {
+                    schema.required = [...new Set([...(schema.required ?? []), ...derivedRequired])];
+                }
+            }
         }
     }
     /**
-     * Map Partial<T> to an object schema with no required properties.
-     * @param context The generation context.
-     * @param typeNode The Partial type reference.
-     * @returns The mapped schema.
-     */
-    static mapPartialUtilityType(context, typeNode) {
-        return UtilityTypeSchemaMapper.mapPartialUtilityType(context, typeNode, (ctx, baseTypeNode) => JsonSchemaBuilder.resolveUtilityBaseObjectSchema(ctx, baseTypeNode));
-    }
-    /**
-     * Map Required<T> to an object schema with all properties required.
-     * @param context The generation context.
-     * @param typeNode The Required type reference.
-     * @returns The mapped schema.
-     */
-    static mapRequiredUtilityType(context, typeNode) {
-        return UtilityTypeSchemaMapper.mapRequiredUtilityType(context, typeNode, (ctx, baseTypeNode) => JsonSchemaBuilder.resolveUtilityBaseObjectSchema(ctx, baseTypeNode));
-    }
-    /**
-     * Map Pick<T, K> to an object schema with selected keys preserved.
+     * Resolve a direct base reference for refinement Omit patterns in interface extends clauses.
      * @param context The generation context.
-     * @param typeNode The Pick type reference.
-     * @returns The mapped schema.
-     */
-    static mapPickUtilityType(context, typeNode) {
-        return UtilityTypeSchemaMapper.mapPickUtilityType(context, typeNode, (ctx, baseTypeNode) => JsonSchemaBuilder.resolveUtilityBaseObjectSchema(ctx, baseTypeNode), (ctx, keysNode) => JsonSchemaBuilder.extractUtilityTypeKeys(ctx, keysNode));
-    }
-    /**
-     * Map Omit<T, K> to an object schema with selected keys removed.
-     * @param context The generation context.
-     * @param typeNode The Omit type reference.
-     * @returns The mapped schema.
-     */
-    static mapOmitUtilityType(context, typeNode) {
-        return UtilityTypeSchemaMapper.mapOmitUtilityType(context, typeNode, (ctx, baseTypeNode) => JsonSchemaBuilder.resolveUtilityBaseObjectSchema(ctx, baseTypeNode), (ctx, keysNode) => JsonSchemaBuilder.extractUtilityTypeKeys(ctx, keysNode));
-    }
-    /**
-     * Map Exclude<T, U> to a schema that removes U members from T.
-     * @param context The generation context.
-     * @param typeNode The Exclude type reference.
-     * @returns The mapped schema.
-     */
-    static mapExcludeUtilityType(context, typeNode) {
-        return UtilityTypeSchemaMapper.mapExcludeUtilityType(context, typeNode, (ctx, node) => JsonSchemaBuilder.mapTypeNodeToSchema(ctx, node));
-    }
-    /**
-     * Map Extract<T, U> to a schema that keeps U members from T.
-     * @param context The generation context.
-     * @param typeNode The Extract type reference.
-     * @returns The mapped schema.
-     */
-    static mapExtractUtilityType(context, typeNode) {
-        return UtilityTypeSchemaMapper.mapExtractUtilityType(context, typeNode, (ctx, node) => JsonSchemaBuilder.mapTypeNodeToSchema(ctx, node));
-    }
-    /**
-     * Map NonNullable<T> by removing null and undefined branches from T.
-     * @param context The generation context.
-     * @param typeNode The NonNullable type reference.
-     * @returns The mapped schema.
+     * @param declaration The interface declaration being mapped.
+     * @param extendedType The heritage type being processed.
+     * @returns A direct base reference when a refinement pattern is detected.
      */
-    static mapNonNullableUtilityType(context, typeNode) {
-        return UtilityTypeSchemaMapper.mapNonNullableUtilityType(context, typeNode, (ctx, node) => JsonSchemaBuilder.mapTypeNodeToSchema(ctx, node));
-    }
-    /**
-     * Map Record<K, V> to an object schema with key constraints where possible.
-     * @param context The generation context.
-     * @param typeNode The Record type reference.
-     * @returns The mapped schema.
-     */
-    static mapRecordUtilityType(context, typeNode) {
-        return UtilityTypeSchemaMapper.mapRecordUtilityType(context, typeNode, (ctx, node) => JsonSchemaBuilder.mapTypeNodeToSchema(ctx, node));
+    static resolveRefinementUtilityBaseRef(context, declaration, extendedType) {
+        const expression = extendedType.expression;
+        if (!ts.isIdentifier(expression) || expression.text !== "Omit") {
+            return undefined;
+        }
+        const baseTypeNode = extendedType.typeArguments?.[0];
+        if (!baseTypeNode || !ts.isTypeReferenceNode(baseTypeNode) || baseTypeNode.typeArguments) {
+            return undefined;
+        }
+        const omittedKeys = JsonSchemaBuilder.extractUtilityTypeKeys(context, extendedType.typeArguments?.[1]);
+        if (omittedKeys.length === 0) {
+            return undefined;
+        }
+        const propertyNames = new Set();
+        const optionalPropertyNames = new Set();
+        for (const member of declaration.members) {
+            if (ts.isPropertySignature(member) && member.name) {
+                if (ts.isIdentifier(member.name)) {
+                    propertyNames.add(member.name.text);
+                    if (member.questionToken) {
+                        optionalPropertyNames.add(member.name.text);
+                    }
+                }
+                else if (ts.isStringLiteral(member.name) || ts.isNumericLiteral(member.name)) {
+                    propertyNames.add(member.name.text);
+                    if (member.questionToken) {
+                        optionalPropertyNames.add(member.name.text);
+                    }
+                }
+            }
+        }
+        // Ensure all omitted keys are redefined in the derived interface
+        if (!omittedKeys.every(omittedKey => propertyNames.has(omittedKey))) {
+            return undefined;
+        }
+        // Ensure ONLY omitted keys are being redefined (no extra properties are being added/redefined)
+        const omittedKeySet = new Set(omittedKeys);
+        if (!Array.from(propertyNames).every(propName => omittedKeySet.has(propName))) {
+            return undefined;
+        }
+        const baseTypeName = ts.isIdentifier(baseTypeNode.typeName)
+            ? baseTypeNode.typeName.text
+            : baseTypeNode.typeName.right.text;
+        const baseSchema = JsonSchemaBuilder.resolveObjectTypeSchemaForUtility(context, baseTypeName);
+        const baseRequiredKeys = new Set((Is.array(baseSchema?.required) ? baseSchema.required : []).filter((requiredKey) => Is.string(requiredKey)));
+        const doesReverseOptionalityForRequiredBaseKey = omittedKeys.some(omittedKey => optionalPropertyNames.has(omittedKey) && baseRequiredKeys.has(omittedKey));
+        if (doesReverseOptionalityForRequiredBaseKey) {
+            return undefined;
+        }
+        const title = StringHelper.stripPrefix(baseTypeName);
+        const existingSchemaId = JsonSchemaBuilder.findExistingSchemaIdByTitle(context, title);
+        return {
+            $ref: existingSchemaId ?? `${context.namespace}${title}`
+        };
     }
     /**
      * Determine whether a type node represents null or undefined.
@@ -2266,19 +2301,6 @@ export class JsonSchemaBuilder {
         }
         return [];
     }
-    /**
-     * Map JsonLdObject utility types using key-removal and optional key-addition rules.
-     * @param context The generation context.
-     * @param typeNode The JsonLdObject utility type reference.
-     * @param options Mapping options.
-     * @param options.keysToRemove Keys to remove from the base schema.
-     * @param options.keyToAdd Optional key to add to the base schema.
-     * @param options.isAddedKeyRequired Whether the added key should be required.
-     * @returns The mapped schema.
-     */
-    static mapJsonLdObjectUtilityType(context, typeNode, options) {
-        return UtilityTypeSchemaMapper.mapJsonLdObjectUtilityType(context, typeNode, options, (ctx, baseTypeNode) => JsonSchemaBuilder.resolveUtilityBaseObjectSchema(ctx, baseTypeNode), (ctx, node) => JsonSchemaBuilder.mapTypeNodeToSchema(ctx, node));
-    }
     /**
      * Resolve a default schema for JsonLdObject utility key additions when the type argument is omitted.
      * @param baseSchema The base object schema.
@@ -2352,24 +2374,6 @@ export class JsonSchemaBuilder {
         }
         return fallbackSchema;
     }
-    /**
-     * Map ObjectOrArray<T> to a schema accepting T or T[].
-     * @param context The generation context.
-     * @param typeNode The ObjectOrArray type reference.
-     * @returns The mapped schema.
-     */
-    static mapObjectOrArrayUtilityType(context, typeNode) {
-        return UtilityTypeSchemaMapper.mapObjectOrArrayUtilityType(context, typeNode, (ctx, node) => JsonSchemaBuilder.mapTypeNodeToSchema(ctx, node));
-    }
-    /**
-     * Map SingleOccurrenceArray<T, U> to a non-empty array containing exactly one U.
-     * @param context The generation context.
-     * @param typeNode The SingleOccurrenceArray type reference.
-     * @returns The mapped schema.
-     */
-    static mapSingleOccurrenceArrayUtilityType(context, typeNode) {
-        return UtilityTypeSchemaMapper.mapSingleOccurrenceArrayUtilityType(context, typeNode, (ctx, node) => JsonSchemaBuilder.mapTypeNodeToSchema(ctx, node));
-    }
     /**
      * Add a comment to schemas inlined for utility type transformations.
      * @param schema The schema to annotate.
@@ -2478,9 +2482,16 @@ export class JsonSchemaBuilder {
      * @returns The resolved object schema.
      */
     static resolveMappedUtilityBaseObjectSchema(context, mappedSchema) {
-        if (mappedSchema.type === "object" && mappedSchema.properties) {
+        if (mappedSchema.type === "object") {
             return ObjectHelper.clone(mappedSchema);
         }
+        if (Is.array(mappedSchema.allOf) && mappedSchema.allOf.length > 0) {
+            const expandedSchema = JsonSchemaBuilder.expandAllOfReferences(context, ObjectHelper.clone(mappedSchema), mappedSchema.title);
+            if (expandedSchema.type === "object" || expandedSchema.properties) {
+                expandedSchema.type ??= "object";
+                return expandedSchema;
+            }
+        }
         if (mappedSchema.$ref) {
             for (const packageSchemaEntries of Object.values(context.schemas)) {
                 for (const referencedSchema of Object.values(packageSchemaEntries)) {
@@ -2680,7 +2691,7 @@ export class JsonSchemaBuilder {
         const candidateTypeNames = [`I${schemaTitle}`, schemaTitle];
         for (const moduleSpecifier of moduleSpecifiers) {
             for (const candidateTypeName of candidateTypeNames) {
-                const declarationResult = Resolver.resolveTypeDeclarationAst(moduleSpecifier, candidateTypeName);
+                const declarationResult = Resolver.resolveTypeDeclarationAst(moduleSpecifier, candidateTypeName, context.activeSourceFile?.fileName);
                 if (declarationResult) {
                     const mappedReference = JsonSchemaBuilder.resolveReferenceMappingTarget(context, moduleSpecifier, candidateTypeName);
                     const externalContext = {
@@ -2803,7 +2814,7 @@ export class JsonSchemaBuilder {
                 }
                 return undefined;
             }
-            const declarationResult = Resolver.resolveTypeDeclarationAst(moduleSpecifier, candidateTypeName);
+            const declarationResult = Resolver.resolveTypeDeclarationAst(moduleSpecifier, candidateTypeName, context.activeSourceFile?.fileName);
             if (!declarationResult) {
                 return undefined;
             }
@@ -3229,7 +3240,7 @@ export class JsonSchemaBuilder {
             return cachedSchemaId;
         }
         const mappedReference = JsonSchemaBuilder.resolveReferenceMappingTarget(context, moduleSpecifier, typeName);
-        const declarationResult = Resolver.resolveTypeDeclarationAst(moduleSpecifier, typeName);
+        const declarationResult = Resolver.resolveTypeDeclarationAst(moduleSpecifier, typeName, context.activeSourceFile?.fileName);
         if (!declarationResult) {
             return mappedReference?.schemaId;
         }