@proofkit/fmodata 0.1.0-alpha.13 → 0.1.0-alpha.14

package/src/client/response-processor.ts

@@ -1,5 +1,5 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { BaseTable } from "./base-table";
+import type { FMTable } from "../orm/table";
 import type { ExecuteOptions } from "../types";
 import type { ExpandValidationConfig } from "../validation";
 import { ValidationError, ResponseStructureError } from "../errors";
@@ -23,16 +23,15 @@ export type ODataRecordResponse<T = unknown> = ODataResponse<
   }
 >;
 
-
 /**
- * Transform field IDs back to names using the base table configuration
+ * Transform field IDs back to names using the table configuration
  */
 export function applyFieldTransformation<T extends Record<string, unknown>>(
   response: ODataResponse<T> | ODataListResponse<T>,
-  baseTable: BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
+  table: FMTable<any, any>,
   expandConfigs?: ExpandValidationConfig[],
 ): ODataResponse<T> | ODataListResponse<T> {
-  return transformResponseFields(response, baseTable, expandConfigs) as
+  return transformResponseFields(response, table, expandConfigs) as
     | ODataResponse<T>
     | ODataListResponse<T>;
 }

package/src/client/update-builder.ts

@@ -6,45 +6,44 @@ import type {
   ExecuteOptions,
 } from "../types";
 import { getAcceptHeader } from "../types";
-import type { TableOccurrence } from "./table-occurrence";
-import type { BaseTable } from "./base-table";
+import type { FMTable, InferSchemaOutputFromFMTable } from "../orm/table";
+import {
+  getTableName,
+  getTableId as getTableIdHelper,
+  getBaseTableConfig,
+  isUsingEntityIds,
+} from "../orm/table";
 import { QueryBuilder } from "./query-builder";
 import { type FFetchOptions } from "@fetchkit/ffetch";
-import {
-  transformFieldNamesToIds,
-  transformTableName,
-  getTableIdentifiers,
-} from "../transform";
+import { transformFieldNamesToIds } from "../transform";
+import { parseErrorResponse } from "./error-parser";
+import { validateAndTransformInput } from "../validation";
 
 /**
  * Initial update builder returned from EntitySet.update(data)
  * Requires calling .byId() or .where() before .execute() is available
  */
 export class UpdateBuilder<
-  T extends Record<string, any>,
-  BT extends BaseTable<any, any, any, any>,
+  Occ extends FMTable<any, any>,
   ReturnPreference extends "minimal" | "representation" = "minimal",
 > {
-  private tableName: string;
   private databaseName: string;
   private context: ExecutionContext;
-  private occurrence?: TableOccurrence<any, any, any, any>;
-  private data: Partial<T>;
+  private table: Occ;
+  private data: Partial<InferSchemaOutputFromFMTable<Occ>>;
   private returnPreference: ReturnPreference;
 
   private databaseUseEntityIds: boolean;
 
   constructor(config: {
-    occurrence?: TableOccurrence<any, any, any, any>;
-    tableName: string;
+    occurrence: Occ;
     databaseName: string;
     context: ExecutionContext;
-    data: Partial<T>;
+    data: Partial<InferSchemaOutputFromFMTable<Occ>>;
     returnPreference: ReturnPreference;
     databaseUseEntityIds?: boolean;
   }) {
-    this.occurrence = config.occurrence;
-    this.tableName = config.tableName;
+    this.table = config.occurrence;
     this.databaseName = config.databaseName;
     this.context = config.context;
     this.data = config.data;
@@ -58,10 +57,9 @@ export class UpdateBuilder<
    */
   byId(
     id: string | number,
-  ): ExecutableUpdateBuilder<T, true, ReturnPreference> {
-    return new ExecutableUpdateBuilder<T, true, ReturnPreference>({
-      occurrence: this.occurrence,
-      tableName: this.tableName,
+  ): ExecutableUpdateBuilder<Occ, true, ReturnPreference> {
+    return new ExecutableUpdateBuilder<Occ, true, ReturnPreference>({
+      occurrence: this.table,
       databaseName: this.databaseName,
       context: this.context,
       data: this.data,
@@ -79,19 +77,12 @@ export class UpdateBuilder<
    */
   where(
     fn: (
-      q: QueryBuilder<WithSystemFields<T>>,
-    ) => QueryBuilder<WithSystemFields<T>>,
-  ): ExecutableUpdateBuilder<T, true, ReturnPreference> {
+      q: QueryBuilder<Occ>,
+    ) => QueryBuilder<Occ>,
+  ): ExecutableUpdateBuilder<Occ, true, ReturnPreference> {
     // Create a QueryBuilder for the user to configure
-    const queryBuilder = new QueryBuilder<
-      WithSystemFields<T>,
-      keyof WithSystemFields<T>,
-      false,
-      false,
-      undefined
-    >({
-      occurrence: undefined,
-      tableName: this.tableName,
+    const queryBuilder = new QueryBuilder<Occ>({
+      occurrence: this.table,
       databaseName: this.databaseName,
       context: this.context,
     });
@@ -99,9 +90,8 @@ export class UpdateBuilder<
     // Let the user configure it
     const configuredBuilder = fn(queryBuilder);
 
-    return new ExecutableUpdateBuilder<T, true, ReturnPreference>({
-      occurrence: this.occurrence,
-      tableName: this.tableName,
+    return new ExecutableUpdateBuilder<Occ, true, ReturnPreference>({
+      occurrence: this.table,
       databaseName: this.databaseName,
       context: this.context,
       data: this.data,
@@ -119,39 +109,36 @@ export class UpdateBuilder<
  * Can return either updated count or full record based on returnFullRecord option
  */
 export class ExecutableUpdateBuilder<
-  T extends Record<string, any>,
+  Occ extends FMTable<any, any>,
   IsByFilter extends boolean,
   ReturnPreference extends "minimal" | "representation" = "minimal",
 > implements
     ExecutableBuilder<
-      ReturnPreference extends "minimal" ? { updatedCount: number } : T
+      ReturnPreference extends "minimal" ? { updatedCount: number } : InferSchemaOutputFromFMTable<Occ>
     >
 {
-  private tableName: string;
   private databaseName: string;
   private context: ExecutionContext;
-  private occurrence?: TableOccurrence<any, any, any, any>;
-  private data: Partial<T>;
+  private table: Occ;
+  private data: Partial<InferSchemaOutputFromFMTable<Occ>>;
   private mode: "byId" | "byFilter";
   private recordId?: string | number;
-  private queryBuilder?: QueryBuilder<any>;
+  private queryBuilder?: QueryBuilder<Occ>;
   private returnPreference: ReturnPreference;
   private databaseUseEntityIds: boolean;
 
   constructor(config: {
-    occurrence?: TableOccurrence<any, any, any, any>;
-    tableName: string;
+    occurrence: Occ;
     databaseName: string;
     context: ExecutionContext;
-    data: Partial<T>;
+    data: Partial<InferSchemaOutputFromFMTable<Occ>>;
     mode: "byId" | "byFilter";
     recordId?: string | number;
-    queryBuilder?: QueryBuilder<any>;
+    queryBuilder?: QueryBuilder<Occ>;
     returnPreference: ReturnPreference;
     databaseUseEntityIds?: boolean;
   }) {
-    this.occurrence = config.occurrence;
-    this.tableName = config.tableName;
+    this.table = config.occurrence;
     this.databaseName = config.databaseName;
     this.context = config.context;
     this.data = config.data;
@@ -180,30 +167,25 @@ export class ExecutableUpdateBuilder<
    * @param useEntityIds - Optional override for entity ID usage
    */
   private getTableId(useEntityIds?: boolean): string {
-    if (!this.occurrence) {
-      return this.tableName;
-    }
-
     const contextDefault = this.context._getUseEntityIds?.() ?? false;
     const shouldUseIds = useEntityIds ?? contextDefault;
 
     if (shouldUseIds) {
-      const identifiers = getTableIdentifiers(this.occurrence);
-      if (!identifiers.id) {
+      if (!isUsingEntityIds(this.table)) {
         throw new Error(
-          `useEntityIds is true but TableOccurrence "${identifiers.name}" does not have an fmtId defined`,
+          `useEntityIds is true but table "${getTableName(this.table)}" does not have entity IDs configured`,
         );
       }
-      return identifiers.id;
+      return getTableIdHelper(this.table);
     }
 
-    return this.occurrence.getTableName();
+    return getTableName(this.table);
   }
 
   async execute(
     options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },
   ): Promise<
-    Result<ReturnPreference extends "minimal" ? { updatedCount: number } : T>
+    Result<ReturnPreference extends "minimal" ? { updatedCount: number } : InferSchemaOutputFromFMTable<Occ>>
   > {
     // Merge database-level useEntityIds with per-request options
     const mergedOptions = this.mergeExecuteOptions(options);
@@ -211,14 +193,31 @@ export class ExecutableUpdateBuilder<
     // Get table identifier with override support
     const tableId = this.getTableId(mergedOptions.useEntityIds);
 
+    // Validate and transform input data using input validators (writeValidators)
+    let validatedData = this.data;
+    if (this.table) {
+      const baseTableConfig = getBaseTableConfig(this.table);
+      const inputSchema = baseTableConfig.inputSchema;
+      
+      try {
+        validatedData = await validateAndTransformInput(this.data, inputSchema);
+      } catch (error) {
+        // If validation fails, return error immediately
+        return {
+          data: undefined,
+          error: error instanceof Error ? error : new Error(String(error)),
+        } as any;
+      }
+    }
+
     // Transform field names to FMFIDs if using entity IDs
     // Only transform if useEntityIds resolves to true (respects per-request override)
     const shouldUseIds = mergedOptions.useEntityIds ?? false;
 
     const transformedData =
-      this.occurrence?.baseTable && shouldUseIds
-        ? transformFieldNamesToIds(this.data, this.occurrence.baseTable)
-        : this.data;
+      this.table && shouldUseIds
+        ? transformFieldNamesToIds(validatedData, this.table)
+        : validatedData;
 
     let url: string;
 
@@ -235,10 +234,11 @@ export class ExecutableUpdateBuilder<
       const queryString = this.queryBuilder.getQueryString();
       // The query string will have the tableId already transformed by QueryBuilder
       // Remove the leading "/" and table name from the query string as we'll build our own URL
+      const tableName = getTableName(this.table);
       const queryParams = queryString.startsWith(`/${tableId}`)
         ? queryString.slice(`/${tableId}`.length)
-        : queryString.startsWith(`/${this.tableName}`)
-          ? queryString.slice(`/${this.tableName}`.length)
+        : queryString.startsWith(`/${tableName}`)
+          ? queryString.slice(`/${tableName}`.length)
           : queryString;
 
       url = `/${this.databaseName}/${tableId}${queryParams}`;
@@ -273,7 +273,7 @@ export class ExecutableUpdateBuilder<
       return {
         data: response as ReturnPreference extends "minimal"
           ? { updatedCount: number }
-          : T,
+          : InferSchemaOutputFromFMTable<Occ>,
         error: undefined,
       };
     } else {
@@ -290,7 +290,7 @@ export class ExecutableUpdateBuilder<
       return {
         data: { updatedCount } as ReturnPreference extends "minimal"
           ? { updatedCount: number }
-          : T,
+          : InferSchemaOutputFromFMTable<Occ>,
         error: undefined,
       };
     }
@@ -298,12 +298,13 @@ export class ExecutableUpdateBuilder<
 
   getRequestConfig(): { method: string; url: string; body?: any } {
     // For batch operations, use database-level setting (no per-request override available here)
+    // Note: Input validation happens in execute() and processResponse() for batch operations
     const tableId = this.getTableId(this.databaseUseEntityIds);
 
     // Transform field names to FMFIDs if using entity IDs
     const transformedData =
-      this.occurrence?.baseTable && this.databaseUseEntityIds
-        ? transformFieldNamesToIds(this.data, this.occurrence.baseTable)
+      this.table && this.databaseUseEntityIds
+        ? transformFieldNamesToIds(this.data, this.table)
         : this.data;
 
     let url: string;
@@ -316,10 +317,11 @@ export class ExecutableUpdateBuilder<
       }
 
       const queryString = this.queryBuilder.getQueryString();
+      const tableName = getTableName(this.table);
       const queryParams = queryString.startsWith(`/${tableId}`)
         ? queryString.slice(`/${tableId}`.length)
-        : queryString.startsWith(`/${this.tableName}`)
-          ? queryString.slice(`/${this.tableName}`.length)
+        : queryString.startsWith(`/${tableName}`)
+          ? queryString.slice(`/${tableName}`.length)
           : queryString;
 
       url = `/${this.databaseName}/${tableId}${queryParams}`;
@@ -350,8 +352,18 @@ export class ExecutableUpdateBuilder<
     response: Response,
     options?: ExecuteOptions,
   ): Promise<
-    Result<ReturnPreference extends "minimal" ? { updatedCount: number } : T>
+    Result<ReturnPreference extends "minimal" ? { updatedCount: number } : InferSchemaOutputFromFMTable<Occ>>
   > {
+    // Check for error responses (important for batch operations)
+    if (!response.ok) {
+      const tableName = getTableName(this.table);
+      const error = await parseErrorResponse(
+        response,
+        response.url || `/${this.databaseName}/${tableName}`,
+      );
+      return { data: undefined, error };
+    }
+
     // Check for empty response (204 No Content)
     const text = await response.text();
     if (!text || text.trim() === "") {
@@ -361,20 +373,37 @@ export class ExecutableUpdateBuilder<
       return {
         data: { updatedCount } as ReturnPreference extends "minimal"
           ? { updatedCount: number }
-          : T,
+          : InferSchemaOutputFromFMTable<Occ>,
         error: undefined,
       };
     }
 
     const rawResponse = JSON.parse(text);
 
+    // Validate and transform input data using input validators (writeValidators)
+    // This is needed for processResponse because it's called from batch operations
+    // where the data hasn't been validated yet
+    let validatedData = this.data;
+    if (this.table) {
+      const baseTableConfig = getBaseTableConfig(this.table);
+      const inputSchema = baseTableConfig.inputSchema;
+      try {
+        validatedData = await validateAndTransformInput(this.data, inputSchema);
+      } catch (error) {
+        return {
+          data: undefined,
+          error: error instanceof Error ? error : new Error(String(error)),
+        } as any;
+      }
+    }
+
     // Handle based on return preference
     if (this.returnPreference === "representation") {
       // Return the full updated record
       return {
         data: rawResponse as ReturnPreference extends "minimal"
           ? { updatedCount: number }
-          : T,
+          : InferSchemaOutputFromFMTable<Occ>,
         error: undefined,
       };
     } else {
@@ -391,7 +420,7 @@ export class ExecutableUpdateBuilder<
       return {
         data: { updatedCount } as ReturnPreference extends "minimal"
           ? { updatedCount: number }
-          : T,
+          : InferSchemaOutputFromFMTable<Occ>,
         error: undefined,
       };
     }

package/src/errors.ts

@@ -167,6 +167,20 @@ export class ResponseParseError extends FMODataError {
   }
 }
 
+export class BatchTruncatedError extends FMODataError {
+  readonly kind = "BatchTruncatedError" as const;
+  readonly operationIndex: number;
+  readonly failedAtIndex: number;
+
+  constructor(operationIndex: number, failedAtIndex: number) {
+    super(
+      `Operation ${operationIndex} was not executed because operation ${failedAtIndex} failed`,
+    );
+    this.operationIndex = operationIndex;
+    this.failedAtIndex = failedAtIndex;
+  }
+}
+
 // ============================================
 // Type Guards
 // ============================================
@@ -207,6 +221,12 @@ export function isResponseParseError(
   return error instanceof ResponseParseError;
 }
 
+export function isBatchTruncatedError(
+  error: unknown,
+): error is BatchTruncatedError {
+  return error instanceof BatchTruncatedError;
+}
+
 export function isFMODataError(error: unknown): error is FMODataError {
   return error instanceof FMODataError;
 }
@@ -237,4 +257,5 @@ export type FMODataErrorType =
   | ResponseStructureError
   | RecordCountMismatchError
   | InvalidLocationHeaderError
-  | ResponseParseError;
+  | ResponseParseError
+  | BatchTruncatedError;

package/src/index.ts

@@ -1,14 +1,60 @@
 // Barrel file - exports all public API from the client folder
 
 // 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";
 
+// NEW ORM API - Drizzle-inspired field builders and operators
+export {
+  // Field builders
+  textField,
+  numberField,
+  dateField,
+  timeField,
+  timestampField,
+  containerField,
+  calcField,
+  type FieldBuilder,
+  // Table definition
+  fmTableOccurrence,
+  FMTable,
+  type FMTableWithColumns as TableOccurrenceResult,
+  type InferTableSchema,
+  // Table helper functions
+  // getTableFields,
+  // getDefaultSelect,
+  // getBaseTableConfig,
+  // getFieldId,
+  // getFieldName,
+  // getTableId,
+  getTableColumns,
+  // Column references
+  type Column,
+  isColumn,
+  // Filter operators
+  type FilterExpression,
+  eq,
+  ne,
+  gt,
+  gte,
+  lt,
+  lte,
+  contains,
+  startsWith,
+  endsWith,
+  inArray,
+  notInArray,
+  isNull,
+  isNotNull,
+  and,
+  or,
+  not,
+  // OrderBy operators
+  type OrderByExpression,
+  asc,
+  desc,
+} from "./orm/index";
+
 // 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 {
@@ -25,6 +71,8 @@ export type {
 // Utility types for type annotations
 export type {
   Result,
+  BatchResult,
+  BatchItemResult,
   InferSchemaType,
   InsertData,
   UpdateData,
@@ -63,6 +111,7 @@ export {
   ResponseStructureError,
   RecordCountMismatchError,
   ResponseParseError,
+  BatchTruncatedError,
   isHTTPError,
   isValidationError,
   isODataError,
@@ -70,6 +119,7 @@ export {
   isResponseStructureError,
   isRecordCountMismatchError,
   isResponseParseError,
+  isBatchTruncatedError,
   isFMODataError,
 } from "./errors";
 

package/src/orm/column.ts

@@ -0,0 +1,78 @@
+/**
+ * Column represents a type-safe reference to a table field.
+ * Used in queries, filters, and operators to provide autocomplete and type checking.
+ *
+ * @template T - The TypeScript type of the column's value
+ * @template TableName - The table name as a string literal type (for validation)
+ * @template IsContainer - Whether this column represents a container field (cannot be selected)
+ */
+export class Column<
+  T = any,
+  TableName extends string = string,
+  IsContainer extends boolean = false,
+> {
+  readonly fieldName: string;
+  readonly entityId?: `FMFID:${string}`;
+  readonly tableName: TableName;
+  readonly tableEntityId?: `FMTID:${string}`;
+
+  // Phantom type for TypeScript inference - never actually holds a value
+  readonly _phantom!: T;
+  readonly _isContainer!: IsContainer;
+
+  constructor(config: {
+    fieldName: string;
+    entityId?: `FMFID:${string}`;
+    tableName: TableName;
+    tableEntityId?: `FMTID:${string}`;
+  }) {
+    this.fieldName = config.fieldName;
+    this.entityId = config.entityId;
+    this.tableName = config.tableName;
+    this.tableEntityId = config.tableEntityId;
+  }
+
+  /**
+   * Get the field identifier (entity ID if available, otherwise field name).
+   * Used when building OData queries.
+   */
+  getFieldIdentifier(useEntityIds?: boolean): string {
+    if (useEntityIds && this.entityId) {
+      return this.entityId;
+    }
+    return this.fieldName;
+  }
+
+  /**
+   * Get the table identifier (entity ID if available, otherwise table name).
+   * Used when building OData queries.
+   */
+  getTableIdentifier(useEntityIds?: boolean): string {
+    if (useEntityIds && this.tableEntityId) {
+      return this.tableEntityId;
+    }
+    return this.tableName;
+  }
+
+  /**
+   * Check if this column is from a specific table.
+   * Useful for validation in cross-table operations.
+   */
+  isFromTable(tableName: string): boolean {
+    return this.tableName === tableName;
+  }
+
+  /**
+   * Create a string representation for debugging.
+   */
+  toString(): string {
+    return `${this.tableName}.${this.fieldName}`;
+  }
+}
+
+/**
+ * Type guard to check if a value is a Column instance.
+ */
+export function isColumn(value: any): value is Column<any, any, any> {
+  return value instanceof Column;
+}