@proofkit/fmodata 0.1.0-alpha.4 → 0.1.0-alpha.7

package/src/types.ts

@@ -1,5 +1,4 @@
 import { type FFetchOptions } from "@fetchkit/ffetch";
-import { z } from "zod/v4";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 
 export type Auth = { username: string; password: string } | { apiKey: string };
@@ -7,18 +6,40 @@ export type Auth = { username: string; password: string } | { apiKey: string };
 export interface ExecutableBuilder<T> {
   execute(): Promise<Result<T>>;
   getRequestConfig(): { method: string; url: string; body?: any };
+
+  /**
+   * Convert this builder to a native Request object for batch processing.
+   * @param baseUrl - The base URL for the OData service
+   * @returns A native Request object
+   */
+  toRequest(baseUrl: string): Request;
+
+  /**
+   * Process a raw Response object into a typed Result.
+   * This allows builders to apply their own validation and transformation logic.
+   * @param response - The native Response object from the batch operation
+   * @param options - Optional execution options (e.g., skipValidation, includeODataAnnotations)
+   * @returns A typed Result with the builder's expected return type
+   */
+  processResponse(
+    response: Response,
+    options?: ExecuteOptions,
+  ): Promise<Result<T>>;
 }
 
 export interface ExecutionContext {
   _makeRequest<T>(
     url: string,
-    options?: RequestInit & FFetchOptions,
-  ): Promise<T>;
+    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },
+  ): Promise<Result<T>>;
+  _setUseEntityIds?(useEntityIds: boolean): void;
+  _getUseEntityIds?(): boolean;
+  _getBaseUrl?(): string;
 }
 
 export type InferSchemaType<Schema extends Record<string, StandardSchemaV1>> = {
-  [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output> 
-    ? Output 
+  [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output>
+    ? Output
     : never;
 };
 
@@ -63,7 +84,7 @@ export type ODataFieldResponse<T> = {
 };
 
 // Result pattern for execute responses
-export type Result<T, E = Error> =
+export type Result<T, E = import("./errors").FMODataErrorType> =
   | { data: T; error: undefined }
   | { data: undefined; error: E };
 
@@ -71,53 +92,198 @@ export type Result<T, E = Error> =
 export type MakeFieldsRequired<T, Keys extends keyof T> = Partial<T> &
   Required<Pick<T, Keys>>;
 
+// Extract keys from schema where validator doesn't allow null/undefined (auto-required fields)
+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];
+
+// Helper type to compute excluded fields (readOnly fields + idField)
+export type ExcludedFields<
+  IdField extends keyof any | undefined,
+  ReadOnly extends readonly any[],
+> = IdField extends keyof any ? IdField | ReadOnly[number] : ReadOnly[number];
+
+// Helper type for InsertData computation
+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>>
+    >;
+
 // Extract insert data type from BaseTable
-// This type makes the insertRequired fields required while keeping others optional
+// Auto-infers required fields from validator nullability + user-specified required fields
+// Excludes readOnly fields and idField
 export type InsertData<BT> = BT extends import("./client/base-table").BaseTable<
-  infer Schema extends Record<string, z.ZodType>,
   any,
-  infer InsertRequired extends readonly any[],
+  any,
+  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>>
+  ? 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>>;
 
 // Extract update data type from BaseTable
-// This type makes the updateRequired fields required while keeping others optional
+// All fields are optional for updates, excludes readOnly fields and idField
 export type UpdateData<BT> = BT extends import("./client/base-table").BaseTable<
-  infer Schema extends Record<string, z.ZodType>,
   any,
   any,
-  infer UpdateRequired extends readonly any[]
+  any,
+  any
 >
-  ? [UpdateRequired[number]] extends [keyof InferSchemaType<Schema>]
-    ? UpdateRequired extends readonly (keyof InferSchemaType<Schema>)[]
-      ? MakeFieldsRequired<InferSchemaType<Schema>, UpdateRequired[number]>
-      : Partial<InferSchemaType<Schema>>
-    : Partial<InferSchemaType<Schema>>
+  ? 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;
+  /**
+   * Overrides the default behavior of the database to use entity IDs (rather than field names) in THIS REQUEST ONLY
+   */
+  useEntityIds?: boolean;
 };
 
-export type ConditionallyWithODataAnnotations<T, IncludeODataAnnotations extends boolean> = 
-  IncludeODataAnnotations extends true 
-    ? T & {
-        "@id": string;
-        "@editLink": string;
-      }
-    : T;
+export type ConditionallyWithODataAnnotations<
+  T,
+  IncludeODataAnnotations extends boolean,
+> = IncludeODataAnnotations extends true
+  ? T & {
+      "@id": string;
+      "@editLink": string;
+    }
+  : T;
 
 // Helper type to extract schema from a TableOccurrence
-export type ExtractSchemaFromOccurrence<Occ> =
-  Occ extends { baseTable: { schema: infer S } }
-    ? S extends Record<string, StandardSchemaV1>
-      ? S
-      : Record<string, StandardSchemaV1>
-    : Record<string, StandardSchemaV1>;
+export type ExtractSchemaFromOccurrence<Occ> = Occ extends {
+  baseTable: { schema: infer S };
+}
+  ? S extends Record<string, StandardSchemaV1>
+    ? S
+    : Record<string, StandardSchemaV1>
+  : Record<string, StandardSchemaV1>;
+
+export type GenericFieldMetadata = {
+  $Nullable?: boolean;
+  "@Index"?: boolean;
+  "@Calculation"?: boolean;
+  "@Summary"?: boolean;
+  "@Global"?: boolean;
+  "@Org.OData.Core.V1.Permissions"?: "Org.OData.Core.V1.Permission@Read";
+};
+
+export type StringFieldMetadata = GenericFieldMetadata & {
+  $Type: "Edm.String";
+  $DefaultValue?: "USER" | "USERNAME" | "CURRENT_USER";
+  $MaxLength?: number;
+};
+
+export type DecimalFieldMetadata = GenericFieldMetadata & {
+  $Type: "Edm.Decimal";
+  "@AutoGenerated"?: boolean;
+};
+
+export type DateFieldMetadata = GenericFieldMetadata & {
+  $Type: "Edm.Date";
+  $DefaultValue?: "CURDATE" | "CURRENT_DATE";
+};
+
+export type TimeOfDayFieldMetadata = GenericFieldMetadata & {
+  $Type: "Edm.TimeOfDay";
+  $DefaultValue?: "CURTIME" | "CURRENT_TIME";
+};
+
+export type DateTimeOffsetFieldMetadata = GenericFieldMetadata & {
+  $Type: "Edm.Date";
+  $DefaultValue?: "CURTIMESTAMP" | "CURRENT_TIMESTAMP";
+  "@VersionId"?: boolean;
+};
+
+export type StreamFieldMetadata = {
+  $Type: "Edm.Stream";
+  $Nullable?: boolean;
+  "@EnclosedPath": string;
+  "@ExternalOpenPath": string;
+  "@ExternalSecurePath"?: string;
+};
+
+export type FieldMetadata =
+  | StringFieldMetadata
+  | DecimalFieldMetadata
+  | DateFieldMetadata
+  | TimeOfDayFieldMetadata
+  | DateTimeOffsetFieldMetadata
+  | StreamFieldMetadata;
+
+export type EntityType = {
+  $Kind: "EntityType";
+  $Key: string[];
+} & Record<string, FieldMetadata>;
+
+export type EntitySet = {
+  $Kind: "EntitySet";
+  $Type: string;
+};
+
+export type Metadata = Record<string, EntityType | EntitySet>;

package/src/validation.ts

@@ -1,12 +1,19 @@
 import type { ODataRecordMetadata } from "./types";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 import type { TableOccurrence } from "./client/table-occurrence";
+import {
+  ValidationError,
+  ResponseStructureError,
+  RecordCountMismatchError,
+} from "./errors";
 
 // Type for expand validation configuration
 export type 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
   selectedFields?: string[];
   nestedExpands?: ExpandValidationConfig[];
 };
@@ -22,7 +29,7 @@ export async function validateRecord<T extends Record<string, any>>(
   expandConfigs?: ExpandValidationConfig[],
 ): Promise<
   | { valid: true; data: T & ODataRecordMetadata }
-  | { valid: false; error: Error }
+  | { valid: false; error: ValidationError }
 > {
   // Extract OData metadata fields (don't validate them - include if present)
   const { "@id": id, "@editLink": editLink, ...rest } = record;
@@ -54,20 +61,42 @@ export async function validateRecord<T extends Record<string, any>>(
 
       if (fieldSchema) {
         const input = rest[fieldName];
-        let result = fieldSchema["~standard"].validate(input);
-        if (result instanceof Promise) result = await result;
+        try {
+          let result = fieldSchema["~standard"].validate(input);
+          if (result instanceof Promise) result = await result;
 
-        // if the `issues` field exists, the validation failed
-        if (result.issues) {
+          // 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,
+                },
+              ),
+            };
+          }
+
+          validatedRecord[fieldName] = result.value;
+        } catch (originalError) {
+          // If the validator throws directly, wrap it
           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;
       } else {
         // For fields not in schema (like when explicitly selecting ROWID/ROWMODID)
         // include them from the original response
@@ -103,8 +132,12 @@ export async function validateRecord<T extends Record<string, any>>(
               if (isRelatedToExpand) {
                 return {
                   valid: false,
-                  error: new Error(
+                  error: new ValidationError(
                     `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,
+                    [],
+                    {
+                      field: expandConfig.relation,
+                    },
                   ),
                 };
               }
@@ -129,8 +162,13 @@ export async function validateRecord<T extends Record<string, any>>(
               if (!itemValidation.valid) {
                 return {
                   valid: false,
-                  error: new Error(
+                  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,
+                    },
                   ),
                 };
               }
@@ -148,8 +186,13 @@ export async function validateRecord<T extends Record<string, any>>(
             if (!itemValidation.valid) {
               return {
                 valid: false,
-                error: new Error(
+                error: new ValidationError(
                   `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,
+                  itemValidation.error.issues,
+                  {
+                    field: expandConfig.relation,
+                    cause: itemValidation.error.cause,
+                  },
                 ),
               };
             }
@@ -171,20 +214,43 @@ export async function validateRecord<T extends Record<string, any>>(
 
   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;
+    try {
+      let result = fieldSchema["~standard"].validate(input);
+      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,
+            },
+          ),
+        };
+      }
 
-    // if the `issues` field exists, the validation failed
-    if (result.issues) {
+      validatedRecord[fieldName] = result.value;
+    } catch (originalError) {
+      // If the validator throws an error directly, catch and wrap it
+      // This preserves the original error instance for instanceof checks
       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;
   }
 
   // Validate expanded relations even when not using selected fields
@@ -215,8 +281,12 @@ export async function validateRecord<T extends Record<string, any>>(
             if (isRelatedToExpand) {
               return {
                 valid: false,
-                error: new Error(
+                error: new ValidationError(
                   `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,
+                  [],
+                  {
+                    field: expandConfig.relation,
+                  },
                 ),
               };
             }
@@ -241,8 +311,13 @@ export async function validateRecord<T extends Record<string, any>>(
             if (!itemValidation.valid) {
               return {
                 valid: false,
-                error: new Error(
+                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,
+                  },
                 ),
               };
             }
@@ -260,8 +335,13 @@ export async function validateRecord<T extends Record<string, any>>(
           if (!itemValidation.valid) {
             return {
               valid: false,
-              error: new Error(
+              error: new ValidationError(
                 `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,
+                itemValidation.error.issues,
+                {
+                  field: expandConfig.relation,
+                  cause: itemValidation.error.cause,
+                },
               ),
             };
           }
@@ -287,13 +367,13 @@ export async function validateListResponse<T extends Record<string, any>>(
   expandConfigs?: ExpandValidationConfig[],
 ): Promise<
   | { valid: true; data: (T & ODataRecordMetadata)[] }
-  | { valid: false; error: Error }
+  | { valid: false; error: ResponseStructureError | ValidationError }
 > {
   // Check if response has the expected structure
   if (!response || typeof response !== "object") {
     return {
       valid: false,
-      error: new Error("Invalid response: expected an object"),
+      error: new ResponseStructureError("an object", response),
     };
   }
 
@@ -303,8 +383,9 @@ export async function validateListResponse<T extends Record<string, any>>(
   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,
       ),
     };
   }
@@ -324,9 +405,7 @@ export async function validateListResponse<T extends Record<string, any>>(
     if (!validation.valid) {
       return {
         valid: false,
-        error: new Error(
-          `Validation failed for record at index ${i}: ${validation.error.message}`,
-        ),
+        error: validation.error,
       };
     }
 
@@ -350,14 +429,19 @@ export async function validateSingleResponse<T extends Record<string, any>>(
   mode: "exact" | "maybe" = "maybe",
 ): Promise<
   | { valid: true; data: (T & ODataRecordMetadata) | null }
-  | { valid: false; error: Error }
+  | { 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 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,
       ),
     };
   }
@@ -367,7 +451,7 @@ export async function validateSingleResponse<T extends Record<string, any>>(
     if (mode === "exact") {
       return {
         valid: false,
-        error: new Error("Expected exactly one record, but received none"),
+        error: new RecordCountMismatchError("one", 0),
       };
     }
     // mode === "maybe" - return null for empty
@@ -387,7 +471,7 @@ export async function validateSingleResponse<T extends Record<string, any>>(
   );
 
   if (!validation.valid) {
-    return validation as { valid: false; error: Error };
+    return validation as { valid: false; error: ValidationError };
   }
 
   return {