@proofkit/fmodata 0.1.0-alpha.1 → 0.1.0-alpha.11

package/src/index.ts

@@ -1,10 +1,38 @@
 // Barrel file - exports all public API from the client folder
-export { BaseTable } from "./client/base-table";
-export {
-  TableOccurrence,
-  createTableOccurrence,
-} from "./client/table-occurrence";
-export { FileMakerOData } from "./client/filemaker-odata";
+
+// Main API - use these functions to create tables and occurrences
+export { defineBaseTable } from "./client/base-table";
+export { defineTableOccurrence } from "./client/table-occurrence";
+export { buildOccurrences } from "./client/build-occurrences";
+export { FMServerConnection } from "./client/filemaker-odata";
+
+// Type-only exports - for type annotations only, not direct instantiation
+export type { BaseTable } from "./client/base-table";
+export type { TableOccurrence } from "./client/table-occurrence";
+export type { Database } from "./client/database";
+export type { EntitySet } from "./client/entity-set";
+export type {
+  SchemaManager,
+  Field,
+  StringField,
+  NumericField,
+  DateField,
+  TimeField,
+  TimestampField,
+  ContainerField,
+} from "./client/schema-manager";
+
+// Utility types for type annotations
+export type {
+  Result,
+  InferSchemaType,
+  InsertData,
+  UpdateData,
+  ODataRecordMetadata,
+  Metadata,
+} from "./types";
+
+// Filter types
 export type {
   Filter,
   TypedFilter,
@@ -15,3 +43,32 @@ 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,
+  SchemaLockedError,
+  ValidationError,
+  ResponseStructureError,
+  RecordCountMismatchError,
+  isHTTPError,
+  isValidationError,
+  isODataError,
+  isSchemaLockedError,
+  isResponseStructureError,
+  isRecordCountMismatchError,
+  isFMODataError,
+} from "./errors";
+
+export type { FMODataErrorType } from "./errors";

package/src/transform.ts

@@ -0,0 +1,249 @@
+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();
+}
+
+/**
+ * Gets both table name and ID from an occurrence
+ * @param occurrence - TableOccurrence instance
+ * @returns Object with name (always present) and id (may be undefined if not using IDs)
+ */
+export function getTableIdentifiers(
+  occurrence: TableOccurrence<any, any, any, any>,
+): { name: string; id: string | undefined } {
+  return {
+    name: occurrence.getTableName(),
+    id: occurrence.isUsingTableId() ? occurrence.getTableId() : undefined,
+  };
+}
+
+/**
+ * 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 };
@@ -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>;