@proofkit/fmodata 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/esm/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import { type FFetchOptions } from \"@fetchkit/ffetch\";\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\nexport type Auth = { username: string; password: string } | { apiKey: string };\n\nexport interface ExecutableBuilder<T> {\n  execute(): Promise<Result<T>>;\n  getRequestConfig(): { method: string; url: string; body?: any };\n\n  /**\n   * Convert this builder to a native Request object for batch processing.\n   * @param baseUrl - The base URL for the OData service\n   * @param options - Optional execution options (e.g., includeODataAnnotations)\n   * @returns A native Request object\n   */\n  toRequest(baseUrl: string, options?: ExecuteOptions): Request;\n\n  /**\n   * Process a raw Response object into a typed Result.\n   * This allows builders to apply their own validation and transformation logic.\n   * @param response - The native Response object from the batch operation\n   * @param options - Optional execution options (e.g., skipValidation, includeODataAnnotations)\n   * @returns A typed Result with the builder's expected return type\n   */\n  processResponse(\n    response: Response,\n    options?: ExecuteOptions,\n  ): Promise<Result<T>>;\n}\n\nexport interface ExecutionContext {\n  _makeRequest<T>(\n    url: string,\n    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },\n  ): Promise<Result<T>>;\n  _setUseEntityIds?(useEntityIds: boolean): void;\n  _getUseEntityIds?(): boolean;\n  _getBaseUrl?(): string;\n}\n\nexport type InferSchemaType<Schema extends Record<string, StandardSchemaV1>> = {\n  [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output>\n    ? Output\n    : never;\n};\n\nexport type WithSystemFields<T> =\n  T extends Record<string, any>\n    ? T & {\n        ROWID: number;\n        ROWMODID: number;\n      }\n    : never;\n\n// Helper type to exclude system fields from a union of keys\nexport type ExcludeSystemFields<T extends keyof any> = Exclude<\n  T,\n  \"ROWID\" | \"ROWMODID\"\n>;\n\n// Helper type to omit system fields from an object type\nexport type OmitSystemFields<T> = Omit<T, \"ROWID\" | \"ROWMODID\">;\n\n// OData record metadata fields (present on each record)\nexport type ODataRecordMetadata = {\n  \"@id\": string;\n  \"@editLink\": string;\n};\n\n// OData response wrapper (top-level, internal use only)\nexport type ODataListResponse<T> = {\n  \"@context\": string;\n  value: (T & ODataRecordMetadata)[];\n};\n\nexport type ODataSingleResponse<T> = T &\n  ODataRecordMetadata & {\n    \"@context\": string;\n  };\n\n// OData response for single field values\nexport type ODataFieldResponse<T> = {\n  \"@context\": string;\n  value: T;\n};\n\n// Result pattern for execute responses\nexport type Result<T, E = import(\"./errors\").FMODataErrorType> =\n  | { data: T; error: undefined }\n  | { data: undefined; error: E };\n\n// Batch operation result types\nexport type BatchItemResult<T> = {\n  data: T | undefined;\n  error: import(\"./errors\").FMODataErrorType | undefined;\n  status: number; // HTTP status code (0 for truncated)\n};\n\nexport type BatchResult<T extends readonly any[]> = {\n  results: { [K in keyof T]: BatchItemResult<T[K]> };\n  successCount: number;\n  errorCount: number;\n  truncated: boolean;\n  firstErrorIndex: number | null;\n};\n\n// Make specific keys required, rest optional\nexport type MakeFieldsRequired<T, Keys extends keyof T> = Partial<T> &\n  Required<Pick<T, Keys>>;\n\n// Extract keys from schema where validator doesn't allow null/undefined (auto-required fields)\nexport type AutoRequiredKeys<Schema extends Record<string, StandardSchemaV1>> =\n  {\n    [K in keyof Schema]: Extract<\n      StandardSchemaV1.InferOutput<Schema[K]>,\n      null | undefined\n    > extends never\n      ? K\n      : never;\n  }[keyof Schema];\n\n// Helper type to compute excluded fields (readOnly fields + idField)\nexport type ExcludedFields<\n  IdField extends keyof any | undefined,\n  ReadOnly extends readonly any[],\n> = IdField extends keyof any ? IdField | ReadOnly[number] : ReadOnly[number];\n\n// Helper type for InsertData computation\ntype ComputeInsertData<\n  Schema extends Record<string, StandardSchemaV1>,\n  IdField extends keyof Schema | undefined,\n  Required extends readonly any[],\n  ReadOnly extends readonly any[],\n> = [Required[number]] extends [keyof InferSchemaType<Schema>]\n  ? Required extends readonly (keyof InferSchemaType<Schema>)[]\n    ? MakeFieldsRequired<\n        Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,\n        Exclude<\n          AutoRequiredKeys<Schema> | Required[number],\n          ExcludedFields<IdField, ReadOnly>\n        >\n      >\n    : MakeFieldsRequired<\n        Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,\n        Exclude<AutoRequiredKeys<Schema>, ExcludedFields<IdField, ReadOnly>>\n      >\n  : MakeFieldsRequired<\n      Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,\n      Exclude<AutoRequiredKeys<Schema>, ExcludedFields<IdField, ReadOnly>>\n    >;\n\nexport type ExecuteOptions = {\n  includeODataAnnotations?: boolean;\n  skipValidation?: boolean;\n  /**\n   * Overrides the default behavior of the database to use entity IDs (rather than field names) in THIS REQUEST ONLY\n   */\n  useEntityIds?: boolean;\n};\n\n/**\n * Type for the fetchHandler callback function.\n * This is a convenience type export that matches the fetchHandler signature in FFetchOptions.\n *\n * @example\n * ```typescript\n * import type { FetchHandler } from '@proofkit/fmodata';\n *\n * const myFetchHandler: FetchHandler = (input, init) => {\n *   console.log('Custom fetch:', input);\n *   return fetch(input, init);\n * };\n *\n * await query.execute({\n *   fetchHandler: myFetchHandler\n * });\n * ```\n */\nexport type FetchHandler = (\n  input: RequestInfo | URL,\n  init?: RequestInit,\n) => Promise<Response>;\n\n/**\n * Combined type for execute() method options.\n *\n * Uses FFetchOptions from @fetchkit/ffetch to ensure proper type inference.\n * FFetchOptions is re-exported in the package to ensure type availability in consuming packages.\n */\nexport type ExecuteMethodOptions<EO extends ExecuteOptions = ExecuteOptions> =\n  RequestInit & FFetchOptions & ExecuteOptions & EO;\n\n/**\n * Get the Accept header value based on includeODataAnnotations option\n * @param includeODataAnnotations - Whether to include OData annotations\n * @returns Accept header value\n */\nexport function getAcceptHeader(includeODataAnnotations?: boolean): string {\n  return includeODataAnnotations === true\n    ? \"application/json\"\n    : \"application/json;odata.metadata=none\";\n}\n\nexport type ConditionallyWithODataAnnotations<\n  T,\n  IncludeODataAnnotations extends boolean,\n> = IncludeODataAnnotations extends true\n  ? T & {\n      \"@id\": string;\n      \"@editLink\": string;\n    }\n  : T;\n\n// Helper type to extract schema from a FMTable\nexport type ExtractSchemaFromOccurrence<Occ> = Occ extends {\n  baseTable: { schema: infer S };\n}\n  ? S extends Record<string, StandardSchemaV1>\n    ? S\n    : Record<string, StandardSchemaV1>\n  : Record<string, StandardSchemaV1>;\n\nexport type GenericFieldMetadata = {\n  $Nullable?: boolean;\n  \"@Index\"?: boolean;\n  \"@Calculation\"?: boolean;\n  \"@Summary\"?: boolean;\n  \"@Global\"?: boolean;\n  \"@Org.OData.Core.V1.Permissions\"?: \"Org.OData.Core.V1.Permission@Read\";\n};\n\nexport type StringFieldMetadata = GenericFieldMetadata & {\n  $Type: \"Edm.String\";\n  $DefaultValue?: \"USER\" | \"USERNAME\" | \"CURRENT_USER\";\n  $MaxLength?: number;\n};\n\nexport type DecimalFieldMetadata = GenericFieldMetadata & {\n  $Type: \"Edm.Decimal\";\n  \"@AutoGenerated\"?: boolean;\n};\n\nexport type DateFieldMetadata = GenericFieldMetadata & {\n  $Type: \"Edm.Date\";\n  $DefaultValue?: \"CURDATE\" | \"CURRENT_DATE\";\n};\n\nexport type TimeOfDayFieldMetadata = GenericFieldMetadata & {\n  $Type: \"Edm.TimeOfDay\";\n  $DefaultValue?: \"CURTIME\" | \"CURRENT_TIME\";\n};\n\nexport type DateTimeOffsetFieldMetadata = GenericFieldMetadata & {\n  $Type: \"Edm.Date\";\n  $DefaultValue?: \"CURTIMESTAMP\" | \"CURRENT_TIMESTAMP\";\n  \"@VersionId\"?: boolean;\n};\n\nexport type StreamFieldMetadata = {\n  $Type: \"Edm.Stream\";\n  $Nullable?: boolean;\n  \"@EnclosedPath\": string;\n  \"@ExternalOpenPath\": string;\n  \"@ExternalSecurePath\"?: string;\n};\n\nexport type FieldMetadata =\n  | StringFieldMetadata\n  | DecimalFieldMetadata\n  | DateFieldMetadata\n  | TimeOfDayFieldMetadata\n  | DateTimeOffsetFieldMetadata\n  | StreamFieldMetadata;\n\nexport type EntityType = {\n  $Kind: \"EntityType\";\n  $Key: string[];\n} & Record<string, FieldMetadata>;\n\nexport type EntitySet = {\n  $Kind: \"EntitySet\";\n  $Type: string;\n};\n\nexport type Metadata = Record<string, EntityType | EntitySet>;\n"],"names":[],"mappings":"AAqMO,SAAS,gBAAgB,yBAA2C;AAClE,SAAA,4BAA4B,OAC/B,qBACA;AACN;"}
+{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import { type FFetchOptions } from \"@fetchkit/ffetch\";\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { InternalLogger } from \"./logger\";\n\nexport type Auth = { username: string; password: string } | { apiKey: string };\n\nexport interface ExecutableBuilder<T> {\n  execute(): Promise<Result<T>>;\n  getRequestConfig(): { method: string; url: string; body?: any };\n\n  /**\n   * Convert this builder to a native Request object for batch processing.\n   * @param baseUrl - The base URL for the OData service\n   * @param options - Optional execution options (e.g., includeODataAnnotations)\n   * @returns A native Request object\n   */\n  toRequest(baseUrl: string, options?: ExecuteOptions): Request;\n\n  /**\n   * Process a raw Response object into a typed Result.\n   * This allows builders to apply their own validation and transformation logic.\n   * @param response - The native Response object from the batch operation\n   * @param options - Optional execution options (e.g., skipValidation, includeODataAnnotations)\n   * @returns A typed Result with the builder's expected return type\n   */\n  processResponse(\n    response: Response,\n    options?: ExecuteOptions,\n  ): Promise<Result<T>>;\n}\n\nexport interface ExecutionContext {\n  _makeRequest<T>(\n    url: string,\n    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },\n  ): Promise<Result<T>>;\n  _setUseEntityIds?(useEntityIds: boolean): void;\n  _getUseEntityIds?(): boolean;\n  _getBaseUrl?(): string;\n  _getLogger?(): InternalLogger;\n}\n\nexport type InferSchemaType<Schema extends Record<string, StandardSchemaV1>> = {\n  [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output>\n    ? Output\n    : never;\n};\n\nexport type WithSystemFields<T> =\n  T extends Record<string, any>\n    ? T & {\n        ROWID: number;\n        ROWMODID: number;\n      }\n    : never;\n\n// Helper type to exclude system fields from a union of keys\nexport type ExcludeSystemFields<T extends keyof any> = Exclude<\n  T,\n  \"ROWID\" | \"ROWMODID\"\n>;\n\n// Helper type to omit system fields from an object type\nexport type OmitSystemFields<T> = Omit<T, \"ROWID\" | \"ROWMODID\">;\n\n// OData record metadata fields (present on each record)\nexport type ODataRecordMetadata = {\n  \"@id\": string;\n  \"@editLink\": string;\n};\n\n// OData response wrapper (top-level, internal use only)\nexport type ODataListResponse<T> = {\n  \"@context\": string;\n  value: (T & ODataRecordMetadata)[];\n};\n\nexport type ODataSingleResponse<T> = T &\n  ODataRecordMetadata & {\n    \"@context\": string;\n  };\n\n// OData response for single field values\nexport type ODataFieldResponse<T> = {\n  \"@context\": string;\n  value: T;\n};\n\n// Result pattern for execute responses\nexport type Result<T, E = import(\"./errors\").FMODataErrorType> =\n  | { data: T; error: undefined }\n  | { data: undefined; error: E };\n\n// Batch operation result types\nexport type BatchItemResult<T> = {\n  data: T | undefined;\n  error: import(\"./errors\").FMODataErrorType | undefined;\n  status: number; // HTTP status code (0 for truncated)\n};\n\nexport type BatchResult<T extends readonly any[]> = {\n  results: { [K in keyof T]: BatchItemResult<T[K]> };\n  successCount: number;\n  errorCount: number;\n  truncated: boolean;\n  firstErrorIndex: number | null;\n};\n\n// Make specific keys required, rest optional\nexport type MakeFieldsRequired<T, Keys extends keyof T> = Partial<T> &\n  Required<Pick<T, Keys>>;\n\n// Extract keys from schema where validator doesn't allow null/undefined (auto-required fields)\nexport type AutoRequiredKeys<Schema extends Record<string, StandardSchemaV1>> =\n  {\n    [K in keyof Schema]: Extract<\n      StandardSchemaV1.InferOutput<Schema[K]>,\n      null | undefined\n    > extends never\n      ? K\n      : never;\n  }[keyof Schema];\n\n// Helper type to compute excluded fields (readOnly fields + idField)\nexport type ExcludedFields<\n  IdField extends keyof any | undefined,\n  ReadOnly extends readonly any[],\n> = IdField extends keyof any ? IdField | ReadOnly[number] : ReadOnly[number];\n\n// Helper type for InsertData computation\ntype ComputeInsertData<\n  Schema extends Record<string, StandardSchemaV1>,\n  IdField extends keyof Schema | undefined,\n  Required extends readonly any[],\n  ReadOnly extends readonly any[],\n> = [Required[number]] extends [keyof InferSchemaType<Schema>]\n  ? Required extends readonly (keyof InferSchemaType<Schema>)[]\n    ? MakeFieldsRequired<\n        Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,\n        Exclude<\n          AutoRequiredKeys<Schema> | Required[number],\n          ExcludedFields<IdField, ReadOnly>\n        >\n      >\n    : MakeFieldsRequired<\n        Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,\n        Exclude<AutoRequiredKeys<Schema>, ExcludedFields<IdField, ReadOnly>>\n      >\n  : MakeFieldsRequired<\n      Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>,\n      Exclude<AutoRequiredKeys<Schema>, ExcludedFields<IdField, ReadOnly>>\n    >;\n\nexport type ExecuteOptions = {\n  includeODataAnnotations?: boolean;\n  skipValidation?: boolean;\n  /**\n   * Overrides the default behavior of the database to use entity IDs (rather than field names) in THIS REQUEST ONLY\n   */\n  useEntityIds?: boolean;\n};\n\n/**\n * Type for the fetchHandler callback function.\n * This is a convenience type export that matches the fetchHandler signature in FFetchOptions.\n *\n * @example\n * ```typescript\n * import type { FetchHandler } from '@proofkit/fmodata';\n *\n * const myFetchHandler: FetchHandler = (input, init) => {\n *   console.log('Custom fetch:', input);\n *   return fetch(input, init);\n * };\n *\n * await query.execute({\n *   fetchHandler: myFetchHandler\n * });\n * ```\n */\nexport type FetchHandler = (\n  input: RequestInfo | URL,\n  init?: RequestInit,\n) => Promise<Response>;\n\n/**\n * Combined type for execute() method options.\n *\n * Uses FFetchOptions from @fetchkit/ffetch to ensure proper type inference.\n * FFetchOptions is re-exported in the package to ensure type availability in consuming packages.\n */\nexport type ExecuteMethodOptions<EO extends ExecuteOptions = ExecuteOptions> =\n  RequestInit & FFetchOptions & ExecuteOptions & EO;\n\n/**\n * Get the Accept header value based on includeODataAnnotations option\n * @param includeODataAnnotations - Whether to include OData annotations\n * @returns Accept header value\n */\nexport function getAcceptHeader(includeODataAnnotations?: boolean): string {\n  return includeODataAnnotations === true\n    ? \"application/json\"\n    : \"application/json;odata.metadata=none\";\n}\n\nexport type ConditionallyWithODataAnnotations<\n  T,\n  IncludeODataAnnotations extends boolean,\n> = IncludeODataAnnotations extends true\n  ? T & {\n      \"@id\": string;\n      \"@editLink\": string;\n    }\n  : T;\n\n// Helper type to extract schema from a FMTable\nexport type ExtractSchemaFromOccurrence<Occ> = Occ extends {\n  baseTable: { schema: infer S };\n}\n  ? S extends Record<string, StandardSchemaV1>\n    ? S\n    : Record<string, StandardSchemaV1>\n  : Record<string, StandardSchemaV1>;\n\nexport type GenericFieldMetadata = {\n  $Nullable?: boolean;\n  \"@Index\"?: boolean;\n  \"@Calculation\"?: boolean;\n  \"@Summary\"?: boolean;\n  \"@Global\"?: boolean;\n  \"@Org.OData.Core.V1.Permissions\"?: \"Org.OData.Core.V1.Permission@Read\";\n};\n\nexport type StringFieldMetadata = GenericFieldMetadata & {\n  $Type: \"Edm.String\";\n  $DefaultValue?: \"USER\" | \"USERNAME\" | \"CURRENT_USER\";\n  $MaxLength?: number;\n};\n\nexport type DecimalFieldMetadata = GenericFieldMetadata & {\n  $Type: \"Edm.Decimal\";\n  \"@AutoGenerated\"?: boolean;\n};\n\nexport type DateFieldMetadata = GenericFieldMetadata & {\n  $Type: \"Edm.Date\";\n  $DefaultValue?: \"CURDATE\" | \"CURRENT_DATE\";\n};\n\nexport type TimeOfDayFieldMetadata = GenericFieldMetadata & {\n  $Type: \"Edm.TimeOfDay\";\n  $DefaultValue?: \"CURTIME\" | \"CURRENT_TIME\";\n};\n\nexport type DateTimeOffsetFieldMetadata = GenericFieldMetadata & {\n  $Type: \"Edm.Date\";\n  $DefaultValue?: \"CURTIMESTAMP\" | \"CURRENT_TIMESTAMP\";\n  \"@VersionId\"?: boolean;\n};\n\nexport type StreamFieldMetadata = {\n  $Type: \"Edm.Stream\";\n  $Nullable?: boolean;\n  \"@EnclosedPath\": string;\n  \"@ExternalOpenPath\": string;\n  \"@ExternalSecurePath\"?: string;\n};\n\nexport type FieldMetadata =\n  | StringFieldMetadata\n  | DecimalFieldMetadata\n  | DateFieldMetadata\n  | TimeOfDayFieldMetadata\n  | DateTimeOffsetFieldMetadata\n  | StreamFieldMetadata;\n\nexport type EntityType = {\n  $Kind: \"EntityType\";\n  $Key: string[];\n} & Record<string, FieldMetadata>;\n\nexport type EntitySet = {\n  $Kind: \"EntitySet\";\n  $Type: string;\n};\n\nexport type Metadata = Record<string, EntityType | EntitySet>;\n"],"names":[],"mappings":"AAuMO,SAAS,gBAAgB,yBAA2C;AAClE,SAAA,4BAA4B,OAC/B,qBACA;AACN;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proofkit/fmodata",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.18",
   "description": "FileMaker OData API client",
   "repository": "git@github.com:proofgeist/proofkit.git",
   "author": "Eric <37158449+eluce2@users.noreply.github.com>",

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

@@ -11,6 +11,7 @@ import type { ExpandValidationConfig } from "../../validation";
 import type { ExpandConfig } from "./shared-types";
 import { formatSelectFields } from "./select-utils";
 import { getDefaultSelectFields } from "./default-select";
+import { InternalLogger } from "../../logger";
 
 /**
  * Builds OData expand query strings and validation configs.
@@ -18,7 +19,10 @@ import { getDefaultSelectFields } from "./default-select";
  * when using entity IDs.
  */
 export class ExpandBuilder {
-  constructor(private useEntityIds: boolean) {}
+  constructor(
+    private useEntityIds: boolean,
+    private logger: InternalLogger,
+  ) {}
 
   /**
    * Builds OData $expand query string from expand configurations.
@@ -90,7 +94,7 @@ export class ExpandBuilder {
     if (sourceTable) {
       const navigationPaths = getNavigationPaths(sourceTable);
       if (navigationPaths && !navigationPaths.includes(relationName)) {
-        console.warn(
+        this.logger.warn(
           `Cannot expand to "${relationName}". Valid navigation paths: ${navigationPaths.length > 0 ? navigationPaths.join(", ") : "none"}`,
         );
       }

package/src/client/builders/query-string-builder.ts

@@ -2,6 +2,7 @@ import type { FMTable } from "../../orm/table";
 import { ExpandBuilder } from "./expand-builder";
 import type { ExpandConfig } from "./shared-types";
 import { formatSelectFields } from "./select-utils";
+import { InternalLogger } from "../../logger";
 
 /**
  * Builds OData query string for $select and $expand parameters.
@@ -15,9 +16,10 @@ export function buildSelectExpandQueryString(config: {
   expandConfigs: ExpandConfig[];
   table?: FMTable<any, any>;
   useEntityIds: boolean;
+  logger: InternalLogger;
 }): string {
   const parts: string[] = [];
-  const expandBuilder = new ExpandBuilder(config.useEntityIds);
+  const expandBuilder = new ExpandBuilder(config.useEntityIds, config.logger);
 
   // Build $select
   if (config.selectedFields && config.selectedFields.length > 0) {

package/src/client/builders/response-processor.ts

@@ -7,6 +7,7 @@ import { RecordCountMismatchError } from "../../errors";
 import { getBaseTableConfig } from "../../orm/table";
 import { ExpandBuilder } from "./expand-builder";
 import type { ExpandConfig } from "./shared-types";
+import { InternalLogger } from "../../logger";
 
 export interface ProcessResponseConfig {
   table?: FMTable<any, any>;
@@ -224,6 +225,7 @@ export async function processQueryResponse<T>(
     useEntityIds?: boolean;
     // Mapping from field names to output keys (for renamed fields in select)
     fieldMapping?: Record<string, string>;
+    logger: InternalLogger;
   },
 ): Promise<Result<any>> {
   const {
@@ -234,9 +236,10 @@ export async function processQueryResponse<T>(
     skipValidation,
     useEntityIds,
     fieldMapping,
+    logger,
   } = config;
 
-  const expandBuilder = new ExpandBuilder(useEntityIds ?? false);
+  const expandBuilder = new ExpandBuilder(useEntityIds ?? false, logger);
   const expandValidationConfigs =
     expandBuilder.buildValidationConfigs(expandConfigs);
 

package/src/client/builders/select-mixin.ts

@@ -1,3 +1,4 @@
+import { InternalLogger } from "../../logger";
 import { isColumn, type Column } from "../../orm/column";
 
 /**
@@ -31,6 +32,7 @@ export function processSelectFields(
 export function processSelectWithRenames<TTableName extends string>(
   fields: Record<string, Column<any, any, TTableName>>,
   tableName: string,
+  logger: InternalLogger,
 ): { selectedFields: string[]; fieldMapping: Record<string, string> } {
   const selectedFields: string[] = [];
   const fieldMapping: Record<string, string> = {};
@@ -44,7 +46,7 @@ export function processSelectWithRenames<TTableName extends string>(
 
     // Warn (not throw) on table mismatch for consistency
     if (column.tableName !== tableName) {
-      console.warn(
+      logger.warn(
         `Column ${column.toString()} is from table "${column.tableName}", but query is for table "${tableName}"`,
       );
     }

package/src/client/builders/select-utils.ts

@@ -1,6 +1,30 @@
 import type { FMTable } from "../../orm/table";
 import { transformFieldNamesArray } from "../../transform";
 
+/**
+ * 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 function needsFieldQuoting(fieldName: string): boolean {
+  // Entity IDs are identifiers and don't need quoting
+  if (fieldName.startsWith("FMFID:") || fieldName.startsWith("FMTID:")) {
+    return false;
+  }
+  // Always quote "id" as it's an OData reserved word
+  if (fieldName === "id") return true;
+  // Quote if field name contains spaces, underscores, or other special characters
+  return (
+    fieldName.includes(" ") ||
+    fieldName.includes("_") ||
+    !/^[a-zA-Z][a-zA-Z0-9]*$/.test(fieldName)
+  );
+}
+
 /**
  * Formats select fields for use in OData query strings.
  * - Transforms field names to FMFIDs if using entity IDs
@@ -24,11 +48,9 @@ export function formatSelectFields(
 
   return transformedFields
     .map((field) => {
-      if (field === "id") return `"id"`;
+      if (needsFieldQuoting(field)) return `"${field}"`;
       const encoded = encodeURIComponent(field);
       return encoded.replace(/%20/g, " ");
     })
     .join(",");
 }
-
-

package/src/client/entity-set.ts

@@ -1,4 +1,4 @@
-import type { ExecutionContext, InferSchemaType } from "../types";
+import type { ExecutionContext } from "../types";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { QueryBuilder } from "./query/index";
 import { RecordBuilder } from "./record-builder";
@@ -9,25 +9,19 @@ import { Database } from "./database";
 import type {
   FMTable,
   InferSchemaOutputFromFMTable,
-  InferInputSchemaFromFMTable,
   InsertDataFromFMTable,
   UpdateDataFromFMTable,
   ValidExpandTarget,
-  ExtractTableName,
-  FMTableWithColumns,
-  InferFieldOutput,
   ColumnMap,
 } from "../orm/table";
 import {
   FMTable as FMTableClass,
   getDefaultSelect,
-  getNavigationPaths,
   getTableName,
   getTableColumns,
-  getTableFields,
 } from "../orm/table";
-import type { Column } from "../orm/column";
 import type { FieldBuilder } from "../orm/field-builders";
+import { createLogger, InternalLogger } from "../logger";
 
 // Helper type to extract defaultSelect from an FMTable
 // Since TypeScript can't extract Symbol-indexed properties at the type level,
@@ -57,6 +51,7 @@ export class EntitySet<Occ extends FMTable<any, any>> {
   private navigateSourceTableName?: string;
   private navigateBasePath?: string; // Full base path for chained navigations
   private databaseUseEntityIds: boolean;
+  private logger: InternalLogger;
 
   constructor(config: {
     occurrence: Occ;
@@ -71,6 +66,7 @@ export class EntitySet<Occ extends FMTable<any, any>> {
     // Get useEntityIds from database if available, otherwise default to false
     this.databaseUseEntityIds =
       (config.database as any)?._useEntityIds ?? false;
+    this.logger = config.context?._getLogger?.() ?? createLogger();
   }
 
   // Type-only method to help TypeScript infer the schema from table
@@ -126,7 +122,7 @@ export class EntitySet<Occ extends FMTable<any, any>> {
         // This is equivalent to select(getTableColumns(occurrence))
         // Cast to the declared return type - runtime behavior handles the actual selection
         const allColumns = getTableColumns(
-          this.occurrence as any,
+          this.occurrence,
         ) as ExtractColumnsFromOcc<Occ>;
         return builder.select(allColumns).top(1000) as QueryBuilder<
           Occ,
@@ -175,7 +171,7 @@ export class EntitySet<Occ extends FMTable<any, any>> {
   ): RecordBuilder<
     Occ,
     false,
-    keyof InferSchemaOutputFromFMTable<Occ>,
+    undefined,
     keyof InferSchemaOutputFromFMTable<Occ>,
     {}
   > {
@@ -358,7 +354,7 @@ export class EntitySet<Occ extends FMTable<any, any>> {
         FMTableClass.Symbol.NavigationPaths
       ] as readonly string[];
       if (navigationPaths && !navigationPaths.includes(relationName)) {
-        console.warn(
+        this.logger.warn(
           `Cannot navigate to "${relationName}". Valid navigation paths: ${navigationPaths.length > 0 ? navigationPaths.join(", ") : "none"}`,
         );
       }

package/src/client/error-parser.ts

@@ -21,8 +21,10 @@ export async function parseErrorResponse(
   url: string,
 ): Promise<FMODataErrorType> {
   // Try to parse error body if it's JSON
-  let errorBody: { error?: { code?: string | number; message?: string } } | undefined;
-  
+  let errorBody:
+    | { error?: { code?: string | number; message?: string } }
+    | undefined;
+
   try {
     if (response.headers.get("content-type")?.includes("application/json")) {
       errorBody = await safeJsonParse<typeof errorBody>(response);
@@ -52,11 +54,3 @@ export async function parseErrorResponse(
   // Fall back to generic HTTPError
   return new HTTPError(url, response.status, response.statusText, errorBody);
 }
-
-
-
-
-
-
-
-

package/src/client/filemaker-odata.ts

@@ -17,17 +17,21 @@ import {
 import { Database } from "./database";
 import { safeJsonParse } from "./sanitize-json";
 import { get } from "es-toolkit/compat";
+import { createLogger, type Logger, type InternalLogger } from "../logger";
 
 export class FMServerConnection implements ExecutionContext {
   private fetchClient: ReturnType<typeof createClient>;
   private serverUrl: string;
   private auth: Auth;
   private useEntityIds: boolean = false;
+  private logger: InternalLogger;
   constructor(config: {
     serverUrl: string;
     auth: Auth;
     fetchClientOptions?: FFetchOptions;
+    logger?: Logger;
   }) {
+    this.logger = createLogger(config.logger);
     this.fetchClient = createClient({
       retries: 0,
       ...config.fetchClientOptions,
@@ -67,6 +71,14 @@ export class FMServerConnection implements ExecutionContext {
     return `${this.serverUrl}${"apiKey" in this.auth ? `/otto` : ""}/fmi/odata/v4`;
   }
 
+  /**
+   * @internal
+   * Gets the logger instance
+   */
+  _getLogger(): InternalLogger {
+    return this.logger;
+  }
+
   /**
    * @internal
    */
@@ -74,6 +86,7 @@ export class FMServerConnection implements ExecutionContext {
     url: string,
     options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },
   ): Promise<Result<T>> {
+    const logger = this._getLogger();
     const baseUrl = `${this.serverUrl}${"apiKey" in this.auth ? `/otto` : ""}/fmi/odata/v4`;
     const fullUrl = baseUrl + url;
 
@@ -94,6 +107,10 @@ export class FMServerConnection implements ExecutionContext {
       ...(options?.headers || {}),
     };
 
+    // Prepare loggableHeaders by omitting the Authorization key
+    const { Authorization, ...loggableHeaders } = headers;
+    logger.debug("Request headers:", loggableHeaders);
+
     // TEMPORARY WORKAROUND: Hopefully this feature will be fixed in the ffetch library
     // Extract fetchHandler and headers separately, only for tests where we're overriding the fetch handler per-request
     const fetchHandler = options?.fetchHandler;
@@ -116,6 +133,7 @@ export class FMServerConnection implements ExecutionContext {
       };
 
       const resp = await clientToUse(fullUrl, finalOptions);
+      logger.debug(`${finalOptions.method ?? "GET"} ${resp.status} ${fullUrl}`);
 
       // Handle HTTP errors
       if (!resp.ok) {

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

@@ -45,6 +45,7 @@ import {
 } from "../builders/index";
 import { QueryUrlBuilder, type NavigationConfig } from "./url-builder";
 import type { TypeSafeOrderBy, QueryReturnType } from "./types";
+import { createLogger, InternalLogger } from "../../logger";
 
 // Re-export QueryReturnType for backward compatibility
 export type { QueryReturnType };
@@ -95,6 +96,7 @@ export class QueryBuilder<
   private urlBuilder: QueryUrlBuilder;
   // Mapping from field names to output keys (for renamed fields in select)
   private fieldMapping?: Record<string, string>;
+  private logger: InternalLogger;
 
   constructor(config: {
     occurrence: Occ;
@@ -105,8 +107,12 @@ export class QueryBuilder<
     this.occurrence = config.occurrence;
     this.databaseName = config.databaseName;
     this.context = config.context;
+    this.logger = config.context?._getLogger?.() ?? createLogger();
     this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
-    this.expandBuilder = new ExpandBuilder(this.databaseUseEntityIds);
+    this.expandBuilder = new ExpandBuilder(
+      this.databaseUseEntityIds,
+      this.logger,
+    );
     this.urlBuilder = new QueryUrlBuilder(
       this.databaseName,
       this.occurrence,
@@ -205,12 +211,16 @@ export class QueryBuilder<
    * @returns QueryBuilder with updated selected fields
    */
   select<
-    TSelect extends Record<string, Column<any, any, ExtractTableName<Occ>, false>>,
+    TSelect extends Record<
+      string,
+      Column<any, any, ExtractTableName<Occ>, false>
+    >,
   >(fields: TSelect): QueryBuilder<Occ, TSelect, SingleMode, IsCount, Expands> {
     const tableName = getTableName(this.occurrence);
     const { selectedFields, fieldMapping } = processSelectWithRenames(
       fields,
       tableName,
+      this.logger,
     );
 
     return this.cloneWithChanges({
@@ -294,7 +304,7 @@ export class QueryBuilder<
         if (isOrderByExpression(arg)) {
           // Validate table match
           if (arg.column.tableName !== tableName) {
-            console.warn(
+            this.logger.warn(
               `Column ${arg.column.toString()} is from table "${arg.column.tableName}", but query is for table "${tableName}"`,
             );
           }
@@ -306,7 +316,7 @@ export class QueryBuilder<
         } else if (isColumn(arg)) {
           // Validate table match
           if (arg.tableName !== tableName) {
-            console.warn(
+            this.logger.warn(
               `Column ${arg.toString()} is from table "${arg.tableName}", but query is for table "${tableName}"`,
             );
           }
@@ -332,7 +342,7 @@ export class QueryBuilder<
     if (isOrderByExpression(orderBy)) {
       // Validate table match
       if (orderBy.column.tableName !== tableName) {
-        console.warn(
+        this.logger.warn(
           `Column ${orderBy.column.toString()} is from table "${orderBy.column.tableName}", but query is for table "${tableName}"`,
         );
       }
@@ -348,7 +358,7 @@ export class QueryBuilder<
     if (isColumn(orderBy)) {
       // Validate table match
       if (orderBy.tableName !== tableName) {
-        console.warn(
+        this.logger.warn(
           `Column ${orderBy.toString()} is from table "${orderBy.tableName}", but query is for table "${tableName}"`,
         );
       }
@@ -530,6 +540,7 @@ export class QueryBuilder<
       expandConfigs: this.expandConfigs,
       table: this.occurrence,
       useEntityIds: this.databaseUseEntityIds,
+      logger: this.logger,
     });
 
     // Append select/expand to existing query string
@@ -603,6 +614,7 @@ export class QueryBuilder<
       skipValidation: options?.skipValidation,
       useEntityIds: mergedOptions.useEntityIds,
       fieldMapping: this.fieldMapping,
+      logger: this.logger,
     });
   }
 
@@ -712,6 +724,7 @@ export class QueryBuilder<
       skipValidation: options?.skipValidation,
       useEntityIds: mergedOptions.useEntityIds,
       fieldMapping: this.fieldMapping,
+      logger: this.logger,
     });
   }
 }

package/src/client/query/response-processor.ts

@@ -8,6 +8,7 @@ import { validateListResponse, validateSingleResponse } from "../../validation";
 import type { ExpandValidationConfig } from "../../validation";
 import type { ExpandConfig } from "./expand-builder";
 import { FMTable as FMTableClass } from "../../orm/table";
+import { InternalLogger } from "../../logger";
 
 /**
  * Configuration for processing query responses
@@ -21,6 +22,7 @@ export interface ProcessQueryResponseConfig<T> {
   useEntityIds?: boolean;
   // Mapping from field names to output keys (for renamed fields in select)
   fieldMapping?: Record<string, string>;
+  logger: InternalLogger;
 }
 
 /**