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

package/src/client/record-builder.ts

@@ -8,10 +8,12 @@ import type {
 } from "../types";
 import type { TableOccurrence } from "./table-occurrence";
 import type { BaseTable } from "./base-table";
+import { transformTableName, transformResponseFields } from "../transform";
 import { QueryBuilder } from "./query-builder";
 import { validateSingleResponse } from "../validation";
 import { type FFetchOptions } from "@fetchkit/ffetch";
-import { z } from "zod/v4";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+// import type { z } from "zod/v4";
 
 // Helper type to extract schema from a TableOccurrence
 type ExtractSchemaFromOccurrence<O> =
@@ -105,7 +107,7 @@ export class RecordBuilder<
   ): QueryBuilder<
     ExtractSchemaFromOccurrence<
       FindNavigationTarget<Occ, RelationName>
-    > extends Record<string, z.ZodType>
+    > extends Record<string, StandardSchemaV1>
       ? InferSchemaType<
           ExtractSchemaFromOccurrence<FindNavigationTarget<Occ, RelationName>>
         >
@@ -127,9 +129,14 @@ export class RecordBuilder<
       context: this.context,
     });
     // Store the navigation info - we'll use it in execute
+    // Transform relation name to FMTID if using entity IDs
+    const relationId = targetOccurrence
+      ? transformTableName(targetOccurrence)
+      : relationName;
+
     (builder as any).isNavigate = true;
     (builder as any).navigateRecordId = this.recordId;
-    (builder as any).navigateRelation = relationName;
+    (builder as any).navigateRelation = relationId;
 
     // If this RecordBuilder came from a navigated EntitySet, we need to preserve that base path
     if (
@@ -142,7 +149,11 @@ export class RecordBuilder<
       (builder as any).navigateBaseRelation = this.navigateRelation;
     } else {
       // Normal record navigation: /tableName('recordId')/relation
-      (builder as any).navigateSourceTableName = this.tableName;
+      // Transform source table name to FMTID if using entity IDs
+      const sourceTableId = this.occurrence
+        ? transformTableName(this.occurrence)
+        : this.tableName;
+      (builder as any).navigateSourceTableName = sourceTableId;
     }
 
     return builder;
@@ -153,63 +164,74 @@ export class RecordBuilder<
   ): Promise<
     Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>
   > {
-    try {
-      let url: string;
-
-      // Build the base URL depending on whether this came from a navigated EntitySet
-      if (
-        this.isNavigateFromEntitySet &&
-        this.navigateSourceTableName &&
-        this.navigateRelation
-      ) {
-        // From navigated EntitySet: /sourceTable/relation('recordId')
-        url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
-      } else {
-        // Normal record: /tableName('recordId')
-        url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
-      }
-
-      if (this.operation === "getSingleField" && this.operationParam) {
-        url += `/${this.operationParam}`;
-      }
-
-      const response = await this.context._makeRequest(url, options);
-
-      // Handle single field operation
-      if (this.operation === "getSingleField") {
-        // Single field returns a JSON object with @context and value
-        const fieldResponse = response as ODataFieldResponse<T>;
-        return { data: fieldResponse.value as any, error: undefined };
-      }
-
-      // Get schema from occurrence if available
-      const schema = this.occurrence?.baseTable?.schema;
-
-      // Validate the single record response
-      const validation = await validateSingleResponse<any>(
+    let url: string;
+
+    // Build the base URL depending on whether this came from a navigated EntitySet
+    if (
+      this.isNavigateFromEntitySet &&
+      this.navigateSourceTableName &&
+      this.navigateRelation
+    ) {
+      // From navigated EntitySet: /sourceTable/relation('recordId')
+      url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
+    } else {
+      // Normal record: /tableName('recordId') - use FMTID if configured
+      const tableId = this.occurrence
+        ? transformTableName(this.occurrence)
+        : this.tableName;
+      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
+    }
+
+    if (this.operation === "getSingleField" && this.operationParam) {
+      url += `/${this.operationParam}`;
+    }
+
+    const result = await this.context._makeRequest(url, options);
+
+    if (result.error) {
+      return { data: undefined, error: result.error };
+    }
+
+    let response = result.data;
+
+    // Handle single field operation
+    if (this.operation === "getSingleField") {
+      // Single field returns a JSON object with @context and value
+      const fieldResponse = response as ODataFieldResponse<T>;
+      return { data: fieldResponse.value as any, error: undefined };
+    }
+
+    // Transform response field IDs back to names if using entity IDs
+    if (this.occurrence?.baseTable) {
+      response = transformResponseFields(
         response,
-        schema,
-        undefined, // No selected fields for record.get()
-        undefined, // No expand configs
-        "exact", // Expect exactly one record
+        this.occurrence.baseTable,
+        undefined, // No expand configs for simple get
       );
+    }
+
+    // Get schema from occurrence if available
+    const schema = this.occurrence?.baseTable?.schema;
+
+    // Validate the single record response
+    const validation = await validateSingleResponse<any>(
+      response,
+      schema,
+      undefined, // No selected fields for record.get()
+      undefined, // No expand configs
+      "exact", // Expect exactly one record
+    );
 
-      if (!validation.valid) {
-        return { data: undefined, error: validation.error };
-      }
-
-      // Handle null response
-      if (validation.data === null) {
-        return { data: null as any, error: undefined };
-      }
-
-      return { data: validation.data, error: undefined };
-    } catch (error) {
-      return {
-        data: undefined,
-        error: error instanceof Error ? error : new Error(String(error)),
-      };
+    if (!validation.valid) {
+      return { data: undefined, error: validation.error };
     }
+
+    // Handle null response
+    if (validation.data === null) {
+      return { data: null as any, error: undefined };
+    }
+
+    return { data: validation.data, error: undefined };
   }
 
   getRequestConfig(): { method: string; url: string; body?: any } {
@@ -224,8 +246,11 @@ export class RecordBuilder<
       // From navigated EntitySet: /sourceTable/relation('recordId')
       url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
     } else {
-      // Normal record: /tableName('recordId')
-      url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
+      // Normal record: /tableName('recordId') - use FMTID if configured
+      const tableId = this.occurrence
+        ? transformTableName(this.occurrence)
+        : this.tableName;
+      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
     }
 
     if (this.operation === "getSingleField" && this.operationParam) {

package/src/client/table-occurrence.ts

@@ -1,4 +1,4 @@
-import { BaseTable } from "./base-table";
+import { BaseTable, BaseTableWithIds } from "./base-table";
 
 // Helper type to extract schema from BaseTable
 type ExtractSchema<BT> =
@@ -48,10 +48,9 @@ export class TableOccurrence<
 > {
   public readonly name: Name;
   public readonly baseTable: BT;
-  private _navigationConfig: Nav;
+  protected _navigationConfig: Nav;
   public readonly navigation: ResolveNavigation<Nav>;
   public readonly defaultSelect: DefSelect;
-
   constructor(config: {
     readonly name: Name;
     readonly baseTable: BT;
@@ -62,7 +61,6 @@ export class TableOccurrence<
     this.baseTable = config.baseTable;
     this._navigationConfig = (config.navigation ?? {}) as Nav;
     this.defaultSelect = (config.defaultSelect ?? "schema") as DefSelect;
-
     // Create navigation getters that lazily resolve functions
     this.navigation = createNavigationGetters(this._navigationConfig);
   }
@@ -81,6 +79,32 @@ export class TableOccurrence<
       defaultSelect: this.defaultSelect,
     });
   }
+
+  /**
+   * Returns the FileMaker table occurrence ID (FMTID) if available, or the table name.
+   * @returns The FMTID string or the table name
+   */
+  getTableId(): string {
+    // Check if fmtId exists (only on TableOccurrenceWithIds)
+    return "fmtId" in this && (this as any).fmtId
+      ? (this as any).fmtId
+      : this.name;
+  }
+
+  /**
+   * Returns the table occurrence name.
+   * @returns The table name
+   */
+  getTableName(): string {
+    return this.name;
+  }
+
+  /**
+   * Returns true if this TableOccurrence is using FileMaker table occurrence IDs.
+   */
+  isUsingTableId(): boolean {
+    return "fmtId" in this && this.fmtId !== undefined;
+  }
 }
 
 // Helper function to create TableOccurrence with proper type inference
@@ -98,3 +122,93 @@ export function createTableOccurrence<
 }): TableOccurrence<BT, Name, {}, DefSelect> {
   return new TableOccurrence(config);
 }
+
+// Helper type to validate that all navigation values are TableOccurrenceWithIds
+type ValidateNavWithIds<Nav> =
+  Nav extends Record<
+    string,
+    | TableOccurrenceWithIds<any, any, any, any>
+    | (() => TableOccurrenceWithIds<any, any, any, any>)
+  >
+    ? Nav
+    : "Error: All navigation table occurrences must be TableOccurrenceWithIds when using TableOccurrenceWithIds";
+
+/**
+ * TableOccurrenceWithIds extends TableOccurrence to require:
+ * 1. A BaseTableWithIds (which has fmfIds defined)
+ * 2. A required fmtId for this table occurrence
+ * 3. All navigation relationships must also be TableOccurrenceWithIds
+ *
+ * This ensures bidirectional type-level enforcement: if you use FileMaker IDs,
+ * they must be defined on both the BaseTable (fmfIds) and TableOccurrence (fmtId),
+ * and all related table occurrences in navigation must also have IDs.
+ *
+ * @template BT - Must be a BaseTableWithIds (enforced at type level)
+ * @template Name - The name of this table occurrence
+ * @template Nav - Navigation relationships (must all be TableOccurrenceWithIds)
+ * @template DefSelect - Default select behavior
+ *
+ * @example
+ * ```ts
+ * const usersBaseWithIds = new BaseTableWithIds({
+ *   schema: { id: z.string(), name: z.string() },
+ *   idField: "id",
+ *   fmfIds: { id: "FMFID:1", name: "FMFID:2" },
+ * });
+ *
+ * const usersTO = new TableOccurrenceWithIds({
+ *   name: "users",
+ *   baseTable: usersBaseWithIds,
+ *   fmtId: "FMTID:100",
+ *   navigation: {
+ *     contacts: () => contactsTO, // Must also be TableOccurrenceWithIds
+ *   },
+ * });
+ * ```
+ */
+export class TableOccurrenceWithIds<
+  BT extends BaseTableWithIds<any, any, any, any> = any,
+  Name extends string = string,
+  Nav extends Record<
+    string,
+    | TableOccurrence<any, any, any, any>
+    | (() => TableOccurrence<any, any, any, any>)
+  > = {},
+  DefSelect extends
+    | "all"
+    | "schema"
+    | readonly (keyof ExtractSchema<BT>)[] = "schema",
+> extends TableOccurrence<BT, Name, Nav, DefSelect> {
+  public readonly fmtId: `FMTID:${string}`;
+
+  constructor(config: {
+    readonly name: Name;
+    readonly baseTable: BT;
+    readonly fmtId: `FMTID:${string}`;
+    readonly navigation?: ValidateNavWithIds<Nav>;
+    readonly defaultSelect?: DefSelect;
+  }) {
+    super({
+      ...config,
+      navigation: config.navigation as Nav,
+    });
+    this.fmtId = config.fmtId;
+  }
+}
+
+// Helper function to create TableOccurrenceWithIds with proper type inference
+export function createTableOccurrenceWithIds<
+  const Name extends string,
+  BT extends BaseTableWithIds<any, any, any, any>,
+  DefSelect extends
+    | "all"
+    | "schema"
+    | readonly (keyof ExtractSchema<BT>)[] = "schema",
+>(config: {
+  name: Name;
+  baseTable: BT;
+  fmtId: `FMTID:${string}`;
+  defaultSelect?: DefSelect;
+}): TableOccurrenceWithIds<BT, Name, {}, DefSelect> {
+  return new TableOccurrenceWithIds(config);
+}

package/src/client/update-builder.ts

@@ -8,6 +8,10 @@ import type { TableOccurrence } from "./table-occurrence";
 import type { BaseTable } from "./base-table";
 import { QueryBuilder } from "./query-builder";
 import { type FFetchOptions } from "@fetchkit/ffetch";
+import {
+  transformFieldNamesToIds,
+  transformTableName,
+} from "../transform";
 
 /**
  * Initial update builder returned from EntitySet.update(data)
@@ -134,79 +138,103 @@ export class ExecutableUpdateBuilder<
   async execute(
     options?: RequestInit & FFetchOptions,
   ): Promise<Result<{ updatedCount: number }>> {
-    try {
-      let url: string;
-
-      if (this.mode === "byId") {
-        // Update single record by ID: PATCH /{database}/{table}('id')
-        url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
-      } else {
-        // Update by filter: PATCH /{database}/{table}?$filter=...
-        if (!this.queryBuilder) {
-          throw new Error("Query builder is required for filter-based update");
-        }
-
-        // 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}`)
+    // Transform table name to FMTID if using entity IDs
+    const tableId = this.occurrence
+      ? transformTableName(this.occurrence)
+      : this.tableName;
+
+    // Transform field names to FMFIDs if using entity IDs
+    const transformedData = this.occurrence?.baseTable
+      ? transformFieldNamesToIds(this.data, this.occurrence.baseTable)
+      : this.data;
+
+    let url: string;
+
+    if (this.mode === "byId") {
+      // Update single record by ID: PATCH /{database}/{table}('id')
+      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
+    } else {
+      // Update by filter: PATCH /{database}/{table}?$filter=...
+      if (!this.queryBuilder) {
+        throw new Error("Query builder is required for filter-based update");
+      }
+
+      // Get the query string from the configured QueryBuilder
+      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 queryParams = queryString.startsWith(`/${tableId}`)
+        ? queryString.slice(`/${tableId}`.length)
+        : queryString.startsWith(`/${this.tableName}`)
           ? queryString.slice(`/${this.tableName}`.length)
           : queryString;
 
-        url = `/${this.databaseName}/${this.tableName}${queryParams}`;
-      }
+      url = `/${this.databaseName}/${tableId}${queryParams}`;
+    }
 
-      // Make PATCH request with JSON body
-      const response = await this.context._makeRequest(url, {
-        method: "PATCH",
-        headers: {
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify(this.data),
-        ...options,
-      });
-
-      // Both byId and byFilter return affected row count
-      let updatedCount = 0;
-
-      if (typeof response === "number") {
-        updatedCount = response;
-      } else if (response && typeof response === "object") {
-        // Check if the response has a count property (fallback)
-        updatedCount = (response as any).updatedCount || 0;
-      }
+    // Make PATCH request with JSON body
+    const result = await this.context._makeRequest(url, {
+      method: "PATCH",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(transformedData),
+      ...options,
+    });
+
+    if (result.error) {
+      return { data: undefined, error: result.error };
+    }
+
+    const response = result.data;
 
-      return { data: { updatedCount }, error: undefined };
-    } catch (error) {
-      return {
-        data: undefined,
-        error: error instanceof Error ? error : new Error(String(error)),
-      };
+    // Both byId and byFilter return affected row count
+    let updatedCount = 0;
+
+    if (typeof response === "number") {
+      updatedCount = response;
+    } else if (response && typeof response === "object") {
+      // Check if the response has a count property (fallback)
+      updatedCount = (response as any).updatedCount || 0;
     }
+
+    return { data: { updatedCount }, error: undefined };
   }
 
   getRequestConfig(): { method: string; url: string; body?: any } {
+    // Transform table name to FMTID if using entity IDs
+    const tableId = this.occurrence
+      ? transformTableName(this.occurrence)
+      : this.tableName;
+
+    // Transform field names to FMFIDs if using entity IDs
+    const transformedData = this.occurrence?.baseTable
+      ? transformFieldNamesToIds(this.data, this.occurrence.baseTable)
+      : this.data;
+
     let url: string;
 
     if (this.mode === "byId") {
-      url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
+      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
     } else {
       if (!this.queryBuilder) {
         throw new Error("Query builder is required for filter-based update");
       }
 
       const queryString = this.queryBuilder.getQueryString();
-      const queryParams = queryString.startsWith(`/${this.tableName}`)
-        ? queryString.slice(`/${this.tableName}`.length)
-        : queryString;
+      const queryParams = queryString.startsWith(`/${tableId}`)
+        ? queryString.slice(`/${tableId}`.length)
+        : queryString.startsWith(`/${this.tableName}`)
+          ? queryString.slice(`/${this.tableName}`.length)
+          : queryString;
 
-      url = `/${this.databaseName}/${this.tableName}${queryParams}`;
+      url = `/${this.databaseName}/${tableId}${queryParams}`;
     }
 
     return {
       method: "PATCH",
       url,
-      body: JSON.stringify(this.data),
+      body: JSON.stringify(transformedData),
     };
   }
 }