@proofkit/fmodata 0.1.0-alpha.0 → 0.1.0-alpha.10

package/src/client/entity-set.ts

@@ -1,4 +1,3 @@
-import { z } from "zod/v4";
 import type {
   ExecutionContext,
   InferSchemaType,
@@ -6,6 +5,7 @@ import type {
   InsertData,
   UpdateData,
 } from "../types";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { BaseTable } from "./base-table";
 import type { TableOccurrence } from "./table-occurrence";
 import { QueryBuilder } from "./query-builder";
@@ -13,6 +13,7 @@ import { RecordBuilder } from "./record-builder";
 import { InsertBuilder } from "./insert-builder";
 import { DeleteBuilder } from "./delete-builder";
 import { UpdateBuilder } from "./update-builder";
+import { Database } from "./database";
 
 // Helper type to extract navigation relation names from an occurrence
 type ExtractNavigationNames<
@@ -27,7 +28,7 @@ type ExtractNavigationNames<
 // Helper type to extract schema from a TableOccurrence
 type ExtractSchemaFromOccurrence<O> =
   O extends TableOccurrence<infer BT, any, any, any>
-    ? BT extends BaseTable<infer S, any>
+    ? BT extends BaseTable<infer S, any, any, any>
       ? S
       : never
     : never;
@@ -35,7 +36,7 @@ type ExtractSchemaFromOccurrence<O> =
 // Helper type to extract defaultSelect from a TableOccurrence
 type ExtractDefaultSelect<O> =
   O extends TableOccurrence<infer BT, any, any, infer DefSelect>
-    ? BT extends BaseTable<infer S, any>
+    ? BT extends BaseTable<infer S, any, any, any>
       ? DefSelect extends "all"
         ? keyof S
         : DefSelect extends "schema"
@@ -59,19 +60,19 @@ type FindNavigationTarget<
       ? Name extends keyof Nav
         ? ResolveNavigationItem<Nav[Name]>
         : TableOccurrence<
-            BaseTable<Record<string, z.ZodTypeAny>, any>,
+            BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
             any,
             any,
             any
           >
       : TableOccurrence<
-          BaseTable<Record<string, z.ZodTypeAny>, any>,
+          BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
           any,
           any,
           any
         >
     : TableOccurrence<
-        BaseTable<Record<string, z.ZodTypeAny>, any>,
+        BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
         any,
         any,
         any
@@ -84,21 +85,22 @@ type GetTargetSchemaType<
 > = [FindNavigationTarget<O, Rel>] extends [
   TableOccurrence<infer BT, any, any, any>,
 ]
-  ? [BT] extends [BaseTable<infer S, any>]
-    ? [S] extends [Record<string, z.ZodType>]
+  ? [BT] extends [BaseTable<infer S, any, any, any>]
+    ? [S] extends [Record<string, StandardSchemaV1>]
       ? InferSchemaType<S>
       : Record<string, any>
     : Record<string, any>
   : Record<string, any>;
 
 export class EntitySet<
-  Schema extends Record<string, z.ZodType> = any,
+  Schema extends Record<string, StandardSchemaV1> = any,
   Occ extends TableOccurrence<any, any, any, any> | undefined = undefined,
 > {
   private occurrence?: Occ;
   private tableName: string;
   private databaseName: string;
   private context: ExecutionContext;
+  private database: Database<any>; // Database instance for accessing occurrences
   private isNavigateFromEntitySet?: boolean;
   private navigateRelation?: string;
   private navigateSourceTableName?: string;
@@ -108,30 +110,39 @@ export class EntitySet<
     tableName: string;
     databaseName: string;
     context: ExecutionContext;
+    database?: any;
   }) {
     this.occurrence = config.occurrence;
     this.tableName = config.tableName;
     this.databaseName = config.databaseName;
     this.context = config.context;
+    this.database = config.database;
   }
 
   // Type-only method to help TypeScript infer the schema from occurrence
   static create<
-    OccurrenceSchema extends Record<string, z.ZodType>,
+    OccurrenceSchema extends Record<string, StandardSchemaV1>,
     Occ extends
-      | TableOccurrence<BaseTable<OccurrenceSchema, any>, any, any, any>
+      | TableOccurrence<
+          BaseTable<OccurrenceSchema, any, any, any>,
+          any,
+          any,
+          any
+        >
       | undefined = undefined,
   >(config: {
     occurrence?: Occ;
     tableName: string;
     databaseName: string;
     context: ExecutionContext;
+    database: Database<any>;
   }): EntitySet<OccurrenceSchema, Occ> {
     return new EntitySet<OccurrenceSchema, Occ>({
       occurrence: config.occurrence,
       tableName: config.tableName,
       databaseName: config.databaseName,
       context: config.context,
+      database: config.database,
     });
   }
 
@@ -157,6 +168,7 @@ export class EntitySet<
       tableName: this.tableName,
       databaseName: this.databaseName,
       context: this.context,
+      databaseUseEntityIds: this.database?.isUsingEntityIds() ?? false,
     });
 
     // Apply defaultSelect if occurrence exists and select hasn't been called
@@ -169,13 +181,13 @@ export class EntitySet<
         const fields = Object.keys(schema) as (keyof InferSchemaType<Schema>)[];
         // Deduplicate fields (same as select method)
         const uniqueFields = [...new Set(fields)];
-        return builder.select(...uniqueFields);
+        return builder.select(...uniqueFields).top(1000);
       } else if (Array.isArray(defaultSelect)) {
         // Use the provided field names, deduplicated
         const uniqueFields = [
           ...new Set(defaultSelect),
         ] as (keyof InferSchemaType<Schema>)[];
-        return builder.select(...uniqueFields);
+        return builder.select(...uniqueFields).top(1000);
       }
       // If defaultSelect is "all", no changes needed (current behavior)
     }
@@ -187,7 +199,10 @@ export class EntitySet<
       (builder as any).navigateSourceTableName = this.navigateSourceTableName;
       // navigateRecordId is intentionally not set (undefined) to indicate navigation from EntitySet
     }
-    return builder;
+
+    // Apply default pagination limit of 1000 records to prevent stack overflow
+    // with large datasets. Users can override with .top() if needed.
+    return builder.top(1000);
   }
 
   get(
@@ -196,19 +211,24 @@ export class EntitySet<
     InferSchemaType<Schema>,
     false,
     keyof InferSchemaType<Schema>,
-    Occ
+    Occ,
+    keyof InferSchemaType<Schema>,
+    {}
   > {
     const builder = new RecordBuilder<
       InferSchemaType<Schema>,
       false,
       keyof InferSchemaType<Schema>,
-      Occ
+      Occ,
+      keyof InferSchemaType<Schema>,
+      {}
     >({
       occurrence: this.occurrence,
       tableName: this.tableName,
       databaseName: this.databaseName,
       context: this.context,
       recordId: id,
+      databaseUseEntityIds: this.database?.isUsingEntityIds() ?? false,
     });
     // Propagate navigation context if present
     if (this.isNavigateFromEntitySet) {
@@ -219,49 +239,119 @@ export class EntitySet<
     return builder;
   }
 
+  // Overload: when returnFullRecord is explicitly false
+  insert(
+    data: Occ extends TableOccurrence<infer BT, any, any, any>
+      ? BT extends BaseTable<any, any, any, any>
+        ? InsertData<BT>
+        : Partial<InferSchemaType<Schema>>
+      : Partial<InferSchemaType<Schema>>,
+    options: { returnFullRecord: false },
+  ): InsertBuilder<InferSchemaType<Schema>, Occ, "minimal">;
+
+  // Overload: when returnFullRecord is true or omitted (default)
+  insert(
+    data: Occ extends TableOccurrence<infer BT, any, any, any>
+      ? BT extends BaseTable<any, any, any, any>
+        ? InsertData<BT>
+        : Partial<InferSchemaType<Schema>>
+      : Partial<InferSchemaType<Schema>>,
+    options?: { returnFullRecord?: true },
+  ): InsertBuilder<InferSchemaType<Schema>, Occ, "representation">;
+
+  // Implementation
   insert(
     data: Occ extends TableOccurrence<infer BT, any, any, any>
       ? BT extends BaseTable<any, any, any, any>
         ? InsertData<BT>
         : Partial<InferSchemaType<Schema>>
       : Partial<InferSchemaType<Schema>>,
-  ): InsertBuilder<InferSchemaType<Schema>, Occ> {
-    return new InsertBuilder<InferSchemaType<Schema>, Occ>({
+    options?: { returnFullRecord?: boolean },
+  ): InsertBuilder<InferSchemaType<Schema>, Occ, "minimal" | "representation"> {
+    const returnPref =
+      options?.returnFullRecord === false ? "minimal" : "representation";
+    return new InsertBuilder<InferSchemaType<Schema>, Occ, typeof returnPref>({
       occurrence: this.occurrence,
       tableName: this.tableName,
       databaseName: this.databaseName,
       context: this.context,
       data: data as Partial<InferSchemaType<Schema>>,
+      returnPreference: returnPref as any,
+      databaseUseEntityIds: this.database?.isUsingEntityIds() ?? false,
     });
   }
 
+  // Overload: when returnFullRecord is explicitly true
   update(
     data: Occ extends TableOccurrence<infer BT, any, any, any>
       ? BT extends BaseTable<any, any, any, any>
         ? UpdateData<BT>
         : Partial<InferSchemaType<Schema>>
       : Partial<InferSchemaType<Schema>>,
+    options: { returnFullRecord: true },
   ): UpdateBuilder<
     InferSchemaType<Schema>,
     Occ extends TableOccurrence<infer BT, any, any, any>
       ? BT extends BaseTable<any, any, any, any>
         ? BT
         : BaseTable<Schema, any, any, any>
-      : BaseTable<Schema, any, any, any>
+      : BaseTable<Schema, any, any, any>,
+    "representation"
+  >;
+
+  // Overload: when returnFullRecord is false or omitted (default returns count)
+  update(
+    data: Occ extends TableOccurrence<infer BT, any, any, any>
+      ? BT extends BaseTable<any, any, any, any>
+        ? UpdateData<BT>
+        : Partial<InferSchemaType<Schema>>
+      : Partial<InferSchemaType<Schema>>,
+    options?: { returnFullRecord?: false },
+  ): UpdateBuilder<
+    InferSchemaType<Schema>,
+    Occ extends TableOccurrence<infer BT, any, any, any>
+      ? BT extends BaseTable<any, any, any, any>
+        ? BT
+        : BaseTable<Schema, any, any, any>
+      : BaseTable<Schema, any, any, any>,
+    "minimal"
+  >;
+
+  // Implementation
+  update(
+    data: Occ extends TableOccurrence<infer BT, any, any, any>
+      ? BT extends BaseTable<any, any, any, any>
+        ? UpdateData<BT>
+        : Partial<InferSchemaType<Schema>>
+      : Partial<InferSchemaType<Schema>>,
+    options?: { returnFullRecord?: boolean },
+  ): UpdateBuilder<
+    InferSchemaType<Schema>,
+    Occ extends TableOccurrence<infer BT, any, any, any>
+      ? BT extends BaseTable<any, any, any, any>
+        ? BT
+        : BaseTable<Schema, any, any, any>
+      : BaseTable<Schema, any, any, any>,
+    "minimal" | "representation"
   > {
+    const returnPref =
+      options?.returnFullRecord === true ? "representation" : "minimal";
     return new UpdateBuilder<
       InferSchemaType<Schema>,
       Occ extends TableOccurrence<infer BT, any, any, any>
         ? BT extends BaseTable<any, any, any, any>
           ? BT
           : BaseTable<Schema, any, any, any>
-        : BaseTable<Schema, any, any, any>
+        : BaseTable<Schema, any, any, any>,
+      typeof returnPref
     >({
       occurrence: this.occurrence,
       tableName: this.tableName,
       databaseName: this.databaseName,
       context: this.context,
       data: data as Partial<InferSchemaType<Schema>>,
+      returnPreference: returnPref as any,
+      databaseUseEntityIds: this.database?.isUsingEntityIds() ?? false,
     });
   }
 
@@ -271,6 +361,7 @@ export class EntitySet<
       tableName: this.tableName,
       databaseName: this.databaseName,
       context: this.context,
+      databaseUseEntityIds: this.database?.isUsingEntityIds() ?? false,
     });
   }
 
@@ -280,15 +371,15 @@ export class EntitySet<
   ): EntitySet<
     ExtractSchemaFromOccurrence<
       FindNavigationTarget<Occ, RelationName>
-    > extends Record<string, z.ZodType>
+    > extends Record<string, StandardSchemaV1>
       ? ExtractSchemaFromOccurrence<FindNavigationTarget<Occ, RelationName>>
-      : Record<string, z.ZodTypeAny>,
+      : Record<string, StandardSchemaV1>,
     FindNavigationTarget<Occ, RelationName>
   >;
   // Overload for arbitrary strings - returns generic EntitySet
   navigate(
     relationName: string,
-  ): EntitySet<Record<string, z.ZodTypeAny>, undefined>;
+  ): EntitySet<Record<string, StandardSchemaV1>, undefined>;
   // Implementation
   navigate(relationName: string): EntitySet<any, any> {
     // Use the target occurrence if available, otherwise allow untyped navigation

package/src/client/filemaker-odata.ts

@@ -1,12 +1,21 @@
-import createClient, { FFetchOptions } from "@fetchkit/ffetch";
-import type { Auth, ExecutionContext } from "../types";
+import createClient, {
+  FFetchOptions,
+  TimeoutError,
+  AbortError,
+  NetworkError,
+  RetryLimitError,
+  CircuitOpenError,
+} from "@fetchkit/ffetch";
+import type { Auth, ExecutionContext, Result } from "../types";
+import { HTTPError, ODataError, SchemaLockedError } from "../errors";
 import { Database } from "./database";
 import { TableOccurrence } from "./table-occurrence";
 
-export class FileMakerOData implements ExecutionContext {
+export class FMServerConnection implements ExecutionContext {
   private fetchClient: ReturnType<typeof createClient>;
   private serverUrl: string;
   private auth: Auth;
+  private useEntityIds: boolean = false;
   constructor(config: {
     serverUrl: string;
     auth: Auth;
@@ -27,14 +36,42 @@ export class FileMakerOData implements ExecutionContext {
     this.auth = config.auth;
   }
 
+  /**
+   * @internal
+   * Sets whether to use FileMaker entity IDs (FMFID/FMTID) in requests
+   */
+  _setUseEntityIds(useEntityIds: boolean): void {
+    this.useEntityIds = useEntityIds;
+  }
+
+  /**
+   * @internal
+   * Gets whether to use FileMaker entity IDs (FMFID/FMTID) in requests
+   */
+  _getUseEntityIds(): boolean {
+    return this.useEntityIds;
+  }
+
+  /**
+   * @internal
+   * Gets the base URL for OData requests
+   */
+  _getBaseUrl(): string {
+    return `${this.serverUrl}${"apiKey" in this.auth ? `/otto` : ""}/fmi/odata/v4`;
+  }
+
   /**
    * @internal
    */
   async _makeRequest<T>(
     url: string,
-    options?: RequestInit & FFetchOptions,
-  ): Promise<T> {
+    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },
+  ): Promise<Result<T>> {
     const baseUrl = `${this.serverUrl}${"apiKey" in this.auth ? `/otto` : ""}/fmi/odata/v4`;
+    const fullUrl = baseUrl + url;
+
+    // Use per-request override if provided, otherwise use the database-level setting
+    const useEntityIds = options?.useEntityIds ?? this.useEntityIds;
 
     const headers = {
       Authorization:
@@ -43,6 +80,7 @@ export class FileMakerOData implements ExecutionContext {
           : `Basic ${btoa(`${this.auth.username}:${this.auth.password}`)}`,
       "Content-Type": "application/json",
       Accept: "application/json",
+      ...(useEntityIds ? { Prefer: "fmodata.entity-ids" } : {}),
       ...(options?.headers || {}),
     };
 
@@ -61,44 +99,147 @@ export class FileMakerOData implements ExecutionContext {
       ? createClient({ retries: 0, fetchHandler })
       : this.fetchClient;
 
-    const resp = await clientToUse(baseUrl + url, {
-      ...restOptions,
-      headers,
-    });
+    try {
+      const finalOptions = {
+        ...restOptions,
+        headers,
+      };
 
-    if (!resp.ok) {
-      throw new Error(
-        `Failed to make request to ${baseUrl + url}: ${resp.statusText}`,
-      );
-    }
+      // For batch requests, use native fetch to avoid any potential serialization issues with ffetch
+      const resp = url.includes("/$batch")
+        ? await fetch(fullUrl, {
+            method: finalOptions.method,
+            headers: finalOptions.headers,
+            body: finalOptions.body,
+          })
+        : await clientToUse(fullUrl, finalOptions);
 
-    // Check for affected rows header (for DELETE and bulk PATCH operations)
-    // FileMaker may return this with 204 No Content or 200 OK
-    const affectedRows = resp.headers.get("fmodata.affected_rows");
-    if (affectedRows !== null) {
-      return parseInt(affectedRows, 10) as T;
-    }
+      // Handle HTTP errors
+      if (!resp.ok) {
+        // Try to parse error body if it's JSON
+        let errorBody;
+        try {
+          if (resp.headers.get("content-type")?.includes("application/json")) {
+            errorBody = await resp.json();
+          }
+        } catch {
+          // Ignore JSON parse errors
+        }
 
-    // Handle 204 No Content with no body
-    if (resp.status === 204) {
-      return 0 as T;
-    }
+        // Check if it's an OData error response
+        if (errorBody?.error) {
+          const errorCode = errorBody.error.code;
+          const errorMessage = errorBody.error.message || resp.statusText;
+
+          // Check for schema locked error (code 303)
+          if (errorCode === "303" || errorCode === 303) {
+            return {
+              data: undefined,
+              error: new SchemaLockedError(
+                fullUrl,
+                errorMessage,
+                errorBody.error,
+              ),
+            };
+          }
+
+          return {
+            data: undefined,
+            error: new ODataError(
+              fullUrl,
+              errorMessage,
+              errorCode,
+              errorBody.error,
+            ),
+          };
+        }
+
+        return {
+          data: undefined,
+          error: new HTTPError(
+            fullUrl,
+            resp.status,
+            resp.statusText,
+            errorBody,
+          ),
+        };
+      }
+
+      // Check for affected rows header (for DELETE and bulk PATCH operations)
+      // FileMaker may return this with 204 No Content or 200 OK
+      const affectedRows = resp.headers.get("fmodata.affected_rows");
+      if (affectedRows !== null) {
+        return { data: parseInt(affectedRows, 10) as T, error: undefined };
+      }
+
+      // Handle 204 No Content with no body
+      if (resp.status === 204) {
+        // Check for Location header (used for insert with return=minimal)
+        // Use optional chaining for safety with mocks that might not have proper headers
+        const locationHeader =
+          resp.headers?.get?.("Location") || resp.headers?.get?.("location");
+        if (locationHeader) {
+          // Return the location header so InsertBuilder can extract ROWID
+          return { data: { _location: locationHeader } as T, error: undefined };
+        }
+        return { data: 0 as T, error: undefined };
+      }
 
-    if (resp.headers.get("content-type")?.includes("application/json")) {
-      let data = await resp.json();
-      if (data.error) {
-        throw new Error(data.error);
+      // Parse response
+      if (resp.headers.get("content-type")?.includes("application/json")) {
+        const data = await resp.json();
+
+        // Check for embedded OData errors
+        if (data.error) {
+          const errorCode = data.error.code;
+          const errorMessage = data.error.message || "Unknown OData error";
+
+          // Check for schema locked error (code 303)
+          if (errorCode === "303" || errorCode === 303) {
+            return {
+              data: undefined,
+              error: new SchemaLockedError(fullUrl, errorMessage, data.error),
+            };
+          }
+
+          return {
+            data: undefined,
+            error: new ODataError(fullUrl, errorMessage, errorCode, data.error),
+          };
+        }
+
+        return { data: data as T, error: undefined };
       }
-      return data as T;
+
+      return { data: (await resp.text()) as T, error: undefined };
+    } catch (err) {
+      // Map ffetch errors - return them directly (no re-wrapping)
+      if (
+        err instanceof TimeoutError ||
+        err instanceof AbortError ||
+        err instanceof NetworkError ||
+        err instanceof RetryLimitError ||
+        err instanceof CircuitOpenError
+      ) {
+        return { data: undefined, error: err };
+      }
+
+      // Unknown error - wrap it as NetworkError
+      return {
+        data: undefined,
+        error: new NetworkError(fullUrl, err),
+      };
     }
-    return (await resp.text()) as T;
   }
 
   database<
     const Occurrences extends readonly TableOccurrence<any, any, any, any>[],
   >(
     name: string,
-    config?: { occurrences?: Occurrences },
+    config?: {
+      occurrences?: Occurrences | undefined;
+      useEntityIds?: boolean;
+    },
   ): Database<Occurrences> {
     return new Database(name, this, config);
   }
@@ -108,11 +249,14 @@ export class FileMakerOData implements ExecutionContext {
    * @returns Promise resolving to an array of database names
    */
   async listDatabaseNames(): Promise<string[]> {
-    const response = (await this._makeRequest("/")) as {
+    const result = await this._makeRequest<{
       value?: Array<{ name: string }>;
-    };
-    if (response.value && Array.isArray(response.value)) {
-      return response.value.map((item) => item.name);
+    }>("/");
+    if (result.error) {
+      throw result.error;
+    }
+    if (result.data.value && Array.isArray(result.data.value)) {
+      return result.data.value.map((item) => item.name);
     }
     return [];
   }