@proofkit/fmodata 0.1.0-alpha.1 → 0.1.0-alpha.10

package/src/client/database.ts

@@ -1,14 +1,15 @@
-import { z } from "zod/v4";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { ExecutionContext } from "../types";
+import type { ExecutionContext, ExecutableBuilder, Metadata } from "../types";
 import type { BaseTable } from "./base-table";
 import type { TableOccurrence } from "./table-occurrence";
 import { EntitySet } from "./entity-set";
+import { BatchBuilder } from "./batch-builder";
+import { SchemaManager } from "./schema-manager";
 
 // Helper type to extract schema from a TableOccurrence
 type ExtractSchemaFromOccurrence<O> =
   O extends TableOccurrence<infer BT, any, any, any>
-    ? BT extends BaseTable<infer S, any>
+    ? BT extends BaseTable<infer S, any, any, any>
       ? S
       : never
     : never;
@@ -44,30 +45,122 @@ export class Database<
   >[] = readonly [],
 > {
   private occurrenceMap: Map<string, TableOccurrence<any, any, any, any>>;
+  private _useEntityIds: boolean = false;
+  public readonly schema: SchemaManager;
 
   constructor(
     private readonly databaseName: string,
     private readonly context: ExecutionContext,
-    config?: { occurrences?: Occurrences },
+    config?: {
+      occurrences?: Occurrences | undefined;
+      /**
+       * Whether to use entity IDs instead of field names in the actual requests to the server
+       * Defaults to true if all occurrences use entity IDs, false otherwise
+       * If set to false but some occurrences do not use entity IDs, an error will be thrown
+       */
+      useEntityIds?: boolean;
+    },
   ) {
     this.occurrenceMap = new Map();
     if (config?.occurrences) {
+      // Validate consistency: either all occurrences use entity IDs or none do
+      const occurrencesWithIds: string[] = [];
+      const occurrencesWithoutIds: string[] = [];
+
       for (const occ of config.occurrences) {
         this.occurrenceMap.set(occ.name, occ);
+
+        const hasTableId = occ.isUsingTableId();
+        const hasFieldIds = occ.baseTable.isUsingFieldIds();
+
+        // An occurrence uses entity IDs if it has both fmtId and fmfIds
+        if (hasTableId && hasFieldIds) {
+          occurrencesWithIds.push(occ.name);
+        } else if (!hasTableId && !hasFieldIds) {
+          occurrencesWithoutIds.push(occ.name);
+        } else {
+          // Partial entity ID usage (only one of fmtId or fmfIds) - this is an error
+          throw new Error(
+            `TableOccurrence "${occ.name}" has inconsistent entity ID configuration. ` +
+              `Both fmtId (${hasTableId ? "present" : "missing"}) and fmfIds (${hasFieldIds ? "present" : "missing"}) must be defined together.`,
+          );
+        }
       }
+
+      // Determine default value: true if all occurrences use entity IDs, false otherwise
+      const allOccurrencesUseEntityIds =
+        occurrencesWithIds.length > 0 && occurrencesWithoutIds.length === 0;
+      const hasMixedUsage =
+        occurrencesWithIds.length > 0 && occurrencesWithoutIds.length > 0;
+
+      // Handle explicit useEntityIds config
+      if (config.useEntityIds !== undefined) {
+        if (config.useEntityIds === false) {
+          // If explicitly set to false, allow mixed usage and use false
+          this._useEntityIds = false;
+        } else if (config.useEntityIds === true) {
+          // If explicitly set to true, validate that all occurrences use entity IDs
+          if (hasMixedUsage || occurrencesWithoutIds.length > 0) {
+            throw new Error(
+              `useEntityIds is set to true but some occurrences do not use entity IDs. ` +
+                `Occurrences without entity IDs: [${occurrencesWithoutIds.join(", ")}]. ` +
+                `Either set useEntityIds to false or configure all occurrences with entity IDs.`,
+            );
+          }
+          this._useEntityIds = true;
+        }
+      } else {
+        // Default: true if all occurrences use entity IDs, false otherwise
+        // But throw error if there's mixed usage when using defaults
+        if (hasMixedUsage) {
+          throw new Error(
+            `Cannot mix TableOccurrence instances with and without entity IDs in the same database. ` +
+              `Occurrences with entity IDs: [${occurrencesWithIds.join(", ")}]. ` +
+              `Occurrences without entity IDs: [${occurrencesWithoutIds.join(", ")}]. ` +
+              `Either all table occurrences must use entity IDs (fmtId + fmfIds), none should, or explicitly set useEntityIds to false.`,
+          );
+        }
+        this._useEntityIds = allOccurrencesUseEntityIds;
+      }
+    } else {
+      // No occurrences provided, use explicit config or default to false
+      this._useEntityIds = config?.useEntityIds ?? false;
+    }
+
+    // Inform the execution context whether to use entity IDs
+    if (this.context._setUseEntityIds) {
+      this.context._setUseEntityIds(this._useEntityIds);
     }
+
+    // Initialize schema manager
+    this.schema = new SchemaManager(this.databaseName, this.context);
+  }
+
+  /**
+   * Returns true if any table occurrence in this database is using entity IDs.
+   */
+  isUsingEntityIds(): boolean {
+    return this._useEntityIds;
+  }
+
+  /**
+   * Gets a table occurrence by name.
+   * @internal
+   */
+  getOccurrence(name: string): TableOccurrence<any, any, any, any> | undefined {
+    return this.occurrenceMap.get(name);
   }
 
   from<Name extends ExtractOccurrenceNames<Occurrences> | (string & {})>(
     name: Name,
   ): Occurrences extends readonly []
-    ? EntitySet<Record<string, z.ZodTypeAny>, undefined>
+    ? EntitySet<Record<string, StandardSchemaV1>, undefined>
     : Name extends ExtractOccurrenceNames<Occurrences>
       ? EntitySet<
           ExtractSchemaFromOccurrence<FindOccurrenceByName<Occurrences, Name>>,
           FindOccurrenceByName<Occurrences, Name>
         >
-      : EntitySet<Record<string, z.ZodTypeAny>, undefined> {
+      : EntitySet<Record<string, StandardSchemaV1>, undefined> {
     const occurrence = this.occurrenceMap.get(name as string);
 
     if (occurrence) {
@@ -76,24 +169,56 @@ export class Database<
       type SchemaType = ExtractSchemaFromOccurrence<OccType>;
 
       return EntitySet.create<SchemaType, OccType>({
-        occurrence: occurrence as any,
+        occurrence: occurrence as OccType,
         tableName: name as string,
         databaseName: this.databaseName,
         context: this.context,
+        database: this,
       }) as any;
     } else {
       // Return untyped EntitySet for dynamic table access
-      return new EntitySet<Record<string, z.ZodTypeAny>, undefined>({
+      return new EntitySet<Record<string, StandardSchemaV1>, undefined>({
         tableName: name as string,
         databaseName: this.databaseName,
         context: this.context,
+        database: this,
       }) as any;
     }
   }
 
-  // Example method showing how to use the request method
-  async getMetadata() {
-    return this.context._makeRequest(`/${this.databaseName}/$metadata`);
+  /**
+   * Retrieves the OData metadata for this database.
+   * @param args Optional configuration object
+   * @param args.format The format to retrieve metadata in. Defaults to "json".
+   * @returns The metadata in the specified format
+   */
+  async getMetadata(args: { format: "xml" }): Promise<string>;
+  async getMetadata(args?: { format?: "json" }): Promise<Metadata>;
+  async getMetadata(args?: {
+    format?: "xml" | "json";
+  }): Promise<string | Metadata> {
+    const result = await this.context._makeRequest<
+      Record<string, Metadata> | string
+    >(`/${this.databaseName}/$metadata`, {
+      headers: {
+        Accept: args?.format === "xml" ? "application/xml" : "application/json",
+      },
+    });
+    if (result.error) {
+      throw result.error;
+    }
+
+    if (args?.format === "json") {
+      const data = result.data as Record<string, Metadata>;
+      const metadata = data[this.databaseName];
+      if (!metadata) {
+        throw new Error(
+          `Metadata for database "${this.databaseName}" not found in response`,
+        );
+      }
+      return metadata;
+    }
+    return result.data as string;
   }
 
   /**
@@ -101,13 +226,14 @@ export class Database<
    * @returns Promise resolving to an array of table names
    */
   async listTableNames(): Promise<string[]> {
-    const response = (await this.context._makeRequest(
-      `/${this.databaseName}`,
-    )) as {
+    const result = await this.context._makeRequest<{
       value?: Array<{ name: string }>;
-    };
-    if (response.value && Array.isArray(response.value)) {
-      return response.value.map((item) => item.name);
+    }>(`/${this.databaseName}`);
+    if (result.error) {
+      throw result.error;
+    }
+    if (result.data.value && Array.isArray(result.data.value)) {
+      return result.data.value.map((item) => item.name);
     }
     return [];
   }
@@ -136,7 +262,7 @@ export class Database<
       body.scriptParameterValue = options.scriptParam;
     }
 
-    const response = await this.context._makeRequest<{
+    const result = await this.context._makeRequest<{
       scriptResult: {
         code: number;
         resultParameter?: string;
@@ -146,6 +272,12 @@ export class Database<
       body: Object.keys(body).length > 0 ? JSON.stringify(body) : undefined,
     });
 
+    if (result.error) {
+      throw result.error;
+    }
+
+    const response = result.data;
+
     // If resultSchema is provided, validate the result through it
     if (options?.resultSchema && response.scriptResult !== undefined) {
       const validationResult = options.resultSchema["~standard"].validate(
@@ -174,4 +306,29 @@ export class Database<
       result: response.scriptResult.resultParameter,
     } as any;
   }
+
+  /**
+   * Create a batch operation builder that allows multiple queries to be executed together
+   * in a single atomic request. All operations succeed or fail together (transactional).
+   *
+   * @param builders - Array of executable query builders to batch
+   * @returns A BatchBuilder that can be executed
+   * @example
+   * ```ts
+   * const result = await db.batch([
+   *   db.from('contacts').list().top(5),
+   *   db.from('users').list().top(5),
+   *   db.from('contacts').insert({ name: 'John' })
+   * ]).execute();
+   *
+   * if (result.data) {
+   *   const [contacts, users, insertResult] = result.data;
+   * }
+   * ```
+   */
+  batch<const Builders extends readonly ExecutableBuilder<any>[]>(
+    builders: Builders,
+  ): BatchBuilder<Builders> {
+    return new BatchBuilder(builders, this.databaseName, this.context);
+  }
 }

package/src/client/delete-builder.ts

@@ -3,11 +3,12 @@ import type {
   ExecutableBuilder,
   Result,
   WithSystemFields,
+  ExecuteOptions,
 } from "../types";
 import type { TableOccurrence } from "./table-occurrence";
 import { QueryBuilder } from "./query-builder";
 import { type FFetchOptions } from "@fetchkit/ffetch";
-import buildQuery from "odata-query";
+import { getTableIdentifiers } from "../transform";
 
 /**
  * Initial delete builder returned from EntitySet.delete()
@@ -18,17 +19,20 @@ export class DeleteBuilder<T extends Record<string, any>> {
   private databaseName: string;
   private context: ExecutionContext;
   private occurrence?: TableOccurrence<any, any, any, any>;
+  private databaseUseEntityIds: boolean;
 
   constructor(config: {
     occurrence?: TableOccurrence<any, any, any, any>;
     tableName: string;
     databaseName: string;
     context: ExecutionContext;
+    databaseUseEntityIds?: boolean;
   }) {
     this.occurrence = config.occurrence;
     this.tableName = config.tableName;
     this.databaseName = config.databaseName;
     this.context = config.context;
+    this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
   }
 
   /**
@@ -42,6 +46,7 @@ export class DeleteBuilder<T extends Record<string, any>> {
       context: this.context,
       mode: "byId",
       recordId: id,
+      databaseUseEntityIds: this.databaseUseEntityIds,
     });
   }
 
@@ -78,6 +83,7 @@ export class DeleteBuilder<T extends Record<string, any>> {
       context: this.context,
       mode: "byFilter",
       queryBuilder: configuredBuilder,
+      databaseUseEntityIds: this.databaseUseEntityIds,
     });
   }
 }
@@ -96,6 +102,7 @@ export class ExecutableDeleteBuilder<T extends Record<string, any>>
   private mode: "byId" | "byFilter";
   private recordId?: string | number;
   private queryBuilder?: QueryBuilder<any>;
+  private databaseUseEntityIds: boolean;
 
   constructor(config: {
     occurrence?: TableOccurrence<any, any, any, any>;
@@ -105,6 +112,7 @@ export class ExecutableDeleteBuilder<T extends Record<string, any>>
     mode: "byId" | "byFilter";
     recordId?: string | number;
     queryBuilder?: QueryBuilder<any>;
+    databaseUseEntityIds?: boolean;
   }) {
     this.occurrence = config.occurrence;
     this.tableName = config.tableName;
@@ -113,76 +121,127 @@ export class ExecutableDeleteBuilder<T extends Record<string, any>>
     this.mode = config.mode;
     this.recordId = config.recordId;
     this.queryBuilder = config.queryBuilder;
+    this.databaseUseEntityIds = config.databaseUseEntityIds ?? false;
+  }
+
+  /**
+   * Helper to merge database-level useEntityIds with per-request options
+   */
+  private mergeExecuteOptions(
+    options?: RequestInit & FFetchOptions & ExecuteOptions,
+  ): RequestInit & FFetchOptions & { useEntityIds?: boolean } {
+    // If useEntityIds is not set in options, use the database-level setting
+    return {
+      ...options,
+      useEntityIds: options?.useEntityIds ?? this.databaseUseEntityIds,
+    };
+  }
+
+  /**
+   * Gets the table ID (FMTID) if using entity IDs, otherwise returns the table name
+   * @param useEntityIds - Optional override for entity ID usage
+   */
+  private getTableId(useEntityIds?: boolean): string {
+    if (!this.occurrence) {
+      return this.tableName;
+    }
+
+    const contextDefault = this.context._getUseEntityIds?.() ?? false;
+    const shouldUseIds = useEntityIds ?? contextDefault;
+
+    if (shouldUseIds) {
+      const identifiers = getTableIdentifiers(this.occurrence);
+      if (!identifiers.id) {
+        throw new Error(
+          `useEntityIds is true but TableOccurrence "${identifiers.name}" does not have an fmtId defined`,
+        );
+      }
+      return identifiers.id;
+    }
+
+    return this.occurrence.getTableName();
   }
 
   async execute(
-    options?: RequestInit & FFetchOptions,
+    options?: RequestInit & FFetchOptions & { useEntityIds?: boolean },
   ): Promise<Result<{ deletedCount: number }>> {
-    try {
-      let url: string;
-
-      if (this.mode === "byId") {
-        // Delete single record by ID: DELETE /{database}/{table}('id')
-        url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
-      } else {
-        // Delete by filter: DELETE /{database}/{table}?$filter=...
-        if (!this.queryBuilder) {
-          throw new Error("Query builder is required for filter-based delete");
-        }
-
-        // Get the query string from the configured QueryBuilder
-        const queryString = this.queryBuilder.getQueryString();
-        // Remove the leading "/" from the query string as we'll build our own URL
-        const queryParams = queryString.startsWith(`/${this.tableName}`)
+    // Merge database-level useEntityIds with per-request options
+    const mergedOptions = this.mergeExecuteOptions(options);
+
+    // Get table identifier with override support
+    const tableId = this.getTableId(mergedOptions.useEntityIds);
+
+    let url: string;
+
+    if (this.mode === "byId") {
+      // Delete single record by ID: DELETE /{database}/{table}('id')
+      url = `/${this.databaseName}/${tableId}('${this.recordId}')`;
+    } else {
+      // Delete by filter: DELETE /{database}/{table}?$filter=...
+      if (!this.queryBuilder) {
+        throw new Error("Query builder is required for filter-based delete");
+      }
+
+      // Get the query string from the configured QueryBuilder
+      const queryString = this.queryBuilder.getQueryString();
+      // Remove the leading "/" 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 DELETE request
-      const response = await this.context._makeRequest(url, {
-        method: "DELETE",
-        ...options,
-      });
-
-      // OData returns 204 No Content with fmodata.affected_rows header
-      // The _makeRequest should handle extracting the header value
-      // For now, we'll check if response contains the count
-      let deletedCount = 0;
-
-      if (typeof response === "number") {
-        deletedCount = response;
-      } else if (response && typeof response === "object") {
-        // Check if the response has a count property (fallback)
-        deletedCount = (response as any).deletedCount || 0;
-      }
+    // Make DELETE request
+    const result = await this.context._makeRequest(url, {
+      method: "DELETE",
+      ...mergedOptions,
+    });
 
-      return { data: { deletedCount }, error: undefined };
-    } catch (error) {
-      return {
-        data: undefined,
-        error: error instanceof Error ? error : new Error(String(error)),
-      };
+    if (result.error) {
+      return { data: undefined, error: result.error };
+    }
+
+    const response = result.data;
+
+    // OData returns 204 No Content with fmodata.affected_rows header
+    // The _makeRequest should handle extracting the header value
+    // For now, we'll check if response contains the count
+    let deletedCount = 0;
+
+    if (typeof response === "number") {
+      deletedCount = response;
+    } else if (response && typeof response === "object") {
+      // Check if the response has a count property (fallback)
+      deletedCount = (response as any).deletedCount || 0;
     }
+
+    return { data: { deletedCount }, error: undefined };
   }
 
   getRequestConfig(): { method: string; url: string; body?: any } {
+    // For batch operations, use database-level setting (no per-request override available here)
+    const tableId = this.getTableId(this.databaseUseEntityIds);
+
     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 delete");
       }
 
       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 {
@@ -190,4 +249,46 @@ export class ExecutableDeleteBuilder<T extends Record<string, any>>
       url,
     };
   }
+
+  toRequest(baseUrl: string): Request {
+    const config = this.getRequestConfig();
+    const fullUrl = `${baseUrl}${config.url}`;
+
+    return new Request(fullUrl, {
+      method: config.method,
+      headers: {
+        Accept: "application/json",
+      },
+    });
+  }
+
+  async processResponse(
+    response: Response,
+    options?: ExecuteOptions,
+  ): Promise<Result<{ deletedCount: number }>> {
+    // Check for empty response (204 No Content)
+    const text = await response.text();
+    if (!text || text.trim() === "") {
+      // For 204 No Content, check the fmodata.affected_rows header
+      const affectedRows = response.headers.get("fmodata.affected_rows");
+      const deletedCount = affectedRows ? parseInt(affectedRows, 10) : 1;
+      return { data: { deletedCount }, error: undefined };
+    }
+
+    const rawResponse = JSON.parse(text);
+
+    // OData returns 204 No Content with fmodata.affected_rows header
+    // The _makeRequest should handle extracting the header value
+    // For now, we'll check if response contains the count
+    let deletedCount = 0;
+
+    if (typeof rawResponse === "number") {
+      deletedCount = rawResponse;
+    } else if (rawResponse && typeof rawResponse === "object") {
+      // Check if the response has a count property (fallback)
+      deletedCount = (rawResponse as any).deletedCount || 0;
+    }
+
+    return { data: { deletedCount }, error: undefined };
+  }
 }