@proofkit/fmodata 0.1.0-alpha.0 → 0.1.0-alpha.10

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 { TableOccurrence } from \"./client/table-occurrence\";\n\n// Type for expand validation configuration\nexport type ExpandValidationConfig = {\n  relation: string;\n  targetSchema?: Record<string, StandardSchemaV1>;\n  targetOccurrence?: TableOccurrence<any, any, any, any>;\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: Error }\n> {\n  // Extract OData metadata fields (don't validate them - include if present)\n  const { \"@id\": id, \"@editLink\": editLink, ...rest } = record;\n\n  // Include metadata fields if present (don't validate they exist)\n  const metadata: ODataRecordMetadata = {\n    \"@id\": id || \"\",\n    \"@editLink\": editLink || \"\",\n  };\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        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 Error(\n              `Validation failed for field '${fieldName}': ${JSON.stringify(result.issues, null, 2)}`,\n            ),\n          };\n        }\n\n        validatedRecord[fieldName] = result.value;\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 Error(\n                    `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,\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 Error(\n                    `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`,\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 Error(\n                  `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,\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    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 Error(\n          `Validation failed for field '${fieldName}': ${JSON.stringify(result.issues, null, 2)}`,\n        ),\n      };\n    }\n\n    validatedRecord[fieldName] = result.value;\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 Error(\n                  `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,\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 Error(\n                  `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`,\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 Error(\n                `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,\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: Error }\n> {\n  // Check if response has the expected structure\n  if (!response || typeof response !== \"object\") {\n    return {\n      valid: false,\n      error: new Error(\"Invalid response: expected an object\"),\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 Error(\n        \"Invalid response: expected 'value' property to be an array\",\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: new Error(\n          `Validation failed for record at index ${i}: ${validation.error.message}`,\n        ),\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: Error }\n> {\n  // Check for multiple records (error in both modes)\n  if (response.value && Array.isArray(response.value) && response.value.length > 1) {\n    return {\n      valid: false,\n      error: new Error(\n        `Expected ${mode === \"exact\" ? \"exactly one\" : \"at most one\"} record, but received ${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 Error(\"Expected exactly one record, but received none\"),\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: Error };\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 { TableOccurrence } from \"./client/table-occurrence\";\nimport {\n  ValidationError,\n  ResponseStructureError,\n  RecordCountMismatchError,\n} from \"./errors\";\n\n// Type for expand validation configuration\nexport type ExpandValidationConfig = {\n  relation: string;\n  targetSchema?: Record<string, StandardSchemaV1>;\n  targetOccurrence?: TableOccurrence<any, any, any, any>;\n  targetBaseTable?: any; // BaseTable instance for transformation\n  occurrence?: TableOccurrence<any, any, 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  // Include metadata fields if present (don't validate they exist)\n  const metadata: ODataRecordMetadata = {\n    \"@id\": id || \"\",\n    \"@editLink\": editLink || \"\",\n  };\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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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proofkit/fmodata",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.10",
   "description": "FileMaker OData API client",
   "repository": "git@github.com:proofgeist/proofkit.git",
   "author": "Eric <37158449+eluce2@users.noreply.github.com>",
@@ -38,6 +38,14 @@
     "neverthrow": "^8.2.0",
     "odata-query": "^8.0.4"
   },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/vite-config": "^0.2.0",
@@ -47,6 +55,7 @@
     "tsx": "^4.19.2",
     "typescript": "^5.9.3",
     "vite": "^6.3.4",
+    "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.0.7",
     "zod": "4.1.12"
   },

package/src/client/base-table.ts

@@ -1,25 +1,175 @@
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
+/**
+ * BaseTable defines the schema and configuration for a table.
+ *
+ * @template Schema - Record of field names to StandardSchemaV1 validators
+ * @template IdField - The name of the primary key field (optional, automatically read-only)
+ * @template Required - Additional field names to require on insert (beyond auto-inferred required fields)
+ * @template ReadOnly - Field names that cannot be modified via insert/update (idField is automatically read-only)
+ *
+ * @example Basic table with auto-inferred required fields
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const usersTable = new BaseTable({
+ *   schema: {
+ *     id: z.string(),               // Auto-required (not nullable), auto-readOnly (idField)
+ *     name: z.string(),             // Auto-required (not nullable)
+ *     email: z.string().nullable(), // Optional (nullable)
+ *   },
+ *   idField: "id",
+ * });
+ * // On insert: name is required, email is optional (id is excluded - readOnly)
+ * // On update: name and email available (id is excluded - readOnly)
+ * ```
+ *
+ * @example Table with additional required and readOnly fields
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const usersTable = new BaseTable({
+ *   schema: {
+ *     id: z.string(),                    // Auto-required, auto-readOnly (idField)
+ *     createdAt: z.string(),             // Read-only system field
+ *     name: z.string(),                  // Auto-required
+ *     email: z.string().nullable(),      // Optional by default...
+ *     legacyField: z.string().nullable(), // Optional by default...
+ *   },
+ *   idField: "id",
+ *   required: ["legacyField"],  // Make legacyField required for new inserts
+ *   readOnly: ["createdAt"],    // Exclude from insert/update
+ * });
+ * // On insert: name and legacyField required; email optional (id and createdAt excluded)
+ * // On update: all fields optional (id and createdAt excluded)
+ * ```
+ *
+ * @example Table with multiple read-only fields
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const usersTable = new BaseTable({
+ *   schema: {
+ *     id: z.string(),
+ *     createdAt: z.string(),
+ *     modifiedAt: z.string(),
+ *     createdBy: z.string(),
+ *     notes: z.string().nullable(),
+ *   },
+ *   idField: "id",
+ *   readOnly: ["createdAt", "modifiedAt", "createdBy"],
+ * });
+ * // On insert/update: only notes is available (id and system fields excluded)
+ * ```
+ */
 export class BaseTable<
   Schema extends Record<string, StandardSchemaV1> = any,
   IdField extends keyof Schema | undefined = undefined,
-  InsertRequired extends readonly (keyof Schema)[] = readonly [],
-  UpdateRequired extends readonly (keyof Schema)[] = readonly [],
+  Required extends readonly (keyof Schema | (string & {}))[] = readonly [],
+  ReadOnly extends readonly (keyof Schema | (string & {}))[] = readonly [],
 > {
   public readonly schema: Schema;
   public readonly idField?: IdField;
-  public readonly insertRequired?: InsertRequired;
-  public readonly updateRequired?: UpdateRequired;
+  public readonly required?: Required;
+  public readonly readOnly?: ReadOnly;
+  public readonly fmfIds?: Record<
+    keyof Schema | (string & {}),
+    `FMFID:${string}`
+  >;
 
   constructor(config: {
     schema: Schema;
     idField?: IdField;
-    insertRequired?: InsertRequired;
-    updateRequired?: UpdateRequired;
+    required?: Required;
+    readOnly?: ReadOnly;
+    fmfIds?: Record<string, `FMFID:${string}`>;
   }) {
     this.schema = config.schema;
     this.idField = config.idField;
-    this.insertRequired = config.insertRequired;
-    this.updateRequired = config.updateRequired;
+    this.required = config.required;
+    this.readOnly = config.readOnly;
+    this.fmfIds = config.fmfIds as
+      | Record<keyof Schema, `FMFID:${string}`>
+      | undefined;
   }
+
+  /**
+   * Returns the FileMaker field ID (FMFID) for a given field name, or the field name itself if not using IDs.
+   * @param fieldName - The field name to get the ID for
+   * @returns The FMFID string or the original field name
+   */
+  getFieldId(fieldName: keyof Schema): string {
+    if (this.fmfIds && fieldName in this.fmfIds) {
+      return this.fmfIds[fieldName];
+    }
+    return String(fieldName);
+  }
+
+  /**
+   * Returns the field name for a given FileMaker field ID (FMFID), or the ID itself if not found.
+   * @param fieldId - The FMFID to get the field name for
+   * @returns The field name or the original ID
+   */
+  getFieldName(fieldId: string): string {
+    if (this.fmfIds) {
+      // Search for the field name that corresponds to this FMFID
+      for (const [fieldName, fmfId] of Object.entries(this.fmfIds)) {
+        if (fmfId === fieldId) {
+          return fieldName;
+        }
+      }
+    }
+    return fieldId;
+  }
+
+  /**
+   * Returns true if this BaseTable is using FileMaker field IDs.
+   */
+  isUsingFieldIds(): boolean {
+    return this.fmfIds !== undefined;
+  }
+}
+
+/**
+ * Creates a BaseTable with proper TypeScript type inference.
+ *
+ * This function should be used instead of `new BaseTable()` to ensure
+ * field names are properly typed throughout the library.
+ *
+ * @example Without entity IDs
+ * ```ts
+ * const users = defineBaseTable({
+ *   schema: { id: z.string(), name: z.string() },
+ *   idField: "id",
+ * });
+ * ```
+ *
+ * @example With entity IDs (FileMaker field IDs)
+ * ```ts
+ * const products = defineBaseTable({
+ *   schema: { id: z.string(), name: z.string() },
+ *   idField: "id",
+ *   fmfIds: { id: "FMFID:1", name: "FMFID:2" },
+ * });
+ * ```
+ */
+export function defineBaseTable<
+  const Schema extends Record<string, StandardSchemaV1>,
+  IdField extends keyof Schema | undefined = undefined,
+  const Required extends readonly (
+    | keyof Schema
+    | (string & {})
+  )[] = readonly [],
+  const ReadOnly extends readonly (
+    | keyof Schema
+    | (string & {})
+  )[] = readonly [],
+>(config: {
+  schema: Schema;
+  idField?: IdField;
+  required?: Required;
+  readOnly?: ReadOnly;
+  fmfIds?: { [K in keyof Schema | (string & {})]: `FMFID:${string}` };
+}): BaseTable<Schema, IdField, Required, ReadOnly> {
+  return new BaseTable(config);
 }

package/src/client/batch-builder.ts

@@ -0,0 +1,265 @@
+import type {
+  ExecutableBuilder,
+  ExecutionContext,
+  Result,
+  ExecuteOptions,
+} from "../types";
+import { type FFetchOptions } from "@fetchkit/ffetch";
+import {
+  formatBatchRequestFromNative,
+  parseBatchResponse,
+  type ParsedBatchResponse,
+} from "./batch-request";
+
+/**
+ * Helper type to extract result types from a tuple of ExecutableBuilders.
+ * Uses a mapped type which TypeScript 4.1+ can handle for tuples.
+ */
+type ExtractTupleTypes<T extends readonly ExecutableBuilder<any>[]> = {
+  [K in keyof T]: T[K] extends ExecutableBuilder<infer U> ? U : never;
+};
+
+/**
+ * Converts a ParsedBatchResponse to a native Response object
+ * @param parsed - The parsed batch response
+ * @returns A native Response object
+ */
+function parsedToResponse(parsed: ParsedBatchResponse): Response {
+  const headers = new Headers(parsed.headers);
+
+  // Handle null body
+  if (parsed.body === null || parsed.body === undefined) {
+    return new Response(null, {
+      status: parsed.status,
+      statusText: parsed.statusText,
+      headers,
+    });
+  }
+
+  // Convert body to string if it's not already
+  const bodyString =
+    typeof parsed.body === "string" ? parsed.body : JSON.stringify(parsed.body);
+
+  // Handle 204 No Content status - it cannot have a body per HTTP spec
+  // If FileMaker returns 204 with a body, treat it as 200
+  let status = parsed.status;
+  if (status === 204 && bodyString && bodyString.trim() !== "") {
+    status = 200;
+  }
+
+  return new Response(status === 204 ? null : bodyString, {
+    status: status,
+    statusText: parsed.statusText,
+    headers,
+  });
+}
+
+/**
+ * Builder for batch operations that allows multiple queries to be executed together
+ * in a single transactional request.
+ */
+export class BatchBuilder<Builders extends readonly ExecutableBuilder<any>[]>
+  implements ExecutableBuilder<ExtractTupleTypes<Builders>>
+{
+  private builders: ExecutableBuilder<any>[];
+  private readonly originalBuilders: Builders;
+
+  constructor(
+    builders: Builders,
+    private readonly databaseName: string,
+    private readonly context: ExecutionContext,
+  ) {
+    // Convert readonly tuple to mutable array for dynamic additions
+    this.builders = [...builders];
+    // Store original tuple for type preservation
+    this.originalBuilders = builders;
+  }
+
+  /**
+   * Add a request to the batch dynamically.
+   * This allows building up batch operations programmatically.
+   *
+   * @param builder - An executable builder to add to the batch
+   * @returns This BatchBuilder for method chaining
+   * @example
+   * ```ts
+   * const batch = db.batch([]);
+   * batch.addRequest(db.from('contacts').list());
+   * batch.addRequest(db.from('users').list());
+   * const result = await batch.execute();
+   * ```
+   */
+  addRequest<T>(builder: ExecutableBuilder<T>): this {
+    this.builders.push(builder);
+    return this;
+  }
+
+  /**
+   * Get the request configuration for this batch operation.
+   * This is used internally by the execution system.
+   */
+  getRequestConfig(): { method: string; url: string; body?: any } {
+    // Note: This method is kept for compatibility but batch operations
+    // should use execute() directly which handles the full Request/Response flow
+    return {
+      method: "POST",
+      url: `/${this.databaseName}/$batch`,
+      body: undefined, // Body is constructed in execute()
+    };
+  }
+
+  toRequest(baseUrl: string): Request {
+    // Batch operations are not designed to be nested, but we provide
+    // a basic implementation for interface compliance
+    const fullUrl = `${baseUrl}/${this.databaseName}/$batch`;
+    return new Request(fullUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "multipart/mixed",
+        "OData-Version": "4.0",
+      },
+    });
+  }
+
+  async processResponse(
+    response: Response,
+    options?: ExecuteOptions,
+  ): Promise<Result<any>> {
+    // This should not typically be called for batch operations
+    // as they handle their own response processing
+    return {
+      data: undefined,
+      error: {
+        name: "NotImplementedError",
+        message: "Batch operations handle response processing internally",
+        timestamp: new Date(),
+      } as any,
+    };
+  }
+
+  /**
+   * Execute the batch operation.
+   *
+   * @param options - Optional fetch options and batch-specific options (includes beforeRequest hook)
+   * @returns A tuple of results matching the input builders
+   */
+  async execute<EO extends ExecuteOptions>(
+    options?: RequestInit & FFetchOptions & EO,
+  ): Promise<Result<ExtractTupleTypes<Builders>>> {
+    const baseUrl = this.context._getBaseUrl?.();
+    if (!baseUrl) {
+      return {
+        data: undefined,
+        error: {
+          name: "ConfigurationError",
+          message:
+            "Base URL not available - execution context must implement _getBaseUrl()",
+          timestamp: new Date(),
+        } as any,
+      };
+    }
+
+    try {
+      // Convert builders to native Request objects
+      const requests: Request[] = this.builders.map((builder) =>
+        builder.toRequest(baseUrl),
+      );
+
+      // Format batch request (automatically groups mutations into changesets)
+      const { body, boundary } = await formatBatchRequestFromNative(
+        requests,
+        baseUrl,
+      );
+
+      // Execute the batch request
+      const response = await this.context._makeRequest<string>(
+        `/${this.databaseName}/$batch`,
+        {
+          ...options,
+          method: "POST",
+          headers: {
+            ...options?.headers,
+            "Content-Type": `multipart/mixed; boundary=${boundary}`,
+            "OData-Version": "4.0",
+          },
+          body,
+        },
+      );
+
+      if (response.error) {
+        return { data: undefined, error: response.error };
+      }
+
+      // Extract the actual boundary from the response
+      // FileMaker uses its own boundary, not the one we sent
+      const firstLine =
+        response.data.split("\r\n")[0] || response.data.split("\n")[0] || "";
+      const actualBoundary = firstLine.startsWith("--")
+        ? firstLine.substring(2)
+        : boundary;
+
+      // Parse the multipart response
+      const contentTypeHeader = `multipart/mixed; boundary=${actualBoundary}`;
+      const parsedResponses = parseBatchResponse(
+        response.data,
+        contentTypeHeader,
+      );
+
+      // Check if we got the expected number of responses
+      if (parsedResponses.length !== this.builders.length) {
+        return {
+          data: undefined,
+          error: {
+            name: "BatchError",
+            message: `Expected ${this.builders.length} responses but got ${parsedResponses.length}`,
+            timestamp: new Date(),
+          } as any,
+        };
+      }
+
+      // Process each response using the corresponding builder
+      // Build tuple by processing each builder in order
+      type ResultTuple = ExtractTupleTypes<Builders>;
+
+      // Process builders sequentially to preserve tuple order
+      const processedResults: any[] = [];
+      for (let i = 0; i < this.originalBuilders.length; i++) {
+        const builder = this.originalBuilders[i];
+        const parsed = parsedResponses[i];
+
+        if (!builder || !parsed) {
+          processedResults.push(undefined);
+          continue;
+        }
+
+        // Convert parsed response to native Response
+        const nativeResponse = parsedToResponse(parsed);
+
+        // Let the builder process its own response
+        const result = await builder.processResponse(nativeResponse, options);
+
+        if (result.error) {
+          processedResults.push(undefined);
+        } else {
+          processedResults.push(result.data);
+        }
+      }
+
+      // Use a type assertion that TypeScript will respect
+      // ExtractTupleTypes ensures this is a proper tuple type
+      return {
+        data: processedResults as unknown as ResultTuple,
+        error: undefined,
+      };
+    } catch (err) {
+      return {
+        data: undefined,
+        error: {
+          name: "BatchError",
+          message: err instanceof Error ? err.message : "Unknown error",
+          timestamp: new Date(),
+        } as any,
+      };
+    }
+  }
+}