@proofkit/fmodata 0.1.0-alpha.9 → 0.1.0-beta.24

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

@@ -0,0 +1,45 @@
+import { InternalLogger } from '../../logger.js';
+import { FMTable } from '../../orm/table.js';
+import { ExpandValidationConfig } from '../../validation.js';
+import { ExpandConfig } from './shared-types.js';
+/**
+ * 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;
+    private readonly logger;
+    constructor(useEntityIds: boolean, logger: InternalLogger);
+    /**
+     * Builds OData $expand query string from expand configurations.
+     */
+    buildExpandString(configs: ExpandConfig[]): string;
+    /**
+     * Builds validation configs for expanded navigation properties.
+     */
+    buildValidationConfigs(configs: ExpandConfig[]): ExpandValidationConfig[];
+    /**
+     * Process an expand() call and return the expand config.
+     * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+     *
+     * @param targetTable - The target table to expand to
+     * @param sourceTable - The source table (for validation)
+     * @param callback - Optional callback to configure the expand query
+     * @param builderFactory - Function that creates a QueryBuilder for the target table
+     * @returns ExpandConfig to add to the builder's expandConfigs array
+     */
+    processExpand<TargetTable extends FMTable<any, any>, Builder = any>(targetTable: TargetTable, sourceTable: FMTable<any, any> | undefined, callback?: (builder: Builder) => Builder, builderFactory?: () => Builder): ExpandConfig;
+    /**
+     * Builds a single expand string with its options.
+     */
+    private buildSingleExpand;
+    /**
+     * Resolves relation name, using FMTID if entity IDs are enabled.
+     */
+    private resolveRelationName;
+    /**
+     * Builds expand parts (select, filter, orderBy, etc.) for a single expand.
+     */
+    private buildExpandParts;
+}

package/dist/esm/client/builders/expand-builder.js

@@ -0,0 +1,185 @@
+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 buildQuery from "odata-query";
+import { getBaseTableConfig, getTableName, getNavigationPaths, FMTable } from "../../orm/table.js";
+import { getDefaultSelectFields } from "./default-select.js";
+import { formatSelectFields } from "./select-utils.js";
+const FILTER_QUERY_REGEX = /\$filter=([^&]+)/;
+class ExpandBuilder {
+  constructor(useEntityIds, logger) {
+    __publicField(this, "useEntityIds");
+    __publicField(this, "logger");
+    this.useEntityIds = useEntityIds;
+    this.logger = logger;
+  }
+  /**
+   * Builds OData $expand query string from expand configurations.
+   */
+  buildExpandString(configs) {
+    if (configs.length === 0) {
+      return "";
+    }
+    return configs.map((config) => this.buildSingleExpand(config)).join(",");
+  }
+  /**
+   * Builds validation configs for expanded navigation properties.
+   */
+  buildValidationConfigs(configs) {
+    return configs.map((config) => {
+      var _a;
+      const targetTable = config.targetTable;
+      let targetSchema;
+      if (targetTable) {
+        const baseTableConfig = getBaseTableConfig(targetTable);
+        const containerFields = baseTableConfig.containerFields || [];
+        const schema = { ...baseTableConfig.schema };
+        for (const containerField of containerFields) {
+          delete schema[containerField];
+        }
+        targetSchema = schema;
+      }
+      let selectedFields;
+      if ((_a = config.options) == null ? void 0 : _a.select) {
+        selectedFields = Array.isArray(config.options.select) ? config.options.select.map(String) : [String(config.options.select)];
+      }
+      const nestedExpands = config.nestedExpandConfigs ? this.buildValidationConfigs(config.nestedExpandConfigs) : void 0;
+      return {
+        relation: config.relation,
+        targetSchema,
+        targetTable,
+        table: targetTable,
+        selectedFields,
+        nestedExpands
+      };
+    });
+  }
+  /**
+   * Process an expand() call and return the expand config.
+   * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+   *
+   * @param targetTable - The target table to expand to
+   * @param sourceTable - The source table (for validation)
+   * @param callback - Optional callback to configure the expand query
+   * @param builderFactory - Function that creates a QueryBuilder for the target table
+   * @returns ExpandConfig to add to the builder's expandConfigs array
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration, generic Builder type
+  processExpand(targetTable, sourceTable, callback, builderFactory) {
+    const relationName = getTableName(targetTable);
+    if (sourceTable) {
+      const navigationPaths = getNavigationPaths(sourceTable);
+      if (navigationPaths && !navigationPaths.includes(relationName)) {
+        this.logger.warn(
+          `Cannot expand to "${relationName}". Valid navigation paths: ${navigationPaths.length > 0 ? navigationPaths.join(", ") : "none"}`
+        );
+      }
+    }
+    if (callback && builderFactory) {
+      const targetBuilder = builderFactory();
+      const configuredBuilder = callback(targetBuilder);
+      const expandOptions = {
+        // biome-ignore lint/suspicious/noExplicitAny: Type assertion for internal builder property access
+        ...configuredBuilder.queryOptions
+      };
+      if (!expandOptions.select) {
+        const defaultFields2 = getDefaultSelectFields(targetTable);
+        if (defaultFields2) {
+          expandOptions.select = defaultFields2;
+        }
+      }
+      const nestedExpandConfigs = configuredBuilder.expandConfigs;
+      if ((nestedExpandConfigs == null ? void 0 : nestedExpandConfigs.length) > 0) {
+        const nestedExpandString = this.buildExpandString(nestedExpandConfigs);
+        if (nestedExpandString) {
+          expandOptions.expand = nestedExpandString;
+        }
+      }
+      return {
+        relation: relationName,
+        options: expandOptions,
+        targetTable,
+        nestedExpandConfigs: (nestedExpandConfigs == null ? void 0 : nestedExpandConfigs.length) > 0 ? nestedExpandConfigs : void 0
+      };
+    }
+    const defaultFields = getDefaultSelectFields(targetTable);
+    if (defaultFields) {
+      return {
+        relation: relationName,
+        options: { select: defaultFields },
+        targetTable
+      };
+    }
+    return {
+      relation: relationName,
+      targetTable
+    };
+  }
+  /**
+   * Builds a single expand string with its options.
+   */
+  buildSingleExpand(config) {
+    const relationName = this.resolveRelationName(config);
+    const parts = this.buildExpandParts(config);
+    if (parts.length === 0) {
+      return relationName;
+    }
+    return `${relationName}(${parts.join(";")})`;
+  }
+  /**
+   * Resolves relation name, using FMTID if entity IDs are enabled.
+   */
+  resolveRelationName(config) {
+    if (!this.useEntityIds) {
+      return config.relation;
+    }
+    const targetTable = config.targetTable;
+    if (targetTable && FMTable.Symbol.EntityId in targetTable) {
+      const tableId = targetTable[FMTable.Symbol.EntityId];
+      if (tableId) {
+        return tableId;
+      }
+    }
+    return config.relation;
+  }
+  /**
+   * Builds expand parts (select, filter, orderBy, etc.) for a single expand.
+   */
+  buildExpandParts(config) {
+    if (!config.options || Object.keys(config.options).length === 0) {
+      return [];
+    }
+    const parts = [];
+    const opts = config.options;
+    if (opts.select) {
+      const selectArray = Array.isArray(opts.select) ? opts.select.map(String) : [String(opts.select)];
+      const selectFields = formatSelectFields(selectArray, config.targetTable, this.useEntityIds);
+      parts.push(`$select=${selectFields}`);
+    }
+    if (opts.filter) {
+      const filterQuery = buildQuery({ filter: opts.filter });
+      const match = filterQuery.match(FILTER_QUERY_REGEX);
+      if (match) {
+        parts.push(`$filter=${match[1]}`);
+      }
+    }
+    if (opts.orderBy) {
+      const orderByValue = Array.isArray(opts.orderBy) ? opts.orderBy.join(",") : String(opts.orderBy);
+      parts.push(`$orderby=${orderByValue}`);
+    }
+    if (opts.top !== void 0) {
+      parts.push(`$top=${opts.top}`);
+    }
+    if (opts.skip !== void 0) {
+      parts.push(`$skip=${opts.skip}`);
+    }
+    if (opts.expand && typeof opts.expand === "string") {
+      parts.push(`$expand=${opts.expand}`);
+    }
+    return parts;
+  }
+}
+export {
+  ExpandBuilder
+};
+//# sourceMappingURL=expand-builder.js.map

package/dist/esm/client/builders/expand-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand-builder.js","sources":["../../../../src/client/builders/expand-builder.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport buildQuery, { type QueryOptions } from \"odata-query\";\nimport type { InternalLogger } from \"../../logger\";\nimport { FMTable, getBaseTableConfig, getNavigationPaths, getTableName } from \"../../orm/table\";\nimport type { ExpandValidationConfig } from \"../../validation\";\nimport { getDefaultSelectFields } from \"./default-select\";\nimport { formatSelectFields } from \"./select-utils\";\nimport type { ExpandConfig } from \"./shared-types\";\n\nconst FILTER_QUERY_REGEX = /\\$filter=([^&]+)/;\n\n/**\n * Builds OData expand query strings and validation configs.\n * Handles nested expands recursively and transforms relation names to FMTIDs\n * when using entity IDs.\n */\nexport class ExpandBuilder {\n  private readonly useEntityIds: boolean;\n  private readonly logger: InternalLogger;\n\n  constructor(useEntityIds: boolean, logger: InternalLogger) {\n    this.useEntityIds = useEntityIds;\n    this.logger = logger;\n  }\n\n  /**\n   * Builds OData $expand query string from expand configurations.\n   */\n  buildExpandString(configs: ExpandConfig[]): string {\n    if (configs.length === 0) {\n      return \"\";\n    }\n\n    return configs.map((config) => this.buildSingleExpand(config)).join(\",\");\n  }\n\n  /**\n   * Builds validation configs for expanded navigation properties.\n   */\n  buildValidationConfigs(configs: ExpandConfig[]): ExpandValidationConfig[] {\n    return configs.map((config) => {\n      const targetTable = config.targetTable;\n\n      let targetSchema: Partial<Record<string, StandardSchemaV1>> | undefined;\n      if (targetTable) {\n        const baseTableConfig = getBaseTableConfig(targetTable);\n        const containerFields = baseTableConfig.containerFields || [];\n\n        // Filter out container fields from schema\n        const schema = { ...baseTableConfig.schema };\n        for (const containerField of containerFields) {\n          delete schema[containerField as string];\n        }\n\n        targetSchema = schema;\n      }\n\n      let selectedFields: string[] | undefined;\n      if (config.options?.select) {\n        selectedFields = Array.isArray(config.options.select)\n          ? config.options.select.map(String)\n          : [String(config.options.select)];\n      }\n\n      // Recursively build validation configs for nested expands\n      const nestedExpands = config.nestedExpandConfigs\n        ? this.buildValidationConfigs(config.nestedExpandConfigs)\n        : undefined;\n\n      return {\n        relation: config.relation,\n        targetSchema,\n        targetTable,\n        table: targetTable,\n        selectedFields,\n        nestedExpands,\n      };\n    });\n  }\n\n  /**\n   * Process an expand() call and return the expand config.\n   * Used by both QueryBuilder and RecordBuilder to eliminate duplication.\n   *\n   * @param targetTable - The target table to expand to\n   * @param sourceTable - The source table (for validation)\n   * @param callback - Optional callback to configure the expand query\n   * @param builderFactory - Function that creates a QueryBuilder for the target table\n   * @returns ExpandConfig to add to the builder's expandConfigs array\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration, generic Builder type\n  processExpand<TargetTable extends FMTable<any, any>, Builder = any>(\n    targetTable: TargetTable,\n    // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration\n    sourceTable: FMTable<any, any> | undefined,\n    callback?: (builder: Builder) => Builder,\n    builderFactory?: () => Builder,\n  ): ExpandConfig {\n    // Extract name and validate\n    const relationName = getTableName(targetTable);\n\n    // Runtime validation: Check if relation name is in navigationPaths\n    if (sourceTable) {\n      const navigationPaths = getNavigationPaths(sourceTable);\n      if (navigationPaths && !navigationPaths.includes(relationName)) {\n        this.logger.warn(\n          `Cannot expand to \"${relationName}\". Valid navigation paths: ${navigationPaths.length > 0 ? navigationPaths.join(\", \") : \"none\"}`,\n        );\n      }\n    }\n\n    if (callback && builderFactory) {\n      // Create a new QueryBuilder for the target table\n      const targetBuilder = builderFactory();\n\n      // Pass to callback and get configured builder\n      const configuredBuilder = callback(targetBuilder);\n\n      // Extract the builder's query options\n      // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any QueryOptions configuration\n      const expandOptions: Partial<QueryOptions<any>> = {\n        // biome-ignore lint/suspicious/noExplicitAny: Type assertion for internal builder property access\n        ...(configuredBuilder as any).queryOptions,\n      };\n\n      // If callback didn't provide select, apply defaultSelect from target table\n      if (!expandOptions.select) {\n        const defaultFields = getDefaultSelectFields(targetTable);\n        if (defaultFields) {\n          expandOptions.select = defaultFields;\n        }\n      }\n\n      // If the configured builder has nested expands, we need to include them\n      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for internal builder property access\n      const nestedExpandConfigs = (configuredBuilder as any).expandConfigs;\n      if (nestedExpandConfigs?.length > 0) {\n        // Build nested expand string from the configured builder's expand configs\n        const nestedExpandString = this.buildExpandString(nestedExpandConfigs);\n        if (nestedExpandString) {\n          // Add nested expand to options\n          // biome-ignore lint/suspicious/noExplicitAny: Type assertion for expand string\n          expandOptions.expand = nestedExpandString as any;\n        }\n      }\n\n      return {\n        relation: relationName,\n        options: expandOptions,\n        targetTable,\n        nestedExpandConfigs: nestedExpandConfigs?.length > 0 ? nestedExpandConfigs : undefined,\n      };\n    }\n    // Simple expand without callback - apply defaultSelect if available\n    const defaultFields = getDefaultSelectFields(targetTable);\n    if (defaultFields) {\n      return {\n        relation: relationName,\n        options: { select: defaultFields },\n        targetTable,\n      };\n    }\n    return {\n      relation: relationName,\n      targetTable,\n    };\n  }\n\n  /**\n   * Builds a single expand string with its options.\n   */\n  private buildSingleExpand(config: ExpandConfig): string {\n    const relationName = this.resolveRelationName(config);\n    const parts = this.buildExpandParts(config);\n\n    if (parts.length === 0) {\n      return relationName;\n    }\n\n    return `${relationName}(${parts.join(\";\")})`;\n  }\n\n  /**\n   * Resolves relation name, using FMTID if entity IDs are enabled.\n   */\n  private resolveRelationName(config: ExpandConfig): string {\n    if (!this.useEntityIds) {\n      return config.relation;\n    }\n\n    const targetTable = config.targetTable;\n    if (targetTable && FMTable.Symbol.EntityId in targetTable) {\n      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for Symbol property access\n      const tableId = (targetTable as any)[FMTable.Symbol.EntityId] as `FMTID:${string}` | undefined;\n      if (tableId) {\n        return tableId;\n      }\n    }\n\n    return config.relation;\n  }\n\n  /**\n   * Builds expand parts (select, filter, orderBy, etc.) for a single expand.\n   */\n  private buildExpandParts(config: ExpandConfig): string[] {\n    if (!config.options || Object.keys(config.options).length === 0) {\n      return [];\n    }\n\n    const parts: string[] = [];\n    const opts = config.options;\n\n    if (opts.select) {\n      const selectArray = Array.isArray(opts.select) ? opts.select.map(String) : [String(opts.select)];\n      const selectFields = formatSelectFields(selectArray, config.targetTable, this.useEntityIds);\n      parts.push(`$select=${selectFields}`);\n    }\n\n    if (opts.filter) {\n      const filterQuery = buildQuery({ filter: opts.filter });\n      const match = filterQuery.match(FILTER_QUERY_REGEX);\n      if (match) {\n        parts.push(`$filter=${match[1]}`);\n      }\n    }\n\n    if (opts.orderBy) {\n      const orderByValue = Array.isArray(opts.orderBy) ? opts.orderBy.join(\",\") : String(opts.orderBy);\n      parts.push(`$orderby=${orderByValue}`);\n    }\n\n    if (opts.top !== undefined) {\n      parts.push(`$top=${opts.top}`);\n    }\n    if (opts.skip !== undefined) {\n      parts.push(`$skip=${opts.skip}`);\n    }\n\n    if (opts.expand && typeof opts.expand === \"string\") {\n      parts.push(`$expand=${opts.expand}`);\n    }\n\n    return parts;\n  }\n}\n"],"names":["defaultFields"],"mappings":"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"}

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

@@ -0,0 +1,9 @@
+/** biome-ignore-all lint/performance/noBarrelFile: Re-exporting all builder utilities */
+export * from './default-select.js';
+export * from './expand-builder.js';
+export * from './query-string-builder.js';
+export * from './response-processor.js';
+export * from './select-mixin.js';
+export * from './select-utils.js';
+export * from './shared-types.js';
+export * from './table-utils.js';

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

@@ -0,0 +1,18 @@
+import { InternalLogger } from '../../logger.js';
+import { FMTable } from '../../orm/table.js';
+import { ExpandConfig } from './shared-types.js';
+/**
+ * Builds OData query string for $select and $expand parameters.
+ * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+ *
+ * @param config - Configuration object
+ * @returns Query string starting with ? or empty string if no parameters
+ */
+export declare function buildSelectExpandQueryString(config: {
+    selectedFields?: string[];
+    expandConfigs: ExpandConfig[];
+    table?: FMTable<any, any>;
+    useEntityIds: boolean;
+    logger: InternalLogger;
+    includeSpecialColumns?: boolean;
+}): string;

package/dist/esm/client/builders/query-string-builder.js

@@ -0,0 +1,21 @@
+import { ExpandBuilder } from "./expand-builder.js";
+import { formatSelectFields } from "./select-utils.js";
+function buildSelectExpandQueryString(config) {
+  const parts = [];
+  const expandBuilder = new ExpandBuilder(config.useEntityIds, config.logger);
+  if (config.selectedFields && config.selectedFields.length > 0) {
+    const selectString = formatSelectFields(config.selectedFields, config.table, config.useEntityIds);
+    if (selectString) {
+      parts.push(`$select=${selectString}`);
+    }
+  }
+  const expandString = expandBuilder.buildExpandString(config.expandConfigs);
+  if (expandString) {
+    parts.push(`$expand=${expandString}`);
+  }
+  return parts.length > 0 ? `?${parts.join("&")}` : "";
+}
+export {
+  buildSelectExpandQueryString
+};
+//# sourceMappingURL=query-string-builder.js.map

package/dist/esm/client/builders/query-string-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-string-builder.js","sources":["../../../../src/client/builders/query-string-builder.ts"],"sourcesContent":["import type { InternalLogger } from \"../../logger\";\nimport type { FMTable } from \"../../orm/table\";\nimport { ExpandBuilder } from \"./expand-builder\";\nimport { formatSelectFields } from \"./select-utils\";\nimport type { ExpandConfig } from \"./shared-types\";\n\n/**\n * Builds OData query string for $select and $expand parameters.\n * Used by both QueryBuilder and RecordBuilder to eliminate duplication.\n *\n * @param config - Configuration object\n * @returns Query string starting with ? or empty string if no parameters\n */\nexport function buildSelectExpandQueryString(config: {\n  selectedFields?: string[];\n  expandConfigs: ExpandConfig[];\n  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration\n  table?: FMTable<any, any>;\n  useEntityIds: boolean;\n  logger: InternalLogger;\n  includeSpecialColumns?: boolean;\n}): string {\n  const parts: string[] = [];\n  const expandBuilder = new ExpandBuilder(config.useEntityIds, config.logger);\n\n  // Build $select\n  if (config.selectedFields && config.selectedFields.length > 0) {\n    // Important: do NOT implicitly add system columns (ROWID/ROWMODID) here.\n    // - `includeSpecialColumns` controls the Prefer header + response parsing, but should not\n    //   mutate/expand an explicit `$select` (e.g. when the user calls `.select({ ... })`).\n    // - If system columns are desired with `.select()`, they must be explicitly included via\n    //   the `systemColumns` argument, which will already have added them to `selectedFields`.\n    const selectString = formatSelectFields(config.selectedFields, config.table, config.useEntityIds);\n    if (selectString) {\n      parts.push(`$select=${selectString}`);\n    }\n  }\n\n  // Build $expand\n  const expandString = expandBuilder.buildExpandString(config.expandConfigs);\n  if (expandString) {\n    parts.push(`$expand=${expandString}`);\n  }\n\n  return parts.length > 0 ? `?${parts.join(\"&\")}` : \"\";\n}\n"],"names":[],"mappings":";;AAaO,SAAS,6BAA6B,QAQlC;AACT,QAAM,QAAkB,CAAA;AACxB,QAAM,gBAAgB,IAAI,cAAc,OAAO,cAAc,OAAO,MAAM;AAG1E,MAAI,OAAO,kBAAkB,OAAO,eAAe,SAAS,GAAG;AAM7D,UAAM,eAAe,mBAAmB,OAAO,gBAAgB,OAAO,OAAO,OAAO,YAAY;AAChG,QAAI,cAAc;AAChB,YAAM,KAAK,WAAW,YAAY,EAAE;AAAA,IACtC;AAAA,EACF;AAGA,QAAM,eAAe,cAAc,kBAAkB,OAAO,aAAa;AACzE,MAAI,cAAc;AAChB,UAAM,KAAK,WAAW,YAAY,EAAE;AAAA,EACtC;AAEA,SAAO,MAAM,SAAS,IAAI,IAAI,MAAM,KAAK,GAAG,CAAC,KAAK;AACpD;"}

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

@@ -0,0 +1,43 @@
+import { InternalLogger } from '../../logger.js';
+import { FMTable } from '../../orm/table.js';
+import { Result } from '../../types.js';
+import { ExpandValidationConfig } from '../../validation.js';
+import { ExpandConfig } from './shared-types.js';
+export interface ProcessResponseConfig {
+    table?: FMTable<any, any>;
+    schema?: Record<string, any>;
+    singleMode: "exact" | "maybe" | false;
+    selectedFields?: string[];
+    expandValidationConfigs?: ExpandValidationConfig[];
+    skipValidation?: boolean;
+    useEntityIds?: boolean;
+    includeSpecialColumns?: boolean;
+    fieldMapping?: Record<string, string>;
+}
+/**
+ * Processes OData response with transformation and validation.
+ * Shared by QueryBuilder and RecordBuilder.
+ */
+export declare function processODataResponse<T>(rawResponse: any, config: ProcessResponseConfig): Promise<Result<T>>;
+/**
+ * Gets schema from a table occurrence, excluding container fields.
+ * Container fields are never returned in regular responses (only via getSingleField).
+ */
+export declare function getSchemaFromTable(table: FMTable<any, any> | undefined): Record<string, any> | undefined;
+/**
+ * Processes query response with expand configs.
+ * This is a convenience wrapper that builds validation configs from expand configs.
+ */
+export declare function processQueryResponse<T>(response: any, config: {
+    occurrence?: FMTable<any, any>;
+    singleMode: "exact" | "maybe" | false;
+    queryOptions: {
+        select?: (keyof T)[] | string[];
+    };
+    expandConfigs: ExpandConfig[];
+    skipValidation?: boolean;
+    useEntityIds?: boolean;
+    includeSpecialColumns?: boolean;
+    fieldMapping?: Record<string, string>;
+    logger: InternalLogger;
+}): Promise<Result<any>>;

package/dist/esm/client/builders/response-processor.js

@@ -0,0 +1,175 @@
+import { RecordCountMismatchError } from "../../errors.js";
+import { getBaseTableConfig } from "../../orm/table.js";
+import { transformResponseFields } from "../../transform.js";
+import { validateSingleResponse, validateListResponse } from "../../validation.js";
+import { ExpandBuilder } from "./expand-builder.js";
+async function processODataResponse(rawResponse, config) {
+  const {
+    table,
+    schema,
+    singleMode,
+    selectedFields,
+    expandValidationConfigs,
+    skipValidation,
+    useEntityIds,
+    includeSpecialColumns,
+    fieldMapping
+  } = config;
+  let response = rawResponse;
+  if (table && useEntityIds) {
+    response = transformResponseFields(response, table, expandValidationConfigs);
+  }
+  if (skipValidation) {
+    const result = extractRecords(response, singleMode);
+    if (result.data && fieldMapping && Object.keys(fieldMapping).length > 0) {
+      if (result.error) {
+        return { data: void 0, error: result.error };
+      }
+      return {
+        data: renameFieldsInResponse(result.data, fieldMapping),
+        error: void 0
+      };
+    }
+    return result;
+  }
+  if (singleMode !== false) {
+    const validation2 = await validateSingleResponse(
+      response,
+      schema,
+      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic type parameter
+      selectedFields,
+      expandValidationConfigs,
+      singleMode,
+      includeSpecialColumns
+    );
+    if (!validation2.valid) {
+      return { data: void 0, error: validation2.error };
+    }
+    if (fieldMapping && Object.keys(fieldMapping).length > 0) {
+      return {
+        data: renameFieldsInResponse(validation2.data, fieldMapping),
+        error: void 0
+      };
+    }
+    return { data: validation2.data, error: void 0 };
+  }
+  const validation = await validateListResponse(
+    response,
+    schema,
+    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic type parameter
+    selectedFields,
+    expandValidationConfigs,
+    includeSpecialColumns
+  );
+  if (!validation.valid) {
+    return { data: void 0, error: validation.error };
+  }
+  if (fieldMapping && Object.keys(fieldMapping).length > 0) {
+    return {
+      data: renameFieldsInResponse(validation.data, fieldMapping),
+      error: void 0
+    };
+  }
+  return { data: validation.data, error: void 0 };
+}
+function extractRecords(response, singleMode) {
+  if (singleMode === false) {
+    const records2 = response.value ?? [];
+    return { data: records2, error: void 0 };
+  }
+  const records = response.value ?? [response];
+  const count = Array.isArray(records) ? records.length : 1;
+  if (count > 1) {
+    return {
+      data: void 0,
+      error: new RecordCountMismatchError(singleMode === "exact" ? "one" : "at-most-one", count)
+    };
+  }
+  if (count === 0) {
+    if (singleMode === "exact") {
+      return { data: void 0, error: new RecordCountMismatchError("one", 0) };
+    }
+    return { data: null, error: void 0 };
+  }
+  const record = Array.isArray(records) ? records[0] : records;
+  return { data: record, error: void 0 };
+}
+function getSchemaFromTable(table) {
+  if (!table) {
+    return void 0;
+  }
+  const baseTableConfig = getBaseTableConfig(table);
+  const containerFields = baseTableConfig.containerFields || [];
+  const schema = { ...baseTableConfig.schema };
+  for (const containerField of containerFields) {
+    delete schema[containerField];
+  }
+  return schema;
+}
+function renameFieldsInResponse(data, fieldMapping) {
+  if (!data || typeof data !== "object") {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    return data.map((item) => renameFieldsInResponse(item, fieldMapping));
+  }
+  if ("value" in data && Array.isArray(data.value)) {
+    return {
+      ...data,
+      // biome-ignore lint/suspicious/noExplicitAny: Dynamic record transformation
+      value: data.value.map((item) => renameFieldsInResponse(item, fieldMapping))
+    };
+  }
+  const renamed = {};
+  for (const [key, value] of Object.entries(data)) {
+    const outputKey = fieldMapping[key];
+    if (outputKey) {
+      renamed[outputKey] = value;
+    } else {
+      renamed[key] = value;
+    }
+  }
+  return renamed;
+}
+async function processQueryResponse(response, config) {
+  const {
+    occurrence,
+    singleMode,
+    queryOptions,
+    expandConfigs,
+    skipValidation,
+    useEntityIds,
+    includeSpecialColumns,
+    fieldMapping,
+    logger
+  } = config;
+  const expandBuilder = new ExpandBuilder(useEntityIds ?? false, logger);
+  const expandValidationConfigs = expandBuilder.buildValidationConfigs(expandConfigs);
+  let selectedFields;
+  if (queryOptions.select) {
+    selectedFields = Array.isArray(queryOptions.select) ? queryOptions.select.map(String) : [String(queryOptions.select)];
+  }
+  let processedResponse = await processODataResponse(response, {
+    table: occurrence,
+    schema: getSchemaFromTable(occurrence),
+    singleMode,
+    selectedFields,
+    expandValidationConfigs,
+    skipValidation,
+    useEntityIds,
+    includeSpecialColumns
+  });
+  if (processedResponse.data && fieldMapping && Object.keys(fieldMapping).length > 0) {
+    processedResponse = {
+      ...processedResponse,
+      data: renameFieldsInResponse(processedResponse.data, fieldMapping)
+    };
+  }
+  return processedResponse;
+}
+export {
+  getSchemaFromTable,
+  processODataResponse,
+  processQueryResponse
+};
+//# sourceMappingURL=response-processor.js.map

package/dist/esm/client/builders/response-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-processor.js","sources":["../../../../src/client/builders/response-processor.ts"],"sourcesContent":["import { RecordCountMismatchError } from \"../../errors\";\nimport type { InternalLogger } from \"../../logger\";\nimport type { FMTable } from \"../../orm/table\";\nimport { getBaseTableConfig } from \"../../orm/table\";\nimport { transformResponseFields } from \"../../transform\";\nimport type { Result } from \"../../types\";\nimport type { ExpandValidationConfig } from \"../../validation\";\nimport { validateListResponse, validateSingleResponse } from \"../../validation\";\nimport { ExpandBuilder } from \"./expand-builder\";\nimport type { ExpandConfig } from \"./shared-types\";\n\nexport interface ProcessResponseConfig {\n  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration\n  table?: FMTable<any, any>;\n  // biome-ignore lint/suspicious/noExplicitAny: Dynamic schema shape from table configuration\n  schema?: Record<string, any>;\n  singleMode: \"exact\" | \"maybe\" | false;\n  selectedFields?: string[];\n  expandValidationConfigs?: ExpandValidationConfig[];\n  skipValidation?: boolean;\n  useEntityIds?: boolean;\n  includeSpecialColumns?: boolean;\n  // Mapping from field names to output keys (for renamed fields in select)\n  fieldMapping?: Record<string, string>;\n}\n\n/**\n * Processes OData response with transformation and validation.\n * Shared by QueryBuilder and RecordBuilder.\n */\n// biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API\nexport async function processODataResponse<T>(rawResponse: any, config: ProcessResponseConfig): Promise<Result<T>> {\n  const {\n    table,\n    schema,\n    singleMode,\n    selectedFields,\n    expandValidationConfigs,\n    skipValidation,\n    useEntityIds,\n    includeSpecialColumns,\n    fieldMapping,\n  } = config;\n\n  // Transform field IDs back to names if using entity IDs\n  let response = rawResponse;\n  if (table && useEntityIds) {\n    response = transformResponseFields(response, table, expandValidationConfigs);\n  }\n\n  // Fast path: skip validation\n  if (skipValidation) {\n    const result = extractRecords(response, singleMode);\n    // Rename fields AFTER extraction (but before returning)\n    if (result.data && fieldMapping && Object.keys(fieldMapping).length > 0) {\n      if (result.error) {\n        return { data: undefined, error: result.error } as Result<T>;\n      }\n      return {\n        data: renameFieldsInResponse(result.data, fieldMapping) as T,\n        error: undefined,\n      };\n    }\n    return result as Result<T>;\n  }\n\n  // Validation path\n  // Note: Special columns are excluded when using QueryBuilder.single() method,\n  // but included for RecordBuilder.get() method (both use singleMode: \"exact\")\n  // The exclusion is handled in QueryBuilder's processQueryResponse, not here\n  if (singleMode !== false) {\n    // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape\n    const validation = await validateSingleResponse<any>(\n      response,\n      schema,\n      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic type parameter\n      selectedFields as any,\n      expandValidationConfigs,\n      singleMode,\n      includeSpecialColumns,\n    );\n\n    if (!validation.valid) {\n      return { data: undefined, error: validation.error };\n    }\n\n    // Rename fields AFTER validation completes\n    if (fieldMapping && Object.keys(fieldMapping).length > 0) {\n      return {\n        data: renameFieldsInResponse(validation.data, fieldMapping) as T,\n        error: undefined,\n      };\n    }\n\n    return { data: validation.data as T, error: undefined };\n  }\n\n  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape\n  const validation = await validateListResponse<any>(\n    response,\n    schema,\n    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic type parameter\n    selectedFields as any,\n    expandValidationConfigs,\n    includeSpecialColumns,\n  );\n\n  if (!validation.valid) {\n    return { data: undefined, error: validation.error };\n  }\n\n  // Rename fields AFTER validation completes\n  if (fieldMapping && Object.keys(fieldMapping).length > 0) {\n    return {\n      data: renameFieldsInResponse(validation.data, fieldMapping) as T,\n      error: undefined,\n    };\n  }\n\n  return { data: validation.data as T, error: undefined };\n}\n\n/**\n * Extracts records from response without validation.\n */\n// biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API\nfunction extractRecords<T>(response: any, singleMode: \"exact\" | \"maybe\" | false): Result<T> {\n  if (singleMode === false) {\n    const records = response.value ?? [];\n    return { data: records as T, error: undefined };\n  }\n\n  const records = response.value ?? [response];\n  const count = Array.isArray(records) ? records.length : 1;\n\n  if (count > 1) {\n    return {\n      data: undefined,\n      error: new RecordCountMismatchError(singleMode === \"exact\" ? \"one\" : \"at-most-one\", count),\n    };\n  }\n\n  if (count === 0) {\n    if (singleMode === \"exact\") {\n      return { data: undefined, error: new RecordCountMismatchError(\"one\", 0) };\n    }\n    return { data: null as T, error: undefined };\n  }\n\n  const record = Array.isArray(records) ? records[0] : records;\n  return { data: record as T, error: undefined };\n}\n\n/**\n * Gets schema from a table occurrence, excluding container fields.\n * Container fields are never returned in regular responses (only via getSingleField).\n */\n// biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration, dynamic schema shape\nexport function getSchemaFromTable(table: FMTable<any, any> | undefined): Record<string, any> | undefined {\n  if (!table) {\n    return undefined;\n  }\n  const baseTableConfig = getBaseTableConfig(table);\n  const containerFields = baseTableConfig.containerFields || [];\n\n  // Filter out container fields from schema\n  const schema = { ...baseTableConfig.schema };\n  for (const containerField of containerFields) {\n    delete schema[containerField as string];\n  }\n\n  return schema;\n}\n\n/**\n * Renames fields in response data according to the field mapping.\n * Used when select() is called with renamed fields (e.g., { userEmail: users.email }).\n */\n// biome-ignore lint/suspicious/noExplicitAny: Dynamic response data transformation\nfunction renameFieldsInResponse(data: any, fieldMapping: Record<string, string>): any {\n  if (!data || typeof data !== \"object\") {\n    return data;\n  }\n\n  // Handle array responses\n  if (Array.isArray(data)) {\n    return data.map((item) => renameFieldsInResponse(item, fieldMapping));\n  }\n\n  // Handle OData list response structure\n  if (\"value\" in data && Array.isArray(data.value)) {\n    return {\n      ...data,\n      // biome-ignore lint/suspicious/noExplicitAny: Dynamic record transformation\n      value: data.value.map((item: any) => renameFieldsInResponse(item, fieldMapping)),\n    };\n  }\n\n  // Handle single record\n  // biome-ignore lint/suspicious/noExplicitAny: Dynamic field transformation\n  const renamed: Record<string, any> = {};\n  for (const [key, value] of Object.entries(data)) {\n    // Check if this field should be renamed\n    const outputKey = fieldMapping[key];\n    if (outputKey) {\n      renamed[outputKey] = value;\n    } else {\n      renamed[key] = value;\n    }\n  }\n  return renamed;\n}\n\n/**\n * Processes query response with expand configs.\n * This is a convenience wrapper that builds validation configs from expand configs.\n */\nexport async function processQueryResponse<T>(\n  // biome-ignore lint/suspicious/noExplicitAny: Dynamic response type from OData API\n  response: any,\n  config: {\n    // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration\n    occurrence?: FMTable<any, any>;\n    singleMode: \"exact\" | \"maybe\" | false;\n    queryOptions: { select?: (keyof T)[] | string[] };\n    expandConfigs: ExpandConfig[];\n    skipValidation?: boolean;\n    useEntityIds?: boolean;\n    includeSpecialColumns?: boolean;\n    // Mapping from field names to output keys (for renamed fields in select)\n    fieldMapping?: Record<string, string>;\n    logger: InternalLogger;\n  },\n  // biome-ignore lint/suspicious/noExplicitAny: Generic return type for interface compliance\n): Promise<Result<any>> {\n  const {\n    occurrence,\n    singleMode,\n    queryOptions,\n    expandConfigs,\n    skipValidation,\n    useEntityIds,\n    includeSpecialColumns,\n    fieldMapping,\n    logger,\n  } = config;\n\n  const expandBuilder = new ExpandBuilder(useEntityIds ?? false, logger);\n  const expandValidationConfigs = expandBuilder.buildValidationConfigs(expandConfigs);\n\n  let selectedFields: string[] | undefined;\n  if (queryOptions.select) {\n    selectedFields = Array.isArray(queryOptions.select)\n      ? queryOptions.select.map(String)\n      : [String(queryOptions.select)];\n  }\n\n  // Process the response first\n  let processedResponse = await processODataResponse(response, {\n    table: occurrence,\n    schema: getSchemaFromTable(occurrence),\n    singleMode,\n    selectedFields,\n    expandValidationConfigs,\n    skipValidation,\n    useEntityIds,\n    includeSpecialColumns,\n  });\n\n  // Rename fields if field mapping is provided (for renamed fields in select)\n  if (processedResponse.data && fieldMapping && Object.keys(fieldMapping).length > 0) {\n    processedResponse = {\n      ...processedResponse,\n      data: renameFieldsInResponse(processedResponse.data, fieldMapping),\n    };\n  }\n\n  return processedResponse;\n}\n"],"names":["validation","records"],"mappings":"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"}

package/dist/esm/client/builders/select-mixin.d.ts

@@ -0,0 +1,25 @@
+import { InternalLogger } from '../../logger.js';
+import { Column } from '../../orm/column.js';
+/**
+ * Utility function for processing select() calls.
+ * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+ *
+ * @param fields - Field names or Column references
+ * @returns Object with selectedFields array
+ */
+export declare function processSelectFields(...fields: (string | Column<any, any, string>)[]): {
+    selectedFields: string[];
+};
+/**
+ * Processes select() calls with field renaming support.
+ * Validates columns belong to the correct table and builds field mapping for renamed fields.
+ * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+ *
+ * @param fields - Object mapping output keys to column references
+ * @param tableName - Expected table name for validation
+ * @returns Object with selectedFields array and fieldMapping for renamed fields
+ */
+export declare function processSelectWithRenames<TTableName extends string>(fields: Record<string, Column<any, any, TTableName>>, tableName: string, logger: InternalLogger): {
+    selectedFields: string[];
+    fieldMapping: Record<string, string>;
+};

package/dist/esm/client/builders/select-mixin.js

@@ -0,0 +1,28 @@
+import { isColumn } from "../../orm/column.js";
+function processSelectWithRenames(fields, tableName, logger) {
+  const selectedFields = [];
+  const fieldMapping = {};
+  for (const [outputKey, column] of Object.entries(fields)) {
+    if (!isColumn(column)) {
+      throw new Error(`select() expects column references, but got: ${typeof column}`);
+    }
+    if (column.tableName !== tableName) {
+      logger.warn(
+        `Column ${column.toString()} is from table "${column.tableName}", but query is for table "${tableName}"`
+      );
+    }
+    const fieldName = column.fieldName;
+    selectedFields.push(fieldName);
+    if (fieldName !== outputKey) {
+      fieldMapping[fieldName] = outputKey;
+    }
+  }
+  return {
+    selectedFields,
+    fieldMapping: Object.keys(fieldMapping).length > 0 ? fieldMapping : {}
+  };
+}
+export {
+  processSelectWithRenames
+};
+//# sourceMappingURL=select-mixin.js.map

package/dist/esm/client/builders/select-mixin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-mixin.js","sources":["../../../../src/client/builders/select-mixin.ts"],"sourcesContent":["import type { InternalLogger } from \"../../logger\";\nimport { type Column, isColumn } from \"../../orm/column\";\n\n/**\n * Utility function for processing select() calls.\n * Used by both QueryBuilder and RecordBuilder to eliminate duplication.\n *\n * @param fields - Field names or Column references\n * @returns Object with selectedFields array\n */\n// biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration\nexport function processSelectFields(...fields: (string | Column<any, any, string>)[]): { selectedFields: string[] } {\n  const fieldNames = fields.map((field) => {\n    if (isColumn(field)) {\n      return field.fieldName as string;\n    }\n    return String(field);\n  });\n  return { selectedFields: [...new Set(fieldNames)] };\n}\n\n/**\n * Processes select() calls with field renaming support.\n * Validates columns belong to the correct table and builds field mapping for renamed fields.\n * Used by both QueryBuilder and RecordBuilder to eliminate duplication.\n *\n * @param fields - Object mapping output keys to column references\n * @param tableName - Expected table name for validation\n * @returns Object with selectedFields array and fieldMapping for renamed fields\n */\nexport function processSelectWithRenames<TTableName extends string>(\n  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any Column configuration\n  fields: Record<string, Column<any, any, TTableName>>,\n  tableName: string,\n  logger: InternalLogger,\n): { selectedFields: string[]; fieldMapping: Record<string, string> } {\n  const selectedFields: string[] = [];\n  const fieldMapping: Record<string, string> = {};\n\n  for (const [outputKey, column] of Object.entries(fields)) {\n    if (!isColumn(column)) {\n      throw new Error(`select() expects column references, but got: ${typeof column}`);\n    }\n\n    // Warn (not throw) on table mismatch for consistency\n    if (column.tableName !== tableName) {\n      logger.warn(\n        `Column ${column.toString()} is from table \"${column.tableName}\", but query is for table \"${tableName}\"`,\n      );\n    }\n\n    const fieldName = column.fieldName;\n    selectedFields.push(fieldName);\n\n    // Build mapping from field name to output key (only if renamed)\n    if (fieldName !== outputKey) {\n      fieldMapping[fieldName] = outputKey;\n    }\n  }\n\n  return {\n    selectedFields,\n    fieldMapping: Object.keys(fieldMapping).length > 0 ? fieldMapping : {},\n  };\n}\n"],"names":[],"mappings":";AA8BO,SAAS,yBAEd,QACA,WACA,QACoE;AACpE,QAAM,iBAA2B,CAAA;AACjC,QAAM,eAAuC,CAAA;AAE7C,aAAW,CAAC,WAAW,MAAM,KAAK,OAAO,QAAQ,MAAM,GAAG;AACxD,QAAI,CAAC,SAAS,MAAM,GAAG;AACrB,YAAM,IAAI,MAAM,gDAAgD,OAAO,MAAM,EAAE;AAAA,IACjF;AAGA,QAAI,OAAO,cAAc,WAAW;AAClC,aAAO;AAAA,QACL,UAAU,OAAO,UAAU,mBAAmB,OAAO,SAAS,8BAA8B,SAAS;AAAA,MAAA;AAAA,IAEzG;AAEA,UAAM,YAAY,OAAO;AACzB,mBAAe,KAAK,SAAS;AAG7B,QAAI,cAAc,WAAW;AAC3B,mBAAa,SAAS,IAAI;AAAA,IAC5B;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA,cAAc,OAAO,KAAK,YAAY,EAAE,SAAS,IAAI,eAAe,CAAA;AAAA,EAAC;AAEzE;"}

package/dist/esm/client/builders/select-utils.d.ts

@@ -0,0 +1,18 @@
+import { FMTable } from '../../orm/table.js';
+/**
+ * Determines if a field name needs to be quoted in OData queries.
+ * Per FileMaker docs: field names with special characters (spaces, underscores, etc.) must be quoted.
+ * Also quotes "id" as it's an OData reserved word.
+ * Entity IDs (FMFID:*, FMTID:*) are not quoted as they're identifiers, not field names.
+ *
+ * @param fieldName - The field name or identifier to check
+ * @returns true if the field name should be quoted in OData queries
+ */
+export declare function needsFieldQuoting(fieldName: string): boolean;
+/**
+ * Formats select fields for use in OData query strings.
+ * - Transforms field names to FMFIDs if using entity IDs
+ * - Wraps "id" fields in double quotes (OData reserved)
+ * - URL-encodes special characters but preserves spaces
+ */
+export declare function formatSelectFields(select: string[] | readonly string[] | undefined, table?: FMTable<any, any>, useEntityIds?: boolean): string;