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

package/src/errors.ts

@@ -0,0 +1,185 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/**
+ * Base class for all fmodata errors
+ */
+export abstract class FMODataError extends Error {
+  abstract readonly kind: string;
+  readonly timestamp: Date;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = this.constructor.name;
+    this.timestamp = new Date();
+  }
+}
+
+// ============================================
+// HTTP Errors (with status codes)
+// ============================================
+
+export class HTTPError extends FMODataError {
+  readonly kind = "HTTPError" as const;
+  readonly url: string;
+  readonly status: number;
+  readonly statusText: string;
+  readonly response?: any;
+
+  constructor(url: string, status: number, statusText: string, response?: any) {
+    super(`HTTP ${status} ${statusText} for ${url}`);
+    this.url = url;
+    this.status = status;
+    this.statusText = statusText;
+    this.response = response;
+  }
+
+  // Helper methods for common status checks
+  is4xx(): boolean {
+    return this.status >= 400 && this.status < 500;
+  }
+
+  is5xx(): boolean {
+    return this.status >= 500 && this.status < 600;
+  }
+
+  isNotFound(): boolean {
+    return this.status === 404;
+  }
+
+  isUnauthorized(): boolean {
+    return this.status === 401;
+  }
+
+  isForbidden(): boolean {
+    return this.status === 403;
+  }
+}
+
+// ============================================
+// OData Specific Errors
+// ============================================
+
+export class ODataError extends FMODataError {
+  readonly kind = "ODataError" as const;
+  readonly url: string;
+  readonly code?: string;
+  readonly details?: any;
+
+  constructor(url: string, message: string, code?: string, details?: any) {
+    super(`OData error: ${message}`);
+    this.url = url;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+// ============================================
+// Validation Errors
+// ============================================
+
+export class ValidationError extends FMODataError {
+  readonly kind = "ValidationError" as const;
+  readonly field?: string;
+  readonly issues: readonly StandardSchemaV1.Issue[];
+  readonly value?: unknown;
+
+  constructor(
+    message: string,
+    issues: readonly StandardSchemaV1.Issue[],
+    options?: {
+      field?: string;
+      value?: unknown;
+      cause?: Error["cause"];
+    },
+  ) {
+    super(
+      message,
+      options?.cause !== undefined ? { cause: options.cause } : undefined,
+    );
+    this.field = options?.field;
+    this.issues = issues;
+    this.value = options?.value;
+  }
+}
+
+export class ResponseStructureError extends FMODataError {
+  readonly kind = "ResponseStructureError" as const;
+  readonly expected: string;
+  readonly received: any;
+
+  constructor(expected: string, received: any) {
+    super(`Invalid response structure: expected ${expected}`);
+    this.expected = expected;
+    this.received = received;
+  }
+}
+
+export class RecordCountMismatchError extends FMODataError {
+  readonly kind = "RecordCountMismatchError" as const;
+  readonly expected: number | "one" | "at-most-one";
+  readonly received: number;
+
+  constructor(expected: number | "one" | "at-most-one", received: number) {
+    const expectedStr = typeof expected === "number" ? expected : expected;
+    super(`Expected ${expectedStr} record(s), but received ${received}`);
+    this.expected = expected;
+    this.received = received;
+  }
+}
+
+// ============================================
+// Type Guards
+// ============================================
+
+export function isHTTPError(error: unknown): error is HTTPError {
+  return error instanceof HTTPError;
+}
+
+export function isValidationError(error: unknown): error is ValidationError {
+  return error instanceof ValidationError;
+}
+
+export function isODataError(error: unknown): error is ODataError {
+  return error instanceof ODataError;
+}
+
+export function isResponseStructureError(
+  error: unknown,
+): error is ResponseStructureError {
+  return error instanceof ResponseStructureError;
+}
+
+export function isRecordCountMismatchError(
+  error: unknown,
+): error is RecordCountMismatchError {
+  return error instanceof RecordCountMismatchError;
+}
+
+export function isFMODataError(error: unknown): error is FMODataError {
+  return error instanceof FMODataError;
+}
+
+// ============================================
+// Union type for all possible errors
+// ============================================
+
+// Re-export ffetch errors (they'll be imported from @fetchkit/ffetch)
+export type {
+  TimeoutError,
+  AbortError,
+  NetworkError,
+  RetryLimitError,
+  CircuitOpenError,
+} from "@fetchkit/ffetch";
+
+export type FMODataErrorType =
+  | import("@fetchkit/ffetch").TimeoutError
+  | import("@fetchkit/ffetch").AbortError
+  | import("@fetchkit/ffetch").NetworkError
+  | import("@fetchkit/ffetch").RetryLimitError
+  | import("@fetchkit/ffetch").CircuitOpenError
+  | HTTPError
+  | ODataError
+  | ValidationError
+  | ResponseStructureError
+  | RecordCountMismatchError;

package/src/index.ts

@@ -1,8 +1,10 @@
 // Barrel file - exports all public API from the client folder
-export { BaseTable } from "./client/base-table";
+export { BaseTable, BaseTableWithIds } from "./client/base-table";
 export {
   TableOccurrence,
   createTableOccurrence,
+  TableOccurrenceWithIds,
+  createTableOccurrenceWithIds,
 } from "./client/table-occurrence";
 export { FMServerConnection } from "./client/filemaker-odata";
 
@@ -31,3 +33,30 @@ export type {
   DateOperators,
   LogicalFilter,
 } from "./filter-types";
+
+// Re-export ffetch errors
+export {
+  TimeoutError,
+  AbortError,
+  NetworkError,
+  RetryLimitError,
+  CircuitOpenError,
+} from "@fetchkit/ffetch";
+
+// Export our errors
+export {
+  FMODataError,
+  HTTPError,
+  ODataError,
+  ValidationError,
+  ResponseStructureError,
+  RecordCountMismatchError,
+  isHTTPError,
+  isValidationError,
+  isODataError,
+  isResponseStructureError,
+  isRecordCountMismatchError,
+  isFMODataError,
+} from "./errors";
+
+export type { FMODataErrorType } from "./errors";

package/src/transform.ts

@@ -0,0 +1,236 @@
+import type { BaseTable } from "./client/base-table";
+import type { TableOccurrence } from "./client/table-occurrence";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/**
+ * Transforms field names to FileMaker field IDs (FMFID) in an object
+ * @param data - Object with field names as keys
+ * @param baseTable - BaseTable instance to get field IDs from
+ * @returns Object with FMFID keys instead of field names
+ */
+export function transformFieldNamesToIds<T extends Record<string, any>>(
+  data: T,
+  baseTable: BaseTable<any, any, any, any>,
+): Record<string, any> {
+  if (!baseTable.isUsingFieldIds()) {
+    return data;
+  }
+
+  const transformed: Record<string, any> = {};
+  for (const [fieldName, value] of Object.entries(data)) {
+    const fieldId = baseTable.getFieldId(fieldName as any);
+    transformed[fieldId] = value;
+  }
+  return transformed;
+}
+
+/**
+ * Transforms FileMaker field IDs (FMFID) to field names in an object
+ * @param data - Object with FMFID keys
+ * @param baseTable - BaseTable instance to get field names from
+ * @returns Object with field names as keys instead of FMFIDs
+ */
+export function transformFieldIdsToNames<T extends Record<string, any>>(
+  data: T,
+  baseTable: BaseTable<any, any, any, any>,
+): Record<string, any> {
+  if (!baseTable.isUsingFieldIds()) {
+    return data;
+  }
+
+  const transformed: Record<string, any> = {};
+  for (const [key, value] of Object.entries(data)) {
+    // Check if this is an OData metadata field (starts with @)
+    if (key.startsWith("@")) {
+      transformed[key] = value;
+      continue;
+    }
+    
+    const fieldName = baseTable.getFieldName(key);
+    transformed[fieldName] = value;
+  }
+  return transformed;
+}
+
+/**
+ * Transforms a field name to FMFID or returns the field name if not using IDs
+ * @param fieldName - The field name to transform
+ * @param baseTable - BaseTable instance to get field ID from
+ * @returns The FMFID or field name
+ */
+export function transformFieldName(
+  fieldName: string,
+  baseTable: BaseTable<any, any, any, any>,
+): string {
+  return baseTable.getFieldId(fieldName as any);
+}
+
+/**
+ * Transforms a table occurrence name to FMTID or returns the name if not using IDs
+ * @param occurrence - TableOccurrence instance to get table ID from
+ * @returns The FMTID or table name
+ */
+export function transformTableName(
+  occurrence: TableOccurrence<any, any, any, any>,
+): string {
+  return occurrence.getTableId();
+}
+
+/**
+ * Transforms response data by converting field IDs back to field names recursively.
+ * Handles both single records and arrays of records, as well as nested expand relationships.
+ * 
+ * @param data - Response data from FileMaker (can be single record, array, or wrapped in value property)
+ * @param baseTable - BaseTable instance for the main table
+ * @param expandConfigs - Configuration for expanded relations (optional)
+ * @returns Transformed data with field names instead of IDs
+ */
+export function transformResponseFields(
+  data: any,
+  baseTable: BaseTable<any, any, any, any>,
+  expandConfigs?: Array<{
+    relation: string;
+    occurrence?: TableOccurrence<any, any, any, any>;
+  }>,
+): any {
+  if (!baseTable.isUsingFieldIds()) {
+    return data;
+  }
+
+  // Handle null/undefined
+  if (data === null || data === undefined) {
+    return data;
+  }
+
+  // Handle OData list response with value array
+  if (data.value && Array.isArray(data.value)) {
+    return {
+      ...data,
+      value: data.value.map((record: any) =>
+        transformSingleRecord(record, baseTable, expandConfigs),
+      ),
+    };
+  }
+
+  // Handle array of records
+  if (Array.isArray(data)) {
+    return data.map((record) =>
+      transformSingleRecord(record, baseTable, expandConfigs),
+    );
+  }
+
+  // Handle single record
+  return transformSingleRecord(data, baseTable, expandConfigs);
+}
+
+/**
+ * Transforms a single record, converting field IDs to names and handling nested expands
+ */
+function transformSingleRecord(
+  record: any,
+  baseTable: BaseTable<any, any, any, any>,
+  expandConfigs?: Array<{
+    relation: string;
+    occurrence?: TableOccurrence<any, any, any, any>;
+  }>,
+): any {
+  if (!record || typeof record !== "object") {
+    return record;
+  }
+
+  const transformed: Record<string, any> = {};
+
+  for (const [key, value] of Object.entries(record)) {
+    // Preserve OData metadata fields
+    if (key.startsWith("@")) {
+      transformed[key] = value;
+      continue;
+    }
+
+    // Check if this is an expanded relation (by relation name)
+    let expandConfig = expandConfigs?.find((ec) => ec.relation === key);
+    
+    // If not found by relation name, check if this key is a FMTID
+    // (FileMaker returns expanded relations with FMTID keys when using entity IDs)
+    if (!expandConfig && key.startsWith("FMTID:")) {
+      expandConfig = expandConfigs?.find(
+        (ec) =>
+          ec.occurrence &&
+          ec.occurrence.isUsingTableId() &&
+          ec.occurrence.getTableId() === key,
+      );
+    }
+    
+    if (expandConfig && expandConfig.occurrence) {
+      // Transform the expanded relation data recursively
+      // Use the relation name (not the FMTID) as the key
+      const relationKey = expandConfig.relation;
+      
+      if (Array.isArray(value)) {
+        transformed[relationKey] = value.map((nestedRecord) =>
+          transformSingleRecord(
+            nestedRecord,
+            expandConfig.occurrence!.baseTable,
+            undefined, // Don't pass nested expand configs for now
+          ),
+        );
+      } else if (value && typeof value === "object") {
+        transformed[relationKey] = transformSingleRecord(
+          value,
+          expandConfig.occurrence.baseTable,
+          undefined,
+        );
+      } else {
+        transformed[relationKey] = value;
+      }
+      continue;
+    }
+
+    // Transform field ID to field name
+    const fieldName = baseTable.getFieldName(key);
+    transformed[fieldName] = value;
+  }
+
+  return transformed;
+}
+
+/**
+ * Transforms an array of field names to FMFIDs
+ * @param fieldNames - Array of field names
+ * @param baseTable - BaseTable instance to get field IDs from
+ * @returns Array of FMFIDs or field names
+ */
+export function transformFieldNamesArray(
+  fieldNames: string[],
+  baseTable: BaseTable<any, any, any, any>,
+): string[] {
+  if (!baseTable.isUsingFieldIds()) {
+    return fieldNames;
+  }
+
+  return fieldNames.map((fieldName) => baseTable.getFieldId(fieldName as any));
+}
+
+/**
+ * Transforms a field name in an orderBy string (e.g., "name desc" -> "FMFID:1 desc")
+ * @param orderByString - The orderBy string (field name with optional asc/desc)
+ * @param baseTable - BaseTable instance to get field ID from
+ * @returns Transformed orderBy string with FMFID
+ */
+export function transformOrderByField(
+  orderByString: string,
+  baseTable: BaseTable<any, any, any, any>,
+): string {
+  if (!baseTable.isUsingFieldIds()) {
+    return orderByString;
+  }
+
+  // Parse the orderBy string to extract field name and direction
+  const parts = orderByString.trim().split(/\s+/);
+  const fieldName = parts[0];
+  const direction = parts[1]; // "asc" or "desc" or undefined
+
+  const fieldId = baseTable.getFieldId(fieldName as any);
+  return direction ? `${fieldId} ${direction}` : fieldId;
+}
+

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 };
@@ -13,12 +12,14 @@ export interface ExecutionContext {
   _makeRequest<T>(
     url: string,
     options?: RequestInit & FFetchOptions,
-  ): Promise<T>;
+  ): 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 
+  [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output>
+    ? Output
     : never;
 };
 
@@ -63,7 +64,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,34 +72,108 @@ 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 = {
@@ -106,18 +181,21 @@ export type ExecuteOptions = {
   skipValidation?: 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>;