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

package/src/validation.ts

@@ -1,58 +1,158 @@
+/** biome-ignore-all lint/style/useCollapsedElseIf: easier to read */
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { RecordCountMismatchError, ResponseStructureError, ValidationError } from "./errors";
+import type { FMTable } from "./orm/table";
 import type { ODataRecordMetadata } from "./types";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-import type { TableOccurrence } from "./client/table-occurrence";
-import {
-  ValidationError,
-  ResponseStructureError,
-  RecordCountMismatchError,
-} from "./errors";
+
+/**
+ * Validates and transforms input data for insert/update operations.
+ * Applies input validators (writeValidators) to transform user input to database format.
+ * Fields without input validators are passed through unchanged.
+ *
+ * @param data - The input data to validate and transform
+ * @param inputSchema - Optional schema containing input validators for each field
+ * @returns Transformed data ready to send to the server
+ * @throws ValidationError if any field fails validation
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
+export async function validateAndTransformInput<T extends Record<string, any>>(
+  data: Partial<T>,
+  inputSchema?: Partial<Record<string, StandardSchemaV1>>,
+): Promise<Partial<T>> {
+  // If no input schema, return data as-is
+  if (!inputSchema) {
+    return data;
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic field transformation
+  const transformedData: Record<string, any> = { ...data };
+
+  // Process each field that has an input validator
+  for (const [fieldName, fieldSchema] of Object.entries(inputSchema)) {
+    // Skip if no schema for this field
+    if (!fieldSchema) {
+      continue;
+    }
+
+    // Only process fields that are present in the input data
+    if (fieldName in data) {
+      const inputValue = data[fieldName];
+
+      try {
+        // Run the input validator to transform the value
+        let result = fieldSchema["~standard"].validate(inputValue);
+        if (result instanceof Promise) {
+          result = await result;
+        }
+
+        // Check for validation errors
+        if (result.issues) {
+          throw new ValidationError(`Input validation failed for field '${fieldName}'`, result.issues, {
+            field: fieldName,
+            value: inputValue,
+            cause: result.issues,
+          });
+        }
+
+        // Store the transformed value
+        transformedData[fieldName] = result.value;
+      } catch (error) {
+        // If it's already a ValidationError, re-throw it
+        if (error instanceof ValidationError) {
+          throw error;
+        }
+
+        // Otherwise, wrap the error
+        throw new ValidationError(`Input validation failed for field '${fieldName}'`, [], {
+          field: fieldName,
+          value: inputValue,
+          cause: error,
+        });
+      }
+    }
+  }
+
+  // Fields without input validators are already in transformedData (passed through)
+  return transformedData as Partial<T>;
+}
 
 // Type for expand validation configuration
-export type ExpandValidationConfig = {
+export interface ExpandValidationConfig {
   relation: string;
-  targetSchema?: Record<string, StandardSchemaV1>;
-  targetOccurrence?: TableOccurrence<any, any, any, any>;
-  targetBaseTable?: any; // BaseTable instance for transformation
-  occurrence?: TableOccurrence<any, any, any, any>; // For transformation
+  targetSchema?: Partial<Record<string, StandardSchemaV1>>;
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  targetTable?: FMTable<any, any>;
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  table?: FMTable<any, any>; // For transformation
   selectedFields?: string[];
   nestedExpands?: ExpandValidationConfig[];
-};
+}
 
 /**
  * Validates a single record against a schema, only validating selected fields.
  * Also validates expanded relations if expandConfigs are provided.
  */
+// biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
 export async function validateRecord<T extends Record<string, any>>(
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic record validation
   record: any,
-  schema: Record<string, StandardSchemaV1> | undefined,
+  schema: Partial<Record<string, StandardSchemaV1>> | undefined,
   selectedFields?: (keyof T)[],
   expandConfigs?: ExpandValidationConfig[],
-): Promise<
-  | { valid: true; data: T & ODataRecordMetadata }
-  | { valid: false; error: ValidationError }
-> {
+  includeSpecialColumns?: boolean,
+): Promise<{ valid: true; data: T & ODataRecordMetadata } | { valid: false; error: ValidationError }> {
   // Extract OData metadata fields (don't validate them - include if present)
   const { "@id": id, "@editLink": editLink, ...rest } = record;
 
-  // Include metadata fields if present (don't validate they exist)
-  const metadata: ODataRecordMetadata = {
-    "@id": id || "",
-    "@editLink": editLink || "",
-  };
+  // Only include metadata fields if they actually exist and have values
+  const metadata: Partial<ODataRecordMetadata> = {};
+  if (id) {
+    metadata["@id"] = id;
+  }
+  if (editLink) {
+    metadata["@editLink"] = editLink;
+  }
 
   // If no schema, just return the data with metadata
+  // Exclude special columns if includeSpecialColumns is false
   if (!schema) {
+    const { ROWID, ROWMODID, ...restWithoutSystemFields } = rest;
+    const specialColumns: { ROWID?: number; ROWMODID?: number } = {};
+    if (includeSpecialColumns) {
+      if (ROWID !== undefined) {
+        specialColumns.ROWID = ROWID;
+      }
+      if (ROWMODID !== undefined) {
+        specialColumns.ROWMODID = ROWMODID;
+      }
+    }
     return {
       valid: true,
-      data: { ...rest, ...metadata } as T & ODataRecordMetadata,
+      data: {
+        ...restWithoutSystemFields,
+        ...specialColumns,
+        ...metadata,
+      } as T & ODataRecordMetadata,
     };
   }
 
-  // Filter out FileMaker system fields that shouldn't be in responses by default
+  // Extract FileMaker special columns - preserve them if includeSpecialColumns is enabled
+  // Note: Special columns are excluded when using single() method (per OData spec behavior)
   const { ROWID, ROWMODID, ...restWithoutSystemFields } = rest;
+  const specialColumns: { ROWID?: number; ROWMODID?: number } = {};
+  // Only include special columns if explicitly enabled (they're excluded for single() by design)
+  if (includeSpecialColumns) {
+    if (ROWID !== undefined) {
+      specialColumns.ROWID = ROWID;
+    }
+    if (ROWMODID !== undefined) {
+      specialColumns.ROWMODID = ROWMODID;
+    }
+  }
 
   // If selected fields are specified, validate only those fields
   if (selectedFields && selectedFields.length > 0) {
+    // biome-ignore lint/suspicious/noExplicitAny: Dynamic field validation
     const validatedRecord: Record<string, any> = {};
 
     for (const field of selectedFields) {
@@ -63,21 +163,19 @@ export async function validateRecord<T extends Record<string, any>>(
         const input = rest[fieldName];
         try {
           let result = fieldSchema["~standard"].validate(input);
-          if (result instanceof Promise) result = await result;
+          if (result instanceof Promise) {
+            result = await result;
+          }
 
           // if the `issues` field exists, the validation failed
           if (result.issues) {
             return {
               valid: false,
-              error: new ValidationError(
-                `Validation failed for field '${fieldName}'`,
-                result.issues,
-                {
-                  field: fieldName,
-                  value: input,
-                  cause: result.issues,
-                },
-              ),
+              error: new ValidationError(`Validation failed for field '${fieldName}'`, result.issues, {
+                field: fieldName,
+                value: input,
+                cause: result.issues,
+              }),
             };
           }
 
@@ -86,21 +184,27 @@ export async function validateRecord<T extends Record<string, any>>(
           // If the validator throws directly, wrap it
           return {
             valid: false,
-            error: new ValidationError(
-              `Validation failed for field '${fieldName}'`,
-              [],
-              {
-                field: fieldName,
-                value: input,
-                cause: originalError,
-              },
-            ),
+            error: new ValidationError(`Validation failed for field '${fieldName}'`, [], {
+              field: fieldName,
+              value: input,
+              cause: originalError,
+            }),
           };
         }
       } else {
         // For fields not in schema (like when explicitly selecting ROWID/ROWMODID)
-        // include them from the original response
-        validatedRecord[fieldName] = rest[fieldName];
+        // Check if it's a special column that was destructured earlier
+        if (fieldName === "ROWID" || fieldName === "ROWMODID") {
+          // Use the destructured value since it was removed from rest
+          if (fieldName === "ROWID" && ROWID !== undefined) {
+            validatedRecord[fieldName] = ROWID;
+          } else if (fieldName === "ROWMODID" && ROWMODID !== undefined) {
+            validatedRecord[fieldName] = ROWMODID;
+          }
+        } else {
+          // For other fields not in schema, include them from the original response
+          validatedRecord[fieldName] = rest[fieldName];
+        }
       }
     }
 
@@ -121,13 +225,8 @@ export async function validateRecord<T extends Record<string, any>>(
               // 1. The error mentions the relation name, OR
               // 2. The error mentions any of the selected fields
               const isRelatedToExpand =
-                errorMessage
-                  .toLowerCase()
-                  .includes(expandConfig.relation.toLowerCase()) ||
-                (expandConfig.selectedFields &&
-                  expandConfig.selectedFields.some((field) =>
-                    errorMessage.toLowerCase().includes(field.toLowerCase()),
-                  ));
+                errorMessage.toLowerCase().includes(expandConfig.relation.toLowerCase()) ||
+                expandConfig.selectedFields?.some((field) => errorMessage.toLowerCase().includes(field.toLowerCase()));
 
               if (isRelatedToExpand) {
                 return {
@@ -150,6 +249,7 @@ export async function validateRecord<T extends Record<string, any>>(
           // Original validation logic for when expand exists
           if (Array.isArray(expandValue)) {
             // Validate each item in the expanded array
+            // biome-ignore lint/suspicious/noExplicitAny: Dynamic expanded items validation
             const validatedExpandedItems: any[] = [];
             for (let i = 0; i < expandValue.length; i++) {
               const item = expandValue[i];
@@ -158,6 +258,7 @@ export async function validateRecord<T extends Record<string, any>>(
                 expandConfig.targetSchema,
                 expandConfig.selectedFields as string[] | undefined,
                 expandConfig.nestedExpands,
+                includeSpecialColumns,
               );
               if (!itemValidation.valid) {
                 return {
@@ -182,6 +283,7 @@ export async function validateRecord<T extends Record<string, any>>(
               expandConfig.targetSchema,
               expandConfig.selectedFields as string[] | undefined,
               expandConfig.nestedExpands,
+              includeSpecialColumns,
             );
             if (!itemValidation.valid) {
               return {
@@ -202,35 +304,40 @@ export async function validateRecord<T extends Record<string, any>>(
       }
     }
 
-    // Merge validated data with metadata
+    // Return only the validated fields plus metadata and special columns
+    // Do NOT merge restWithoutSystemFields as that would overwrite validated values
     return {
       valid: true,
-      data: { ...validatedRecord, ...metadata } as T & ODataRecordMetadata,
+      data: { ...validatedRecord, ...specialColumns, ...metadata } as T & ODataRecordMetadata,
     };
   }
 
-  // Validate all fields in schema, but exclude ROWID/ROWMODID by default
+  // Validate all fields in schema, but exclude ROWID/ROWMODID by default (unless includeSpecialColumns is enabled)
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic field validation
   const validatedRecord: Record<string, any> = { ...restWithoutSystemFields };
 
   for (const [fieldName, fieldSchema] of Object.entries(schema)) {
+    // Skip if no schema for this field
+    if (!fieldSchema) {
+      continue;
+    }
+
     const input = rest[fieldName];
     try {
       let result = fieldSchema["~standard"].validate(input);
-      if (result instanceof Promise) result = await result;
+      if (result instanceof Promise) {
+        result = await result;
+      }
 
       // if the `issues` field exists, the validation failed
       if (result.issues) {
         return {
           valid: false,
-          error: new ValidationError(
-            `Validation failed for field '${fieldName}'`,
-            result.issues,
-            {
-              field: fieldName,
-              value: input,
-              cause: result.issues,
-            },
-          ),
+          error: new ValidationError(`Validation failed for field '${fieldName}'`, result.issues, {
+            field: fieldName,
+            value: input,
+            cause: result.issues,
+          }),
         };
       }
 
@@ -240,15 +347,11 @@ export async function validateRecord<T extends Record<string, any>>(
       // This preserves the original error instance for instanceof checks
       return {
         valid: false,
-        error: new ValidationError(
-          `Validation failed for field '${fieldName}'`,
-          [],
-          {
-            field: fieldName,
-            value: input,
-            cause: originalError,
-          },
-        ),
+        error: new ValidationError(`Validation failed for field '${fieldName}'`, [], {
+          field: fieldName,
+          value: input,
+          cause: originalError,
+        }),
       };
     }
   }
@@ -270,13 +373,8 @@ export async function validateRecord<T extends Record<string, any>>(
             // 1. The error mentions the relation name, OR
             // 2. The error mentions any of the selected fields
             const isRelatedToExpand =
-              errorMessage
-                .toLowerCase()
-                .includes(expandConfig.relation.toLowerCase()) ||
-              (expandConfig.selectedFields &&
-                expandConfig.selectedFields.some((field) =>
-                  errorMessage.toLowerCase().includes(field.toLowerCase()),
-                ));
+              errorMessage.toLowerCase().includes(expandConfig.relation.toLowerCase()) ||
+              expandConfig.selectedFields?.some((field) => errorMessage.toLowerCase().includes(field.toLowerCase()));
 
             if (isRelatedToExpand) {
               return {
@@ -299,6 +397,7 @@ export async function validateRecord<T extends Record<string, any>>(
         // Original validation logic for when expand exists
         if (Array.isArray(expandValue)) {
           // Validate each item in the expanded array
+          // biome-ignore lint/suspicious/noExplicitAny: Dynamic expanded items validation
           const validatedExpandedItems: any[] = [];
           for (let i = 0; i < expandValue.length; i++) {
             const item = expandValue[i];
@@ -307,6 +406,7 @@ export async function validateRecord<T extends Record<string, any>>(
               expandConfig.targetSchema,
               expandConfig.selectedFields as string[] | undefined,
               expandConfig.nestedExpands,
+              includeSpecialColumns,
             );
             if (!itemValidation.valid) {
               return {
@@ -331,6 +431,7 @@ export async function validateRecord<T extends Record<string, any>>(
             expandConfig.targetSchema,
             expandConfig.selectedFields as string[] | undefined,
             expandConfig.nestedExpands,
+            includeSpecialColumns,
           );
           if (!itemValidation.valid) {
             return {
@@ -353,21 +454,23 @@ export async function validateRecord<T extends Record<string, any>>(
 
   return {
     valid: true,
-    data: { ...validatedRecord, ...metadata } as T & ODataRecordMetadata,
+    data: { ...validatedRecord, ...specialColumns, ...metadata } as T & ODataRecordMetadata,
   };
 }
 
 /**
  * Validates a list response against a schema.
  */
+// biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
 export async function validateListResponse<T extends Record<string, any>>(
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic response validation
   response: any,
-  schema: Record<string, StandardSchemaV1> | undefined,
+  schema: Partial<Record<string, StandardSchemaV1>> | undefined,
   selectedFields?: (keyof T)[],
   expandConfigs?: ExpandValidationConfig[],
+  includeSpecialColumns?: boolean,
 ): Promise<
-  | { valid: true; data: (T & ODataRecordMetadata)[] }
-  | { valid: false; error: ResponseStructureError | ValidationError }
+  { valid: true; data: (T & ODataRecordMetadata)[] } | { valid: false; error: ResponseStructureError | ValidationError }
 > {
   // Check if response has the expected structure
   if (!response || typeof response !== "object") {
@@ -378,29 +481,20 @@ export async function validateListResponse<T extends Record<string, any>>(
   }
 
   // Extract @context (for internal validation, but we won't return it)
-  const { "@context": context, value, ...rest } = response;
+  const { "@context": context, value, ..._rest } = response;
 
   if (!Array.isArray(value)) {
     return {
       valid: false,
-      error: new ResponseStructureError(
-        "'value' property to be an array",
-        value,
-      ),
+      error: new ResponseStructureError("'value' property to be an array", value),
     };
   }
 
   // Validate each record in the array
   const validatedRecords: (T & ODataRecordMetadata)[] = [];
 
-  for (let i = 0; i < value.length; i++) {
-    const record = value[i];
-    const validation = await validateRecord<T>(
-      record,
-      schema,
-      selectedFields,
-      expandConfigs,
-    );
+  for (const record of value) {
+    const validation = await validateRecord<T>(record, schema, selectedFields, expandConfigs, includeSpecialColumns);
 
     if (!validation.valid) {
       return {
@@ -421,28 +515,24 @@ export async function validateListResponse<T extends Record<string, any>>(
 /**
  * Validates a single record response against a schema.
  */
+// biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
 export async function validateSingleResponse<T extends Record<string, any>>(
+  // biome-ignore lint/suspicious/noExplicitAny: Dynamic response validation
   response: any,
-  schema: Record<string, StandardSchemaV1> | undefined,
+  schema: Partial<Record<string, StandardSchemaV1>> | undefined,
   selectedFields?: (keyof T)[],
   expandConfigs?: ExpandValidationConfig[],
   mode: "exact" | "maybe" = "maybe",
+  includeSpecialColumns?: boolean,
 ): Promise<
   | { valid: true; data: (T & ODataRecordMetadata) | null }
   | { valid: false; error: RecordCountMismatchError | ValidationError }
 > {
   // Check for multiple records (error in both modes)
-  if (
-    response.value &&
-    Array.isArray(response.value) &&
-    response.value.length > 1
-  ) {
+  if (response.value && Array.isArray(response.value) && response.value.length > 1) {
     return {
       valid: false,
-      error: new RecordCountMismatchError(
-        mode === "exact" ? "one" : "at-most-one",
-        response.value.length,
-      ),
+      error: new RecordCountMismatchError(mode === "exact" ? "one" : "at-most-one", response.value.length),
     };
   }
 
@@ -463,12 +553,7 @@ export async function validateSingleResponse<T extends Record<string, any>>(
 
   // Single record validation
   const record = response.value?.[0] ?? response;
-  const validation = await validateRecord<T>(
-    record,
-    schema,
-    selectedFields,
-    expandConfigs,
-  );
+  const validation = await validateRecord<T>(record, schema, selectedFields, expandConfigs, includeSpecialColumns);
 
   if (!validation.valid) {
     return validation as { valid: false; error: ValidationError };

package/dist/esm/client/base-table.d.ts

@@ -1,125 +0,0 @@
-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 declare class BaseTable<Schema extends Record<string, StandardSchemaV1> = any, IdField extends keyof Schema | undefined = undefined, Required extends readonly (keyof Schema | (string & {}))[] = readonly [], ReadOnly extends readonly (keyof Schema | (string & {}))[] = readonly []> {
-    readonly schema: Schema;
-    readonly idField?: IdField;
-    readonly required?: Required;
-    readonly readOnly?: ReadOnly;
-    readonly fmfIds?: Record<keyof Schema | (string & {}), `FMFID:${string}`>;
-    constructor(config: {
-        schema: Schema;
-        idField?: IdField;
-        required?: Required;
-        readOnly?: ReadOnly;
-        fmfIds?: Record<string, `FMFID:${string}`>;
-    });
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * Returns true if this BaseTable is using FileMaker field IDs.
-     */
-    isUsingFieldIds(): boolean;
-}
-/**
- * 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 declare 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>;