@proofkit/fmodata 0.1.0-alpha.8 → 0.1.0-beta.23

package/dist/esm/client/insert-builder.js

@@ -1,25 +1,31 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-import { validateSingleResponse } from "../validation.js";
-import { getTableIdentifiers, transformFieldNamesToIds, transformResponseFields } from "../transform.js";
 import { InvalidLocationHeaderError } from "../errors.js";
+import { isUsingEntityIds, getTableName, getTableId, getBaseTableConfig } from "../orm/table.js";
+import { transformFieldNamesToIds, transformResponseFields } from "../transform.js";
+import { getAcceptHeader } from "../types.js";
+import { validateAndTransformInput, validateSingleResponse } from "../validation.js";
+import { parseErrorResponse } from "./error-parser.js";
+import { safeJsonParse } from "./sanitize-json.js";
+const ROWID_MATCH_REGEX = /ROWID=(\d+)/;
+const PAREN_VALUE_REGEX = /\(['"]?([^'"]+)['"]?\)/;
 class InsertBuilder {
   constructor(config) {
-    __publicField(this, "occurrence");
-    __publicField(this, "tableName");
+    __publicField(this, "table");
     __publicField(this, "databaseName");
     __publicField(this, "context");
     __publicField(this, "data");
     __publicField(this, "returnPreference");
     __publicField(this, "databaseUseEntityIds");
-    this.occurrence = config.occurrence;
-    this.tableName = config.tableName;
+    __publicField(this, "databaseIncludeSpecialColumns");
+    this.table = config.occurrence;
     this.databaseName = config.databaseName;
     this.context = config.context;
     this.data = config.data;
     this.returnPreference = config.returnPreference || "representation";
     this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
+    this.databaseIncludeSpecialColumns = config.databaseIncludeSpecialColumns ?? false;
   }
   /**
    * Helper to merge database-level useEntityIds with per-request options
@@ -30,16 +36,6 @@ class InsertBuilder {
       useEntityIds: (options == null ? void 0 : options.useEntityIds) ?? this.databaseUseEntityIds
     };
   }
-  /**
-   * Helper to conditionally strip OData annotations based on options
-   */
-  stripODataAnnotationsIfNeeded(data, options) {
-    if ((options == null ? void 0 : options.includeODataAnnotations) === true) {
-      return data;
-    }
-    const { "@id": _id, "@editLink": _editLink, ...rest } = data;
-    return rest;
-  }
   /**
    * Parse ROWID from Location header
    * Expected formats:
@@ -48,19 +44,17 @@ class InsertBuilder {
    */
   parseLocationHeader(locationHeader) {
     if (!locationHeader) {
-      throw new InvalidLocationHeaderError(
-        "Location header is required but was not provided"
-      );
+      throw new InvalidLocationHeaderError("Location header is required but was not provided");
     }
-    const rowidMatch = locationHeader.match(/ROWID=(\d+)/);
-    if (rowidMatch && rowidMatch[1]) {
-      return parseInt(rowidMatch[1], 10);
+    const rowidMatch = locationHeader.match(ROWID_MATCH_REGEX);
+    if (rowidMatch == null ? void 0 : rowidMatch[1]) {
+      return Number.parseInt(rowidMatch[1], 10);
     }
-    const parenMatch = locationHeader.match(/\(['"]?([^'"]+)['"]?\)/);
-    if (parenMatch && parenMatch[1]) {
+    const parenMatch = locationHeader.match(PAREN_VALUE_REGEX);
+    if (parenMatch == null ? void 0 : parenMatch[1]) {
       const value = parenMatch[1];
-      const numValue = parseInt(value, 10);
-      if (!isNaN(numValue)) {
+      const numValue = Number.parseInt(value, 10);
+      if (!Number.isNaN(numValue)) {
         return numValue;
       }
     }
@@ -75,35 +69,48 @@ class InsertBuilder {
    */
   getTableId(useEntityIds) {
     var _a, _b;
-    if (!this.occurrence) {
-      return this.tableName;
+    if (!this.table) {
+      throw new Error("Table occurrence is required");
     }
     const contextDefault = ((_b = (_a = this.context)._getUseEntityIds) == null ? void 0 : _b.call(_a)) ?? 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 getTableId(this.table);
     }
-    return this.occurrence.getTableName();
+    return getTableName(this.table);
   }
   async execute(options) {
-    var _a, _b, _c, _d;
     const mergedOptions = this.mergeExecuteOptions(options);
     const tableId = this.getTableId(mergedOptions.useEntityIds);
     const url = `/${this.databaseName}/${tableId}`;
+    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: void 0,
+          error: error instanceof Error ? error : new Error(String(error))
+          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type
+        };
+      }
+    }
     const shouldUseIds = mergedOptions.useEntityIds ?? false;
-    const transformedData = ((_a = this.occurrence) == null ? void 0 : _a.baseTable) && shouldUseIds ? transformFieldNamesToIds(this.data, this.occurrence.baseTable) : this.data;
+    const transformedData = this.table && shouldUseIds ? transformFieldNamesToIds(validatedData, this.table) : validatedData;
     const preferHeader = this.returnPreference === "minimal" ? "return=minimal" : "return=representation";
     const result = await this.context._makeRequest(url, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         Prefer: preferHeader,
+        // biome-ignore lint/suspicious/noExplicitAny: Type assertion for headers object
         ...(mergedOptions == null ? void 0 : mergedOptions.headers) || {}
       },
       body: JSON.stringify(transformedData),
@@ -114,7 +121,7 @@ class InsertBuilder {
     }
     if (this.returnPreference === "minimal") {
       const responseData = result.data;
-      if (!responseData || !responseData._location) {
+      if (!(responseData == null ? void 0 : responseData._location)) {
         throw new InvalidLocationHeaderError(
           "Location header is required when using return=minimal but was not found in response"
         );
@@ -123,15 +130,23 @@ class InsertBuilder {
       return { data: { ROWID: rowid }, error: void 0 };
     }
     let response = result.data;
-    if (((_b = this.occurrence) == null ? void 0 : _b.baseTable) && shouldUseIds) {
+    if (this.table && shouldUseIds) {
       response = transformResponseFields(
         response,
-        this.occurrence.baseTable,
+        this.table,
         void 0
         // No expand configs for insert
       );
     }
-    const schema = (_d = (_c = this.occurrence) == null ? void 0 : _c.baseTable) == null ? void 0 : _d.schema;
+    let schema;
+    if (this.table) {
+      const baseTableConfig = getBaseTableConfig(this.table);
+      const containerFields = baseTableConfig.containerFields || [];
+      schema = { ...baseTableConfig.schema };
+      for (const containerField of containerFields) {
+        delete schema[containerField];
+      }
+    }
     const validation = await validateSingleResponse(
       response,
       schema,
@@ -151,23 +166,19 @@ class InsertBuilder {
         error: new Error("Insert operation returned null response")
       };
     }
-    const finalData = this.stripODataAnnotationsIfNeeded(
-      validation.data,
-      options
-    );
-    return { data: finalData, error: void 0 };
+    return { data: validation.data, error: void 0 };
   }
+  // biome-ignore lint/suspicious/noExplicitAny: Request body can be any JSON-serializable value
   getRequestConfig() {
-    var _a;
     const tableId = this.getTableId(this.databaseUseEntityIds);
-    const transformedData = ((_a = this.occurrence) == null ? void 0 : _a.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",
       url: `/${this.databaseName}/${tableId}`,
       body: JSON.stringify(transformedData)
     };
   }
-  toRequest(baseUrl) {
+  toRequest(baseUrl, options) {
     const config = this.getRequestConfig();
     const fullUrl = `${baseUrl}${config.url}`;
     const preferHeader = this.returnPreference === "minimal" ? "return=minimal" : "return=representation";
@@ -175,14 +186,18 @@ class InsertBuilder {
       method: config.method,
       headers: {
         "Content-Type": "application/json",
-        Accept: "application/json",
+        Accept: getAcceptHeader(options == null ? void 0 : options.includeODataAnnotations),
         Prefer: preferHeader
       },
       body: config.body
     });
   }
   async processResponse(response, options) {
-    var _a, _b, _c;
+    if (!response.ok) {
+      const tableName = this.table ? getTableName(this.table) : "unknown";
+      const error = await parseErrorResponse(response, response.url || `/${this.databaseName}/${tableName}`);
+      return { data: void 0, error };
+    }
     if (response.status === 204) {
       if (this.returnPreference === "minimal") {
         const locationHeader = response.headers.get("Location") || response.headers.get("location");
@@ -195,6 +210,7 @@ class InsertBuilder {
         );
       }
       return {
+        // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type
         data: {},
         error: void 0
       };
@@ -206,10 +222,11 @@ class InsertBuilder {
     }
     let rawResponse;
     try {
-      rawResponse = await response.json();
+      rawResponse = await safeJsonParse(response);
     } catch (err) {
       if (response.status === 204) {
         return {
+          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type
           data: {},
           error: void 0
         };
@@ -220,20 +237,43 @@ class InsertBuilder {
           name: "ResponseParseError",
           message: `Failed to parse response JSON: ${err instanceof Error ? err.message : "Unknown error"}`,
           timestamp: /* @__PURE__ */ new Date()
+          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for error object
         }
       };
     }
+    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: void 0,
+          error: error instanceof Error ? error : new Error(String(error))
+          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type
+        };
+      }
+    }
     const shouldUseIds = (options == null ? void 0 : options.useEntityIds) ?? this.databaseUseEntityIds;
     let transformedResponse = rawResponse;
-    if (((_a = this.occurrence) == null ? void 0 : _a.baseTable) && shouldUseIds) {
+    if (this.table && shouldUseIds) {
       transformedResponse = transformResponseFields(
         rawResponse,
-        this.occurrence.baseTable,
+        this.table,
         void 0
         // No expand configs for insert
       );
     }
-    const schema = (_c = (_b = this.occurrence) == null ? void 0 : _b.baseTable) == null ? void 0 : _c.schema;
+    let schema;
+    if (this.table) {
+      const baseTableConfig = getBaseTableConfig(this.table);
+      const containerFields = baseTableConfig.containerFields || [];
+      schema = { ...baseTableConfig.schema };
+      for (const containerField of containerFields) {
+        delete schema[containerField];
+      }
+    }
     const validation = await validateSingleResponse(
       transformedResponse,
       schema,
@@ -253,11 +293,7 @@ class InsertBuilder {
         error: new Error("Insert operation returned null response")
       };
     }
-    const finalData = this.stripODataAnnotationsIfNeeded(
-      validation.data,
-      options
-    );
-    return { data: finalData, error: void 0 };
+    return { data: validation.data, error: void 0 };
   }
 }
 export {

package/dist/esm/client/insert-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"insert-builder.js","sources":["../../../src/client/insert-builder.ts"],"sourcesContent":["import type {\n  ExecutionContext,\n  ExecutableBuilder,\n  Result,\n  ODataRecordMetadata,\n  InferSchemaType,\n  ExecuteOptions,\n  ConditionallyWithODataAnnotations,\n} from \"../types\";\nimport type { TableOccurrence } from \"./table-occurrence\";\nimport { validateSingleResponse } from \"../validation\";\nimport { type FFetchOptions } from \"@fetchkit/ffetch\";\nimport {\n  transformFieldNamesToIds,\n  transformTableName,\n  transformResponseFields,\n  getTableIdentifiers,\n} from \"../transform\";\nimport { InvalidLocationHeaderError } from \"../errors\";\n\nexport type InsertOptions = {\n  return?: \"minimal\" | \"representation\";\n};\n\nexport class InsertBuilder<\n  T extends Record<string, any>,\n  Occ extends TableOccurrence<any, any, any, any> | undefined = undefined,\n  ReturnPreference extends \"minimal\" | \"representation\" = \"representation\",\n> implements\n    ExecutableBuilder<\n      ReturnPreference extends \"minimal\" ? { ROWID: number } : T\n    >\n{\n  private occurrence?: Occ;\n  private tableName: string;\n  private databaseName: string;\n  private context: ExecutionContext;\n  private data: Partial<T>;\n  private returnPreference: ReturnPreference;\n\n  private databaseUseEntityIds: boolean;\n\n  constructor(config: {\n    occurrence?: Occ;\n    tableName: string;\n    databaseName: string;\n    context: ExecutionContext;\n    data: Partial<T>;\n    returnPreference?: ReturnPreference;\n    databaseUseEntityIds?: boolean;\n  }) {\n    this.occurrence = config.occurrence;\n    this.tableName = config.tableName;\n    this.databaseName = config.databaseName;\n    this.context = config.context;\n    this.data = config.data;\n    this.returnPreference = (config.returnPreference ||\n      \"representation\") as ReturnPreference;\n    this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;\n  }\n\n  /**\n   * Helper to merge database-level useEntityIds with per-request options\n   */\n  private mergeExecuteOptions(\n    options?: RequestInit & FFetchOptions & ExecuteOptions,\n  ): RequestInit & FFetchOptions & { useEntityIds?: boolean } {\n    // If useEntityIds is not set in options, use the database-level setting\n    return {\n      ...options,\n      useEntityIds: options?.useEntityIds ?? this.databaseUseEntityIds,\n    };\n  }\n\n  /**\n   * Helper to conditionally strip OData annotations based on options\n   */\n  private stripODataAnnotationsIfNeeded<T extends Record<string, any>>(\n    data: T,\n    options?: ExecuteOptions,\n  ): T {\n    // Only include annotations if explicitly requested\n    if (options?.includeODataAnnotations === true) {\n      return data;\n    }\n\n    // Strip OData annotations\n    const { \"@id\": _id, \"@editLink\": _editLink, ...rest } = data;\n    return rest as T;\n  }\n\n  /**\n   * Parse ROWID from Location header\n   * Expected formats:\n   * - contacts(ROWID=4583)\n   * - contacts('some-uuid')\n   */\n  private parseLocationHeader(locationHeader: string | undefined): number {\n    if (!locationHeader) {\n      throw new InvalidLocationHeaderError(\n        \"Location header is required but was not provided\",\n      );\n    }\n\n    // Try to match ROWID=number pattern\n    const rowidMatch = locationHeader.match(/ROWID=(\\d+)/);\n    if (rowidMatch && rowidMatch[1]) {\n      return parseInt(rowidMatch[1], 10);\n    }\n\n    // Try to extract value from parentheses and parse as number\n    const parenMatch = locationHeader.match(/\\(['\"]?([^'\"]+)['\"]?\\)/);\n    if (parenMatch && parenMatch[1]) {\n      const value = parenMatch[1];\n      const numValue = parseInt(value, 10);\n      if (!isNaN(numValue)) {\n        return numValue;\n      }\n    }\n\n    throw new InvalidLocationHeaderError(\n      `Could not extract ROWID from Location header: ${locationHeader}`,\n      locationHeader,\n    );\n  }\n\n  /**\n   * Gets the table ID (FMTID) if using entity IDs, otherwise returns the table name\n   * @param useEntityIds - Optional override for entity ID usage\n   */\n  private getTableId(useEntityIds?: boolean): string {\n    if (!this.occurrence) {\n      return this.tableName;\n    }\n\n    const contextDefault = this.context._getUseEntityIds?.() ?? false;\n    const shouldUseIds = useEntityIds ?? contextDefault;\n\n    if (shouldUseIds) {\n      const identifiers = getTableIdentifiers(this.occurrence);\n      if (!identifiers.id) {\n        throw new Error(\n          `useEntityIds is true but TableOccurrence \"${identifiers.name}\" does not have an fmtId defined`\n        );\n      }\n      return identifiers.id;\n    }\n\n    return this.occurrence.getTableName();\n  }\n\n  async execute<EO extends ExecuteOptions>(\n    options?: RequestInit & FFetchOptions & EO,\n  ): Promise<\n    Result<\n      ReturnPreference extends \"minimal\"\n        ? { ROWID: number }\n        : ConditionallyWithODataAnnotations<\n            T,\n            EO[\"includeODataAnnotations\"] extends true ? true : false\n          >\n    >\n  > {\n    // Merge database-level useEntityIds with per-request options\n    const mergedOptions = this.mergeExecuteOptions(options);\n    \n    // Get table identifier with override support\n    const tableId = this.getTableId(mergedOptions.useEntityIds);\n    const url = `/${this.databaseName}/${tableId}`;\n\n    // Transform field names to FMFIDs if using entity IDs\n    // Only transform if useEntityIds resolves to true (respects per-request override)\n    const shouldUseIds = mergedOptions.useEntityIds ?? false;\n    \n    const transformedData = this.occurrence?.baseTable && shouldUseIds\n      ? transformFieldNamesToIds(this.data, this.occurrence.baseTable)\n      : this.data;\n\n    // Set Prefer header based on return preference\n    const preferHeader =\n      this.returnPreference === \"minimal\"\n        ? \"return=minimal\"\n        : \"return=representation\";\n\n    // Make POST request with JSON body\n    const result = await this.context._makeRequest<any>(url, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Prefer: preferHeader,\n        ...((mergedOptions as any)?.headers || {}),\n      },\n      body: JSON.stringify(transformedData),\n      ...mergedOptions,\n    });\n\n    if (result.error) {\n      return { data: undefined, error: result.error };\n    }\n\n    // Handle return=minimal case\n    if (this.returnPreference === \"minimal\") {\n      // The response should be empty (204 No Content)\n      // _makeRequest will return { _location: string } when there's a Location header\n      const responseData = result.data as any;\n\n      if (!responseData || !responseData._location) {\n        throw new InvalidLocationHeaderError(\n          \"Location header is required when using return=minimal but was not found in response\",\n        );\n      }\n\n      const rowid = this.parseLocationHeader(responseData._location);\n      return { data: { ROWID: rowid } as any, error: undefined };\n    }\n\n    let response = result.data;\n\n    // Transform response field IDs back to names if using entity IDs\n    // Only transform if useEntityIds resolves to true (respects per-request override)\n    if (this.occurrence?.baseTable && shouldUseIds) {\n      response = transformResponseFields(\n        response,\n        this.occurrence.baseTable,\n        undefined, // No expand configs for insert\n      );\n    }\n\n    // Get schema from occurrence if available\n    const schema = this.occurrence?.baseTable?.schema;\n\n    // Validate the response (FileMaker returns the created record)\n    const validation = await validateSingleResponse<T>(\n      response,\n      schema,\n      undefined, // No selected fields for insert\n      undefined, // No expand configs\n      \"exact\", // Expect exactly one record\n    );\n\n    if (!validation.valid) {\n      return { data: undefined, error: validation.error };\n    }\n\n    // Handle null response (shouldn't happen for insert, but handle it)\n    if (validation.data === null) {\n      return {\n        data: undefined,\n        error: new Error(\"Insert operation returned null response\"),\n      };\n    }\n\n    // Strip OData annotations unless explicitly requested\n    const finalData = this.stripODataAnnotationsIfNeeded(\n      validation.data,\n      options,\n    );\n\n    return { data: finalData as any, error: undefined };\n  }\n\n  getRequestConfig(): { method: string; url: string; body?: any } {\n    // For batch operations, use database-level setting (no per-request override available here)\n    const tableId = this.getTableId(this.databaseUseEntityIds);\n\n    // Transform field names to FMFIDs if using entity IDs\n    const transformedData = this.occurrence?.baseTable && this.databaseUseEntityIds\n      ? transformFieldNamesToIds(this.data, this.occurrence.baseTable)\n      : this.data;\n\n    return {\n      method: \"POST\",\n      url: `/${this.databaseName}/${tableId}`,\n      body: JSON.stringify(transformedData),\n    };\n  }\n\n  toRequest(baseUrl: string): Request {\n    const config = this.getRequestConfig();\n    const fullUrl = `${baseUrl}${config.url}`;\n\n    // Set Prefer header based on return preference\n    const preferHeader =\n      this.returnPreference === \"minimal\"\n        ? \"return=minimal\"\n        : \"return=representation\";\n\n    return new Request(fullUrl, {\n      method: config.method,\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Accept: \"application/json\",\n        Prefer: preferHeader,\n      },\n      body: config.body,\n    });\n  }\n\n  async processResponse(\n    response: Response,\n    options?: ExecuteOptions,\n  ): Promise<\n    Result<ReturnPreference extends \"minimal\" ? { ROWID: number } : T>\n  > {\n    // Handle 204 No Content (common in batch/changeset operations)\n    // FileMaker uses return=minimal for changeset operations regardless of Prefer header\n    if (response.status === 204) {\n      // Check for Location header (for return=minimal)\n      if (this.returnPreference === \"minimal\") {\n        const locationHeader =\n          response.headers.get(\"Location\") || response.headers.get(\"location\");\n        if (locationHeader) {\n          const rowid = this.parseLocationHeader(locationHeader);\n          return { data: { ROWID: rowid } as any, error: undefined };\n        }\n        throw new InvalidLocationHeaderError(\n          \"Location header is required when using return=minimal but was not found in response\",\n        );\n      }\n\n      // For 204 responses without return=minimal, FileMaker doesn't return the created entity\n      // This is valid OData behavior for changeset operations\n      // We return a success indicator but no actual data\n      return {\n        data: {} as any,\n        error: undefined,\n      };\n    }\n\n    // If we expected return=minimal but got a body, that's unexpected\n    if (this.returnPreference === \"minimal\") {\n      throw new InvalidLocationHeaderError(\n        \"Expected 204 No Content for return=minimal, but received response with body\",\n      );\n    }\n\n    let rawResponse;\n    try {\n      rawResponse = await response.json();\n    } catch (err) {\n      // If parsing fails with 204, handle it gracefully\n      if (response.status === 204) {\n        return {\n          data: {} as any,\n          error: undefined,\n        };\n      }\n      return {\n        data: undefined,\n        error: {\n          name: \"ResponseParseError\",\n          message: `Failed to parse response JSON: ${err instanceof Error ? err.message : \"Unknown error\"}`,\n          timestamp: new Date(),\n        } as any,\n      };\n    }\n\n    // Transform response field IDs back to names if using entity IDs\n    // Only transform if useEntityIds resolves to true (respects per-request override)\n    const shouldUseIds = options?.useEntityIds ?? this.databaseUseEntityIds;\n    \n    let transformedResponse = rawResponse;\n    if (this.occurrence?.baseTable && shouldUseIds) {\n      transformedResponse = transformResponseFields(\n        rawResponse,\n        this.occurrence.baseTable,\n        undefined, // No expand configs for insert\n      );\n    }\n\n    // Get schema from occurrence if available\n    const schema = this.occurrence?.baseTable?.schema;\n\n    // Validate the response (FileMaker returns the created record)\n    const validation = await validateSingleResponse<T>(\n      transformedResponse,\n      schema,\n      undefined, // No selected fields for insert\n      undefined, // No expand configs\n      \"exact\", // Expect exactly one record\n    );\n\n    if (!validation.valid) {\n      return { data: undefined, error: validation.error };\n    }\n\n    // Handle null response (shouldn't happen for insert, but handle it)\n    if (validation.data === null) {\n      return {\n        data: undefined,\n        error: new Error(\"Insert operation returned null response\"),\n      };\n    }\n\n    // Strip OData annotations unless explicitly requested\n    const finalData = this.stripODataAnnotationsIfNeeded(\n      validation.data,\n      options,\n    );\n\n    return { data: finalData as any, error: undefined };\n  }\n}\n"],"names":[],"mappings":";;;;;;AAwBO,MAAM,cAQb;AAAA,EAUE,YAAY,QAQT;AAjBK;AACA;AACA;AACA;AACA;AACA;AAEA;AAWN,SAAK,aAAa,OAAO;AACzB,SAAK,YAAY,OAAO;AACxB,SAAK,eAAe,OAAO;AAC3B,SAAK,UAAU,OAAO;AACtB,SAAK,OAAO,OAAO;AACd,SAAA,mBAAoB,OAAO,oBAC9B;AACG,SAAA,uBAAuB,OAAO,wBAAwB;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMrD,oBACN,SAC0D;AAEnD,WAAA;AAAA,MACL,GAAG;AAAA,MACH,eAAc,mCAAS,iBAAgB,KAAK;AAAA,IAC9C;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMM,8BACN,MACA,SACG;AAEC,SAAA,mCAAS,6BAA4B,MAAM;AACtC,aAAA;AAAA,IAAA;AAIT,UAAM,EAAE,OAAO,KAAK,aAAa,WAAW,GAAG,SAAS;AACjD,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASD,oBAAoB,gBAA4C;AACtE,QAAI,CAAC,gBAAgB;AACnB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IAAA;AAII,UAAA,aAAa,eAAe,MAAM,aAAa;AACjD,QAAA,cAAc,WAAW,CAAC,GAAG;AAC/B,aAAO,SAAS,WAAW,CAAC,GAAG,EAAE;AAAA,IAAA;AAI7B,UAAA,aAAa,eAAe,MAAM,wBAAwB;AAC5D,QAAA,cAAc,WAAW,CAAC,GAAG;AACzB,YAAA,QAAQ,WAAW,CAAC;AACpB,YAAA,WAAW,SAAS,OAAO,EAAE;AAC/B,UAAA,CAAC,MAAM,QAAQ,GAAG;AACb,eAAA;AAAA,MAAA;AAAA,IACT;AAGF,UAAM,IAAI;AAAA,MACR,iDAAiD,cAAc;AAAA,MAC/D;AAAA,IACF;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOM,WAAW,cAAgC;;AAC7C,QAAA,CAAC,KAAK,YAAY;AACpB,aAAO,KAAK;AAAA,IAAA;AAGd,UAAM,mBAAiB,gBAAK,SAAQ,qBAAb,gCAAqC;AAC5D,UAAM,eAAe,gBAAgB;AAErC,QAAI,cAAc;AACV,YAAA,cAAc,oBAAoB,KAAK,UAAU;AACnD,UAAA,CAAC,YAAY,IAAI;AACnB,cAAM,IAAI;AAAA,UACR,6CAA6C,YAAY,IAAI;AAAA,QAC/D;AAAA,MAAA;AAEF,aAAO,YAAY;AAAA,IAAA;AAGd,WAAA,KAAK,WAAW,aAAa;AAAA,EAAA;AAAA,EAGtC,MAAM,QACJ,SAUA;;AAEM,UAAA,gBAAgB,KAAK,oBAAoB,OAAO;AAGtD,UAAM,UAAU,KAAK,WAAW,cAAc,YAAY;AAC1D,UAAM,MAAM,IAAI,KAAK,YAAY,IAAI,OAAO;AAItC,UAAA,eAAe,cAAc,gBAAgB;AAEnD,UAAM,oBAAkB,UAAK,eAAL,mBAAiB,cAAa,eAClD,yBAAyB,KAAK,MAAM,KAAK,WAAW,SAAS,IAC7D,KAAK;AAGT,UAAM,eACJ,KAAK,qBAAqB,YACtB,mBACA;AAGN,UAAM,SAAS,MAAM,KAAK,QAAQ,aAAkB,KAAK;AAAA,MACvD,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,QAAQ;AAAA,QACR,IAAK,+CAAuB,YAAW,CAAA;AAAA,MACzC;AAAA,MACA,MAAM,KAAK,UAAU,eAAe;AAAA,MACpC,GAAG;AAAA,IAAA,CACJ;AAED,QAAI,OAAO,OAAO;AAChB,aAAO,EAAE,MAAM,QAAW,OAAO,OAAO,MAAM;AAAA,IAAA;AAI5C,QAAA,KAAK,qBAAqB,WAAW;AAGvC,YAAM,eAAe,OAAO;AAE5B,UAAI,CAAC,gBAAgB,CAAC,aAAa,WAAW;AAC5C,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MAAA;AAGF,YAAM,QAAQ,KAAK,oBAAoB,aAAa,SAAS;AAC7D,aAAO,EAAE,MAAM,EAAE,OAAO,MAAM,GAAU,OAAO,OAAU;AAAA,IAAA;AAG3D,QAAI,WAAW,OAAO;AAIlB,UAAA,UAAK,eAAL,mBAAiB,cAAa,cAAc;AACnC,iBAAA;AAAA,QACT;AAAA,QACA,KAAK,WAAW;AAAA,QAChB;AAAA;AAAA,MACF;AAAA,IAAA;AAII,UAAA,UAAS,gBAAK,eAAL,mBAAiB,cAAjB,mBAA4B;AAG3C,UAAM,aAAa,MAAM;AAAA,MACvB;AAAA,MACA;AAAA,MACA;AAAA;AAAA,MACA;AAAA;AAAA,MACA;AAAA;AAAA,IACF;AAEI,QAAA,CAAC,WAAW,OAAO;AACrB,aAAO,EAAE,MAAM,QAAW,OAAO,WAAW,MAAM;AAAA,IAAA;AAIhD,QAAA,WAAW,SAAS,MAAM;AACrB,aAAA;AAAA,QACL,MAAM;AAAA,QACN,OAAO,IAAI,MAAM,yCAAyC;AAAA,MAC5D;AAAA,IAAA;AAIF,UAAM,YAAY,KAAK;AAAA,MACrB,WAAW;AAAA,MACX;AAAA,IACF;AAEA,WAAO,EAAE,MAAM,WAAkB,OAAO,OAAU;AAAA,EAAA;AAAA,EAGpD,mBAAgE;;AAE9D,UAAM,UAAU,KAAK,WAAW,KAAK,oBAAoB;AAGzD,UAAM,oBAAkB,UAAK,eAAL,mBAAiB,cAAa,KAAK,uBACvD,yBAAyB,KAAK,MAAM,KAAK,WAAW,SAAS,IAC7D,KAAK;AAEF,WAAA;AAAA,MACL,QAAQ;AAAA,MACR,KAAK,IAAI,KAAK,YAAY,IAAI,OAAO;AAAA,MACrC,MAAM,KAAK,UAAU,eAAe;AAAA,IACtC;AAAA,EAAA;AAAA,EAGF,UAAU,SAA0B;AAC5B,UAAA,SAAS,KAAK,iBAAiB;AACrC,UAAM,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG;AAGvC,UAAM,eACJ,KAAK,qBAAqB,YACtB,mBACA;AAEC,WAAA,IAAI,QAAQ,SAAS;AAAA,MAC1B,QAAQ,OAAO;AAAA,MACf,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,QAAQ;AAAA,QACR,QAAQ;AAAA,MACV;AAAA,MACA,MAAM,OAAO;AAAA,IAAA,CACd;AAAA,EAAA;AAAA,EAGH,MAAM,gBACJ,UACA,SAGA;;AAGI,QAAA,SAAS,WAAW,KAAK;AAEvB,UAAA,KAAK,qBAAqB,WAAW;AACjC,cAAA,iBACJ,SAAS,QAAQ,IAAI,UAAU,KAAK,SAAS,QAAQ,IAAI,UAAU;AACrE,YAAI,gBAAgB;AACZ,gBAAA,QAAQ,KAAK,oBAAoB,cAAc;AACrD,iBAAO,EAAE,MAAM,EAAE,OAAO,MAAM,GAAU,OAAO,OAAU;AAAA,QAAA;AAE3D,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MAAA;AAMK,aAAA;AAAA,QACL,MAAM,CAAC;AAAA,QACP,OAAO;AAAA,MACT;AAAA,IAAA;AAIE,QAAA,KAAK,qBAAqB,WAAW;AACvC,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IAAA;AAGE,QAAA;AACA,QAAA;AACY,oBAAA,MAAM,SAAS,KAAK;AAAA,aAC3B,KAAK;AAER,UAAA,SAAS,WAAW,KAAK;AACpB,eAAA;AAAA,UACL,MAAM,CAAC;AAAA,UACP,OAAO;AAAA,QACT;AAAA,MAAA;AAEK,aAAA;AAAA,QACL,MAAM;AAAA,QACN,OAAO;AAAA,UACL,MAAM;AAAA,UACN,SAAS,kCAAkC,eAAe,QAAQ,IAAI,UAAU,eAAe;AAAA,UAC/F,+BAAe,KAAK;AAAA,QAAA;AAAA,MAExB;AAAA,IAAA;AAKI,UAAA,gBAAe,mCAAS,iBAAgB,KAAK;AAEnD,QAAI,sBAAsB;AACtB,UAAA,UAAK,eAAL,mBAAiB,cAAa,cAAc;AACxB,4BAAA;AAAA,QACpB;AAAA,QACA,KAAK,WAAW;AAAA,QAChB;AAAA;AAAA,MACF;AAAA,IAAA;AAII,UAAA,UAAS,gBAAK,eAAL,mBAAiB,cAAjB,mBAA4B;AAG3C,UAAM,aAAa,MAAM;AAAA,MACvB;AAAA,MACA;AAAA,MACA;AAAA;AAAA,MACA;AAAA;AAAA,MACA;AAAA;AAAA,IACF;AAEI,QAAA,CAAC,WAAW,OAAO;AACrB,aAAO,EAAE,MAAM,QAAW,OAAO,WAAW,MAAM;AAAA,IAAA;AAIhD,QAAA,WAAW,SAAS,MAAM;AACrB,aAAA;AAAA,QACL,MAAM;AAAA,QACN,OAAO,IAAI,MAAM,yCAAyC;AAAA,MAC5D;AAAA,IAAA;AAIF,UAAM,YAAY,KAAK;AAAA,MACrB,WAAW;AAAA,MACX;AAAA,IACF;AAEA,WAAO,EAAE,MAAM,WAAkB,OAAO,OAAU;AAAA,EAAA;AAEtD;"}
+{"version":3,"file":"insert-builder.js","sources":["../../../src/client/insert-builder.ts"],"sourcesContent":["import type { FFetchOptions } from \"@fetchkit/ffetch\";\nimport { InvalidLocationHeaderError } from \"../errors\";\nimport type { FMTable } from \"../orm/table\";\nimport { getBaseTableConfig, getTableId as getTableIdHelper, getTableName, isUsingEntityIds } from \"../orm/table\";\nimport { transformFieldNamesToIds, transformResponseFields } from \"../transform\";\nimport type {\n  ConditionallyWithODataAnnotations,\n  ExecutableBuilder,\n  ExecuteMethodOptions,\n  ExecuteOptions,\n  ExecutionContext,\n  Result,\n} from \"../types\";\nimport { getAcceptHeader } from \"../types\";\nimport { validateAndTransformInput, validateSingleResponse } from \"../validation\";\nimport { parseErrorResponse } from \"./error-parser\";\nimport { safeJsonParse } from \"./sanitize-json\";\n\nconst ROWID_MATCH_REGEX = /ROWID=(\\d+)/;\nconst PAREN_VALUE_REGEX = /\\(['\"]?([^'\"]+)['\"]?\\)/;\n\nexport interface InsertOptions {\n  return?: \"minimal\" | \"representation\";\n}\n\nimport type { InferSchemaOutputFromFMTable } from \"../orm/table\";\n\nexport class InsertBuilder<\n  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration\n  Occ extends FMTable<any, any> | undefined = undefined,\n  ReturnPreference extends \"minimal\" | \"representation\" = \"representation\",\n> implements\n    ExecutableBuilder<\n      ReturnPreference extends \"minimal\" ? { ROWID: number } : InferSchemaOutputFromFMTable<NonNullable<Occ>>\n    >\n{\n  private readonly table?: Occ;\n  private readonly databaseName: string;\n  private readonly context: ExecutionContext;\n  private readonly data: Partial<InferSchemaOutputFromFMTable<NonNullable<Occ>>>;\n  private readonly returnPreference: ReturnPreference;\n\n  private readonly databaseUseEntityIds: boolean;\n  private readonly databaseIncludeSpecialColumns: boolean;\n\n  constructor(config: {\n    occurrence?: Occ;\n    databaseName: string;\n    context: ExecutionContext;\n    data: Partial<InferSchemaOutputFromFMTable<NonNullable<Occ>>>;\n    returnPreference?: ReturnPreference;\n    databaseUseEntityIds?: boolean;\n    databaseIncludeSpecialColumns?: boolean;\n  }) {\n    this.table = config.occurrence;\n    this.databaseName = config.databaseName;\n    this.context = config.context;\n    this.data = config.data;\n    this.returnPreference = (config.returnPreference || \"representation\") as ReturnPreference;\n    this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;\n    this.databaseIncludeSpecialColumns = config.databaseIncludeSpecialColumns ?? false;\n  }\n\n  /**\n   * Helper to merge database-level useEntityIds with per-request options\n   */\n  private mergeExecuteOptions(\n    options?: RequestInit & FFetchOptions & ExecuteOptions,\n  ): RequestInit & FFetchOptions & { useEntityIds?: boolean } {\n    // If useEntityIds is not set in options, use the database-level setting\n    return {\n      ...options,\n      useEntityIds: options?.useEntityIds ?? this.databaseUseEntityIds,\n    };\n  }\n\n  /**\n   * Parse ROWID from Location header\n   * Expected formats:\n   * - contacts(ROWID=4583)\n   * - contacts('some-uuid')\n   */\n  private parseLocationHeader(locationHeader: string | undefined): number {\n    if (!locationHeader) {\n      throw new InvalidLocationHeaderError(\"Location header is required but was not provided\");\n    }\n\n    // Try to match ROWID=number pattern\n    const rowidMatch = locationHeader.match(ROWID_MATCH_REGEX);\n    if (rowidMatch?.[1]) {\n      return Number.parseInt(rowidMatch[1], 10);\n    }\n\n    // Try to extract value from parentheses and parse as number\n    const parenMatch = locationHeader.match(PAREN_VALUE_REGEX);\n    if (parenMatch?.[1]) {\n      const value = parenMatch[1];\n      const numValue = Number.parseInt(value, 10);\n      if (!Number.isNaN(numValue)) {\n        return numValue;\n      }\n    }\n\n    throw new InvalidLocationHeaderError(\n      `Could not extract ROWID from Location header: ${locationHeader}`,\n      locationHeader,\n    );\n  }\n\n  /**\n   * Gets the table ID (FMTID) if using entity IDs, otherwise returns the table name\n   * @param useEntityIds - Optional override for entity ID usage\n   */\n  private getTableId(useEntityIds?: boolean): string {\n    if (!this.table) {\n      throw new Error(\"Table occurrence is required\");\n    }\n\n    const contextDefault = this.context._getUseEntityIds?.() ?? false;\n    const shouldUseIds = useEntityIds ?? contextDefault;\n\n    if (shouldUseIds) {\n      if (!isUsingEntityIds(this.table)) {\n        throw new Error(\n          `useEntityIds is true but table \"${getTableName(this.table)}\" does not have entity IDs configured`,\n        );\n      }\n      return getTableIdHelper(this.table);\n    }\n\n    return getTableName(this.table);\n  }\n\n  async execute<EO extends ExecuteOptions>(\n    options?: ExecuteMethodOptions<EO>,\n  ): Promise<\n    Result<\n      ReturnPreference extends \"minimal\"\n        ? { ROWID: number }\n        : ConditionallyWithODataAnnotations<\n            InferSchemaOutputFromFMTable<NonNullable<Occ>>,\n            EO[\"includeODataAnnotations\"] extends true ? true : false\n          >\n    >\n  > {\n    // Merge database-level useEntityIds with per-request options\n    const mergedOptions = this.mergeExecuteOptions(options);\n\n    // Get table identifier with override support\n    const tableId = this.getTableId(mergedOptions.useEntityIds);\n    const url = `/${this.databaseName}/${tableId}`;\n\n    // Validate and transform input data using input validators (writeValidators)\n    let validatedData = this.data;\n    if (this.table) {\n      const baseTableConfig = getBaseTableConfig(this.table);\n      const inputSchema = baseTableConfig.inputSchema;\n\n      try {\n        validatedData = await validateAndTransformInput(this.data, inputSchema);\n      } catch (error) {\n        // If validation fails, return error immediately\n        return {\n          data: undefined,\n          error: error instanceof Error ? error : new Error(String(error)),\n          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type\n        } as any;\n      }\n    }\n\n    // Transform field names to FMFIDs if using entity IDs\n    // Only transform if useEntityIds resolves to true (respects per-request override)\n    const shouldUseIds = mergedOptions.useEntityIds ?? false;\n\n    const transformedData =\n      this.table && shouldUseIds ? transformFieldNamesToIds(validatedData, this.table) : validatedData;\n\n    // Set Prefer header based on return preference\n    const preferHeader = this.returnPreference === \"minimal\" ? \"return=minimal\" : \"return=representation\";\n\n    // Make POST request with JSON body\n    // biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API\n    const result = await this.context._makeRequest<any>(url, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Prefer: preferHeader,\n        // biome-ignore lint/suspicious/noExplicitAny: Type assertion for headers object\n        ...((mergedOptions as any)?.headers || {}),\n      },\n      body: JSON.stringify(transformedData),\n      ...mergedOptions,\n    });\n\n    if (result.error) {\n      return { data: undefined, error: result.error };\n    }\n\n    // Handle return=minimal case\n    if (this.returnPreference === \"minimal\") {\n      // The response should be empty (204 No Content)\n      // _makeRequest will return { _location: string } when there's a Location header\n      // biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API\n      const responseData = result.data as any;\n\n      if (!responseData?._location) {\n        throw new InvalidLocationHeaderError(\n          \"Location header is required when using return=minimal but was not found in response\",\n        );\n      }\n\n      const rowid = this.parseLocationHeader(responseData._location);\n      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type\n      return { data: { ROWID: rowid } as any, error: undefined };\n    }\n\n    let response = result.data;\n\n    // Transform response field IDs back to names if using entity IDs\n    // Only transform if useEntityIds resolves to true (respects per-request override)\n    if (this.table && shouldUseIds) {\n      response = transformResponseFields(\n        response,\n        this.table,\n        undefined, // No expand configs for insert\n      );\n    }\n\n    // Get schema from table if available, excluding container fields\n    // biome-ignore lint/suspicious/noExplicitAny: Dynamic schema shape from table configuration\n    let schema: Record<string, any> | undefined;\n    if (this.table) {\n      const baseTableConfig = getBaseTableConfig(this.table);\n      const containerFields = baseTableConfig.containerFields || [];\n\n      // Filter out container fields from schema\n      schema = { ...baseTableConfig.schema };\n      for (const containerField of containerFields) {\n        delete schema[containerField as string];\n      }\n    }\n\n    // Validate the response (FileMaker returns the created record)\n    const validation = await validateSingleResponse<InferSchemaOutputFromFMTable<NonNullable<Occ>>>(\n      response,\n      schema,\n      undefined, // No selected fields for insert\n      undefined, // No expand configs\n      \"exact\", // Expect exactly one record\n    );\n\n    if (!validation.valid) {\n      return { data: undefined, error: validation.error };\n    }\n\n    // Handle null response (shouldn't happen for insert, but handle it)\n    if (validation.data === null) {\n      return {\n        data: undefined,\n        error: new Error(\"Insert operation returned null response\"),\n      };\n    }\n\n    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type\n    return { data: validation.data as any, error: undefined };\n  }\n\n  // biome-ignore lint/suspicious/noExplicitAny: Request body can be any JSON-serializable value\n  getRequestConfig(): { method: string; url: string; body?: any } {\n    // For batch operations, use database-level setting (no per-request override available here)\n    // Note: Input validation happens in execute() and processResponse() for batch operations\n    const tableId = this.getTableId(this.databaseUseEntityIds);\n\n    // Transform field names to FMFIDs if using entity IDs\n    const transformedData =\n      this.table && this.databaseUseEntityIds ? transformFieldNamesToIds(this.data, this.table) : this.data;\n\n    return {\n      method: \"POST\",\n      url: `/${this.databaseName}/${tableId}`,\n      body: JSON.stringify(transformedData),\n    };\n  }\n\n  toRequest(baseUrl: string, options?: ExecuteOptions): Request {\n    const config = this.getRequestConfig();\n    const fullUrl = `${baseUrl}${config.url}`;\n\n    // Set Prefer header based on return preference\n    const preferHeader = this.returnPreference === \"minimal\" ? \"return=minimal\" : \"return=representation\";\n\n    return new Request(fullUrl, {\n      method: config.method,\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Accept: getAcceptHeader(options?.includeODataAnnotations),\n        Prefer: preferHeader,\n      },\n      body: config.body,\n    });\n  }\n\n  async processResponse(\n    response: Response,\n    options?: ExecuteOptions,\n  ): Promise<\n    Result<ReturnPreference extends \"minimal\" ? { ROWID: number } : InferSchemaOutputFromFMTable<NonNullable<Occ>>>\n  > {\n    // Check for error responses (important for batch operations)\n    if (!response.ok) {\n      const tableName = this.table ? getTableName(this.table) : \"unknown\";\n      const error = await parseErrorResponse(response, response.url || `/${this.databaseName}/${tableName}`);\n      return { data: undefined, error };\n    }\n\n    // Handle 204 No Content (common in batch/changeset operations)\n    // FileMaker uses return=minimal for changeset operations regardless of Prefer header\n    if (response.status === 204) {\n      // Check for Location header (for return=minimal)\n      if (this.returnPreference === \"minimal\") {\n        const locationHeader = response.headers.get(\"Location\") || response.headers.get(\"location\");\n        if (locationHeader) {\n          const rowid = this.parseLocationHeader(locationHeader);\n          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type\n          return { data: { ROWID: rowid } as any, error: undefined };\n        }\n        throw new InvalidLocationHeaderError(\n          \"Location header is required when using return=minimal but was not found in response\",\n        );\n      }\n\n      // For 204 responses without return=minimal, FileMaker doesn't return the created entity\n      // This is valid OData behavior for changeset operations\n      // We return a success indicator but no actual data\n      return {\n        // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type\n        data: {} as any,\n        error: undefined,\n      };\n    }\n\n    // If we expected return=minimal but got a body, that's unexpected\n    if (this.returnPreference === \"minimal\") {\n      throw new InvalidLocationHeaderError(\n        \"Expected 204 No Content for return=minimal, but received response with body\",\n      );\n    }\n\n    // Use safeJsonParse to handle FileMaker's invalid JSON with unquoted ? values\n    let rawResponse: unknown;\n    try {\n      rawResponse = await safeJsonParse(response);\n    } catch (err) {\n      // If parsing fails with 204, handle it gracefully\n      if (response.status === 204) {\n        return {\n          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type\n          data: {} as any,\n          error: undefined,\n        };\n      }\n      return {\n        data: undefined,\n        error: {\n          name: \"ResponseParseError\",\n          message: `Failed to parse response JSON: ${err instanceof Error ? err.message : \"Unknown error\"}`,\n          timestamp: new Date(),\n          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for error object\n        } as any,\n      };\n    }\n\n    // Validate and transform input data using input validators (writeValidators)\n    // This is needed for processResponse because it's called from batch operations\n    // where the data hasn't been validated yet\n    let _validatedData = this.data;\n    if (this.table) {\n      const baseTableConfig = getBaseTableConfig(this.table);\n      const inputSchema = baseTableConfig.inputSchema;\n      try {\n        _validatedData = await validateAndTransformInput(this.data, inputSchema);\n      } catch (error) {\n        return {\n          data: undefined,\n          error: error instanceof Error ? error : new Error(String(error)),\n          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type\n        } as any;\n      }\n    }\n\n    // Transform response field IDs back to names if using entity IDs\n    // Only transform if useEntityIds resolves to true (respects per-request override)\n    const shouldUseIds = options?.useEntityIds ?? this.databaseUseEntityIds;\n\n    let transformedResponse = rawResponse;\n    if (this.table && shouldUseIds) {\n      transformedResponse = transformResponseFields(\n        rawResponse,\n        this.table,\n        undefined, // No expand configs for insert\n      );\n    }\n\n    // Get schema from table if available, excluding container fields\n    // biome-ignore lint/suspicious/noExplicitAny: Dynamic schema shape from table configuration\n    let schema: Record<string, any> | undefined;\n    if (this.table) {\n      const baseTableConfig = getBaseTableConfig(this.table);\n      const containerFields = baseTableConfig.containerFields || [];\n\n      // Filter out container fields from schema\n      schema = { ...baseTableConfig.schema };\n      for (const containerField of containerFields) {\n        delete schema[containerField as string];\n      }\n    }\n\n    // Validate the response (FileMaker returns the created record)\n    const validation = await validateSingleResponse<InferSchemaOutputFromFMTable<NonNullable<Occ>>>(\n      transformedResponse,\n      schema,\n      undefined, // No selected fields for insert\n      undefined, // No expand configs\n      \"exact\", // Expect exactly one record\n    );\n\n    if (!validation.valid) {\n      return { data: undefined, error: validation.error };\n    }\n\n    // Handle null response (shouldn't happen for insert, but handle it)\n    if (validation.data === null) {\n      return {\n        data: undefined,\n        error: new Error(\"Insert operation returned null response\"),\n      };\n    }\n\n    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type\n    return { data: validation.data as any, error: undefined };\n  }\n}\n"],"names":["getTableIdHelper"],"mappings":"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"}

package/dist/esm/client/query/expand-builder.d.ts

@@ -0,0 +1,35 @@
+import { QueryOptions } from 'odata-query';
+import { FMTable } from '../../orm/table.js';
+import { ExpandValidationConfig } from '../../validation.js';
+/**
+ * Internal type for expand configuration
+ */
+export interface 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 declare class ExpandBuilder {
+    private readonly useEntityIds;
+    constructor(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;
+    /**
+     * Builds a single expand string with its options.
+     */
+    private buildSingleExpand;
+    /**
+     * Builds expand validation configs from internal expand configurations.
+     * These are used to validate expanded navigation properties.
+     */
+    buildValidationConfigs(configs: ExpandConfig[]): ExpandValidationConfig[];
+}

package/dist/esm/client/query/index.d.ts

@@ -0,0 +1,4 @@
+/** biome-ignore-all lint/performance/noBarrelFile: Re-exporting QueryBuilder and types */
+export type { ExpandConfig } from './expand-builder.js';
+export type { ExpandedRelations, QueryReturnType, TypeSafeOrderBy, } from './query-builder.js';
+export { QueryBuilder } from './query-builder.js';

package/dist/esm/client/query/query-builder.d.ts

@@ -0,0 +1,132 @@
+import { Column } from '../../orm/column.js';
+import { FilterExpression, OrderByExpression } from '../../orm/operators.js';
+import { ExtractTableName, FMTable, InferSchemaOutputFromFMTable, ValidExpandTarget } from '../../orm/table.js';
+import { ConditionallyWithODataAnnotations, ConditionallyWithSpecialColumns, ExecutableBuilder, ExecuteMethodOptions, ExecuteOptions, ExecutionContext, NormalizeIncludeSpecialColumns, Result } from '../../types.js';
+import { ExpandedRelations } from '../builders/index.js';
+import { QueryReturnType, SystemColumnsOption, TypeSafeOrderBy } from './types.js';
+export type { ExpandedRelations } from '../builders/index.js';
+export type { QueryReturnType, SystemColumnsOption, TypeSafeOrderBy } from './types.js';
+export declare class QueryBuilder<Occ extends FMTable<any, any>, Selected extends keyof InferSchemaOutputFromFMTable<Occ> | Record<string, Column<any, any, ExtractTableName<Occ>>> = keyof InferSchemaOutputFromFMTable<Occ>, SingleMode extends "exact" | "maybe" | false = false, IsCount extends boolean = false, Expands extends ExpandedRelations = {}, DatabaseIncludeSpecialColumns extends boolean = false, SystemCols extends SystemColumnsOption | undefined = undefined> implements ExecutableBuilder<QueryReturnType<InferSchemaOutputFromFMTable<Occ>, Selected, SingleMode, IsCount, Expands, SystemCols>> {
+    private queryOptions;
+    private expandConfigs;
+    private singleMode;
+    private isCountMode;
+    private readonly occurrence;
+    private readonly databaseName;
+    private readonly context;
+    private navigation?;
+    private readonly databaseUseEntityIds;
+    private readonly databaseIncludeSpecialColumns;
+    private readonly expandBuilder;
+    private urlBuilder;
+    private fieldMapping?;
+    private systemColumns?;
+    private readonly logger;
+    constructor(config: {
+        occurrence: Occ;
+        databaseName: string;
+        context: ExecutionContext;
+        databaseUseEntityIds?: boolean;
+        databaseIncludeSpecialColumns?: boolean;
+    });
+    /**
+     * Helper to merge database-level useEntityIds and includeSpecialColumns with per-request options
+     */
+    private mergeExecuteOptions;
+    /**
+     * Creates a new QueryBuilder with modified configuration.
+     * Used by single(), maybeSingle(), count(), and select() to create new instances.
+     */
+    private cloneWithChanges;
+    /**
+     * Select fields using column references.
+     * Allows renaming fields by using different keys in the object.
+     * Container fields cannot be selected and will cause a type error.
+     *
+     * @example
+     * db.from(users).list().select({
+     *   name: users.name,
+     *   userEmail: users.email  // renamed!
+     * })
+     *
+     * @example
+     * // Include system columns (ROWID, ROWMODID) when using select()
+     * db.from(users).list().select(
+     *   { name: users.name },
+     *   { ROWID: true, ROWMODID: true }
+     * )
+     *
+     * @param fields - Object mapping output keys to column references (container fields excluded)
+     * @param systemColumns - Optional object to request system columns (ROWID, ROWMODID)
+     * @returns QueryBuilder with updated selected fields
+     */
+    select<TSelect extends Record<string, Column<any, any, ExtractTableName<Occ>, false>>, TSystemCols extends SystemColumnsOption = {}>(fields: TSelect, systemColumns?: TSystemCols): QueryBuilder<Occ, TSelect, SingleMode, IsCount, Expands, DatabaseIncludeSpecialColumns, TSystemCols>;
+    /**
+     * Filter results using operator expressions (new ORM-style API).
+     * Supports eq, gt, lt, and, or, etc. operators with Column references.
+     * Also supports raw OData filter strings as an escape hatch.
+     *
+     * @example
+     * .where(eq(users.hobby, "reading"))
+     * .where(and(eq(users.active, true), gt(users.age, 18)))
+     * .where("status eq 'active'")  // Raw OData string escape hatch
+     */
+    where(expression: FilterExpression | string): QueryBuilder<Occ, Selected, SingleMode, IsCount, Expands, DatabaseIncludeSpecialColumns, SystemCols>;
+    /**
+     * Specify the sort order for query results.
+     *
+     * @example Single field (ascending by default)
+     * ```ts
+     * .orderBy("name")
+     * .orderBy(users.name)  // Column reference
+     * .orderBy(asc(users.name))  // Explicit ascending
+     * ```
+     *
+     * @example Single field with explicit direction
+     * ```ts
+     * .orderBy(["name", "desc"])
+     * .orderBy([users.name, "desc"])  // Column reference
+     * .orderBy(desc(users.name))  // Explicit descending
+     * ```
+     *
+     * @example Multiple fields with directions
+     * ```ts
+     * .orderBy([["name", "asc"], ["createdAt", "desc"]])
+     * .orderBy([[users.name, "asc"], [users.createdAt, "desc"]])  // Column references
+     * .orderBy(users.name, desc(users.age))  // Variadic with helpers
+     * ```
+     */
+    orderBy(...orderByArgs: [
+        TypeSafeOrderBy<InferSchemaOutputFromFMTable<Occ>> | Column<any, any, ExtractTableName<Occ>> | OrderByExpression<ExtractTableName<Occ>>
+    ] | [
+        Column<any, any, ExtractTableName<Occ>>,
+        ...Array<Column<any, any, ExtractTableName<Occ>> | OrderByExpression<ExtractTableName<Occ>>>
+    ]): QueryBuilder<Occ, Selected, SingleMode, IsCount, Expands, DatabaseIncludeSpecialColumns, SystemCols>;
+    top(count: number): QueryBuilder<Occ, Selected, SingleMode, IsCount, Expands, DatabaseIncludeSpecialColumns, SystemCols>;
+    skip(count: number): QueryBuilder<Occ, Selected, SingleMode, IsCount, Expands, DatabaseIncludeSpecialColumns, SystemCols>;
+    expand<TargetTable extends FMTable<any, any>, TSelected extends keyof InferSchemaOutputFromFMTable<TargetTable> | Record<string, Column<any, any, ExtractTableName<TargetTable>>> = keyof InferSchemaOutputFromFMTable<TargetTable>, TNestedExpands extends ExpandedRelations = {}>(targetTable: ValidExpandTarget<Occ, TargetTable>, callback?: (builder: QueryBuilder<TargetTable, keyof InferSchemaOutputFromFMTable<TargetTable>, false, false, {}>) => QueryBuilder<TargetTable, TSelected, any, any, TNestedExpands>): QueryBuilder<Occ, Selected, SingleMode, IsCount, Expands & {
+        [K in ExtractTableName<TargetTable>]: {
+            schema: InferSchemaOutputFromFMTable<TargetTable>;
+            selected: TSelected;
+            nested: TNestedExpands;
+        };
+    }, DatabaseIncludeSpecialColumns, SystemCols>;
+    single(): QueryBuilder<Occ, Selected, "exact", IsCount, Expands, DatabaseIncludeSpecialColumns, SystemCols>;
+    maybeSingle(): QueryBuilder<Occ, Selected, "maybe", IsCount, Expands, DatabaseIncludeSpecialColumns, SystemCols>;
+    count(): QueryBuilder<Occ, Selected, SingleMode, true, Expands, DatabaseIncludeSpecialColumns, SystemCols>;
+    /**
+     * Builds the OData query string from current query options and expand configs.
+     */
+    private buildQueryString;
+    execute<EO extends ExecuteOptions>(options?: ExecuteMethodOptions<EO>): Promise<Result<ConditionallyWithODataAnnotations<ConditionallyWithSpecialColumns<QueryReturnType<InferSchemaOutputFromFMTable<Occ>, Selected, SingleMode, IsCount, Expands, SystemCols>, NormalizeIncludeSpecialColumns<EO["includeSpecialColumns"], DatabaseIncludeSpecialColumns>, Selected extends Record<string, Column<any, any, any>> ? true : Selected extends keyof InferSchemaOutputFromFMTable<Occ> ? false : true>, EO["includeODataAnnotations"] extends true ? true : false>>>;
+    getQueryString(options?: {
+        useEntityIds?: boolean;
+    }): string;
+    getRequestConfig(): {
+        method: string;
+        url: string;
+        body?: any;
+    };
+    toRequest(baseUrl: string, options?: ExecuteOptions): Request;
+    processResponse(response: Response, options?: ExecuteOptions): Promise<Result<QueryReturnType<InferSchemaOutputFromFMTable<Occ>, Selected, SingleMode, IsCount, Expands, SystemCols>>>;
+}