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

package/README.md

@@ -6,6 +6,7 @@ A strongly-typed FileMaker OData API client.
 
 Roadmap:
 
+- [ ] Crossjoin support
 - [ ] Batch operations
 - [ ] Proper docs at proofkit.dev
 - [ ] @proofkit/typegen integration
@@ -140,9 +141,9 @@ const contactsBase = new BaseTable({
     phone: z.string().optional(),
     createdAt: z.string(),
   },
-  idField: "id", // The primary key field
-  insertRequired: ["name", "email"], // optional: fields that are required on insert
-  updateRequired: ["email"], // optional: fields that are required on update
+  idField: "id", // The primary key field (automatically read-only)
+  required: ["phone"], // optional: additional required fields for insert (beyond auto-inferred)
+  readOnly: ["createdAt"], // optional: fields excluded from insert/update
 });
 ```
 
@@ -524,27 +525,30 @@ if (result.data) {
 }
 ```
 
-If you specify `insertRequired` fields in your base table, those fields become required:
+Fields are automatically required for insert if their validator doesn't allow `null` or `undefined`. You can specify additional required fields:
 
 ```typescript
 const usersBase = new BaseTable({
   schema: {
-    id: z.string(),
-    username: z.string(),
-    email: z.string(),
-    createdAt: z.string().optional(),
+    id: z.string(), // Auto-required (not nullable), but excluded from insert (idField)
+    username: z.string(), // Auto-required (not nullable)
+    email: z.string(), // Auto-required (not nullable)
+    phone: z.string().nullable(), // Optional by default
+    createdAt: z.string(), // Auto-required, but excluded (readOnly)
   },
-  idField: "id",
-  insertRequired: ["username", "email"], // These fields are required on insert
+  idField: "id", // Automatically excluded from insert/update
+  required: ["phone"], // Make phone required for inserts despite being nullable
+  readOnly: ["createdAt"], // Exclude from insert/update operations
 });
 
-// TypeScript will enforce that username and email are provided
+// TypeScript enforces: username, email, and phone are required
+// TypeScript excludes: id and createdAt cannot be provided
 const result = await db
   .from("users")
   .insert({
     username: "johndoe",
     email: "john@example.com",
-    // createdAt is optional
+    phone: "+1234567890", // Required because specified in 'required' array
   })
   .execute();
 ```
@@ -839,43 +843,97 @@ db.from("users")
   .filter({ invalid: { eq: "john" } }); // TS Error
 ```
 
-### Required Fields
+### Required and Read-Only Fields
 
-Control which fields are required for insert and update operations:
+The library automatically infers which fields are required based on whether their validator allows `null` or `undefined`:
 
 ```typescript
 const usersBase = new BaseTable({
   schema: {
-    id: z.string(),
-    username: z.string(),
-    email: z.string(),
-    status: z.string(),
-    updatedAt: z.string().optional(),
+    id: z.string(), // Auto-required, auto-readOnly (idField)
+    username: z.string(), // Auto-required (not nullable)
+    email: z.string(), // Auto-required (not nullable)
+    status: z.string().nullable(), // Optional (nullable)
+    createdAt: z.string(), // Read-only system field
+    updatedAt: z.string().nullable(), // Optional
   },
-  idField: "id",
-  insertRequired: ["username", "email"], // Required on insert
-  updateRequired: ["status"], // Required on update
+  idField: "id", // Automatically excluded from insert/update
+  required: ["status"], // Make status required despite being nullable
+  readOnly: ["createdAt"], // Exclude createdAt from insert/update
 });
 
-// Insert requires username and email
+// Insert: username, email, and status are required
+// Insert: id and createdAt are excluded (cannot be provided)
 db.from("users").insert({
   username: "john",
   email: "john@example.com",
-  // updatedAt is optional
+  status: "active", // Required due to 'required' array
+  updatedAt: new Date().toISOString(), // Optional
 });
 
-// Update requires status
+// Update: all fields are optional except id and createdAt are excluded
 db.from("users")
   .update({
-    status: "active",
-    // other fields are optional
+    status: "active", // Optional
+    // id and createdAt cannot be modified
   })
   .byId("user-123");
 ```
 
+**Key Features:**
+
+- **Auto-inference:** Non-nullable fields are automatically required for insert
+- **Additional requirements:** Use `required` to make nullable fields required for new records
+- **Read-only fields:** Use `readOnly` to exclude fields from insert/update (e.g., timestamps)
+- **Automatic ID exclusion:** The `idField` is always read-only without needing to specify it
+- **Update flexibility:** All fields are optional for updates (except read-only fields)
+
+### Prefer: fmodata.entity-ids
+
+This library supports using FileMaker's internal field identifiers (FMFID) and table occurrence identifiers (FMTID) instead of names. This protects your integration from both field and table occurrence name changes.
+
+To enable this feature, simply define your schema with the `BaseTableWithIds` and `TableOccurrenceWithIds` classes. Behind the scenes, the library will transform your request and the response back to the names you specify in these schemas. This is an all-or-nothing feature. For it to work properly, you must define all table occurrences passed to a `Database` with the `TableOccurrenceWithIds` class.
+
+_Note for OttoFMS proxy: This feature requires version 4.14 or later of OttoFMS_
+
+How do I find these ids? They can be found in the XML version of the `$metadata` endpoint for your database, or you can calculate them using these [custom functions](https://github.com/rwu2359/CFforID) from John Renfrew
+
+#### Basic Usage
+
+```typescript
+import { BaseTableWithIds, TableOccurrenceWithIds } from "@proofkit/fmodata";
+import { z } from "zod/v4";
+
+// Define a base table with FileMaker field IDs
+const usersBase = new BaseTableWithIds({
+  schema: {
+    id: z.string(),
+    username: z.string(),
+    email: z.string().nullable(),
+    createdAt: z.string(),
+  },
+  idField: "id",
+  fmfIds: {
+    id: "FMFID:12039485",
+    username: "FMFID:34323433",
+    email: "FMFID:12232424",
+    createdAt: "FMFID:43234355",
+  },
+});
+
+// Create a table occurrence with a FileMaker table occurrence ID
+const usersTO = new TableOccurrenceWithIds({
+  name: "users",
+  baseTable: usersBase, // Must be a BaseTableWithIds
+  fmtId: "FMTID:12432533",
+});
+```
+
 ### Error Handling
 
-All operations return a `Result` type with either `data` or `error`:
+All operations return a `Result` type with either `data` or `error`. The library provides rich error types that help you handle different error scenarios appropriately.
+
+#### Basic Error Checking
 
 ```typescript
 const result = await db.from("users").list().execute();
@@ -890,6 +948,277 @@ if (result.data) {
 }
 ```
 
+#### HTTP Errors
+
+Handle HTTP status codes (4xx, 5xx) with the `HTTPError` class:
+
+```typescript
+import { HTTPError, isHTTPError } from "@proofkit/fmodata";
+
+const result = await db.from("users").list().execute();
+
+if (result.error) {
+  if (isHTTPError(result.error)) {
+    // TypeScript knows this is HTTPError
+    console.log("HTTP Status:", result.error.status);
+
+    if (result.error.isNotFound()) {
+      console.log("Resource not found");
+    } else if (result.error.isUnauthorized()) {
+      console.log("Authentication required");
+    } else if (result.error.is5xx()) {
+      console.log("Server error - try again later");
+    } else if (result.error.is4xx()) {
+      console.log("Client error:", result.error.statusText);
+    }
+
+    // Access the response body if available
+    if (result.error.response) {
+      console.log("Error details:", result.error.response);
+    }
+  }
+}
+```
+
+#### Network Errors
+
+Handle network-level errors (timeouts, connection issues, etc.):
+
+```typescript
+import {
+  TimeoutError,
+  NetworkError,
+  RetryLimitError,
+  CircuitOpenError,
+} from "@proofkit/fmodata";
+
+const result = await db.from("users").list().execute();
+
+if (result.error) {
+  if (result.error instanceof TimeoutError) {
+    console.log("Request timed out");
+    // Show user-friendly timeout message
+  } else if (result.error instanceof NetworkError) {
+    console.log("Network connectivity issue");
+    // Show offline message
+  } else if (result.error instanceof RetryLimitError) {
+    console.log("Request failed after retries");
+    // Log the underlying error: result.error.cause
+  } else if (result.error instanceof CircuitOpenError) {
+    console.log("Service is currently unavailable");
+    // Show maintenance message
+  }
+}
+```
+
+#### Validation Errors
+
+When schema validation fails, you get a `ValidationError` with rich context:
+
+```typescript
+import { ValidationError, isValidationError } from "@proofkit/fmodata";
+
+const result = await db.from("users").list().execute();
+
+if (result.error) {
+  if (isValidationError(result.error)) {
+    // Access validation issues (Standard Schema format)
+    console.log("Validation failed for field:", result.error.field);
+    console.log("Issues:", result.error.issues);
+    console.log("Failed value:", result.error.value);
+  }
+}
+```
+
+**Validator-Agnostic Error Handling**
+
+The library uses [Standard Schema](https://github.com/standard-schema/standard-schema) to support any validation library (Zod, Valibot, ArkType, etc.). Following the same pattern as [uploadthing](https://github.com/pingdotgg/uploadthing), the `ValidationError.cause` property contains the normalized Standard Schema issues array:
+
+```typescript
+import { ValidationError } from "@proofkit/fmodata";
+
+const result = await db.from("users").list().execute();
+
+if (result.error instanceof ValidationError) {
+  // The cause property (ES2022 Error.cause) contains the Standard Schema issues array
+  // This is validator-agnostic and works with Zod, Valibot, ArkType, etc.
+  console.log("Validation issues:", result.error.cause);
+  console.log("Issues are also available directly:", result.error.issues);
+
+  // Both point to the same array
+  console.log(result.error.cause === result.error.issues); // true
+
+  // Access additional context
+  console.log("Failed field:", result.error.field);
+  console.log("Failed value:", result.error.value);
+
+  // Standard Schema issues have a normalized format
+  result.error.issues.forEach((issue) => {
+    console.log("Path:", issue.path);
+    console.log("Message:", issue.message);
+  });
+}
+```
+
+**Why Standard Schema Issues Instead of Original Validator Errors?**
+
+By using Standard Schema's normalized issue format in the `cause` property, the library remains truly validator-agnostic. All validation libraries that implement Standard Schema (Zod, Valibot, ArkType, etc.) produce the same issue structure, making error handling consistent regardless of which validator you choose.
+
+If you need validator-specific error formatting, you can still access your validator's methods during validation before the data reaches fmodata:
+
+```typescript
+import { z } from "zod";
+
+const userSchema = z.object({
+  email: z.string().email(),
+  age: z.number().min(0).max(150),
+});
+
+// Validate early if you need Zod-specific error handling
+const parseResult = userSchema.safeParse(userData);
+if (!parseResult.success) {
+  // Use Zod's error formatting
+  const formatted = parseResult.error.flatten();
+  console.log("Zod-specific formatting:", formatted);
+}
+```
+
+#### OData Errors
+
+Handle OData-specific protocol errors:
+
+```typescript
+import { ODataError, isODataError } from "@proofkit/fmodata";
+
+const result = await db.from("users").list().execute();
+
+if (result.error) {
+  if (isODataError(result.error)) {
+    console.log("OData Error Code:", result.error.code);
+    console.log("OData Error Message:", result.error.message);
+    console.log("OData Error Details:", result.error.details);
+  }
+}
+```
+
+#### Error Handling Patterns
+
+**Pattern 1: Using instanceof (like ffetch):**
+
+```typescript
+import {
+  HTTPError,
+  ValidationError,
+  TimeoutError,
+  NetworkError,
+} from "@proofkit/fmodata";
+
+const result = await db.from("users").list().execute();
+
+if (result.error) {
+  if (result.error instanceof TimeoutError) {
+    showTimeoutMessage();
+  } else if (result.error instanceof HTTPError) {
+    if (result.error.isNotFound()) {
+      showNotFoundMessage();
+    } else if (result.error.is5xx()) {
+      showServerErrorMessage();
+    }
+  } else if (result.error instanceof ValidationError) {
+    showValidationError(result.error.field, result.error.issues);
+  } else if (result.error instanceof NetworkError) {
+    showOfflineMessage();
+  }
+}
+```
+
+**Pattern 2: Using kind property (for exhaustive matching):**
+
+```typescript
+const result = await db.from("users").list().execute();
+
+if (result.error) {
+  switch (result.error.kind) {
+    case "TimeoutError":
+      showTimeoutMessage();
+      break;
+    case "HTTPError":
+      handleHTTPError(result.error.status);
+      break;
+    case "ValidationError":
+      showValidationError(result.error.field, result.error.issues);
+      break;
+    case "NetworkError":
+      showOfflineMessage();
+      break;
+    case "ODataError":
+      handleODataError(result.error.code);
+      break;
+    // TypeScript ensures exhaustive matching!
+  }
+}
+```
+
+**Pattern 3: Using type guards:**
+
+```typescript
+import {
+  isHTTPError,
+  isValidationError,
+  isODataError,
+  isNetworkError,
+} from "@proofkit/fmodata";
+
+const result = await db.from("users").list().execute();
+
+if (result.error) {
+  if (isHTTPError(result.error)) {
+    // TypeScript knows this is HTTPError
+    console.log("Status:", result.error.status);
+  } else if (isValidationError(result.error)) {
+    // TypeScript knows this is ValidationError
+    console.log("Field:", result.error.field);
+    console.log("Issues:", result.error.issues);
+  } else if (isODataError(result.error)) {
+    // TypeScript knows this is ODataError
+    console.log("Code:", result.error.code);
+  } else if (isNetworkError(result.error)) {
+    // TypeScript knows this is NetworkError
+    console.log("Network issue:", result.error.cause);
+  }
+}
+```
+
+#### Error Properties
+
+All errors include helpful metadata:
+
+```typescript
+if (result.error) {
+  // All errors have a timestamp
+  console.log("Error occurred at:", result.error.timestamp);
+
+  // All errors have a kind property for discriminated unions
+  console.log("Error kind:", result.error.kind);
+
+  // All errors have a message
+  console.log("Error message:", result.error.message);
+}
+```
+
+#### Available Error Types
+
+- **`HTTPError`** - HTTP status errors (4xx, 5xx) with helper methods (`is4xx()`, `is5xx()`, `isNotFound()`, etc.)
+- **`ODataError`** - OData protocol errors with code and details
+- **`ValidationError`** - Schema validation failures with issues, schema reference, and failed value
+- **`ResponseStructureError`** - Malformed API responses
+- **`RecordCountMismatchError`** - When `single()` or `maybeSingle()` expectations aren't met
+- **`TimeoutError`** - Request timeout (from ffetch)
+- **`NetworkError`** - Network connectivity issues (from ffetch)
+- **`RetryLimitError`** - Request failed after retries (from ffetch)
+- **`CircuitOpenError`** - Circuit breaker is open (from ffetch)
+- **`AbortError`** - Request was aborted (from ffetch)
+
 ### OData Annotations and Validation
 
 By default, the library automatically strips OData annotations fields (`@id` and `@editLink`) from responses. If you need these fields, you can include them by passing `includeODataAnnotations: true`:

package/dist/esm/client/base-table.d.ts

@@ -1,13 +1,130 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-export declare class BaseTable<Schema extends Record<string, StandardSchemaV1> = any, IdField extends keyof Schema | undefined = undefined, InsertRequired extends readonly (keyof Schema)[] = readonly [], UpdateRequired extends readonly (keyof Schema)[] = readonly []> {
+/**
+ * BaseTable defines the schema and configuration for a table.
+ *
+ * @template Schema - Record of field names to StandardSchemaV1 validators
+ * @template IdField - The name of the primary key field (optional, automatically read-only)
+ * @template Required - Additional field names to require on insert (beyond auto-inferred required fields)
+ * @template ReadOnly - Field names that cannot be modified via insert/update (idField is automatically read-only)
+ *
+ * @example Basic table with auto-inferred required fields
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const usersTable = new BaseTable({
+ *   schema: {
+ *     id: z.string(),               // Auto-required (not nullable), auto-readOnly (idField)
+ *     name: z.string(),             // Auto-required (not nullable)
+ *     email: z.string().nullable(), // Optional (nullable)
+ *   },
+ *   idField: "id",
+ * });
+ * // On insert: name is required, email is optional (id is excluded - readOnly)
+ * // On update: name and email available (id is excluded - readOnly)
+ * ```
+ *
+ * @example Table with additional required and readOnly fields
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const usersTable = new BaseTable({
+ *   schema: {
+ *     id: z.string(),                    // Auto-required, auto-readOnly (idField)
+ *     createdAt: z.string(),             // Read-only system field
+ *     name: z.string(),                  // Auto-required
+ *     email: z.string().nullable(),      // Optional by default...
+ *     legacyField: z.string().nullable(), // Optional by default...
+ *   },
+ *   idField: "id",
+ *   required: ["legacyField"],  // Make legacyField required for new inserts
+ *   readOnly: ["createdAt"],    // Exclude from insert/update
+ * });
+ * // On insert: name and legacyField required; email optional (id and createdAt excluded)
+ * // On update: all fields optional (id and createdAt excluded)
+ * ```
+ *
+ * @example Table with multiple read-only fields
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const usersTable = new BaseTable({
+ *   schema: {
+ *     id: z.string(),
+ *     createdAt: z.string(),
+ *     modifiedAt: z.string(),
+ *     createdBy: z.string(),
+ *     notes: z.string().nullable(),
+ *   },
+ *   idField: "id",
+ *   readOnly: ["createdAt", "modifiedAt", "createdBy"],
+ * });
+ * // On insert/update: only notes is available (id and system fields excluded)
+ * ```
+ */
+export declare class BaseTable<Schema extends Record<string, StandardSchemaV1> = any, IdField extends keyof Schema | undefined = undefined, Required extends readonly (keyof Schema)[] = readonly [], ReadOnly extends readonly (keyof Schema)[] = readonly []> {
     readonly schema: Schema;
     readonly idField?: IdField;
-    readonly insertRequired?: InsertRequired;
-    readonly updateRequired?: UpdateRequired;
+    readonly required?: Required;
+    readonly readOnly?: ReadOnly;
+    readonly fmfIds?: Record<keyof Schema, `FMFID:${string}`>;
     constructor(config: {
         schema: Schema;
         idField?: IdField;
-        insertRequired?: InsertRequired;
-        updateRequired?: UpdateRequired;
+        required?: Required;
+        readOnly?: ReadOnly;
+    });
+    /**
+     * Returns the FileMaker field ID (FMFID) for a given field name, or the field name itself if not using IDs.
+     * @param fieldName - The field name to get the ID for
+     * @returns The FMFID string or the original field name
+     */
+    getFieldId(fieldName: keyof Schema): string;
+    /**
+     * Returns the field name for a given FileMaker field ID (FMFID), or the ID itself if not found.
+     * @param fieldId - The FMFID to get the field name for
+     * @returns The field name or the original ID
+     */
+    getFieldName(fieldId: string): string;
+    /**
+     * Returns true if this BaseTable is using FileMaker field IDs.
+     */
+    isUsingFieldIds(): boolean;
+}
+/**
+ * BaseTableWithIds extends BaseTable to require FileMaker field IDs (fmfIds).
+ * Use this class when you need to work with FileMaker's internal field identifiers.
+ *
+ * @template Schema - Record of field names to StandardSchemaV1 validators
+ * @template IdField - The name of the primary key field (optional, automatically read-only)
+ * @template Required - Additional field names to require on insert (beyond auto-inferred required fields)
+ * @template ReadOnly - Field names that cannot be modified via insert/update (idField is automatically read-only)
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const usersTableWithIds = new BaseTableWithIds({
+ *   schema: {
+ *     id: z.string(),
+ *     name: z.string(),
+ *     email: z.string().nullable(),
+ *   },
+ *   idField: "id",
+ *   fmfIds: {
+ *     id: "FMFID:1",
+ *     name: "FMFID:2",
+ *     email: "FMFID:3",
+ *   },
+ * });
+ * ```
+ */
+export declare class BaseTableWithIds<Schema extends Record<string, StandardSchemaV1> = any, IdField extends keyof Schema | undefined = undefined, Required extends readonly (keyof Schema)[] = readonly [], ReadOnly extends readonly (keyof Schema)[] = readonly []> extends BaseTable<Schema, IdField, Required, ReadOnly> {
+    readonly fmfIds: Record<keyof Schema, `FMFID:${string}`>;
+    constructor(config: {
+        schema: Schema;
+        fmfIds: Record<keyof Schema, `FMFID:${string}`>;
+        idField?: IdField;
+        required?: Required;
+        readOnly?: ReadOnly;
     });
 }

package/dist/esm/client/base-table.js

@@ -5,15 +5,56 @@ class BaseTable {
   constructor(config) {
     __publicField(this, "schema");
     __publicField(this, "idField");
-    __publicField(this, "insertRequired");
-    __publicField(this, "updateRequired");
+    __publicField(this, "required");
+    __publicField(this, "readOnly");
+    __publicField(this, "fmfIds");
     this.schema = config.schema;
     this.idField = config.idField;
-    this.insertRequired = config.insertRequired;
-    this.updateRequired = config.updateRequired;
+    this.required = config.required;
+    this.readOnly = config.readOnly;
+  }
+  /**
+   * Returns the FileMaker field ID (FMFID) for a given field name, or the field name itself if not using IDs.
+   * @param fieldName - The field name to get the ID for
+   * @returns The FMFID string or the original field name
+   */
+  getFieldId(fieldName) {
+    if (this.fmfIds && fieldName in this.fmfIds) {
+      return this.fmfIds[fieldName];
+    }
+    return String(fieldName);
+  }
+  /**
+   * Returns the field name for a given FileMaker field ID (FMFID), or the ID itself if not found.
+   * @param fieldId - The FMFID to get the field name for
+   * @returns The field name or the original ID
+   */
+  getFieldName(fieldId) {
+    if (this.fmfIds) {
+      for (const [fieldName, fmfId] of Object.entries(this.fmfIds)) {
+        if (fmfId === fieldId) {
+          return fieldName;
+        }
+      }
+    }
+    return fieldId;
+  }
+  /**
+   * Returns true if this BaseTable is using FileMaker field IDs.
+   */
+  isUsingFieldIds() {
+    return this.fmfIds !== void 0;
+  }
+}
+class BaseTableWithIds extends BaseTable {
+  constructor(config) {
+    super(config);
+    __publicField(this, "fmfIds");
+    this.fmfIds = config.fmfIds;
   }
 }
 export {
-  BaseTable
+  BaseTable,
+  BaseTableWithIds
 };
 //# sourceMappingURL=base-table.js.map

package/dist/esm/client/base-table.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-table.js","sources":["../../../src/client/base-table.ts"],"sourcesContent":["import { StandardSchemaV1 } from \"@standard-schema/spec\";\n\nexport class BaseTable<\n  Schema extends Record<string, StandardSchemaV1> = any,\n  IdField extends keyof Schema | undefined = undefined,\n  InsertRequired extends readonly (keyof Schema)[] = readonly [],\n  UpdateRequired extends readonly (keyof Schema)[] = readonly [],\n> {\n  public readonly schema: Schema;\n  public readonly idField?: IdField;\n  public readonly insertRequired?: InsertRequired;\n  public readonly updateRequired?: UpdateRequired;\n\n  constructor(config: {\n    schema: Schema;\n    idField?: IdField;\n    insertRequired?: InsertRequired;\n    updateRequired?: UpdateRequired;\n  }) {\n    this.schema = config.schema;\n    this.idField = config.idField;\n    this.insertRequired = config.insertRequired;\n    this.updateRequired = config.updateRequired;\n  }\n}\n"],"names":[],"mappings":";;;AAEO,MAAM,UAKX;AAAA,EAMA,YAAY,QAKT;AAVa;AACA;AACA;AACA;AAQd,SAAK,SAAS,OAAO;AACrB,SAAK,UAAU,OAAO;AACtB,SAAK,iBAAiB,OAAO;AAC7B,SAAK,iBAAiB,OAAO;AAAA,EAAA;AAEjC;"}
+{"version":3,"file":"base-table.js","sources":["../../../src/client/base-table.ts"],"sourcesContent":["import { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * BaseTable defines the schema and configuration for a table.\n *\n * @template Schema - Record of field names to StandardSchemaV1 validators\n * @template IdField - The name of the primary key field (optional, automatically read-only)\n * @template Required - Additional field names to require on insert (beyond auto-inferred required fields)\n * @template ReadOnly - Field names that cannot be modified via insert/update (idField is automatically read-only)\n *\n * @example Basic table with auto-inferred required fields\n * ```ts\n * import { z } from \"zod\";\n *\n * const usersTable = new BaseTable({\n *   schema: {\n *     id: z.string(),               // Auto-required (not nullable), auto-readOnly (idField)\n *     name: z.string(),             // Auto-required (not nullable)\n *     email: z.string().nullable(), // Optional (nullable)\n *   },\n *   idField: \"id\",\n * });\n * // On insert: name is required, email is optional (id is excluded - readOnly)\n * // On update: name and email available (id is excluded - readOnly)\n * ```\n *\n * @example Table with additional required and readOnly fields\n * ```ts\n * import { z } from \"zod\";\n *\n * const usersTable = new BaseTable({\n *   schema: {\n *     id: z.string(),                    // Auto-required, auto-readOnly (idField)\n *     createdAt: z.string(),             // Read-only system field\n *     name: z.string(),                  // Auto-required\n *     email: z.string().nullable(),      // Optional by default...\n *     legacyField: z.string().nullable(), // Optional by default...\n *   },\n *   idField: \"id\",\n *   required: [\"legacyField\"],  // Make legacyField required for new inserts\n *   readOnly: [\"createdAt\"],    // Exclude from insert/update\n * });\n * // On insert: name and legacyField required; email optional (id and createdAt excluded)\n * // On update: all fields optional (id and createdAt excluded)\n * ```\n *\n * @example Table with multiple read-only fields\n * ```ts\n * import { z } from \"zod\";\n *\n * const usersTable = new BaseTable({\n *   schema: {\n *     id: z.string(),\n *     createdAt: z.string(),\n *     modifiedAt: z.string(),\n *     createdBy: z.string(),\n *     notes: z.string().nullable(),\n *   },\n *   idField: \"id\",\n *   readOnly: [\"createdAt\", \"modifiedAt\", \"createdBy\"],\n * });\n * // On insert/update: only notes is available (id and system fields excluded)\n * ```\n */\nexport class BaseTable<\n  Schema extends Record<string, StandardSchemaV1> = any,\n  IdField extends keyof Schema | undefined = undefined,\n  Required extends readonly (keyof Schema)[] = readonly [],\n  ReadOnly extends readonly (keyof Schema)[] = readonly [],\n> {\n  public readonly schema: Schema;\n  public readonly idField?: IdField;\n  public readonly required?: Required;\n  public readonly readOnly?: ReadOnly;\n  public readonly fmfIds?: Record<keyof Schema, `FMFID:${string}`>;\n\n  constructor(config: {\n    schema: Schema;\n    idField?: IdField;\n    required?: Required;\n    readOnly?: ReadOnly;\n  }) {\n    this.schema = config.schema;\n    this.idField = config.idField;\n    this.required = config.required;\n    this.readOnly = config.readOnly;\n  }\n\n  /**\n   * Returns the FileMaker field ID (FMFID) for a given field name, or the field name itself if not using IDs.\n   * @param fieldName - The field name to get the ID for\n   * @returns The FMFID string or the original field name\n   */\n  getFieldId(fieldName: keyof Schema): string {\n    if (this.fmfIds && fieldName in this.fmfIds) {\n      return this.fmfIds[fieldName];\n    }\n    return String(fieldName);\n  }\n\n  /**\n   * Returns the field name for a given FileMaker field ID (FMFID), or the ID itself if not found.\n   * @param fieldId - The FMFID to get the field name for\n   * @returns The field name or the original ID\n   */\n  getFieldName(fieldId: string): string {\n    if (this.fmfIds) {\n      // Search for the field name that corresponds to this FMFID\n      for (const [fieldName, fmfId] of Object.entries(this.fmfIds)) {\n        if (fmfId === fieldId) {\n          return fieldName;\n        }\n      }\n    }\n    return fieldId;\n  }\n\n  /**\n   * Returns true if this BaseTable is using FileMaker field IDs.\n   */\n  isUsingFieldIds(): boolean {\n    return this.fmfIds !== undefined;\n  }\n}\n\n/**\n * BaseTableWithIds extends BaseTable to require FileMaker field IDs (fmfIds).\n * Use this class when you need to work with FileMaker's internal field identifiers.\n *\n * @template Schema - Record of field names to StandardSchemaV1 validators\n * @template IdField - The name of the primary key field (optional, automatically read-only)\n * @template Required - Additional field names to require on insert (beyond auto-inferred required fields)\n * @template ReadOnly - Field names that cannot be modified via insert/update (idField is automatically read-only)\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n *\n * const usersTableWithIds = new BaseTableWithIds({\n *   schema: {\n *     id: z.string(),\n *     name: z.string(),\n *     email: z.string().nullable(),\n *   },\n *   idField: \"id\",\n *   fmfIds: {\n *     id: \"FMFID:1\",\n *     name: \"FMFID:2\",\n *     email: \"FMFID:3\",\n *   },\n * });\n * ```\n */\nexport class BaseTableWithIds<\n  Schema extends Record<string, StandardSchemaV1> = any,\n  IdField extends keyof Schema | undefined = undefined,\n  Required extends readonly (keyof Schema)[] = readonly [],\n  ReadOnly extends readonly (keyof Schema)[] = readonly [],\n> extends BaseTable<Schema, IdField, Required, ReadOnly> {\n  public override readonly fmfIds: Record<keyof Schema, `FMFID:${string}`>;\n\n  constructor(config: {\n    schema: Schema;\n    fmfIds: Record<keyof Schema, `FMFID:${string}`>;\n    idField?: IdField;\n    required?: Required;\n    readOnly?: ReadOnly;\n  }) {\n    super(config);\n    this.fmfIds = config.fmfIds;\n  }\n}\n"],"names":[],"mappings":";;;AAgEO,MAAM,UAKX;AAAA,EAOA,YAAY,QAKT;AAXa;AACA;AACA;AACA;AACA;AAQd,SAAK,SAAS,OAAO;AACrB,SAAK,UAAU,OAAO;AACtB,SAAK,WAAW,OAAO;AACvB,SAAK,WAAW,OAAO;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQzB,WAAW,WAAiC;AAC1C,QAAI,KAAK,UAAU,aAAa,KAAK,QAAQ;AACpC,aAAA,KAAK,OAAO,SAAS;AAAA,IAAA;AAE9B,WAAO,OAAO,SAAS;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQzB,aAAa,SAAyB;AACpC,QAAI,KAAK,QAAQ;AAEJ,iBAAA,CAAC,WAAW,KAAK,KAAK,OAAO,QAAQ,KAAK,MAAM,GAAG;AAC5D,YAAI,UAAU,SAAS;AACd,iBAAA;AAAA,QAAA;AAAA,MACT;AAAA,IACF;AAEK,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMT,kBAA2B;AACzB,WAAO,KAAK,WAAW;AAAA,EAAA;AAE3B;AA8BO,MAAM,yBAKH,UAA+C;AAAA,EAGvD,YAAY,QAMT;AACD,UAAM,MAAM;AATW;AAUvB,SAAK,SAAS,OAAO;AAAA,EAAA;AAEzB;"}