@proofkit/fmodata 0.1.0-alpha.19 → 0.1.0-alpha.20

package/dist/esm/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sources":["../../src/validation.ts"],"sourcesContent":["import type { ODataRecordMetadata } from \"./types\";\nimport { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { FMTable } from \"./orm/table\";\nimport {\n  ValidationError,\n  ResponseStructureError,\n  RecordCountMismatchError,\n} from \"./errors\";\n\n/**\n * Validates and transforms input data for insert/update operations.\n * Applies input validators (writeValidators) to transform user input to database format.\n * Fields without input validators are passed through unchanged.\n *\n * @param data - The input data to validate and transform\n * @param inputSchema - Optional schema containing input validators for each field\n * @returns Transformed data ready to send to the server\n * @throws ValidationError if any field fails validation\n */\nexport async function validateAndTransformInput<T extends Record<string, any>>(\n  data: Partial<T>,\n  inputSchema?: Record<string, StandardSchemaV1>,\n): Promise<Partial<T>> {\n  // If no input schema, return data as-is\n  if (!inputSchema) {\n    return data;\n  }\n\n  const transformedData: Record<string, any> = { ...data };\n\n  // Process each field that has an input validator\n  for (const [fieldName, fieldSchema] of Object.entries(inputSchema)) {\n    // Only process fields that are present in the input data\n    if (fieldName in data) {\n      const inputValue = data[fieldName];\n\n      try {\n        // Run the input validator to transform the value\n        let result = fieldSchema[\"~standard\"].validate(inputValue);\n        if (result instanceof Promise) {\n          result = await result;\n        }\n\n        // Check for validation errors\n        if (result.issues) {\n          throw new ValidationError(\n            `Input validation failed for field '${fieldName}'`,\n            result.issues,\n            {\n              field: fieldName,\n              value: inputValue,\n              cause: result.issues,\n            },\n          );\n        }\n\n        // Store the transformed value\n        transformedData[fieldName] = result.value;\n      } catch (error) {\n        // If it's already a ValidationError, re-throw it\n        if (error instanceof ValidationError) {\n          throw error;\n        }\n\n        // Otherwise, wrap the error\n        throw new ValidationError(\n          `Input validation failed for field '${fieldName}'`,\n          [],\n          {\n            field: fieldName,\n            value: inputValue,\n            cause: error,\n          },\n        );\n      }\n    }\n  }\n\n  // Fields without input validators are already in transformedData (passed through)\n  return transformedData as Partial<T>;\n}\n\n// Type for expand validation configuration\nexport type ExpandValidationConfig = {\n  relation: string;\n  targetSchema?: Record<string, StandardSchemaV1>;\n  targetTable?: FMTable<any, any>;\n  table?: FMTable<any, any>; // For transformation\n  selectedFields?: string[];\n  nestedExpands?: ExpandValidationConfig[];\n};\n\n/**\n * Validates a single record against a schema, only validating selected fields.\n * Also validates expanded relations if expandConfigs are provided.\n */\nexport async function validateRecord<T extends Record<string, any>>(\n  record: any,\n  schema: Record<string, StandardSchemaV1> | undefined,\n  selectedFields?: (keyof T)[],\n  expandConfigs?: ExpandValidationConfig[],\n): Promise<\n  | { valid: true; data: T & ODataRecordMetadata }\n  | { valid: false; error: ValidationError }\n> {\n  // Extract OData metadata fields (don't validate them - include if present)\n  const { \"@id\": id, \"@editLink\": editLink, ...rest } = record;\n\n  // Only include metadata fields if they actually exist and have values\n  const metadata: Partial<ODataRecordMetadata> = {};\n  if (id) metadata[\"@id\"] = id;\n  if (editLink) metadata[\"@editLink\"] = editLink;\n\n  // If no schema, just return the data with metadata\n  if (!schema) {\n    return {\n      valid: true,\n      data: { ...rest, ...metadata } as T & ODataRecordMetadata,\n    };\n  }\n\n  // Filter out FileMaker system fields that shouldn't be in responses by default\n  const { ROWID, ROWMODID, ...restWithoutSystemFields } = rest;\n\n  // If selected fields are specified, validate only those fields\n  if (selectedFields && selectedFields.length > 0) {\n    const validatedRecord: Record<string, any> = {};\n\n    for (const field of selectedFields) {\n      const fieldName = String(field);\n      const fieldSchema = schema[fieldName];\n\n      if (fieldSchema) {\n        const input = rest[fieldName];\n        try {\n          let result = fieldSchema[\"~standard\"].validate(input);\n          if (result instanceof Promise) result = await result;\n\n          // if the `issues` field exists, the validation failed\n          if (result.issues) {\n            return {\n              valid: false,\n              error: new ValidationError(\n                `Validation failed for field '${fieldName}'`,\n                result.issues,\n                {\n                  field: fieldName,\n                  value: input,\n                  cause: result.issues,\n                },\n              ),\n            };\n          }\n\n          validatedRecord[fieldName] = result.value;\n        } catch (originalError) {\n          // If the validator throws directly, wrap it\n          return {\n            valid: false,\n            error: new ValidationError(\n              `Validation failed for field '${fieldName}'`,\n              [],\n              {\n                field: fieldName,\n                value: input,\n                cause: originalError,\n              },\n            ),\n          };\n        }\n      } else {\n        // For fields not in schema (like when explicitly selecting ROWID/ROWMODID)\n        // include them from the original response\n        validatedRecord[fieldName] = rest[fieldName];\n      }\n    }\n\n    // Validate expanded relations\n    if (expandConfigs && expandConfigs.length > 0) {\n      for (const expandConfig of expandConfigs) {\n        const expandValue = rest[expandConfig.relation];\n\n        // Check if expand field is missing\n        if (expandValue === undefined) {\n          // Check for inline error array (FileMaker returns errors inline when expand fails)\n          if (Array.isArray(rest.error) && rest.error.length > 0) {\n            // Extract error message from inline error\n            const errorDetail = rest.error[0]?.error;\n            if (errorDetail?.message) {\n              const errorMessage = errorDetail.message;\n              // Check if the error is related to this expand by checking if:\n              // 1. The error mentions the relation name, OR\n              // 2. The error mentions any of the selected fields\n              const isRelatedToExpand =\n                errorMessage\n                  .toLowerCase()\n                  .includes(expandConfig.relation.toLowerCase()) ||\n                (expandConfig.selectedFields &&\n                  expandConfig.selectedFields.some((field) =>\n                    errorMessage.toLowerCase().includes(field.toLowerCase()),\n                  ));\n\n              if (isRelatedToExpand) {\n                return {\n                  valid: false,\n                  error: new ValidationError(\n                    `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,\n                    [],\n                    {\n                      field: expandConfig.relation,\n                    },\n                  ),\n                };\n              }\n            }\n          }\n          // If no inline error but expand was expected, that's also an issue\n          // However, this might be a legitimate case (e.g., no related records)\n          // So we'll only fail if there's an explicit error array\n        } else {\n          // Original validation logic for when expand exists\n          if (Array.isArray(expandValue)) {\n            // Validate each item in the expanded array\n            const validatedExpandedItems: any[] = [];\n            for (let i = 0; i < expandValue.length; i++) {\n              const item = expandValue[i];\n              const itemValidation = await validateRecord(\n                item,\n                expandConfig.targetSchema,\n                expandConfig.selectedFields as string[] | undefined,\n                expandConfig.nestedExpands,\n              );\n              if (!itemValidation.valid) {\n                return {\n                  valid: false,\n                  error: new ValidationError(\n                    `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`,\n                    itemValidation.error.issues,\n                    {\n                      field: expandConfig.relation,\n                      cause: itemValidation.error.cause,\n                    },\n                  ),\n                };\n              }\n              validatedExpandedItems.push(itemValidation.data);\n            }\n            validatedRecord[expandConfig.relation] = validatedExpandedItems;\n          } else {\n            // Single expanded item (shouldn't happen in OData, but handle it)\n            const itemValidation = await validateRecord(\n              expandValue,\n              expandConfig.targetSchema,\n              expandConfig.selectedFields as string[] | undefined,\n              expandConfig.nestedExpands,\n            );\n            if (!itemValidation.valid) {\n              return {\n                valid: false,\n                error: new ValidationError(\n                  `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,\n                  itemValidation.error.issues,\n                  {\n                    field: expandConfig.relation,\n                    cause: itemValidation.error.cause,\n                  },\n                ),\n              };\n            }\n            validatedRecord[expandConfig.relation] = itemValidation.data;\n          }\n        }\n      }\n    }\n\n    // Merge validated data with metadata\n    return {\n      valid: true,\n      data: { ...validatedRecord, ...metadata } as T & ODataRecordMetadata,\n    };\n  }\n\n  // Validate all fields in schema, but exclude ROWID/ROWMODID by default\n  const validatedRecord: Record<string, any> = { ...restWithoutSystemFields };\n\n  for (const [fieldName, fieldSchema] of Object.entries(schema)) {\n    const input = rest[fieldName];\n    try {\n      let result = fieldSchema[\"~standard\"].validate(input);\n      if (result instanceof Promise) result = await result;\n\n      // if the `issues` field exists, the validation failed\n      if (result.issues) {\n        return {\n          valid: false,\n          error: new ValidationError(\n            `Validation failed for field '${fieldName}'`,\n            result.issues,\n            {\n              field: fieldName,\n              value: input,\n              cause: result.issues,\n            },\n          ),\n        };\n      }\n\n      validatedRecord[fieldName] = result.value;\n    } catch (originalError) {\n      // If the validator throws an error directly, catch and wrap it\n      // This preserves the original error instance for instanceof checks\n      return {\n        valid: false,\n        error: new ValidationError(\n          `Validation failed for field '${fieldName}'`,\n          [],\n          {\n            field: fieldName,\n            value: input,\n            cause: originalError,\n          },\n        ),\n      };\n    }\n  }\n\n  // Validate expanded relations even when not using selected fields\n  if (expandConfigs && expandConfigs.length > 0) {\n    for (const expandConfig of expandConfigs) {\n      const expandValue = rest[expandConfig.relation];\n\n      // Check if expand field is missing\n      if (expandValue === undefined) {\n        // Check for inline error array (FileMaker returns errors inline when expand fails)\n        if (Array.isArray(rest.error) && rest.error.length > 0) {\n          // Extract error message from inline error\n          const errorDetail = rest.error[0]?.error;\n          if (errorDetail?.message) {\n            const errorMessage = errorDetail.message;\n            // Check if the error is related to this expand by checking if:\n            // 1. The error mentions the relation name, OR\n            // 2. The error mentions any of the selected fields\n            const isRelatedToExpand =\n              errorMessage\n                .toLowerCase()\n                .includes(expandConfig.relation.toLowerCase()) ||\n              (expandConfig.selectedFields &&\n                expandConfig.selectedFields.some((field) =>\n                  errorMessage.toLowerCase().includes(field.toLowerCase()),\n                ));\n\n            if (isRelatedToExpand) {\n              return {\n                valid: false,\n                error: new ValidationError(\n                  `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,\n                  [],\n                  {\n                    field: expandConfig.relation,\n                  },\n                ),\n              };\n            }\n          }\n        }\n        // If no inline error but expand was expected, that's also an issue\n        // However, this might be a legitimate case (e.g., no related records)\n        // So we'll only fail if there's an explicit error array\n      } else {\n        // Original validation logic for when expand exists\n        if (Array.isArray(expandValue)) {\n          // Validate each item in the expanded array\n          const validatedExpandedItems: any[] = [];\n          for (let i = 0; i < expandValue.length; i++) {\n            const item = expandValue[i];\n            const itemValidation = await validateRecord(\n              item,\n              expandConfig.targetSchema,\n              expandConfig.selectedFields as string[] | undefined,\n              expandConfig.nestedExpands,\n            );\n            if (!itemValidation.valid) {\n              return {\n                valid: false,\n                error: new ValidationError(\n                  `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`,\n                  itemValidation.error.issues,\n                  {\n                    field: expandConfig.relation,\n                    cause: itemValidation.error.cause,\n                  },\n                ),\n              };\n            }\n            validatedExpandedItems.push(itemValidation.data);\n          }\n          validatedRecord[expandConfig.relation] = validatedExpandedItems;\n        } else {\n          // Single expanded item (shouldn't happen in OData, but handle it)\n          const itemValidation = await validateRecord(\n            expandValue,\n            expandConfig.targetSchema,\n            expandConfig.selectedFields as string[] | undefined,\n            expandConfig.nestedExpands,\n          );\n          if (!itemValidation.valid) {\n            return {\n              valid: false,\n              error: new ValidationError(\n                `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,\n                itemValidation.error.issues,\n                {\n                  field: expandConfig.relation,\n                  cause: itemValidation.error.cause,\n                },\n              ),\n            };\n          }\n          validatedRecord[expandConfig.relation] = itemValidation.data;\n        }\n      }\n    }\n  }\n\n  return {\n    valid: true,\n    data: { ...validatedRecord, ...metadata } as T & ODataRecordMetadata,\n  };\n}\n\n/**\n * Validates a list response against a schema.\n */\nexport async function validateListResponse<T extends Record<string, any>>(\n  response: any,\n  schema: Record<string, StandardSchemaV1> | undefined,\n  selectedFields?: (keyof T)[],\n  expandConfigs?: ExpandValidationConfig[],\n): Promise<\n  | { valid: true; data: (T & ODataRecordMetadata)[] }\n  | { valid: false; error: ResponseStructureError | ValidationError }\n> {\n  // Check if response has the expected structure\n  if (!response || typeof response !== \"object\") {\n    return {\n      valid: false,\n      error: new ResponseStructureError(\"an object\", response),\n    };\n  }\n\n  // Extract @context (for internal validation, but we won't return it)\n  const { \"@context\": context, value, ...rest } = response;\n\n  if (!Array.isArray(value)) {\n    return {\n      valid: false,\n      error: new ResponseStructureError(\n        \"'value' property to be an array\",\n        value,\n      ),\n    };\n  }\n\n  // Validate each record in the array\n  const validatedRecords: (T & ODataRecordMetadata)[] = [];\n\n  for (let i = 0; i < value.length; i++) {\n    const record = value[i];\n    const validation = await validateRecord<T>(\n      record,\n      schema,\n      selectedFields,\n      expandConfigs,\n    );\n\n    if (!validation.valid) {\n      return {\n        valid: false,\n        error: validation.error,\n      };\n    }\n\n    validatedRecords.push(validation.data);\n  }\n\n  return {\n    valid: true,\n    data: validatedRecords,\n  };\n}\n\n/**\n * Validates a single record response against a schema.\n */\nexport async function validateSingleResponse<T extends Record<string, any>>(\n  response: any,\n  schema: Record<string, StandardSchemaV1> | undefined,\n  selectedFields?: (keyof T)[],\n  expandConfigs?: ExpandValidationConfig[],\n  mode: \"exact\" | \"maybe\" = \"maybe\",\n): Promise<\n  | { valid: true; data: (T & ODataRecordMetadata) | null }\n  | { valid: false; error: RecordCountMismatchError | ValidationError }\n> {\n  // Check for multiple records (error in both modes)\n  if (\n    response.value &&\n    Array.isArray(response.value) &&\n    response.value.length > 1\n  ) {\n    return {\n      valid: false,\n      error: new RecordCountMismatchError(\n        mode === \"exact\" ? \"one\" : \"at-most-one\",\n        response.value.length,\n      ),\n    };\n  }\n\n  // Handle empty responses\n  if (!response || (response.value && response.value.length === 0)) {\n    if (mode === \"exact\") {\n      return {\n        valid: false,\n        error: new RecordCountMismatchError(\"one\", 0),\n      };\n    }\n    // mode === \"maybe\" - return null for empty\n    return {\n      valid: true,\n      data: null,\n    };\n  }\n\n  // Single record validation\n  const record = response.value?.[0] ?? response;\n  const validation = await validateRecord<T>(\n    record,\n    schema,\n    selectedFields,\n    expandConfigs,\n  );\n\n  if (!validation.valid) {\n    return validation as { valid: false; error: ValidationError };\n  }\n\n  return {\n    valid: true,\n    data: validation.data,\n  };\n}\n"],"names":["validatedRecord"],"mappings":"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"}
+{"version":3,"file":"validation.js","sources":["../../src/validation.ts"],"sourcesContent":["import type { ODataRecordMetadata } from \"./types\";\nimport { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { FMTable } from \"./orm/table\";\nimport {\n  ValidationError,\n  ResponseStructureError,\n  RecordCountMismatchError,\n} from \"./errors\";\n\n/**\n * Validates and transforms input data for insert/update operations.\n * Applies input validators (writeValidators) to transform user input to database format.\n * Fields without input validators are passed through unchanged.\n *\n * @param data - The input data to validate and transform\n * @param inputSchema - Optional schema containing input validators for each field\n * @returns Transformed data ready to send to the server\n * @throws ValidationError if any field fails validation\n */\nexport async function validateAndTransformInput<T extends Record<string, any>>(\n  data: Partial<T>,\n  inputSchema?: Partial<Record<string, StandardSchemaV1>>,\n): Promise<Partial<T>> {\n  // If no input schema, return data as-is\n  if (!inputSchema) {\n    return data;\n  }\n\n  const transformedData: Record<string, any> = { ...data };\n\n  // Process each field that has an input validator\n  for (const [fieldName, fieldSchema] of Object.entries(inputSchema)) {\n    // Skip if no schema for this field\n    if (!fieldSchema) continue;\n    \n    // Only process fields that are present in the input data\n    if (fieldName in data) {\n      const inputValue = data[fieldName];\n\n      try {\n        // Run the input validator to transform the value\n        let result = fieldSchema[\"~standard\"].validate(inputValue);\n        if (result instanceof Promise) {\n          result = await result;\n        }\n\n        // Check for validation errors\n        if (result.issues) {\n          throw new ValidationError(\n            `Input validation failed for field '${fieldName}'`,\n            result.issues,\n            {\n              field: fieldName,\n              value: inputValue,\n              cause: result.issues,\n            },\n          );\n        }\n\n        // Store the transformed value\n        transformedData[fieldName] = result.value;\n      } catch (error) {\n        // If it's already a ValidationError, re-throw it\n        if (error instanceof ValidationError) {\n          throw error;\n        }\n\n        // Otherwise, wrap the error\n        throw new ValidationError(\n          `Input validation failed for field '${fieldName}'`,\n          [],\n          {\n            field: fieldName,\n            value: inputValue,\n            cause: error,\n          },\n        );\n      }\n    }\n  }\n\n  // Fields without input validators are already in transformedData (passed through)\n  return transformedData as Partial<T>;\n}\n\n// Type for expand validation configuration\nexport type ExpandValidationConfig = {\n  relation: string;\n  targetSchema?: Partial<Record<string, StandardSchemaV1>>;\n  targetTable?: FMTable<any, any>;\n  table?: FMTable<any, any>; // For transformation\n  selectedFields?: string[];\n  nestedExpands?: ExpandValidationConfig[];\n};\n\n/**\n * Validates a single record against a schema, only validating selected fields.\n * Also validates expanded relations if expandConfigs are provided.\n */\nexport async function validateRecord<T extends Record<string, any>>(\n  record: any,\n  schema: Partial<Record<string, StandardSchemaV1>> | undefined,\n  selectedFields?: (keyof T)[],\n  expandConfigs?: ExpandValidationConfig[],\n  includeSpecialColumns?: boolean,\n): Promise<\n  | { valid: true; data: T & ODataRecordMetadata }\n  | { valid: false; error: ValidationError }\n> {\n  // Extract OData metadata fields (don't validate them - include if present)\n  const { \"@id\": id, \"@editLink\": editLink, ...rest } = record;\n\n  // Only include metadata fields if they actually exist and have values\n  const metadata: Partial<ODataRecordMetadata> = {};\n  if (id) metadata[\"@id\"] = id;\n  if (editLink) metadata[\"@editLink\"] = editLink;\n\n  // If no schema, just return the data with metadata\n  // Exclude special columns if includeSpecialColumns is false\n  if (!schema) {\n    const { ROWID, ROWMODID, ...restWithoutSystemFields } = rest;\n    const specialColumns: { ROWID?: number; ROWMODID?: number } = {};\n    if (includeSpecialColumns) {\n      if (ROWID !== undefined) specialColumns.ROWID = ROWID;\n      if (ROWMODID !== undefined) specialColumns.ROWMODID = ROWMODID;\n    }\n    return {\n      valid: true,\n      data: {\n        ...restWithoutSystemFields,\n        ...specialColumns,\n        ...metadata,\n      } as T & ODataRecordMetadata,\n    };\n  }\n\n  // Extract FileMaker special columns - preserve them if includeSpecialColumns is enabled\n  // Note: Special columns are excluded when using single() method (per OData spec behavior)\n  const { ROWID, ROWMODID, ...restWithoutSystemFields } = rest;\n  const specialColumns: { ROWID?: number; ROWMODID?: number } = {};\n  // Only include special columns if explicitly enabled (they're excluded for single() by design)\n  if (includeSpecialColumns) {\n    if (ROWID !== undefined) specialColumns.ROWID = ROWID;\n    if (ROWMODID !== undefined) specialColumns.ROWMODID = ROWMODID;\n  }\n\n  // If selected fields are specified, validate only those fields\n  if (selectedFields && selectedFields.length > 0) {\n    const validatedRecord: Record<string, any> = {};\n\n    for (const field of selectedFields) {\n      const fieldName = String(field);\n      const fieldSchema = schema[fieldName];\n\n      if (fieldSchema) {\n        const input = rest[fieldName];\n        try {\n          let result = fieldSchema[\"~standard\"].validate(input);\n          if (result instanceof Promise) result = await result;\n\n          // if the `issues` field exists, the validation failed\n          if (result.issues) {\n            return {\n              valid: false,\n              error: new ValidationError(\n                `Validation failed for field '${fieldName}'`,\n                result.issues,\n                {\n                  field: fieldName,\n                  value: input,\n                  cause: result.issues,\n                },\n              ),\n            };\n          }\n\n          validatedRecord[fieldName] = result.value;\n        } catch (originalError) {\n          // If the validator throws directly, wrap it\n          return {\n            valid: false,\n            error: new ValidationError(\n              `Validation failed for field '${fieldName}'`,\n              [],\n              {\n                field: fieldName,\n                value: input,\n                cause: originalError,\n              },\n            ),\n          };\n        }\n      } else {\n        // For fields not in schema (like when explicitly selecting ROWID/ROWMODID)\n        // Check if it's a special column that was destructured earlier\n        if (fieldName === \"ROWID\" || fieldName === \"ROWMODID\") {\n          // Use the destructured value since it was removed from rest\n          if (fieldName === \"ROWID\" && ROWID !== undefined) {\n            validatedRecord[fieldName] = ROWID;\n          } else if (fieldName === \"ROWMODID\" && ROWMODID !== undefined) {\n            validatedRecord[fieldName] = ROWMODID;\n          }\n        } else {\n          // For other fields not in schema, include them from the original response\n          validatedRecord[fieldName] = rest[fieldName];\n        }\n      }\n    }\n\n    // Validate expanded relations\n    if (expandConfigs && expandConfigs.length > 0) {\n      for (const expandConfig of expandConfigs) {\n        const expandValue = rest[expandConfig.relation];\n\n        // Check if expand field is missing\n        if (expandValue === undefined) {\n          // Check for inline error array (FileMaker returns errors inline when expand fails)\n          if (Array.isArray(rest.error) && rest.error.length > 0) {\n            // Extract error message from inline error\n            const errorDetail = rest.error[0]?.error;\n            if (errorDetail?.message) {\n              const errorMessage = errorDetail.message;\n              // Check if the error is related to this expand by checking if:\n              // 1. The error mentions the relation name, OR\n              // 2. The error mentions any of the selected fields\n              const isRelatedToExpand =\n                errorMessage\n                  .toLowerCase()\n                  .includes(expandConfig.relation.toLowerCase()) ||\n                (expandConfig.selectedFields &&\n                  expandConfig.selectedFields.some((field) =>\n                    errorMessage.toLowerCase().includes(field.toLowerCase()),\n                  ));\n\n              if (isRelatedToExpand) {\n                return {\n                  valid: false,\n                  error: new ValidationError(\n                    `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,\n                    [],\n                    {\n                      field: expandConfig.relation,\n                    },\n                  ),\n                };\n              }\n            }\n          }\n          // If no inline error but expand was expected, that's also an issue\n          // However, this might be a legitimate case (e.g., no related records)\n          // So we'll only fail if there's an explicit error array\n        } else {\n          // Original validation logic for when expand exists\n          if (Array.isArray(expandValue)) {\n            // Validate each item in the expanded array\n            const validatedExpandedItems: any[] = [];\n            for (let i = 0; i < expandValue.length; i++) {\n              const item = expandValue[i];\n              const itemValidation = await validateRecord(\n                item,\n                expandConfig.targetSchema,\n                expandConfig.selectedFields as string[] | undefined,\n                expandConfig.nestedExpands,\n                includeSpecialColumns,\n              );\n              if (!itemValidation.valid) {\n                return {\n                  valid: false,\n                  error: new ValidationError(\n                    `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`,\n                    itemValidation.error.issues,\n                    {\n                      field: expandConfig.relation,\n                      cause: itemValidation.error.cause,\n                    },\n                  ),\n                };\n              }\n              validatedExpandedItems.push(itemValidation.data);\n            }\n            validatedRecord[expandConfig.relation] = validatedExpandedItems;\n          } else {\n            // Single expanded item (shouldn't happen in OData, but handle it)\n            const itemValidation = await validateRecord(\n              expandValue,\n              expandConfig.targetSchema,\n              expandConfig.selectedFields as string[] | undefined,\n              expandConfig.nestedExpands,\n              includeSpecialColumns,\n            );\n            if (!itemValidation.valid) {\n              return {\n                valid: false,\n                error: new ValidationError(\n                  `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,\n                  itemValidation.error.issues,\n                  {\n                    field: expandConfig.relation,\n                    cause: itemValidation.error.cause,\n                  },\n                ),\n              };\n            }\n            validatedRecord[expandConfig.relation] = itemValidation.data;\n          }\n        }\n      }\n    }\n\n    // Merge validated data with metadata and special columns\n    return {\n      valid: true,\n      data: { ...validatedRecord, ...specialColumns, ...metadata } as T &\n        ODataRecordMetadata,\n    };\n  }\n\n  // Validate all fields in schema, but exclude ROWID/ROWMODID by default (unless includeSpecialColumns is enabled)\n  const validatedRecord: Record<string, any> = { ...restWithoutSystemFields };\n\n  for (const [fieldName, fieldSchema] of Object.entries(schema)) {\n    // Skip if no schema for this field\n    if (!fieldSchema) continue;\n    \n    const input = rest[fieldName];\n    try {\n      let result = fieldSchema[\"~standard\"].validate(input);\n      if (result instanceof Promise) result = await result;\n\n      // if the `issues` field exists, the validation failed\n      if (result.issues) {\n        return {\n          valid: false,\n          error: new ValidationError(\n            `Validation failed for field '${fieldName}'`,\n            result.issues,\n            {\n              field: fieldName,\n              value: input,\n              cause: result.issues,\n            },\n          ),\n        };\n      }\n\n      validatedRecord[fieldName] = result.value;\n    } catch (originalError) {\n      // If the validator throws an error directly, catch and wrap it\n      // This preserves the original error instance for instanceof checks\n      return {\n        valid: false,\n        error: new ValidationError(\n          `Validation failed for field '${fieldName}'`,\n          [],\n          {\n            field: fieldName,\n            value: input,\n            cause: originalError,\n          },\n        ),\n      };\n    }\n  }\n\n  // Validate expanded relations even when not using selected fields\n  if (expandConfigs && expandConfigs.length > 0) {\n    for (const expandConfig of expandConfigs) {\n      const expandValue = rest[expandConfig.relation];\n\n      // Check if expand field is missing\n      if (expandValue === undefined) {\n        // Check for inline error array (FileMaker returns errors inline when expand fails)\n        if (Array.isArray(rest.error) && rest.error.length > 0) {\n          // Extract error message from inline error\n          const errorDetail = rest.error[0]?.error;\n          if (errorDetail?.message) {\n            const errorMessage = errorDetail.message;\n            // Check if the error is related to this expand by checking if:\n            // 1. The error mentions the relation name, OR\n            // 2. The error mentions any of the selected fields\n            const isRelatedToExpand =\n              errorMessage\n                .toLowerCase()\n                .includes(expandConfig.relation.toLowerCase()) ||\n              (expandConfig.selectedFields &&\n                expandConfig.selectedFields.some((field) =>\n                  errorMessage.toLowerCase().includes(field.toLowerCase()),\n                ));\n\n            if (isRelatedToExpand) {\n              return {\n                valid: false,\n                error: new ValidationError(\n                  `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,\n                  [],\n                  {\n                    field: expandConfig.relation,\n                  },\n                ),\n              };\n            }\n          }\n        }\n        // If no inline error but expand was expected, that's also an issue\n        // However, this might be a legitimate case (e.g., no related records)\n        // So we'll only fail if there's an explicit error array\n      } else {\n        // Original validation logic for when expand exists\n        if (Array.isArray(expandValue)) {\n          // Validate each item in the expanded array\n          const validatedExpandedItems: any[] = [];\n          for (let i = 0; i < expandValue.length; i++) {\n            const item = expandValue[i];\n            const itemValidation = await validateRecord(\n              item,\n              expandConfig.targetSchema,\n              expandConfig.selectedFields as string[] | undefined,\n              expandConfig.nestedExpands,\n              includeSpecialColumns,\n            );\n            if (!itemValidation.valid) {\n              return {\n                valid: false,\n                error: new ValidationError(\n                  `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`,\n                  itemValidation.error.issues,\n                  {\n                    field: expandConfig.relation,\n                    cause: itemValidation.error.cause,\n                  },\n                ),\n              };\n            }\n            validatedExpandedItems.push(itemValidation.data);\n          }\n          validatedRecord[expandConfig.relation] = validatedExpandedItems;\n        } else {\n          // Single expanded item (shouldn't happen in OData, but handle it)\n          const itemValidation = await validateRecord(\n            expandValue,\n            expandConfig.targetSchema,\n            expandConfig.selectedFields as string[] | undefined,\n            expandConfig.nestedExpands,\n            includeSpecialColumns,\n          );\n          if (!itemValidation.valid) {\n            return {\n              valid: false,\n              error: new ValidationError(\n                `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,\n                itemValidation.error.issues,\n                {\n                  field: expandConfig.relation,\n                  cause: itemValidation.error.cause,\n                },\n              ),\n            };\n          }\n          validatedRecord[expandConfig.relation] = itemValidation.data;\n        }\n      }\n    }\n  }\n\n  return {\n    valid: true,\n    data: { ...validatedRecord, ...specialColumns, ...metadata } as T &\n      ODataRecordMetadata,\n  };\n}\n\n/**\n * Validates a list response against a schema.\n */\nexport async function validateListResponse<T extends Record<string, any>>(\n  response: any,\n  schema: Partial<Record<string, StandardSchemaV1>> | undefined,\n  selectedFields?: (keyof T)[],\n  expandConfigs?: ExpandValidationConfig[],\n  includeSpecialColumns?: boolean,\n): Promise<\n  | { valid: true; data: (T & ODataRecordMetadata)[] }\n  | { valid: false; error: ResponseStructureError | ValidationError }\n> {\n  // Check if response has the expected structure\n  if (!response || typeof response !== \"object\") {\n    return {\n      valid: false,\n      error: new ResponseStructureError(\"an object\", response),\n    };\n  }\n\n  // Extract @context (for internal validation, but we won't return it)\n  const { \"@context\": context, value, ...rest } = response;\n\n  if (!Array.isArray(value)) {\n    return {\n      valid: false,\n      error: new ResponseStructureError(\n        \"'value' property to be an array\",\n        value,\n      ),\n    };\n  }\n\n  // Validate each record in the array\n  const validatedRecords: (T & ODataRecordMetadata)[] = [];\n\n  for (let i = 0; i < value.length; i++) {\n    const record = value[i];\n    const validation = await validateRecord<T>(\n      record,\n      schema,\n      selectedFields,\n      expandConfigs,\n      includeSpecialColumns,\n    );\n\n    if (!validation.valid) {\n      return {\n        valid: false,\n        error: validation.error,\n      };\n    }\n\n    validatedRecords.push(validation.data);\n  }\n\n  return {\n    valid: true,\n    data: validatedRecords,\n  };\n}\n\n/**\n * Validates a single record response against a schema.\n */\nexport async function validateSingleResponse<T extends Record<string, any>>(\n  response: any,\n  schema: Partial<Record<string, StandardSchemaV1>> | undefined,\n  selectedFields?: (keyof T)[],\n  expandConfigs?: ExpandValidationConfig[],\n  mode: \"exact\" | \"maybe\" = \"maybe\",\n  includeSpecialColumns?: boolean,\n): Promise<\n  | { valid: true; data: (T & ODataRecordMetadata) | null }\n  | { valid: false; error: RecordCountMismatchError | ValidationError }\n> {\n  // Check for multiple records (error in both modes)\n  if (\n    response.value &&\n    Array.isArray(response.value) &&\n    response.value.length > 1\n  ) {\n    return {\n      valid: false,\n      error: new RecordCountMismatchError(\n        mode === \"exact\" ? \"one\" : \"at-most-one\",\n        response.value.length,\n      ),\n    };\n  }\n\n  // Handle empty responses\n  if (!response || (response.value && response.value.length === 0)) {\n    if (mode === \"exact\") {\n      return {\n        valid: false,\n        error: new RecordCountMismatchError(\"one\", 0),\n      };\n    }\n    // mode === \"maybe\" - return null for empty\n    return {\n      valid: true,\n      data: null,\n    };\n  }\n\n  // Single record validation\n  const record = response.value?.[0] ?? response;\n  const validation = await validateRecord<T>(\n    record,\n    schema,\n    selectedFields,\n    expandConfigs,\n    includeSpecialColumns,\n  );\n\n  if (!validation.valid) {\n    return validation as { valid: false; error: ValidationError };\n  }\n\n  return {\n    valid: true,\n    data: validation.data,\n  };\n}\n"],"names":["ROWID","ROWMODID","restWithoutSystemFields","specialColumns","validatedRecord"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proofkit/fmodata",
-  "version": "0.1.0-alpha.19",
+  "version": "0.1.0-alpha.20",
   "description": "FileMaker OData API client",
   "repository": "git@github.com:proofgeist/proofkit.git",
   "author": "Eric <37158449+eluce2@users.noreply.github.com>",
@@ -63,7 +63,7 @@
     "vite": "^6.3.4",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.0.7",
-    "zod": "4.1.12"
+    "zod": "^4.1.13"
   },
   "engines": {
     "node": ">=18.0.0"

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

@@ -20,9 +20,13 @@ function getContainerFieldNames(table: FMTable<any, any>): string[] {
  * Gets default select fields from a table definition.
  * Returns undefined if defaultSelect is "all".
  * Automatically filters out container fields since they cannot be selected via $select.
+ * 
+ * @param table - The table occurrence
+ * @param includeSpecialColumns - If true, includes ROWID and ROWMODID when defaultSelect is "schema"
  */
 export function getDefaultSelectFields(
   table: FMTable<any, any> | undefined,
+  includeSpecialColumns?: boolean,
 ): string[] | undefined {
   if (!table) return undefined;
 
@@ -33,7 +37,14 @@ export function getDefaultSelectFields(
     const baseTableConfig = getBaseTableConfig(table);
     const allFields = Object.keys(baseTableConfig.schema);
     // Filter out container fields
-    return [...new Set(allFields.filter((f) => !containerFields.includes(f)))];
+    const fields = [...new Set(allFields.filter((f) => !containerFields.includes(f)))];
+    
+    // Add special columns if requested
+    if (includeSpecialColumns) {
+      fields.push("ROWID", "ROWMODID");
+    }
+    
+    return fields;
   }
 
   if (Array.isArray(defaultSelect)) {

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

@@ -40,7 +40,7 @@ export class ExpandBuilder {
     return configs.map((config) => {
       const targetTable = config.targetTable;
 
-      let targetSchema: Record<string, StandardSchemaV1> | undefined;
+      let targetSchema: Partial<Record<string, StandardSchemaV1>> | undefined;
       if (targetTable) {
         const baseTableConfig = getBaseTableConfig(targetTable);
         const containerFields = baseTableConfig.containerFields || [];

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

@@ -17,12 +17,18 @@ export function buildSelectExpandQueryString(config: {
   table?: FMTable<any, any>;
   useEntityIds: boolean;
   logger: InternalLogger;
+  includeSpecialColumns?: boolean;
 }): string {
   const parts: string[] = [];
   const expandBuilder = new ExpandBuilder(config.useEntityIds, config.logger);
 
   // Build $select
   if (config.selectedFields && config.selectedFields.length > 0) {
+    // Important: do NOT implicitly add system columns (ROWID/ROWMODID) here.
+    // - `includeSpecialColumns` controls the Prefer header + response parsing, but should not
+    //   mutate/expand an explicit `$select` (e.g. when the user calls `.select({ ... })`).
+    // - If system columns are desired with `.select()`, they must be explicitly included via
+    //   the `systemColumns` argument, which will already have added them to `selectedFields`.
     const selectString = formatSelectFields(
       config.selectedFields,
       config.table,

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

@@ -17,6 +17,7 @@ export interface ProcessResponseConfig {
   expandValidationConfigs?: ExpandValidationConfig[];
   skipValidation?: boolean;
   useEntityIds?: boolean;
+  includeSpecialColumns?: boolean;
   // Mapping from field names to output keys (for renamed fields in select)
   fieldMapping?: Record<string, string>;
 }
@@ -37,6 +38,7 @@ export async function processODataResponse<T>(
     expandValidationConfigs,
     skipValidation,
     useEntityIds,
+    includeSpecialColumns,
     fieldMapping,
   } = config;
 
@@ -67,6 +69,9 @@ export async function processODataResponse<T>(
   }
 
   // Validation path
+  // Note: Special columns are excluded when using QueryBuilder.single() method,
+  // but included for RecordBuilder.get() method (both use singleMode: "exact")
+  // The exclusion is handled in QueryBuilder's processQueryResponse, not here
   if (singleMode !== false) {
     const validation = await validateSingleResponse<any>(
       response,
@@ -74,6 +79,7 @@ export async function processODataResponse<T>(
       selectedFields as any,
       expandValidationConfigs,
       singleMode,
+      includeSpecialColumns,
     );
 
     if (!validation.valid) {
@@ -96,6 +102,7 @@ export async function processODataResponse<T>(
     schema,
     selectedFields as any,
     expandValidationConfigs,
+    includeSpecialColumns,
   );
 
   if (!validation.valid) {
@@ -223,6 +230,7 @@ export async function processQueryResponse<T>(
     expandConfigs: ExpandConfig[];
     skipValidation?: boolean;
     useEntityIds?: boolean;
+    includeSpecialColumns?: boolean;
     // Mapping from field names to output keys (for renamed fields in select)
     fieldMapping?: Record<string, string>;
     logger: InternalLogger;
@@ -235,6 +243,7 @@ export async function processQueryResponse<T>(
     expandConfigs,
     skipValidation,
     useEntityIds,
+    includeSpecialColumns,
     fieldMapping,
     logger,
   } = config;
@@ -258,6 +267,7 @@ export async function processQueryResponse<T>(
     expandValidationConfigs,
     skipValidation,
     useEntityIds,
+    includeSpecialColumns,
   });
 
   // Rename fields if field mapping is provided (for renamed fields in select)

package/src/client/database.ts

@@ -4,10 +4,26 @@ import { EntitySet } from "./entity-set";
 import { BatchBuilder } from "./batch-builder";
 import { SchemaManager } from "./schema-manager";
 import { FMTable } from "../orm/table";
+import { WebhookManager } from "./webhook-builder";
 
-export class Database {
+type MetadataArgs = {
+  format?: "xml" | "json";
+  /**
+   * If provided, only the metadata for the specified table will be returned.
+   * Requires FileMaker Server 22.0.4 or later.
+   */
+  tableName?: string;
+  /**
+   * If true, a reduced payload size will be returned by omitting certain annotations.
+   */
+  reduceAnnotations?: boolean;
+};
+
+export class Database<IncludeSpecialColumns extends boolean = false> {
   private _useEntityIds: boolean = false;
+  private _includeSpecialColumns: IncludeSpecialColumns;
   public readonly schema: SchemaManager;
+  public readonly webhook: WebhookManager;
 
   constructor(
     private readonly databaseName: string,
@@ -19,14 +35,24 @@ export class Database {
        * If set to false but some occurrences do not use entity IDs, an error will be thrown
        */
       useEntityIds?: boolean;
+      /**
+       * Whether to include special columns (ROWID and ROWMODID) in responses.
+       * Note: Special columns are only included when there is no $select query.
+       */
+      includeSpecialColumns?: IncludeSpecialColumns;
     },
   ) {
     // Initialize schema manager
     this.schema = new SchemaManager(this.databaseName, this.context);
+    this.webhook = new WebhookManager(this.databaseName, this.context);
     this._useEntityIds = config?.useEntityIds ?? false;
+    this._includeSpecialColumns = (config?.includeSpecialColumns ??
+      false) as IncludeSpecialColumns;
   }
 
-  from<T extends FMTable<any, any>>(table: T): EntitySet<T> {
+  from<T extends FMTable<any, any>>(
+    table: T,
+  ): EntitySet<T, IncludeSpecialColumns> {
     // Only override database-level useEntityIds if table explicitly sets it
     // (not if it's undefined, which would override the database setting)
     if (
@@ -37,7 +63,7 @@ export class Database {
         this._useEntityIds = tableUseEntityIds;
       }
     }
-    return new EntitySet<T>({
+    return new EntitySet<T, IncludeSpecialColumns>({
       occurrence: table as T,
       databaseName: this.databaseName,
       context: this.context,
@@ -49,19 +75,35 @@ export class Database {
    * Retrieves the OData metadata for this database.
    * @param args Optional configuration object
    * @param args.format The format to retrieve metadata in. Defaults to "json".
+   * @param args.tableName If provided, only the metadata for the specified table will be returned. Requires FileMaker Server 22.0.4 or later.
+   * @param args.reduceAnnotations If true, a reduced payload size will be returned by omitting certain annotations.
    * @returns The metadata in the specified format
    */
-  async getMetadata(args: { format: "xml" }): Promise<string>;
-  async getMetadata(args?: { format?: "json" }): Promise<Metadata>;
-  async getMetadata(args?: {
-    format?: "xml" | "json";
-  }): Promise<string | Metadata> {
+  async getMetadata(args: { format: "xml" } & MetadataArgs): Promise<string>;
+  async getMetadata(
+    args?: { format?: "json" } & MetadataArgs,
+  ): Promise<Metadata>;
+  async getMetadata(args?: MetadataArgs): Promise<string | Metadata> {
+    // Build the URL - if tableName is provided, append %23{tableName} to the path
+    let url = `/${this.databaseName}/$metadata`;
+    if (args?.tableName) {
+      url = `/${this.databaseName}/$metadata%23${args.tableName}`;
+    }
+
+    // Build headers
+    const headers: Record<string, string> = {
+      Accept: args?.format === "xml" ? "application/xml" : "application/json",
+    };
+
+    // Add Prefer header if reduceAnnotations is true
+    if (args?.reduceAnnotations) {
+      headers["Prefer"] = 'include-annotations="-*"';
+    }
+
     const result = await this.context._makeRequest<
       Record<string, Metadata> | string
-    >(`/${this.databaseName}/$metadata`, {
-      headers: {
-        Accept: args?.format === "xml" ? "application/xml" : "application/json",
-      },
+    >(url, {
+      headers,
     });
     if (result.error) {
       throw result.error;

package/src/client/delete-builder.ts

@@ -2,7 +2,7 @@ import type {
   ExecutionContext,
   ExecutableBuilder,
   Result,
-  WithSystemFields,
+  WithSpecialColumns,
   ExecuteOptions,
   ExecuteMethodOptions,
 } from "../types";
@@ -26,17 +26,21 @@ export class DeleteBuilder<Occ extends FMTable<any, any>> {
   private context: ExecutionContext;
   private table: Occ;
   private databaseUseEntityIds: boolean;
+  private databaseIncludeSpecialColumns: boolean;
 
   constructor(config: {
     occurrence: Occ;
     databaseName: string;
     context: ExecutionContext;
     databaseUseEntityIds?: boolean;
+    databaseIncludeSpecialColumns?: boolean;
   }) {
     this.table = config.occurrence;
     this.databaseName = config.databaseName;
     this.context = config.context;
     this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
+    this.databaseIncludeSpecialColumns =
+      config.databaseIncludeSpecialColumns ?? false;
   }
 
   /**

package/src/client/entity-set.ts

@@ -19,6 +19,7 @@ import {
   getDefaultSelect,
   getTableName,
   getTableColumns,
+  getTableSchema,
 } from "../orm/table";
 import type { FieldBuilder } from "../orm/field-builders";
 import { createLogger, InternalLogger } from "../logger";
@@ -41,16 +42,20 @@ type ExtractColumnsFromOcc<T> =
       : never
     : never;
 
-export class EntitySet<Occ extends FMTable<any, any>> {
+export class EntitySet<
+  Occ extends FMTable<any, any>,
+  DatabaseIncludeSpecialColumns extends boolean = false,
+> {
   private occurrence: Occ;
   private databaseName: string;
   private context: ExecutionContext;
-  private database: Database; // Database instance for accessing occurrences
+  private database: Database<DatabaseIncludeSpecialColumns>; // Database instance for accessing occurrences
   private isNavigateFromEntitySet?: boolean;
   private navigateRelation?: string;
   private navigateSourceTableName?: string;
   private navigateBasePath?: string; // Full base path for chained navigations
   private databaseUseEntityIds: boolean;
+  private databaseIncludeSpecialColumns: DatabaseIncludeSpecialColumns;
   private logger: InternalLogger;
 
   constructor(config: {
@@ -66,17 +71,23 @@ 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;
+    // Get includeSpecialColumns from database if available, otherwise default to false
+    this.databaseIncludeSpecialColumns =
+      (config.database as any)?._includeSpecialColumns ?? false;
     this.logger = config.context?._getLogger?.() ?? createLogger();
   }
 
   // Type-only method to help TypeScript infer the schema from table
-  static create<Occ extends FMTable<any, any>>(config: {
+  static create<
+    Occ extends FMTable<any, any>,
+    DatabaseIncludeSpecialColumns extends boolean = false,
+  >(config: {
     occurrence: Occ;
     databaseName: string;
     context: ExecutionContext;
-    database: Database;
-  }): EntitySet<Occ> {
-    return new EntitySet<Occ>({
+    database: Database<DatabaseIncludeSpecialColumns>;
+  }): EntitySet<Occ, DatabaseIncludeSpecialColumns> {
+    return new EntitySet<Occ, DatabaseIncludeSpecialColumns>({
       occurrence: config.occurrence,
       databaseName: config.databaseName,
       context: config.context,
@@ -89,33 +100,30 @@ export class EntitySet<Occ extends FMTable<any, any>> {
     keyof InferSchemaOutputFromFMTable<Occ>,
     false,
     false,
-    {}
+    {},
+    DatabaseIncludeSpecialColumns
   > {
-    const builder = new QueryBuilder<Occ>({
+    const builder = new QueryBuilder<
+      Occ,
+      keyof InferSchemaOutputFromFMTable<Occ>,
+      false,
+      false,
+      {},
+      DatabaseIncludeSpecialColumns
+    >({
       occurrence: this.occurrence as Occ,
       databaseName: this.databaseName,
       context: this.context,
       databaseUseEntityIds: this.databaseUseEntityIds,
+      databaseIncludeSpecialColumns: this.databaseIncludeSpecialColumns,
     });
 
     // Apply defaultSelect if occurrence exists and select hasn't been called
     if (this.occurrence) {
       // FMTable - access via helper functions
       const defaultSelectValue = getDefaultSelect(this.occurrence);
-      const tableSchema = (this.occurrence as any)[FMTableClass.Symbol.Schema];
-      let schema: Record<string, StandardSchemaV1> | undefined;
-
-      if (tableSchema) {
-        // Extract schema from StandardSchemaV1
-        const zodSchema = tableSchema["~standard"]?.schema;
-        if (
-          zodSchema &&
-          typeof zodSchema === "object" &&
-          "shape" in zodSchema
-        ) {
-          schema = zodSchema.shape as Record<string, StandardSchemaV1>;
-        }
-      }
+      // Schema is stored directly as Partial<Record<keyof TFields, StandardSchemaV1>>
+      const schema = getTableSchema(this.occurrence);
 
       if (defaultSelectValue === "schema") {
         // Use getTableColumns to get all columns and select them
@@ -124,12 +132,22 @@ export class EntitySet<Occ extends FMTable<any, any>> {
         const allColumns = getTableColumns(
           this.occurrence,
         ) as ExtractColumnsFromOcc<Occ>;
-        return builder.select(allColumns).top(1000) as QueryBuilder<
+
+        // Include special columns if enabled at database level
+        const systemColumns = this.databaseIncludeSpecialColumns
+          ? { ROWID: true, ROWMODID: true }
+          : undefined;
+
+        return builder
+          .select(allColumns, systemColumns)
+          .top(1000) as QueryBuilder<
           Occ,
           keyof InferSchemaOutputFromFMTable<Occ>,
           false,
           false,
-          {}
+          {},
+          DatabaseIncludeSpecialColumns,
+          typeof systemColumns
         >;
       } else if (typeof defaultSelectValue === "object") {
         // defaultSelectValue is a select object (Record<string, Column>)
@@ -141,7 +159,8 @@ export class EntitySet<Occ extends FMTable<any, any>> {
           keyof InferSchemaOutputFromFMTable<Occ>,
           false,
           false,
-          {}
+          {},
+          DatabaseIncludeSpecialColumns
         >;
       }
       // If defaultSelect is "all", no changes needed (current behavior)
@@ -173,34 +192,31 @@ export class EntitySet<Occ extends FMTable<any, any>> {
     false,
     undefined,
     keyof InferSchemaOutputFromFMTable<Occ>,
-    {}
+    {},
+    DatabaseIncludeSpecialColumns
   > {
-    const builder = new RecordBuilder<Occ>({
+    const builder = new RecordBuilder<
+      Occ,
+      false,
+      undefined,
+      keyof InferSchemaOutputFromFMTable<Occ>,
+      {},
+      DatabaseIncludeSpecialColumns
+    >({
       occurrence: this.occurrence,
       databaseName: this.databaseName,
       context: this.context,
       recordId: id,
       databaseUseEntityIds: this.databaseUseEntityIds,
+      databaseIncludeSpecialColumns: this.databaseIncludeSpecialColumns,
     });
 
     // Apply defaultSelect if occurrence exists
     if (this.occurrence) {
       // FMTable - access via helper functions
       const defaultSelectValue = getDefaultSelect(this.occurrence);
-      const tableSchema = (this.occurrence as any)[FMTableClass.Symbol.Schema];
-      let schema: Record<string, StandardSchemaV1> | undefined;
-
-      if (tableSchema) {
-        // Extract schema from StandardSchemaV1
-        const zodSchema = tableSchema["~standard"]?.schema;
-        if (
-          zodSchema &&
-          typeof zodSchema === "object" &&
-          "shape" in zodSchema
-        ) {
-          schema = zodSchema.shape as Record<string, StandardSchemaV1>;
-        }
-      }
+      // Schema is stored directly as Partial<Record<keyof TFields, StandardSchemaV1>>
+      const schema = getTableSchema(this.occurrence);
 
       if (defaultSelectValue === "schema") {
         // Use getTableColumns to get all columns and select them
@@ -209,7 +225,13 @@ export class EntitySet<Occ extends FMTable<any, any>> {
         const allColumns = getTableColumns(
           this.occurrence as any,
         ) as ExtractColumnsFromOcc<Occ>;
-        const selectedBuilder = builder.select(allColumns);
+
+        // Include special columns if enabled at database level
+        const systemColumns = this.databaseIncludeSpecialColumns
+          ? { ROWID: true, ROWMODID: true }
+          : undefined;
+
+        const selectedBuilder = builder.select(allColumns, systemColumns);
         // Propagate navigation context if present
         if (
           this.isNavigateFromEntitySet &&
@@ -293,6 +315,7 @@ export class EntitySet<Occ extends FMTable<any, any>> {
       data: data as any, // Input type is validated/transformed at runtime
       returnPreference: returnPreference as any,
       databaseUseEntityIds: this.databaseUseEntityIds,
+      databaseIncludeSpecialColumns: this.databaseIncludeSpecialColumns,
     });
   }
 
@@ -323,6 +346,7 @@ export class EntitySet<Occ extends FMTable<any, any>> {
       data: data as any, // Input type is validated/transformed at runtime
       returnPreference: returnPreference as any,
       databaseUseEntityIds: this.databaseUseEntityIds,
+      databaseIncludeSpecialColumns: this.databaseIncludeSpecialColumns,
     });
   }
 
@@ -332,13 +356,17 @@ export class EntitySet<Occ extends FMTable<any, any>> {
       databaseName: this.databaseName,
       context: this.context,
       databaseUseEntityIds: this.databaseUseEntityIds,
+      databaseIncludeSpecialColumns: this.databaseIncludeSpecialColumns,
     }) as any;
   }
 
   // Implementation
   navigate<TargetTable extends FMTable<any, any>>(
     targetTable: ValidExpandTarget<Occ, TargetTable>,
-  ): EntitySet<TargetTable extends FMTable<any, any> ? TargetTable : never> {
+  ): EntitySet<
+    TargetTable extends FMTable<any, any> ? TargetTable : never,
+    DatabaseIncludeSpecialColumns
+  > {
     // Check if it's an FMTable object or a string
     let relationName: string;
 
@@ -361,7 +389,7 @@ export class EntitySet<Occ extends FMTable<any, any>> {
     }
 
     // Create EntitySet with target table
-    const entitySet = new EntitySet<any>({
+    const entitySet = new EntitySet<any, DatabaseIncludeSpecialColumns>({
       occurrence: targetTable,
       databaseName: this.databaseName,
       context: this.context,