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

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;"}

package/dist/esm/client/batch-builder.d.ts

@@ -0,0 +1,54 @@
+import { ExecutableBuilder, ExecutionContext, Result, ExecuteOptions } from '../types.js';
+import { FFetchOptions } from '@fetchkit/ffetch';
+/**
+ * Helper type to extract result types from a tuple of ExecutableBuilders.
+ * Uses a mapped type which TypeScript 4.1+ can handle for tuples.
+ */
+type ExtractTupleTypes<T extends readonly ExecutableBuilder<any>[]> = {
+    [K in keyof T]: T[K] extends ExecutableBuilder<infer U> ? U : never;
+};
+/**
+ * Builder for batch operations that allows multiple queries to be executed together
+ * in a single transactional request.
+ */
+export declare class BatchBuilder<Builders extends readonly ExecutableBuilder<any>[]> implements ExecutableBuilder<ExtractTupleTypes<Builders>> {
+    private readonly databaseName;
+    private readonly context;
+    private builders;
+    private readonly originalBuilders;
+    constructor(builders: Builders, databaseName: string, context: ExecutionContext);
+    /**
+     * Add a request to the batch dynamically.
+     * This allows building up batch operations programmatically.
+     *
+     * @param builder - An executable builder to add to the batch
+     * @returns This BatchBuilder for method chaining
+     * @example
+     * ```ts
+     * const batch = db.batch([]);
+     * batch.addRequest(db.from('contacts').list());
+     * batch.addRequest(db.from('users').list());
+     * const result = await batch.execute();
+     * ```
+     */
+    addRequest<T>(builder: ExecutableBuilder<T>): this;
+    /**
+     * Get the request configuration for this batch operation.
+     * This is used internally by the execution system.
+     */
+    getRequestConfig(): {
+        method: string;
+        url: string;
+        body?: any;
+    };
+    toRequest(baseUrl: string): Request;
+    processResponse(response: Response, options?: ExecuteOptions): Promise<Result<any>>;
+    /**
+     * Execute the batch operation.
+     *
+     * @param options - Optional fetch options and batch-specific options (includes beforeRequest hook)
+     * @returns A tuple of results matching the input builders
+     */
+    execute<EO extends ExecuteOptions>(options?: RequestInit & FFetchOptions & EO): Promise<Result<ExtractTupleTypes<Builders>>>;
+}
+export {};

package/dist/esm/client/batch-builder.js

@@ -0,0 +1,179 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { formatBatchRequestFromNative, parseBatchResponse } from "./batch-request.js";
+function parsedToResponse(parsed) {
+  const headers = new Headers(parsed.headers);
+  if (parsed.body === null || parsed.body === void 0) {
+    return new Response(null, {
+      status: parsed.status,
+      statusText: parsed.statusText,
+      headers
+    });
+  }
+  const bodyString = typeof parsed.body === "string" ? parsed.body : JSON.stringify(parsed.body);
+  let status = parsed.status;
+  if (status === 204 && bodyString && bodyString.trim() !== "") {
+    status = 200;
+  }
+  return new Response(status === 204 ? null : bodyString, {
+    status,
+    statusText: parsed.statusText,
+    headers
+  });
+}
+class BatchBuilder {
+  constructor(builders, databaseName, context) {
+    __publicField(this, "builders");
+    __publicField(this, "originalBuilders");
+    this.databaseName = databaseName;
+    this.context = context;
+    this.builders = [...builders];
+    this.originalBuilders = builders;
+  }
+  /**
+   * Add a request to the batch dynamically.
+   * This allows building up batch operations programmatically.
+   *
+   * @param builder - An executable builder to add to the batch
+   * @returns This BatchBuilder for method chaining
+   * @example
+   * ```ts
+   * const batch = db.batch([]);
+   * batch.addRequest(db.from('contacts').list());
+   * batch.addRequest(db.from('users').list());
+   * const result = await batch.execute();
+   * ```
+   */
+  addRequest(builder) {
+    this.builders.push(builder);
+    return this;
+  }
+  /**
+   * Get the request configuration for this batch operation.
+   * This is used internally by the execution system.
+   */
+  getRequestConfig() {
+    return {
+      method: "POST",
+      url: `/${this.databaseName}/$batch`,
+      body: void 0
+      // Body is constructed in execute()
+    };
+  }
+  toRequest(baseUrl) {
+    const fullUrl = `${baseUrl}/${this.databaseName}/$batch`;
+    return new Request(fullUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "multipart/mixed",
+        "OData-Version": "4.0"
+      }
+    });
+  }
+  async processResponse(response, options) {
+    return {
+      data: void 0,
+      error: {
+        name: "NotImplementedError",
+        message: "Batch operations handle response processing internally",
+        timestamp: /* @__PURE__ */ new Date()
+      }
+    };
+  }
+  /**
+   * Execute the batch operation.
+   *
+   * @param options - Optional fetch options and batch-specific options (includes beforeRequest hook)
+   * @returns A tuple of results matching the input builders
+   */
+  async execute(options) {
+    var _a, _b;
+    const baseUrl = (_b = (_a = this.context)._getBaseUrl) == null ? void 0 : _b.call(_a);
+    if (!baseUrl) {
+      return {
+        data: void 0,
+        error: {
+          name: "ConfigurationError",
+          message: "Base URL not available - execution context must implement _getBaseUrl()",
+          timestamp: /* @__PURE__ */ new Date()
+        }
+      };
+    }
+    try {
+      const requests = this.builders.map(
+        (builder) => builder.toRequest(baseUrl)
+      );
+      const { body, boundary } = await formatBatchRequestFromNative(
+        requests,
+        baseUrl
+      );
+      const response = await this.context._makeRequest(
+        `/${this.databaseName}/$batch`,
+        {
+          ...options,
+          method: "POST",
+          headers: {
+            ...options == null ? void 0 : options.headers,
+            "Content-Type": `multipart/mixed; boundary=${boundary}`,
+            "OData-Version": "4.0"
+          },
+          body
+        }
+      );
+      if (response.error) {
+        return { data: void 0, error: response.error };
+      }
+      const firstLine = response.data.split("\r\n")[0] || response.data.split("\n")[0] || "";
+      const actualBoundary = firstLine.startsWith("--") ? firstLine.substring(2) : boundary;
+      const contentTypeHeader = `multipart/mixed; boundary=${actualBoundary}`;
+      const parsedResponses = parseBatchResponse(
+        response.data,
+        contentTypeHeader
+      );
+      if (parsedResponses.length !== this.builders.length) {
+        return {
+          data: void 0,
+          error: {
+            name: "BatchError",
+            message: `Expected ${this.builders.length} responses but got ${parsedResponses.length}`,
+            timestamp: /* @__PURE__ */ new Date()
+          }
+        };
+      }
+      const processedResults = [];
+      for (let i = 0; i < this.originalBuilders.length; i++) {
+        const builder = this.originalBuilders[i];
+        const parsed = parsedResponses[i];
+        if (!builder || !parsed) {
+          processedResults.push(void 0);
+          continue;
+        }
+        const nativeResponse = parsedToResponse(parsed);
+        const result = await builder.processResponse(nativeResponse, options);
+        if (result.error) {
+          processedResults.push(void 0);
+        } else {
+          processedResults.push(result.data);
+        }
+      }
+      return {
+        data: processedResults,
+        error: void 0
+      };
+    } catch (err) {
+      return {
+        data: void 0,
+        error: {
+          name: "BatchError",
+          message: err instanceof Error ? err.message : "Unknown error",
+          timestamp: /* @__PURE__ */ new Date()
+        }
+      };
+    }
+  }
+}
+export {
+  BatchBuilder
+};
+//# sourceMappingURL=batch-builder.js.map

package/dist/esm/client/batch-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-builder.js","sources":["../../../src/client/batch-builder.ts"],"sourcesContent":["import type {\n  ExecutableBuilder,\n  ExecutionContext,\n  Result,\n  ExecuteOptions,\n} from \"../types\";\nimport { type FFetchOptions } from \"@fetchkit/ffetch\";\nimport {\n  formatBatchRequestFromNative,\n  parseBatchResponse,\n  type ParsedBatchResponse,\n} from \"./batch-request\";\n\n/**\n * Helper type to extract result types from a tuple of ExecutableBuilders.\n * Uses a mapped type which TypeScript 4.1+ can handle for tuples.\n */\ntype ExtractTupleTypes<T extends readonly ExecutableBuilder<any>[]> = {\n  [K in keyof T]: T[K] extends ExecutableBuilder<infer U> ? U : never;\n};\n\n/**\n * Converts a ParsedBatchResponse to a native Response object\n * @param parsed - The parsed batch response\n * @returns A native Response object\n */\nfunction parsedToResponse(parsed: ParsedBatchResponse): Response {\n  const headers = new Headers(parsed.headers);\n\n  // Handle null body\n  if (parsed.body === null || parsed.body === undefined) {\n    return new Response(null, {\n      status: parsed.status,\n      statusText: parsed.statusText,\n      headers,\n    });\n  }\n\n  // Convert body to string if it's not already\n  const bodyString =\n    typeof parsed.body === \"string\" ? parsed.body : JSON.stringify(parsed.body);\n\n  // Handle 204 No Content status - it cannot have a body per HTTP spec\n  // If FileMaker returns 204 with a body, treat it as 200\n  let status = parsed.status;\n  if (status === 204 && bodyString && bodyString.trim() !== \"\") {\n    status = 200;\n  }\n\n  return new Response(status === 204 ? null : bodyString, {\n    status: status,\n    statusText: parsed.statusText,\n    headers,\n  });\n}\n\n/**\n * Builder for batch operations that allows multiple queries to be executed together\n * in a single transactional request.\n */\nexport class BatchBuilder<Builders extends readonly ExecutableBuilder<any>[]>\n  implements ExecutableBuilder<ExtractTupleTypes<Builders>>\n{\n  private builders: ExecutableBuilder<any>[];\n  private readonly originalBuilders: Builders;\n\n  constructor(\n    builders: Builders,\n    private readonly databaseName: string,\n    private readonly context: ExecutionContext,\n  ) {\n    // Convert readonly tuple to mutable array for dynamic additions\n    this.builders = [...builders];\n    // Store original tuple for type preservation\n    this.originalBuilders = builders;\n  }\n\n  /**\n   * Add a request to the batch dynamically.\n   * This allows building up batch operations programmatically.\n   *\n   * @param builder - An executable builder to add to the batch\n   * @returns This BatchBuilder for method chaining\n   * @example\n   * ```ts\n   * const batch = db.batch([]);\n   * batch.addRequest(db.from('contacts').list());\n   * batch.addRequest(db.from('users').list());\n   * const result = await batch.execute();\n   * ```\n   */\n  addRequest<T>(builder: ExecutableBuilder<T>): this {\n    this.builders.push(builder);\n    return this;\n  }\n\n  /**\n   * Get the request configuration for this batch operation.\n   * This is used internally by the execution system.\n   */\n  getRequestConfig(): { method: string; url: string; body?: any } {\n    // Note: This method is kept for compatibility but batch operations\n    // should use execute() directly which handles the full Request/Response flow\n    return {\n      method: \"POST\",\n      url: `/${this.databaseName}/$batch`,\n      body: undefined, // Body is constructed in execute()\n    };\n  }\n\n  toRequest(baseUrl: string): Request {\n    // Batch operations are not designed to be nested, but we provide\n    // a basic implementation for interface compliance\n    const fullUrl = `${baseUrl}/${this.databaseName}/$batch`;\n    return new Request(fullUrl, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"multipart/mixed\",\n        \"OData-Version\": \"4.0\",\n      },\n    });\n  }\n\n  async processResponse(\n    response: Response,\n    options?: ExecuteOptions,\n  ): Promise<Result<any>> {\n    // This should not typically be called for batch operations\n    // as they handle their own response processing\n    return {\n      data: undefined,\n      error: {\n        name: \"NotImplementedError\",\n        message: \"Batch operations handle response processing internally\",\n        timestamp: new Date(),\n      } as any,\n    };\n  }\n\n  /**\n   * Execute the batch operation.\n   *\n   * @param options - Optional fetch options and batch-specific options (includes beforeRequest hook)\n   * @returns A tuple of results matching the input builders\n   */\n  async execute<EO extends ExecuteOptions>(\n    options?: RequestInit & FFetchOptions & EO,\n  ): Promise<Result<ExtractTupleTypes<Builders>>> {\n    const baseUrl = this.context._getBaseUrl?.();\n    if (!baseUrl) {\n      return {\n        data: undefined,\n        error: {\n          name: \"ConfigurationError\",\n          message:\n            \"Base URL not available - execution context must implement _getBaseUrl()\",\n          timestamp: new Date(),\n        } as any,\n      };\n    }\n\n    try {\n      // Convert builders to native Request objects\n      const requests: Request[] = this.builders.map((builder) =>\n        builder.toRequest(baseUrl),\n      );\n\n      // Format batch request (automatically groups mutations into changesets)\n      const { body, boundary } = await formatBatchRequestFromNative(\n        requests,\n        baseUrl,\n      );\n\n      // Execute the batch request\n      const response = await this.context._makeRequest<string>(\n        `/${this.databaseName}/$batch`,\n        {\n          ...options,\n          method: \"POST\",\n          headers: {\n            ...options?.headers,\n            \"Content-Type\": `multipart/mixed; boundary=${boundary}`,\n            \"OData-Version\": \"4.0\",\n          },\n          body,\n        },\n      );\n\n      if (response.error) {\n        return { data: undefined, error: response.error };\n      }\n\n      // Extract the actual boundary from the response\n      // FileMaker uses its own boundary, not the one we sent\n      const firstLine =\n        response.data.split(\"\\r\\n\")[0] || response.data.split(\"\\n\")[0] || \"\";\n      const actualBoundary = firstLine.startsWith(\"--\")\n        ? firstLine.substring(2)\n        : boundary;\n\n      // Parse the multipart response\n      const contentTypeHeader = `multipart/mixed; boundary=${actualBoundary}`;\n      const parsedResponses = parseBatchResponse(\n        response.data,\n        contentTypeHeader,\n      );\n\n      // Check if we got the expected number of responses\n      if (parsedResponses.length !== this.builders.length) {\n        return {\n          data: undefined,\n          error: {\n            name: \"BatchError\",\n            message: `Expected ${this.builders.length} responses but got ${parsedResponses.length}`,\n            timestamp: new Date(),\n          } as any,\n        };\n      }\n\n      // Process each response using the corresponding builder\n      // Build tuple by processing each builder in order\n      type ResultTuple = ExtractTupleTypes<Builders>;\n\n      // Process builders sequentially to preserve tuple order\n      const processedResults: any[] = [];\n      for (let i = 0; i < this.originalBuilders.length; i++) {\n        const builder = this.originalBuilders[i];\n        const parsed = parsedResponses[i];\n\n        if (!builder || !parsed) {\n          processedResults.push(undefined);\n          continue;\n        }\n\n        // Convert parsed response to native Response\n        const nativeResponse = parsedToResponse(parsed);\n\n        // Let the builder process its own response\n        const result = await builder.processResponse(nativeResponse, options);\n\n        if (result.error) {\n          processedResults.push(undefined);\n        } else {\n          processedResults.push(result.data);\n        }\n      }\n\n      // Use a type assertion that TypeScript will respect\n      // ExtractTupleTypes ensures this is a proper tuple type\n      return {\n        data: processedResults as unknown as ResultTuple,\n        error: undefined,\n      };\n    } catch (err) {\n      return {\n        data: undefined,\n        error: {\n          name: \"BatchError\",\n          message: err instanceof Error ? err.message : \"Unknown error\",\n          timestamp: new Date(),\n        } as any,\n      };\n    }\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/client/batch-request.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Batch Request Utilities
+ *
+ * Utilities for formatting and parsing OData batch requests using multipart/mixed format.
+ * OData batch requests allow bundling multiple operations into a single HTTP request,
+ * with support for transactional changesets.
+ */
+export interface RequestConfig {
+    method: string;
+    url: string;
+    body?: string;
+    headers?: Record<string, string>;
+}
+export interface ParsedBatchResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: any;
+}
+/**
+ * Generates a random boundary string for multipart requests
+ * @param prefix - Prefix for the boundary (e.g., "batch_" or "changeset_")
+ * @returns A boundary string with the prefix and 32 random hex characters
+ */
+export declare function generateBoundary(prefix?: string): string;
+/**
+ * Formats multiple requests into a batch request body
+ * @param requests - Array of request configurations
+ * @param baseUrl - The base URL to prepend to relative URLs
+ * @param batchBoundary - Optional boundary string for the batch (generated if not provided)
+ * @returns Object containing the formatted body and boundary
+ */
+export declare function formatBatchRequest(requests: RequestConfig[], baseUrl: string, batchBoundary?: string): {
+    body: string;
+    boundary: string;
+};
+/**
+ * Formats multiple Request objects into a batch request body
+ * Supports explicit changesets via Request arrays
+ * @param requests - Array of Request objects or Request arrays (for explicit changesets)
+ * @param baseUrl - The base URL to prepend to relative URLs
+ * @param batchBoundary - Optional boundary string for the batch (generated if not provided)
+ * @returns Promise resolving to object containing the formatted body and boundary
+ */
+export declare function formatBatchRequestFromNative(requests: Array<Request | Request[]>, baseUrl: string, batchBoundary?: string): Promise<{
+    body: string;
+    boundary: string;
+}>;
+/**
+ * Extracts the boundary from a Content-Type header
+ * @param contentType - The Content-Type header value
+ * @returns The boundary string, or null if not found
+ */
+export declare function extractBoundary(contentType: string): string | null;
+/**
+ * Parses a batch response into individual responses
+ * @param responseText - The raw batch response text
+ * @param contentType - The Content-Type header from the response
+ * @returns Array of parsed responses in the same order as the request
+ */
+export declare function parseBatchResponse(responseText: string, contentType: string): ParsedBatchResponse[];