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

package/src/client/database.ts

@@ -1,10 +1,40 @@
-import { z } from "zod/v4";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { ExecutionContext } from "../types";
 import type { BaseTable } from "./base-table";
 import type { TableOccurrence } from "./table-occurrence";
 import { EntitySet } from "./entity-set";
 
+// Type-level validation: Check if a TableOccurrence has fmtId (is TableOccurrenceWithIds)
+type HasFmtId<T> = T extends { fmtId: string } ? true : false;
+
+// Check if all occurrences in a tuple have fmtId
+type AllHaveFmtId<Occurrences extends readonly any[]> =
+  Occurrences extends readonly [infer First, ...infer Rest]
+    ? HasFmtId<First> extends true
+      ? Rest extends readonly []
+        ? true
+        : AllHaveFmtId<Rest>
+      : false
+    : true; // empty array is valid
+
+// Check if none have fmtId
+type NoneHaveFmtId<Occurrences extends readonly any[]> =
+  Occurrences extends readonly [infer First, ...infer Rest]
+    ? HasFmtId<First> extends false
+      ? Rest extends readonly []
+        ? true
+        : NoneHaveFmtId<Rest>
+      : false
+    : true; // empty array is valid
+
+// Valid if all have fmtId or none have fmtId (no mixing allowed)
+export type ValidOccurrenceMix<Occurrences extends readonly any[]> =
+  AllHaveFmtId<Occurrences> extends true
+    ? true
+    : NoneHaveFmtId<Occurrences> extends true
+      ? true
+      : false;
+
 // Helper type to extract schema from a TableOccurrence
 type ExtractSchemaFromOccurrence<O> =
   O extends TableOccurrence<infer BT, any, any, any>
@@ -44,30 +74,88 @@ export class Database<
   >[] = readonly [],
 > {
   private occurrenceMap: Map<string, TableOccurrence<any, any, any, any>>;
+  private _useEntityIds: boolean = false;
 
   constructor(
     private readonly databaseName: string,
     private readonly context: ExecutionContext,
-    config?: { occurrences?: Occurrences },
+    config?: {
+      occurrences?: ValidOccurrenceMix<Occurrences> extends true
+        ? Occurrences
+        : Occurrences & {
+            __type_error__: "❌ Cannot mix TableOccurrence with and without entity IDs. Either all occurrences must use TableOccurrenceWithIds (with fmtId and fmfIds) or all must be regular TableOccurrence.";
+          };
+    },
   ) {
     this.occurrenceMap = new Map();
     if (config?.occurrences) {
+      // Validate consistency: either all occurrences use entity IDs or none do
+      const occurrencesWithIds: string[] = [];
+      const occurrencesWithoutIds: string[] = [];
+
       for (const occ of config.occurrences) {
         this.occurrenceMap.set(occ.name, occ);
+
+        const hasTableId = occ.isUsingTableId();
+        const hasFieldIds = occ.baseTable.isUsingFieldIds();
+
+        // An occurrence uses entity IDs if it has both fmtId and fmfIds
+        if (hasTableId && hasFieldIds) {
+          occurrencesWithIds.push(occ.name);
+          this._useEntityIds = true;
+        } else if (!hasTableId && !hasFieldIds) {
+          occurrencesWithoutIds.push(occ.name);
+        } else {
+          // Partial entity ID usage (only one of fmtId or fmfIds) - this is an error
+          throw new Error(
+            `TableOccurrence "${occ.name}" has inconsistent entity ID configuration. ` +
+              `Both fmtId (${hasTableId ? "present" : "missing"}) and fmfIds (${hasFieldIds ? "present" : "missing"}) must be defined together.`,
+          );
+        }
       }
+
+      // Check for mixed usage
+      if (occurrencesWithIds.length > 0 && occurrencesWithoutIds.length > 0) {
+        throw new Error(
+          `Cannot mix TableOccurrence instances with and without entity IDs in the same database. ` +
+            `Occurrences with entity IDs: [${occurrencesWithIds.join(", ")}]. ` +
+            `Occurrences without entity IDs: [${occurrencesWithoutIds.join(", ")}]. ` +
+            `Either all table occurrences must use entity IDs (fmtId + fmfIds) or none should.`,
+        );
+      }
+    }
+
+    // Inform the execution context whether to use entity IDs
+    if (this.context._setUseEntityIds) {
+      this.context._setUseEntityIds(this._useEntityIds);
     }
   }
 
+  /**
+   * Returns true if any table occurrence in this database is using entity IDs.
+   */
+  isUsingEntityIds(): boolean {
+    return this._useEntityIds;
+  }
+
+  /**
+   * Gets a table occurrence by name.
+   * @internal
+   */
+  getOccurrence(name: string): TableOccurrence<any, any, any, any> | undefined {
+    return this.occurrenceMap.get(name);
+  }
+
   from<Name extends ExtractOccurrenceNames<Occurrences> | (string & {})>(
     name: Name,
   ): Occurrences extends readonly []
-    ? EntitySet<Record<string, z.ZodTypeAny>, undefined>
+    ? EntitySet<Record<string, StandardSchemaV1>, undefined>
     : Name extends ExtractOccurrenceNames<Occurrences>
       ? EntitySet<
           ExtractSchemaFromOccurrence<FindOccurrenceByName<Occurrences, Name>>,
           FindOccurrenceByName<Occurrences, Name>
         >
-      : EntitySet<Record<string, z.ZodTypeAny>, undefined> {
+      : EntitySet<Record<string, StandardSchemaV1>, undefined> {
     const occurrence = this.occurrenceMap.get(name as string);
 
     if (occurrence) {
@@ -80,20 +168,28 @@ export class Database<
         tableName: name as string,
         databaseName: this.databaseName,
         context: this.context,
+        database: this as any,
       }) as any;
     } else {
       // Return untyped EntitySet for dynamic table access
-      return new EntitySet<Record<string, z.ZodTypeAny>, undefined>({
+      return new EntitySet<Record<string, StandardSchemaV1>, undefined>({
         tableName: name as string,
         databaseName: this.databaseName,
         context: this.context,
+        database: this as any,
       }) as any;
     }
   }
 
   // Example method showing how to use the request method
   async getMetadata() {
-    return this.context._makeRequest(`/${this.databaseName}/$metadata`);
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/$metadata`,
+    );
+    if (result.error) {
+      throw result.error;
+    }
+    return result.data;
   }
 
   /**
@@ -101,13 +197,14 @@ export class Database<
    * @returns Promise resolving to an array of table names
    */
   async listTableNames(): Promise<string[]> {
-    const response = (await this.context._makeRequest(
-      `/${this.databaseName}`,
-    )) as {
+    const result = await this.context._makeRequest<{
       value?: Array<{ name: string }>;
-    };
-    if (response.value && Array.isArray(response.value)) {
-      return response.value.map((item) => item.name);
+    }>(`/${this.databaseName}`);
+    if (result.error) {
+      throw result.error;
+    }
+    if (result.data.value && Array.isArray(result.data.value)) {
+      return result.data.value.map((item) => item.name);
     }
     return [];
   }
@@ -136,7 +233,7 @@ export class Database<
       body.scriptParameterValue = options.scriptParam;
     }
 
-    const response = await this.context._makeRequest<{
+    const result = await this.context._makeRequest<{
       scriptResult: {
         code: number;
         resultParameter?: string;
@@ -146,6 +243,12 @@ export class Database<
       body: Object.keys(body).length > 0 ? JSON.stringify(body) : undefined,
     });
 
+    if (result.error) {
+      throw result.error;
+    }
+
+    const response = result.data;
+
     // If resultSchema is provided, validate the result through it
     if (options?.resultSchema && response.scriptResult !== undefined) {
       const validationResult = options.resultSchema["~standard"].validate(

package/src/client/delete-builder.ts

@@ -118,53 +118,52 @@ export class ExecutableDeleteBuilder<T extends Record<string, any>>
   async execute(
     options?: RequestInit & FFetchOptions,
   ): Promise<Result<{ deletedCount: number }>> {
-    try {
-      let url: string;
-
-      if (this.mode === "byId") {
-        // Delete single record by ID: DELETE /{database}/{table}('id')
-        url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
-      } else {
-        // Delete by filter: DELETE /{database}/{table}?$filter=...
-        if (!this.queryBuilder) {
-          throw new Error("Query builder is required for filter-based delete");
-        }
-
-        // Get the query string from the configured QueryBuilder
-        const queryString = this.queryBuilder.getQueryString();
-        // Remove the leading "/" from the query string as we'll build our own URL
-        const queryParams = queryString.startsWith(`/${this.tableName}`)
-          ? queryString.slice(`/${this.tableName}`.length)
-          : queryString;
-
-        url = `/${this.databaseName}/${this.tableName}${queryParams}`;
-      }
+    let url: string;
 
-      // Make DELETE request
-      const response = await this.context._makeRequest(url, {
-        method: "DELETE",
-        ...options,
-      });
-
-      // OData returns 204 No Content with fmodata.affected_rows header
-      // The _makeRequest should handle extracting the header value
-      // For now, we'll check if response contains the count
-      let deletedCount = 0;
-
-      if (typeof response === "number") {
-        deletedCount = response;
-      } else if (response && typeof response === "object") {
-        // Check if the response has a count property (fallback)
-        deletedCount = (response as any).deletedCount || 0;
+    if (this.mode === "byId") {
+      // Delete single record by ID: DELETE /{database}/{table}('id')
+      url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
+    } else {
+      // Delete by filter: DELETE /{database}/{table}?$filter=...
+      if (!this.queryBuilder) {
+        throw new Error("Query builder is required for filter-based delete");
       }
 
-      return { data: { deletedCount }, error: undefined };
-    } catch (error) {
-      return {
-        data: undefined,
-        error: error instanceof Error ? error : new Error(String(error)),
-      };
+      // Get the query string from the configured QueryBuilder
+      const queryString = this.queryBuilder.getQueryString();
+      // Remove the leading "/" from the query string as we'll build our own URL
+      const queryParams = queryString.startsWith(`/${this.tableName}`)
+        ? queryString.slice(`/${this.tableName}`.length)
+        : queryString;
+
+      url = `/${this.databaseName}/${this.tableName}${queryParams}`;
+    }
+
+    // Make DELETE request
+    const result = await this.context._makeRequest(url, {
+      method: "DELETE",
+      ...options,
+    });
+
+    if (result.error) {
+      return { data: undefined, error: result.error };
     }
+
+    const response = result.data;
+
+    // OData returns 204 No Content with fmodata.affected_rows header
+    // The _makeRequest should handle extracting the header value
+    // For now, we'll check if response contains the count
+    let deletedCount = 0;
+
+    if (typeof response === "number") {
+      deletedCount = response;
+    } else if (response && typeof response === "object") {
+      // Check if the response has a count property (fallback)
+      deletedCount = (response as any).deletedCount || 0;
+    }
+
+    return { data: { deletedCount }, error: undefined };
   }
 
   getRequestConfig(): { method: string; url: string; body?: any } {

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";
@@ -59,19 +59,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
@@ -85,20 +85,21 @@ type GetTargetSchemaType<
   TableOccurrence<infer BT, any, any, any>,
 ]
   ? [BT] extends [BaseTable<infer S, any>]
-    ? [S] extends [Record<string, z.ZodType>]
+    ? [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?: any; // Database instance for accessing occurrences
   private isNavigateFromEntitySet?: boolean;
   private navigateRelation?: string;
   private navigateSourceTableName?: string;
@@ -108,30 +109,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?: any;
   }): EntitySet<OccurrenceSchema, Occ> {
     return new EntitySet<OccurrenceSchema, Occ>({
       occurrence: config.occurrence,
       tableName: config.tableName,
       databaseName: config.databaseName,
       context: config.context,
+      database: config.database,
     });
   }
 
@@ -280,15 +290,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 { Database } from "./database";
+import createClient, {
+  FFetchOptions,
+  TimeoutError,
+  AbortError,
+  NetworkError,
+  RetryLimitError,
+  CircuitOpenError,
+} from "@fetchkit/ffetch";
+import type { Auth, ExecutionContext, Result } from "../types";
+import { HTTPError, ODataError } from "../errors";
+import { Database, type ValidOccurrenceMix } from "./database";
 import { TableOccurrence } from "./table-occurrence";
 
 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,31 @@ export class FMServerConnection 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
    */
   async _makeRequest<T>(
     url: string,
     options?: RequestInit & FFetchOptions,
-  ): Promise<T> {
+  ): Promise<Result<T>> {
     const baseUrl = `${this.serverUrl}${"apiKey" in this.auth ? `/otto` : ""}/fmi/odata/v4`;
+    const fullUrl = baseUrl + url;
 
     const headers = {
       Authorization:
@@ -43,6 +69,7 @@ export class FMServerConnection implements ExecutionContext {
           : `Basic ${btoa(`${this.auth.username}:${this.auth.password}`)}`,
       "Content-Type": "application/json",
       Accept: "application/json",
+      ...(this.useEntityIds ? { Prefer: "fmodata.entity-ids" } : {}),
       ...(options?.headers || {}),
     };
 
@@ -61,44 +88,112 @@ export class FMServerConnection implements ExecutionContext {
       ? createClient({ retries: 0, fetchHandler })
       : this.fetchClient;
 
-    const resp = await clientToUse(baseUrl + url, {
-      ...restOptions,
-      headers,
-    });
+    try {
+      const resp = await clientToUse(fullUrl, {
+        ...restOptions,
+        headers,
+      });
 
-    if (!resp.ok) {
-      throw new Error(
-        `Failed to make request to ${baseUrl + url}: ${resp.statusText}`,
-      );
-    }
+      // 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
+        }
 
-    // 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;
-    }
+        // Check if it's an OData error response
+        if (errorBody?.error) {
+          return {
+            data: undefined,
+            error: new ODataError(
+              fullUrl,
+              errorBody.error.message || resp.statusText,
+              errorBody.error.code,
+              errorBody.error,
+            ),
+          };
+        }
 
-    // Handle 204 No Content with no body
-    if (resp.status === 204) {
-      return 0 as T;
-    }
+        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 };
+      }
 
-    if (resp.headers.get("content-type")?.includes("application/json")) {
-      let data = await resp.json();
-      if (data.error) {
-        throw new Error(data.error);
+      // Handle 204 No Content with no body
+      if (resp.status === 204) {
+        return { data: 0 as T, error: undefined };
       }
-      return data as T;
+
+      // Parse response
+      if (resp.headers.get("content-type")?.includes("application/json")) {
+        const data = await resp.json();
+
+        // Check for embedded OData errors
+        if (data.error) {
+          return {
+            data: undefined,
+            error: new ODataError(
+              fullUrl,
+              data.error.message || "Unknown OData error",
+              data.error.code,
+              data.error,
+            ),
+          };
+        }
+
+        return { data: data as T, error: undefined };
+      }
+
+      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?: ValidOccurrenceMix<Occurrences> extends true
+        ? Occurrences
+        : Occurrences & {
+            __type_error__: "❌ Cannot mix TableOccurrence with and without entity IDs. Either all occurrences must use TableOccurrenceWithIds (with fmtId and fmfIds) or all must be regular TableOccurrence.";
+          };
+    },
   ): Database<Occurrences> {
     return new Database(name, this, config);
   }
@@ -108,11 +203,14 @@ export class FMServerConnection 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 [];
   }