@twin.org/tools-core 0.0.3-next.16 → 0.0.3-next.18

package/dist/es/utils/typeScriptToSchema.js

@@ -4,7 +4,6 @@ import { Is, StringHelper } from "@twin.org/core";
 import { FileUtils } from "./fileUtils.js";
 import { JsonSchemaBuilder } from "./jsonSchemaBuilder.js";
 import { Resolver } from "./resolver.js";
-import { Utility } from "./utility.js";
 /**
  * Class for converting TypeScript types to JSON Schema.
  */
@@ -54,7 +53,7 @@ export class TypeScriptToSchema {
                 }
             }
         }
-        else if (Utility.isTypeNameInput(sourceFileOrTypeName)) {
+        else if (this.isTypeNameInput(sourceFileOrTypeName)) {
             const declarationResult = Resolver.resolveTypeDeclarationAst(context.packageName, sourceFileOrTypeName);
             if (declarationResult) {
                 generatedTitles = JsonSchemaBuilder.parseAllObjectSchemas(context, declarationResult.sourceFile.fileName, declarationResult.sourceFile.getFullText(), visitedFiles);
@@ -70,7 +69,7 @@ export class TypeScriptToSchema {
                 generatedSchemas[generatedTitle] = generatedSchema;
             }
         }
-        if (Utility.isTypeNameInput(sourceFileOrTypeName)) {
+        if (this.isTypeNameInput(sourceFileOrTypeName)) {
             const requestedTitle = StringHelper.stripPrefix(sourceFileOrTypeName);
             const requestedSchema = context.schemas[context.packageName][requestedTitle];
             if (requestedSchema) {
@@ -98,5 +97,16 @@ export class TypeScriptToSchema {
         const packagePathNoTrailingSlash = `/node_modules/${normalisedPackageName}`;
         return sourcePaths.some(sourcePath => sourcePath.includes(packagePath) || sourcePath.endsWith(packagePathNoTrailingSlash));
     }
+    /**
+     * Determine whether an input value is a valid TypeScript type identifier.
+     * An identifier must start with a letter, underscore, or dollar sign and contain only
+     * alphanumerics, underscores, or dollar signs thereafter.
+     * @param value The value to inspect.
+     * @returns True if the value looks like a type name.
+     * @internal
+     */
+    isTypeNameInput(value) {
+        return /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(value);
+    }
 }
 //# sourceMappingURL=typeScriptToSchema.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"typeScriptToSchema.js","sourceRoot":"","sources":["../../../src/utils/typeScriptToSchema.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is, StringHelper } from \"@twin.org/core\";\nimport type { IJsonSchema } from \"@twin.org/tools-models\";\nimport { FileUtils } from \"./fileUtils.js\";\nimport { JsonSchemaBuilder } from \"./jsonSchemaBuilder.js\";\nimport { Resolver } from \"./resolver.js\";\nimport { Utility } from \"./utility.js\";\nimport type { ITypeScriptToSchemaContext } from \"../models/ITypeScriptToSchemaContext.js\";\nimport type { ITypeScriptToSchemaOptions } from \"../models/ITypeScriptToSchemaOptions.js\";\n\n/**\n * Class for converting TypeScript types to JSON Schema.\n */\nexport class TypeScriptToSchema {\n\t/**\n\t * Generates a JSON schema from a TypeScript source file or type name.\n\t * @param namespace The schema namespace.\n\t * @param packageName The package name.\n\t * @param schemas The package schema map.\n\t * @param sourceFileOrTypeName The source file to process or type name to resolve.\n\t * @param options Additional generation options.\n\t * @returns The generated JSON schemas indexed by title.\n\t */\n\tpublic async generateSchema(\n\t\tnamespace: string,\n\t\tpackageName: string,\n\t\tschemas: { [id: string]: { [id: string]: IJsonSchema } },\n\t\tsourceFileOrTypeName: string,\n\t\toptions?: ITypeScriptToSchemaOptions\n\t): Promise<{ [id: string]: IJsonSchema }> {\n\t\tconst suppressPackageWarnings = (options?.suppressPackageWarnings ?? [])\n\t\t\t.filter(packageNameToSkip => Is.stringValue(packageNameToSkip))\n\t\t\t.map(packageNameToSkip => packageNameToSkip.toLowerCase());\n\t\tconst filteredOptions: ITypeScriptToSchemaOptions = {\n\t\t\t...options,\n\t\t\tonDiagnostic: diagnostic => {\n\t\t\t\tif (\n\t\t\t\t\tsuppressPackageWarnings.some(packageToSkip =>\n\t\t\t\t\t\tthis.isDiagnosticFromPackage(diagnostic.path, diagnostic.fileName, packageToSkip)\n\t\t\t\t\t)\n\t\t\t\t) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\toptions?.onDiagnostic?.(diagnostic);\n\t\t\t}\n\t\t};\n\n\t\tconst context: ITypeScriptToSchemaContext = {\n\t\t\tnamespace,\n\t\t\tpackageName,\n\t\t\tschemas,\n\t\t\toptions: filteredOptions\n\t\t};\n\n\t\tlet generatedTitles: string[] = [];\n\t\tcontext.schemas[context.packageName] ??= {};\n\t\tconst visitedFiles: string[] = [];\n\t\tconst sourceFiles = FileUtils.resolveSourceFiles(sourceFileOrTypeName);\n\n\t\tif (sourceFiles.length > 0) {\n\t\t\tfor (const sourceFilePath of sourceFiles) {\n\t\t\t\tconst source = FileUtils.readFile(sourceFilePath);\n\t\t\t\tif (source) {\n\t\t\t\t\tconst parsedTitles = JsonSchemaBuilder.parseAllObjectSchemas(\n\t\t\t\t\t\tcontext,\n\t\t\t\t\t\tsourceFilePath,\n\t\t\t\t\t\tsource,\n\t\t\t\t\t\tvisitedFiles\n\t\t\t\t\t);\n\t\t\t\t\tfor (const parsedTitle of parsedTitles) {\n\t\t\t\t\t\tif (!generatedTitles.includes(parsedTitle)) {\n\t\t\t\t\t\t\tgeneratedTitles.push(parsedTitle);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (Utility.isTypeNameInput(sourceFileOrTypeName)) {\n\t\t\tconst declarationResult = Resolver.resolveTypeDeclarationAst(\n\t\t\t\tcontext.packageName,\n\t\t\t\tsourceFileOrTypeName\n\t\t\t);\n\t\t\tif (declarationResult) {\n\t\t\t\tgeneratedTitles = JsonSchemaBuilder.parseAllObjectSchemas(\n\t\t\t\t\tcontext,\n\t\t\t\t\tdeclarationResult.sourceFile.fileName,\n\t\t\t\t\tdeclarationResult.sourceFile.getFullText(),\n\t\t\t\t\tvisitedFiles\n\t\t\t\t);\n\t\t\t}\n\t\t} else {\n\t\t\treturn {};\n\t\t}\n\n\t\tconst generatedSchemas: { [id: string]: IJsonSchema } = {};\n\t\tfor (const generatedTitle of generatedTitles) {\n\t\t\tconst generatedSchema = context.schemas[context.packageName][generatedTitle];\n\t\t\tif (generatedSchema) {\n\t\t\t\tgeneratedSchemas[generatedTitle] = generatedSchema;\n\t\t\t}\n\t\t}\n\n\t\tif (Utility.isTypeNameInput(sourceFileOrTypeName)) {\n\t\t\tconst requestedTitle = StringHelper.stripPrefix(sourceFileOrTypeName);\n\t\t\tconst requestedSchema = context.schemas[context.packageName][requestedTitle];\n\t\t\tif (requestedSchema) {\n\t\t\t\tgeneratedSchemas[requestedTitle] = requestedSchema;\n\t\t\t}\n\t\t}\n\n\t\treturn generatedSchemas;\n\t}\n\n\t/**\n\t * Determine if a diagnostic originates from a specific package.\n\t * @param path The schema or source path associated with the diagnostic.\n\t * @param fileName The source filename associated with the diagnostic.\n\t * @param packageName The package name to check, e.g. jose.\n\t * @returns True if the diagnostic originated from the package.\n\t */\n\tpublic isDiagnosticFromPackage(\n\t\tpath: string,\n\t\tfileName: string | undefined,\n\t\tpackageName: string\n\t): boolean {\n\t\tif (!Is.stringValue(packageName)) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst sourcePaths = [fileName, path]\n\t\t\t.filter((value): value is string => Is.stringValue(value))\n\t\t\t.map(value => value.replace(/\\\\/g, \"/\").toLowerCase());\n\t\tconst normalisedPackageName = packageName.toLowerCase();\n\t\tconst packagePath = `/node_modules/${normalisedPackageName}/`;\n\t\tconst packagePathNoTrailingSlash = `/node_modules/${normalisedPackageName}`;\n\n\t\treturn sourcePaths.some(\n\t\t\tsourcePath =>\n\t\t\t\tsourcePath.includes(packagePath) || sourcePath.endsWith(packagePathNoTrailingSlash)\n\t\t);\n\t}\n}\n"]}
+{"version":3,"file":"typeScriptToSchema.js","sourceRoot":"","sources":["../../../src/utils/typeScriptToSchema.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is, StringHelper } from \"@twin.org/core\";\nimport type { IJsonSchema } from \"@twin.org/tools-models\";\nimport { FileUtils } from \"./fileUtils.js\";\nimport { JsonSchemaBuilder } from \"./jsonSchemaBuilder.js\";\nimport { Resolver } from \"./resolver.js\";\nimport type { ITypeScriptToSchemaContext } from \"../models/ITypeScriptToSchemaContext.js\";\nimport type { ITypeScriptToSchemaOptions } from \"../models/ITypeScriptToSchemaOptions.js\";\n\n/**\n * Class for converting TypeScript types to JSON Schema.\n */\nexport class TypeScriptToSchema {\n\t/**\n\t * Generates a JSON schema from a TypeScript source file or type name.\n\t * @param namespace The schema namespace.\n\t * @param packageName The package name.\n\t * @param schemas The package schema map.\n\t * @param sourceFileOrTypeName The source file to process or type name to resolve.\n\t * @param options Additional generation options.\n\t * @returns The generated JSON schemas indexed by title.\n\t */\n\tpublic async generateSchema(\n\t\tnamespace: string,\n\t\tpackageName: string,\n\t\tschemas: { [id: string]: { [id: string]: IJsonSchema } },\n\t\tsourceFileOrTypeName: string,\n\t\toptions?: ITypeScriptToSchemaOptions\n\t): Promise<{ [id: string]: IJsonSchema }> {\n\t\tconst suppressPackageWarnings = (options?.suppressPackageWarnings ?? [])\n\t\t\t.filter(packageNameToSkip => Is.stringValue(packageNameToSkip))\n\t\t\t.map(packageNameToSkip => packageNameToSkip.toLowerCase());\n\t\tconst filteredOptions: ITypeScriptToSchemaOptions = {\n\t\t\t...options,\n\t\t\tonDiagnostic: diagnostic => {\n\t\t\t\tif (\n\t\t\t\t\tsuppressPackageWarnings.some(packageToSkip =>\n\t\t\t\t\t\tthis.isDiagnosticFromPackage(diagnostic.path, diagnostic.fileName, packageToSkip)\n\t\t\t\t\t)\n\t\t\t\t) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\toptions?.onDiagnostic?.(diagnostic);\n\t\t\t}\n\t\t};\n\n\t\tconst context: ITypeScriptToSchemaContext = {\n\t\t\tnamespace,\n\t\t\tpackageName,\n\t\t\tschemas,\n\t\t\toptions: filteredOptions\n\t\t};\n\n\t\tlet generatedTitles: string[] = [];\n\t\tcontext.schemas[context.packageName] ??= {};\n\t\tconst visitedFiles: string[] = [];\n\t\tconst sourceFiles = FileUtils.resolveSourceFiles(sourceFileOrTypeName);\n\n\t\tif (sourceFiles.length > 0) {\n\t\t\tfor (const sourceFilePath of sourceFiles) {\n\t\t\t\tconst source = FileUtils.readFile(sourceFilePath);\n\t\t\t\tif (source) {\n\t\t\t\t\tconst parsedTitles = JsonSchemaBuilder.parseAllObjectSchemas(\n\t\t\t\t\t\tcontext,\n\t\t\t\t\t\tsourceFilePath,\n\t\t\t\t\t\tsource,\n\t\t\t\t\t\tvisitedFiles\n\t\t\t\t\t);\n\t\t\t\t\tfor (const parsedTitle of parsedTitles) {\n\t\t\t\t\t\tif (!generatedTitles.includes(parsedTitle)) {\n\t\t\t\t\t\t\tgeneratedTitles.push(parsedTitle);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (this.isTypeNameInput(sourceFileOrTypeName)) {\n\t\t\tconst declarationResult = Resolver.resolveTypeDeclarationAst(\n\t\t\t\tcontext.packageName,\n\t\t\t\tsourceFileOrTypeName\n\t\t\t);\n\t\t\tif (declarationResult) {\n\t\t\t\tgeneratedTitles = JsonSchemaBuilder.parseAllObjectSchemas(\n\t\t\t\t\tcontext,\n\t\t\t\t\tdeclarationResult.sourceFile.fileName,\n\t\t\t\t\tdeclarationResult.sourceFile.getFullText(),\n\t\t\t\t\tvisitedFiles\n\t\t\t\t);\n\t\t\t}\n\t\t} else {\n\t\t\treturn {};\n\t\t}\n\n\t\tconst generatedSchemas: { [id: string]: IJsonSchema } = {};\n\t\tfor (const generatedTitle of generatedTitles) {\n\t\t\tconst generatedSchema = context.schemas[context.packageName][generatedTitle];\n\t\t\tif (generatedSchema) {\n\t\t\t\tgeneratedSchemas[generatedTitle] = generatedSchema;\n\t\t\t}\n\t\t}\n\n\t\tif (this.isTypeNameInput(sourceFileOrTypeName)) {\n\t\t\tconst requestedTitle = StringHelper.stripPrefix(sourceFileOrTypeName);\n\t\t\tconst requestedSchema = context.schemas[context.packageName][requestedTitle];\n\t\t\tif (requestedSchema) {\n\t\t\t\tgeneratedSchemas[requestedTitle] = requestedSchema;\n\t\t\t}\n\t\t}\n\n\t\treturn generatedSchemas;\n\t}\n\n\t/**\n\t * Determine if a diagnostic originates from a specific package.\n\t * @param path The schema or source path associated with the diagnostic.\n\t * @param fileName The source filename associated with the diagnostic.\n\t * @param packageName The package name to check, e.g. jose.\n\t * @returns True if the diagnostic originated from the package.\n\t */\n\tpublic isDiagnosticFromPackage(\n\t\tpath: string,\n\t\tfileName: string | undefined,\n\t\tpackageName: string\n\t): boolean {\n\t\tif (!Is.stringValue(packageName)) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst sourcePaths = [fileName, path]\n\t\t\t.filter((value): value is string => Is.stringValue(value))\n\t\t\t.map(value => value.replace(/\\\\/g, \"/\").toLowerCase());\n\t\tconst normalisedPackageName = packageName.toLowerCase();\n\t\tconst packagePath = `/node_modules/${normalisedPackageName}/`;\n\t\tconst packagePathNoTrailingSlash = `/node_modules/${normalisedPackageName}`;\n\n\t\treturn sourcePaths.some(\n\t\t\tsourcePath =>\n\t\t\t\tsourcePath.includes(packagePath) || sourcePath.endsWith(packagePathNoTrailingSlash)\n\t\t);\n\t}\n\n\t/**\n\t * Determine whether an input value is a valid TypeScript type identifier.\n\t * An identifier must start with a letter, underscore, or dollar sign and contain only\n\t * alphanumerics, underscores, or dollar signs thereafter.\n\t * @param value The value to inspect.\n\t * @returns True if the value looks like a type name.\n\t * @internal\n\t */\n\tprivate isTypeNameInput(value: string): boolean {\n\t\treturn /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(value);\n\t}\n}\n"]}

package/dist/types/index.d.ts

@@ -16,5 +16,5 @@ export * from "./utils/regEx.js";
 export * from "./utils/resolver.js";
 export * from "./utils/templateLiteralPatternBuilder.js";
 export * from "./utils/typeScriptToSchema.js";
-export * from "./utils/utility.js";
+export * from "./utils/jsDoc.js";
 export * from "./utils/utilityTypeSchemaMapper.js";

package/dist/types/utils/{utility.d.ts → jsDoc.d.ts}

@@ -1,27 +1,8 @@
 import * as ts from "typescript";
 /**
- * General-purpose utility methods for working with TypeScript AST nodes.
- *
- * Enum-related helpers live in TypeScriptEnum.
- * Reference-mapping regex helpers live in TypeScriptRegEx.
+ * General-purpose utility methods for working with JsDoc.
  */
-export declare class Utility {
-    /**
-     * Determine whether an input value is a valid TypeScript type identifier.
-     * An identifier must start with a letter, underscore, or dollar sign and contain only
-     * alphanumerics, underscores, or dollar signs thereafter.
-     * @param value The value to inspect.
-     * @returns True if the value looks like a type name.
-     */
-    static isTypeNameInput(value: string): boolean;
-    /**
-     * Extract the inner type node from a named or rest tuple element.
-     * Named tuple members and rest elements both wrap an inner type node; this unwraps them.
-     * Plain type nodes are returned as-is.
-     * @param element The tuple element.
-     * @returns The inner type node.
-     */
-    static extractTupleElementType(element: ts.TypeNode): ts.TypeNode | undefined;
+export declare class JsDoc {
     /**
      * Extract the JSDoc description comment for an AST node.
      * Only top-level JSDoc block comments are considered; inline tags are ignored.
@@ -47,6 +28,13 @@ export declare class Utility {
     static getNodeTags(node: ts.Node, tagName: string): {
         [id: string]: string;
     };
+    /**
+     * Read the plain comment text for the first matching JSDoc tag on a node.
+     * @param node The node to inspect.
+     * @param tagName The tag name to filter by (e.g., 'default').
+     * @returns The trimmed comment text, or undefined when absent.
+     */
+    static getNodeTagComment(node: ts.Node, tagName: string): string | undefined;
     /**
      * Parse a custom JSDoc tag value into JSON-compatible data.
      * Values that begin with a JSON token character ({, [, ", true, false, null) or look like a

package/dist/types/utils/jsonSchemaBuilder.d.ts

@@ -112,6 +112,14 @@ export declare class JsonSchemaBuilder {
      * @returns The mapped schema.
      */
     static mapTypeNodeToSchema(context: ITypeScriptToSchemaContext, typeNode: ts.TypeNode): IJsonSchema | undefined;
+    /**
+     * Determine whether a union of primitive keyword branches is pairwise disjoint.
+     * @param unionTypeNode The union node being mapped.
+     * @param unionTypeNodes The original union branch type nodes.
+     * @param unionSchemas The mapped union branch schemas.
+     * @returns True if every branch is a primitive keyword schema and no branches overlap.
+     */
+    static isDisjointPrimitiveKeywordUnion(unionTypeNode: ts.UnionTypeNode, unionTypeNodes: ts.NodeArray<ts.TypeNode>, unionSchemas: IJsonSchema[]): boolean;
     /**
      * Determine whether a union of schemas represents mutually exclusive object branches.
      * @param context The generation context.
@@ -718,4 +726,12 @@ export declare class JsonSchemaBuilder {
      * @returns The schema key.
      */
     static mapJsonSchemaTagKey(key: string): string;
+    /**
+     * Extract the inner type node from a named or rest tuple element.
+     * Named tuple members and rest elements both wrap an inner type node; this unwraps them.
+     * Plain type nodes are returned as-is.
+     * @param element The tuple element.
+     * @returns The inner type node.
+     */
+    static extractTupleElementType(element: ts.TypeNode): ts.TypeNode | undefined;
 }

package/docs/changelog.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.0.3-next.18](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.17...tools-core-v0.0.3-next.18) (2026-03-19)
+
+
+### Features
+
+* add jsdoc default value to schema ([7886a84](https://github.com/twinfoundation/tools/commit/7886a84961e692d2054f223e2e99205a654b76a6))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tools-models bumped from 0.0.3-next.17 to 0.0.3-next.18
+
+## [0.0.3-next.17](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.16...tools-core-v0.0.3-next.17) (2026-03-19)
+
+
+### Features
+
+* improve discriminated unions ([9c36ea7](https://github.com/twinfoundation/tools/commit/9c36ea7283230089ff19085ddc4b4c30a4e3f8a2))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tools-models bumped from 0.0.3-next.16 to 0.0.3-next.17
+
 ## [0.0.3-next.16](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.15...tools-core-v0.0.3-next.16) (2026-03-19)
 
 

package/docs/reference/classes/{Utility.md → JsDoc.md}

@@ -1,70 +1,19 @@
-# Class: Utility
+# Class: JsDoc
 
-General-purpose utility methods for working with TypeScript AST nodes.
-
-Enum-related helpers live in TypeScriptEnum.
-Reference-mapping regex helpers live in TypeScriptRegEx.
+General-purpose utility methods for working with JsDoc.
 
 ## Constructors
 
 ### Constructor
 
-> **new Utility**(): `Utility`
+> **new JsDoc**(): `JsDoc`
 
 #### Returns
 
-`Utility`
+`JsDoc`
 
 ## Methods
 
-### isTypeNameInput() {#istypenameinput}
-
-> `static` **isTypeNameInput**(`value`): `boolean`
-
-Determine whether an input value is a valid TypeScript type identifier.
-An identifier must start with a letter, underscore, or dollar sign and contain only
-alphanumerics, underscores, or dollar signs thereafter.
-
-#### Parameters
-
-##### value
-
-`string`
-
-The value to inspect.
-
-#### Returns
-
-`boolean`
-
-True if the value looks like a type name.
-
-***
-
-### extractTupleElementType() {#extracttupleelementtype}
-
-> `static` **extractTupleElementType**(`element`): `TypeNode` \| `undefined`
-
-Extract the inner type node from a named or rest tuple element.
-Named tuple members and rest elements both wrap an inner type node; this unwraps them.
-Plain type nodes are returned as-is.
-
-#### Parameters
-
-##### element
-
-`TypeNode`
-
-The tuple element.
-
-#### Returns
-
-`TypeNode` \| `undefined`
-
-The inner type node.
-
-***
-
 ### getNodeJsDocDescription() {#getnodejsdocdescription}
 
 > `static` **getNodeJsDocDescription**(`node`): `string` \| `undefined`
@@ -141,6 +90,34 @@ The extracted key/value pairs.
 
 ***
 
+### getNodeTagComment() {#getnodetagcomment}
+
+> `static` **getNodeTagComment**(`node`, `tagName`): `string` \| `undefined`
+
+Read the plain comment text for the first matching JSDoc tag on a node.
+
+#### Parameters
+
+##### node
+
+`Node`
+
+The node to inspect.
+
+##### tagName
+
+`string`
+
+The tag name to filter by (e.g., 'default').
+
+#### Returns
+
+`string` \| `undefined`
+
+The trimmed comment text, or undefined when absent.
+
+***
+
 ### parseTagValue() {#parsetagvalue}
 
 > `static` **parseTagValue**(`value`): `unknown`

package/docs/reference/classes/JsonSchemaBuilder.md

@@ -376,6 +376,40 @@ The mapped schema.
 
 ***
 
+### isDisjointPrimitiveKeywordUnion() {#isdisjointprimitivekeywordunion}
+
+> `static` **isDisjointPrimitiveKeywordUnion**(`unionTypeNode`, `unionTypeNodes`, `unionSchemas`): `boolean`
+
+Determine whether a union of primitive keyword branches is pairwise disjoint.
+
+#### Parameters
+
+##### unionTypeNode
+
+`UnionTypeNode`
+
+The union node being mapped.
+
+##### unionTypeNodes
+
+`NodeArray`\<`TypeNode`\>
+
+The original union branch type nodes.
+
+##### unionSchemas
+
+`IJsonSchema`[]
+
+The mapped union branch schemas.
+
+#### Returns
+
+`boolean`
+
+True if every branch is a primitive keyword schema and no branches overlap.
+
+***
+
 ### isNeverDiscriminatedObjectUnion() {#isneverdiscriminatedobjectunion}
 
 > `static` **isNeverDiscriminatedObjectUnion**(`context`, `unionTypeNodes`, `unionSchemas`): `boolean`
@@ -2770,3 +2804,27 @@ The raw tag key.
 `string`
 
 The schema key.
+
+***
+
+### extractTupleElementType() {#extracttupleelementtype}
+
+> `static` **extractTupleElementType**(`element`): `TypeNode` \| `undefined`
+
+Extract the inner type node from a named or rest tuple element.
+Named tuple members and rest elements both wrap an inner type node; this unwraps them.
+Plain type nodes are returned as-is.
+
+#### Parameters
+
+##### element
+
+`TypeNode`
+
+The tuple element.
+
+#### Returns
+
+`TypeNode` \| `undefined`
+
+The inner type node.

package/docs/reference/index.md

@@ -10,6 +10,7 @@
 - [ImportTypeQuerySchemaResolver](classes/ImportTypeQuerySchemaResolver.md)
 - [IndexSignaturePatternResolver](classes/IndexSignaturePatternResolver.md)
 - [IntersectionSchemaMerger](classes/IntersectionSchemaMerger.md)
+- [JsDoc](classes/JsDoc.md)
 - [JsonSchemaBuilder](classes/JsonSchemaBuilder.md)
 - [MappedTypeSchemaResolver](classes/MappedTypeSchemaResolver.md)
 - [ObjectTransformer](classes/ObjectTransformer.md)
@@ -17,7 +18,6 @@
 - [Resolver](classes/Resolver.md)
 - [TemplateLiteralPatternBuilder](classes/TemplateLiteralPatternBuilder.md)
 - [TypeScriptToSchema](classes/TypeScriptToSchema.md)
-- [Utility](classes/Utility.md)
 - [UtilityTypeSchemaMapper](classes/UtilityTypeSchemaMapper.md)
 
 ## Interfaces

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/tools-core",
-	"version": "0.0.3-next.16",
+	"version": "0.0.3-next.18",
 	"description": "Shared utilities and models for tooling packages",
 	"repository": {
 		"type": "git",
@@ -16,7 +16,7 @@
 	"dependencies": {
 		"@twin.org/core": "next",
 		"@twin.org/nameof": "next",
-		"@twin.org/tools-models": "0.0.3-next.16",
+		"@twin.org/tools-models": "0.0.3-next.18",
 		"glob": "13.0.6"
 	},
 	"main": "./dist/es/index.js",

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

@@ -1 +0,0 @@
-{"version":3,"file":"utility.js","sourceRoot":"","sources":["../../../src/utils/utility.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,OAAO,OAAO;IACnB;;;;;;OAMG;IACI,MAAM,CAAC,eAAe,CAAC,KAAa;QAC1C,OAAO,6BAA6B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,uBAAuB,CAAC,OAAoB;QACzD,2EAA2E;QAC3E,IAAI,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,OAAO,OAAO,CAAC,IAAI,CAAC;QACrB,CAAC;QAED,kFAAkF;QAClF,IAAI,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;YAChC,OAAO,OAAO,CAAC,IAAI,CAAC;QACrB,CAAC;QAED,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,uBAAuB,CAAC,IAAa;QAClD,kEAAkE;QAClE,MAAM,UAAU,GAAG,EAAE;aACnB,uBAAuB,CAAC,IAAI,CAAC;aAC7B,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;QACnD,MAAM,WAAW,GAAG,UAAU;aAC5B,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,qBAAqB,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC;aACrE,IAAI,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAEnD,IAAI,WAAW,EAAE,CAAC;YACjB,OAAO,WAAW,CAAC;QACpB,CAAC;QAED,OAAO,SAAS,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,sBAAsB,CAAC,QAAqB;QACzD,IAAI,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACjC,OAAO,QAAQ,CAAC,OAAO,CAAC;QACzB,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACrC,OAAO,QAAQ,CAAC,OAAO;iBACrB,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;iBACtB,IAAI,CAAC,EAAE,CAAC;iBACR,IAAI,EAAE,CAAC;QACV,CAAC;QAED,OAAO,SAAS,CAAC;IAClB,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,WAAW,CAAC,IAAa,EAAE,OAAe;QACvD,MAAM,MAAM,GAA6B,EAAE,CAAC;QAC5C,KAAK,MAAM,QAAQ,IAAI,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9C,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACvC,MAAM,WAAW,GAAG,OAAO,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC;gBAC7D,IAAI,WAAW,EAAE,CAAC;oBACjB,MAAM,cAAc,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;oBAChD,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;wBACxB,MAAM,GAAG,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,IAAI,EAAE,CAAC;wBACxD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;wBAC3D,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;4BACpB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;wBACrB,CAAC;oBACF,CAAC;gBACF,CAAC;YACF,CAAC;QACF,CAAC;QAED,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,aAAa,CAAC,KAAa;QACxC,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,EAAE,CAAC;QACX,CAAC;QAED,MAAM,mBAAmB,GACxB,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC;YAC5B,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC;YAC5B,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC;YAC5B,YAAY,KAAK,MAAM;YACvB,YAAY,KAAK,OAAO;YACxB,YAAY,KAAK,MAAM;YACvB,kBAAkB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAEvC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC1B,OAAO,YAAY,CAAC;QACrB,CAAC;QAED,IAAI,CAAC;YACJ,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,YAAY,CAAC;QACrB,CAAC;IACF,CAAC;CACD","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is } from \"@twin.org/core\";\nimport * as ts from \"typescript\";\n\n/**\n * General-purpose utility methods for working with TypeScript AST nodes.\n *\n * Enum-related helpers live in TypeScriptEnum.\n * Reference-mapping regex helpers live in TypeScriptRegEx.\n */\nexport class Utility {\n\t/**\n\t * Determine whether an input value is a valid TypeScript type identifier.\n\t * An identifier must start with a letter, underscore, or dollar sign and contain only\n\t * alphanumerics, underscores, or dollar signs thereafter.\n\t * @param value The value to inspect.\n\t * @returns True if the value looks like a type name.\n\t */\n\tpublic static isTypeNameInput(value: string): boolean {\n\t\treturn /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(value);\n\t}\n\n\t/**\n\t * Extract the inner type node from a named or rest tuple element.\n\t * Named tuple members and rest elements both wrap an inner type node; this unwraps them.\n\t * Plain type nodes are returned as-is.\n\t * @param element The tuple element.\n\t * @returns The inner type node.\n\t */\n\tpublic static extractTupleElementType(element: ts.TypeNode): ts.TypeNode | undefined {\n\t\t// label: string  (named tuple member, e.g. [label: string, count: number])\n\t\tif (ts.isNamedTupleMember(element)) {\n\t\t\treturn element.type;\n\t\t}\n\n\t\t// ...string[]  (rest element in a tuple, e.g. [first: string, ...rest: string[]])\n\t\tif (ts.isRestTypeNode(element)) {\n\t\t\treturn element.type;\n\t\t}\n\n\t\treturn element;\n\t}\n\n\t/**\n\t * Extract the JSDoc description comment for an AST node.\n\t * Only top-level JSDoc block comments are considered; inline tags are ignored.\n\t * @param node The node to inspect.\n\t * @returns The trimmed description text, or undefined when absent.\n\t */\n\tpublic static getNodeJsDocDescription(node: ts.Node): string | undefined {\n\t\t// /** Description text */ (JSDoc block attached to a declaration)\n\t\tconst jsDocNodes = ts\n\t\t\t.getJSDocCommentsAndTags(node)\n\t\t\t.filter(commentOrTag => ts.isJSDoc(commentOrTag));\n\t\tconst description = jsDocNodes\n\t\t\t.map(jsDocNode => ts.getTextOfJSDocComment(jsDocNode.comment)?.trim())\n\t\t\t.find((value): value is string => Boolean(value));\n\n\t\tif (description) {\n\t\t\treturn description;\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Convert a JSDoc tag's comment portion to a plain text string.\n\t * JSDoc tag comments may be plain strings or arrays of link/text parts.\n\t * @param jsDocTag The JSDoc tag.\n\t * @returns The comment text, or undefined when absent.\n\t */\n\tpublic static getJSDocTagCommentText(jsDocTag: ts.JSDocTag): string | undefined {\n\t\tif (Is.string(jsDocTag.comment)) {\n\t\t\treturn jsDocTag.comment;\n\t\t}\n\n\t\tif (Array.isArray(jsDocTag.comment)) {\n\t\t\treturn jsDocTag.comment\n\t\t\t\t.map(part => part.text)\n\t\t\t\t.join(\"\")\n\t\t\t\t.trim();\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Read all custom JSDoc tags matching a tag name from a node and convert them to key/value pairs.\n\t * Each matching tag's comment must be in the form \"key: value\"; entries that do not follow this\n\t * convention are silently skipped.\n\t * @param node The node to inspect.\n\t * @param tagName The tag name to filter by (e.g., 'json-schema').\n\t * @returns The extracted key/value pairs.\n\t */\n\tpublic static getNodeTags(node: ts.Node, tagName: string): { [id: string]: string } {\n\t\tconst output: { [id: string]: string } = {};\n\t\tfor (const jsDocTag of ts.getJSDocTags(node)) {\n\t\t\tif (jsDocTag.tagName.text === tagName) {\n\t\t\t\tconst commentText = Utility.getJSDocTagCommentText(jsDocTag);\n\t\t\t\tif (commentText) {\n\t\t\t\t\tconst separatorIndex = commentText.indexOf(\":\");\n\t\t\t\t\tif (separatorIndex > 0) {\n\t\t\t\t\t\tconst key = commentText.slice(0, separatorIndex).trim();\n\t\t\t\t\t\tconst value = commentText.slice(separatorIndex + 1).trim();\n\t\t\t\t\t\tif (key.length > 0) {\n\t\t\t\t\t\t\toutput[key] = value;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn output;\n\t}\n\n\t/**\n\t * Parse a custom JSDoc tag value into JSON-compatible data.\n\t * Values that begin with a JSON token character ({, [, \", true, false, null) or look like a\n\t * number are parsed with JSON.parse.  All other values are returned as plain strings.\n\t * @param value The raw value text.\n\t * @returns The parsed value.\n\t */\n\tpublic static parseTagValue(value: string): unknown {\n\t\tconst trimmedValue = value.trim();\n\t\tif (trimmedValue.length === 0) {\n\t\t\treturn \"\";\n\t\t}\n\n\t\tconst startsWithJsonToken =\n\t\t\ttrimmedValue.startsWith(\"{\") ||\n\t\t\ttrimmedValue.startsWith(\"[\") ||\n\t\t\ttrimmedValue.startsWith('\"') ||\n\t\t\ttrimmedValue === \"true\" ||\n\t\t\ttrimmedValue === \"false\" ||\n\t\t\ttrimmedValue === \"null\" ||\n\t\t\t/^-?\\d+(\\.\\d+)?$/u.test(trimmedValue);\n\n\t\tif (!startsWithJsonToken) {\n\t\t\treturn trimmedValue;\n\t\t}\n\n\t\ttry {\n\t\t\treturn JSON.parse(trimmedValue);\n\t\t} catch {\n\t\t\treturn trimmedValue;\n\t\t}\n\t}\n}\n"]}