@proofkit/fmodata 0.1.0-alpha.1 → 0.1.0-alpha.11

package/src/client/update-builder.ts

@@ -3,11 +3,17 @@ import type {
   ExecutableBuilder,
   Result,
   WithSystemFields,
+  ExecuteOptions,
 } from "../types";
 import type { TableOccurrence } from "./table-occurrence";
 import type { BaseTable } from "./base-table";
 import { QueryBuilder } from "./query-builder";
 import { type FFetchOptions } from "@fetchkit/ffetch";
+import {
+  transformFieldNamesToIds,
+  transformTableName,
+  getTableIdentifiers,
+} from "../transform";
 
 /**
  * Initial update builder returned from EntitySet.update(data)
@@ -16,12 +22,16 @@ import { type FFetchOptions } from "@fetchkit/ffetch";
 export class UpdateBuilder<
   T extends Record<string, any>,
   BT extends BaseTable<any, any, any, any>,
+  ReturnPreference extends "minimal" | "representation" = "minimal",
 > {
   private tableName: string;
   private databaseName: string;
   private context: ExecutionContext;
   private occurrence?: TableOccurrence<any, any, any, any>;
   private data: Partial<T>;
+  private returnPreference: ReturnPreference;
+
+  private databaseUseEntityIds: boolean;
 
   constructor(config: {
     occurrence?: TableOccurrence<any, any, any, any>;
@@ -29,20 +39,26 @@ export class UpdateBuilder<
     databaseName: string;
     context: ExecutionContext;
     data: Partial<T>;
+    returnPreference: ReturnPreference;
+    databaseUseEntityIds?: boolean;
   }) {
     this.occurrence = config.occurrence;
     this.tableName = config.tableName;
     this.databaseName = config.databaseName;
     this.context = config.context;
     this.data = config.data;
+    this.returnPreference = config.returnPreference;
+    this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
   }
 
   /**
    * Update a single record by ID
-   * Returns the count of updated records (0 or 1)
+   * Returns updated count by default, or full record if returnFullRecord was set to true
    */
-  byId(id: string | number): ExecutableUpdateBuilder<T, true> {
-    return new ExecutableUpdateBuilder<T, true>({
+  byId(
+    id: string | number,
+  ): ExecutableUpdateBuilder<T, true, ReturnPreference> {
+    return new ExecutableUpdateBuilder<T, true, ReturnPreference>({
       occurrence: this.occurrence,
       tableName: this.tableName,
       databaseName: this.databaseName,
@@ -50,19 +66,21 @@ export class UpdateBuilder<
       data: this.data,
       mode: "byId",
       recordId: id,
+      returnPreference: this.returnPreference,
+      databaseUseEntityIds: this.databaseUseEntityIds,
     });
   }
 
   /**
    * Update records matching a filter query
-   * Returns the count of updated records
+   * Returns updated count by default, or full record if returnFullRecord was set to true
    * @param fn Callback that receives a QueryBuilder for building the filter
    */
   where(
     fn: (
       q: QueryBuilder<WithSystemFields<T>>,
     ) => QueryBuilder<WithSystemFields<T>>,
-  ): ExecutableUpdateBuilder<T, true> {
+  ): ExecutableUpdateBuilder<T, true, ReturnPreference> {
     // Create a QueryBuilder for the user to configure
     const queryBuilder = new QueryBuilder<
       WithSystemFields<T>,
@@ -80,7 +98,7 @@ export class UpdateBuilder<
     // Let the user configure it
     const configuredBuilder = fn(queryBuilder);
 
-    return new ExecutableUpdateBuilder<T, true>({
+    return new ExecutableUpdateBuilder<T, true, ReturnPreference>({
       occurrence: this.occurrence,
       tableName: this.tableName,
       databaseName: this.databaseName,
@@ -88,6 +106,8 @@ export class UpdateBuilder<
       data: this.data,
       mode: "byFilter",
       queryBuilder: configuredBuilder,
+      returnPreference: this.returnPreference,
+      databaseUseEntityIds: this.databaseUseEntityIds,
     });
   }
 }
@@ -95,12 +115,16 @@ export class UpdateBuilder<
 /**
  * Executable update builder - has execute() method
  * Returned after calling .byId() or .where()
- * Both modes return the count of updated records
+ * Can return either updated count or full record based on returnFullRecord option
  */
 export class ExecutableUpdateBuilder<
   T extends Record<string, any>,
   IsByFilter extends boolean,
-> implements ExecutableBuilder<{ updatedCount: number }>
+  ReturnPreference extends "minimal" | "representation" = "minimal",
+> implements
+    ExecutableBuilder<
+      ReturnPreference extends "minimal" ? { updatedCount: number } : T
+    >
 {
   private tableName: string;
   private databaseName: string;
@@ -110,6 +134,8 @@ export class ExecutableUpdateBuilder<
   private mode: "byId" | "byFilter";
   private recordId?: string | number;
   private queryBuilder?: QueryBuilder<any>;
+  private returnPreference: ReturnPreference;
+  private databaseUseEntityIds: boolean;
 
   constructor(config: {
     occurrence?: TableOccurrence<any, any, any, any>;
@@ -120,6 +146,8 @@ export class ExecutableUpdateBuilder<
     mode: "byId" | "byFilter";
     recordId?: string | number;
     queryBuilder?: QueryBuilder<any>;
+    returnPreference: ReturnPreference;
+    databaseUseEntityIds?: boolean;
   }) {
     this.occurrence = config.occurrence;
     this.tableName = config.tableName;
@@ -129,44 +157,126 @@ export class ExecutableUpdateBuilder<
     this.mode = config.mode;
     this.recordId = config.recordId;
     this.queryBuilder = config.queryBuilder;
+    this.returnPreference = config.returnPreference;
+    this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
+  }
+
+  /**
+   * Helper to merge database-level useEntityIds with per-request options
+   */
+  private mergeExecuteOptions(
+    options?: RequestInit & FFetchOptions & ExecuteOptions,
+  ): RequestInit & FFetchOptions & { useEntityIds?: boolean } {
+    // If useEntityIds is not set in options, use the database-level setting
+    return {
+      ...options,
+      useEntityIds: options?.useEntityIds ?? this.databaseUseEntityIds,
+    };
+  }
+
+  /**
+   * Gets the table ID (FMTID) if using entity IDs, otherwise returns the table name
+   * @param useEntityIds - Optional override for entity ID usage
+   */
+  private getTableId(useEntityIds?: boolean): string {
+    if (!this.occurrence) {
+      return this.tableName;
+    }
+
+    const contextDefault = this.context._getUseEntityIds?.() ?? false;
+    const shouldUseIds = useEntityIds ?? contextDefault;
+
+    if (shouldUseIds) {
+      const identifiers = getTableIdentifiers(this.occurrence);
+      if (!identifiers.id) {
+        throw new Error(
+          `useEntityIds is true but TableOccurrence "${identifiers.name}" does not have an fmtId defined`,
+        );
+      }
+      return identifiers.id;
+    }
+
+    return this.occurrence.getTableName();
   }
 
   async execute(
-    options?: RequestInit & FFetchOptions,
-  ): Promise<Result<{ updatedCount: number }>> {
-    try {
-      let url: string;
-
-      if (this.mode === "byId") {
-        // Update single record by ID: PATCH /{database}/{table}('id')
-        url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
-      } else {
-        // Update by filter: PATCH /{database}/{table}?$filter=...
-        if (!this.queryBuilder) {
-          throw new Error("Query builder is required for filter-based update");
-        }
-
-        // Get the query string from the configured QueryBuilder
-        const queryString = this.queryBuilder.getQueryString();
-        // Remove the leading "/" from the query string as we'll build our own URL
-        const queryParams = queryString.startsWith(`/${this.tableName}`)
+    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },
+  ): Promise<
+    Result<ReturnPreference extends "minimal" ? { updatedCount: number } : T>
+  > {
+    // Merge database-level useEntityIds with per-request options
+    const mergedOptions = this.mergeExecuteOptions(options);
+
+    // Get table identifier with override support
+    const tableId = this.getTableId(mergedOptions.useEntityIds);
+
+    // Transform field names to FMFIDs if using entity IDs
+    // Only transform if useEntityIds resolves to true (respects per-request override)
+    const shouldUseIds = mergedOptions.useEntityIds ?? false;
+
+    const transformedData =
+      this.occurrence?.baseTable && shouldUseIds
+        ? transformFieldNamesToIds(this.data, this.occurrence.baseTable)
+        : this.data;
+
+    let url: string;
+
+    if (this.mode === "byId") {
+      // Update single record by ID: PATCH /{database}/{table}('id')
+      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
+    } else {
+      // Update by filter: PATCH /{database}/{table}?$filter=...
+      if (!this.queryBuilder) {
+        throw new Error("Query builder is required for filter-based update");
+      }
+
+      // Get the query string from the configured QueryBuilder
+      const queryString = this.queryBuilder.getQueryString();
+      // The query string will have the tableId already transformed by QueryBuilder
+      // Remove the leading "/" and table name from the query string as we'll build our own URL
+      const queryParams = queryString.startsWith(`/${tableId}`)
+        ? queryString.slice(`/${tableId}`.length)
+        : queryString.startsWith(`/${this.tableName}`)
           ? queryString.slice(`/${this.tableName}`.length)
           : queryString;
 
-        url = `/${this.databaseName}/${this.tableName}${queryParams}`;
-      }
+      url = `/${this.databaseName}/${tableId}${queryParams}`;
+    }
+
+    // Set Prefer header based on returnPreference
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (this.returnPreference === "representation") {
+      headers["Prefer"] = "return=representation";
+    }
 
-      // Make PATCH request with JSON body
-      const response = await this.context._makeRequest(url, {
-        method: "PATCH",
-        headers: {
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify(this.data),
-        ...options,
-      });
-
-      // Both byId and byFilter return affected row count
+    // Make PATCH request with JSON body
+    const result = await this.context._makeRequest(url, {
+      method: "PATCH",
+      headers,
+      body: JSON.stringify(transformedData),
+      ...mergedOptions,
+    });
+
+    if (result.error) {
+      return { data: undefined, error: result.error };
+    }
+
+    const response = result.data;
+
+    // Handle based on return preference
+    if (this.returnPreference === "representation") {
+      // Return the full updated record
+      return {
+        data: response as ReturnPreference extends "minimal"
+          ? { updatedCount: number }
+          : T,
+        error: undefined,
+      };
+    } else {
+      // Return updated count (minimal)
       let updatedCount = 0;
 
       if (typeof response === "number") {
@@ -176,37 +286,113 @@ export class ExecutableUpdateBuilder<
         updatedCount = (response as any).updatedCount || 0;
       }
 
-      return { data: { updatedCount }, error: undefined };
-    } catch (error) {
       return {
-        data: undefined,
-        error: error instanceof Error ? error : new Error(String(error)),
+        data: { updatedCount } as ReturnPreference extends "minimal"
+          ? { updatedCount: number }
+          : T,
+        error: undefined,
       };
     }
   }
 
   getRequestConfig(): { method: string; url: string; body?: any } {
+    // For batch operations, use database-level setting (no per-request override available here)
+    const tableId = this.getTableId(this.databaseUseEntityIds);
+
+    // Transform field names to FMFIDs if using entity IDs
+    const transformedData =
+      this.occurrence?.baseTable && this.databaseUseEntityIds
+        ? transformFieldNamesToIds(this.data, this.occurrence.baseTable)
+        : this.data;
+
     let url: string;
 
     if (this.mode === "byId") {
-      url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
+      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
     } else {
       if (!this.queryBuilder) {
         throw new Error("Query builder is required for filter-based update");
       }
 
       const queryString = this.queryBuilder.getQueryString();
-      const queryParams = queryString.startsWith(`/${this.tableName}`)
-        ? queryString.slice(`/${this.tableName}`.length)
-        : queryString;
+      const queryParams = queryString.startsWith(`/${tableId}`)
+        ? queryString.slice(`/${tableId}`.length)
+        : queryString.startsWith(`/${this.tableName}`)
+          ? queryString.slice(`/${this.tableName}`.length)
+          : queryString;
 
-      url = `/${this.databaseName}/${this.tableName}${queryParams}`;
+      url = `/${this.databaseName}/${tableId}${queryParams}`;
     }
 
     return {
       method: "PATCH",
       url,
-      body: JSON.stringify(this.data),
+      body: JSON.stringify(transformedData),
     };
   }
+
+  toRequest(baseUrl: string): Request {
+    const config = this.getRequestConfig();
+    const fullUrl = `${baseUrl}${config.url}`;
+
+    return new Request(fullUrl, {
+      method: config.method,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: config.body,
+    });
+  }
+
+  async processResponse(
+    response: Response,
+    options?: ExecuteOptions,
+  ): Promise<
+    Result<ReturnPreference extends "minimal" ? { updatedCount: number } : T>
+  > {
+    // Check for empty response (204 No Content)
+    const text = await response.text();
+    if (!text || text.trim() === "") {
+      // For 204 No Content, check the fmodata.affected_rows header
+      const affectedRows = response.headers.get("fmodata.affected_rows");
+      const updatedCount = affectedRows ? parseInt(affectedRows, 10) : 1;
+      return {
+        data: { updatedCount } as ReturnPreference extends "minimal"
+          ? { updatedCount: number }
+          : T,
+        error: undefined,
+      };
+    }
+
+    const rawResponse = JSON.parse(text);
+
+    // Handle based on return preference
+    if (this.returnPreference === "representation") {
+      // Return the full updated record
+      return {
+        data: rawResponse as ReturnPreference extends "minimal"
+          ? { updatedCount: number }
+          : T,
+        error: undefined,
+      };
+    } else {
+      // Return updated count (minimal)
+      let updatedCount = 0;
+
+      if (typeof rawResponse === "number") {
+        updatedCount = rawResponse;
+      } else if (rawResponse && typeof rawResponse === "object") {
+        // Check if the response has a count property (fallback)
+        updatedCount = (rawResponse as any).updatedCount || 0;
+      }
+
+      return {
+        data: { updatedCount } as ReturnPreference extends "minimal"
+          ? { updatedCount: number }
+          : T,
+        error: undefined,
+      };
+    }
+  }
 }

package/src/errors.ts

@@ -0,0 +1,217 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/**
+ * Base class for all fmodata errors
+ */
+export abstract class FMODataError extends Error {
+  abstract readonly kind: string;
+  readonly timestamp: Date;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = this.constructor.name;
+    this.timestamp = new Date();
+  }
+}
+
+// ============================================
+// HTTP Errors (with status codes)
+// ============================================
+
+export class HTTPError extends FMODataError {
+  readonly kind = "HTTPError" as const;
+  readonly url: string;
+  readonly status: number;
+  readonly statusText: string;
+  readonly response?: any;
+
+  constructor(url: string, status: number, statusText: string, response?: any) {
+    super(`HTTP ${status} ${statusText} for ${url}`);
+    this.url = url;
+    this.status = status;
+    this.statusText = statusText;
+    this.response = response;
+  }
+
+  // Helper methods for common status checks
+  is4xx(): boolean {
+    return this.status >= 400 && this.status < 500;
+  }
+
+  is5xx(): boolean {
+    return this.status >= 500 && this.status < 600;
+  }
+
+  isNotFound(): boolean {
+    return this.status === 404;
+  }
+
+  isUnauthorized(): boolean {
+    return this.status === 401;
+  }
+
+  isForbidden(): boolean {
+    return this.status === 403;
+  }
+}
+
+// ============================================
+// OData Specific Errors
+// ============================================
+
+export class ODataError extends FMODataError {
+  readonly kind = "ODataError" as const;
+  readonly url: string;
+  readonly code?: string;
+  readonly details?: any;
+
+  constructor(url: string, message: string, code?: string, details?: any) {
+    super(`OData error: ${message}`);
+    this.url = url;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class SchemaLockedError extends FMODataError {
+  readonly kind = "SchemaLockedError" as const;
+  readonly url: string;
+  readonly code: string;
+  readonly details?: any;
+
+  constructor(url: string, message: string, details?: any) {
+    super(`OData error: ${message}`);
+    this.url = url;
+    this.code = "303";
+    this.details = details;
+  }
+}
+
+// ============================================
+// Validation Errors
+// ============================================
+
+export class ValidationError extends FMODataError {
+  readonly kind = "ValidationError" as const;
+  readonly field?: string;
+  readonly issues: readonly StandardSchemaV1.Issue[];
+  readonly value?: unknown;
+
+  constructor(
+    message: string,
+    issues: readonly StandardSchemaV1.Issue[],
+    options?: {
+      field?: string;
+      value?: unknown;
+      cause?: Error["cause"];
+    },
+  ) {
+    super(
+      message,
+      options?.cause !== undefined ? { cause: options.cause } : undefined,
+    );
+    this.field = options?.field;
+    this.issues = issues;
+    this.value = options?.value;
+  }
+}
+
+export class ResponseStructureError extends FMODataError {
+  readonly kind = "ResponseStructureError" as const;
+  readonly expected: string;
+  readonly received: any;
+
+  constructor(expected: string, received: any) {
+    super(`Invalid response structure: expected ${expected}`);
+    this.expected = expected;
+    this.received = received;
+  }
+}
+
+export class RecordCountMismatchError extends FMODataError {
+  readonly kind = "RecordCountMismatchError" as const;
+  readonly expected: number | "one" | "at-most-one";
+  readonly received: number;
+
+  constructor(expected: number | "one" | "at-most-one", received: number) {
+    const expectedStr = typeof expected === "number" ? expected : expected;
+    super(`Expected ${expectedStr} record(s), but received ${received}`);
+    this.expected = expected;
+    this.received = received;
+  }
+}
+
+export class InvalidLocationHeaderError extends FMODataError {
+  readonly kind = "InvalidLocationHeaderError" as const;
+  readonly locationHeader?: string;
+
+  constructor(message: string, locationHeader?: string) {
+    super(message);
+    this.locationHeader = locationHeader;
+  }
+}
+
+// ============================================
+// Type Guards
+// ============================================
+
+export function isHTTPError(error: unknown): error is HTTPError {
+  return error instanceof HTTPError;
+}
+
+export function isValidationError(error: unknown): error is ValidationError {
+  return error instanceof ValidationError;
+}
+
+export function isODataError(error: unknown): error is ODataError {
+  return error instanceof ODataError;
+}
+
+export function isSchemaLockedError(
+  error: unknown,
+): error is SchemaLockedError {
+  return error instanceof SchemaLockedError;
+}
+
+export function isResponseStructureError(
+  error: unknown,
+): error is ResponseStructureError {
+  return error instanceof ResponseStructureError;
+}
+
+export function isRecordCountMismatchError(
+  error: unknown,
+): error is RecordCountMismatchError {
+  return error instanceof RecordCountMismatchError;
+}
+
+export function isFMODataError(error: unknown): error is FMODataError {
+  return error instanceof FMODataError;
+}
+
+// ============================================
+// Union type for all possible errors
+// ============================================
+
+// Re-export ffetch errors (they'll be imported from @fetchkit/ffetch)
+export type {
+  TimeoutError,
+  AbortError,
+  NetworkError,
+  RetryLimitError,
+  CircuitOpenError,
+} from "@fetchkit/ffetch";
+
+export type FMODataErrorType =
+  | import("@fetchkit/ffetch").TimeoutError
+  | import("@fetchkit/ffetch").AbortError
+  | import("@fetchkit/ffetch").NetworkError
+  | import("@fetchkit/ffetch").RetryLimitError
+  | import("@fetchkit/ffetch").CircuitOpenError
+  | HTTPError
+  | ODataError
+  | SchemaLockedError
+  | ValidationError
+  | ResponseStructureError
+  | RecordCountMismatchError
+  | InvalidLocationHeaderError;