feat: support typescript v6

Author: stas-nc

.github/workflows/runTestsOnPush.yml

@@ -8,7 +8,7 @@ jobs:
       matrix:
         node-version: [22]
         os: [ubuntu-latest]
-        typescript-version: ["^5.0.0"]
+        typescript-version: ["^6.0.0"]
 
     steps:
       - uses: actions/checkout@master

memory/MEMORY.md

@@ -0,0 +1,3 @@
+# Memory Index
+
+- [TypeScript v6 upgrade fixes](project_ts6_upgrade.md) — TS v6 breaking changes fixed in typeResolver.ts, specGenerator2/3.ts, and test expectations

memory/project_ts6_upgrade.md

@@ -0,0 +1,30 @@
+---
+name: project_ts6_upgrade
+description: "TypeScript v6 upgrade — breaking changes fixed in tsoa's type resolver and swagger generators"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 55aaffb4-ee2d-4c95-9ce0-76947e423b97
+---
+
+TypeScript v6 was upgraded in this repo. All unit tests (1111) now pass after fixes.
+
+**Why:** TS v6 changed type checker behavior in two ways relevant to tsoa.
+
+**Key fixes applied:**
+
+1. **`typeResolver.ts` `calcMappedType` (line ~210)**: TS v6 `getTypeOfSymbol()` for optional properties in mapped types now includes `undefined` (e.g., `"id" | undefined` instead of `"id"`). Fix: strip the single `undefined` constituent when the property is optional (`SymbolFlags.Optional`) and only one non-undefined type remains.
+
+2. **`typeResolver.ts` union TypeNode ordering (line ~65)**: TS v6 UnionType `.types` order may differ from the UnionTypeNode `.types` order. Fix: semantic matching for synthetic TypeNodes (pos === -1) instead of index-based — UndefinedKeyword matches undefined type, non-keyword matches non-null/undefined type.
+
+3. **`typeResolver.ts` MappedTypeNode guard (line ~441)**: Skip `symbol.valueDeclaration` when it's a MappedTypeNode, since `.type` on such nodes is the unresolved template.
+
+4. **`typeResolver.ts` synthetic node referencer fallback (line ~796)**: For synthetic TypeNodes (pos === -1), fall back to `this.referencer` instead of calling `typeChecker.getTypeFromTypeNode()` which fails.
+
+5. **`typeResolver.ts` keyword-indexed accessor (line ~445)**: Pass `type` as 5th arg (referencer) to TypeResolver.
+
+6. **`specGenerator2.ts` union type**: Added `typesWithoutUndefined.length === 1` shortcut in `getSwaggerTypeForUnionType` to handle optional enum properties becoming `T | undefined` in TS v6.
+
+7. **Test expectations**: Updated `boolValue*` test expectations from `type: 'string'` to `type: 'boolean'` — TS v6 changed conditional type evaluation: `boolean | undefined extends boolean` = `false` (not `true`).
+
+**How to apply:** If TS is upgraded again, check these same locations for API behavior changes.

package.json

@@ -56,7 +56,7 @@
     "typedoc": "^0.26.7"
   },
   "resolutions": {
-    "typescript": "^5.2.2"
+    "typescript": "^6.0.0"
   },
   "repository": {
     "type": "git",

packages/cli/src/metadataGeneration/typeResolver.ts

@@ -63,8 +63,21 @@ export class TypeResolver {
     }
 
     if (ts.isUnionTypeNode(this.typeNode)) {
+      const referencerUnionTypes = this.referencer?.isUnion() ? this.referencer.types : undefined;
       const types = this.typeNode.types.map(type => {
-        return new TypeResolver(type, this.current, this.parentNode, this.context).resolve();
+        let memberReferencer: ts.Type | undefined;
+        if (referencerUnionTypes && this.typeNode.pos === -1) {
+          // Synthetic union TypeNode: match member by type flag rather than position,
+          // since typeToTypeNode and union .types may be in different order.
+          if (type.kind === ts.SyntaxKind.UndefinedKeyword) {
+            memberReferencer = referencerUnionTypes.find(t => !!(t.flags & ts.TypeFlags.Undefined));
+          } else if (type.kind === ts.SyntaxKind.NullKeyword) {
+            memberReferencer = referencerUnionTypes.find(t => !!(t.flags & ts.TypeFlags.Null));
+          } else {
+            memberReferencer = referencerUnionTypes.find(t => !(t.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null)));
+          }
+        }
+        return new TypeResolver(type, this.current, this.parentNode, this.context, memberReferencer).resolve();
       });
 
       const unionMetaType: Tsoa.UnionType = {
@@ -194,13 +207,23 @@ export class TypeResolver {
             .filter(property => isIgnored(property) === false)
             // Transform to property
             .map(property => {
-              const propertyType = this.current.typeChecker.getTypeOfSymbolAtLocation(property, this.typeNode);
+              const propertyType = this.current.typeChecker.getTypeOfSymbol(property);
+              const required = !this.hasFlag(property, ts.SymbolFlags.Optional);
 
-              const typeNode = this.current.typeChecker.typeToTypeNode(propertyType, undefined, ts.NodeBuilderFlags.NoTruncation)!;
-              const parent = getOneOrigDeclaration(property); //If there are more declarations, we need to get one of them, from where we want to recognize jsDoc
-              const type = new TypeResolver(typeNode, this.current, parent, this.context, propertyType).resolve();
+              // TypeScript v6 includes `undefined` in getTypeOfSymbol for optional properties.
+              // Strip it since optionality is encoded in `required` and including undefined
+              // causes enum types to go through the union path (losing explicit nullable: false).
+              let effectiveType: ts.Type = propertyType;
+              if (!required && propertyType.isUnion()) {
+                const withoutUndefined = propertyType.types.filter(t => !(t.flags & ts.TypeFlags.Undefined));
+                if (withoutUndefined.length === 1) {
+                  effectiveType = withoutUndefined[0];
+                }
+              }
 
-              const required = !this.hasFlag(property, ts.SymbolFlags.Optional);
+              const typeNode = this.current.typeChecker.typeToTypeNode(effectiveType, undefined, ts.NodeBuilderFlags.NoTruncation)!;
+              const parent = getOneOrigDeclaration(property); //If there are more declarations, we need to get one of them, from where we want to recognize jsDoc
+              const type = new TypeResolver(typeNode, this.current, parent, this.context, effectiveType).resolve();
 
               const comments = property.getDocumentationComment(this.current.typeChecker);
               const description = comments.length ? ts.displayPartsToString(comments) : undefined;
@@ -316,7 +339,7 @@ export class TypeResolver {
         if (type.isIndexType()) {
           // in case of generic: keyof T. Not handles all possible cases
           const symbol = type.type.getSymbol();
-          if (symbol && symbol.getFlags() & ts.TypeFlags.TypeParameter) {
+          if (symbol && symbol.getFlags() & ts.SymbolFlags.TypeParameter) {
             const typeName = symbol.getEscapedName();
             throwUnless(typeof typeName === 'string', new GenerateMetadataError(`typeName is not string, but ${typeof typeName}`, typeNode));
 
@@ -428,18 +451,18 @@ export class TypeResolver {
       const typeOfObjectType = typeChecker.getTypeFromTypeNode(objectType);
       const type = isNumberIndexType ? typeOfObjectType.getNumberIndexType() : typeOfObjectType.getStringIndexType();
       throwUnless(type, new GenerateMetadataError(`Could not determine ${isNumberIndexType ? 'number' : 'string'} index on ${typeChecker.typeToString(typeOfObjectType)}`, typeNode));
-      return new TypeResolver(typeChecker.typeToTypeNode(type, objectType, ts.NodeBuilderFlags.NoTruncation)!, current, typeNode, context).resolve();
+      return new TypeResolver(typeChecker.typeToTypeNode(type, objectType, ts.NodeBuilderFlags.NoTruncation)!, current, typeNode, context, type).resolve();
     } else if (ts.isLiteralTypeNode(indexType) && (ts.isStringLiteral(indexType.literal) || ts.isNumericLiteral(indexType.literal))) {
       // Indexed by literal
       const hasType = (node: ts.Node | undefined): node is ts.HasType => node !== undefined && Object.prototype.hasOwnProperty.call(node, 'type');
       const symbol = typeChecker.getPropertyOfType(typeChecker.getTypeFromTypeNode(objectType), indexType.literal.text);
       throwUnless(symbol, new GenerateMetadataError(`Could not determine the keys on ${typeChecker.typeToString(typeChecker.getTypeFromTypeNode(objectType))}`, typeNode));
-      if (hasType(symbol.valueDeclaration) && symbol.valueDeclaration.type) {
+      if (hasType(symbol.valueDeclaration) && symbol.valueDeclaration.type && !ts.isMappedTypeNode(symbol.valueDeclaration)) {
         return new TypeResolver(symbol.valueDeclaration.type, current, typeNode, context).resolve();
       }
       const declaration = typeChecker.getTypeOfSymbolAtLocation(symbol, objectType);
       try {
-        return new TypeResolver(typeChecker.typeToTypeNode(declaration, objectType, ts.NodeBuilderFlags.NoTruncation)!, current, typeNode, context).resolve();
+        return new TypeResolver(typeChecker.typeToTypeNode(declaration, objectType, ts.NodeBuilderFlags.NoTruncation)!, current, typeNode, context, declaration).resolve();
       } catch {
         throw new GenerateMetadataError(
           `Could not determine the keys on ${typeChecker.typeToString(typeChecker.getTypeFromTypeNode(typeChecker.typeToTypeNode(declaration, undefined, ts.NodeBuilderFlags.NoTruncation)!))}`,
@@ -789,7 +812,7 @@ export class TypeResolver {
         const referenceTypes: Tsoa.ReferenceType[] = [];
         for (const declaration of declarations) {
           if (ts.isTypeAliasDeclaration(declaration)) {
-            const referencer = node.pos !== -1 ? this.current.typeChecker.getTypeFromTypeNode(node) : undefined;
+            const referencer = node.pos !== -1 ? this.current.typeChecker.getTypeFromTypeNode(node) : this.referencer;
             referenceTypes.push(new ReferenceTransformer().transform(declaration, refTypeName, this, referencer));
           } else if (EnumTransformer.transformable(declaration)) {
             referenceTypes.push(new EnumTransformer().transform(this, declaration, refTypeName));
@@ -950,9 +973,14 @@ export class TypeResolver {
 
     if (modelTypes.length > 1) {
       // remove types that are from typescript e.g. 'Account'
-      modelTypes = modelTypes.filter(modelType => {
+      // Only apply filter if it leaves at least one declaration; built-ins like Error have all
+      // declarations inside node_modules/typescript (TypeScript v6 ships multiple lib files).
+      const nonTsModelTypes = modelTypes.filter(modelType => {
         return modelType.getSourceFile().fileName.replace(/\\/g, '/').toLowerCase().indexOf('node_modules/typescript') <= -1;
       });
+      if (nonTsModelTypes.length) {
+        modelTypes = nonTsModelTypes;
+      }
 
       modelTypes = this.getDesignatedModels(modelTypes, typeName);
     }

packages/cli/src/swagger/specGenerator2.ts

@@ -455,6 +455,10 @@ export class SpecGenerator2 extends SpecGenerator {
         swaggerType['x-nullable'] = true;
         return swaggerType;
       }
+    } else if (typesWithoutUndefined.length === 1) {
+      // A type that is optional (T | undefined) — return the underlying type directly.
+      // In Swagger 2, optionality is expressed via the required array, not the type itself.
+      return this.getSwaggerType(typesWithoutUndefined[0]);
     } else if (process.env.NODE_ENV !== 'tsoa_test') {
       // eslint-disable-next-line no-console
       console.warn('Swagger 2.0 does not support union types beyond string literals.\n' + 'If you would like to take advantage of this, please change tsoa.json\'s "specVersion" to 3.');

packages/cli/tsconfig.json

@@ -9,6 +9,7 @@
     "lib": ["es2021"],
     "typeRoots": ["node_modules/@types", "./typings"],
     "downlevelIteration": true,
+    "ignoreDeprecations": "6.0",
     "experimentalDecorators": true,
     "declaration": true,
     "noUnusedLocals": true,

packages/runtime/tsconfig.json

@@ -10,6 +10,7 @@
     "lib": ["es2021"],
     "typeRoots": ["node_modules/@types", "./typings"],
     "downlevelIteration": true,
+    "ignoreDeprecations": "6.0",
     "experimentalDecorators": true,
     "declaration": true,
     "noUnusedLocals": true,

packages/tsoa/tsconfig.json

@@ -9,6 +9,7 @@
     "lib": ["es2021"],
     "typeRoots": ["node_modules/@types", "./typings"],
     "downlevelIteration": true,
+    "ignoreDeprecations": "6.0",
     "experimentalDecorators": true,
     "declaration": true,
     "noUnusedLocals": true,

tests/.mocharc.json

@@ -4,6 +4,5 @@
   "exclude": ["esm/**/*"],
   "require": ["ts-node/register", "tsconfig-paths/register"],
   "exit": true,
-  "colors": true,
-  "node-option": ["no-experimental-strip-types"]
+  "colors": true
 }