@proofkit/fmodata 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/client/batch-builder.ts

@@ -0,0 +1,334 @@
+import type {
+  ExecutableBuilder,
+  ExecutionContext,
+  Result,
+  ExecuteOptions,
+  BatchResult,
+  BatchItemResult,
+  ExecuteMethodOptions,
+} from "../types";
+import { BatchTruncatedError } from "../errors";
+import { type FFetchOptions } from "@fetchkit/ffetch";
+import {
+  formatBatchRequestFromNative,
+  parseBatchResponse,
+  type ParsedBatchResponse,
+} from "./batch-request";
+
+/**
+ * Helper type to extract result types from a tuple of ExecutableBuilders.
+ * Uses a mapped type which TypeScript 4.1+ can handle for tuples.
+ */
+type ExtractTupleTypes<T extends readonly ExecutableBuilder<any>[]> = {
+  [K in keyof T]: T[K] extends ExecutableBuilder<infer U> ? U : never;
+};
+
+/**
+ * Converts a ParsedBatchResponse to a native Response object
+ * @param parsed - The parsed batch response
+ * @returns A native Response object
+ */
+function parsedToResponse(parsed: ParsedBatchResponse): Response {
+  const headers = new Headers(parsed.headers);
+
+  // Handle null body
+  if (parsed.body === null || parsed.body === undefined) {
+    return new Response(null, {
+      status: parsed.status,
+      statusText: parsed.statusText,
+      headers,
+    });
+  }
+
+  // Convert body to string if it's not already
+  const bodyString =
+    typeof parsed.body === "string" ? parsed.body : JSON.stringify(parsed.body);
+
+  // Handle 204 No Content status - it cannot have a body per HTTP spec
+  // If FileMaker returns 204 with a body, treat it as 200
+  let status = parsed.status;
+  if (status === 204 && bodyString && bodyString.trim() !== "") {
+    status = 200;
+  }
+
+  return new Response(status === 204 ? null : bodyString, {
+    status: status,
+    statusText: parsed.statusText,
+    headers,
+  });
+}
+
+/**
+ * Builder for batch operations that allows multiple queries to be executed together
+ * in a single transactional request.
+ *
+ * Note: BatchBuilder does not implement ExecutableBuilder because execute() returns
+ * BatchResult instead of Result, which is a different return type structure.
+ */
+export class BatchBuilder<Builders extends readonly ExecutableBuilder<any>[]> {
+  private builders: ExecutableBuilder<any>[];
+  private readonly originalBuilders: Builders;
+
+  constructor(
+    builders: Builders,
+    private readonly databaseName: string,
+    private readonly context: ExecutionContext,
+  ) {
+    // Convert readonly tuple to mutable array for dynamic additions
+    this.builders = [...builders];
+    // Store original tuple for type preservation
+    this.originalBuilders = builders;
+  }
+
+  /**
+   * Add a request to the batch dynamically.
+   * This allows building up batch operations programmatically.
+   *
+   * @param builder - An executable builder to add to the batch
+   * @returns This BatchBuilder for method chaining
+   * @example
+   * ```ts
+   * const batch = db.batch([]);
+   * batch.addRequest(db.from('contacts').list());
+   * batch.addRequest(db.from('users').list());
+   * const result = await batch.execute();
+   * ```
+   */
+  addRequest<T>(builder: ExecutableBuilder<T>): this {
+    this.builders.push(builder);
+    return this;
+  }
+
+  /**
+   * Get the request configuration for this batch operation.
+   * This is used internally by the execution system.
+   */
+  getRequestConfig(): { method: string; url: string; body?: any } {
+    // Note: This method is kept for compatibility but batch operations
+    // should use execute() directly which handles the full Request/Response flow
+    return {
+      method: "POST",
+      url: `/${this.databaseName}/$batch`,
+      body: undefined, // Body is constructed in execute()
+    };
+  }
+
+  toRequest(baseUrl: string, options?: ExecuteOptions): Request {
+    // Batch operations are not designed to be nested, but we provide
+    // a basic implementation for interface compliance
+    const fullUrl = `${baseUrl}/${this.databaseName}/$batch`;
+    return new Request(fullUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "multipart/mixed",
+        "OData-Version": "4.0",
+      },
+    });
+  }
+
+  async processResponse(
+    response: Response,
+    options?: ExecuteOptions,
+  ): Promise<Result<any>> {
+    // This should not typically be called for batch operations
+    // as they handle their own response processing
+    return {
+      data: undefined,
+      error: {
+        name: "NotImplementedError",
+        message: "Batch operations handle response processing internally",
+        timestamp: new Date(),
+      } as any,
+    };
+  }
+
+  /**
+   * Execute the batch operation.
+   *
+   * @param options - Optional fetch options and batch-specific options (includes beforeRequest hook)
+   * @returns A BatchResult containing individual results for each operation
+   */
+  async execute<EO extends ExecuteOptions>(
+    options?: ExecuteMethodOptions<EO>,
+  ): Promise<BatchResult<ExtractTupleTypes<Builders>>> {
+    const baseUrl = this.context._getBaseUrl?.();
+    if (!baseUrl) {
+      // Return BatchResult with all operations marked as failed
+      const errorCount = this.builders.length;
+      const results: BatchItemResult<any>[] = this.builders.map((_, i) => ({
+        data: undefined,
+        error: {
+          name: "ConfigurationError",
+          message:
+            "Base URL not available - execution context must implement _getBaseUrl()",
+          timestamp: new Date(),
+        } as any,
+        status: 0,
+      }));
+
+      return {
+        results: results as any,
+        successCount: 0,
+        errorCount,
+        truncated: false,
+        firstErrorIndex: 0,
+      };
+    }
+
+    try {
+      // Convert builders to native Request objects
+      const requests: Request[] = this.builders.map((builder) =>
+        builder.toRequest(baseUrl, options),
+      );
+
+      // Format batch request (automatically groups mutations into changesets)
+      const { body, boundary } = await formatBatchRequestFromNative(
+        requests,
+        baseUrl,
+      );
+
+      // Execute the batch request
+      const response = await this.context._makeRequest<string>(
+        `/${this.databaseName}/$batch`,
+        {
+          ...options,
+          method: "POST",
+          headers: {
+            ...options?.headers,
+            "Content-Type": `multipart/mixed; boundary=${boundary}`,
+            "OData-Version": "4.0",
+          },
+          body,
+        },
+      );
+
+      if (response.error) {
+        // Return BatchResult with all operations marked as failed
+        const errorCount = this.builders.length;
+        const results: BatchItemResult<any>[] = this.builders.map((_, i) => ({
+          data: undefined,
+          error: response.error,
+          status: 0,
+        }));
+
+        return {
+          results: results as any,
+          successCount: 0,
+          errorCount,
+          truncated: false,
+          firstErrorIndex: 0,
+        };
+      }
+
+      // Extract the actual boundary from the response
+      // FileMaker uses its own boundary, not the one we sent
+      const firstLine =
+        response.data.split("\r\n")[0] || response.data.split("\n")[0] || "";
+      const actualBoundary = firstLine.startsWith("--")
+        ? firstLine.substring(2)
+        : boundary;
+
+      // Parse the multipart response
+      const contentTypeHeader = `multipart/mixed; boundary=${actualBoundary}`;
+      const parsedResponses = parseBatchResponse(
+        response.data,
+        contentTypeHeader,
+      );
+
+      // Process each response using the corresponding builder
+      // Build BatchResult with per-item results
+      type ResultTuple = ExtractTupleTypes<Builders>;
+
+      const results: BatchItemResult<any>[] = [];
+      let successCount = 0;
+      let errorCount = 0;
+      let firstErrorIndex: number | null = null;
+      const truncated = parsedResponses.length < this.builders.length;
+
+      // Process builders sequentially to preserve tuple order
+      for (let i = 0; i < this.builders.length; i++) {
+        const builder = this.builders[i];
+        const parsed = parsedResponses[i];
+
+        if (!parsed) {
+          // Truncated - operation never executed
+          const failedAtIndex = firstErrorIndex ?? i;
+          results.push({
+            data: undefined,
+            error: new BatchTruncatedError(i, failedAtIndex),
+            status: 0,
+          });
+          errorCount++;
+          continue;
+        }
+
+        if (!builder) {
+          // Should not happen, but handle gracefully
+          results.push({
+            data: undefined,
+            error: {
+              name: "BatchError",
+              message: `Builder at index ${i} is undefined`,
+              timestamp: new Date(),
+            } as any,
+            status: parsed.status,
+          });
+          errorCount++;
+          if (firstErrorIndex === null) firstErrorIndex = i;
+          continue;
+        }
+
+        // Convert parsed response to native Response
+        const nativeResponse = parsedToResponse(parsed);
+
+        // Let the builder process its own response
+        const result = await builder.processResponse(nativeResponse, options);
+
+        if (result.error) {
+          results.push({
+            data: undefined,
+            error: result.error,
+            status: parsed.status,
+          });
+          errorCount++;
+          if (firstErrorIndex === null) firstErrorIndex = i;
+        } else {
+          results.push({
+            data: result.data,
+            error: undefined,
+            status: parsed.status,
+          });
+          successCount++;
+        }
+      }
+
+      return {
+        results: results as any,
+        successCount,
+        errorCount,
+        truncated,
+        firstErrorIndex,
+      };
+    } catch (err) {
+      // On exception, return a BatchResult with all operations marked as failed
+      const errorCount = this.builders.length;
+      const results: BatchItemResult<any>[] = this.builders.map((_, i) => ({
+        data: undefined,
+        error: {
+          name: "BatchError",
+          message: err instanceof Error ? err.message : "Unknown error",
+          timestamp: new Date(),
+        } as any,
+        status: 0,
+      }));
+
+      return {
+        results: results as any,
+        successCount: 0,
+        errorCount,
+        truncated: false,
+        firstErrorIndex: 0,
+      };
+    }
+  }
+}