Merge pull request #3099 from hey-api/feat/sdk-instance-lazy

feat(sdk): lazily initialize sub-resources to improve performance

.changeset/major-cats-divide.md

···
+---
+'@hey-api/openapi-ts': patch
+---
+
+**@hey-api/sdk**: lazily initialize sub-resources to improve performance

dev/openapi-ts.config.ts

···
             // 'invalid',
             // 'object-property-names.yaml',
             // 'openai.yaml',
-            'opencode.yaml',
+            // 'opencode.yaml',
             // 'pagination-ref.yaml',
             // 'schema-const.yaml',
             // 'sdk-instance.yaml',
             // 'sdk-method-class-conflict.yaml',
             // 'sdk-nested-classes.yaml',
+            'sdk-nested-conflict.yaml',
             // 'string-with-format.yaml',
             // 'transformers.json',
             // 'transformers-recursive.json',

packages/openapi-ts-tests/main/test/__snapshots__/2.0.x/plugins/@hey-api/client-fetch/sdk-nested-classes-instance/sdk.gen.ts

···
 }
 
 export class Providers extends HeyApiClient {
-    domains = new Domains({ client: this.client });
+    private _domains?: Domains;
+    get domains(): Domains {
+        return this._domains ??= new Domains({ client: this.client });
+    }
 }
 
 export class Business extends HeyApiClient {
···
         return (options?.client ?? this.client).get<BusinessGetResponses, unknown, ThrowOnError>({ url: '/locations/businesses', ...options });
     }
     
-    providers = new Providers({ client: this.client });
+    private _providers?: Providers;
+    get providers(): Providers {
+        return this._providers ??= new Providers({ client: this.client });
+    }
 }
 
 export class NestedSdkWithInstance extends HeyApiClient {
···
         return (options?.client ?? this.client).get<GetResponses, unknown, ThrowOnError>({ url: '/locations', ...options });
     }
     
-    business = new Business({ client: this.client });
+    private _business?: Business;
+    get business(): Business {
+        return this._business ??= new Business({ client: this.client });
+    }
 }

packages/openapi-ts-tests/main/test/__snapshots__/2.0.x/plugins/@hey-api/sdk/instance/sdk.gen.ts

···
         return (options?.client ?? this.client).put<FooPutResponses, unknown, ThrowOnError>({ url: '/foo', ...options });
     }
     
-    bar = new Bar({ client: this.client });
+    private _bar?: Bar;
+    get bar(): Bar {
+        return this._bar ??= new Bar({ client: this.client });
+    }
 }
 
 export class Sdk extends HeyApiClient {
···
         return (options?.client ?? this.client).get<GetFooBarResponses, unknown, ThrowOnError>({ url: '/foo/bar', ...options });
     }
     
-    foo = new Foo({ client: this.client });
+    private _foo?: Foo;
+    get foo(): Foo {
+        return this._foo ??= new Foo({ client: this.client });
+    }
 }

packages/openapi-ts-tests/main/test/__snapshots__/3.0.x/plugins/@hey-api/client-fetch/sdk-nested-classes-instance/sdk.gen.ts

···
 }
 
 export class Providers extends HeyApiClient {
-    domains = new Domains({ client: this.client });
+    private _domains?: Domains;
+    get domains(): Domains {
+        return this._domains ??= new Domains({ client: this.client });
+    }
 }
 
 export class Business extends HeyApiClient {
···
         return (options?.client ?? this.client).get<BusinessGetResponses, unknown, ThrowOnError>({ url: '/locations/businesses', ...options });
     }
     
-    providers = new Providers({ client: this.client });
+    private _providers?: Providers;
+    get providers(): Providers {
+        return this._providers ??= new Providers({ client: this.client });
+    }
 }
 
 export class NestedSdkWithInstance extends HeyApiClient {
···
         return (options?.client ?? this.client).get<GetResponses, unknown, ThrowOnError>({ url: '/locations', ...options });
     }
     
-    business = new Business({ client: this.client });
+    private _business?: Business;
+    get business(): Business {
+        return this._business ??= new Business({ client: this.client });
+    }
 }

packages/openapi-ts-tests/main/test/__snapshots__/3.0.x/plugins/@hey-api/sdk/instance/sdk.gen.ts

···
         return (options?.client ?? this.client).put<FooPutResponses, unknown, ThrowOnError>({ url: '/foo', ...options });
     }
     
-    bar = new Bar({ client: this.client });
+    private _bar?: Bar;
+    get bar(): Bar {
+        return this._bar ??= new Bar({ client: this.client });
+    }
 }
 
 export class Sdk extends HeyApiClient {
···
         return (options?.client ?? this.client).get<GetFooBarResponses, unknown, ThrowOnError>({ url: '/foo/bar', ...options });
     }
     
-    foo = new Foo({ client: this.client });
+    private _foo?: Foo;
+    get foo(): Foo {
+        return this._foo ??= new Foo({ client: this.client });
+    }
 }

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/plugins/@hey-api/client-fetch/sdk-nested-classes-instance/sdk.gen.ts

···
 }
 
 export class Providers extends HeyApiClient {
-    domains = new Domains({ client: this.client });
+    private _domains?: Domains;
+    get domains(): Domains {
+        return this._domains ??= new Domains({ client: this.client });
+    }
 }
 
 export class Business extends HeyApiClient {
···
         return (options?.client ?? this.client).get<BusinessGetResponses, unknown, ThrowOnError>({ url: '/locations/businesses', ...options });
     }
     
-    providers = new Providers({ client: this.client });
+    private _providers?: Providers;
+    get providers(): Providers {
+        return this._providers ??= new Providers({ client: this.client });
+    }
 }
 
 export class NestedSdkWithInstance extends HeyApiClient {
···
         return (options?.client ?? this.client).get<GetResponses, unknown, ThrowOnError>({ url: '/locations', ...options });
     }
     
-    business = new Business({ client: this.client });
+    private _business?: Business;
+    get business(): Business {
+        return this._business ??= new Business({ client: this.client });
+    }
 }

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/plugins/@hey-api/sdk/instance/sdk.gen.ts

···
         return (options?.client ?? this.client).put<FooPutResponses, unknown, ThrowOnError>({ url: '/foo', ...options });
     }
     
-    bar = new Bar({ client: this.client });
+    private _bar?: Bar;
+    get bar(): Bar {
+        return this._bar ??= new Bar({ client: this.client });
+    }
 }
 
 export class Sdk extends HeyApiClient {
···
         return (options?.client ?? this.client).get<GetFooBarResponses, unknown, ThrowOnError>({ url: '/foo/bar', ...options });
     }
     
-    foo = new Foo({ client: this.client });
+    private _foo?: Foo;
+    get foo(): Foo {
+        return this._foo ??= new Foo({ client: this.client });
+    }
 }

packages/openapi-ts-tests/sdks/__snapshots__/method-class-conflict/instance/sdk.gen.ts

···
         return (options?.client ?? this.client).get<ApiVVersionApiVersionOdataTasksKeyResponses, unknown, ThrowOnError>({ url: '/api/v1/odata/Tasks({key})', ...options });
     }
     
-    accountingCompanies2 = new AccountingCompanies({ client: this.client });
+    private _accountingCompanies2?: AccountingCompanies;
+    get accountingCompanies2(): AccountingCompanies {
+        return this._accountingCompanies2 ??= new AccountingCompanies({ client: this.client });
+    }
     
-    accountingCompanyMemberships2 = new AccountingCompanyMemberships({ client: this.client });
+    private _accountingCompanyMemberships2?: AccountingCompanyMemberships;
+    get accountingCompanyMemberships2(): AccountingCompanyMemberships {
+        return this._accountingCompanyMemberships2 ??= new AccountingCompanyMemberships({ client: this.client });
+    }
     
-    bankAccounts2 = new BankAccounts({ client: this.client });
+    private _bankAccounts2?: BankAccounts;
+    get bankAccounts2(): BankAccounts {
+        return this._bankAccounts2 ??= new BankAccounts({ client: this.client });
+    }
     
-    businessAccountantAssignments2 = new BusinessAccountantAssignments({ client: this.client });
+    private _businessAccountantAssignments2?: BusinessAccountantAssignments;
+    get businessAccountantAssignments2(): BusinessAccountantAssignments {
+        return this._businessAccountantAssignments2 ??= new BusinessAccountantAssignments({ client: this.client });
+    }
     
-    businessDocumentActivities2 = new BusinessDocumentActivities({ client: this.client });
+    private _businessDocumentActivities2?: BusinessDocumentActivities;
+    get businessDocumentActivities2(): BusinessDocumentActivities {
+        return this._businessDocumentActivities2 ??= new BusinessDocumentActivities({ client: this.client });
+    }
     
-    businessDocuments2 = new BusinessDocuments({ client: this.client });
+    private _businessDocuments2?: BusinessDocuments;
+    get businessDocuments2(): BusinessDocuments {
+        return this._businessDocuments2 ??= new BusinessDocuments({ client: this.client });
+    }
     
-    businessDocumentsSummaries2 = new BusinessDocumentsSummaries({ client: this.client });
+    private _businessDocumentsSummaries2?: BusinessDocumentsSummaries;
+    get businessDocumentsSummaries2(): BusinessDocumentsSummaries {
+        return this._businessDocumentsSummaries2 ??= new BusinessDocumentsSummaries({ client: this.client });
+    }
     
-    businesses2 = new Businesses({ client: this.client });
+    private _businesses2?: Businesses;
+    get businesses2(): Businesses {
+        return this._businesses2 ??= new Businesses({ client: this.client });
+    }
     
-    businessSummaries2 = new BusinessSummaries({ client: this.client });
+    private _businessSummaries2?: BusinessSummaries;
+    get businessSummaries2(): BusinessSummaries {
+        return this._businessSummaries2 ??= new BusinessSummaries({ client: this.client });
+    }
     
-    counterparties2 = new Counterparties({ client: this.client });
+    private _counterparties2?: Counterparties;
+    get counterparties2(): Counterparties {
+        return this._counterparties2 ??= new Counterparties({ client: this.client });
+    }
     
-    dataBoxCredentials2 = new DataBoxCredentials({ client: this.client });
+    private _dataBoxCredentials2?: DataBoxCredentials;
+    get dataBoxCredentials2(): DataBoxCredentials {
+        return this._dataBoxCredentials2 ??= new DataBoxCredentials({ client: this.client });
+    }
     
-    documentTypes2 = new DocumentTypes({ client: this.client });
+    private _documentTypes2?: DocumentTypes;
+    get documentTypes2(): DocumentTypes {
+        return this._documentTypes2 ??= new DocumentTypes({ client: this.client });
+    }
     
-    invitations2 = new Invitations({ client: this.client });
+    private _invitations2?: Invitations;
+    get invitations2(): Invitations {
+        return this._invitations2 ??= new Invitations({ client: this.client });
+    }
     
-    invoices2 = new Invoices({ client: this.client });
+    private _invoices2?: Invoices;
+    get invoices2(): Invoices {
+        return this._invoices2 ??= new Invoices({ client: this.client });
+    }
     
-    invoiceSettings2 = new InvoiceSettings({ client: this.client });
+    private _invoiceSettings2?: InvoiceSettings;
+    get invoiceSettings2(): InvoiceSettings {
+        return this._invoiceSettings2 ??= new InvoiceSettings({ client: this.client });
+    }
     
-    licenses2 = new Licenses({ client: this.client });
+    private _licenses2?: Licenses;
+    get licenses2(): Licenses {
+        return this._licenses2 ??= new Licenses({ client: this.client });
+    }
     
-    personalDocuments2 = new PersonalDocuments({ client: this.client });
+    private _personalDocuments2?: PersonalDocuments;
+    get personalDocuments2(): PersonalDocuments {
+        return this._personalDocuments2 ??= new PersonalDocuments({ client: this.client });
+    }
     
-    recurringTasks2 = new RecurringTasks({ client: this.client });
+    private _recurringTasks2?: RecurringTasks;
+    get recurringTasks2(): RecurringTasks {
+        return this._recurringTasks2 ??= new RecurringTasks({ client: this.client });
+    }
     
-    tasks2 = new Tasks({ client: this.client });
+    private _tasks2?: Tasks;
+    get tasks2(): Tasks {
+        return this._tasks2 ??= new Tasks({ client: this.client });
+    }
 }
 
 export class User extends HeyApiClient {
···
 }
 
 export class VVersionApiVersion extends HeyApiClient {
-    odata = new Odata({ client: this.client });
+    private _odata?: Odata;
+    get odata(): Odata {
+        return this._odata ??= new Odata({ client: this.client });
+    }
     
-    user = new User({ client: this.client });
+    private _user?: User;
+    get user(): User {
+        return this._user ??= new User({ client: this.client });
+    }
 }
 
 export class Api extends HeyApiClient {
-    vVersionApiVersion = new VVersionApiVersion({ client: this.client });
+    private _vVersionApiVersion?: VVersionApiVersion;
+    get vVersionApiVersion(): VVersionApiVersion {
+        return this._vVersionApiVersion ??= new VVersionApiVersion({ client: this.client });
+    }
 }
 
 export class MapIdentityApi extends HeyApiClient {
-    api = new Api({ client: this.client });
+    private _api?: Api;
+    get api(): Api {
+        return this._api ??= new Api({ client: this.client });
+    }
 }
 
 export class Sdk extends HeyApiClient {
···
         });
     }
     
-    api = new Api({ client: this.client });
+    private _api?: Api;
+    get api(): Api {
+        return this._api ??= new Api({ client: this.client });
+    }
     
-    mapIdentityApi = new MapIdentityApi({ client: this.client });
+    private _mapIdentityApi?: MapIdentityApi;
+    get mapIdentityApi(): MapIdentityApi {
+        return this._mapIdentityApi ??= new MapIdentityApi({ client: this.client });
+    }
 }

packages/openapi-ts/src/plugins/@hey-api/sdk/shared/class.ts

···
             symbolCurrentClass.meta!.resourceId!,
           )!;
 
-          // avoid duplicate methods
-          if (currentClass.methods.has(entry.methodName)) {
-            return;
-          }
+          const methodName = entry.methodName;
+          if (currentClass.methods.has(methodName)) return;
+          currentClass.methods.add(methodName);
 
           const opParameters = operationParameters({
             isRequiredOptions,
···
             operation,
             plugin,
           });
-          const functionNode = $.method(entry.methodName, (m) =>
+          const functionNode = $.method(methodName, (m) =>
             m
               .$if(createOperationComment(operation), (m, v) => m.doc(v))
               .public()
···
             currentClass.nodes.push($.newline(), functionNode);
           }
 
-          currentClass.methods.add(entry.methodName);
-
           sdkClasses.set(symbolCurrentClass.meta!.resourceId!, currentClass);
         });
       }
···
     },
   );
 
-  const heyApiClientIndex = plugin.config.instance
-    ? plugin.node(null)
-    : undefined;
-  const symbolHeyApiClient =
-    heyApiClientIndex !== undefined
+  const clientIndex = plugin.config.instance ? plugin.node(null) : undefined;
+  const symbolClient =
+    clientIndex !== undefined
       ? plugin.symbol('HeyApiClient', {
           meta: {
             category: 'utility',
···
           },
         })
       : undefined;
-  const heyApiRegistryIndex = plugin.config.instance
-    ? plugin.node(null)
-    : undefined;
+  const registryIndex = plugin.config.instance ? plugin.node(null) : undefined;
 
   const generateClass = (currentClass: SdkClassEntry) => {
-    if (generatedClasses.has(currentClass.className)) {
-      return;
-    }
+    const resourceId = currentClass.className;
 
-    const resourceId = currentClass.className;
+    if (generatedClasses.has(resourceId)) return;
     generatedClasses.add(resourceId);
 
-    if (currentClass.classes.size) {
-      for (const childClassName of currentClass.classes) {
-        const childClass = sdkClasses.get(childClassName)!;
-        generateClass(childClass);
+    if (clientIndex !== undefined && symbolClient && !symbolClient.node) {
+      const node = createClientClass({ plugin, symbol: symbolClient });
+      plugin.node(node, clientIndex);
+    }
 
-        const refChildClass = plugin.referenceSymbol({
-          category: 'utility',
-          resource: 'class',
-          resourceId: childClass.className,
-          tool: 'sdk',
-        });
+    for (const childClassName of currentClass.classes) {
+      const childClass = sdkClasses.get(childClassName)!;
+      generateClass(childClass);
 
-        const originalMemberName = stringCase({
-          case: 'camelCase',
-          value: refChildClass.meta!.resourceId!,
-        });
-        // avoid collisions with existing method names
-        let memberName = originalMemberName;
-        if (currentClass.methods.has(memberName)) {
-          let index = 2;
-          let attempt = `${memberName}${index}`;
-          while (currentClass.methods.has(attempt)) {
-            attempt = `${memberName}${index++}`;
-          }
-          memberName = attempt;
+      const refChildClass = plugin.referenceSymbol({
+        category: 'utility',
+        resource: 'class',
+        resourceId: childClass.className,
+        tool: 'sdk',
+      });
+
+      const originalMemberName = stringCase({
+        case: 'camelCase',
+        value: refChildClass.meta!.resourceId!,
+      });
+      // avoid collisions with existing method names
+      let memberName = originalMemberName;
+      if (currentClass.methods.has(memberName)) {
+        let index = 2;
+        let attempt = `${memberName}${index}`;
+        while (currentClass.methods.has(attempt)) {
+          attempt = `${memberName}${index++}`;
         }
-        currentClass.methods.add(memberName);
+        memberName = attempt;
+      }
+      currentClass.methods.add(memberName);
 
+      if (currentClass.nodes.length > 0) {
+        currentClass.nodes.push($.newline());
+      }
+
+      if (plugin.config.instance) {
+        const privateName = plugin.symbol(`_${memberName}`);
+        const privateNode = $.field(privateName, (f) =>
+          f.private().optional().type(refChildClass),
+        );
+        currentClass.nodes.push(privateNode);
+        const getterNode = $.getter(memberName, (g) =>
+          g.returns(refChildClass).do(
+            $('this')
+              .attr(privateName)
+              .nullishAssign(
+                $.new(refChildClass).args(
+                  $.object().prop('client', $('this').attr('client')),
+                ),
+              )
+              .return(),
+          ),
+        );
+        currentClass.nodes.push(getterNode);
+      } else {
         const subClassReferenceNode = plugin.isSymbolRegistered(
           refChildClass.id,
         )
-          ? $.field(memberName, (f) =>
-              f
-                .static(!plugin.config.instance)
-                .assign(
-                  plugin.config.instance
-                    ? $.new(refChildClass).args(
-                        $.object().prop('client', $('this').attr('client')),
-                      )
-                    : $(refChildClass),
-                ),
-            )
+          ? $.field(memberName, (f) => f.static().assign($(refChildClass)))
           : $.getter(memberName, (g) =>
-              g
-                .$if(!plugin.config.instance, (g) => g.public().static())
-                .do(
-                  $.return(
-                    plugin.config.instance
-                      ? $.new(refChildClass).args(
-                          $.object().prop('client', $('this').attr('client')),
-                        )
-                      : refChildClass,
-                  ),
-                ),
+              g.public().static().do($.return(refChildClass)),
             );
-
-        if (!currentClass.nodes.length) {
-          currentClass.nodes.push(subClassReferenceNode);
-        } else {
-          currentClass.nodes.push($.newline(), subClassReferenceNode);
-        }
+        currentClass.nodes.push(subClassReferenceNode);
       }
     }
 
-    if (
-      heyApiClientIndex !== undefined &&
-      symbolHeyApiClient &&
-      !symbolHeyApiClient.node
-    ) {
-      const node = createClientClass({
-        plugin,
-        symbol: symbolHeyApiClient,
-      });
-      plugin.node(node, heyApiClientIndex);
-    }
-
     const symbol = plugin.symbol(resourceId, {
       meta: {
         category: 'utility',
···
       },
     });
 
-    if (currentClass.root && heyApiRegistryIndex !== undefined) {
-      const symClient = plugin.getSymbol({
-        category: 'client',
-      });
+    if (currentClass.root && registryIndex !== undefined) {
+      const symClient = plugin.getSymbol({ category: 'client' });
       const isClientRequired = !plugin.config.client || !symClient;
       const symbolClient = plugin.referenceSymbol({
         category: 'external',
···
         sdkSymbol: symbol,
         symbol: symbolRegistry,
       });
-      plugin.node(node, heyApiRegistryIndex);
+      plugin.node(node, registryIndex);
       const registryNode = $.field(registryName, (f) =>
         f
           .public()
···
 
     const node = $.class(symbol)
       .export()
-      .extends(symbolHeyApiClient)
-      .$if(currentClass.root && isAngularClient, (c) =>
+      .extends(symbolClient)
+      .$if(isAngularClient && currentClass.root, (c) =>
         c.decorator(
           plugin.referenceSymbol({
             category: 'external',

packages/openapi-ts/src/ts-dsl/decl/field.ts

···
   ReadonlyMixin,
   StaticMixin,
 } from '../mixins/modifiers';
+import { OptionalMixin } from '../mixins/optional';
 import { ValueMixin } from '../mixins/value';
+import { TokenTsDsl } from '../token';
 import type { TypeExprName } from '../type/expr';
 import { TypeExprTsDsl } from '../type/expr';
 
···
 
 const Mixed = DecoratorMixin(
   DocMixin(
-    PrivateMixin(
-      ProtectedMixin(
-        PublicMixin(
-          ReadonlyMixin(StaticMixin(ValueMixin(TsDsl<ts.PropertyDeclaration>))),
+    OptionalMixin(
+      PrivateMixin(
+        ProtectedMixin(
+          PublicMixin(
+            ReadonlyMixin(
+              StaticMixin(ValueMixin(TsDsl<ts.PropertyDeclaration>)),
+            ),
+          ),
         ),
       ),
     ),
···
     const node = ts.factory.createPropertyDeclaration(
       [...this.$decorators(ctx), ...this.modifiers],
       this.$node(ctx, this.name) as ts.PropertyName,
-      undefined,
+      this._optional ? this.$node(ctx, new TokenTsDsl().optional()) : undefined,
       this.$type(ctx, this._type),
       this.$value(ctx),
     );

packages/openapi-ts/src/ts-dsl/decl/func.ts

···
 import { isSymbol, ref } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import { TsDsl, TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { AsMixin } from '../mixins/as';
 import { DecoratorMixin } from '../mixins/decorator';
 import { DoMixin } from '../mixins/do';
···
 } from '../mixins/modifiers';
 import { ParamMixin } from '../mixins/param';
 import { TypeParamsMixin } from '../mixins/type-params';
+import { TypeReturnsMixin } from '../mixins/type-returns';
 import { BlockTsDsl } from '../stmt/block';
-import { TypeExprTsDsl } from '../type/expr';
 import { safeRuntimeName } from '../utils/name';
 
 export type FuncMode = 'arrow' | 'decl' | 'expr';
···
               PrivateMixin(
                 ProtectedMixin(
                   PublicMixin(
-                    StaticMixin(TypeParamsMixin(TsDsl<ts.ArrowFunction>)),
+                    StaticMixin(
+                      TypeParamsMixin(
+                        TypeReturnsMixin(TsDsl<ts.ArrowFunction>),
+                      ),
+                    ),
                   ),
                 ),
               ),
···
 
   protected mode?: FuncMode;
   protected name?: Ref<FuncName>;
-  protected _returns?: TypeTsDsl;
 
   constructor();
   constructor(fn: (f: ImplFuncTsDsl<'arrow'>) => void);
···
     try {
       super.analyze(ctx);
       ctx.analyze(this.name);
-      ctx.analyze(this._returns);
     } finally {
       ctx.popScope();
     }
···
     return this as unknown as FuncTsDsl<'expr'>;
   }
 
-  /** Sets the return type. */
-  returns(type: string | TypeTsDsl): this {
-    this._returns = type instanceof TypeTsDsl ? type : new TypeExprTsDsl(type);
-    return this;
-  }
-
   // @ts-expect-error --- need to fix types ---
   override toAst(
     ctx: AstContext,
···
         this.$node(ctx, this.name) as ts.Identifier,
         this.$generics(ctx),
         this.$params(ctx),
-        this.$type(ctx, this._returns),
+        this.$returns(ctx),
         body,
       ) as any;
       return this.$docs(ctx, node);
···
         this.$node(ctx, this.name) as ts.Identifier,
         this.$generics(ctx),
         this.$params(ctx),
-        this.$type(ctx, this._returns),
+        this.$returns(ctx),
         body,
       ) as any;
       return this.$docs(ctx, node);
···
       this.modifiers,
       this.$generics(ctx),
       this.$params(ctx),
-      this.$type(ctx, this._returns),
+      this.$returns(ctx),
       undefined,
       body.statements.length === 1 &&
         ts.isReturnStatement(body.statements[0]!) &&

packages/openapi-ts/src/ts-dsl/decl/getter.ts

···
   StaticMixin,
 } from '../mixins/modifiers';
 import { ParamMixin } from '../mixins/param';
+import { TypeReturnsMixin } from '../mixins/type-returns';
 import { BlockTsDsl } from '../stmt/block';
 
 export type GetterName = string | ts.PropertyName;
···
           ParamMixin(
             PrivateMixin(
               ProtectedMixin(
-                PublicMixin(StaticMixin(TsDsl<ts.GetAccessorDeclaration>)),
+                PublicMixin(
+                  StaticMixin(
+                    TypeReturnsMixin(TsDsl<ts.GetAccessorDeclaration>),
+                  ),
+                ),
               ),
             ),
           ),
···
       [...this.$decorators(ctx), ...this.modifiers],
       this.name,
       this.$params(ctx),
-      undefined,
+      this.$returns(ctx),
       this.$node(ctx, new BlockTsDsl(...this._do).pretty()),
     );
     return this.$docs(ctx, node);

packages/openapi-ts/src/ts-dsl/decl/method.ts

···
 import type { AnalysisContext, AstContext } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import { TsDsl, TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { DecoratorMixin } from '../mixins/decorator';
 import { DoMixin } from '../mixins/do';
 import { DocMixin } from '../mixins/doc';
···
 import { OptionalMixin } from '../mixins/optional';
 import { ParamMixin } from '../mixins/param';
 import { TypeParamsMixin } from '../mixins/type-params';
+import { TypeReturnsMixin } from '../mixins/type-returns';
 import { BlockTsDsl } from '../stmt/block';
 import { TokenTsDsl } from '../token';
-import { TypeExprTsDsl } from '../type/expr';
 
 const Mixed = AbstractMixin(
   AsyncMixin(
···
               PrivateMixin(
                 ProtectedMixin(
                   PublicMixin(
-                    StaticMixin(TypeParamsMixin(TsDsl<ts.MethodDeclaration>)),
+                    StaticMixin(
+                      TypeParamsMixin(
+                        TypeReturnsMixin(TsDsl<ts.MethodDeclaration>),
+                      ),
+                    ),
                   ),
                 ),
               ),
···
   readonly '~dsl' = 'MethodTsDsl';
 
   protected name: string;
-  protected _returns?: TypeTsDsl;
 
   constructor(name: string, fn?: (m: MethodTsDsl) => void) {
     super();
···
     ctx.pushScope();
     try {
       super.analyze(ctx);
-      ctx.analyze(this._returns);
     } finally {
       ctx.popScope();
     }
   }
 
-  /** Sets the return type. */
-  returns(type: string | TypeTsDsl): this {
-    this._returns = type instanceof TypeTsDsl ? type : new TypeExprTsDsl(type);
-    return this;
-  }
-
   override toAst(ctx: AstContext) {
     const node = ts.factory.createMethodDeclaration(
       [...this.$decorators(ctx), ...this.modifiers],
···
       this._optional ? this.$node(ctx, new TokenTsDsl().optional()) : undefined,
       this.$generics(ctx),
       this.$params(ctx),
-      this.$type(ctx, this._returns),
+      this.$returns(ctx),
       this.$node(ctx, new BlockTsDsl(...this._do).pretty()),
     );
     return this.$docs(ctx, node);

packages/openapi-ts/src/ts-dsl/expr/binary.ts

···
   | '>'
   | '>='
   | '??'
+  | '??='
   | '||';
 
 const Mixed = AsMixin(ExprMixin(TsDsl<ts.BinaryExpression>));
···
     return this.opAndExpr('!==', expr);
   }
 
+  /** Nullish assignment — `this ??= expr` */
+  nullishAssign(expr: Expr): this {
+    return this.opAndExpr('??=', expr);
+  }
+
   /** Logical OR — `this || expr` */
   or(expr: Expr): this {
     return this.opAndExpr('||', expr);
···
       '>': ts.SyntaxKind.GreaterThanToken,
       '>=': ts.SyntaxKind.GreaterThanEqualsToken,
       '??': ts.SyntaxKind.QuestionQuestionToken,
+      '??=': ts.SyntaxKind.QuestionQuestionEqualsToken,
       '||': ts.SyntaxKind.BarBarToken,
     };
     const token = tokenMap[op];

packages/openapi-ts/src/ts-dsl/mixins/operator.ts

···
   minus(expr: Expr): BinaryTsDsl;
   /** Strict inequality — `this !== expr` */
   neq(expr: Expr): BinaryTsDsl;
+  /** Nullish assignment — `this ??= expr` */
+  nullishAssign(expr: Expr): BinaryTsDsl;
   /** Logical OR — `this || expr` */
   or(expr: Expr): BinaryTsDsl;
   /** Addition — `this + expr` */
···
 
     protected neq(expr: Expr): BinaryTsDsl {
       return new BinaryTsDsl(this).neq(expr);
+    }
+
+    protected nullishAssign(expr: Expr): BinaryTsDsl {
+      return new BinaryTsDsl(this).nullishAssign(expr);
     }
 
     protected or(expr: Expr): BinaryTsDsl {

packages/openapi-ts/src/ts-dsl/mixins/type-returns.ts

···
+import type { AnalysisContext, AstContext, Node } from '@hey-api/codegen-core';
+import type ts from 'typescript';
+
+import { TypeTsDsl } from '../base';
+import type { TypeExprName } from '../type/expr';
+import { TypeExprTsDsl } from '../type/expr';
+import type { BaseCtor, MixinCtor } from './types';
+
+export interface TypeReturnsMethods extends Node {
+  /** Returns the return type node. */
+  $returns(ctx: AstContext): ts.TypeNode | undefined;
+  /** Sets the return type. */
+  returns(type: TypeExprName | TypeTsDsl): this;
+}
+
+export function TypeReturnsMixin<T extends ts.Node, TBase extends BaseCtor<T>>(
+  Base: TBase,
+) {
+  abstract class TypeReturns extends Base {
+    protected _returns?: TypeTsDsl;
+
+    override analyze(ctx: AnalysisContext): void {
+      super.analyze(ctx);
+      ctx.analyze(this._returns);
+    }
+
+    protected returns(type: TypeExprName | TypeTsDsl): this {
+      this._returns =
+        type instanceof TypeTsDsl ? type : new TypeExprTsDsl(type);
+      return this;
+    }
+
+    protected $returns(ctx: AstContext): ts.TypeNode | undefined {
+      return this.$type(ctx, this._returns);
+    }
+  }
+
+  return TypeReturns as unknown as MixinCtor<TBase, TypeReturnsMethods>;
+}

packages/openapi-ts/src/ts-dsl/type/and.ts

···
 import { ref } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import { TypeTsDsl } from '../base';
+import type { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 
 type Type = Symbol | string | ts.TypeNode | TypeTsDsl;
 
-const Mixed = TypeTsDsl<ts.IntersectionTypeNode>;
+const Mixed = TsDsl<ts.IntersectionTypeNode>;
 
 export class TypeAndTsDsl extends Mixed {
   readonly '~dsl' = 'TypeAndTsDsl';

packages/openapi-ts/src/ts-dsl/type/attr.ts

···
 import ts from 'typescript';
 
 import type { MaybeTsDsl } from '../base';
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { TypeExprMixin } from '../mixins/type-expr';
 
 type Base = Symbol | string | MaybeTsDsl<ts.EntityName>;
 type Right = Symbol | string | ts.Identifier;
 
-const Mixed = TypeExprMixin(TypeTsDsl<ts.QualifiedName>);
+const Mixed = TypeExprMixin(TsDsl<ts.QualifiedName>);
 
 export class TypeAttrTsDsl extends Mixed {
   readonly '~dsl' = 'TypeAttrTsDsl';

packages/openapi-ts/src/ts-dsl/type/expr.ts

···
 import { isNode, ref } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { TypeArgsMixin } from '../mixins/type-args';
 import { TypeExprMixin } from '../mixins/type-expr';
 import { f } from '../utils/factories';
···
   fn?: TypeExprFn,
 ) => TypeExprTsDsl;
 
-const Mixed = TypeArgsMixin(TypeExprMixin(TypeTsDsl<ts.TypeReferenceNode>));
+const Mixed = TypeArgsMixin(TypeExprMixin(TsDsl<ts.TypeReferenceNode>));
 
 export class TypeExprTsDsl extends Mixed {
   readonly '~dsl' = 'TypeExprTsDsl';

packages/openapi-ts/src/ts-dsl/type/func.ts

···
 import type { AnalysisContext, AstContext } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { DocMixin } from '../mixins/doc';
 import { ParamMixin } from '../mixins/param';
 import { TypeParamsMixin } from '../mixins/type-params';
-import { TypeExprTsDsl } from './expr';
+import { TypeReturnsMixin } from '../mixins/type-returns';
 
 const Mixed = DocMixin(
-  ParamMixin(TypeParamsMixin(TypeTsDsl<ts.FunctionTypeNode>)),
+  ParamMixin(TypeParamsMixin(TypeReturnsMixin(TsDsl<ts.FunctionTypeNode>))),
 );
 
 export class TypeFuncTsDsl extends Mixed {
   readonly '~dsl' = 'TypeFuncTsDsl';
-
-  protected _returns?: TypeTsDsl;
 
   override analyze(ctx: AnalysisContext): void {
     super.analyze(ctx);
-    ctx.analyze(this._returns);
-  }
-
-  /** Sets the return type. */
-  returns(type: string | TypeTsDsl): this {
-    this._returns = type instanceof TypeTsDsl ? type : new TypeExprTsDsl(type);
-    return this;
   }
 
   override toAst(ctx: AstContext) {
-    if (this._returns === undefined) {
+    const returns = this.$returns(ctx);
+    if (returns === undefined) {
       throw new Error('Missing return type in function type DSL');
     }
     const node = ts.factory.createFunctionTypeNode(
       this.$generics(ctx),
       this.$params(ctx),
-      this.$type(ctx, this._returns),
+      returns,
     );
     return this.$docs(ctx, node);
   }

packages/openapi-ts/src/ts-dsl/type/idx-sig.ts

···
 import ts from 'typescript';
 
 import type { MaybeTsDsl } from '../base';
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { DocMixin } from '../mixins/doc';
 import { ReadonlyMixin } from '../mixins/modifiers';
 
 export type TypeIdxSigName = string;
 export type TypeIdxSigType = string | MaybeTsDsl<ts.TypeNode>;
 
-const Mixed = DocMixin(ReadonlyMixin(TypeTsDsl<ts.IndexSignatureDeclaration>));
+const Mixed = DocMixin(ReadonlyMixin(TsDsl<ts.IndexSignatureDeclaration>));
 
 export class TypeIdxSigTsDsl extends Mixed {
   readonly '~dsl' = 'TypeIdxSigTsDsl';

packages/openapi-ts/src/ts-dsl/type/idx.ts

···
 import ts from 'typescript';
 
 import type { MaybeTsDsl } from '../base';
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { TypeExprMixin } from '../mixins/type-expr';
 import { f } from '../utils/factories';
 
···
 type Index = string | number | MaybeTsDsl<ts.TypeNode>;
 export type TypeIdxCtor = (base: Base, index: Index) => TypeIdxTsDsl;
 
-const Mixed = TypeExprMixin(TypeTsDsl<ts.IndexedAccessTypeNode>);
+const Mixed = TypeExprMixin(TsDsl<ts.IndexedAccessTypeNode>);
 
 export class TypeIdxTsDsl extends Mixed {
   readonly '~dsl' = 'TypeIdxTsDsl';

packages/openapi-ts/src/ts-dsl/type/literal.ts

···
 import type { AnalysisContext, AstContext } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { LiteralTsDsl } from '../expr/literal';
 
-const Mixed = TypeTsDsl<ts.LiteralTypeNode>;
+const Mixed = TsDsl<ts.LiteralTypeNode>;
 
 export class TypeLiteralTsDsl extends Mixed {
   readonly '~dsl' = 'TypeLiteralTsDsl';

packages/openapi-ts/src/ts-dsl/type/mapped.ts

···
 import ts from 'typescript';
 
 import type { MaybeTsDsl } from '../base';
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { TokenTsDsl } from '../token';
 
-const Mixed = TypeTsDsl<ts.MappedTypeNode>;
+const Mixed = TsDsl<ts.MappedTypeNode>;
 
 export class TypeMappedTsDsl extends Mixed {
   readonly '~dsl' = 'TypeMappedTsDsl';

packages/openapi-ts/src/ts-dsl/type/object.ts

···
 import type { AnalysisContext, AstContext } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { TypeIdxSigTsDsl } from './idx-sig';
 import { TypePropTsDsl } from './prop';
 
-const Mixed = TypeTsDsl<ts.TypeNode>;
+const Mixed = TsDsl<ts.TypeNode>;
 
 export class TypeObjectTsDsl extends Mixed {
   readonly '~dsl' = 'TypeObjectTsDsl';

packages/openapi-ts/src/ts-dsl/type/operator.ts

···
 import ts from 'typescript';
 
 import type { MaybeTsDsl } from '../base';
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { f } from '../utils/factories';
 
 type Op =
···
 type Type = string | MaybeTsDsl<ts.TypeNode>;
 export type TypeOperatorCtor = () => TypeOperatorTsDsl;
 
-const Mixed = TypeTsDsl<ts.TypeOperatorNode>;
+const Mixed = TsDsl<ts.TypeOperatorNode>;
 
 /**
  * Builds a TypeScript `TypeOperatorNode`, such as:

packages/openapi-ts/src/ts-dsl/type/or.ts

···
 import { ref } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import { TypeTsDsl } from '../base';
+import type { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 
 type Type = Symbol | string | ts.TypeNode | TypeTsDsl;
 
-const Mixed = TypeTsDsl<ts.UnionTypeNode>;
+const Mixed = TsDsl<ts.UnionTypeNode>;
 
 export class TypeOrTsDsl extends Mixed {
   readonly '~dsl' = 'TypeOrTsDsl';

packages/openapi-ts/src/ts-dsl/type/param.ts

···
 import { ref } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import type { MaybeTsDsl } from '../base';
-import { TypeTsDsl } from '../base';
+import type { MaybeTsDsl, TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 
 export type TypeParamName = Symbol | string;
 export type TypeParamExpr = Symbol | string | boolean | MaybeTsDsl<TypeTsDsl>;
 
-const Mixed = TypeTsDsl<ts.TypeParameterDeclaration>;
+const Mixed = TsDsl<ts.TypeParameterDeclaration>;
 
 export class TypeParamTsDsl extends Mixed {
   readonly '~dsl' = 'TypeParamTsDsl';

packages/openapi-ts/src/ts-dsl/type/prop.ts

···
 import ts from 'typescript';
 
 import type { MaybeTsDsl } from '../base';
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { DocMixin } from '../mixins/doc';
 import { ReadonlyMixin } from '../mixins/modifiers';
 import { OptionalMixin } from '../mixins/optional';
···
 export type TypePropName = string;
 export type TypePropType = Symbol | string | MaybeTsDsl<ts.TypeNode>;
 
-const Mixed = DocMixin(OptionalMixin(ReadonlyMixin(TypeTsDsl<ts.TypeElement>)));
+const Mixed = DocMixin(OptionalMixin(ReadonlyMixin(TsDsl<ts.TypeElement>)));
 
 export class TypePropTsDsl extends Mixed {
   readonly '~dsl' = 'TypePropTsDsl';

packages/openapi-ts/src/ts-dsl/type/query.ts

···
 import type { AnalysisContext, AstContext } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import type { MaybeTsDsl } from '../base';
-import { TypeTsDsl } from '../base';
+import type { MaybeTsDsl, TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 import { TypeExprMixin } from '../mixins/type-expr';
 import { f } from '../utils/factories';
 
 export type TypeQueryExpr = string | MaybeTsDsl<TypeTsDsl | ts.Expression>;
 export type TypeQueryCtor = (expr: TypeQueryExpr) => TypeQueryTsDsl;
 
-const Mixed = TypeExprMixin(TypeTsDsl<ts.TypeQueryNode>);
+const Mixed = TypeExprMixin(TsDsl<ts.TypeQueryNode>);
 
 export class TypeQueryTsDsl extends Mixed {
   readonly '~dsl' = 'TypeQueryTsDsl';

packages/openapi-ts/src/ts-dsl/type/template.ts

···
 import ts from 'typescript';
 
 import type { MaybeTsDsl } from '../base';
-import { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 
-const Mixed = TypeTsDsl<ts.TemplateLiteralTypeNode>;
+const Mixed = TsDsl<ts.TemplateLiteralTypeNode>;
 
 export class TypeTemplateTsDsl extends Mixed {
   readonly '~dsl' = 'TypeTemplateTsDsl';

packages/openapi-ts/src/ts-dsl/type/tuple.ts

···
 import type { AnalysisContext, AstContext } from '@hey-api/codegen-core';
 import ts from 'typescript';
 
-import { TypeTsDsl } from '../base';
+import type { TypeTsDsl } from '../base';
+import { TsDsl } from '../base';
 
-const Mixed = TypeTsDsl<ts.TupleTypeNode>;
+const Mixed = TsDsl<ts.TupleTypeNode>;
 
 export class TypeTupleTsDsl extends Mixed {
   readonly '~dsl' = 'TypeTupleTsDsl';

specs/3.1.x/sdk-nested-conflict.yaml

···
+openapi: 3.1.1
+info:
+  title: OpenAPI 3.1.1 sdk nested conflict example
+  version: 1
+paths:
+  /v1/providers:
+    get:
+      operationId: providers.list
+      summary: List Providers
+      tags:
+        - providers
+  /v1/tenants/{tenantId}/providers:
+    get:
+      operationId: tenants.providers.list
+      summary: List Tenant Providers
+      tags:
+        - tenants
+        - tenantProviders
+      parameters:
+        - name: tenantId
+          in: path
+          required: true
+          schema:
+            type: string
+            description: Tenant ID