fix(typescript): guard against null/undefined in file upload core utility

generators/typescript/sdk/changes/unreleased/fix-file-upload-null-crash.yml

@@ -0,0 +1,6 @@
+- summary: |
+    Fix `TypeError: Cannot use 'in' operator to search for 'path' in undefined`
+    crash when `null` or `undefined` is passed to a file upload parameter at
+    runtime. The error is now a clear `TypeError` describing the expected types
+    instead of a cryptic `in` operator failure.
+  type: fix

generators/typescript/utils/core-utilities/src/core/file/file.ts

@@ -37,6 +37,11 @@ async function getFileWithMetadata(
     file: Uploadable,
     { noSniffFileSize }: { noSniffFileSize?: boolean } = {},
 ): Promise<Uploadable.WithMetadata> {
+    if (file == null) {
+        throw new Error(
+            `Expected file to be a Blob, Buffer, ReadableStream, or an object with a "path" or "data" property, but received ${file === null ? "null" : "undefined"}.`,
+        );
+    }
     if (isFileLike(file)) {
         return getFileWithMetadata(
             {

generators/typescript/utils/core-utilities/src/core/form-data-utils/FormDataWrapper.template.ts

@@ -79,6 +79,11 @@ export class Node18FormData implements CrossPlatformFormData {
     }
 
     public async appendFile(key: string, value: Uploadable): Promise<void> {
+        if (value == null) {
+            throw new Error(
+                `File upload for "${key}" received ${value === null ? "null" : "undefined"}. The generated code should not call appendFile with null/undefined — check that optional file fields are guarded before this call.`
+            );
+        }
         const { data, filename } = await toMultipartDataPart(value);
 
         if (data instanceof Blob) {
@@ -140,6 +145,11 @@ export class Node16FormData implements CrossPlatformFormData {
     }
 
     public async appendFile(key: string, value: Uploadable): Promise<void> {
+        if (value == null) {
+            throw new Error(
+                `File upload for "${key}" received ${value === null ? "null" : "undefined"}. The generated code should not call appendFile with null/undefined — check that optional file fields are guarded before this call.`
+            );
+        }
         const { data, filename } = await toMultipartDataPart(value);
 
         let bufferedValue;
@@ -181,6 +191,11 @@ export class WebFormData implements CrossPlatformFormData {
     }
 
     public async appendFile(key: string, value: Uploadable): Promise<void> {
+        if (value == null) {
+            throw new Error(
+                `File upload for "${key}" received ${value === null ? "null" : "undefined"}. The generated code should not call appendFile with null/undefined — check that optional file fields are guarded before this call.`
+            );
+        }
         const { data, filename, contentType } = await toMultipartDataPart(value);
 
         if (data instanceof Blob) {
@@ -221,6 +236,11 @@ export class FormDataWrapper {
     }
 
     public async appendFile(key: string, value: Uploadable): Promise<void> {
+        if (value == null) {
+            throw new Error(
+                `File upload for "${key}" received ${value === null ? "null" : "undefined"}. The generated code should not call appendFile with null/undefined — check that optional file fields are guarded before this call.`
+            );
+        }
         const { data, filename, contentType } = await toMultipartDataPart(value);
         const blob = await convertToBlob(data, contentType);
         if (filename) {

generators/typescript/utils/core-utilities/tests/unit/file/file.test.ts

@@ -430,6 +430,22 @@ describe("toBinaryUploadRequest", () => {
         });
     });
 
+    describe("null and undefined input", () => {
+        it("should throw Error for undefined in binary upload", async () => {
+            await expect(toBinaryUploadRequest(undefined as unknown as Uploadable)).rejects.toThrow(Error);
+            await expect(toBinaryUploadRequest(undefined as unknown as Uploadable)).rejects.toThrow(
+                /but received undefined/,
+            );
+        });
+
+        it("should throw Error for null in binary upload", async () => {
+            await expect(toBinaryUploadRequest(null as unknown as Uploadable)).rejects.toThrow(Error);
+            await expect(toBinaryUploadRequest(null as unknown as Uploadable)).rejects.toThrow(
+                /but received null/,
+            );
+        });
+    });
+
     describe("Edge cases", () => {
         it("should handle empty headers when no metadata is available", async () => {
             const buffer = Buffer.from("");