fix(open-api#ts-client): fail loud on non-encodable urlencoded array bodies (#938)

A top-level array/tuple application/x-www-form-urlencoded body has no
property names to key on, so $urlEncodedForm emitted index-keyed pairs
(0=a&1=b) that no form parser can decode. Raise a generation-time error
directing users to an object or primitive schema, matching the existing
fail-loud guards for ambiguous unions and non-JSON content params.

The guard tracks the client's actual wire media type (JSON-preferred), so
an array body offering both JSON and urlencoded is unaffected. Dictionary
(additionalProperties) and object bodies remain form-encoded; primitives
are sent verbatim (#937).

Co-authored-by: test <test@example.com>

Author: nx-plugin-for-aws

packages/nx-plugin/src/open-api/ts-client/generator.content-type.spec.ts

@@ -508,4 +508,161 @@ describe('openApiTsClientGenerator - content type header', () => {
       }),
     );
   });
+
+  it('should form-encode a urlencoded dictionary (additionalProperties) body', async () => {
+    const spec: Spec = {
+      info: { title, version: '1.0.0' },
+      openapi: '3.0.0',
+      paths: {
+        '/urlencoded-dict': {
+          post: {
+            requestBody: {
+              required: true,
+              content: {
+                'application/x-www-form-urlencoded': {
+                  schema: {
+                    type: 'object',
+                    additionalProperties: { type: 'string' },
+                  },
+                },
+              },
+            },
+            responses: {
+              '200': {
+                content: {
+                  'application/json': {
+                    schema: { type: 'array', items: { type: 'string' } },
+                  },
+                },
+                description: 'Success',
+              },
+            },
+          },
+        },
+      },
+    };
+
+    tree.write('openapi.json', JSON.stringify(spec));
+
+    await openApiTsClientGenerator(tree, {
+      openApiSpecPath: 'openapi.json',
+      outputPath: 'src/generated',
+    });
+
+    validateTypeScript([
+      'src/generated/client.gen.ts',
+      'src/generated/types.gen.ts',
+    ]);
+
+    const client = tree.read('src/generated/client.gen.ts', 'utf-8');
+    const mockFetch = vi.fn();
+    mockFetch.mockResolvedValue({
+      status: 200,
+      json: vi.fn().mockResolvedValue(['ok']),
+    });
+
+    // Each dictionary entry becomes a form field.
+    await callGeneratedClient(client, mockFetch, 'postUrlencodedDict', {
+      first: 'a b',
+      second: 'c&d',
+    });
+    expect(mockFetch).toHaveBeenCalledWith(
+      `${baseUrl}/urlencoded-dict`,
+      expect.objectContaining({
+        method: 'POST',
+        body: 'first=a+b&second=c%26d',
+        headers: [['Content-Type', 'application/x-www-form-urlencoded']],
+      }),
+    );
+  });
+
+  it('should throw for a urlencoded body whose schema is an array', async () => {
+    // A top-level array has no property names to key on, so it has no defined
+    // form encoding — fail fast rather than emit index-keyed pairs (0=a&1=b)
+    // that no form parser can decode.
+    const spec: Spec = {
+      info: { title, version: '1.0.0' },
+      openapi: '3.0.0',
+      paths: {
+        '/urlencoded-array': {
+          post: {
+            requestBody: {
+              required: true,
+              content: {
+                'application/x-www-form-urlencoded': {
+                  schema: { type: 'array', items: { type: 'string' } },
+                },
+              },
+            },
+            responses: { '204': { description: 'No content' } },
+          },
+        },
+      },
+    };
+
+    tree.write('openapi.json', JSON.stringify(spec));
+
+    await expect(
+      openApiTsClientGenerator(tree, {
+        openApiSpecPath: 'openapi.json',
+        outputPath: 'src/generated',
+      }),
+    ).rejects.toThrow(/x-www-form-urlencoded.*array.*no defined form encoding/);
+  });
+
+  it('should not throw for an array body offering both JSON and urlencoded', async () => {
+    // JSON is the preferred wire type, so the array body is sent as JSON — the
+    // urlencoded offering is never used and must not trip the form-encoding guard.
+    const spec: Spec = {
+      info: { title, version: '1.0.0' },
+      openapi: '3.0.0',
+      paths: {
+        '/array-json-or-form': {
+          post: {
+            requestBody: {
+              required: true,
+              content: {
+                'application/json': {
+                  schema: { type: 'array', items: { type: 'string' } },
+                },
+                'application/x-www-form-urlencoded': {
+                  schema: { type: 'array', items: { type: 'string' } },
+                },
+              },
+            },
+            responses: { '204': { description: 'No content' } },
+          },
+        },
+      },
+    };
+
+    tree.write('openapi.json', JSON.stringify(spec));
+
+    await openApiTsClientGenerator(tree, {
+      openApiSpecPath: 'openapi.json',
+      outputPath: 'src/generated',
+    });
+
+    validateTypeScript([
+      'src/generated/client.gen.ts',
+      'src/generated/types.gen.ts',
+    ]);
+
+    const client = tree.read('src/generated/client.gen.ts', 'utf-8');
+    const mockFetch = vi.fn();
+    mockFetch.mockResolvedValue({ status: 204 });
+
+    await callGeneratedClient(client, mockFetch, 'postArrayJsonOrForm', [
+      'a',
+      'b',
+    ]);
+    expect(mockFetch).toHaveBeenCalledWith(
+      `${baseUrl}/array-json-or-form`,
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify(['a', 'b']),
+        headers: [['Content-Type', 'application/json']],
+      }),
+    );
+  });
 });

packages/nx-plugin/src/open-api/utils/codegen-data.ts

@@ -92,6 +92,10 @@ export const buildOpenApiCodeGenData = (inSpec: Spec): CodeGenData => {
     assertNoConflictingUnionMemberMarshalling(model);
   }
 
+  for (const op of allOperations) {
+    assertEncodableUrlEncodedBody(op);
+  }
+
   data.models = orderBy(data.models, (d) => d.name);
   // Default service first, then by name.
   data.services = orderBy(data.services, (s) =>
@@ -572,6 +576,35 @@ const assertNoConflictingUnionMemberMarshalling = (model: Model): void => {
   }
 };
 
+/**
+ * An `application/x-www-form-urlencoded` body is form-encoded as `key=value`
+ * pairs, so the wire form is only defined for a schema with named properties
+ * (an object) or a primitive sent verbatim. A top-level array or tuple has no
+ * property names to key on — encoding it would emit index keys (`0=a&1=b`) that
+ * no form parser can decode — so fail fast rather than generate a client that
+ * is silently wrong on the wire.
+ */
+const assertEncodableUrlEncodedBody = (op: Operation): void => {
+  const body = op.parametersBody;
+  if (!body?.mediaTypes) return;
+  const mediaTypes = Array.isArray(body.mediaTypes)
+    ? body.mediaTypes
+    : [body.mediaTypes];
+  // Match the wire media type the client actually sends: JSON is preferred, so
+  // an array body offering both JSON and urlencoded is sent as JSON and is fine.
+  const chosenMediaType =
+    mediaTypes.find(
+      (mt) => mt === 'application/json' || mt.endsWith('+json'),
+    ) ?? mediaTypes[0];
+  if (chosenMediaType !== 'application/x-www-form-urlencoded') return;
+  if (body.isPrimitive) return;
+  if (body.export === 'array' || body.export === 'tuple') {
+    throw new Error(
+      `Operation ${op.method} ${op.path} has an application/x-www-form-urlencoded request body whose schema is a ${body.export}, which has no defined form encoding. Use an object schema (its properties become the form fields) or a primitive schema (sent verbatim) in your OpenAPI specification.`,
+    );
+  }
+};
+
 /**
  * Group operations by their (camelCased) tags, collecting any untagged
  * operations separately.