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

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

@@ -1,4 +1,4 @@
-import { ExecutionContext, ExecutableBuilder, Result, ODataRecordMetadata, InferSchemaType } from '../types.js';
+import { ExecutionContext, ExecutableBuilder, Result, ODataRecordMetadata, InferSchemaType, ExecuteOptions } from '../types.js';
 import { TableOccurrence } from './table-occurrence.js';
 import { BaseTable } from './base-table.js';
 import { QueryBuilder } from './query-builder.js';
@@ -19,13 +19,24 @@ export declare class RecordBuilder<T extends Record<string, any>, IsSingleField
     private isNavigateFromEntitySet?;
     private navigateRelation?;
     private navigateSourceTableName?;
+    private databaseUseEntityIds;
     constructor(config: {
         occurrence?: Occ;
         tableName: string;
         databaseName: string;
         context: ExecutionContext;
         recordId: string | number;
+        databaseUseEntityIds?: boolean;
     });
+    /**
+     * Helper to merge database-level useEntityIds with per-request options
+     */
+    private mergeExecuteOptions;
+    /**
+     * Gets the table ID (FMTID) if using entity IDs, otherwise returns the table name
+     * @param useEntityIds - Optional override for entity ID usage
+     */
+    private getTableId;
     getSingleField<K extends keyof T>(field: K): RecordBuilder<T, true, K, Occ>;
     navigate<RelationName extends ExtractNavigationNames<Occ>>(relationName: RelationName): QueryBuilder<ExtractSchemaFromOccurrence<FindNavigationTarget<Occ, RelationName>> extends Record<string, StandardSchemaV1> ? InferSchemaType<ExtractSchemaFromOccurrence<FindNavigationTarget<Occ, RelationName>>> : Record<string, any>>;
     navigate(relationName: string): QueryBuilder<{
@@ -33,11 +44,15 @@ export declare class RecordBuilder<T extends Record<string, any>, IsSingleField
         ROWMODID: number;
         [key: string]: any;
     }>;
-    execute(options?: RequestInit & FFetchOptions): Promise<Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>>;
+    execute(options?: RequestInit & FFetchOptions & {
+        useEntityIds?: boolean;
+    }): Promise<Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>>;
     getRequestConfig(): {
         method: string;
         url: string;
         body?: any;
     };
+    toRequest(baseUrl: string): Request;
+    processResponse(response: Response, options?: ExecuteOptions): Promise<Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>>;
 }
 export {};

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

@@ -1,7 +1,7 @@
 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 { transformTableName, transformResponseFields } from "../transform.js";
+import { getTableIdentifiers, transformTableName, transformResponseFields } from "../transform.js";
 import { QueryBuilder } from "./query-builder.js";
 import { validateSingleResponse } from "../validation.js";
 class RecordBuilder {
@@ -16,11 +16,44 @@ class RecordBuilder {
     __publicField(this, "isNavigateFromEntitySet");
     __publicField(this, "navigateRelation");
     __publicField(this, "navigateSourceTableName");
+    __publicField(this, "databaseUseEntityIds");
     this.occurrence = config.occurrence;
     this.tableName = config.tableName;
     this.databaseName = config.databaseName;
     this.context = config.context;
     this.recordId = config.recordId;
+    this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
+  }
+  /**
+   * Helper to merge database-level useEntityIds with per-request options
+   */
+  mergeExecuteOptions(options) {
+    return {
+      ...options,
+      useEntityIds: (options == null ? void 0 : 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
+   */
+  getTableId(useEntityIds) {
+    var _a, _b;
+    if (!this.occurrence) {
+      return this.tableName;
+    }
+    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) {
+        throw new Error(
+          `useEntityIds is true but TableOccurrence "${identifiers.name}" does not have an fmtId defined`
+        );
+      }
+      return identifiers.id;
+    }
+    return this.occurrence.getTableName();
   }
   getSingleField(field) {
     const newBuilder = new RecordBuilder({
@@ -66,13 +99,14 @@ class RecordBuilder {
     if (this.isNavigateFromEntitySet && this.navigateSourceTableName && this.navigateRelation) {
       url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
     } else {
-      const tableId = this.occurrence ? transformTableName(this.occurrence) : this.tableName;
+      const tableId = this.getTableId((options == null ? void 0 : options.useEntityIds) ?? this.databaseUseEntityIds);
       url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
     }
     if (this.operation === "getSingleField" && this.operationParam) {
       url += `/${this.operationParam}`;
     }
-    const result = await this.context._makeRequest(url, options);
+    const mergedOptions = this.mergeExecuteOptions(options);
+    const result = await this.context._makeRequest(url, mergedOptions);
     if (result.error) {
       return { data: void 0, error: result.error };
     }
@@ -81,7 +115,8 @@ class RecordBuilder {
       const fieldResponse = response;
       return { data: fieldResponse.value, error: void 0 };
     }
-    if ((_a = this.occurrence) == null ? void 0 : _a.baseTable) {
+    const shouldUseIds = mergedOptions.useEntityIds ?? false;
+    if (((_a = this.occurrence) == null ? void 0 : _a.baseTable) && shouldUseIds) {
       response = transformResponseFields(
         response,
         this.occurrence.baseTable,
@@ -113,7 +148,7 @@ class RecordBuilder {
     if (this.isNavigateFromEntitySet && this.navigateSourceTableName && this.navigateRelation) {
       url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
     } else {
-      const tableId = this.occurrence ? transformTableName(this.occurrence) : this.tableName;
+      const tableId = this.getTableId(this.databaseUseEntityIds);
       url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
     }
     if (this.operation === "getSingleField" && this.operationParam) {
@@ -124,6 +159,53 @@ class RecordBuilder {
       url
     };
   }
+  toRequest(baseUrl) {
+    const config = this.getRequestConfig();
+    const fullUrl = `${baseUrl}${config.url}`;
+    return new Request(fullUrl, {
+      method: config.method,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      }
+    });
+  }
+  async processResponse(response, options) {
+    var _a, _b, _c;
+    const rawResponse = await response.json();
+    if (this.operation === "getSingleField") {
+      const fieldResponse = rawResponse;
+      return { data: fieldResponse.value, error: void 0 };
+    }
+    const shouldUseIds = (options == null ? void 0 : options.useEntityIds) ?? this.databaseUseEntityIds;
+    let transformedResponse = rawResponse;
+    if (((_a = this.occurrence) == null ? void 0 : _a.baseTable) && shouldUseIds) {
+      transformedResponse = transformResponseFields(
+        rawResponse,
+        this.occurrence.baseTable,
+        void 0
+        // No expand configs for simple get
+      );
+    }
+    const schema = (_c = (_b = this.occurrence) == null ? void 0 : _b.baseTable) == null ? void 0 : _c.schema;
+    const validation = await validateSingleResponse(
+      transformedResponse,
+      schema,
+      void 0,
+      // No selected fields for record.get()
+      void 0,
+      // No expand configs
+      "exact"
+      // Expect exactly one record
+    );
+    if (!validation.valid) {
+      return { data: void 0, error: validation.error };
+    }
+    if (validation.data === null) {
+      return { data: null, error: void 0 };
+    }
+    return { data: validation.data, error: void 0 };
+  }
 }
 export {
   RecordBuilder

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

@@ -1 +1 @@
-{"version":3,"file":"record-builder.js","sources":["../../../src/client/record-builder.ts"],"sourcesContent":["import type {\n  ExecutionContext,\n  ExecutableBuilder,\n  Result,\n  ODataRecordMetadata,\n  ODataFieldResponse,\n  InferSchemaType,\n} from \"../types\";\nimport type { TableOccurrence } from \"./table-occurrence\";\nimport type { BaseTable } from \"./base-table\";\nimport { transformTableName, transformResponseFields } from \"../transform\";\nimport { QueryBuilder } from \"./query-builder\";\nimport { validateSingleResponse } from \"../validation\";\nimport { type FFetchOptions } from \"@fetchkit/ffetch\";\nimport { StandardSchemaV1 } from \"@standard-schema/spec\";\n// import type { z } from \"zod/v4\";\n\n// Helper type to extract schema from a TableOccurrence\ntype ExtractSchemaFromOccurrence<O> =\n  O extends TableOccurrence<infer BT, any, any, any>\n    ? BT extends BaseTable<infer S, any>\n      ? S\n      : never\n    : never;\n\n// Helper type to extract navigation relation names from an occurrence\ntype ExtractNavigationNames<\n  O extends TableOccurrence<any, any, any, any> | undefined,\n> =\n  O extends TableOccurrence<any, any, infer Nav, any>\n    ? Nav extends Record<string, any>\n      ? keyof Nav\n      : never\n    : never;\n\n// Helper type to resolve a navigation item (handles both direct and lazy-loaded)\ntype ResolveNavigationItem<T> = T extends () => infer R ? R : T;\n\n// Helper type to find target occurrence by relation name\ntype FindNavigationTarget<\n  O extends TableOccurrence<any, any, any, any> | undefined,\n  Name extends string,\n> =\n  O extends TableOccurrence<any, any, infer Nav, any>\n    ? Name extends keyof Nav\n      ? ResolveNavigationItem<Nav[Name]>\n      : never\n    : never;\n\nexport class RecordBuilder<\n  T extends Record<string, any>,\n  IsSingleField extends boolean = false,\n  FieldKey extends keyof T = keyof T,\n  Occ extends TableOccurrence<any, any, any, any> | undefined =\n    | TableOccurrence<any, any, any, any>\n    | undefined,\n> implements\n    ExecutableBuilder<\n      IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata\n    >\n{\n  private occurrence?: Occ;\n  private tableName: string;\n  private databaseName: string;\n  private context: ExecutionContext;\n  private recordId: string | number;\n  private operation?: \"getSingleField\" | \"navigate\";\n  private operationParam?: string;\n  private isNavigateFromEntitySet?: boolean;\n  private navigateRelation?: string;\n  private navigateSourceTableName?: string;\n\n  constructor(config: {\n    occurrence?: Occ;\n    tableName: string;\n    databaseName: string;\n    context: ExecutionContext;\n    recordId: string | number;\n  }) {\n    this.occurrence = config.occurrence;\n    this.tableName = config.tableName;\n    this.databaseName = config.databaseName;\n    this.context = config.context;\n    this.recordId = config.recordId;\n  }\n\n  getSingleField<K extends keyof T>(field: K): RecordBuilder<T, true, K, Occ> {\n    const newBuilder = new RecordBuilder<T, true, K, Occ>({\n      occurrence: this.occurrence,\n      tableName: this.tableName,\n      databaseName: this.databaseName,\n      context: this.context,\n      recordId: this.recordId,\n    });\n    newBuilder.operation = \"getSingleField\";\n    newBuilder.operationParam = field.toString();\n    // Preserve navigation context\n    newBuilder.isNavigateFromEntitySet = this.isNavigateFromEntitySet;\n    newBuilder.navigateRelation = this.navigateRelation;\n    newBuilder.navigateSourceTableName = this.navigateSourceTableName;\n    return newBuilder;\n  }\n\n  // Overload for valid relation names - returns typed QueryBuilder\n  navigate<RelationName extends ExtractNavigationNames<Occ>>(\n    relationName: RelationName,\n  ): QueryBuilder<\n    ExtractSchemaFromOccurrence<\n      FindNavigationTarget<Occ, RelationName>\n    > extends Record<string, StandardSchemaV1>\n      ? InferSchemaType<\n          ExtractSchemaFromOccurrence<FindNavigationTarget<Occ, RelationName>>\n        >\n      : Record<string, any>\n  >;\n  // Overload for arbitrary strings - returns generic QueryBuilder with system fields\n  navigate(\n    relationName: string,\n  ): QueryBuilder<{ ROWID: number; ROWMODID: number; [key: string]: any }>;\n  // Implementation\n  navigate(relationName: string): QueryBuilder<any> {\n    // Use the target occurrence if available, otherwise allow untyped navigation\n    // (useful when types might be incomplete)\n    const targetOccurrence = this.occurrence?.navigation[relationName];\n    const builder = new QueryBuilder<any>({\n      occurrence: targetOccurrence,\n      tableName: targetOccurrence?.name ?? relationName,\n      databaseName: this.databaseName,\n      context: this.context,\n    });\n    // Store the navigation info - we'll use it in execute\n    // Transform relation name to FMTID if using entity IDs\n    const relationId = targetOccurrence\n      ? transformTableName(targetOccurrence)\n      : relationName;\n\n    (builder as any).isNavigate = true;\n    (builder as any).navigateRecordId = this.recordId;\n    (builder as any).navigateRelation = relationId;\n\n    // If this RecordBuilder came from a navigated EntitySet, we need to preserve that base path\n    if (\n      this.isNavigateFromEntitySet &&\n      this.navigateSourceTableName &&\n      this.navigateRelation\n    ) {\n      // Build the base path: /sourceTable/relation('recordId')/newRelation\n      (builder as any).navigateSourceTableName = this.navigateSourceTableName;\n      (builder as any).navigateBaseRelation = this.navigateRelation;\n    } else {\n      // Normal record navigation: /tableName('recordId')/relation\n      // Transform source table name to FMTID if using entity IDs\n      const sourceTableId = this.occurrence\n        ? transformTableName(this.occurrence)\n        : this.tableName;\n      (builder as any).navigateSourceTableName = sourceTableId;\n    }\n\n    return builder;\n  }\n\n  async execute(\n    options?: RequestInit & FFetchOptions,\n  ): Promise<\n    Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>\n  > {\n    let url: string;\n\n    // Build the base URL depending on whether this came from a navigated EntitySet\n    if (\n      this.isNavigateFromEntitySet &&\n      this.navigateSourceTableName &&\n      this.navigateRelation\n    ) {\n      // From navigated EntitySet: /sourceTable/relation('recordId')\n      url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;\n    } else {\n      // Normal record: /tableName('recordId') - use FMTID if configured\n      const tableId = this.occurrence\n        ? transformTableName(this.occurrence)\n        : this.tableName;\n      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;\n    }\n\n    if (this.operation === \"getSingleField\" && this.operationParam) {\n      url += `/${this.operationParam}`;\n    }\n\n    const result = await this.context._makeRequest(url, options);\n\n    if (result.error) {\n      return { data: undefined, error: result.error };\n    }\n\n    let response = result.data;\n\n    // Handle single field operation\n    if (this.operation === \"getSingleField\") {\n      // Single field returns a JSON object with @context and value\n      const fieldResponse = response as ODataFieldResponse<T>;\n      return { data: fieldResponse.value as any, error: undefined };\n    }\n\n    // Transform response field IDs back to names if using entity IDs\n    if (this.occurrence?.baseTable) {\n      response = transformResponseFields(\n        response,\n        this.occurrence.baseTable,\n        undefined, // No expand configs for simple get\n      );\n    }\n\n    // Get schema from occurrence if available\n    const schema = this.occurrence?.baseTable?.schema;\n\n    // Validate the single record response\n    const validation = await validateSingleResponse<any>(\n      response,\n      schema,\n      undefined, // No selected fields for record.get()\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\n    if (validation.data === null) {\n      return { data: null as any, error: undefined };\n    }\n\n    return { data: validation.data, error: undefined };\n  }\n\n  getRequestConfig(): { method: string; url: string; body?: any } {\n    let url: string;\n\n    // Build the base URL depending on whether this came from a navigated EntitySet\n    if (\n      this.isNavigateFromEntitySet &&\n      this.navigateSourceTableName &&\n      this.navigateRelation\n    ) {\n      // From navigated EntitySet: /sourceTable/relation('recordId')\n      url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;\n    } else {\n      // Normal record: /tableName('recordId') - use FMTID if configured\n      const tableId = this.occurrence\n        ? transformTableName(this.occurrence)\n        : this.tableName;\n      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;\n    }\n\n    if (this.operation === \"getSingleField\" && this.operationParam) {\n      url += `/${this.operationParam}`;\n    }\n\n    return {\n      method: \"GET\",\n      url,\n    };\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"record-builder.js","sources":["../../../src/client/record-builder.ts"],"sourcesContent":["import type {\n  ExecutionContext,\n  ExecutableBuilder,\n  Result,\n  ODataRecordMetadata,\n  ODataFieldResponse,\n  InferSchemaType,\n  ExecuteOptions,\n} from \"../types\";\nimport type { TableOccurrence } from \"./table-occurrence\";\nimport type { BaseTable } from \"./base-table\";\nimport { transformTableName, transformResponseFields, getTableIdentifiers } from \"../transform\";\nimport { QueryBuilder } from \"./query-builder\";\nimport { validateSingleResponse } from \"../validation\";\nimport { type FFetchOptions } from \"@fetchkit/ffetch\";\nimport { StandardSchemaV1 } from \"@standard-schema/spec\";\n// import type { z } from \"zod/v4\";\n\n// Helper type to extract schema from a TableOccurrence\ntype ExtractSchemaFromOccurrence<O> =\n  O extends TableOccurrence<infer BT, any, any, any>\n    ? BT extends BaseTable<infer S, any>\n      ? S\n      : never\n    : never;\n\n// Helper type to extract navigation relation names from an occurrence\ntype ExtractNavigationNames<\n  O extends TableOccurrence<any, any, any, any> | undefined,\n> =\n  O extends TableOccurrence<any, any, infer Nav, any>\n    ? Nav extends Record<string, any>\n      ? keyof Nav\n      : never\n    : never;\n\n// Helper type to resolve a navigation item (handles both direct and lazy-loaded)\ntype ResolveNavigationItem<T> = T extends () => infer R ? R : T;\n\n// Helper type to find target occurrence by relation name\ntype FindNavigationTarget<\n  O extends TableOccurrence<any, any, any, any> | undefined,\n  Name extends string,\n> =\n  O extends TableOccurrence<any, any, infer Nav, any>\n    ? Name extends keyof Nav\n      ? ResolveNavigationItem<Nav[Name]>\n      : never\n    : never;\n\nexport class RecordBuilder<\n  T extends Record<string, any>,\n  IsSingleField extends boolean = false,\n  FieldKey extends keyof T = keyof T,\n  Occ extends TableOccurrence<any, any, any, any> | undefined =\n    | TableOccurrence<any, any, any, any>\n    | undefined,\n> implements\n    ExecutableBuilder<\n      IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata\n    >\n{\n  private occurrence?: Occ;\n  private tableName: string;\n  private databaseName: string;\n  private context: ExecutionContext;\n  private recordId: string | number;\n  private operation?: \"getSingleField\" | \"navigate\";\n  private operationParam?: string;\n  private isNavigateFromEntitySet?: boolean;\n  private navigateRelation?: string;\n  private navigateSourceTableName?: string;\n\n  private databaseUseEntityIds: boolean;\n\n  constructor(config: {\n    occurrence?: Occ;\n    tableName: string;\n    databaseName: string;\n    context: ExecutionContext;\n    recordId: string | number;\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.recordId = config.recordId;\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   * 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  getSingleField<K extends keyof T>(field: K): RecordBuilder<T, true, K, Occ> {\n    const newBuilder = new RecordBuilder<T, true, K, Occ>({\n      occurrence: this.occurrence,\n      tableName: this.tableName,\n      databaseName: this.databaseName,\n      context: this.context,\n      recordId: this.recordId,\n    });\n    newBuilder.operation = \"getSingleField\";\n    newBuilder.operationParam = field.toString();\n    // Preserve navigation context\n    newBuilder.isNavigateFromEntitySet = this.isNavigateFromEntitySet;\n    newBuilder.navigateRelation = this.navigateRelation;\n    newBuilder.navigateSourceTableName = this.navigateSourceTableName;\n    return newBuilder;\n  }\n\n  // Overload for valid relation names - returns typed QueryBuilder\n  navigate<RelationName extends ExtractNavigationNames<Occ>>(\n    relationName: RelationName,\n  ): QueryBuilder<\n    ExtractSchemaFromOccurrence<\n      FindNavigationTarget<Occ, RelationName>\n    > extends Record<string, StandardSchemaV1>\n      ? InferSchemaType<\n          ExtractSchemaFromOccurrence<FindNavigationTarget<Occ, RelationName>>\n        >\n      : Record<string, any>\n  >;\n  // Overload for arbitrary strings - returns generic QueryBuilder with system fields\n  navigate(\n    relationName: string,\n  ): QueryBuilder<{ ROWID: number; ROWMODID: number; [key: string]: any }>;\n  // Implementation\n  navigate(relationName: string): QueryBuilder<any> {\n    // Use the target occurrence if available, otherwise allow untyped navigation\n    // (useful when types might be incomplete)\n    const targetOccurrence = this.occurrence?.navigation[relationName];\n    const builder = new QueryBuilder<any>({\n      occurrence: targetOccurrence,\n      tableName: targetOccurrence?.name ?? relationName,\n      databaseName: this.databaseName,\n      context: this.context,\n    });\n    // Store the navigation info - we'll use it in execute\n    // Transform relation name to FMTID if using entity IDs\n    const relationId = targetOccurrence\n      ? transformTableName(targetOccurrence)\n      : relationName;\n\n    (builder as any).isNavigate = true;\n    (builder as any).navigateRecordId = this.recordId;\n    (builder as any).navigateRelation = relationId;\n\n    // If this RecordBuilder came from a navigated EntitySet, we need to preserve that base path\n    if (\n      this.isNavigateFromEntitySet &&\n      this.navigateSourceTableName &&\n      this.navigateRelation\n    ) {\n      // Build the base path: /sourceTable/relation('recordId')/newRelation\n      (builder as any).navigateSourceTableName = this.navigateSourceTableName;\n      (builder as any).navigateBaseRelation = this.navigateRelation;\n    } else {\n      // Normal record navigation: /tableName('recordId')/relation\n      // Transform source table name to FMTID if using entity IDs\n      const sourceTableId = this.occurrence\n        ? transformTableName(this.occurrence)\n        : this.tableName;\n      (builder as any).navigateSourceTableName = sourceTableId;\n    }\n\n    return builder;\n  }\n\n  async execute(\n    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },\n  ): Promise<\n    Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>\n  > {\n    let url: string;\n\n    // Build the base URL depending on whether this came from a navigated EntitySet\n    if (\n      this.isNavigateFromEntitySet &&\n      this.navigateSourceTableName &&\n      this.navigateRelation\n    ) {\n      // From navigated EntitySet: /sourceTable/relation('recordId')\n      url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;\n    } else {\n      // Normal record: /tableName('recordId') - use FMTID if configured\n      const tableId = this.getTableId(options?.useEntityIds ?? this.databaseUseEntityIds);\n      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;\n    }\n\n    if (this.operation === \"getSingleField\" && this.operationParam) {\n      url += `/${this.operationParam}`;\n    }\n\n    const mergedOptions = this.mergeExecuteOptions(options);\n    const result = await this.context._makeRequest(url, mergedOptions);\n\n    if (result.error) {\n      return { data: undefined, error: result.error };\n    }\n\n    let response = result.data;\n\n    // Handle single field operation\n    if (this.operation === \"getSingleField\") {\n      // Single field returns a JSON object with @context and value\n      const fieldResponse = response as ODataFieldResponse<T>;\n      return { data: fieldResponse.value as any, error: undefined };\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 = mergedOptions.useEntityIds ?? false;\n    \n    if (this.occurrence?.baseTable && shouldUseIds) {\n      response = transformResponseFields(\n        response,\n        this.occurrence.baseTable,\n        undefined, // No expand configs for simple get\n      );\n    }\n\n    // Get schema from occurrence if available\n    const schema = this.occurrence?.baseTable?.schema;\n\n    // Validate the single record response\n    const validation = await validateSingleResponse<any>(\n      response,\n      schema,\n      undefined, // No selected fields for record.get()\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\n    if (validation.data === null) {\n      return { data: null as any, error: undefined };\n    }\n\n    return { data: validation.data, error: undefined };\n  }\n\n  getRequestConfig(): { method: string; url: string; body?: any } {\n    let url: string;\n\n    // Build the base URL depending on whether this came from a navigated EntitySet\n    if (\n      this.isNavigateFromEntitySet &&\n      this.navigateSourceTableName &&\n      this.navigateRelation\n    ) {\n      // From navigated EntitySet: /sourceTable/relation('recordId')\n      url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;\n    } else {\n      // For batch operations, use database-level setting (no per-request override available here)\n      const tableId = this.getTableId(this.databaseUseEntityIds);\n      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;\n    }\n\n    if (this.operation === \"getSingleField\" && this.operationParam) {\n      url += `/${this.operationParam}`;\n    }\n\n    return {\n      method: \"GET\",\n      url,\n    };\n  }\n\n  toRequest(baseUrl: string): Request {\n    const config = this.getRequestConfig();\n    const fullUrl = `${baseUrl}${config.url}`;\n\n    return new Request(fullUrl, {\n      method: config.method,\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Accept: \"application/json\",\n      },\n    });\n  }\n\n  async processResponse(\n    response: Response,\n    options?: ExecuteOptions,\n  ): Promise<\n    Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>\n  > {\n    const rawResponse = await response.json();\n\n    // Handle single field operation\n    if (this.operation === \"getSingleField\") {\n      // Single field returns a JSON object with @context and value\n      const fieldResponse = rawResponse as ODataFieldResponse<T>;\n      return { data: fieldResponse.value as any, error: undefined };\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 simple get\n      );\n    }\n\n    // Get schema from occurrence if available\n    const schema = this.occurrence?.baseTable?.schema;\n\n    // Validate the single record response\n    const validation = await validateSingleResponse<any>(\n      transformedResponse,\n      schema,\n      undefined, // No selected fields for record.get()\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\n    if (validation.data === null) {\n      return { data: null as any, error: undefined };\n    }\n\n    return { data: validation.data, error: undefined };\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/client/response-processor.d.ts

@@ -0,0 +1,38 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { BaseTable } from './base-table.js';
+import { ExecuteOptions } from '../types.js';
+import { ExpandValidationConfig } from '../validation.js';
+import { ValidationError, ResponseStructureError } from '../errors.js';
+export type ODataResponse<T = unknown> = T & {
+    "@odata.context"?: string;
+    "@odata.count"?: number;
+};
+export type ODataListResponse<T = unknown> = ODataResponse<{
+    value: T[];
+}>;
+export type ODataRecordResponse<T = unknown> = ODataResponse<T & {
+    "@id"?: string;
+    "@editLink"?: string;
+}>;
+/**
+ * Strip OData annotations from a single record
+ */
+export declare function stripODataAnnotations<T extends Record<string, unknown>>(record: ODataRecordResponse<T>, options?: ExecuteOptions): T;
+/**
+ * Transform field IDs back to names using the base table configuration
+ */
+export declare function applyFieldTransformation<T extends Record<string, unknown>>(response: ODataResponse<T> | ODataListResponse<T>, baseTable: BaseTable<Record<string, StandardSchemaV1>, any, any, any>, expandConfigs?: ExpandValidationConfig[]): ODataResponse<T> | ODataListResponse<T>;
+/**
+ * Apply schema validation and transformation to data
+ */
+export declare function applyValidation<T extends Record<string, unknown>>(data: T | T[], schema?: Record<string, StandardSchemaV1>, selectedFields?: (keyof T)[], expandConfigs?: ExpandValidationConfig[]): Promise<{
+    valid: true;
+    data: T | T[];
+} | {
+    valid: false;
+    error: ValidationError | ResponseStructureError;
+}>;
+/**
+ * Extract value array from OData list response, or wrap single record in array
+ */
+export declare function extractListValue<T>(response: ODataListResponse<T> | ODataRecordResponse<T>): T[];

package/dist/esm/client/schema-manager.d.ts

@@ -0,0 +1,57 @@
+import { FFetchOptions } from '@fetchkit/ffetch';
+import { ExecutionContext } from '../types.js';
+type GenericField = {
+    name: string;
+    nullable?: boolean;
+    primary?: boolean;
+    unique?: boolean;
+    global?: boolean;
+    repetitions?: number;
+};
+type StringField = GenericField & {
+    type: "string";
+    maxLength?: number;
+    default?: "USER" | "USERNAME" | "CURRENT_USER";
+};
+type NumericField = GenericField & {
+    type: "numeric";
+};
+type DateField = GenericField & {
+    type: "date";
+    default?: "CURRENT_DATE" | "CURDATE";
+};
+type TimeField = GenericField & {
+    type: "time";
+    default?: "CURRENT_TIME" | "CURTIME";
+};
+type TimestampField = GenericField & {
+    type: "timestamp";
+    default?: "CURRENT_TIMESTAMP" | "CURTIMESTAMP";
+};
+type ContainerField = GenericField & {
+    type: "container";
+    externalSecurePath?: string;
+};
+export type Field = StringField | NumericField | DateField | TimeField | TimestampField | ContainerField;
+export type { StringField, NumericField, DateField, TimeField, TimestampField, ContainerField, };
+type FileMakerField = Omit<Field, "type" | "repetitions" | "maxLength"> & {
+    type: string;
+};
+type TableDefinition = {
+    tableName: string;
+    fields: FileMakerField[];
+};
+export declare class SchemaManager {
+    private readonly databaseName;
+    private readonly context;
+    constructor(databaseName: string, context: ExecutionContext);
+    createTable(tableName: string, fields: Field[], options?: RequestInit & FFetchOptions): Promise<TableDefinition>;
+    addFields(tableName: string, fields: Field[], options?: RequestInit & FFetchOptions): Promise<TableDefinition>;
+    deleteTable(tableName: string, options?: RequestInit & FFetchOptions): Promise<void>;
+    deleteField(tableName: string, fieldName: string, options?: RequestInit & FFetchOptions): Promise<void>;
+    createIndex(tableName: string, fieldName: string, options?: RequestInit & FFetchOptions): Promise<{
+        indexName: string;
+    }>;
+    deleteIndex(tableName: string, fieldName: string, options?: RequestInit & FFetchOptions): Promise<void>;
+    private static compileFieldDefinition;
+}

package/dist/esm/client/schema-manager.js

@@ -0,0 +1,132 @@
+class SchemaManager {
+  constructor(databaseName, context) {
+    this.databaseName = databaseName;
+    this.context = context;
+  }
+  async createTable(tableName, fields, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          tableName,
+          fields: fields.map(SchemaManager.compileFieldDefinition)
+        }),
+        ...options
+      }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+    return result.data;
+  }
+  async addFields(tableName, fields, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}`,
+      {
+        method: "PATCH",
+        body: JSON.stringify({
+          fields: fields.map(SchemaManager.compileFieldDefinition)
+        }),
+        ...options
+      }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+    return result.data;
+  }
+  async deleteTable(tableName, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}`,
+      { method: "DELETE", ...options }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+  }
+  async deleteField(tableName, fieldName, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}/${fieldName}`,
+      {
+        method: "DELETE",
+        ...options
+      }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+  }
+  async createIndex(tableName, fieldName, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Indexes/${tableName}`,
+      {
+        method: "POST",
+        body: JSON.stringify({ indexName: fieldName }),
+        ...options
+      }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+    return result.data;
+  }
+  async deleteIndex(tableName, fieldName, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Indexes/${tableName}/${fieldName}`,
+      {
+        method: "DELETE",
+        ...options
+      }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+  }
+  static compileFieldDefinition(field) {
+    let type = field.type;
+    const repetitions = field.repetitions;
+    if (field.type === "string") {
+      type = "varchar";
+      const stringField = field;
+      if (stringField.maxLength !== void 0) {
+        type += `(${stringField.maxLength})`;
+      }
+    }
+    if (repetitions !== void 0) {
+      type += `[${repetitions}]`;
+    }
+    const result = {
+      name: field.name,
+      type
+    };
+    if (field.nullable !== void 0) result.nullable = field.nullable;
+    if (field.primary !== void 0) result.primary = field.primary;
+    if (field.unique !== void 0) result.unique = field.unique;
+    if (field.global !== void 0) result.global = field.global;
+    if (field.type === "string") {
+      const stringField = field;
+      if (stringField.default !== void 0)
+        result.default = stringField.default;
+    } else if (field.type === "date") {
+      const dateField = field;
+      if (dateField.default !== void 0) result.default = dateField.default;
+    } else if (field.type === "time") {
+      const timeField = field;
+      if (timeField.default !== void 0) result.default = timeField.default;
+    } else if (field.type === "timestamp") {
+      const timestampField = field;
+      if (timestampField.default !== void 0)
+        result.default = timestampField.default;
+    } else if (field.type === "container") {
+      const containerField = field;
+      if (containerField.externalSecurePath !== void 0)
+        result.externalSecurePath = containerField.externalSecurePath;
+    }
+    return result;
+  }
+}
+export {
+  SchemaManager
+};
+//# sourceMappingURL=schema-manager.js.map

package/dist/esm/client/schema-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-manager.js","sources":["../../../src/client/schema-manager.ts"],"sourcesContent":["import type { FFetchOptions } from \"@fetchkit/ffetch\";\nimport type { ExecutionContext } from \"../types\";\n\ntype GenericField = {\n  name: string;\n  nullable?: boolean;\n  primary?: boolean;\n  unique?: boolean;\n  global?: boolean;\n  repetitions?: number;\n};\n\ntype StringField = GenericField & {\n  type: \"string\";\n  maxLength?: number;\n  default?: \"USER\" | \"USERNAME\" | \"CURRENT_USER\";\n};\n\ntype NumericField = GenericField & {\n  type: \"numeric\";\n};\n\ntype DateField = GenericField & {\n  type: \"date\";\n  default?: \"CURRENT_DATE\" | \"CURDATE\";\n};\n\ntype TimeField = GenericField & {\n  type: \"time\";\n  default?: \"CURRENT_TIME\" | \"CURTIME\";\n};\n\ntype TimestampField = GenericField & {\n  type: \"timestamp\";\n  default?: \"CURRENT_TIMESTAMP\" | \"CURTIMESTAMP\";\n};\n\ntype ContainerField = GenericField & {\n  type: \"container\";\n  externalSecurePath?: string;\n};\n\nexport type Field =\n  | StringField\n  | NumericField\n  | DateField\n  | TimeField\n  | TimestampField\n  | ContainerField;\n\nexport type {\n  StringField,\n  NumericField,\n  DateField,\n  TimeField,\n  TimestampField,\n  ContainerField,\n};\n\ntype FileMakerField = Omit<Field, \"type\" | \"repetitions\" | \"maxLength\"> & {\n  type: string;\n};\n\ntype TableDefinition = {\n  tableName: string;\n  fields: FileMakerField[];\n};\n\nexport class SchemaManager {\n  public constructor(\n    private readonly databaseName: string,\n    private readonly context: ExecutionContext,\n  ) {}\n\n  public async createTable(\n    tableName: string,\n    fields: Field[],\n    options?: RequestInit & FFetchOptions,\n  ): Promise<TableDefinition> {\n    const result = await this.context._makeRequest<TableDefinition>(\n      `/${this.databaseName}/FileMaker_Tables`,\n      {\n        method: \"POST\",\n        body: JSON.stringify({\n          tableName,\n          fields: fields.map(SchemaManager.compileFieldDefinition),\n        }),\n        ...options,\n      },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n\n    return result.data;\n  }\n\n  public async addFields(\n    tableName: string,\n    fields: Field[],\n    options?: RequestInit & FFetchOptions,\n  ): Promise<TableDefinition> {\n    const result = await this.context._makeRequest<TableDefinition>(\n      `/${this.databaseName}/FileMaker_Tables/${tableName}`,\n      {\n        method: \"PATCH\",\n        body: JSON.stringify({\n          fields: fields.map(SchemaManager.compileFieldDefinition),\n        }),\n        ...options,\n      },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n\n    return result.data;\n  }\n\n  public async deleteTable(\n    tableName: string,\n    options?: RequestInit & FFetchOptions,\n  ): Promise<void> {\n    const result = await this.context._makeRequest(\n      `/${this.databaseName}/FileMaker_Tables/${tableName}`,\n      { method: \"DELETE\", ...options },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n  }\n\n  public async deleteField(\n    tableName: string,\n    fieldName: string,\n    options?: RequestInit & FFetchOptions,\n  ): Promise<void> {\n    const result = await this.context._makeRequest(\n      `/${this.databaseName}/FileMaker_Tables/${tableName}/${fieldName}`,\n      {\n        method: \"DELETE\",\n        ...options,\n      },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n  }\n\n  public async createIndex(\n    tableName: string,\n    fieldName: string,\n    options?: RequestInit & FFetchOptions,\n  ): Promise<{ indexName: string }> {\n    const result = await this.context._makeRequest<{ indexName: string }>(\n      `/${this.databaseName}/FileMaker_Indexes/${tableName}`,\n      {\n        method: \"POST\",\n        body: JSON.stringify({ indexName: fieldName }),\n        ...options,\n      },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n\n    return result.data;\n  }\n\n  public async deleteIndex(\n    tableName: string,\n    fieldName: string,\n    options?: RequestInit & FFetchOptions,\n  ): Promise<void> {\n    const result = await this.context._makeRequest(\n      `/${this.databaseName}/FileMaker_Indexes/${tableName}/${fieldName}`,\n      {\n        method: \"DELETE\",\n        ...options,\n      },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n  }\n\n  private static compileFieldDefinition(field: Field): FileMakerField {\n    let type: string = field.type;\n    const repetitions = field.repetitions;\n\n    // Handle string fields - convert to varchar and add maxLength if present\n    if (field.type === \"string\") {\n      type = \"varchar\";\n      const stringField = field as StringField;\n      if (stringField.maxLength !== undefined) {\n        type += `(${stringField.maxLength})`;\n      }\n    }\n\n    // Add repetitions suffix if present\n    if (repetitions !== undefined) {\n      type += `[${repetitions}]`;\n    }\n\n    // Build the result object, excluding type, maxLength, and repetitions\n    const result: any = {\n      name: field.name,\n      type,\n    };\n\n    // Add optional properties that FileMaker expects\n    if (field.nullable !== undefined) result.nullable = field.nullable;\n    if (field.primary !== undefined) result.primary = field.primary;\n    if (field.unique !== undefined) result.unique = field.unique;\n    if (field.global !== undefined) result.global = field.global;\n\n    // Add type-specific properties\n    if (field.type === \"string\") {\n      const stringField = field as StringField;\n      if (stringField.default !== undefined)\n        result.default = stringField.default;\n    } else if (field.type === \"date\") {\n      const dateField = field as DateField;\n      if (dateField.default !== undefined) result.default = dateField.default;\n    } else if (field.type === \"time\") {\n      const timeField = field as TimeField;\n      if (timeField.default !== undefined) result.default = timeField.default;\n    } else if (field.type === \"timestamp\") {\n      const timestampField = field as TimestampField;\n      if (timestampField.default !== undefined)\n        result.default = timestampField.default;\n    } else if (field.type === \"container\") {\n      const containerField = field as ContainerField;\n      if (containerField.externalSecurePath !== undefined)\n        result.externalSecurePath = containerField.externalSecurePath;\n    }\n\n    return result as FileMakerField;\n  }\n}\n"],"names":[],"mappings":"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"}

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

@@ -1,4 +1,4 @@
-import { ExecutionContext, ExecutableBuilder, Result, WithSystemFields } from '../types.js';
+import { ExecutionContext, ExecutableBuilder, Result, WithSystemFields, ExecuteOptions } from '../types.js';
 import { TableOccurrence } from './table-occurrence.js';
 import { BaseTable } from './base-table.js';
 import { QueryBuilder } from './query-builder.js';
@@ -7,39 +7,43 @@ import { FFetchOptions } from '@fetchkit/ffetch';
  * Initial update builder returned from EntitySet.update(data)
  * Requires calling .byId() or .where() before .execute() is available
  */
-export declare class UpdateBuilder<T extends Record<string, any>, BT extends BaseTable<any, any, any, any>> {
+export declare class UpdateBuilder<T extends Record<string, any>, BT extends BaseTable<any, any, any, any>, ReturnPreference extends "minimal" | "representation" = "minimal"> {
     private tableName;
     private databaseName;
     private context;
     private occurrence?;
     private data;
+    private returnPreference;
+    private databaseUseEntityIds;
     constructor(config: {
         occurrence?: TableOccurrence<any, any, any, any>;
         tableName: string;
         databaseName: string;
         context: ExecutionContext;
         data: Partial<T>;
+        returnPreference: ReturnPreference;
+        databaseUseEntityIds?: boolean;
     });
     /**
      * 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>;
+    byId(id: string | number): ExecutableUpdateBuilder<T, true, ReturnPreference>;
     /**
      * 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>;
+    where(fn: (q: QueryBuilder<WithSystemFields<T>>) => QueryBuilder<WithSystemFields<T>>): ExecutableUpdateBuilder<T, true, ReturnPreference>;
 }
 /**
  * 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 declare class ExecutableUpdateBuilder<T extends Record<string, any>, IsByFilter extends boolean> implements ExecutableBuilder<{
+export declare class ExecutableUpdateBuilder<T extends Record<string, any>, IsByFilter extends boolean, ReturnPreference extends "minimal" | "representation" = "minimal"> implements ExecutableBuilder<ReturnPreference extends "minimal" ? {
     updatedCount: number;
-}> {
+} : T> {
     private tableName;
     private databaseName;
     private context;
@@ -48,6 +52,8 @@ export declare class ExecutableUpdateBuilder<T extends Record<string, any>, IsBy
     private mode;
     private recordId?;
     private queryBuilder?;
+    private returnPreference;
+    private databaseUseEntityIds;
     constructor(config: {
         occurrence?: TableOccurrence<any, any, any, any>;
         tableName: string;
@@ -57,13 +63,30 @@ export declare class ExecutableUpdateBuilder<T extends Record<string, any>, IsBy
         mode: "byId" | "byFilter";
         recordId?: string | number;
         queryBuilder?: QueryBuilder<any>;
+        returnPreference: ReturnPreference;
+        databaseUseEntityIds?: boolean;
     });
-    execute(options?: RequestInit & FFetchOptions): Promise<Result<{
+    /**
+     * Helper to merge database-level useEntityIds with per-request options
+     */
+    private mergeExecuteOptions;
+    /**
+     * Gets the table ID (FMTID) if using entity IDs, otherwise returns the table name
+     * @param useEntityIds - Optional override for entity ID usage
+     */
+    private getTableId;
+    execute(options?: RequestInit & FFetchOptions & {
+        useEntityIds?: boolean;
+    }): Promise<Result<ReturnPreference extends "minimal" ? {
         updatedCount: number;
-    }>>;
+    } : T>>;
     getRequestConfig(): {
         method: string;
         url: string;
         body?: any;
     };
+    toRequest(baseUrl: string): Request;
+    processResponse(response: Response, options?: ExecuteOptions): Promise<Result<ReturnPreference extends "minimal" ? {
+        updatedCount: number;
+    } : T>>;
 }