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

package/dist/esm/types.d.ts

@@ -13,11 +13,28 @@ export interface ExecutableBuilder<T> {
         url: string;
         body?: any;
     };
+    /**
+     * Convert this builder to a native Request object for batch processing.
+     * @param baseUrl - The base URL for the OData service
+     * @returns A native Request object
+     */
+    toRequest(baseUrl: string): Request;
+    /**
+     * Process a raw Response object into a typed Result.
+     * This allows builders to apply their own validation and transformation logic.
+     * @param response - The native Response object from the batch operation
+     * @param options - Optional execution options (e.g., skipValidation, includeODataAnnotations)
+     * @returns A typed Result with the builder's expected return type
+     */
+    processResponse(response: Response, options?: ExecuteOptions): Promise<Result<T>>;
 }
 export interface ExecutionContext {
-    _makeRequest<T>(url: string, options?: RequestInit & FFetchOptions): Promise<Result<T>>;
+    _makeRequest<T>(url: string, options?: RequestInit & FFetchOptions & {
+        useEntityIds?: boolean;
+    }): Promise<Result<T>>;
     _setUseEntityIds?(useEntityIds: boolean): void;
     _getUseEntityIds?(): boolean;
+    _getBaseUrl?(): string;
 }
 export type InferSchemaType<Schema extends Record<string, StandardSchemaV1>> = {
     [K in keyof Schema]: Schema[K] extends StandardSchemaV1<any, infer Output> ? Output : never;
@@ -70,6 +87,10 @@ export type UpdateData<BT> = BT extends import('./client/base-table.js').BaseTab
 export type ExecuteOptions = {
     includeODataAnnotations?: boolean;
     skipValidation?: boolean;
+    /**
+     * Overrides the default behavior of the database to use entity IDs (rather than field names) in THIS REQUEST ONLY
+     */
+    useEntityIds?: boolean;
 };
 export type ConditionallyWithODataAnnotations<T, IncludeODataAnnotations extends boolean> = IncludeODataAnnotations extends true ? T & {
     "@id": string;
@@ -80,4 +101,51 @@ export type ExtractSchemaFromOccurrence<Occ> = Occ extends {
         schema: infer S;
     };
 } ? S extends Record<string, StandardSchemaV1> ? S : Record<string, StandardSchemaV1> : Record<string, StandardSchemaV1>;
+export type GenericFieldMetadata = {
+    $Nullable?: boolean;
+    "@Index"?: boolean;
+    "@Calculation"?: boolean;
+    "@Summary"?: boolean;
+    "@Global"?: boolean;
+    "@Org.OData.Core.V1.Permissions"?: "Org.OData.Core.V1.Permission@Read";
+};
+export type StringFieldMetadata = GenericFieldMetadata & {
+    $Type: "Edm.String";
+    $DefaultValue?: "USER" | "USERNAME" | "CURRENT_USER";
+    $MaxLength?: number;
+};
+export type DecimalFieldMetadata = GenericFieldMetadata & {
+    $Type: "Edm.Decimal";
+    "@AutoGenerated"?: boolean;
+};
+export type DateFieldMetadata = GenericFieldMetadata & {
+    $Type: "Edm.Date";
+    $DefaultValue?: "CURDATE" | "CURRENT_DATE";
+};
+export type TimeOfDayFieldMetadata = GenericFieldMetadata & {
+    $Type: "Edm.TimeOfDay";
+    $DefaultValue?: "CURTIME" | "CURRENT_TIME";
+};
+export type DateTimeOffsetFieldMetadata = GenericFieldMetadata & {
+    $Type: "Edm.Date";
+    $DefaultValue?: "CURTIMESTAMP" | "CURRENT_TIMESTAMP";
+    "@VersionId"?: boolean;
+};
+export type StreamFieldMetadata = {
+    $Type: "Edm.Stream";
+    $Nullable?: boolean;
+    "@EnclosedPath": string;
+    "@ExternalOpenPath": string;
+    "@ExternalSecurePath"?: string;
+};
+export type FieldMetadata = StringFieldMetadata | DecimalFieldMetadata | DateFieldMetadata | TimeOfDayFieldMetadata | DateTimeOffsetFieldMetadata | StreamFieldMetadata;
+export type EntityType = {
+    $Kind: "EntityType";
+    $Key: string[];
+} & Record<string, FieldMetadata>;
+export type EntitySet = {
+    $Kind: "EntitySet";
+    $Type: string;
+};
+export type Metadata = Record<string, EntityType | EntitySet>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proofkit/fmodata",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "description": "FileMaker OData API client",
   "repository": "git@github.com:proofgeist/proofkit.git",
   "author": "Eric <37158449+eluce2@users.noreply.github.com>",

package/src/client/base-table.ts

@@ -79,11 +79,15 @@ export class BaseTable<
     idField?: IdField;
     required?: Required;
     readOnly?: ReadOnly;
+    fmfIds?: Record<string, `FMFID:${string}`>;
   }) {
     this.schema = config.schema;
     this.idField = config.idField;
     this.required = config.required;
     this.readOnly = config.readOnly;
+    this.fmfIds = config.fmfIds as
+      | Record<keyof Schema, `FMFID:${string}`>
+      | undefined;
   }
 
   /**
@@ -124,49 +128,39 @@ export class BaseTable<
 }
 
 /**
- * BaseTableWithIds extends BaseTable to require FileMaker field IDs (fmfIds).
- * Use this class when you need to work with FileMaker's internal field identifiers.
+ * Creates a BaseTable with proper TypeScript type inference.
  *
- * @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)
+ * This function should be used instead of `new BaseTable()` to ensure
+ * field names are properly typed throughout the library.
  *
- * @example
+ * @example Without entity IDs
  * ```ts
- * import { z } from "zod";
+ * const users = defineBaseTable({
+ *   schema: { id: z.string(), name: z.string() },
+ *   idField: "id",
+ * });
+ * ```
  *
- * const usersTableWithIds = new BaseTableWithIds({
- *   schema: {
- *     id: z.string(),
- *     name: z.string(),
- *     email: z.string().nullable(),
- *   },
+ * @example With entity IDs (FileMaker field IDs)
+ * ```ts
+ * const products = defineBaseTable({
+ *   schema: { id: z.string(), name: z.string() },
  *   idField: "id",
- *   fmfIds: {
- *     id: "FMFID:1",
- *     name: "FMFID:2",
- *     email: "FMFID:3",
- *   },
+ *   fmfIds: { id: "FMFID:1", name: "FMFID:2" },
  * });
  * ```
  */
-export class BaseTableWithIds<
-  Schema extends Record<string, StandardSchemaV1> = any,
+export function defineBaseTable<
+  const Schema extends Record<string, StandardSchemaV1>,
   IdField extends keyof Schema | undefined = undefined,
-  Required extends readonly (keyof Schema)[] = readonly [],
-  ReadOnly extends readonly (keyof Schema)[] = readonly [],
-> extends BaseTable<Schema, IdField, Required, ReadOnly> {
-  public override readonly fmfIds: Record<keyof Schema, `FMFID:${string}`>;
-
-  constructor(config: {
-    schema: Schema;
-    fmfIds: Record<keyof Schema, `FMFID:${string}`>;
-    idField?: IdField;
-    required?: Required;
-    readOnly?: ReadOnly;
-  }) {
-    super(config);
-    this.fmfIds = config.fmfIds;
-  }
+  const Required extends readonly (keyof Schema)[] = readonly [],
+  const ReadOnly extends readonly (keyof Schema)[] = readonly [],
+>(config: {
+  schema: Schema;
+  idField?: IdField;
+  required?: Required;
+  readOnly?: ReadOnly;
+  fmfIds?: { [K in keyof Schema]: `FMFID:${string}` };
+}): BaseTable<Schema, IdField, Required, ReadOnly> {
+  return new BaseTable(config);
 }

package/src/client/batch-builder.ts

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