Fix TS2615 circular reference error with mutually-recursive OpenAPI schemas (e.g. Argo Workflows) (#3665)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: ardatan <20847995+ardatan@users.noreply.github.com>

Author: Copilot

.changeset/fix-mutual-circular-ref.md

@@ -0,0 +1,36 @@
+---
+"fets": patch
+---
+
+Fix "Type of property circularly references itself" error for mutually-recursive schemas (e.g. Argo Workflows OpenAPI spec)
+
+Large OpenAPI specs such as Argo Workflows contain **mutually-recursive** schema references (e.g. `Template → DAGTemplate → DAGTask → Template`). These schemas caused TypeScript error TS2615 when used with `OASModel`, `OASOutput`, `OASJSONResponseSchema`, or `createClient`.
+
+The root cause was in the `Circular<T>` type helper, which detected only:
+1. Direct self-references (`child: Node` where `Node.child` resolves back to the same `Node` type)
+2. Array self-references added in a previous fix (`children: Node[]`)
+
+It did **not** detect indirect mutual recursion (Schema A → Schema B → Schema A), because the recursive type check `Circular<PropertyValue<A>>` eventually calls `Circular<A>` again, causing TypeScript to hit its recursion limit and silently fail, leaving the deserializer enabled and triggering TS2615 inside `json-schema-to-ts`.
+
+The fix extends `Circular<T>` to also return `true` when any property of the schema is a **resolved `$ref`** — identified by the presence of a `$id` field that `NormalizeOAS` injects. Such schemas were resolved from `$ref` entries in the original OpenAPI document and may participate in complex circular reference chains. Disabling the deserializer expansion for these schemas avoids the TS2615 error.
+
+**Before (broken):**
+```typescript
+// Template → DAGTemplate → DAGTask → Template caused TS2615
+type NormalizedArgo = NormalizeOAS<typeof argoWorkflowsOAS>;
+type TemplateType = OASModel<NormalizedArgo, 'Template'>; // Error: TS2615
+const client = createClient<NormalizedArgo>({});
+await client['/workflow'].get(); // Error: TS2615
+```
+
+**After (fixed):**
+```typescript
+type NormalizedArgo = NormalizeOAS<typeof argoWorkflowsOAS>;
+type TemplateType = OASModel<NormalizedArgo, 'Template'>; // Works!
+const client = createClient<NormalizedArgo>({});
+const res = await client['/workflow'].get(); // Works!
+if (res.ok) {
+  const body = await res.json();
+  body.dag?.tasks?.[0]?.name; // correctly typed as string | undefined
+}
+```

packages/fets/src/types.ts

@@ -167,11 +167,13 @@ export type Circular<TJSONSchema extends JSONSchema> = TJSONSchema extends {
 }
   ? TJSONSchema extends PropertyValue<TJSONSchema, Property<TJSONSchema>>
     ? true
-    : [ArrayItemValue<PropertyValue<TJSONSchema, Property<TJSONSchema>>>] extends [never]
-      ? Circular<PropertyValue<TJSONSchema, Property<TJSONSchema>>>
-      : ArrayItemValue<PropertyValue<TJSONSchema, Property<TJSONSchema>>> extends TJSONSchema
-        ? true
-        : Circular<PropertyValue<TJSONSchema, Property<TJSONSchema>>>
+    : [Extract<PropertyValue<TJSONSchema, Property<TJSONSchema>>, { $id: string }>] extends [never]
+      ? [ArrayItemValue<PropertyValue<TJSONSchema, Property<TJSONSchema>>>] extends [never]
+        ? Circular<PropertyValue<TJSONSchema, Property<TJSONSchema>>>
+        : ArrayItemValue<PropertyValue<TJSONSchema, Property<TJSONSchema>>> extends TJSONSchema
+          ? true
+          : Circular<PropertyValue<TJSONSchema, Property<TJSONSchema>>>
+      : true
   : false;
 
 export type Property<TJSONSchema extends JSONSchema> = keyof TJSONSchema['properties'];

packages/fets/tests/client/fixtures/example-mutual-circular-ref-oas.ts

@@ -0,0 +1,78 @@
+/**
+ * Simplified schema that reproduces the mutual recursion pattern found in large OpenAPI specs
+ * such as Argo Workflows: Template → DAGTemplate → DAGTask → Template (circular).
+ *
+ * Before the fix, using OASModel with such schemas caused TypeScript error TS2615:
+ * "Type of property 'X' circularly references itself in mapped type 'Y'"
+ */
+export default {
+  openapi: '3.0.3',
+  info: {
+    version: '1',
+    title: 'Mutual Circular Ref - OpenAPI 3.0',
+    description: 'This is a sample of mutually recursive schemas (Argo-like pattern)',
+    termsOfService: 'http://swagger.io/terms/',
+  },
+  paths: {
+    '/workflow': {
+      get: {
+        tags: ['workflow'],
+        summary: 'Get workflow',
+        description: '',
+        operationId: 'getWorkflow',
+        responses: {
+          '200': {
+            description: 'successful operation',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Template',
+                },
+              },
+            },
+          },
+          '404': {
+            description: 'Workflow not found',
+          },
+        },
+      },
+    },
+  },
+  components: {
+    schemas: {
+      Template: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+          },
+          dag: {
+            $ref: '#/components/schemas/DAGTemplate',
+          },
+        },
+      },
+      DAGTemplate: {
+        type: 'object',
+        properties: {
+          tasks: {
+            type: 'array',
+            items: {
+              $ref: '#/components/schemas/DAGTask',
+            },
+          },
+        },
+      },
+      DAGTask: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+          },
+          template: {
+            $ref: '#/components/schemas/Template',
+          },
+        },
+      },
+    },
+  },
+} as const;

packages/fets/tests/client/mutual-circular-ref-test.ts

@@ -0,0 +1,48 @@
+import { createClient, OASModel, OASOutput, type NormalizeOAS } from 'fets';
+import type workflowOAS from './fixtures/example-mutual-circular-ref-oas';
+
+// This resolves mutual circular reference (Template → DAGTemplate → DAGTask → Template)
+type NormalizedOAS = NormalizeOAS<typeof workflowOAS>;
+
+// OASModel should work without TS2615 for mutually-recursive schemas
+type TemplateModel = OASModel<NormalizedOAS, 'Template'>;
+const template = {} as TemplateModel;
+
+// Should be able to navigate the mutually-recursive structure
+const taskName = template.dag?.tasks?.[0]?.name;
+type TaskNameType = typeof taskName;
+let taskNameVar: TaskNameType;
+taskNameVar = 'my-task';
+// @ts-expect-error - taskNameVar is a string
+taskNameVar = 42;
+
+console.log(taskNameVar);
+
+// OASOutput should also work
+type TemplateOutput = OASOutput<NormalizedOAS, '/workflow', 'get', '200'>;
+const templateOutput = {} as TemplateOutput;
+const outputTaskName = templateOutput.dag?.tasks?.[0]?.name;
+type OutputTaskNameType = typeof outputTaskName;
+let outputTaskNameVar: OutputTaskNameType;
+outputTaskNameVar = 'another-task';
+// @ts-expect-error - outputTaskNameVar is a string
+outputTaskNameVar = 42;
+
+console.log(outputTaskNameVar);
+
+// createClient should also work without TS2615
+const client = createClient<NormalizedOAS>({});
+const response = await client['/workflow'].get();
+
+if (response.ok) {
+  const body = await response.json();
+  const nestedTaskName = body.dag?.tasks?.[0]?.name;
+  type NestedTaskNameType = typeof nestedTaskName;
+  let nestedTaskNameVar: NestedTaskNameType;
+  nestedTaskNameVar = 'nested-task';
+  // @ts-expect-error - nestedTaskNameVar is a string
+  nestedTaskNameVar = 42;
+  console.log(nestedTaskNameVar);
+} else {
+  console.log(response.status);
+}