fix(UploadController): tests typedoc and error types

Updates the test cases to test on the expanded upload result types.
Additionally typedoc documentation was updated to document the error and
the controller more accurately.

Author: bitbeckers

src/controllers/UploadController.ts

@@ -14,6 +14,7 @@ import {
   NoFilesUploadedError,
   PartialUploadError,
   UploadFailedError,
+  SingleUploadFailedError,
 } from "../lib/uploads/errors.js";
 
 // Type definitions and guards at module scope
@@ -80,31 +81,37 @@ export class UploadController extends Controller {
    * });
    * ```
    *
-   * Success Response (201):
+   * Full Success Response (201):
    * ```json
    * {
    *   "success": true,
    *   "message": "Upload successful",
+   *   "uploadStatus": "all",
    *   "data": {
    *     "results": [
-   *       { "cid": "Qm...", "fileName": "example.txt" }
+   *       { "cid": "Qm...", "fileName": "example1.txt" },
+   *       { "cid": "Qm...", "fileName": "example2.txt" }
    *     ],
    *     "failed": []
    *   }
    * }
    * ```
    *
-   * Partial Success Response (207):
+   * Multi-Status Response (207):
    * ```json
    * {
    *   "success": false,
    *   "message": "Some uploads failed",
+   *   "uploadStatus": "some",
    *   "data": {
    *     "results": [
    *       { "cid": "Qm...", "fileName": "success.txt" }
    *     ],
    *     "failed": [
-   *       { "fileName": "failed.txt", "error": "Upload failed" }
+   *       {
+   *         "fileName": "failed.txt",
+   *         "error": "File exceeds size limit"
+   *       }
    *     ]
    *   }
    * }
@@ -115,6 +122,7 @@ export class UploadController extends Controller {
    * {
    *   "success": false,
    *   "message": "No files uploaded",
+   *   "uploadStatus": "none",
    *   "errors": {
    *     "upload": "No files uploaded"
    *   }
@@ -164,8 +172,7 @@ export class UploadController extends Controller {
               fileName: file.originalname,
             };
           } catch (error) {
-            throw new UploadFailedError(
-              `Failed to upload file`,
+            throw new SingleUploadFailedError(
               file.originalname,
               (error as Error).message,
             );
@@ -178,7 +185,7 @@ export class UploadController extends Controller {
         .map((result) => result.value);
 
       const failed = uploadResults.filter(isFailedUpload).map((result) => {
-        const error = result.reason as UploadFailedError;
+        const error = result.reason as SingleUploadFailedError;
         return {
           fileName: error.fileName,
           error: error.errorDetail,
@@ -188,18 +195,14 @@ export class UploadController extends Controller {
       if (failed.length > 0) {
         const data = {
           results: successful,
-          failed: failed.map((f) => ({
-            fileName: f.fileName,
-            error: f.error,
-          })),
+          failed: failed,
         };
 
         if (failed.length === uploadResults.length) {
-          throw new UploadFailedError(
-            "All uploads failed",
-            "multiple files",
-            "None of the files could be uploaded",
-          );
+          throw new UploadFailedError("All uploads failed", {
+            results: [],
+            failed: failed, // Preserve all failed upload details
+          });
         }
 
         throw new PartialUploadError("Some uploads failed", data);
@@ -209,6 +212,7 @@ export class UploadController extends Controller {
       return {
         success: true,
         message: "Upload successful",
+        uploadStatus: "all",
         data: {
           results: successful,
           failed: [],
@@ -220,16 +224,51 @@ export class UploadController extends Controller {
         return {
           success: false,
           message: error.message,
-          ...(error.errors && { errors: error.errors }),
-          ...(error instanceof PartialUploadError && { data: error.results }),
+          uploadStatus: error instanceof PartialUploadError ? "some" : "none",
+          errors: error.errors,
+          data:
+            error instanceof PartialUploadError ||
+            error instanceof UploadFailedError
+              ? error.results
+              : {
+                  results: [],
+                  failed: [
+                    {
+                      fileName:
+                        error instanceof SingleUploadFailedError
+                          ? error.fileName
+                          : "unknown",
+                      error:
+                        error instanceof SingleUploadFailedError
+                          ? error.errorDetail
+                          : error.message,
+                    },
+                  ],
+                },
         };
       }
 
-      throw new UploadFailedError(
-        "Upload failed",
-        "unknown file",
-        (error as Error).message,
+      const uploadError = new UploadFailedError(
+        `Upload failed: ${(error as Error).message}`,
+        {
+          results: [],
+          failed: [
+            {
+              fileName: "unknown",
+              error: (error as Error).message,
+            },
+          ],
+        },
       );
+
+      this.setStatus(uploadError.code);
+      return {
+        success: false,
+        message: uploadError.message,
+        uploadStatus: "none",
+        errors: uploadError.errors,
+        data: uploadError.results,
+      };
     }
   }
 }

src/lib/uploads/errors.ts

@@ -1,16 +1,61 @@
 import { UploadResponse } from "../../types/api.js";
 
+/**
+ * Base class for file upload errors
+ * @class FileUploadError
+ * @extends Error
+ *
+ * @example
+ * ```typescript
+ * throw new FileUploadError(500, "Upload failed");
+ * ```
+ *
+ * Response:
+ * ```json
+ * {
+ *   "success": false,
+ *   "message": "Upload failed",
+ *   "uploadStatus": "none"
+ * }
+ * ```
+ */
 export class FileUploadError extends Error {
   code: number;
   public errors: UploadResponse["errors"];
 
+  /**
+   * @param code - HTTP status code
+   * @param message - Error message
+   */
   constructor(code: number, message: string) {
     super(message);
     this.name = "FileUploadError";
     this.code = code;
   }
 }
 
+/**
+ * Error thrown when no files are provided in the upload request
+ * @class NoFilesUploadedError
+ * @extends FileUploadError
+ *
+ * @example
+ * ```typescript
+ * throw new NoFilesUploadedError();
+ * ```
+ *
+ * Response:
+ * ```json
+ * {
+ *   "success": false,
+ *   "message": "No files uploaded",
+ *   "uploadStatus": "none",
+ *   "errors": {
+ *     "upload": "No files uploaded"
+ *   }
+ * }
+ * ```
+ */
 export class NoFilesUploadedError extends FileUploadError {
   constructor() {
     super(400, "No files uploaded");
@@ -19,6 +64,36 @@ export class NoFilesUploadedError extends FileUploadError {
   }
 }
 
+/**
+ * Error thrown when some files uploaded successfully but others failed
+ * @class PartialUploadError
+ * @extends FileUploadError
+ *
+ * @example
+ * ```typescript
+ * throw new PartialUploadError("Some uploads failed", {
+ *   results: [{ cid: "Qm...", fileName: "success.txt" }],
+ *   failed: [{ fileName: "failed.txt", error: "Upload failed" }]
+ * });
+ * ```
+ *
+ * Response:
+ * ```json
+ * {
+ *   "success": false,
+ *   "message": "Some uploads failed",
+ *   "uploadStatus": "some",
+ *   "data": {
+ *     "results": [
+ *       { "cid": "Qm...", "fileName": "success.txt" }
+ *     ],
+ *     "failed": [
+ *       { "fileName": "failed.txt", "error": "Upload failed" }
+ *     ]
+ *   }
+ * }
+ * ```
+ */
 export class PartialUploadError extends FileUploadError {
   constructor(
     message: string,
@@ -29,11 +104,80 @@ export class PartialUploadError extends FileUploadError {
   }
 }
 
-export class UploadFailedError extends FileUploadError {
+/**
+ * Error thrown when a single file upload fails
+ * @class SingleUploadFailedError
+ * @extends FileUploadError
+ *
+ * @example
+ * ```typescript
+ * throw new SingleUploadFailedError("example.txt", "File too large");
+ * ```
+ *
+ * Response:
+ * ```json
+ * {
+ *   "success": false,
+ *   "message": "Failed to upload example.txt",
+ *   "uploadStatus": "none",
+ *   "data": {
+ *     "results": [],
+ *     "failed": [
+ *       { "fileName": "example.txt", "error": "File too large" }
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+export class SingleUploadFailedError extends FileUploadError {
   constructor(
-    message: string,
     public fileName: string,
     public errorDetail: string,
+  ) {
+    super(422, `Failed to upload ${fileName}`);
+    this.name = "SingleUploadFailedError";
+  }
+}
+
+/**
+ * Error thrown when the upload service is unavailable or all uploads fail due to service issues
+ * @class UploadFailedError
+ * @extends FileUploadError
+ *
+ * @example
+ * ```typescript
+ * throw new UploadFailedError("Upload service unavailable", {
+ *   results: [],
+ *   failed: [
+ *     { fileName: "file1.txt", error: "IPFS service unavailable" },
+ *     { fileName: "file2.txt", error: "Storage service not responding" }
+ *   ]
+ * });
+ * ```
+ *
+ * Response:
+ * ```json
+ * {
+ *   "success": false,
+ *   "message": "Upload service unavailable",
+ *   "uploadStatus": "none",
+ *   "errors": {
+ *     "upload": "Upload service unavailable"
+ *   },
+ *   "data": {
+ *     "results": [],
+ *     "failed": [
+ *       { "fileName": "file1.txt", "error": "IPFS service unavailable" },
+ *       { "fileName": "file2.txt", "error": "Storage service not responding" }
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+export class UploadFailedError extends FileUploadError {
+  constructor(
+    message: string,
+    public results: UploadResponse["data"],
   ) {
     super(500, message);
     this.name = "UploadFailedError";

src/types/api.ts

@@ -26,7 +26,12 @@ export interface ValidationResponse extends BaseResponse {
 // Storage-related interfaces
 export interface StorageResponse extends DataResponse<{ cid: string }> {}
 
-export interface UploadResponse extends BaseResponse {
+export type UploadStatus = "all" | "some" | "none";
+
+export interface UploadResponse {
+  success: boolean;
+  message: string;
+  uploadStatus: UploadStatus;
   data?: {
     results: Array<{
       cid: string;
@@ -37,6 +42,7 @@ export interface UploadResponse extends BaseResponse {
       error: string;
     }>;
   };
+  errors?: Record<string, string>;
 }
 
 // Data-related interfaces