Updated baw-api create method

src/app/components/import-annotations/details/details.component.ts

@@ -245,30 +245,6 @@ class AnnotationsDetailsComponent extends PageComponent implements OnInit {
           );
         }
       });
-
-    // return new Promise<void>((resolve, reject) => {
-    //   this.eventImportsApi
-    //     .importFile(audioEventImportModel)
-    //     .pipe(takeUntil(this.unsubscribe))
-    //     .subscribe({
-    //       complete: () => {
-    //         model.uploaded = true;
-    //         // resolving the promise allows the next file to be uploaded
-    //         resolve();
-    //       },
-    //       error: (error: BawApiError) => {
-    //         // some of the default error messages are ambiguous on this page
-    //         // e.g. "you do not have access to this page" means that the user doesn't have access to the audio recording
-    //         if (error.status === FORBIDDEN) {
-    //           model.errors.push(
-    //             "You do not have access to all the audio recordings or tags in your files."
-    //           );
-    //         }
-
-    //         reject(error);
-    //       },
-    //     });
-    // });
   }
 
   private performDryRun(model: ImportGroup) {

src/app/services/baw-api/baw-api.service.ts

@@ -18,8 +18,8 @@ import { withCacheLogging } from "@services/cache/cache-logging.service";
 import { CacheSettings, CACHE_SETTINGS } from "@services/cache/cache-settings";
 import { API_ROOT } from "@services/config/config.tokens";
 import { ToastrService } from "ngx-toastr";
-import { Observable, iif, of, throwError } from "rxjs";
-import { catchError, concatMap, map, switchMap, tap } from "rxjs/operators";
+import { Observable, identity, iif, of, throwError } from "rxjs";
+import { catchError, concatMap, map, mergeMap, switchMap, tap } from "rxjs/operators";
 import { IS_SERVER_PLATFORM } from "src/app/app.helper";
 import { BawSessionService } from "./baw-session.service";
 
@@ -264,14 +264,24 @@ export class BawApiService<
       ? { [model.kind]: jsonData ?? model }
       : jsonData ?? model;
 
+    // as part of the multi part request, if there is only a JSON body, we want to return the output of the JSON POST request
+    // if there is only a formData body, we want to return the output of the formData PUT request
+    // if there is both a JSON body and formData, we want to return the output of the last request sent (formData PUT request)
+    // we default to returning null if there is no JSON or formData body
     return of(null).pipe(
       concatMap(
         model.hasJsonOnlyAttributes({ create: true })
           ? () => this.httpPost(createPath, body).pipe()
-          : (data) => of(data)
+          : identity
       ),
+      // we create a class from the POST response so that we can construct an update route for the formData PUT request
+      // using the updatePath callback. We do this before the concatMap below because the updatePath callback is dependent
+      // on the instantiated class from the POST response object
       map(this.handleSingleResponse(classBuilder)),
+      // using concatMap here ensures that the httpPost request completes before the httpPut request is made
       concatMap((data) =>
+        // we use an if statement here because we want to create a new observable and apply a map function to it
+        // using ternary logic here (similar to the update function) would result in poor readability and a lot of nesting
         iif(
           () => model.hasFormDataOnlyAttributes({ create: true }),
           this.httpPut(updatePath(data), formData, multiPartApiHeaders).pipe(
@@ -280,6 +290,8 @@ export class BawApiService<
           of(data)
         )
       ),
+      // there is no map function here, because the handleSingleResponse method is invoked on the POST and PUT requests
+      // individually. Moving the handleSingleResponse mapping here would result in the response object being instantiated twice
       catchError((err) => this.handleError(err, opts?.disableNotification))
     );
   }
@@ -304,16 +316,20 @@ export class BawApiService<
       ? { [model.kind]: jsonData ?? model }
       : jsonData ?? model;
 
+    // as part of the multi part request, if there is only a JSON body, we want to return the output of the JSON PATCH request
+    // if there is only a formData body, we want to return the output of the formData PUT request
+    // if there is both a JSON body and formData, we want to return the output of the last request sent (formData PUT request)
+    // we default to returning null if there is no JSON or formData body
     return of(null).pipe(
       concatMap(
-        // we use (data) => of(data) here instead of the identity function because the identify function
-        // returns a value, and not an observable. Because we use concatMap below, we need the existing
-        // value to be emitted as an observable instead. Therefore, we create a static observable using of()
         model.hasJsonOnlyAttributes({ update: true })
           ? () => this.httpPatch(path, body)
-          : (data) => of(data)
+          : identity
       ),
       concatMap(
+        // we use (data) => of(data) here instead of the identity function because the identify function
+        // returns a value, and not an observable. Because we use concatMap below, we need the existing
+        // value to be emitted as an observable instead. Therefore, we create a static observable using of()
         model.hasFormDataOnlyAttributes({ update: true })
           ? () => this.httpPut(path, formData, multiPartApiHeaders)
           : (data) => of(data)