@proofkit/fmodata 0.1.0-alpha.0

package/src/types.ts

@@ -0,0 +1,123 @@
+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 };
+
+export interface ExecutableBuilder<T> {
+  execute(): Promise<Result<T>>;
+  getRequestConfig(): { method: string; url: string; body?: any };
+}
+
+export interface ExecutionContext {
+  _makeRequest<T>(
+    url: string,
+    options?: RequestInit & FFetchOptions,
+  ): Promise<T>;
+}
+
+export type InferSchemaType<Schema extends Record<string, StandardSchemaV1>> = {
+  [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output> 
+    ? Output 
+    : never;
+};
+
+export type WithSystemFields<T> =
+  T extends Record<string, any>
+    ? T & {
+        ROWID: number;
+        ROWMODID: number;
+      }
+    : never;
+
+// Helper type to exclude system fields from a union of keys
+export type ExcludeSystemFields<T extends keyof any> = Exclude<
+  T,
+  "ROWID" | "ROWMODID"
+>;
+
+// Helper type to omit system fields from an object type
+export type OmitSystemFields<T> = Omit<T, "ROWID" | "ROWMODID">;
+
+// OData record metadata fields (present on each record)
+export type ODataRecordMetadata = {
+  "@id": string;
+  "@editLink": string;
+};
+
+// OData response wrapper (top-level, internal use only)
+export type ODataListResponse<T> = {
+  "@context": string;
+  value: (T & ODataRecordMetadata)[];
+};
+
+export type ODataSingleResponse<T> = T &
+  ODataRecordMetadata & {
+    "@context": string;
+  };
+
+// OData response for single field values
+export type ODataFieldResponse<T> = {
+  "@context": string;
+  value: T;
+};
+
+// Result pattern for execute responses
+export type Result<T, E = Error> =
+  | { data: T; error: undefined }
+  | { data: undefined; error: E };
+
+// Make specific keys required, rest optional
+export type MakeFieldsRequired<T, Keys extends keyof T> = Partial<T> &
+  Required<Pick<T, Keys>>;
+
+// Extract insert data type from BaseTable
+// This type makes the insertRequired fields required while keeping others optional
+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
+>
+  ? [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>>;
+
+// Extract update data type from BaseTable
+// This type makes the updateRequired fields required while keeping others optional
+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[]
+>
+  ? [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 ExecuteOptions = {
+  includeODataAnnotations?: boolean;
+  skipValidation?: boolean;
+};
+
+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>;

package/src/validation.ts

@@ -0,0 +1,397 @@
+import type { ODataRecordMetadata } from "./types";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import type { TableOccurrence } from "./client/table-occurrence";
+
+// Type for expand validation configuration
+export type ExpandValidationConfig = {
+  relation: string;
+  targetSchema?: Record<string, StandardSchemaV1>;
+  targetOccurrence?: TableOccurrence<any, any, any, any>;
+  selectedFields?: string[];
+  nestedExpands?: ExpandValidationConfig[];
+};
+
+/**
+ * Validates a single record against a schema, only validating selected fields.
+ * Also validates expanded relations if expandConfigs are provided.
+ */
+export async function validateRecord<T extends Record<string, any>>(
+  record: any,
+  schema: Record<string, StandardSchemaV1> | undefined,
+  selectedFields?: (keyof T)[],
+  expandConfigs?: ExpandValidationConfig[],
+): Promise<
+  | { valid: true; data: T & ODataRecordMetadata }
+  | { valid: false; error: Error }
+> {
+  // 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 || "",
+  };
+
+  // If no schema, just return the data with metadata
+  if (!schema) {
+    return {
+      valid: true,
+      data: { ...rest, ...metadata } as T & ODataRecordMetadata,
+    };
+  }
+
+  // Filter out FileMaker system fields that shouldn't be in responses by default
+  const { ROWID, ROWMODID, ...restWithoutSystemFields } = rest;
+
+  // If selected fields are specified, validate only those fields
+  if (selectedFields && selectedFields.length > 0) {
+    const validatedRecord: Record<string, any> = {};
+
+    for (const field of selectedFields) {
+      const fieldName = String(field);
+      const fieldSchema = schema[fieldName];
+
+      if (fieldSchema) {
+        const input = rest[fieldName];
+        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 Error(
+              `Validation failed for field '${fieldName}': ${JSON.stringify(result.issues, null, 2)}`,
+            ),
+          };
+        }
+
+        validatedRecord[fieldName] = result.value;
+      } else {
+        // For fields not in schema (like when explicitly selecting ROWID/ROWMODID)
+        // include them from the original response
+        validatedRecord[fieldName] = rest[fieldName];
+      }
+    }
+
+    // Validate expanded relations
+    if (expandConfigs && expandConfigs.length > 0) {
+      for (const expandConfig of expandConfigs) {
+        const expandValue = rest[expandConfig.relation];
+
+        // Check if expand field is missing
+        if (expandValue === undefined) {
+          // Check for inline error array (FileMaker returns errors inline when expand fails)
+          if (Array.isArray(rest.error) && rest.error.length > 0) {
+            // Extract error message from inline error
+            const errorDetail = rest.error[0]?.error;
+            if (errorDetail?.message) {
+              const errorMessage = errorDetail.message;
+              // Check if the error is related to this expand by checking if:
+              // 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()),
+                  ));
+
+              if (isRelatedToExpand) {
+                return {
+                  valid: false,
+                  error: new Error(
+                    `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,
+                  ),
+                };
+              }
+            }
+          }
+          // If no inline error but expand was expected, that's also an issue
+          // However, this might be a legitimate case (e.g., no related records)
+          // So we'll only fail if there's an explicit error array
+        } else {
+          // Original validation logic for when expand exists
+          if (Array.isArray(expandValue)) {
+            // Validate each item in the expanded array
+            const validatedExpandedItems: any[] = [];
+            for (let i = 0; i < expandValue.length; i++) {
+              const item = expandValue[i];
+              const itemValidation = await validateRecord(
+                item,
+                expandConfig.targetSchema,
+                expandConfig.selectedFields as string[] | undefined,
+                expandConfig.nestedExpands,
+              );
+              if (!itemValidation.valid) {
+                return {
+                  valid: false,
+                  error: new Error(
+                    `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`,
+                  ),
+                };
+              }
+              validatedExpandedItems.push(itemValidation.data);
+            }
+            validatedRecord[expandConfig.relation] = validatedExpandedItems;
+          } else {
+            // Single expanded item (shouldn't happen in OData, but handle it)
+            const itemValidation = await validateRecord(
+              expandValue,
+              expandConfig.targetSchema,
+              expandConfig.selectedFields as string[] | undefined,
+              expandConfig.nestedExpands,
+            );
+            if (!itemValidation.valid) {
+              return {
+                valid: false,
+                error: new Error(
+                  `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,
+                ),
+              };
+            }
+            validatedRecord[expandConfig.relation] = itemValidation.data;
+          }
+        }
+      }
+    }
+
+    // Merge validated data with metadata
+    return {
+      valid: true,
+      data: { ...validatedRecord, ...metadata } as T & ODataRecordMetadata,
+    };
+  }
+
+  // Validate all fields in schema, but exclude ROWID/ROWMODID by default
+  const validatedRecord: Record<string, any> = { ...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 the `issues` field exists, the validation failed
+    if (result.issues) {
+      return {
+        valid: false,
+        error: new Error(
+          `Validation failed for field '${fieldName}': ${JSON.stringify(result.issues, null, 2)}`,
+        ),
+      };
+    }
+
+    validatedRecord[fieldName] = result.value;
+  }
+
+  // Validate expanded relations even when not using selected fields
+  if (expandConfigs && expandConfigs.length > 0) {
+    for (const expandConfig of expandConfigs) {
+      const expandValue = rest[expandConfig.relation];
+
+      // Check if expand field is missing
+      if (expandValue === undefined) {
+        // Check for inline error array (FileMaker returns errors inline when expand fails)
+        if (Array.isArray(rest.error) && rest.error.length > 0) {
+          // Extract error message from inline error
+          const errorDetail = rest.error[0]?.error;
+          if (errorDetail?.message) {
+            const errorMessage = errorDetail.message;
+            // Check if the error is related to this expand by checking if:
+            // 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()),
+                ));
+
+            if (isRelatedToExpand) {
+              return {
+                valid: false,
+                error: new Error(
+                  `Validation failed for expanded relation '${expandConfig.relation}': ${errorMessage}`,
+                ),
+              };
+            }
+          }
+        }
+        // If no inline error but expand was expected, that's also an issue
+        // However, this might be a legitimate case (e.g., no related records)
+        // So we'll only fail if there's an explicit error array
+      } else {
+        // Original validation logic for when expand exists
+        if (Array.isArray(expandValue)) {
+          // Validate each item in the expanded array
+          const validatedExpandedItems: any[] = [];
+          for (let i = 0; i < expandValue.length; i++) {
+            const item = expandValue[i];
+            const itemValidation = await validateRecord(
+              item,
+              expandConfig.targetSchema,
+              expandConfig.selectedFields as string[] | undefined,
+              expandConfig.nestedExpands,
+            );
+            if (!itemValidation.valid) {
+              return {
+                valid: false,
+                error: new Error(
+                  `Validation failed for expanded relation '${expandConfig.relation}' at index ${i}: ${itemValidation.error.message}`,
+                ),
+              };
+            }
+            validatedExpandedItems.push(itemValidation.data);
+          }
+          validatedRecord[expandConfig.relation] = validatedExpandedItems;
+        } else {
+          // Single expanded item (shouldn't happen in OData, but handle it)
+          const itemValidation = await validateRecord(
+            expandValue,
+            expandConfig.targetSchema,
+            expandConfig.selectedFields as string[] | undefined,
+            expandConfig.nestedExpands,
+          );
+          if (!itemValidation.valid) {
+            return {
+              valid: false,
+              error: new Error(
+                `Validation failed for expanded relation '${expandConfig.relation}': ${itemValidation.error.message}`,
+              ),
+            };
+          }
+          validatedRecord[expandConfig.relation] = itemValidation.data;
+        }
+      }
+    }
+  }
+
+  return {
+    valid: true,
+    data: { ...validatedRecord, ...metadata } as T & ODataRecordMetadata,
+  };
+}
+
+/**
+ * Validates a list response against a schema.
+ */
+export async function validateListResponse<T extends Record<string, any>>(
+  response: any,
+  schema: Record<string, StandardSchemaV1> | undefined,
+  selectedFields?: (keyof T)[],
+  expandConfigs?: ExpandValidationConfig[],
+): Promise<
+  | { valid: true; data: (T & ODataRecordMetadata)[] }
+  | { valid: false; error: Error }
+> {
+  // Check if response has the expected structure
+  if (!response || typeof response !== "object") {
+    return {
+      valid: false,
+      error: new Error("Invalid response: expected an object"),
+    };
+  }
+
+  // Extract @context (for internal validation, but we won't return it)
+  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",
+      ),
+    };
+  }
+
+  // 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,
+    );
+
+    if (!validation.valid) {
+      return {
+        valid: false,
+        error: new Error(
+          `Validation failed for record at index ${i}: ${validation.error.message}`,
+        ),
+      };
+    }
+
+    validatedRecords.push(validation.data);
+  }
+
+  return {
+    valid: true,
+    data: validatedRecords,
+  };
+}
+
+/**
+ * Validates a single record response against a schema.
+ */
+export async function validateSingleResponse<T extends Record<string, any>>(
+  response: any,
+  schema: Record<string, StandardSchemaV1> | undefined,
+  selectedFields?: (keyof T)[],
+  expandConfigs?: ExpandValidationConfig[],
+  mode: "exact" | "maybe" = "maybe",
+): Promise<
+  | { valid: true; data: (T & ODataRecordMetadata) | null }
+  | { valid: false; error: Error }
+> {
+  // Check for multiple records (error in both modes)
+  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}`
+      ),
+    };
+  }
+
+  // Handle empty responses
+  if (!response || (response.value && response.value.length === 0)) {
+    if (mode === "exact") {
+      return {
+        valid: false,
+        error: new Error("Expected exactly one record, but received none"),
+      };
+    }
+    // mode === "maybe" - return null for empty
+    return {
+      valid: true,
+      data: null,
+    };
+  }
+
+  // Single record validation
+  const record = response.value?.[0] ?? response;
+  const validation = await validateRecord<T>(
+    record,
+    schema,
+    selectedFields,
+    expandConfigs,
+  );
+
+  if (!validation.valid) {
+    return validation as { valid: false; error: Error };
+  }
+
+  return {
+    valid: true,
+    data: validation.data,
+  };
+}