@proofkit/fmodata 0.1.0-alpha.9 → 0.1.0-beta.23

package/src/client/builders/select-utils.ts

@@ -0,0 +1,59 @@
+import type { FMTable } from "../../orm/table";
+import { transformFieldNamesArray } from "../../transform";
+
+const VALID_FIELD_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9]*$/;
+
+/**
+ * Determines if a field name needs to be quoted in OData queries.
+ * Per FileMaker docs: field names with special characters (spaces, underscores, etc.) must be quoted.
+ * Also quotes "id" as it's an OData reserved word.
+ * Entity IDs (FMFID:*, FMTID:*) are not quoted as they're identifiers, not field names.
+ *
+ * @param fieldName - The field name or identifier to check
+ * @returns true if the field name should be quoted in OData queries
+ */
+export function needsFieldQuoting(fieldName: string): boolean {
+  // Entity IDs are identifiers and don't need quoting
+  if (fieldName.startsWith("FMFID:") || fieldName.startsWith("FMTID:")) {
+    return false;
+  }
+  // Always quote "id" as it's an OData reserved word
+  if (fieldName === "id") {
+    return true;
+  }
+  // Quote if field name contains spaces, underscores, or other special characters
+  return fieldName.includes(" ") || fieldName.includes("_") || !VALID_FIELD_NAME_REGEX.test(fieldName);
+}
+
+/**
+ * Formats select fields for use in OData query strings.
+ * - Transforms field names to FMFIDs if using entity IDs
+ * - Wraps "id" fields in double quotes (OData reserved)
+ * - URL-encodes special characters but preserves spaces
+ */
+export function formatSelectFields(
+  select: string[] | readonly string[] | undefined,
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  table?: FMTable<any, any>,
+  useEntityIds?: boolean,
+): string {
+  if (!select || select.length === 0) {
+    return "";
+  }
+
+  const selectArray = Array.isArray(select) ? select : [select];
+
+  // Transform to field IDs if using entity IDs
+  const transformedFields =
+    table && useEntityIds ? transformFieldNamesArray(selectArray.map(String), table) : selectArray.map(String);
+
+  return transformedFields
+    .map((field) => {
+      if (needsFieldQuoting(field)) {
+        return `"${field}"`;
+      }
+      const encoded = encodeURIComponent(field);
+      return encoded.replace(/%20/g, " ");
+    })
+    .join(",");
+}

package/src/client/builders/shared-types.ts

@@ -0,0 +1,45 @@
+import type { QueryOptions } from "odata-query";
+import type { FMTable } from "../../orm/table";
+import type { ExecutionContext } from "../../types";
+
+/**
+ * Expand configuration used by both QueryBuilder and RecordBuilder
+ */
+export interface ExpandConfig {
+  relation: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any QueryOptions configuration
+  options?: Partial<QueryOptions<any>>;
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  targetTable?: FMTable<any, any>;
+  nestedExpandConfigs?: ExpandConfig[];
+}
+
+/**
+ * Type to represent expanded relations in return types
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Dynamic schema and selected types from user input
+export type ExpandedRelations = Record<string, { schema: any; selected: any }>;
+
+/**
+ * Navigation context shared between builders
+ */
+export interface NavigationContext {
+  isNavigate?: boolean;
+  navigateRecordId?: string | number;
+  navigateRelation?: string;
+  navigateSourceTableName?: string;
+  navigateBaseRelation?: string;
+  navigateBasePath?: string;
+}
+
+/**
+ * Common builder configuration
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+export interface BuilderConfig<Occ extends FMTable<any, any> | undefined> {
+  occurrence?: Occ;
+  tableName: string;
+  databaseName: string;
+  context: ExecutionContext;
+  databaseUseEntityIds?: boolean;
+}

package/src/client/builders/table-utils.ts

@@ -0,0 +1,83 @@
+import type { FFetchOptions } from "@fetchkit/ffetch";
+import type { FMTable } from "../../orm/table";
+import { getTableId as getTableIdHelper, getTableName, isUsingEntityIds } from "../../orm/table";
+import type { ExecuteOptions, ExecutionContext } from "../../types";
+import { getAcceptHeader } from "../../types";
+
+/**
+ * Resolves table identifier based on entity ID settings.
+ * Used by both QueryBuilder and RecordBuilder.
+ */
+export function resolveTableId(
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  table: FMTable<any, any> | undefined,
+  fallbackTableName: string,
+  context: ExecutionContext,
+  useEntityIdsOverride?: boolean,
+): string {
+  if (!table) {
+    return fallbackTableName;
+  }
+
+  const contextDefault = context._getUseEntityIds?.() ?? false;
+  const shouldUseIds = useEntityIdsOverride ?? contextDefault;
+
+  if (shouldUseIds) {
+    if (!isUsingEntityIds(table)) {
+      throw new Error(`useEntityIds is true but table "${getTableName(table)}" does not have entity IDs configured`);
+    }
+    return getTableIdHelper(table);
+  }
+
+  return getTableName(table);
+}
+
+/**
+ * Merges database-level useEntityIds with per-request options.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
+export function mergeEntityIdOptions<T extends Record<string, any>>(
+  options: T | undefined,
+  databaseDefault: boolean,
+): T & { useEntityIds?: boolean } {
+  return {
+    ...options,
+    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for optional property access
+    useEntityIds: (options as any)?.useEntityIds ?? databaseDefault,
+  } as T & { useEntityIds?: boolean };
+}
+
+/**
+ * Type-safe helper for merging execute options with entity ID settings
+ */
+export function mergeExecuteOptions(
+  options: (RequestInit & FFetchOptions & ExecuteOptions) | undefined,
+  databaseUseEntityIds: boolean,
+): RequestInit & FFetchOptions & { useEntityIds?: boolean } {
+  return mergeEntityIdOptions(options, databaseUseEntityIds);
+}
+
+/**
+ * Creates an OData Request object with proper headers.
+ * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+ *
+ * @param baseUrl - Base URL for the request
+ * @param config - Request configuration with method and url
+ * @param options - Optional execution options
+ * @returns Request object ready to use
+ */
+export function createODataRequest(
+  baseUrl: string,
+  config: { method: string; url: string },
+  options?: { includeODataAnnotations?: boolean },
+): Request {
+  const fullUrl = `${baseUrl}${config.url}`;
+
+  return new Request(fullUrl, {
+    method: config.method,
+    headers: {
+      "Content-Type": "application/json",
+      Accept: getAcceptHeader(options?.includeODataAnnotations),
+    },
+  });
+}

package/src/client/database.ts

@@ -1,208 +1,120 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-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 { FMTable } from "../orm/table";
+import type { ExecutableBuilder, ExecutionContext, Metadata } from "../types";
 import { BatchBuilder } from "./batch-builder";
+import { EntitySet } from "./entity-set";
 import { SchemaManager } from "./schema-manager";
+import { WebhookManager } from "./webhook-builder";
 
-// 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, any, any>
-      ? S
-      : never
-    : never;
-
-// Helper type to find an occurrence by name in the occurrences tuple
-type FindOccurrenceByName<
-  Occurrences extends readonly TableOccurrence<any, any, any, any>[],
-  Name extends string,
-> = Occurrences extends readonly [
-  infer First,
-  ...infer Rest extends readonly TableOccurrence<any, any, any, any>[],
-]
-  ? First extends TableOccurrence<any, any, any, any>
-    ? First["name"] extends Name
-      ? First
-      : FindOccurrenceByName<Rest, Name>
-    : never
-  : never;
-
-// Helper type to extract all occurrence names from the tuple
-type ExtractOccurrenceNames<
-  Occurrences extends readonly TableOccurrence<any, any, any, any>[],
-> = Occurrences extends readonly []
-  ? string // If no occurrences, allow any string
-  : Occurrences[number]["name"]; // Otherwise, extract union of names
+interface MetadataArgs {
+  format?: "xml" | "json";
+  /**
+   * If provided, only the metadata for the specified table will be returned.
+   * Requires FileMaker Server 22.0.4 or later.
+   */
+  tableName?: string;
+  /**
+   * If true, a reduced payload size will be returned by omitting certain annotations.
+   */
+  reduceAnnotations?: boolean;
+}
 
-export class Database<
-  Occurrences extends readonly TableOccurrence<
-    any,
-    any,
-    any,
-    any
-  >[] = readonly [],
-> {
-  private occurrenceMap: Map<string, TableOccurrence<any, any, any, any>>;
-  private _useEntityIds: boolean = false;
-  public readonly schema: SchemaManager;
+export class Database<IncludeSpecialColumns extends boolean = false> {
+  readonly schema: SchemaManager;
+  readonly webhook: WebhookManager;
+  private readonly databaseName: string;
+  private readonly context: ExecutionContext;
+  private _useEntityIds: boolean;
+  private readonly _includeSpecialColumns: IncludeSpecialColumns;
 
   constructor(
-    private readonly databaseName: string,
-    private readonly context: ExecutionContext,
+    databaseName: string,
+    context: ExecutionContext,
     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;
+      /**
+       * Whether to include special columns (ROWID and ROWMODID) in responses.
+       * Note: Special columns are only included when there is no $select query.
+       */
+      includeSpecialColumns?: IncludeSpecialColumns;
     },
   ) {
-    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);
-    }
-
+    this.databaseName = databaseName;
+    this.context = context;
     // Initialize schema manager
     this.schema = new SchemaManager(this.databaseName, this.context);
+    this.webhook = new WebhookManager(this.databaseName, this.context);
+    this._useEntityIds = config?.useEntityIds ?? false;
+    this._includeSpecialColumns = (config?.includeSpecialColumns ?? false) as IncludeSpecialColumns;
   }
 
   /**
-   * Returns true if any table occurrence in this database is using entity IDs.
+   * @internal Used by EntitySet to access database configuration
    */
-  isUsingEntityIds(): boolean {
+  get _getUseEntityIds(): boolean {
     return this._useEntityIds;
   }
 
   /**
-   * Gets a table occurrence by name.
-   * @internal
+   * @internal Used by EntitySet to access database configuration
    */
-  getOccurrence(name: string): TableOccurrence<any, any, any, any> | undefined {
-    return this.occurrenceMap.get(name);
+  get _getIncludeSpecialColumns(): IncludeSpecialColumns {
+    return this._includeSpecialColumns;
   }
 
-  from<Name extends ExtractOccurrenceNames<Occurrences> | (string & {})>(
-    name: Name,
-  ): Occurrences extends readonly []
-    ? EntitySet<Record<string, StandardSchemaV1>, undefined>
-    : Name extends ExtractOccurrenceNames<Occurrences>
-      ? EntitySet<
-          ExtractSchemaFromOccurrence<FindOccurrenceByName<Occurrences, Name>>,
-          FindOccurrenceByName<Occurrences, Name>
-        >
-      : EntitySet<Record<string, StandardSchemaV1>, undefined> {
-    const occurrence = this.occurrenceMap.get(name as string);
-
-    if (occurrence) {
-      // Use EntitySet.create to preserve types better
-      type OccType = FindOccurrenceByName<Occurrences, Name>;
-      type SchemaType = ExtractSchemaFromOccurrence<OccType>;
-
-      return EntitySet.create<SchemaType, OccType>({
-        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, StandardSchemaV1>, undefined>({
-        tableName: name as string,
-        databaseName: this.databaseName,
-        context: this.context,
-        database: this,
-      }) as any;
+  // biome-ignore lint/suspicious/noExplicitAny: Accepts any FMTable configuration
+  from<T extends FMTable<any, any>>(table: T): EntitySet<T, IncludeSpecialColumns> {
+    // Only override database-level useEntityIds if table explicitly sets it
+    // (not if it's undefined, which would override the database setting)
+    if (Object.hasOwn(table, FMTable.Symbol.UseEntityIds)) {
+      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for Symbol property access
+      const tableUseEntityIds = (table as any)[FMTable.Symbol.UseEntityIds];
+      if (typeof tableUseEntityIds === "boolean") {
+        this._useEntityIds = tableUseEntityIds;
+      }
     }
+    return new EntitySet<T, IncludeSpecialColumns>({
+      occurrence: table as T,
+      databaseName: this.databaseName,
+      context: this.context,
+      database: this,
+    });
   }
 
   /**
    * Retrieves the OData metadata for this database.
    * @param args Optional configuration object
    * @param args.format The format to retrieve metadata in. Defaults to "json".
+   * @param args.tableName If provided, only the metadata for the specified table will be returned. Requires FileMaker Server 22.0.4 or later.
+   * @param args.reduceAnnotations If true, a reduced payload size will be returned by omitting certain annotations.
    * @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",
-      },
+  async getMetadata(args: { format: "xml" } & MetadataArgs): Promise<string>;
+  async getMetadata(args?: { format?: "json" } & MetadataArgs): Promise<Metadata>;
+  async getMetadata(args?: MetadataArgs): Promise<string | Metadata> {
+    // Build the URL - if tableName is provided, append %23{tableName} to the path
+    let url = `/${this.databaseName}/$metadata`;
+    if (args?.tableName) {
+      url = `/${this.databaseName}/$metadata%23${args.tableName}`;
+    }
+
+    // Build headers
+    const headers: Record<string, string> = {
+      Accept: args?.format === "xml" ? "application/xml" : "application/json",
+    };
+
+    // Add Prefer header if reduceAnnotations is true
+    if (args?.reduceAnnotations) {
+      headers.Prefer = 'include-annotations="-*"';
+    }
+
+    const result = await this.context._makeRequest<Record<string, Metadata> | string>(url, {
+      headers,
     });
     if (result.error) {
       throw result.error;
@@ -212,9 +124,7 @@ export class Database<
       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`,
-        );
+        throw new Error(`Metadata for database "${this.databaseName}" not found in response`);
       }
       return metadata;
     }
@@ -244,9 +154,11 @@ export class Database<
    * @param options - Optional script parameter and result schema
    * @returns Promise resolving to script execution result
    */
+  // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer
   async runScript<ResultSchema extends StandardSchemaV1<string, any> = never>(
     scriptName: string,
     options?: {
+      // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any record shape
       scriptParam?: string | number | Record<string, any>;
       resultSchema?: ResultSchema;
     },
@@ -280,30 +192,25 @@ export class Database<
 
     // If resultSchema is provided, validate the result through it
     if (options?.resultSchema && response.scriptResult !== undefined) {
-      const validationResult = options.resultSchema["~standard"].validate(
-        response.scriptResult.resultParameter,
-      );
+      const validationResult = options.resultSchema["~standard"].validate(response.scriptResult.resultParameter);
       // Handle both sync and async validation
-      const result =
-        validationResult instanceof Promise
-          ? await validationResult
-          : validationResult;
+      const result = validationResult instanceof Promise ? await validationResult : validationResult;
 
       if (result.issues) {
-        throw new Error(
-          `Script result validation failed: ${JSON.stringify(result.issues)}`,
-        );
+        throw new Error(`Script result validation failed: ${JSON.stringify(result.issues)}`);
       }
 
       return {
         resultCode: response.scriptResult.code,
         result: result.value,
+        // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type
       } as any;
     }
 
     return {
       resultCode: response.scriptResult.code,
       result: response.scriptResult.resultParameter,
+      // biome-ignore lint/suspicious/noExplicitAny: Type assertion for generic return type
     } as any;
   }
 
@@ -326,9 +233,8 @@ export class Database<
    * }
    * ```
    */
-  batch<const Builders extends readonly ExecutableBuilder<any>[]>(
-    builders: Builders,
-  ): BatchBuilder<Builders> {
+  // biome-ignore lint/suspicious/noExplicitAny: Generic constraint accepting any ExecutableBuilder result type
+  batch<const Builders extends readonly ExecutableBuilder<any>[]>(builders: Builders): BatchBuilder<Builders> {
     return new BatchBuilder(builders, this.databaseName, this.context);
   }
 }