@proofkit/fmodata 0.1.0-alpha.6 → 0.1.0-alpha.7

package/src/client/batch-request.ts

@@ -0,0 +1,485 @@
+/**
+ * Batch Request Utilities
+ *
+ * Utilities for formatting and parsing OData batch requests using multipart/mixed format.
+ * OData batch requests allow bundling multiple operations into a single HTTP request,
+ * with support for transactional changesets.
+ */
+
+export interface RequestConfig {
+  method: string;
+  url: string;
+  body?: string;
+  headers?: Record<string, string>;
+}
+
+export interface ParsedBatchResponse {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  body: any;
+}
+
+/**
+ * Generates a random boundary string for multipart requests
+ * @param prefix - Prefix for the boundary (e.g., "batch_" or "changeset_")
+ * @returns A boundary string with the prefix and 32 random hex characters
+ */
+export function generateBoundary(prefix: string = "batch_"): string {
+  const randomHex = Array.from({ length: 32 }, () =>
+    Math.floor(Math.random() * 16).toString(16),
+  ).join("");
+  return `${prefix}${randomHex}`;
+}
+
+/**
+ * Converts a native Request object to RequestConfig
+ * @param request - Native Request object
+ * @returns RequestConfig object
+ */
+async function requestToConfig(request: Request): Promise<RequestConfig> {
+  const headers: Record<string, string> = {};
+  request.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+
+  let body: string | undefined;
+  if (request.body) {
+    // Clone the request to read the body without consuming it
+    const clonedRequest = request.clone();
+    body = await clonedRequest.text();
+  }
+
+  return {
+    method: request.method,
+    url: request.url,
+    body,
+    headers,
+  };
+}
+
+/**
+ * Formats a single HTTP request for inclusion in a batch
+ * @param request - The request configuration
+ * @param baseUrl - The base URL to prepend to relative URLs
+ * @returns Formatted request string with CRLF line endings
+ *
+ * Formatting rules for FileMaker OData:
+ * - GET (no body): request line → blank → blank
+ * - POST/PATCH (with body): request line → headers → blank → body (NO blank after!)
+ */
+function formatSubRequest(request: RequestConfig, baseUrl: string): string {
+  const lines: string[] = [];
+
+  // Add required headers for sub-request
+  lines.push("Content-Type: application/http");
+  lines.push("Content-Transfer-Encoding: binary");
+  lines.push(""); // Empty line after multipart headers
+
+  // Construct full URL (convert relative to absolute)
+  const fullUrl = request.url.startsWith("http")
+    ? request.url
+    : `${baseUrl}${request.url}`;
+
+  // Add HTTP request line
+  lines.push(`${request.method} ${fullUrl} HTTP/1.1`);
+
+  // For requests with body, add headers
+  if (request.body) {
+    // Add request headers (excluding Authorization - it's in the outer request)
+    if (request.headers) {
+      for (const [key, value] of Object.entries(request.headers)) {
+        if (key.toLowerCase() !== "authorization") {
+          lines.push(`${key}: ${value}`);
+        }
+      }
+    }
+
+    // Check if Content-Type is already set
+    const hasContentType =
+      request.headers &&
+      Object.keys(request.headers).some(
+        (k) => k.toLowerCase() === "content-type",
+      );
+
+    if (!hasContentType) {
+      lines.push("Content-Type: application/json");
+    }
+
+    // Add Content-Length (required for FileMaker to read the body)
+    const hasContentLength =
+      request.headers &&
+      Object.keys(request.headers).some(
+        (k) => k.toLowerCase() === "content-length",
+      );
+
+    if (!hasContentLength) {
+      lines.push(`Content-Length: ${request.body.length}`);
+    }
+
+    lines.push(""); // Empty line between headers and body
+    lines.push(request.body);
+    // NO blank line after body - the boundary comes immediately
+  } else {
+    // For GET requests (no body), add TWO blank lines
+    lines.push(""); // First blank
+    lines.push(""); // Second blank
+  }
+
+  return lines.join("\r\n");
+}
+
+/**
+ * Formats a changeset containing multiple non-GET operations
+ * @param requests - Array of request configurations (should be non-GET)
+ * @param baseUrl - The base URL to prepend to relative URLs
+ * @param changesetBoundary - Boundary string for the changeset
+ * @returns Formatted changeset string with CRLF line endings
+ */
+function formatChangeset(
+  requests: RequestConfig[],
+  baseUrl: string,
+  changesetBoundary: string,
+): string {
+  const lines: string[] = [];
+
+  lines.push(`Content-Type: multipart/mixed; boundary=${changesetBoundary}`);
+  lines.push(""); // Empty line after headers
+
+  // Add each request in the changeset
+  for (const request of requests) {
+    lines.push(`--${changesetBoundary}`);
+    lines.push(formatSubRequest(request, baseUrl));
+  }
+
+  // Close the changeset
+  lines.push(`--${changesetBoundary}--`);
+
+  return lines.join("\r\n");
+}
+
+/**
+ * Formats multiple requests into a batch request body
+ * @param requests - Array of request configurations
+ * @param baseUrl - The base URL to prepend to relative URLs
+ * @param batchBoundary - Optional boundary string for the batch (generated if not provided)
+ * @returns Object containing the formatted body and boundary
+ */
+export function formatBatchRequest(
+  requests: RequestConfig[],
+  baseUrl: string,
+  batchBoundary?: string,
+): { body: string; boundary: string } {
+  const boundary = batchBoundary || generateBoundary("batch_");
+  const lines: string[] = [];
+
+  // Group requests: consecutive non-GET operations go into changesets
+  let currentChangeset: RequestConfig[] | null = null;
+
+  for (const request of requests) {
+    if (request.method === "GET") {
+      // GET operations break changesets and are added individually
+      if (currentChangeset) {
+        // Close and add the current changeset
+        const changesetBoundary = generateBoundary("changeset_");
+        lines.push(`--${boundary}`);
+        lines.push(
+          formatChangeset(currentChangeset, baseUrl, changesetBoundary),
+        );
+        currentChangeset = null;
+      }
+
+      // Add GET request
+      lines.push(`--${boundary}`);
+      lines.push(formatSubRequest(request, baseUrl));
+    } else {
+      // Non-GET operations: add to current changeset or create new one
+      if (!currentChangeset) {
+        currentChangeset = [];
+      }
+      currentChangeset.push(request);
+    }
+  }
+
+  // Add any remaining changeset
+  if (currentChangeset) {
+    const changesetBoundary = generateBoundary("changeset_");
+    lines.push(`--${boundary}`);
+    lines.push(formatChangeset(currentChangeset, baseUrl, changesetBoundary));
+  }
+
+  // Close the batch
+  lines.push(`--${boundary}--`);
+
+  return {
+    body: lines.join("\r\n"),
+    boundary,
+  };
+}
+
+/**
+ * Formats multiple Request objects into a batch request body
+ * Supports explicit changesets via Request arrays
+ * @param requests - Array of Request objects or Request arrays (for explicit changesets)
+ * @param baseUrl - The base URL to prepend to relative URLs
+ * @param batchBoundary - Optional boundary string for the batch (generated if not provided)
+ * @returns Promise resolving to object containing the formatted body and boundary
+ */
+export async function formatBatchRequestFromNative(
+  requests: Array<Request | Request[]>,
+  baseUrl: string,
+  batchBoundary?: string,
+): Promise<{ body: string; boundary: string }> {
+  const boundary = batchBoundary || generateBoundary("batch_");
+  const lines: string[] = [];
+
+  for (const item of requests) {
+    if (Array.isArray(item)) {
+      // Explicit changeset - array of Requests
+      const changesetBoundary = generateBoundary("changeset_");
+      const changesetConfigs: RequestConfig[] = [];
+
+      for (const request of item) {
+        changesetConfigs.push(await requestToConfig(request));
+      }
+
+      lines.push(`--${boundary}`);
+      lines.push(formatChangeset(changesetConfigs, baseUrl, changesetBoundary));
+    } else {
+      // Single request
+      const config = await requestToConfig(item);
+
+      if (config.method === "GET") {
+        // GET requests are always individual
+        lines.push(`--${boundary}`);
+        lines.push(formatSubRequest(config, baseUrl));
+      } else {
+        // Non-GET operations wrapped in a changeset
+        const changesetBoundary = generateBoundary("changeset_");
+        lines.push(`--${boundary}`);
+        lines.push(formatChangeset([config], baseUrl, changesetBoundary));
+      }
+    }
+  }
+
+  // Close the batch
+  lines.push(`--${boundary}--`);
+
+  return {
+    body: lines.join("\r\n"),
+    boundary,
+  };
+}
+
+/**
+ * Extracts the boundary from a Content-Type header
+ * @param contentType - The Content-Type header value
+ * @returns The boundary string, or null if not found
+ */
+export function extractBoundary(contentType: string): string | null {
+  const match = contentType.match(/boundary=([^;]+)/);
+  return match && match[1] ? match[1].trim() : null;
+}
+
+/**
+ * Parses an HTTP response line (status line)
+ * @param line - The HTTP status line (e.g., "HTTP/1.1 200 OK")
+ * @returns Object containing status code and status text
+ */
+function parseStatusLine(line: string): {
+  status: number;
+  statusText: string;
+} {
+  const match = line.match(/HTTP\/\d\.\d\s+(\d+)\s*(.*)/);
+  if (!match || !match[1]) {
+    return { status: 0, statusText: "" };
+  }
+  return {
+    status: parseInt(match[1], 10),
+    statusText: match[2]?.trim() || "",
+  };
+}
+
+/**
+ * Parses headers from an array of header lines
+ * @param lines - Array of header lines
+ * @returns Object containing parsed headers
+ */
+function parseHeaders(lines: string[]): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const line of lines) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex > 0) {
+      const key = line.substring(0, colonIndex).trim();
+      const value = line.substring(colonIndex + 1).trim();
+      headers[key.toLowerCase()] = value;
+    }
+  }
+  return headers;
+}
+
+/**
+ * Parses a single HTTP response from a batch part
+ * @param part - The raw HTTP response string
+ * @returns Parsed response object
+ */
+function parseHttpResponse(part: string): ParsedBatchResponse {
+  const lines = part.split(/\r\n/);
+
+  // Find the HTTP status line (skip multipart headers)
+  let statusLineIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line && line.startsWith("HTTP/")) {
+      statusLineIndex = i;
+      break;
+    }
+  }
+
+  if (statusLineIndex === -1) {
+    return {
+      status: 0,
+      statusText: "Invalid response",
+      headers: {},
+      body: null,
+    };
+  }
+
+  const statusLine = lines[statusLineIndex];
+  if (!statusLine) {
+    return {
+      status: 0,
+      statusText: "Invalid response",
+      headers: {},
+      body: null,
+    };
+  }
+
+  const { status, statusText } = parseStatusLine(statusLine);
+
+  // Parse headers (between status line and empty line)
+  const headerLines: string[] = [];
+  let bodyStartIndex = lines.length; // Default to end of lines (no body)
+  let foundEmptyLine = false;
+
+  for (let i = statusLineIndex + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === "") {
+      bodyStartIndex = i + 1;
+      foundEmptyLine = true;
+      break;
+    }
+    // Stop at boundary markers (for responses without bodies like 204)
+    if (line && line.startsWith("--")) {
+      break;
+    }
+    if (line) {
+      headerLines.push(line);
+    }
+  }
+
+  const headers = parseHeaders(headerLines);
+
+  // Parse body (everything after the empty line, if there was one)
+  let bodyText = "";
+  if (foundEmptyLine && bodyStartIndex < lines.length) {
+    const bodyLines = lines.slice(bodyStartIndex);
+    // Stop at boundary markers
+    const bodyLinesFiltered: string[] = [];
+    for (const line of bodyLines) {
+      if (line.startsWith("--")) {
+        break;
+      }
+      bodyLinesFiltered.push(line);
+    }
+    bodyText = bodyLinesFiltered.join("\r\n").trim();
+  }
+
+  let body: any = null;
+  if (bodyText) {
+    try {
+      body = JSON.parse(bodyText);
+    } catch {
+      // If not JSON, return as text
+      body = bodyText;
+    }
+  }
+
+  return {
+    status,
+    statusText,
+    headers,
+    body,
+  };
+}
+
+/**
+ * Parses a batch response into individual responses
+ * @param responseText - The raw batch response text
+ * @param contentType - The Content-Type header from the response
+ * @returns Array of parsed responses in the same order as the request
+ */
+export function parseBatchResponse(
+  responseText: string,
+  contentType: string,
+): ParsedBatchResponse[] {
+  const boundary = extractBoundary(contentType);
+  if (!boundary) {
+    throw new Error("Could not extract boundary from Content-Type header");
+  }
+
+  const results: ParsedBatchResponse[] = [];
+
+  // Split by boundary (handle both --boundary and --boundary--)
+  const boundaryPattern = `--${boundary}`;
+  const parts = responseText.split(boundaryPattern);
+
+  for (const part of parts) {
+    const trimmedPart = part.trim();
+
+    // Skip empty parts and the closing boundary marker
+    if (!trimmedPart || trimmedPart === "--") {
+      continue;
+    }
+
+    // Check if this part is a changeset (nested multipart)
+    if (trimmedPart.includes("Content-Type: multipart/mixed")) {
+      // Extract the changeset boundary
+      const changesetContentTypeMatch = trimmedPart.match(
+        /Content-Type: multipart\/mixed;\s*boundary=([^\r\n]+)/,
+      );
+      if (changesetContentTypeMatch) {
+        const changesetBoundary = changesetContentTypeMatch?.[1]?.trim();
+        const changesetPattern = `--${changesetBoundary}`;
+        const changesetParts = trimmedPart.split(changesetPattern);
+
+        for (const changesetPart of changesetParts) {
+          const trimmedChangesetPart = changesetPart.trim();
+          if (!trimmedChangesetPart || trimmedChangesetPart === "--") {
+            continue;
+          }
+
+          // Skip the changeset header
+          if (
+            trimmedChangesetPart.startsWith("Content-Type: multipart/mixed")
+          ) {
+            continue;
+          }
+
+          const response = parseHttpResponse(trimmedChangesetPart);
+          if (response.status > 0) {
+            results.push(response);
+          }
+        }
+      }
+    } else {
+      // Regular response (not a changeset)
+      const response = parseHttpResponse(trimmedPart);
+      if (response.status > 0) {
+        results.push(response);
+      }
+    }
+  }
+
+  return results;
+}

package/src/client/database.ts

@@ -1,39 +1,10 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { ExecutionContext } from "../types";
+import type { ExecutionContext, ExecutableBuilder, Metadata } from "../types";
 import type { BaseTable } from "./base-table";
 import type { TableOccurrence } from "./table-occurrence";
 import { EntitySet } from "./entity-set";
-
-// Type-level validation: Check if a TableOccurrence has fmtId (is TableOccurrenceWithIds)
-type HasFmtId<T> = T extends { fmtId: string } ? true : false;
-
-// Check if all occurrences in a tuple have fmtId
-type AllHaveFmtId<Occurrences extends readonly any[]> =
-  Occurrences extends readonly [infer First, ...infer Rest]
-    ? HasFmtId<First> extends true
-      ? Rest extends readonly []
-        ? true
-        : AllHaveFmtId<Rest>
-      : false
-    : true; // empty array is valid
-
-// Check if none have fmtId
-type NoneHaveFmtId<Occurrences extends readonly any[]> =
-  Occurrences extends readonly [infer First, ...infer Rest]
-    ? HasFmtId<First> extends false
-      ? Rest extends readonly []
-        ? true
-        : NoneHaveFmtId<Rest>
-      : false
-    : true; // empty array is valid
-
-// Valid if all have fmtId or none have fmtId (no mixing allowed)
-export type ValidOccurrenceMix<Occurrences extends readonly any[]> =
-  AllHaveFmtId<Occurrences> extends true
-    ? true
-    : NoneHaveFmtId<Occurrences> extends true
-      ? true
-      : false;
+import { BatchBuilder } from "./batch-builder";
+import { SchemaManager } from "./schema-manager";
 
 // Helper type to extract schema from a TableOccurrence
 type ExtractSchemaFromOccurrence<O> =
@@ -75,16 +46,19 @@ export class Database<
 > {
   private occurrenceMap: Map<string, TableOccurrence<any, any, any, any>>;
   private _useEntityIds: boolean = false;
+  public readonly schema: SchemaManager;
 
   constructor(
     private readonly databaseName: string,
     private readonly context: ExecutionContext,
     config?: {
-      occurrences?: ValidOccurrenceMix<Occurrences> extends true
-        ? Occurrences
-        : Occurrences & {
-            __type_error__: "❌ Cannot mix TableOccurrence with and without entity IDs. Either all occurrences must use TableOccurrenceWithIds (with fmtId and fmfIds) or all must be regular TableOccurrence.";
-          };
+      occurrences?: Occurrences | undefined;
+      /**
+       * Whether to use entity IDs instead of field names in the actual requests to the server
+       * Defaults to true if all occurrences use entity IDs, false otherwise
+       * If set to false but some occurrences do not use entity IDs, an error will be thrown
+       */
+      useEntityIds?: boolean;
     },
   ) {
     this.occurrenceMap = new Map();
@@ -102,7 +76,6 @@ export class Database<
         // An occurrence uses entity IDs if it has both fmtId and fmfIds
         if (hasTableId && hasFieldIds) {
           occurrencesWithIds.push(occ.name);
-          this._useEntityIds = true;
         } else if (!hasTableId && !hasFieldIds) {
           occurrencesWithoutIds.push(occ.name);
         } else {
@@ -114,21 +87,53 @@ export class Database<
         }
       }
 
-      // Check for mixed usage
-      if (occurrencesWithIds.length > 0 && occurrencesWithoutIds.length > 0) {
-        throw new Error(
-          `Cannot mix TableOccurrence instances with and without entity IDs in the same database. ` +
-            `Occurrences with entity IDs: [${occurrencesWithIds.join(", ")}]. ` +
-            `Occurrences without entity IDs: [${occurrencesWithoutIds.join(", ")}]. ` +
-            `Either all table occurrences must use entity IDs (fmtId + fmfIds) or none should.`,
-        );
+      // Determine default value: true if all occurrences use entity IDs, false otherwise
+      const allOccurrencesUseEntityIds =
+        occurrencesWithIds.length > 0 && occurrencesWithoutIds.length === 0;
+      const hasMixedUsage =
+        occurrencesWithIds.length > 0 && occurrencesWithoutIds.length > 0;
+
+      // Handle explicit useEntityIds config
+      if (config.useEntityIds !== undefined) {
+        if (config.useEntityIds === false) {
+          // If explicitly set to false, allow mixed usage and use false
+          this._useEntityIds = false;
+        } else if (config.useEntityIds === true) {
+          // If explicitly set to true, validate that all occurrences use entity IDs
+          if (hasMixedUsage || occurrencesWithoutIds.length > 0) {
+            throw new Error(
+              `useEntityIds is set to true but some occurrences do not use entity IDs. ` +
+                `Occurrences without entity IDs: [${occurrencesWithoutIds.join(", ")}]. ` +
+                `Either set useEntityIds to false or configure all occurrences with entity IDs.`,
+            );
+          }
+          this._useEntityIds = true;
+        }
+      } else {
+        // Default: true if all occurrences use entity IDs, false otherwise
+        // But throw error if there's mixed usage when using defaults
+        if (hasMixedUsage) {
+          throw new Error(
+            `Cannot mix TableOccurrence instances with and without entity IDs in the same database. ` +
+              `Occurrences with entity IDs: [${occurrencesWithIds.join(", ")}]. ` +
+              `Occurrences without entity IDs: [${occurrencesWithoutIds.join(", ")}]. ` +
+              `Either all table occurrences must use entity IDs (fmtId + fmfIds), none should, or explicitly set useEntityIds to false.`,
+          );
+        }
+        this._useEntityIds = allOccurrencesUseEntityIds;
       }
+    } else {
+      // No occurrences provided, use explicit config or default to false
+      this._useEntityIds = config?.useEntityIds ?? false;
     }
 
     // Inform the execution context whether to use entity IDs
     if (this.context._setUseEntityIds) {
       this.context._setUseEntityIds(this._useEntityIds);
     }
+
+    // Initialize schema manager
+    this.schema = new SchemaManager(this.databaseName, this.context);
   }
 
   /**
@@ -181,15 +186,39 @@ export class Database<
     }
   }
 
-  // Example method showing how to use the request method
-  async getMetadata() {
-    const result = await this.context._makeRequest(
-      `/${this.databaseName}/$metadata`,
-    );
+  /**
+   * Retrieves the OData metadata for this database.
+   * @param args Optional configuration object
+   * @param args.format The format to retrieve metadata in. Defaults to "json".
+   * @returns The metadata in the specified format
+   */
+  async getMetadata(args: { format: "xml" }): Promise<string>;
+  async getMetadata(args?: { format?: "json" }): Promise<Metadata>;
+  async getMetadata(args?: {
+    format?: "xml" | "json";
+  }): Promise<string | Metadata> {
+    const result = await this.context._makeRequest<
+      Record<string, Metadata> | string
+    >(`/${this.databaseName}/$metadata`, {
+      headers: {
+        Accept: args?.format === "xml" ? "application/xml" : "application/json",
+      },
+    });
     if (result.error) {
       throw result.error;
     }
-    return result.data;
+
+    if (args?.format === "json") {
+      const data = result.data as Record<string, Metadata>;
+      const metadata = data[this.databaseName];
+      if (!metadata) {
+        throw new Error(
+          `Metadata for database "${this.databaseName}" not found in response`,
+        );
+      }
+      return metadata;
+    }
+    return result.data as string;
   }
 
   /**
@@ -277,4 +306,29 @@ export class Database<
       result: response.scriptResult.resultParameter,
     } as any;
   }
+
+  /**
+   * Create a batch operation builder that allows multiple queries to be executed together
+   * in a single atomic request. All operations succeed or fail together (transactional).
+   *
+   * @param builders - Array of executable query builders to batch
+   * @returns A BatchBuilder that can be executed
+   * @example
+   * ```ts
+   * const result = await db.batch([
+   *   db.from('contacts').list().top(5),
+   *   db.from('users').list().top(5),
+   *   db.from('contacts').insert({ name: 'John' })
+   * ]).execute();
+   *
+   * if (result.data) {
+   *   const [contacts, users, insertResult] = result.data;
+   * }
+   * ```
+   */
+  batch<const Builders extends readonly ExecutableBuilder<any>[]>(
+    builders: Builders,
+  ): BatchBuilder<Builders> {
+    return new BatchBuilder(builders, this.databaseName, this.context);
+  }
 }