@proofkit/fmodata 0.1.0-alpha.13 → 0.1.0-alpha.14

package/src/client/error-parser.ts

@@ -0,0 +1,59 @@
+import {
+  HTTPError,
+  ODataError,
+  SchemaLockedError,
+  FMODataErrorType,
+} from "../errors";
+import { safeJsonParse } from "./sanitize-json";
+
+/**
+ * Parses an error response and returns an appropriate error object.
+ * This helper is used by builder processResponse methods to handle error responses
+ * consistently, particularly important for batch operations where errors need to be
+ * properly parsed from the response body.
+ *
+ * @param response - The Response object (may be from batch or direct request)
+ * @param url - The URL that was requested (for error context)
+ * @returns An appropriate error object (ODataError, SchemaLockedError, or HTTPError)
+ */
+export async function parseErrorResponse(
+  response: Response,
+  url: string,
+): Promise<FMODataErrorType> {
+  // Try to parse error body if it's JSON
+  let errorBody: { error?: { code?: string | number; message?: string } } | undefined;
+  
+  try {
+    if (response.headers.get("content-type")?.includes("application/json")) {
+      errorBody = await safeJsonParse<typeof errorBody>(response);
+    }
+  } catch {
+    // Ignore JSON parse errors - we'll fall back to HTTPError
+  }
+
+  // Check if it's an OData error response
+  if (errorBody?.error) {
+    const errorCode = errorBody.error.code;
+    const errorMessage = errorBody.error.message || response.statusText;
+
+    // Check for schema locked error (code 303)
+    if (errorCode === "303" || errorCode === 303) {
+      return new SchemaLockedError(url, errorMessage, errorBody.error);
+    }
+
+    return new ODataError(
+      url,
+      errorMessage,
+      String(errorCode),
+      errorBody.error,
+    );
+  }
+
+  // Fall back to generic HTTPError
+  return new HTTPError(url, response.status, response.statusText, errorBody);
+}
+
+
+
+
+

package/src/client/filemaker-odata.ts

@@ -15,7 +15,6 @@ import {
   ResponseParseError,
 } from "../errors";
 import { Database } from "./database";
-import { TableOccurrence } from "./table-occurrence";
 import { safeJsonParse } from "./sanitize-json";
 import { get } from "es-toolkit/compat";
 
@@ -116,14 +115,7 @@ export class FMServerConnection implements ExecutionContext {
         headers,
       };
 
-      // For batch requests, use native fetch to avoid any potential serialization issues with ffetch
-      const resp = url.includes("/$batch")
-        ? await fetch(fullUrl, {
-            method: finalOptions.method,
-            headers: finalOptions.headers,
-            body: finalOptions.body,
-          })
-        : await clientToUse(fullUrl, finalOptions);
+      const resp = await clientToUse(fullUrl, finalOptions);
 
       // Handle HTTP errors
       if (!resp.ok) {
@@ -261,15 +253,12 @@ export class FMServerConnection implements ExecutionContext {
     }
   }
 
-  database<
-    const Occurrences extends readonly TableOccurrence<any, any, any, any>[],
-  >(
+  database(
     name: string,
     config?: {
-      occurrences?: Occurrences | undefined;
       useEntityIds?: boolean;
     },
-  ): Database<Occurrences> {
+  ): Database {
     return new Database(name, this, config);
   }
 

package/src/client/insert-builder.ts

@@ -8,51 +8,59 @@ import type {
   ConditionallyWithODataAnnotations,
 } from "../types";
 import { getAcceptHeader } from "../types";
-import type { TableOccurrence } from "./table-occurrence";
-import { validateSingleResponse } from "../validation";
+import type { FMTable } from "../orm/table";
+import {
+  getBaseTableConfig,
+  getTableName,
+  getTableId as getTableIdHelper,
+  isUsingEntityIds,
+} from "../orm/table";
+import {
+  validateSingleResponse,
+  validateAndTransformInput,
+} from "../validation";
 import { type FFetchOptions } from "@fetchkit/ffetch";
 import {
   transformFieldNamesToIds,
-  transformTableName,
   transformResponseFields,
-  getTableIdentifiers,
 } from "../transform";
 import { InvalidLocationHeaderError } from "../errors";
 import { safeJsonParse } from "./sanitize-json";
+import { parseErrorResponse } from "./error-parser";
 
 export type InsertOptions = {
   return?: "minimal" | "representation";
 };
 
+import type { InferSchemaOutputFromFMTable } from "../orm/table";
+
 export class InsertBuilder<
-  T extends Record<string, any>,
-  Occ extends TableOccurrence<any, any, any, any> | undefined = undefined,
+  Occ extends FMTable<any, any> | undefined = undefined,
   ReturnPreference extends "minimal" | "representation" = "representation",
 > implements
     ExecutableBuilder<
-      ReturnPreference extends "minimal" ? { ROWID: number } : T
+      ReturnPreference extends "minimal"
+        ? { ROWID: number }
+        : InferSchemaOutputFromFMTable<NonNullable<Occ>>
     >
 {
-  private occurrence?: Occ;
-  private tableName: string;
+  private table?: Occ;
   private databaseName: string;
   private context: ExecutionContext;
-  private data: Partial<T>;
+  private data: Partial<InferSchemaOutputFromFMTable<NonNullable<Occ>>>;
   private returnPreference: ReturnPreference;
 
   private databaseUseEntityIds: boolean;
 
   constructor(config: {
     occurrence?: Occ;
-    tableName: string;
     databaseName: string;
     context: ExecutionContext;
-    data: Partial<T>;
+    data: Partial<InferSchemaOutputFromFMTable<NonNullable<Occ>>>;
     returnPreference?: ReturnPreference;
     databaseUseEntityIds?: boolean;
   }) {
-    this.occurrence = config.occurrence;
-    this.tableName = config.tableName;
+    this.table = config.occurrence;
     this.databaseName = config.databaseName;
     this.context = config.context;
     this.data = config.data;
@@ -74,7 +82,6 @@ export class InsertBuilder<
     };
   }
 
-
   /**
    * Parse ROWID from Location header
    * Expected formats:
@@ -115,24 +122,23 @@ export class InsertBuilder<
    * @param useEntityIds - Optional override for entity ID usage
    */
   private getTableId(useEntityIds?: boolean): string {
-    if (!this.occurrence) {
-      return this.tableName;
+    if (!this.table) {
+      throw new Error("Table occurrence is required");
     }
 
     const contextDefault = this.context._getUseEntityIds?.() ?? false;
     const shouldUseIds = useEntityIds ?? contextDefault;
 
     if (shouldUseIds) {
-      const identifiers = getTableIdentifiers(this.occurrence);
-      if (!identifiers.id) {
+      if (!isUsingEntityIds(this.table)) {
         throw new Error(
-          `useEntityIds is true but TableOccurrence "${identifiers.name}" does not have an fmtId defined`
+          `useEntityIds is true but table "${getTableName(this.table)}" does not have entity IDs configured`,
         );
       }
-      return identifiers.id;
+      return getTableIdHelper(this.table);
     }
 
-    return this.occurrence.getTableName();
+    return getTableName(this.table);
   }
 
   async execute<EO extends ExecuteOptions>(
@@ -142,25 +148,43 @@ export class InsertBuilder<
       ReturnPreference extends "minimal"
         ? { ROWID: number }
         : ConditionallyWithODataAnnotations<
-            T,
+            InferSchemaOutputFromFMTable<NonNullable<Occ>>,
             EO["includeODataAnnotations"] extends true ? true : false
           >
     >
   > {
     // 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);
     const url = `/${this.databaseName}/${tableId}`;
 
+    // Validate and transform input data using input validators (writeValidators)
+    let validatedData = this.data;
+    if (this.table) {
+      const baseTableConfig = getBaseTableConfig(this.table);
+      const inputSchema = baseTableConfig.inputSchema;
+
+      try {
+        validatedData = await validateAndTransformInput(this.data, inputSchema);
+      } catch (error) {
+        // If validation fails, return error immediately
+        return {
+          data: undefined,
+          error: error instanceof Error ? error : new Error(String(error)),
+        } as any;
+      }
+    }
+
     // 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;
+
+    const transformedData =
+      this.table && shouldUseIds
+        ? transformFieldNamesToIds(validatedData, this.table)
+        : validatedData;
 
     // Set Prefer header based on return preference
     const preferHeader =
@@ -204,19 +228,31 @@ export class InsertBuilder<
 
     // Transform response field IDs back to names if using entity IDs
     // Only transform if useEntityIds resolves to true (respects per-request override)
-    if (this.occurrence?.baseTable && shouldUseIds) {
+    if (this.table && shouldUseIds) {
       response = transformResponseFields(
         response,
-        this.occurrence.baseTable,
+        this.table,
         undefined, // No expand configs for insert
       );
     }
 
-    // Get schema from occurrence if available
-    const schema = this.occurrence?.baseTable?.schema;
+    // Get schema from table if available, excluding container fields
+    let schema: Record<string, any> | undefined;
+    if (this.table) {
+      const baseTableConfig = getBaseTableConfig(this.table);
+      const containerFields = baseTableConfig.containerFields || [];
+
+      // Filter out container fields from schema
+      schema = { ...baseTableConfig.schema };
+      for (const containerField of containerFields) {
+        delete schema[containerField as string];
+      }
+    }
 
     // Validate the response (FileMaker returns the created record)
-    const validation = await validateSingleResponse<T>(
+    const validation = await validateSingleResponse<
+      InferSchemaOutputFromFMTable<NonNullable<Occ>>
+    >(
       response,
       schema,
       undefined, // No selected fields for insert
@@ -241,12 +277,14 @@ export class InsertBuilder<
 
   getRequestConfig(): { method: string; url: string; body?: any } {
     // For batch operations, use database-level setting (no per-request override available here)
+    // Note: Input validation happens in execute() and processResponse() for batch operations
     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;
+    const transformedData =
+      this.table && this.databaseUseEntityIds
+        ? transformFieldNamesToIds(this.data, this.table)
+        : this.data;
 
     return {
       method: "POST",
@@ -280,8 +318,22 @@ export class InsertBuilder<
     response: Response,
     options?: ExecuteOptions,
   ): Promise<
-    Result<ReturnPreference extends "minimal" ? { ROWID: number } : T>
+    Result<
+      ReturnPreference extends "minimal"
+        ? { ROWID: number }
+        : InferSchemaOutputFromFMTable<NonNullable<Occ>>
+    >
   > {
+    // Check for error responses (important for batch operations)
+    if (!response.ok) {
+      const tableName = this.table ? getTableName(this.table) : "unknown";
+      const error = await parseErrorResponse(
+        response,
+        response.url || `/${this.databaseName}/${tableName}`,
+      );
+      return { data: undefined, error };
+    }
+
     // Handle 204 No Content (common in batch/changeset operations)
     // FileMaker uses return=minimal for changeset operations regardless of Prefer header
     if (response.status === 204) {
@@ -336,24 +388,53 @@ export class InsertBuilder<
       };
     }
 
+    // Validate and transform input data using input validators (writeValidators)
+    // This is needed for processResponse because it's called from batch operations
+    // where the data hasn't been validated yet
+    let validatedData = this.data;
+    if (this.table) {
+      const baseTableConfig = getBaseTableConfig(this.table);
+      const inputSchema = baseTableConfig.inputSchema;
+      try {
+        validatedData = await validateAndTransformInput(this.data, inputSchema);
+      } catch (error) {
+        return {
+          data: undefined,
+          error: error instanceof Error ? error : new Error(String(error)),
+        } as any;
+      }
+    }
+
     // Transform response field IDs back to names if using entity IDs
     // Only transform if useEntityIds resolves to true (respects per-request override)
     const shouldUseIds = options?.useEntityIds ?? this.databaseUseEntityIds;
-    
+
     let transformedResponse = rawResponse;
-    if (this.occurrence?.baseTable && shouldUseIds) {
+    if (this.table && shouldUseIds) {
       transformedResponse = transformResponseFields(
         rawResponse,
-        this.occurrence.baseTable,
+        this.table,
         undefined, // No expand configs for insert
       );
     }
 
-    // Get schema from occurrence if available
-    const schema = this.occurrence?.baseTable?.schema;
+    // Get schema from table if available, excluding container fields
+    let schema: Record<string, any> | undefined;
+    if (this.table) {
+      const baseTableConfig = getBaseTableConfig(this.table);
+      const containerFields = baseTableConfig.containerFields || [];
+
+      // Filter out container fields from schema
+      schema = { ...baseTableConfig.schema };
+      for (const containerField of containerFields) {
+        delete schema[containerField as string];
+      }
+    }
 
     // Validate the response (FileMaker returns the created record)
-    const validation = await validateSingleResponse<T>(
+    const validation = await validateSingleResponse<
+      InferSchemaOutputFromFMTable<NonNullable<Occ>>
+    >(
       transformedResponse,
       schema,
       undefined, // No selected fields for insert

package/src/client/query/expand-builder.ts

@@ -0,0 +1,164 @@
+import { QueryOptions } from "odata-query";
+import buildQuery from "odata-query";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { FMTable } from "../../orm/table";
+import type { ExpandValidationConfig } from "../../validation";
+import { formatSelectFields } from "../builders/select-utils";
+
+/**
+ * Internal type for expand configuration
+ */
+export type ExpandConfig = {
+  relation: string;
+  options?: Partial<QueryOptions<any>>;
+  targetTable?: FMTable<any, any>;
+};
+
+/**
+ * Builds OData expand query strings and validation configs.
+ * Handles nested expands recursively and transforms relation names to FMTIDs
+ * when using entity IDs.
+ */
+export class ExpandBuilder {
+  constructor(private useEntityIds: boolean) {}
+
+  /**
+   * Builds OData expand query string from expand configurations.
+   * Handles nested expands recursively.
+   * Transforms relation names to FMTIDs if using entity IDs.
+   */
+  buildExpandString(configs: ExpandConfig[]): string {
+    if (configs.length === 0) {
+      return "";
+    }
+
+    return configs.map((config) => this.buildSingleExpand(config)).join(",");
+  }
+
+  /**
+   * Builds a single expand string with its options.
+   */
+  private buildSingleExpand(config: ExpandConfig): string {
+    // Get target table/occurrence from config (stored during expand call)
+    const targetTable = config.targetTable;
+
+    // When using entity IDs, use the target table's FMTID in the expand parameter
+    // FileMaker expects FMTID in $expand when Prefer header is set
+    // Only use FMTID if databaseUseEntityIds is enabled
+    let relationName = config.relation;
+    if (this.useEntityIds) {
+      if (targetTable && FMTable.Symbol.EntityId in targetTable) {
+        const tableId = (targetTable as any)[FMTable.Symbol.EntityId] as
+          | `FMTID:${string}`
+          | undefined;
+        if (tableId) {
+          relationName = tableId;
+        }
+      }
+    }
+
+    if (!config.options || Object.keys(config.options).length === 0) {
+      // Simple expand without options
+      return relationName;
+    }
+
+    // Build query options for this expand
+    const parts: string[] = [];
+
+    if (config.options.select) {
+      // Use shared formatSelectFields function for consistent id field quoting
+      const selectArray = Array.isArray(config.options.select)
+        ? config.options.select.map(String)
+        : [String(config.options.select)];
+      const selectFields = formatSelectFields(
+        selectArray,
+        targetTable,
+        this.useEntityIds,
+      );
+      parts.push(`$select=${selectFields}`);
+    }
+
+    if (config.options.filter) {
+      // Filter should already be transformed by the nested builder
+      // Use odata-query to build filter string
+      const filterQuery = buildQuery({ filter: config.options.filter });
+      const filterMatch = filterQuery.match(/\$filter=([^&]+)/);
+      if (filterMatch) {
+        parts.push(`$filter=${filterMatch[1]}`);
+      }
+    }
+
+    if (config.options.orderBy) {
+      // OrderBy should already be transformed by the nested builder
+      const orderByValue = Array.isArray(config.options.orderBy)
+        ? config.options.orderBy.join(",")
+        : config.options.orderBy;
+      parts.push(`$orderby=${String(orderByValue)}`);
+    }
+
+    if (config.options.top !== undefined) {
+      parts.push(`$top=${config.options.top}`);
+    }
+
+    if (config.options.skip !== undefined) {
+      parts.push(`$skip=${config.options.skip}`);
+    }
+
+    // Handle nested expands (from expand configs)
+    if (config.options.expand) {
+      // If expand is a string, it's already been built
+      if (typeof config.options.expand === "string") {
+        parts.push(`$expand=${config.options.expand}`);
+      }
+    }
+
+    if (parts.length === 0) {
+      return relationName;
+    }
+
+    return `${relationName}(${parts.join(";")})`;
+  }
+
+  /**
+   * Builds expand validation configs from internal expand configurations.
+   * These are used to validate expanded navigation properties.
+   */
+  buildValidationConfigs(configs: ExpandConfig[]): ExpandValidationConfig[] {
+    return configs.map((config) => {
+      // Get target table/occurrence from config (stored during expand call)
+      const targetTable = config.targetTable;
+
+      // Extract schema from target table/occurrence
+      let targetSchema: Record<string, StandardSchemaV1> | undefined;
+      if (targetTable) {
+        const tableSchema = (targetTable as any)[FMTable.Symbol.Schema];
+        if (tableSchema) {
+          const zodSchema = tableSchema["~standard"]?.schema;
+          if (
+            zodSchema &&
+            typeof zodSchema === "object" &&
+            "shape" in zodSchema
+          ) {
+            targetSchema = zodSchema.shape as Record<string, StandardSchemaV1>;
+          }
+        }
+      }
+
+      // Extract selected fields from options
+      const selectedFields = config.options?.select
+        ? Array.isArray(config.options.select)
+          ? config.options.select.map((f) => String(f))
+          : [String(config.options.select)]
+        : undefined;
+
+      return {
+        relation: config.relation,
+        targetSchema: targetSchema,
+        targetTable: targetTable,
+        table: targetTable, // For transformation
+        selectedFields: selectedFields,
+        nestedExpands: undefined, // TODO: Handle nested expands if needed
+      };
+    });
+  }
+}

package/src/client/query/index.ts

@@ -0,0 +1,13 @@
+// Re-export QueryBuilder as the main export
+export { QueryBuilder } from "./query-builder";
+
+// Export types
+export type {
+  TypeSafeOrderBy,
+  ExpandedRelations,
+  QueryReturnType,
+} from "./query-builder";
+
+// Export ExpandConfig from expand-builder
+export type { ExpandConfig } from "./expand-builder";
+