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

package/dist/esm/types.d.ts

@@ -1,5 +1,4 @@
 import { FFetchOptions } from '@fetchkit/ffetch';
-import { z } from 'zod/v4';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 export type Auth = {
     username: string;
@@ -16,7 +15,9 @@ export interface ExecutableBuilder<T> {
     };
 }
 export interface ExecutionContext {
-    _makeRequest<T>(url: string, options?: RequestInit & FFetchOptions): Promise<T>;
+    _makeRequest<T>(url: string, options?: RequestInit & FFetchOptions): Promise<Result<T>>;
+    _setUseEntityIds?(useEntityIds: boolean): void;
+    _getUseEntityIds?(): boolean;
 }
 export type InferSchemaType<Schema extends Record<string, StandardSchemaV1>> = {
     [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output> ? Output : never;
@@ -42,7 +43,7 @@ export type ODataFieldResponse<T> = {
     "@context": string;
     value: T;
 };
-export type Result<T, E = Error> = {
+export type Result<T, E = import('./errors.js').FMODataErrorType> = {
     data: T;
     error: undefined;
 } | {
@@ -50,8 +51,22 @@ export type Result<T, E = Error> = {
     error: E;
 };
 export type MakeFieldsRequired<T, Keys extends keyof T> = Partial<T> & Required<Pick<T, Keys>>;
-export type InsertData<BT> = BT extends import('./client/base-table.js').BaseTable<infer Schema extends Record<string, z.ZodType>, any, infer InsertRequired extends readonly any[], any> ? [InsertRequired[number]] extends [keyof InferSchemaType<Schema>] ? InsertRequired extends readonly (keyof InferSchemaType<Schema>)[] ? MakeFieldsRequired<InferSchemaType<Schema>, InsertRequired[number]> : Partial<InferSchemaType<Schema>> : Partial<InferSchemaType<Schema>> : Partial<Record<string, any>>;
-export type UpdateData<BT> = BT extends import('./client/base-table.js').BaseTable<infer Schema extends Record<string, z.ZodType>, any, any, infer UpdateRequired extends readonly any[]> ? [UpdateRequired[number]] extends [keyof InferSchemaType<Schema>] ? UpdateRequired extends readonly (keyof InferSchemaType<Schema>)[] ? MakeFieldsRequired<InferSchemaType<Schema>, UpdateRequired[number]> : Partial<InferSchemaType<Schema>> : Partial<InferSchemaType<Schema>> : Partial<Record<string, any>>;
+export type AutoRequiredKeys<Schema extends Record<string, StandardSchemaV1>> = {
+    [K in keyof Schema]: Extract<StandardSchemaV1.InferOutput<Schema[K]>, null | undefined> extends never ? K : never;
+}[keyof Schema];
+export type ExcludedFields<IdField extends keyof any | undefined, ReadOnly extends readonly any[]> = IdField extends keyof any ? IdField | ReadOnly[number] : ReadOnly[number];
+type ComputeInsertData<Schema extends Record<string, StandardSchemaV1>, IdField extends keyof Schema | undefined, Required extends readonly any[], ReadOnly extends readonly any[]> = [Required[number]] extends [keyof InferSchemaType<Schema>] ? Required extends readonly (keyof InferSchemaType<Schema>)[] ? MakeFieldsRequired<Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>, Exclude<AutoRequiredKeys<Schema> | Required[number], ExcludedFields<IdField, ReadOnly>>> : MakeFieldsRequired<Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>, Exclude<AutoRequiredKeys<Schema>, ExcludedFields<IdField, ReadOnly>>> : MakeFieldsRequired<Omit<InferSchemaType<Schema>, ExcludedFields<IdField, ReadOnly>>, Exclude<AutoRequiredKeys<Schema>, ExcludedFields<IdField, ReadOnly>>>;
+export type InsertData<BT> = BT extends import('./client/base-table.js').BaseTable<any, any, any, any> ? BT extends {
+    schema: infer Schema;
+    idField?: infer IdField;
+    required?: infer Required;
+    readOnly?: infer ReadOnly;
+} ? Schema extends Record<string, StandardSchemaV1> ? IdField extends keyof Schema | undefined ? Required extends readonly any[] ? ReadOnly extends readonly any[] ? ComputeInsertData<Schema, Extract<IdField, keyof Schema | undefined>, Required, ReadOnly> : Partial<Record<string, any>> : Partial<Record<string, any>> : Partial<Record<string, any>> : Partial<Record<string, any>> : Partial<Record<string, any>> : Partial<Record<string, any>>;
+export type UpdateData<BT> = BT extends import('./client/base-table.js').BaseTable<any, any, any, any> ? BT extends {
+    schema: infer Schema;
+    idField?: infer IdField;
+    readOnly?: infer ReadOnly;
+} ? Schema extends Record<string, StandardSchemaV1> ? IdField extends keyof Schema | undefined ? ReadOnly extends readonly any[] ? Partial<Omit<InferSchemaType<Schema>, ExcludedFields<Extract<IdField, keyof Schema | undefined>, ReadOnly>>> : Partial<Record<string, any>> : Partial<Record<string, any>> : Partial<Record<string, any>> : Partial<Record<string, any>> : Partial<Record<string, any>>;
 export type ExecuteOptions = {
     includeODataAnnotations?: boolean;
     skipValidation?: boolean;
@@ -65,3 +80,4 @@ export type ExtractSchemaFromOccurrence<Occ> = Occ extends {
         schema: infer S;
     };
 } ? S extends Record<string, StandardSchemaV1> ? S : Record<string, StandardSchemaV1> : Record<string, StandardSchemaV1>;
+export {};

package/dist/esm/validation.d.ts

@@ -1,10 +1,13 @@
 import { ODataRecordMetadata } from './types.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { TableOccurrence } from './client/table-occurrence.js';
+import { ValidationError, ResponseStructureError, RecordCountMismatchError } from './errors.js';
 export type ExpandValidationConfig = {
     relation: string;
     targetSchema?: Record<string, StandardSchemaV1>;
     targetOccurrence?: TableOccurrence<any, any, any, any>;
+    targetBaseTable?: any;
+    occurrence?: TableOccurrence<any, any, any, any>;
     selectedFields?: string[];
     nestedExpands?: ExpandValidationConfig[];
 };
@@ -17,7 +20,7 @@ export declare function validateRecord<T extends Record<string, any>>(record: an
     data: T & ODataRecordMetadata;
 } | {
     valid: false;
-    error: Error;
+    error: ValidationError;
 }>;
 /**
  * Validates a list response against a schema.
@@ -27,7 +30,7 @@ export declare function validateListResponse<T extends Record<string, any>>(resp
     data: (T & ODataRecordMetadata)[];
 } | {
     valid: false;
-    error: Error;
+    error: ResponseStructureError | ValidationError;
 }>;
 /**
  * Validates a single record response against a schema.
@@ -37,5 +40,5 @@ export declare function validateSingleResponse<T extends Record<string, any>>(re
     data: (T & ODataRecordMetadata) | null;
 } | {
     valid: false;
-    error: Error;
+    error: RecordCountMismatchError | ValidationError;
 }>;

package/dist/esm/validation.js

@@ -1,3 +1,4 @@
+import { RecordCountMismatchError, ResponseStructureError, ValidationError } from "./errors.js";
 async function validateRecord(record, schema, selectedFields, expandConfigs) {
   var _a, _b;
   const { "@id": id, "@editLink": editLink, ...rest } = record;
@@ -19,17 +20,38 @@ async function validateRecord(record, schema, selectedFields, expandConfigs) {
       const fieldSchema = schema[fieldName];
       if (fieldSchema) {
         const input = rest[fieldName];
-        let result = fieldSchema["~standard"].validate(input);
-        if (result instanceof Promise) result = await result;
-        if (result.issues) {
+        try {
+          let result = fieldSchema["~standard"].validate(input);
+          if (result instanceof Promise) result = await result;
+          if (result.issues) {
+            return {
+              valid: false,
+              error: new ValidationError(
+                `Validation failed for field '${fieldName}'`,
+                result.issues,
+                {
+                  field: fieldName,
+                  value: input,
+                  cause: result.issues
+                }
+              )
+            };
+          }
+          validatedRecord2[fieldName] = result.value;
+        } catch (originalError) {
           return {
             valid: false,
-            error: new Error(
-              `Validation failed for field '${fieldName}': ${JSON.stringify(result.issues, null, 2)}`
+            error: new ValidationError(
+              `Validation failed for field '${fieldName}'`,
+              [],
+              {
+                field: fieldName,
+                value: input,
+                cause: originalError
+              }
             )
           };
         }
-        validatedRecord2[fieldName] = result.value;
       } else {
         validatedRecord2[fieldName] = rest[fieldName];
       }
@@ -48,8 +70,12 @@ async function validateRecord(record, schema, selectedFields, expandConfigs) {
               if (isRelatedToExpand) {
                 return {
                   valid: false,
-                  error: new Error(
-                    `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`
+                  error: new ValidationError(
+                    `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,
+                    [],
+                    {
+                      field: expandConfig.relation
+                    }
                   )
                 };
               }
@@ -69,8 +95,13 @@ async function validateRecord(record, schema, selectedFields, expandConfigs) {
               if (!itemValidation.valid) {
                 return {
                   valid: false,
-                  error: new Error(
-                    `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`
+                  error: new ValidationError(
+                    `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`,
+                    itemValidation.error.issues,
+                    {
+                      field: expandConfig.relation,
+                      cause: itemValidation.error.cause
+                    }
                   )
                 };
               }
@@ -87,8 +118,13 @@ async function validateRecord(record, schema, selectedFields, expandConfigs) {
             if (!itemValidation.valid) {
               return {
                 valid: false,
-                error: new Error(
-                  `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`
+                error: new ValidationError(
+                  `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,
+                  itemValidation.error.issues,
+                  {
+                    field: expandConfig.relation,
+                    cause: itemValidation.error.cause
+                  }
                 )
               };
             }
@@ -105,17 +141,38 @@ async function validateRecord(record, schema, selectedFields, expandConfigs) {
   const validatedRecord = { ...restWithoutSystemFields };
   for (const [fieldName, fieldSchema] of Object.entries(schema)) {
     const input = rest[fieldName];
-    let result = fieldSchema["~standard"].validate(input);
-    if (result instanceof Promise) result = await result;
-    if (result.issues) {
+    try {
+      let result = fieldSchema["~standard"].validate(input);
+      if (result instanceof Promise) result = await result;
+      if (result.issues) {
+        return {
+          valid: false,
+          error: new ValidationError(
+            `Validation failed for field '${fieldName}'`,
+            result.issues,
+            {
+              field: fieldName,
+              value: input,
+              cause: result.issues
+            }
+          )
+        };
+      }
+      validatedRecord[fieldName] = result.value;
+    } catch (originalError) {
       return {
         valid: false,
-        error: new Error(
-          `Validation failed for field '${fieldName}': ${JSON.stringify(result.issues, null, 2)}`
+        error: new ValidationError(
+          `Validation failed for field '${fieldName}'`,
+          [],
+          {
+            field: fieldName,
+            value: input,
+            cause: originalError
+          }
         )
       };
     }
-    validatedRecord[fieldName] = result.value;
   }
   if (expandConfigs && expandConfigs.length > 0) {
     for (const expandConfig of expandConfigs) {
@@ -131,8 +188,12 @@ async function validateRecord(record, schema, selectedFields, expandConfigs) {
             if (isRelatedToExpand) {
               return {
                 valid: false,
-                error: new Error(
-                  `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`
+                error: new ValidationError(
+                  `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,
+                  [],
+                  {
+                    field: expandConfig.relation
+                  }
                 )
               };
             }
@@ -152,8 +213,13 @@ async function validateRecord(record, schema, selectedFields, expandConfigs) {
             if (!itemValidation.valid) {
               return {
                 valid: false,
-                error: new Error(
-                  `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`
+                error: new ValidationError(
+                  `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`,
+                  itemValidation.error.issues,
+                  {
+                    field: expandConfig.relation,
+                    cause: itemValidation.error.cause
+                  }
                 )
               };
             }
@@ -170,8 +236,13 @@ async function validateRecord(record, schema, selectedFields, expandConfigs) {
           if (!itemValidation.valid) {
             return {
               valid: false,
-              error: new Error(
-                `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`
+              error: new ValidationError(
+                `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,
+                itemValidation.error.issues,
+                {
+                  field: expandConfig.relation,
+                  cause: itemValidation.error.cause
+                }
               )
             };
           }
@@ -189,15 +260,16 @@ async function validateListResponse(response, schema, selectedFields, expandConf
   if (!response || typeof response !== "object") {
     return {
       valid: false,
-      error: new Error("Invalid response: expected an object")
+      error: new ResponseStructureError("an object", response)
     };
   }
   const { "@context": context, value, ...rest } = response;
   if (!Array.isArray(value)) {
     return {
       valid: false,
-      error: new Error(
-        "Invalid response: expected 'value' property to be an array"
+      error: new ResponseStructureError(
+        "'value' property to be an array",
+        value
       )
     };
   }
@@ -213,9 +285,7 @@ async function validateListResponse(response, schema, selectedFields, expandConf
     if (!validation.valid) {
       return {
         valid: false,
-        error: new Error(
-          `Validation failed for record at index ${i}: ${validation.error.message}`
-        )
+        error: validation.error
       };
     }
     validatedRecords.push(validation.data);
@@ -230,8 +300,9 @@ async function validateSingleResponse(response, schema, selectedFields, expandCo
   if (response.value && Array.isArray(response.value) && response.value.length > 1) {
     return {
       valid: false,
-      error: new Error(
-        `Expected ${mode === "exact" ? "exactly one" : "at most one"} record, but received ${response.value.length}`
+      error: new RecordCountMismatchError(
+        mode === "exact" ? "one" : "at-most-one",
+        response.value.length
       )
     };
   }
@@ -239,7 +310,7 @@ async function validateSingleResponse(response, schema, selectedFields, expandCo
     if (mode === "exact") {
       return {
         valid: false,
-        error: new Error("Expected exactly one record, but received none")
+        error: new RecordCountMismatchError("one", 0)
       };
     }
     return {

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":";AAwBA,eAAsB,eACpB,QACA,QACA,gBACA,eAIA;;AAEA,QAAM,EAAE,OAAO,IAAI,aAAa,UAAU,GAAG,SAAS;AAGtD,QAAM,WAAgC;AAAA,IACpC,OAAO,MAAM;AAAA,IACb,aAAa,YAAY;AAAA,EAC3B;AAGA,MAAI,CAAC,QAAQ;AACJ,WAAA;AAAA,MACL,OAAO;AAAA,MACP,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS;AAAA,IAC/B;AAAA,EAAA;AAIF,QAAM,EAAE,OAAO,UAAU,GAAG,wBAA4B,IAAA;AAGpD,MAAA,kBAAkB,eAAe,SAAS,GAAG;AAC/C,UAAMA,mBAAuC,CAAC;AAE9C,eAAW,SAAS,gBAAgB;AAC5B,YAAA,YAAY,OAAO,KAAK;AACxB,YAAA,cAAc,OAAO,SAAS;AAEpC,UAAI,aAAa;AACT,cAAA,QAAQ,KAAK,SAAS;AACxB,YAAA;AACF,cAAI,SAAS,YAAY,WAAW,EAAE,SAAS,KAAK;AAChD,cAAA,kBAAkB,QAAS,UAAS,MAAM;AAG9C,cAAI,OAAO,QAAQ;AACV,mBAAA;AAAA,cACL,OAAO;AAAA,cACP,OAAO,IAAI;AAAA,gBACT,gCAAgC,SAAS;AAAA,gBACzC,OAAO;AAAA,gBACP;AAAA,kBACE,OAAO;AAAA,kBACP,OAAO;AAAA,kBACP,OAAO,OAAO;AAAA,gBAAA;AAAA,cAChB;AAAA,YAEJ;AAAA,UAAA;AAGFA,2BAAgB,SAAS,IAAI,OAAO;AAAA,iBAC7B,eAAe;AAEf,iBAAA;AAAA,YACL,OAAO;AAAA,YACP,OAAO,IAAI;AAAA,cACT,gCAAgC,SAAS;AAAA,cACzC,CAAC;AAAA,cACD;AAAA,gBACE,OAAO;AAAA,gBACP,OAAO;AAAA,gBACP,OAAO;AAAA,cAAA;AAAA,YACT;AAAA,UAEJ;AAAA,QAAA;AAAA,MACF,OACK;AAGLA,yBAAgB,SAAS,IAAI,KAAK,SAAS;AAAA,MAAA;AAAA,IAC7C;AAIE,QAAA,iBAAiB,cAAc,SAAS,GAAG;AAC7C,iBAAW,gBAAgB,eAAe;AAClC,cAAA,cAAc,KAAK,aAAa,QAAQ;AAG9C,YAAI,gBAAgB,QAAW;AAEzB,cAAA,MAAM,QAAQ,KAAK,KAAK,KAAK,KAAK,MAAM,SAAS,GAAG;AAEtD,kBAAM,eAAc,UAAK,MAAM,CAAC,MAAZ,mBAAe;AACnC,gBAAI,2CAAa,SAAS;AACxB,oBAAM,eAAe,YAAY;AAIjC,oBAAM,oBACJ,aACG,YAAY,EACZ,SAAS,aAAa,SAAS,YAAA,CAAa,KAC9C,aAAa,kBACZ,aAAa,eAAe;AAAA,gBAAK,CAAC,UAChC,aAAa,cAAc,SAAS,MAAM,YAAa,CAAA;AAAA,cACzD;AAEJ,kBAAI,mBAAmB;AACd,uBAAA;AAAA,kBACL,OAAO;AAAA,kBACP,OAAO,IAAI;AAAA,oBACT,4CAA4C,aAAa,QAAQ,MAAM,YAAY;AAAA,oBACnF,CAAC;AAAA,oBACD;AAAA,sBACE,OAAO,aAAa;AAAA,oBAAA;AAAA,kBACtB;AAAA,gBAEJ;AAAA,cAAA;AAAA,YACF;AAAA,UACF;AAAA,QACF,OAIK;AAED,cAAA,MAAM,QAAQ,WAAW,GAAG;AAE9B,kBAAM,yBAAgC,CAAC;AACvC,qBAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AACrC,oBAAA,OAAO,YAAY,CAAC;AAC1B,oBAAM,iBAAiB,MAAM;AAAA,gBAC3B;AAAA,gBACA,aAAa;AAAA,gBACb,aAAa;AAAA,gBACb,aAAa;AAAA,cACf;AACI,kBAAA,CAAC,eAAe,OAAO;AAClB,uBAAA;AAAA,kBACL,OAAO;AAAA,kBACP,OAAO,IAAI;AAAA,oBACT,4CAA4C,aAAa,QAAQ,cAAc,CAAC,KAAK,eAAe,MAAM,OAAO;AAAA,oBACjH,eAAe,MAAM;AAAA,oBACrB;AAAA,sBACE,OAAO,aAAa;AAAA,sBACpB,OAAO,eAAe,MAAM;AAAA,oBAAA;AAAA,kBAC9B;AAAA,gBAEJ;AAAA,cAAA;AAEqB,qCAAA,KAAK,eAAe,IAAI;AAAA,YAAA;AAEjDA,6BAAgB,aAAa,QAAQ,IAAI;AAAA,UAAA,OACpC;AAEL,kBAAM,iBAAiB,MAAM;AAAA,cAC3B;AAAA,cACA,aAAa;AAAA,cACb,aAAa;AAAA,cACb,aAAa;AAAA,YACf;AACI,gBAAA,CAAC,eAAe,OAAO;AAClB,qBAAA;AAAA,gBACL,OAAO;AAAA,gBACP,OAAO,IAAI;AAAA,kBACT,4CAA4C,aAAa,QAAQ,MAAM,eAAe,MAAM,OAAO;AAAA,kBACnG,eAAe,MAAM;AAAA,kBACrB;AAAA,oBACE,OAAO,aAAa;AAAA,oBACpB,OAAO,eAAe,MAAM;AAAA,kBAAA;AAAA,gBAC9B;AAAA,cAEJ;AAAA,YAAA;AAEFA,6BAAgB,aAAa,QAAQ,IAAI,eAAe;AAAA,UAAA;AAAA,QAC1D;AAAA,MACF;AAAA,IACF;AAIK,WAAA;AAAA,MACL,OAAO;AAAA,MACP,MAAM,EAAE,GAAGA,kBAAiB,GAAG,SAAS;AAAA,IAC1C;AAAA,EAAA;AAII,QAAA,kBAAuC,EAAE,GAAG,wBAAwB;AAE1E,aAAW,CAAC,WAAW,WAAW,KAAK,OAAO,QAAQ,MAAM,GAAG;AACvD,UAAA,QAAQ,KAAK,SAAS;AACxB,QAAA;AACF,UAAI,SAAS,YAAY,WAAW,EAAE,SAAS,KAAK;AAChD,UAAA,kBAAkB,QAAS,UAAS,MAAM;AAG9C,UAAI,OAAO,QAAQ;AACV,eAAA;AAAA,UACL,OAAO;AAAA,UACP,OAAO,IAAI;AAAA,YACT,gCAAgC,SAAS;AAAA,YACzC,OAAO;AAAA,YACP;AAAA,cACE,OAAO;AAAA,cACP,OAAO;AAAA,cACP,OAAO,OAAO;AAAA,YAAA;AAAA,UAChB;AAAA,QAEJ;AAAA,MAAA;AAGc,sBAAA,SAAS,IAAI,OAAO;AAAA,aAC7B,eAAe;AAGf,aAAA;AAAA,QACL,OAAO;AAAA,QACP,OAAO,IAAI;AAAA,UACT,gCAAgC,SAAS;AAAA,UACzC,CAAC;AAAA,UACD;AAAA,YACE,OAAO;AAAA,YACP,OAAO;AAAA,YACP,OAAO;AAAA,UAAA;AAAA,QACT;AAAA,MAEJ;AAAA,IAAA;AAAA,EACF;AAIE,MAAA,iBAAiB,cAAc,SAAS,GAAG;AAC7C,eAAW,gBAAgB,eAAe;AAClC,YAAA,cAAc,KAAK,aAAa,QAAQ;AAG9C,UAAI,gBAAgB,QAAW;AAEzB,YAAA,MAAM,QAAQ,KAAK,KAAK,KAAK,KAAK,MAAM,SAAS,GAAG;AAEtD,gBAAM,eAAc,UAAK,MAAM,CAAC,MAAZ,mBAAe;AACnC,cAAI,2CAAa,SAAS;AACxB,kBAAM,eAAe,YAAY;AAIjC,kBAAM,oBACJ,aACG,YAAY,EACZ,SAAS,aAAa,SAAS,YAAA,CAAa,KAC9C,aAAa,kBACZ,aAAa,eAAe;AAAA,cAAK,CAAC,UAChC,aAAa,cAAc,SAAS,MAAM,YAAa,CAAA;AAAA,YACzD;AAEJ,gBAAI,mBAAmB;AACd,qBAAA;AAAA,gBACL,OAAO;AAAA,gBACP,OAAO,IAAI;AAAA,kBACT,4CAA4C,aAAa,QAAQ,MAAM,YAAY;AAAA,kBACnF,CAAC;AAAA,kBACD;AAAA,oBACE,OAAO,aAAa;AAAA,kBAAA;AAAA,gBACtB;AAAA,cAEJ;AAAA,YAAA;AAAA,UACF;AAAA,QACF;AAAA,MACF,OAIK;AAED,YAAA,MAAM,QAAQ,WAAW,GAAG;AAE9B,gBAAM,yBAAgC,CAAC;AACvC,mBAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AACrC,kBAAA,OAAO,YAAY,CAAC;AAC1B,kBAAM,iBAAiB,MAAM;AAAA,cAC3B;AAAA,cACA,aAAa;AAAA,cACb,aAAa;AAAA,cACb,aAAa;AAAA,YACf;AACI,gBAAA,CAAC,eAAe,OAAO;AAClB,qBAAA;AAAA,gBACL,OAAO;AAAA,gBACP,OAAO,IAAI;AAAA,kBACT,4CAA4C,aAAa,QAAQ,cAAc,CAAC,KAAK,eAAe,MAAM,OAAO;AAAA,kBACjH,eAAe,MAAM;AAAA,kBACrB;AAAA,oBACE,OAAO,aAAa;AAAA,oBACpB,OAAO,eAAe,MAAM;AAAA,kBAAA;AAAA,gBAC9B;AAAA,cAEJ;AAAA,YAAA;AAEqB,mCAAA,KAAK,eAAe,IAAI;AAAA,UAAA;AAEjC,0BAAA,aAAa,QAAQ,IAAI;AAAA,QAAA,OACpC;AAEL,gBAAM,iBAAiB,MAAM;AAAA,YAC3B;AAAA,YACA,aAAa;AAAA,YACb,aAAa;AAAA,YACb,aAAa;AAAA,UACf;AACI,cAAA,CAAC,eAAe,OAAO;AAClB,mBAAA;AAAA,cACL,OAAO;AAAA,cACP,OAAO,IAAI;AAAA,gBACT,4CAA4C,aAAa,QAAQ,MAAM,eAAe,MAAM,OAAO;AAAA,gBACnG,eAAe,MAAM;AAAA,gBACrB;AAAA,kBACE,OAAO,aAAa;AAAA,kBACpB,OAAO,eAAe,MAAM;AAAA,gBAAA;AAAA,cAC9B;AAAA,YAEJ;AAAA,UAAA;AAEc,0BAAA,aAAa,QAAQ,IAAI,eAAe;AAAA,QAAA;AAAA,MAC1D;AAAA,IACF;AAAA,EACF;AAGK,SAAA;AAAA,IACL,OAAO;AAAA,IACP,MAAM,EAAE,GAAG,iBAAiB,GAAG,SAAS;AAAA,EAC1C;AACF;AAKA,eAAsB,qBACpB,UACA,QACA,gBACA,eAIA;AAEA,MAAI,CAAC,YAAY,OAAO,aAAa,UAAU;AACtC,WAAA;AAAA,MACL,OAAO;AAAA,MACP,OAAO,IAAI,uBAAuB,aAAa,QAAQ;AAAA,IACzD;AAAA,EAAA;AAIF,QAAM,EAAE,YAAY,SAAS,OAAO,GAAG,KAAS,IAAA;AAEhD,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AAClB,WAAA;AAAA,MACL,OAAO;AAAA,MACP,OAAO,IAAI;AAAA,QACT;AAAA,QACA;AAAA,MAAA;AAAA,IAEJ;AAAA,EAAA;AAIF,QAAM,mBAAgD,CAAC;AAEvD,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AAC/B,UAAA,SAAS,MAAM,CAAC;AACtB,UAAM,aAAa,MAAM;AAAA,MACvB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAEI,QAAA,CAAC,WAAW,OAAO;AACd,aAAA;AAAA,QACL,OAAO;AAAA,QACP,OAAO,WAAW;AAAA,MACpB;AAAA,IAAA;AAGe,qBAAA,KAAK,WAAW,IAAI;AAAA,EAAA;AAGhC,SAAA;AAAA,IACL,OAAO;AAAA,IACP,MAAM;AAAA,EACR;AACF;AAKA,eAAsB,uBACpB,UACA,QACA,gBACA,eACA,OAA0B,SAI1B;;AAGE,MAAA,SAAS,SACT,MAAM,QAAQ,SAAS,KAAK,KAC5B,SAAS,MAAM,SAAS,GACxB;AACO,WAAA;AAAA,MACL,OAAO;AAAA,MACP,OAAO,IAAI;AAAA,QACT,SAAS,UAAU,QAAQ;AAAA,QAC3B,SAAS,MAAM;AAAA,MAAA;AAAA,IAEnB;AAAA,EAAA;AAIF,MAAI,CAAC,YAAa,SAAS,SAAS,SAAS,MAAM,WAAW,GAAI;AAChE,QAAI,SAAS,SAAS;AACb,aAAA;AAAA,QACL,OAAO;AAAA,QACP,OAAO,IAAI,yBAAyB,OAAO,CAAC;AAAA,MAC9C;AAAA,IAAA;AAGK,WAAA;AAAA,MACL,OAAO;AAAA,MACP,MAAM;AAAA,IACR;AAAA,EAAA;AAIF,QAAM,WAAS,cAAS,UAAT,mBAAiB,OAAM;AACtC,QAAM,aAAa,MAAM;AAAA,IACvB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEI,MAAA,CAAC,WAAW,OAAO;AACd,WAAA;AAAA,EAAA;AAGF,SAAA;AAAA,IACL,OAAO;AAAA,IACP,MAAM,WAAW;AAAA,EACnB;AACF;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proofkit/fmodata",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.6",
   "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,172 @@
 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)[] = readonly [],
+  ReadOnly extends readonly (keyof Schema)[] = 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, `FMFID:${string}`>;
 
   constructor(config: {
     schema: Schema;
     idField?: IdField;
-    insertRequired?: InsertRequired;
-    updateRequired?: UpdateRequired;
+    required?: Required;
+    readOnly?: ReadOnly;
   }) {
     this.schema = config.schema;
     this.idField = config.idField;
-    this.insertRequired = config.insertRequired;
-    this.updateRequired = config.updateRequired;
+    this.required = config.required;
+    this.readOnly = config.readOnly;
+  }
+
+  /**
+   * 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;
+  }
+}
+
+/**
+ * BaseTableWithIds extends BaseTable to require FileMaker field IDs (fmfIds).
+ * Use this class when you need to work with FileMaker's internal field identifiers.
+ *
+ * @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
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const usersTableWithIds = new BaseTableWithIds({
+ *   schema: {
+ *     id: z.string(),
+ *     name: z.string(),
+ *     email: z.string().nullable(),
+ *   },
+ *   idField: "id",
+ *   fmfIds: {
+ *     id: "FMFID:1",
+ *     name: "FMFID:2",
+ *     email: "FMFID:3",
+ *   },
+ * });
+ * ```
+ */
+export class BaseTableWithIds<
+  Schema extends Record<string, StandardSchemaV1> = any,
+  IdField extends keyof Schema | undefined = undefined,
+  Required extends readonly (keyof Schema)[] = readonly [],
+  ReadOnly extends readonly (keyof Schema)[] = readonly [],
+> extends BaseTable<Schema, IdField, Required, ReadOnly> {
+  public override readonly fmfIds: Record<keyof Schema, `FMFID:${string}`>;
+
+  constructor(config: {
+    schema: Schema;
+    fmfIds: Record<keyof Schema, `FMFID:${string}`>;
+    idField?: IdField;
+    required?: Required;
+    readOnly?: ReadOnly;
+  }) {
+    super(config);
+    this.fmfIds = config.fmfIds;
   }
 }