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

package/dist/es/index.js

@@ -1,14 +1,23 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-export * from "./models/IJsonSchema.js";
-export * from "./models/IOpenApi.js";
-export * from "./models/IOpenApiExample.js";
-export * from "./models/IOpenApiHeader.js";
-export * from "./models/IOpenApiPathMethod.js";
-export * from "./models/IOpenApiResponse.js";
-export * from "./models/IOpenApiSecurityScheme.js";
-export * from "./models/IPackageJson.js";
-export * from "./models/jsonTypeName.js";
-export * from "./utils/jsonSchemaHelper.js";
-export * from "./utils/openApiHelper.js";
+export * from "./models/ITypeScriptToSchemaContext.js";
+export * from "./models/ITypeScriptToSchemaDiagnostics.js";
+export * from "./models/ITypeScriptToSchemaOptions.js";
+export * from "./utils/diagnosticReporter.js";
+export * from "./utils/disallowedTypeGuard.js";
+export * from "./utils/enum.js";
+export * from "./utils/fileUtils.js";
+export * from "./utils/importTypeQuerySchemaResolver.js";
+export * from "./utils/indexSignaturePatternResolver.js";
+export * from "./utils/intersectionSchemaMerger.js";
+export * from "./utils/jsonSchemaBuilder.js";
+export * from "./utils/constants.js";
+export * from "./utils/mappedTypeSchemaResolver.js";
+export * from "./utils/objectTransformer.js";
+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/utilityTypeSchemaMapper.js";
 //# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./models/IJsonSchema.js\";\nexport * from \"./models/IOpenApi.js\";\nexport * from \"./models/IOpenApiExample.js\";\nexport * from \"./models/IOpenApiHeader.js\";\nexport * from \"./models/IOpenApiPathMethod.js\";\nexport * from \"./models/IOpenApiResponse.js\";\nexport * from \"./models/IOpenApiSecurityScheme.js\";\nexport * from \"./models/IPackageJson.js\";\nexport * from \"./models/jsonTypeName.js\";\nexport * from \"./utils/jsonSchemaHelper.js\";\nexport * from \"./utils/openApiHelper.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,wCAAwC,CAAC;AACvD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0CAA0C,CAAC;AACzD,cAAc,0CAA0C,CAAC;AACzD,cAAc,qCAAqC,CAAC;AACpD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,qCAAqC,CAAC;AACpD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oBAAoB,CAAC;AACnC,cAAc,oCAAoC,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./models/ITypeScriptToSchemaContext.js\";\nexport * from \"./models/ITypeScriptToSchemaDiagnostics.js\";\nexport * from \"./models/ITypeScriptToSchemaOptions.js\";\nexport * from \"./utils/diagnosticReporter.js\";\nexport * from \"./utils/disallowedTypeGuard.js\";\nexport * from \"./utils/enum.js\";\nexport * from \"./utils/fileUtils.js\";\nexport * from \"./utils/importTypeQuerySchemaResolver.js\";\nexport * from \"./utils/indexSignaturePatternResolver.js\";\nexport * from \"./utils/intersectionSchemaMerger.js\";\nexport * from \"./utils/jsonSchemaBuilder.js\";\nexport * from \"./utils/constants.js\";\nexport * from \"./utils/mappedTypeSchemaResolver.js\";\nexport * from \"./utils/objectTransformer.js\";\nexport * from \"./utils/regEx.js\";\nexport * from \"./utils/resolver.js\";\nexport * from \"./utils/templateLiteralPatternBuilder.js\";\nexport * from \"./utils/typeScriptToSchema.js\";\nexport * from \"./utils/utility.js\";\nexport * from \"./utils/utilityTypeSchemaMapper.js\";\n"]}

package/dist/es/models/ITypeScriptToSchemaContext.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ITypeScriptToSchemaContext.js.map

package/dist/es/models/ITypeScriptToSchemaContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITypeScriptToSchemaContext.js","sourceRoot":"","sources":["../../../src/models/ITypeScriptToSchemaContext.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IJsonSchema } from \"@twin.org/tools-models\";\nimport type * as ts from \"typescript\";\nimport type { ITypeScriptToSchemaOptions } from \"./ITypeScriptToSchemaOptions.js\";\n\n/**\n * Context for TypeScript to JSON schema generation.\n */\nexport interface ITypeScriptToSchemaContext {\n\t/**\n\t * The namespace for generated schema ids.\n\t */\n\tnamespace: string;\n\n\t/**\n\t * The package name for generated schema ids.\n\t */\n\tpackageName: string;\n\n\t/**\n\t * The schema cache indexed by package and title.\n\t */\n\tschemas: { [id: string]: { [id: string]: IJsonSchema } };\n\n\t/**\n\t * The currently active source file being mapped.\n\t */\n\tactiveSourceFile?: ts.SourceFile;\n\n\t/**\n\t * The currently active enclosing object (interface/type) being mapped.\n\t */\n\tactiveEnclosingObjectName?: string;\n\n\t/**\n\t * The first disallowed type encountered while mapping the active enclosing object.\n\t */\n\tactiveDisallowedType?: {\n\t\tdisallowedTypeName: string;\n\t\tpropertyName: string;\n\t\tenclosingObjectName: string;\n\t};\n\n\t/**\n\t * Type names currently being resolved to avoid recursive local-type expansion loops.\n\t */\n\tresolvingTypeNames?: Set<string>;\n\n\t/**\n\t * Utility type names currently being processed to avoid infinite recursion cycles\n\t * when encountering complex combinations of indexed access types, keyof, and utility types.\n\t */\n\tresolvingUtilityTypes?: Set<string>;\n\n\t/**\n\t * Imported utility base schemas currently being resolved to avoid recursive re-entry\n\t * while parsing module graphs for utility type application.\n\t */\n\tresolvingImportedObjectSchemas?: Set<string>;\n\n\t/**\n\t * Generic type parameter bindings active for the current mapping scope.\n\t */\n\ttypeParameterBindings?: { [id: string]: ts.TypeNode | null };\n\n\t/**\n\t * Optional schema generation options.\n\t */\n\toptions?: ITypeScriptToSchemaOptions;\n}\n"]}

package/dist/es/models/ITypeScriptToSchemaDiagnostics.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=ITypeScriptToSchemaDiagnostics.js.map

package/dist/es/models/ITypeScriptToSchemaDiagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITypeScriptToSchemaDiagnostics.js","sourceRoot":"","sources":["../../../src/models/ITypeScriptToSchemaDiagnostics.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Diagnostic payload for non-fatal schema generation issues.\n */\nexport interface ITypeScriptToSchemaDiagnostics {\n\t/**\n\t * Stable diagnostic code identifying the issue type.\n\t */\n\tcode: string;\n\n\t/**\n\t * Additional structured metadata related to the diagnostic.\n\t */\n\tproperties?: { [key: string]: unknown };\n\n\t/**\n\t * Schema path where the issue was detected.\n\t */\n\tpath: string;\n\n\t/**\n\t * Source file where the diagnostic originated, if available.\n\t */\n\tfileName?: string;\n\n\t/**\n\t * One-based source line number, when available.\n\t */\n\tline?: number;\n\n\t/**\n\t * One-based source column number, when available.\n\t */\n\tcolumn?: number;\n}\n"]}

package/dist/es/models/ITypeScriptToSchemaOptions.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=ITypeScriptToSchemaOptions.js.map

package/dist/es/models/ITypeScriptToSchemaOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITypeScriptToSchemaOptions.js","sourceRoot":"","sources":["../../../src/models/ITypeScriptToSchemaOptions.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\nimport type { ITypeScriptToSchemaDiagnostics } from \"./ITypeScriptToSchemaDiagnostics.js\";\n\n/**\n * Options for TypeScript to JSON schema generation.\n */\nexport interface ITypeScriptToSchemaOptions {\n\t/**\n\t * Mapping of package ids, type ids, wildcard patterns, or regex patterns to schema id prefixes\n\t * or replacement templates for referenced schemas.\n\t */\n\texternalReferences?: { [id: string]: string };\n\n\t/**\n\t * Optional diagnostic callback for non-fatal generation issues.\n\t * @param diagnostic The diagnostic details for the generation issue.\n\t */\n\tonDiagnostic?: (diagnostic: ITypeScriptToSchemaDiagnostics) => void;\n\n\t/**\n\t * Package names where diagnostics should be suppressed, e.g. jose.\n\t */\n\tsuppressPackageWarnings?: string[];\n}\n"]}

package/dist/es/utils/constants.js

@@ -0,0 +1,43 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Shared constants for TypeScript to JSON schema generation.
+ */
+export class Constants {
+    /**
+     * Utility type names currently unsupported and mapped to open schemas with diagnostics.
+     */
+    static UNSUPPORTED_UTILITY_TYPE_NAMES = [
+        "Awaited",
+        "ReturnType",
+        "Parameters",
+        "ConstructorParameters",
+        "InstanceType",
+        "ThisParameterType",
+        "OmitThisParameter",
+        "ThisType",
+        "CallableFunction",
+        "NewableFunction",
+        "Uppercase",
+        "Lowercase",
+        "Capitalize",
+        "Uncapitalize"
+    ];
+    /**
+     * Native typed-array and binary type names mapped to JSON number arrays.
+     */
+    static ARRAY_NUMBER_TYPE_NAMES = [
+        "ArrayBuffer",
+        "SharedArrayBuffer",
+        "Int8Array",
+        "Uint8Array",
+        "Uint8ClampedArray",
+        "Int16Array",
+        "Uint16Array",
+        "Int32Array",
+        "Uint32Array",
+        "Float32Array",
+        "Float64Array"
+    ];
+}
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/utils/constants.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,MAAM,OAAO,SAAS;IACrB;;OAEG;IACI,MAAM,CAAU,8BAA8B,GAAa;QACjE,SAAS;QACT,YAAY;QACZ,YAAY;QACZ,uBAAuB;QACvB,cAAc;QACd,mBAAmB;QACnB,mBAAmB;QACnB,UAAU;QACV,kBAAkB;QAClB,iBAAiB;QACjB,WAAW;QACX,WAAW;QACX,YAAY;QACZ,cAAc;KACd,CAAC;IAEF;;OAEG;IACI,MAAM,CAAU,uBAAuB,GAAa;QAC1D,aAAa;QACb,mBAAmB;QACnB,WAAW;QACX,YAAY;QACZ,mBAAmB;QACnB,YAAY;QACZ,aAAa;QACb,YAAY;QACZ,aAAa;QACb,cAAc;QACd,cAAc;KACd,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Shared constants for TypeScript to JSON schema generation.\n */\nexport class Constants {\n\t/**\n\t * Utility type names currently unsupported and mapped to open schemas with diagnostics.\n\t */\n\tpublic static readonly UNSUPPORTED_UTILITY_TYPE_NAMES: string[] = [\n\t\t\"Awaited\",\n\t\t\"ReturnType\",\n\t\t\"Parameters\",\n\t\t\"ConstructorParameters\",\n\t\t\"InstanceType\",\n\t\t\"ThisParameterType\",\n\t\t\"OmitThisParameter\",\n\t\t\"ThisType\",\n\t\t\"CallableFunction\",\n\t\t\"NewableFunction\",\n\t\t\"Uppercase\",\n\t\t\"Lowercase\",\n\t\t\"Capitalize\",\n\t\t\"Uncapitalize\"\n\t];\n\n\t/**\n\t * Native typed-array and binary type names mapped to JSON number arrays.\n\t */\n\tpublic static readonly ARRAY_NUMBER_TYPE_NAMES: string[] = [\n\t\t\"ArrayBuffer\",\n\t\t\"SharedArrayBuffer\",\n\t\t\"Int8Array\",\n\t\t\"Uint8Array\",\n\t\t\"Uint8ClampedArray\",\n\t\t\"Int16Array\",\n\t\t\"Uint16Array\",\n\t\t\"Int32Array\",\n\t\t\"Uint32Array\",\n\t\t\"Float32Array\",\n\t\t\"Float64Array\"\n\t];\n}\n"]}

package/dist/es/utils/diagnosticReporter.js

@@ -0,0 +1,32 @@
+/**
+ * Emits non-fatal diagnostics during schema mapping.
+ */
+export class DiagnosticReporter {
+    /**
+     * Emit an optional non-fatal schema generation diagnostic.
+     * @param context The generation context.
+     * @param node The related AST node.
+     * @param code The diagnostic code.
+     * @param properties The values to substitute into the localised message.
+     */
+    static report(context, node, code, properties) {
+        if (!context.options?.onDiagnostic) {
+            return;
+        }
+        const sourceFile = context.activeSourceFile;
+        const sourcePosition = sourceFile
+            ? sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
+            : undefined;
+        context.options.onDiagnostic({
+            code,
+            properties,
+            path: sourceFile
+                ? `${sourceFile.fileName}:${(sourcePosition?.line ?? 0) + 1}:${(sourcePosition?.character ?? 0) + 1}`
+                : "unknown",
+            fileName: sourceFile?.fileName,
+            line: sourcePosition ? sourcePosition.line + 1 : undefined,
+            column: sourcePosition ? sourcePosition.character + 1 : undefined
+        });
+    }
+}
+//# sourceMappingURL=diagnosticReporter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnosticReporter.js","sourceRoot":"","sources":["../../../src/utils/diagnosticReporter.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,OAAO,kBAAkB;IAC9B;;;;;;OAMG;IACI,MAAM,CAAC,MAAM,CACnB,OAAmC,EACnC,IAAa,EACb,IAAY,EACZ,UAAuC;QAEvC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;YACpC,OAAO;QACR,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC;QAC5C,MAAM,cAAc,GAAG,UAAU;YAChC,CAAC,CAAC,UAAU,CAAC,6BAA6B,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YACrE,CAAC,CAAC,SAAS,CAAC;QAEb,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC;YAC5B,IAAI;YACJ,UAAU;YACV,IAAI,EAAE,UAAU;gBACf,CAAC,CAAC,GAAG,UAAU,CAAC,QAAQ,IAAI,CAAC,cAAc,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,EAAE,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE;gBACrG,CAAC,CAAC,SAAS;YACZ,QAAQ,EAAE,UAAU,EAAE,QAAQ;YAC9B,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;YAC1D,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;SACjE,CAAC,CAAC;IACJ,CAAC;CACD","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type * as ts from \"typescript\";\nimport type { ITypeScriptToSchemaContext } from \"../models/ITypeScriptToSchemaContext.js\";\n\n/**\n * Emits non-fatal diagnostics during schema mapping.\n */\nexport class DiagnosticReporter {\n\t/**\n\t * Emit an optional non-fatal schema generation diagnostic.\n\t * @param context The generation context.\n\t * @param node The related AST node.\n\t * @param code The diagnostic code.\n\t * @param properties The values to substitute into the localised message.\n\t */\n\tpublic static report(\n\t\tcontext: ITypeScriptToSchemaContext,\n\t\tnode: ts.Node,\n\t\tcode: string,\n\t\tproperties?: { [key: string]: unknown }\n\t): void {\n\t\tif (!context.options?.onDiagnostic) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst sourceFile = context.activeSourceFile;\n\t\tconst sourcePosition = sourceFile\n\t\t\t? sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))\n\t\t\t: undefined;\n\n\t\tcontext.options.onDiagnostic({\n\t\t\tcode,\n\t\t\tproperties,\n\t\t\tpath: sourceFile\n\t\t\t\t? `${sourceFile.fileName}:${(sourcePosition?.line ?? 0) + 1}:${(sourcePosition?.character ?? 0) + 1}`\n\t\t\t\t: \"unknown\",\n\t\t\tfileName: sourceFile?.fileName,\n\t\t\tline: sourcePosition ? sourcePosition.line + 1 : undefined,\n\t\t\tcolumn: sourcePosition ? sourcePosition.character + 1 : undefined\n\t\t});\n\t}\n}\n"]}

package/dist/es/utils/disallowedTypeGuard.js

@@ -0,0 +1,151 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import * as ts from "typescript";
+/**
+ * Validates whether a type node is allowed for schema generation.
+ */
+export class DisallowedTypeGuard {
+    /**
+     * Type names that are not supported for JSON schema generation.
+     */
+    static _DISALLOWED_TYPE_NAMES = [
+        "Date",
+        "RegExp",
+        "Function",
+        "Error",
+        "TypeError",
+        "RangeError",
+        "EvalError",
+        "ReferenceError",
+        "SyntaxError",
+        "URIError",
+        "AggregateError",
+        "bigint",
+        "BigInt",
+        "BigInt64Array",
+        "BigUint64Array",
+        "DataView",
+        "Promise",
+        "WeakRef",
+        "URL",
+        "URLSearchParams",
+        "Blob",
+        "File",
+        "FormData",
+        "ReadableStream",
+        "WeakMap",
+        "WeakSet",
+        "Symbol"
+    ];
+    /**
+     * Resolve a disallowed type name from a type node.
+     * @param typeNode The type node to inspect.
+     * @returns The disallowed type name, if found.
+     */
+    static getDisallowedTypeName(typeNode) {
+        // (string | number)  (parenthesised type, unwrap and recurse)
+        if (ts.isParenthesizedTypeNode(typeNode)) {
+            return DisallowedTypeGuard.getDisallowedTypeName(typeNode.type);
+        }
+        // readonly T[] or keyof T or unique symbol  (type operator node)
+        if (ts.isTypeOperatorNode(typeNode)) {
+            if (typeNode.operator === ts.SyntaxKind.UniqueKeyword &&
+                typeNode.type.kind === ts.SyntaxKind.SymbolKeyword) {
+                return "symbol";
+            }
+            return DisallowedTypeGuard.getDisallowedTypeName(typeNode.type);
+        }
+        // bigint  (bigint keyword type, always disallowed)
+        if (typeNode.kind === ts.SyntaxKind.BigIntKeyword) {
+            return "bigint";
+        }
+        // symbol  (symbol keyword type, always disallowed)
+        if (typeNode.kind === ts.SyntaxKind.SymbolKeyword) {
+            return "symbol";
+        }
+        // 9007199254740991n  (bigint literal wrapped in a literal type node)
+        if (ts.isLiteralTypeNode(typeNode) && ts.isBigIntLiteral(typeNode.literal)) {
+            return "bigint";
+        }
+        // Date or RegExp or Promise<T>  (named type reference)
+        if (ts.isTypeReferenceNode(typeNode)) {
+            // Namespace.TypeName  (qualified name) or TypeName  (plain identifier)
+            const rawTypeName = ts.isIdentifier(typeNode.typeName)
+                ? typeNode.typeName.text
+                : typeNode.typeName.right.text;
+            const normalizedTypeName = rawTypeName.toLowerCase();
+            const matchedTypeName = DisallowedTypeGuard._DISALLOWED_TYPE_NAMES.find(typeName => typeName.toLowerCase() === normalizedTypeName);
+            if (matchedTypeName) {
+                return matchedTypeName;
+            }
+        }
+        // string[]  (array type, check the element type)
+        if (ts.isArrayTypeNode(typeNode)) {
+            return DisallowedTypeGuard.getDisallowedTypeName(typeNode.elementType);
+        }
+        // [string, number]  (tuple type, check each element)
+        if (ts.isTupleTypeNode(typeNode)) {
+            return DisallowedTypeGuard.getDisallowedTypeNameFromTypeNodes(typeNode.elements);
+        }
+        // string | number  (union) or TypeA & TypeB  (intersection)
+        if (ts.isUnionTypeNode(typeNode) || ts.isIntersectionTypeNode(typeNode)) {
+            return DisallowedTypeGuard.getDisallowedTypeNameFromTypeNodes(typeNode.types);
+        }
+        // T["key"]  (indexed access type, check both object and index sides)
+        if (ts.isIndexedAccessTypeNode(typeNode)) {
+            return (DisallowedTypeGuard.getDisallowedTypeName(typeNode.objectType) ??
+                DisallowedTypeGuard.getDisallowedTypeName(typeNode.indexType));
+        }
+        // T extends U ? X : Y  (conditional type, check all four branches)
+        if (ts.isConditionalTypeNode(typeNode)) {
+            return (DisallowedTypeGuard.getDisallowedTypeName(typeNode.checkType) ??
+                DisallowedTypeGuard.getDisallowedTypeName(typeNode.extendsType) ??
+                DisallowedTypeGuard.getDisallowedTypeName(typeNode.trueType) ??
+                DisallowedTypeGuard.getDisallowedTypeName(typeNode.falseType));
+        }
+        // { [K in keyof T]: T[K] }  (mapped type, check constraint, name type, and value type)
+        if (ts.isMappedTypeNode(typeNode)) {
+            return ((typeNode.typeParameter.constraint
+                ? DisallowedTypeGuard.getDisallowedTypeName(typeNode.typeParameter.constraint)
+                : undefined) ??
+                (typeNode.nameType
+                    ? DisallowedTypeGuard.getDisallowedTypeName(typeNode.nameType)
+                    : undefined) ??
+                (typeNode.type ? DisallowedTypeGuard.getDisallowedTypeName(typeNode.type) : undefined));
+        }
+        // { prop: string }  (inline object type literal, inspect each member)
+        if (ts.isTypeLiteralNode(typeNode)) {
+            for (const member of typeNode.members) {
+                if (
+                // prop: string  or  [key: string]: Value  (property or index signature)
+                (ts.isPropertySignature(member) || ts.isIndexSignatureDeclaration(member)) &&
+                    member.type) {
+                    const memberDisallowedTypeName = DisallowedTypeGuard.getDisallowedTypeName(member.type);
+                    if (memberDisallowedTypeName) {
+                        return memberDisallowedTypeName;
+                    }
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Resolve the first disallowed type name from a collection of type nodes.
+     * @param typeNodes The nodes to inspect.
+     * @returns The disallowed type name, if found.
+     * @internal
+     */
+    static getDisallowedTypeNameFromTypeNodes(typeNodes) {
+        if (!typeNodes) {
+            return undefined;
+        }
+        for (const typeNode of typeNodes) {
+            const disallowedTypeName = DisallowedTypeGuard.getDisallowedTypeName(typeNode);
+            if (disallowedTypeName) {
+                return disallowedTypeName;
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=disallowedTypeGuard.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disallowedTypeGuard.js","sourceRoot":"","sources":["../../../src/utils/disallowedTypeGuard.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport * as ts from \"typescript\";\n\n/**\n * Validates whether a type node is allowed for schema generation.\n */\nexport class DisallowedTypeGuard {\n\t/**\n\t * Type names that are not supported for JSON schema generation.\n\t */\n\tprivate static readonly _DISALLOWED_TYPE_NAMES: string[] = [\n\t\t\"Date\",\n\t\t\"RegExp\",\n\t\t\"Function\",\n\t\t\"Error\",\n\t\t\"TypeError\",\n\t\t\"RangeError\",\n\t\t\"EvalError\",\n\t\t\"ReferenceError\",\n\t\t\"SyntaxError\",\n\t\t\"URIError\",\n\t\t\"AggregateError\",\n\t\t\"bigint\",\n\t\t\"BigInt\",\n\t\t\"BigInt64Array\",\n\t\t\"BigUint64Array\",\n\t\t\"DataView\",\n\t\t\"Promise\",\n\t\t\"WeakRef\",\n\t\t\"URL\",\n\t\t\"URLSearchParams\",\n\t\t\"Blob\",\n\t\t\"File\",\n\t\t\"FormData\",\n\t\t\"ReadableStream\",\n\t\t\"WeakMap\",\n\t\t\"WeakSet\",\n\t\t\"Symbol\"\n\t];\n\n\t/**\n\t * Resolve a disallowed type name from a type node.\n\t * @param typeNode The type node to inspect.\n\t * @returns The disallowed type name, if found.\n\t */\n\tpublic static getDisallowedTypeName(typeNode: ts.TypeNode): string | undefined {\n\t\t// (string | number)  (parenthesised type, unwrap and recurse)\n\t\tif (ts.isParenthesizedTypeNode(typeNode)) {\n\t\t\treturn DisallowedTypeGuard.getDisallowedTypeName(typeNode.type);\n\t\t}\n\n\t\t// readonly T[] or keyof T or unique symbol  (type operator node)\n\t\tif (ts.isTypeOperatorNode(typeNode)) {\n\t\t\tif (\n\t\t\t\ttypeNode.operator === ts.SyntaxKind.UniqueKeyword &&\n\t\t\t\ttypeNode.type.kind === ts.SyntaxKind.SymbolKeyword\n\t\t\t) {\n\t\t\t\treturn \"symbol\";\n\t\t\t}\n\n\t\t\treturn DisallowedTypeGuard.getDisallowedTypeName(typeNode.type);\n\t\t}\n\n\t\t// bigint  (bigint keyword type, always disallowed)\n\t\tif (typeNode.kind === ts.SyntaxKind.BigIntKeyword) {\n\t\t\treturn \"bigint\";\n\t\t}\n\n\t\t// symbol  (symbol keyword type, always disallowed)\n\t\tif (typeNode.kind === ts.SyntaxKind.SymbolKeyword) {\n\t\t\treturn \"symbol\";\n\t\t}\n\n\t\t// 9007199254740991n  (bigint literal wrapped in a literal type node)\n\t\tif (ts.isLiteralTypeNode(typeNode) && ts.isBigIntLiteral(typeNode.literal)) {\n\t\t\treturn \"bigint\";\n\t\t}\n\n\t\t// Date or RegExp or Promise<T>  (named type reference)\n\t\tif (ts.isTypeReferenceNode(typeNode)) {\n\t\t\t// Namespace.TypeName  (qualified name) or TypeName  (plain identifier)\n\t\t\tconst rawTypeName = ts.isIdentifier(typeNode.typeName)\n\t\t\t\t? typeNode.typeName.text\n\t\t\t\t: typeNode.typeName.right.text;\n\t\t\tconst normalizedTypeName = rawTypeName.toLowerCase();\n\t\t\tconst matchedTypeName = DisallowedTypeGuard._DISALLOWED_TYPE_NAMES.find(\n\t\t\t\ttypeName => typeName.toLowerCase() === normalizedTypeName\n\t\t\t);\n\t\t\tif (matchedTypeName) {\n\t\t\t\treturn matchedTypeName;\n\t\t\t}\n\t\t}\n\n\t\t// string[]  (array type, check the element type)\n\t\tif (ts.isArrayTypeNode(typeNode)) {\n\t\t\treturn DisallowedTypeGuard.getDisallowedTypeName(typeNode.elementType);\n\t\t}\n\n\t\t// [string, number]  (tuple type, check each element)\n\t\tif (ts.isTupleTypeNode(typeNode)) {\n\t\t\treturn DisallowedTypeGuard.getDisallowedTypeNameFromTypeNodes(typeNode.elements);\n\t\t}\n\n\t\t// string | number  (union) or TypeA & TypeB  (intersection)\n\t\tif (ts.isUnionTypeNode(typeNode) || ts.isIntersectionTypeNode(typeNode)) {\n\t\t\treturn DisallowedTypeGuard.getDisallowedTypeNameFromTypeNodes(typeNode.types);\n\t\t}\n\n\t\t// T[\"key\"]  (indexed access type, check both object and index sides)\n\t\tif (ts.isIndexedAccessTypeNode(typeNode)) {\n\t\t\treturn (\n\t\t\t\tDisallowedTypeGuard.getDisallowedTypeName(typeNode.objectType) ??\n\t\t\t\tDisallowedTypeGuard.getDisallowedTypeName(typeNode.indexType)\n\t\t\t);\n\t\t}\n\n\t\t// T extends U ? X : Y  (conditional type, check all four branches)\n\t\tif (ts.isConditionalTypeNode(typeNode)) {\n\t\t\treturn (\n\t\t\t\tDisallowedTypeGuard.getDisallowedTypeName(typeNode.checkType) ??\n\t\t\t\tDisallowedTypeGuard.getDisallowedTypeName(typeNode.extendsType) ??\n\t\t\t\tDisallowedTypeGuard.getDisallowedTypeName(typeNode.trueType) ??\n\t\t\t\tDisallowedTypeGuard.getDisallowedTypeName(typeNode.falseType)\n\t\t\t);\n\t\t}\n\n\t\t// { [K in keyof T]: T[K] }  (mapped type, check constraint, name type, and value type)\n\t\tif (ts.isMappedTypeNode(typeNode)) {\n\t\t\treturn (\n\t\t\t\t(typeNode.typeParameter.constraint\n\t\t\t\t\t? DisallowedTypeGuard.getDisallowedTypeName(typeNode.typeParameter.constraint)\n\t\t\t\t\t: undefined) ??\n\t\t\t\t(typeNode.nameType\n\t\t\t\t\t? DisallowedTypeGuard.getDisallowedTypeName(typeNode.nameType)\n\t\t\t\t\t: undefined) ??\n\t\t\t\t(typeNode.type ? DisallowedTypeGuard.getDisallowedTypeName(typeNode.type) : undefined)\n\t\t\t);\n\t\t}\n\n\t\t// { prop: string }  (inline object type literal, inspect each member)\n\t\tif (ts.isTypeLiteralNode(typeNode)) {\n\t\t\tfor (const member of typeNode.members) {\n\t\t\t\tif (\n\t\t\t\t\t// prop: string  or  [key: string]: Value  (property or index signature)\n\t\t\t\t\t(ts.isPropertySignature(member) || ts.isIndexSignatureDeclaration(member)) &&\n\t\t\t\t\tmember.type\n\t\t\t\t) {\n\t\t\t\t\tconst memberDisallowedTypeName = DisallowedTypeGuard.getDisallowedTypeName(member.type);\n\t\t\t\t\tif (memberDisallowedTypeName) {\n\t\t\t\t\t\treturn memberDisallowedTypeName;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Resolve the first disallowed type name from a collection of type nodes.\n\t * @param typeNodes The nodes to inspect.\n\t * @returns The disallowed type name, if found.\n\t * @internal\n\t */\n\tprivate static getDisallowedTypeNameFromTypeNodes(\n\t\ttypeNodes: readonly ts.TypeNode[] | ts.NodeArray<ts.TypeNode> | undefined\n\t): string | undefined {\n\t\tif (!typeNodes) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tfor (const typeNode of typeNodes) {\n\t\t\tconst disallowedTypeName = DisallowedTypeGuard.getDisallowedTypeName(typeNode);\n\t\t\tif (disallowedTypeName) {\n\t\t\t\treturn disallowedTypeName;\n\t\t\t}\n\t\t}\n\n\t\treturn undefined;\n\t}\n}\n"]}

package/dist/es/utils/enum.js

@@ -0,0 +1,152 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Is } from "@twin.org/core";
+import * as ts from "typescript";
+import { Utility } from "./utility.js";
+/**
+ * Utility methods for extracting enum values from TypeScript AST nodes.
+ *
+ * Handles three distinct patterns used to define enumerable sets of values:
+ * - Native enum declarations: `enum Color { Red = "red" }`
+ * - Const-object-with-matching-type patterns: `const Foo = { A: "a" } as const` paired with a type alias named identically to the const
+ */
+export class Enum {
+    /**
+     * Extract enum values from a const-and-type pair where a const object and a type alias share the
+     * same name.  The const object is located first because its members may carry JSDoc descriptions
+     * that would be lost if the type alias were processed in isolation.
+     * @param name The name to search for.
+     * @param sourceFile The source file to search.
+     * @returns The extracted enum entries or undefined when the pattern is not present.
+     */
+    static extractEnumValuesFromConstAndType(name, sourceFile) {
+        // const Foo = { A: "a", B: "b" } as const
+        const varStmt = sourceFile.statements.find(stmt => {
+            // const Foo = ...
+            if (!ts.isVariableStatement(stmt)) {
+                return false;
+            }
+            const decl = stmt.declarationList.declarations[0];
+            // Foo (the identifier that names the const)
+            return decl?.name && ts.isIdentifier(decl.name) && decl.name.text === name;
+        });
+        if (!varStmt) {
+            return undefined;
+        }
+        const decl = varStmt.declarationList.declarations[0];
+        if (!decl?.initializer) {
+            return undefined;
+        }
+        let objLiteral;
+        // { A: "a", B: "b" }
+        if (ts.isObjectLiteralExpression(decl.initializer)) {
+            objLiteral = decl.initializer;
+        }
+        else if (
+        // { A: "a", B: "b" } as const
+        ts.isAsExpression(decl.initializer) &&
+            ts.isObjectLiteralExpression(decl.initializer.expression)) {
+            objLiteral = decl.initializer.expression;
+        }
+        if (!objLiteral) {
+            return undefined;
+        }
+        const entries = Enum.extractEnumEntriesFromConstObject(objLiteral);
+        return entries.length > 0 ? entries : undefined;
+    }
+    /**
+     * Extract enum entries from a const object literal.
+     * Only properties whose initializer is a string or numeric literal are included.
+     * @param objLiteral The object literal expression.
+     * @returns The extracted enum entries.
+     */
+    static extractEnumEntriesFromConstObject(objLiteral) {
+        return (objLiteral.properties
+            // A: "a"  (property assignment with an initializer)
+            .filter(prop => ts.isPropertyAssignment(prop) && prop.initializer)
+            .map(prop => {
+            const assignment = prop;
+            const initializer = assignment.initializer;
+            const description = Utility.getNodeJsDocDescription(assignment);
+            // "a"  (string literal initializer)
+            if (ts.isStringLiteral(initializer)) {
+                return {
+                    value: initializer.text,
+                    description: description ?? undefined
+                };
+            }
+            // 42  (numeric literal initializer)
+            if (ts.isNumericLiteral(initializer)) {
+                return {
+                    value: Number(initializer.text),
+                    description: description ?? undefined
+                };
+            }
+            return null;
+        })
+            .filter((entry) => entry !== null));
+    }
+    /**
+     * Extract enum values from a native TypeScript enum declaration.
+     * Numeric members without an explicit initializer are auto-incremented from the previous value.
+     * @param declaration The enum declaration.
+     * @returns The extracted enum entries.
+     */
+    static extractEnumValuesFromEnumDeclaration(declaration) {
+        const entries = [];
+        let nextNumericValue = 0;
+        // enum Color { Red = "red", Count = 1 }
+        for (const member of declaration.members) {
+            const resolvedValue = Enum.resolveEnumMemberValue(member, nextNumericValue);
+            if (resolvedValue !== undefined) {
+                entries.push({
+                    value: resolvedValue,
+                    description: Utility.getNodeJsDocDescription(member)
+                });
+                if (Is.number(resolvedValue)) {
+                    nextNumericValue = resolvedValue + 1;
+                }
+            }
+        }
+        return entries;
+    }
+    /**
+     * Resolve the literal value of an enum member when possible.
+     * Members without an initializer inherit the current auto-increment counter.
+     * Negative numeric members expressed as unary minus (e.g. -1) are also resolved.
+     * @param member The enum member node.
+     * @param defaultNumericValue The default numeric value for auto-incremented members.
+     * @returns The resolved enum value, or undefined when the initializer cannot be evaluated statically.
+     * @internal
+     */
+    static resolveEnumMemberValue(member, defaultNumericValue) {
+        // Red  (member with no explicit initializer inherits the auto-increment counter)
+        if (!member.initializer) {
+            return defaultNumericValue;
+        }
+        // Red = "red"  (string literal enum member)
+        if (ts.isStringLiteral(member.initializer)) {
+            return member.initializer.text;
+        }
+        // Count = 42  (positive numeric literal enum member)
+        if (ts.isNumericLiteral(member.initializer)) {
+            return Number(member.initializer.text);
+        }
+        if (
+        // Negative = -1  (prefix unary minus applied to a numeric literal)
+        ts.isPrefixUnaryExpression(member.initializer) &&
+            member.initializer.operator === ts.SyntaxKind.MinusToken &&
+            ts.isNumericLiteral(member.initializer.operand)) {
+            return -Number(member.initializer.operand.text);
+        }
+        if (
+        // Explicit = +1  (prefix unary plus applied to a numeric literal)
+        ts.isPrefixUnaryExpression(member.initializer) &&
+            member.initializer.operator === ts.SyntaxKind.PlusToken &&
+            ts.isNumericLiteral(member.initializer.operand)) {
+            return Number(member.initializer.operand.text);
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=enum.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"enum.js","sourceRoot":"","sources":["../../../src/utils/enum.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Is } from \"@twin.org/core\";\nimport * as ts from \"typescript\";\nimport { Utility } from \"./utility.js\";\n\n/**\n * Utility methods for extracting enum values from TypeScript AST nodes.\n *\n * Handles three distinct patterns used to define enumerable sets of values:\n * - Native enum declarations: `enum Color { Red = \"red\" }`\n * - Const-object-with-matching-type patterns: `const Foo = { A: \"a\" } as const` paired with a type alias named identically to the const\n */\nexport class Enum {\n\t/**\n\t * Extract enum values from a const-and-type pair where a const object and a type alias share the\n\t * same name.  The const object is located first because its members may carry JSDoc descriptions\n\t * that would be lost if the type alias were processed in isolation.\n\t * @param name The name to search for.\n\t * @param sourceFile The source file to search.\n\t * @returns The extracted enum entries or undefined when the pattern is not present.\n\t */\n\tpublic static extractEnumValuesFromConstAndType(\n\t\tname: string,\n\t\tsourceFile: ts.SourceFile\n\t): { value: string | number; description?: string }[] | undefined {\n\t\t// const Foo = { A: \"a\", B: \"b\" } as const\n\t\tconst varStmt = sourceFile.statements.find(stmt => {\n\t\t\t// const Foo = ...\n\t\t\tif (!ts.isVariableStatement(stmt)) {\n\t\t\t\treturn false;\n\t\t\t}\n\n\t\t\tconst decl = stmt.declarationList.declarations[0];\n\t\t\t// Foo (the identifier that names the const)\n\t\t\treturn decl?.name && ts.isIdentifier(decl.name) && decl.name.text === name;\n\t\t}) as ts.VariableStatement | undefined;\n\n\t\tif (!varStmt) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst decl = varStmt.declarationList.declarations[0];\n\t\tif (!decl?.initializer) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tlet objLiteral: ts.ObjectLiteralExpression | undefined;\n\n\t\t// { A: \"a\", B: \"b\" }\n\t\tif (ts.isObjectLiteralExpression(decl.initializer)) {\n\t\t\tobjLiteral = decl.initializer;\n\t\t} else if (\n\t\t\t// { A: \"a\", B: \"b\" } as const\n\t\t\tts.isAsExpression(decl.initializer) &&\n\t\t\tts.isObjectLiteralExpression(decl.initializer.expression)\n\t\t) {\n\t\t\tobjLiteral = decl.initializer.expression;\n\t\t}\n\n\t\tif (!objLiteral) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst entries = Enum.extractEnumEntriesFromConstObject(objLiteral);\n\t\treturn entries.length > 0 ? entries : undefined;\n\t}\n\n\t/**\n\t * Extract enum entries from a const object literal.\n\t * Only properties whose initializer is a string or numeric literal are included.\n\t * @param objLiteral The object literal expression.\n\t * @returns The extracted enum entries.\n\t */\n\tpublic static extractEnumEntriesFromConstObject(\n\t\tobjLiteral: ts.ObjectLiteralExpression\n\t): { value: string | number; description?: string }[] {\n\t\treturn (\n\t\t\tobjLiteral.properties\n\t\t\t\t// A: \"a\"  (property assignment with an initializer)\n\t\t\t\t.filter(prop => ts.isPropertyAssignment(prop) && prop.initializer)\n\t\t\t\t.map<{ value: string | number; description?: string } | null>(prop => {\n\t\t\t\t\tconst assignment = prop as ts.PropertyAssignment;\n\t\t\t\t\tconst initializer = assignment.initializer;\n\t\t\t\t\tconst description = Utility.getNodeJsDocDescription(assignment);\n\n\t\t\t\t\t// \"a\"  (string literal initializer)\n\t\t\t\t\tif (ts.isStringLiteral(initializer)) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tvalue: initializer.text as string | number,\n\t\t\t\t\t\t\tdescription: description ?? undefined\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\t// 42  (numeric literal initializer)\n\t\t\t\t\tif (ts.isNumericLiteral(initializer)) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tvalue: Number(initializer.text),\n\t\t\t\t\t\t\tdescription: description ?? undefined\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\n\t\t\t\t\treturn null;\n\t\t\t\t})\n\t\t\t\t.filter(\n\t\t\t\t\t(entry): entry is { value: string | number; description?: string } => entry !== null\n\t\t\t\t)\n\t\t);\n\t}\n\n\t/**\n\t * Extract enum values from a native TypeScript enum declaration.\n\t * Numeric members without an explicit initializer are auto-incremented from the previous value.\n\t * @param declaration The enum declaration.\n\t * @returns The extracted enum entries.\n\t */\n\tpublic static extractEnumValuesFromEnumDeclaration(\n\t\tdeclaration: ts.EnumDeclaration\n\t): { value: string | number; description?: string }[] {\n\t\tconst entries: { value: string | number; description?: string }[] = [];\n\t\tlet nextNumericValue = 0;\n\n\t\t// enum Color { Red = \"red\", Count = 1 }\n\t\tfor (const member of declaration.members) {\n\t\t\tconst resolvedValue = Enum.resolveEnumMemberValue(member, nextNumericValue);\n\t\t\tif (resolvedValue !== undefined) {\n\t\t\t\tentries.push({\n\t\t\t\t\tvalue: resolvedValue,\n\t\t\t\t\tdescription: Utility.getNodeJsDocDescription(member)\n\t\t\t\t});\n\n\t\t\t\tif (Is.number(resolvedValue)) {\n\t\t\t\t\tnextNumericValue = resolvedValue + 1;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn entries;\n\t}\n\n\t/**\n\t * Resolve the literal value of an enum member when possible.\n\t * Members without an initializer inherit the current auto-increment counter.\n\t * Negative numeric members expressed as unary minus (e.g. -1) are also resolved.\n\t * @param member The enum member node.\n\t * @param defaultNumericValue The default numeric value for auto-incremented members.\n\t * @returns The resolved enum value, or undefined when the initializer cannot be evaluated statically.\n\t * @internal\n\t */\n\tprivate static resolveEnumMemberValue(\n\t\tmember: ts.EnumMember,\n\t\tdefaultNumericValue: number\n\t): string | number | undefined {\n\t\t// Red  (member with no explicit initializer inherits the auto-increment counter)\n\t\tif (!member.initializer) {\n\t\t\treturn defaultNumericValue;\n\t\t}\n\n\t\t// Red = \"red\"  (string literal enum member)\n\t\tif (ts.isStringLiteral(member.initializer)) {\n\t\t\treturn member.initializer.text;\n\t\t}\n\n\t\t// Count = 42  (positive numeric literal enum member)\n\t\tif (ts.isNumericLiteral(member.initializer)) {\n\t\t\treturn Number(member.initializer.text);\n\t\t}\n\n\t\tif (\n\t\t\t// Negative = -1  (prefix unary minus applied to a numeric literal)\n\t\t\tts.isPrefixUnaryExpression(member.initializer) &&\n\t\t\tmember.initializer.operator === ts.SyntaxKind.MinusToken &&\n\t\t\tts.isNumericLiteral(member.initializer.operand)\n\t\t) {\n\t\t\treturn -Number(member.initializer.operand.text);\n\t\t}\n\n\t\tif (\n\t\t\t// Explicit = +1  (prefix unary plus applied to a numeric literal)\n\t\t\tts.isPrefixUnaryExpression(member.initializer) &&\n\t\t\tmember.initializer.operator === ts.SyntaxKind.PlusToken &&\n\t\t\tts.isNumericLiteral(member.initializer.operand)\n\t\t) {\n\t\t\treturn Number(member.initializer.operand.text);\n\t\t}\n\n\t\treturn undefined;\n\t}\n}\n"]}