@proofkit/fmodata 0.1.0-alpha.13 → 0.1.0-alpha.15

package/dist/esm/client/builders/response-processor.d.ts

@@ -0,0 +1,39 @@
+import { FMTable } from '../../orm/table.js';
+import { Result } from '../../types.js';
+import { ExpandValidationConfig } from '../../validation.js';
+import { ExpandConfig } from './shared-types.js';
+export interface ProcessResponseConfig {
+    table?: FMTable<any, any>;
+    schema?: Record<string, any>;
+    singleMode: "exact" | "maybe" | false;
+    selectedFields?: string[];
+    expandValidationConfigs?: ExpandValidationConfig[];
+    skipValidation?: boolean;
+    useEntityIds?: boolean;
+    fieldMapping?: Record<string, string>;
+}
+/**
+ * Processes OData response with transformation and validation.
+ * Shared by QueryBuilder and RecordBuilder.
+ */
+export declare function processODataResponse<T>(rawResponse: any, config: ProcessResponseConfig): Promise<Result<T>>;
+/**
+ * Gets schema from a table occurrence, excluding container fields.
+ * Container fields are never returned in regular responses (only via getSingleField).
+ */
+export declare function getSchemaFromTable(table: FMTable<any, any> | undefined): Record<string, any> | undefined;
+/**
+ * Processes query response with expand configs.
+ * This is a convenience wrapper that builds validation configs from expand configs.
+ */
+export declare function processQueryResponse<T>(response: any, config: {
+    occurrence?: FMTable<any, any>;
+    singleMode: "exact" | "maybe" | false;
+    queryOptions: {
+        select?: (keyof T)[] | string[];
+    };
+    expandConfigs: ExpandConfig[];
+    skipValidation?: boolean;
+    useEntityIds?: boolean;
+    fieldMapping?: Record<string, string>;
+}): Promise<Result<any>>;

package/dist/esm/client/builders/response-processor.js

@@ -0,0 +1,170 @@
+import { validateSingleResponse, validateListResponse } from "../../validation.js";
+import { transformResponseFields } from "../../transform.js";
+import { RecordCountMismatchError } from "../../errors.js";
+import { getBaseTableConfig } from "../../orm/table.js";
+import { ExpandBuilder } from "./expand-builder.js";
+async function processODataResponse(rawResponse, config) {
+  const {
+    table,
+    schema,
+    singleMode,
+    selectedFields,
+    expandValidationConfigs,
+    skipValidation,
+    useEntityIds,
+    fieldMapping
+  } = config;
+  let response = rawResponse;
+  if (table && useEntityIds) {
+    response = transformResponseFields(
+      response,
+      table,
+      expandValidationConfigs
+    );
+  }
+  if (skipValidation) {
+    const result = extractRecords(response, singleMode);
+    if (result.data && fieldMapping && Object.keys(fieldMapping).length > 0) {
+      if (result.error) {
+        return { data: void 0, error: result.error };
+      }
+      return {
+        data: renameFieldsInResponse(result.data, fieldMapping),
+        error: void 0
+      };
+    }
+    return result;
+  }
+  if (singleMode !== false) {
+    const validation2 = await validateSingleResponse(
+      response,
+      schema,
+      selectedFields,
+      expandValidationConfigs,
+      singleMode
+    );
+    if (!validation2.valid) {
+      return { data: void 0, error: validation2.error };
+    }
+    if (fieldMapping && Object.keys(fieldMapping).length > 0) {
+      return {
+        data: renameFieldsInResponse(validation2.data, fieldMapping),
+        error: void 0
+      };
+    }
+    return { data: validation2.data, error: void 0 };
+  }
+  const validation = await validateListResponse(
+    response,
+    schema,
+    selectedFields,
+    expandValidationConfigs
+  );
+  if (!validation.valid) {
+    return { data: void 0, error: validation.error };
+  }
+  if (fieldMapping && Object.keys(fieldMapping).length > 0) {
+    return {
+      data: renameFieldsInResponse(validation.data, fieldMapping),
+      error: void 0
+    };
+  }
+  return { data: validation.data, error: void 0 };
+}
+function extractRecords(response, singleMode) {
+  if (singleMode === false) {
+    const records2 = response.value ?? [];
+    return { data: records2, error: void 0 };
+  }
+  const records = response.value ?? [response];
+  const count = Array.isArray(records) ? records.length : 1;
+  if (count > 1) {
+    return {
+      data: void 0,
+      error: new RecordCountMismatchError(
+        singleMode === "exact" ? "one" : "at-most-one",
+        count
+      )
+    };
+  }
+  if (count === 0) {
+    if (singleMode === "exact") {
+      return { data: void 0, error: new RecordCountMismatchError("one", 0) };
+    }
+    return { data: null, error: void 0 };
+  }
+  const record = Array.isArray(records) ? records[0] : records;
+  return { data: record, error: void 0 };
+}
+function getSchemaFromTable(table) {
+  if (!table) return void 0;
+  const baseTableConfig = getBaseTableConfig(table);
+  const containerFields = baseTableConfig.containerFields || [];
+  const schema = { ...baseTableConfig.schema };
+  for (const containerField of containerFields) {
+    delete schema[containerField];
+  }
+  return schema;
+}
+function renameFieldsInResponse(data, fieldMapping) {
+  if (!data || typeof data !== "object") {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    return data.map((item) => renameFieldsInResponse(item, fieldMapping));
+  }
+  if ("value" in data && Array.isArray(data.value)) {
+    return {
+      ...data,
+      value: data.value.map(
+        (item) => renameFieldsInResponse(item, fieldMapping)
+      )
+    };
+  }
+  const renamed = {};
+  for (const [key, value] of Object.entries(data)) {
+    const outputKey = fieldMapping[key];
+    if (outputKey) {
+      renamed[outputKey] = value;
+    } else {
+      renamed[key] = value;
+    }
+  }
+  return renamed;
+}
+async function processQueryResponse(response, config) {
+  const {
+    occurrence,
+    singleMode,
+    queryOptions,
+    expandConfigs,
+    skipValidation,
+    useEntityIds,
+    fieldMapping
+  } = config;
+  const expandBuilder = new ExpandBuilder(useEntityIds ?? false);
+  const expandValidationConfigs = expandBuilder.buildValidationConfigs(expandConfigs);
+  const selectedFields = queryOptions.select ? Array.isArray(queryOptions.select) ? queryOptions.select.map(String) : [String(queryOptions.select)] : void 0;
+  let processedResponse = await processODataResponse(response, {
+    table: occurrence,
+    schema: getSchemaFromTable(occurrence),
+    singleMode,
+    selectedFields,
+    expandValidationConfigs,
+    skipValidation,
+    useEntityIds
+  });
+  if (processedResponse.data && fieldMapping && Object.keys(fieldMapping).length > 0) {
+    processedResponse = {
+      ...processedResponse,
+      data: renameFieldsInResponse(processedResponse.data, fieldMapping)
+    };
+  }
+  return processedResponse;
+}
+export {
+  getSchemaFromTable,
+  processODataResponse,
+  processQueryResponse
+};
+//# sourceMappingURL=response-processor.js.map

package/dist/esm/client/builders/response-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-processor.js","sources":["../../../../src/client/builders/response-processor.ts"],"sourcesContent":["import type { FMTable } from \"../../orm/table\";\nimport type { Result } from \"../../types\";\nimport type { ExpandValidationConfig } from \"../../validation\";\nimport { validateSingleResponse, validateListResponse } from \"../../validation\";\nimport { transformResponseFields } from \"../../transform\";\nimport { RecordCountMismatchError } from \"../../errors\";\nimport { getBaseTableConfig } from \"../../orm/table\";\nimport { ExpandBuilder } from \"./expand-builder\";\nimport type { ExpandConfig } from \"./shared-types\";\n\nexport interface ProcessResponseConfig {\n  table?: FMTable<any, any>;\n  schema?: Record<string, any>;\n  singleMode: \"exact\" | \"maybe\" | false;\n  selectedFields?: string[];\n  expandValidationConfigs?: ExpandValidationConfig[];\n  skipValidation?: boolean;\n  useEntityIds?: boolean;\n  // Mapping from field names to output keys (for renamed fields in select)\n  fieldMapping?: Record<string, string>;\n}\n\n/**\n * Processes OData response with transformation and validation.\n * Shared by QueryBuilder and RecordBuilder.\n */\nexport async function processODataResponse<T>(\n  rawResponse: any,\n  config: ProcessResponseConfig,\n): Promise<Result<T>> {\n  const {\n    table,\n    schema,\n    singleMode,\n    selectedFields,\n    expandValidationConfigs,\n    skipValidation,\n    useEntityIds,\n    fieldMapping,\n  } = config;\n\n  // Transform field IDs back to names if using entity IDs\n  let response = rawResponse;\n  if (table && useEntityIds) {\n    response = transformResponseFields(\n      response,\n      table,\n      expandValidationConfigs,\n    );\n  }\n\n  // Fast path: skip validation\n  if (skipValidation) {\n    const result = extractRecords(response, singleMode);\n    // Rename fields AFTER extraction (but before returning)\n    if (result.data && fieldMapping && Object.keys(fieldMapping).length > 0) {\n      if (result.error) {\n        return { data: undefined, error: result.error } as Result<T>;\n      }\n      return {\n        data: renameFieldsInResponse(result.data, fieldMapping) as T,\n        error: undefined,\n      };\n    }\n    return result as Result<T>;\n  }\n\n  // Validation path\n  if (singleMode !== false) {\n    const validation = await validateSingleResponse<any>(\n      response,\n      schema,\n      selectedFields as any,\n      expandValidationConfigs,\n      singleMode,\n    );\n\n    if (!validation.valid) {\n      return { data: undefined, error: validation.error };\n    }\n\n    // Rename fields AFTER validation completes\n    if (fieldMapping && Object.keys(fieldMapping).length > 0) {\n      return {\n        data: renameFieldsInResponse(validation.data, fieldMapping) as T,\n        error: undefined,\n      };\n    }\n\n    return { data: validation.data as T, error: undefined };\n  }\n\n  const validation = await validateListResponse<any>(\n    response,\n    schema,\n    selectedFields as any,\n    expandValidationConfigs,\n  );\n\n  if (!validation.valid) {\n    return { data: undefined, error: validation.error };\n  }\n\n  // Rename fields AFTER validation completes\n  if (fieldMapping && Object.keys(fieldMapping).length > 0) {\n    return {\n      data: renameFieldsInResponse(validation.data, fieldMapping) as T,\n      error: undefined,\n    };\n  }\n\n  return { data: validation.data as T, error: undefined };\n}\n\n/**\n * Extracts records from response without validation.\n */\nfunction extractRecords<T>(\n  response: any,\n  singleMode: \"exact\" | \"maybe\" | false,\n): Result<T> {\n  if (singleMode === false) {\n    const records = response.value ?? [];\n    return { data: records as T, error: undefined };\n  }\n\n  const records = response.value ?? [response];\n  const count = Array.isArray(records) ? records.length : 1;\n\n  if (count > 1) {\n    return {\n      data: undefined,\n      error: new RecordCountMismatchError(\n        singleMode === \"exact\" ? \"one\" : \"at-most-one\",\n        count,\n      ),\n    };\n  }\n\n  if (count === 0) {\n    if (singleMode === \"exact\") {\n      return { data: undefined, error: new RecordCountMismatchError(\"one\", 0) };\n    }\n    return { data: null as T, error: undefined };\n  }\n\n  const record = Array.isArray(records) ? records[0] : records;\n  return { data: record as T, error: undefined };\n}\n\n/**\n * Gets schema from a table occurrence, excluding container fields.\n * Container fields are never returned in regular responses (only via getSingleField).\n */\nexport function getSchemaFromTable(\n  table: FMTable<any, any> | undefined,\n): Record<string, any> | undefined {\n  if (!table) return undefined;\n  const baseTableConfig = getBaseTableConfig(table);\n  const containerFields = baseTableConfig.containerFields || [];\n\n  // Filter out container fields from schema\n  const schema = { ...baseTableConfig.schema };\n  for (const containerField of containerFields) {\n    delete schema[containerField as string];\n  }\n\n  return schema;\n}\n\n/**\n * Renames fields in response data according to the field mapping.\n * Used when select() is called with renamed fields (e.g., { userEmail: users.email }).\n */\nfunction renameFieldsInResponse(\n  data: any,\n  fieldMapping: Record<string, string>,\n): any {\n  if (!data || typeof data !== \"object\") {\n    return data;\n  }\n\n  // Handle array responses\n  if (Array.isArray(data)) {\n    return data.map((item) => renameFieldsInResponse(item, fieldMapping));\n  }\n\n  // Handle OData list response structure\n  if (\"value\" in data && Array.isArray(data.value)) {\n    return {\n      ...data,\n      value: data.value.map((item: any) =>\n        renameFieldsInResponse(item, fieldMapping),\n      ),\n    };\n  }\n\n  // Handle single record\n  const renamed: Record<string, any> = {};\n  for (const [key, value] of Object.entries(data)) {\n    // Check if this field should be renamed\n    const outputKey = fieldMapping[key];\n    if (outputKey) {\n      renamed[outputKey] = value;\n    } else {\n      renamed[key] = value;\n    }\n  }\n  return renamed;\n}\n\n/**\n * Processes query response with expand configs.\n * This is a convenience wrapper that builds validation configs from expand configs.\n */\nexport async function processQueryResponse<T>(\n  response: any,\n  config: {\n    occurrence?: FMTable<any, any>;\n    singleMode: \"exact\" | \"maybe\" | false;\n    queryOptions: { select?: (keyof T)[] | string[] };\n    expandConfigs: ExpandConfig[];\n    skipValidation?: boolean;\n    useEntityIds?: boolean;\n    // Mapping from field names to output keys (for renamed fields in select)\n    fieldMapping?: Record<string, string>;\n  },\n): Promise<Result<any>> {\n  const {\n    occurrence,\n    singleMode,\n    queryOptions,\n    expandConfigs,\n    skipValidation,\n    useEntityIds,\n    fieldMapping,\n  } = config;\n\n  const expandBuilder = new ExpandBuilder(useEntityIds ?? false);\n  const expandValidationConfigs =\n    expandBuilder.buildValidationConfigs(expandConfigs);\n\n  const selectedFields = queryOptions.select\n    ? Array.isArray(queryOptions.select)\n      ? queryOptions.select.map(String)\n      : [String(queryOptions.select)]\n    : undefined;\n\n  // Process the response first\n  let processedResponse = await processODataResponse(response, {\n    table: occurrence,\n    schema: getSchemaFromTable(occurrence),\n    singleMode,\n    selectedFields,\n    expandValidationConfigs,\n    skipValidation,\n    useEntityIds,\n  });\n\n  // Rename fields if field mapping is provided (for renamed fields in select)\n  if (\n    processedResponse.data &&\n    fieldMapping &&\n    Object.keys(fieldMapping).length > 0\n  ) {\n    processedResponse = {\n      ...processedResponse,\n      data: renameFieldsInResponse(processedResponse.data, fieldMapping),\n    };\n  }\n\n  return processedResponse;\n}\n"],"names":["validation","records"],"mappings":"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"}

package/dist/esm/client/builders/select-mixin.d.ts

@@ -0,0 +1,31 @@
+import { Column } from '../../orm/column.js';
+/**
+ * Utility function for processing select() calls.
+ * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+ *
+ * @param fields - Field names or Column references
+ * @returns Object with selectedFields array
+ */
+export declare function processSelectFields(...fields: (string | Column<any, string>)[]): {
+    selectedFields: string[];
+};
+/**
+ * Processes select() calls with field renaming support.
+ * Validates columns belong to the correct table and builds field mapping for renamed fields.
+ * Used by both QueryBuilder and RecordBuilder to eliminate duplication.
+ *
+ * @param fields - Object mapping output keys to column references
+ * @param tableName - Expected table name for validation
+ * @returns Object with selectedFields array and fieldMapping for renamed fields
+ */
+export declare function processSelectWithRenames<TTableName extends string>(fields: Record<string, Column<any, TTableName>>, tableName: string): {
+    selectedFields: string[];
+    fieldMapping: Record<string, string>;
+};
+/**
+ * Legacy class name for backward compatibility.
+ * @deprecated Use processSelectFields function instead
+ */
+export declare class SelectMixin {
+    static processSelect: typeof processSelectFields;
+}

package/dist/esm/client/builders/select-mixin.js

@@ -0,0 +1,30 @@
+import { isColumn } from "../../orm/column.js";
+function processSelectWithRenames(fields, tableName) {
+  const selectedFields = [];
+  const fieldMapping = {};
+  for (const [outputKey, column] of Object.entries(fields)) {
+    if (!isColumn(column)) {
+      throw new Error(
+        `select() expects column references, but got: ${typeof column}`
+      );
+    }
+    if (column.tableName !== tableName) {
+      console.warn(
+        `Column ${column.toString()} is from table "${column.tableName}", but query is for table "${tableName}"`
+      );
+    }
+    const fieldName = column.fieldName;
+    selectedFields.push(fieldName);
+    if (fieldName !== outputKey) {
+      fieldMapping[fieldName] = outputKey;
+    }
+  }
+  return {
+    selectedFields,
+    fieldMapping: Object.keys(fieldMapping).length > 0 ? fieldMapping : {}
+  };
+}
+export {
+  processSelectWithRenames
+};
+//# sourceMappingURL=select-mixin.js.map

package/dist/esm/client/builders/select-mixin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-mixin.js","sources":["../../../../src/client/builders/select-mixin.ts"],"sourcesContent":["import { isColumn, type Column } from \"../../orm/column\";\n\n/**\n * Utility function for processing select() calls.\n * Used by both QueryBuilder and RecordBuilder to eliminate duplication.\n *\n * @param fields - Field names or Column references\n * @returns Object with selectedFields array\n */\nexport function processSelectFields(\n  ...fields: (string | Column<any, string>)[]\n): { selectedFields: string[] } {\n  const fieldNames = fields.map((field) => {\n    if (isColumn(field)) {\n      return field.fieldName as string;\n    }\n    return String(field);\n  });\n  return { selectedFields: [...new Set(fieldNames)] };\n}\n\n/**\n * Processes select() calls with field renaming support.\n * Validates columns belong to the correct table and builds field mapping for renamed fields.\n * Used by both QueryBuilder and RecordBuilder to eliminate duplication.\n *\n * @param fields - Object mapping output keys to column references\n * @param tableName - Expected table name for validation\n * @returns Object with selectedFields array and fieldMapping for renamed fields\n */\nexport function processSelectWithRenames<TTableName extends string>(\n  fields: Record<string, Column<any, TTableName>>,\n  tableName: string,\n): { selectedFields: string[]; fieldMapping: Record<string, string> } {\n  const selectedFields: string[] = [];\n  const fieldMapping: Record<string, string> = {};\n\n  for (const [outputKey, column] of Object.entries(fields)) {\n    if (!isColumn(column)) {\n      throw new Error(\n        `select() expects column references, but got: ${typeof column}`,\n      );\n    }\n\n    // Warn (not throw) on table mismatch for consistency\n    if (column.tableName !== tableName) {\n      console.warn(\n        `Column ${column.toString()} is from table \"${column.tableName}\", but query is for table \"${tableName}\"`,\n      );\n    }\n\n    const fieldName = column.fieldName;\n    selectedFields.push(fieldName);\n\n    // Build mapping from field name to output key (only if renamed)\n    if (fieldName !== outputKey) {\n      fieldMapping[fieldName] = outputKey;\n    }\n  }\n\n  return {\n    selectedFields,\n    fieldMapping: Object.keys(fieldMapping).length > 0 ? fieldMapping : {},\n  };\n}\n\n/**\n * Legacy class name for backward compatibility.\n * @deprecated Use processSelectFields function instead\n */\nexport class SelectMixin {\n  static processSelect = processSelectFields;\n}\n\n"],"names":[],"mappings":";AA8BgB,SAAA,yBACd,QACA,WACoE;AACpE,QAAM,iBAA2B,CAAC;AAClC,QAAM,eAAuC,CAAC;AAE9C,aAAW,CAAC,WAAW,MAAM,KAAK,OAAO,QAAQ,MAAM,GAAG;AACpD,QAAA,CAAC,SAAS,MAAM,GAAG;AACrB,YAAM,IAAI;AAAA,QACR,gDAAgD,OAAO,MAAM;AAAA,MAC/D;AAAA,IAAA;AAIE,QAAA,OAAO,cAAc,WAAW;AAC1B,cAAA;AAAA,QACN,UAAU,OAAO,UAAU,mBAAmB,OAAO,SAAS,8BAA8B,SAAS;AAAA,MACvG;AAAA,IAAA;AAGF,UAAM,YAAY,OAAO;AACzB,mBAAe,KAAK,SAAS;AAG7B,QAAI,cAAc,WAAW;AAC3B,mBAAa,SAAS,IAAI;AAAA,IAAA;AAAA,EAC5B;AAGK,SAAA;AAAA,IACL;AAAA,IACA,cAAc,OAAO,KAAK,YAAY,EAAE,SAAS,IAAI,eAAe,CAAA;AAAA,EACtE;AACF;"}

package/dist/esm/client/builders/select-utils.d.ts

@@ -0,0 +1,8 @@
+import { FMTable } from '../../orm/table.js';
+/**
+ * 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 declare function formatSelectFields(select: string[] | readonly string[] | undefined, table?: FMTable<any, any>, useEntityIds?: boolean): string;

package/dist/esm/client/builders/select-utils.js

@@ -0,0 +1,15 @@
+import { transformFieldNamesArray } from "../../transform.js";
+function formatSelectFields(select, table, useEntityIds) {
+  if (!select || select.length === 0) return "";
+  const selectArray = Array.isArray(select) ? select : [select];
+  const transformedFields = table && useEntityIds ? transformFieldNamesArray(selectArray.map(String), table) : selectArray.map(String);
+  return transformedFields.map((field) => {
+    if (field === "id") return `"id"`;
+    const encoded = encodeURIComponent(field);
+    return encoded.replace(/%20/g, " ");
+  }).join(",");
+}
+export {
+  formatSelectFields
+};
+//# sourceMappingURL=select-utils.js.map

package/dist/esm/client/builders/select-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-utils.js","sources":["../../../../src/client/builders/select-utils.ts"],"sourcesContent":["import type { FMTable } from \"../../orm/table\";\nimport { transformFieldNamesArray } from \"../../transform\";\n\n/**\n * Formats select fields for use in OData query strings.\n * - Transforms field names to FMFIDs if using entity IDs\n * - Wraps \"id\" fields in double quotes (OData reserved)\n * - URL-encodes special characters but preserves spaces\n */\nexport function formatSelectFields(\n  select: string[] | readonly string[] | undefined,\n  table?: FMTable<any, any>,\n  useEntityIds?: boolean,\n): string {\n  if (!select || select.length === 0) return \"\";\n\n  const selectArray = Array.isArray(select) ? select : [select];\n\n  // Transform to field IDs if using entity IDs\n  const transformedFields =\n    table && useEntityIds\n      ? transformFieldNamesArray(selectArray.map(String), table)\n      : selectArray.map(String);\n\n  return transformedFields\n    .map((field) => {\n      if (field === \"id\") return `\"id\"`;\n      const encoded = encodeURIComponent(field);\n      return encoded.replace(/%20/g, \" \");\n    })\n    .join(\",\");\n}\n\n\n"],"names":[],"mappings":";AASgB,SAAA,mBACd,QACA,OACA,cACQ;AACR,MAAI,CAAC,UAAU,OAAO,WAAW,EAAU,QAAA;AAE3C,QAAM,cAAc,MAAM,QAAQ,MAAM,IAAI,SAAS,CAAC,MAAM;AAG5D,QAAM,oBACJ,SAAS,eACL,yBAAyB,YAAY,IAAI,MAAM,GAAG,KAAK,IACvD,YAAY,IAAI,MAAM;AAErB,SAAA,kBACJ,IAAI,CAAC,UAAU;AACV,QAAA,UAAU,KAAa,QAAA;AACrB,UAAA,UAAU,mBAAmB,KAAK;AACjC,WAAA,QAAQ,QAAQ,QAAQ,GAAG;AAAA,EAAA,CACnC,EACA,KAAK,GAAG;AACb;"}

package/dist/esm/client/builders/shared-types.d.ts

@@ -0,0 +1,39 @@
+import { QueryOptions } from 'odata-query';
+import { ExecutionContext } from '../../types.js';
+import { FMTable } from '../../orm/table.js';
+/**
+ * Expand configuration used by both QueryBuilder and RecordBuilder
+ */
+export type ExpandConfig = {
+    relation: string;
+    options?: Partial<QueryOptions<any>>;
+    targetTable?: FMTable<any, any>;
+};
+/**
+ * Type to represent expanded relations in return types
+ */
+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
+ */
+export interface BuilderConfig<Occ extends FMTable<any, any> | undefined> {
+    occurrence?: Occ;
+    tableName: string;
+    databaseName: string;
+    context: ExecutionContext;
+    databaseUseEntityIds?: boolean;
+}

package/dist/esm/client/builders/table-utils.d.ts

@@ -0,0 +1,35 @@
+import { ExecutionContext, ExecuteOptions } from '../../types.js';
+import { FMTable } from '../../orm/table.js';
+import { FFetchOptions } from '@fetchkit/ffetch';
+/**
+ * Resolves table identifier based on entity ID settings.
+ * Used by both QueryBuilder and RecordBuilder.
+ */
+export declare function resolveTableId(table: FMTable<any, any> | undefined, fallbackTableName: string, context: ExecutionContext, useEntityIdsOverride?: boolean): string;
+/**
+ * Merges database-level useEntityIds with per-request options.
+ */
+export declare function mergeEntityIdOptions<T extends Record<string, any>>(options: T | undefined, databaseDefault: boolean): T & {
+    useEntityIds?: boolean;
+};
+/**
+ * Type-safe helper for merging execute options with entity ID settings
+ */
+export declare function mergeExecuteOptions(options: (RequestInit & FFetchOptions & ExecuteOptions) | undefined, databaseUseEntityIds: boolean): RequestInit & FFetchOptions & {
+    useEntityIds?: boolean;
+};
+/**
+ * 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 declare function createODataRequest(baseUrl: string, config: {
+    method: string;
+    url: string;
+}, options?: {
+    includeODataAnnotations?: boolean;
+}): Request;

package/dist/esm/client/builders/table-utils.js

@@ -0,0 +1,45 @@
+import { getAcceptHeader } from "../../types.js";
+import { isUsingEntityIds, getTableName, getTableId } from "../../orm/table.js";
+function resolveTableId(table, fallbackTableName, context, useEntityIdsOverride) {
+  var _a;
+  if (!table) {
+    return fallbackTableName;
+  }
+  const contextDefault = ((_a = context._getUseEntityIds) == null ? void 0 : _a.call(context)) ?? 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 getTableId(table);
+  }
+  return getTableName(table);
+}
+function mergeEntityIdOptions(options, databaseDefault) {
+  return {
+    ...options,
+    useEntityIds: (options == null ? void 0 : options.useEntityIds) ?? databaseDefault
+  };
+}
+function mergeExecuteOptions(options, databaseUseEntityIds) {
+  return mergeEntityIdOptions(options, databaseUseEntityIds);
+}
+function createODataRequest(baseUrl, config, options) {
+  const fullUrl = `${baseUrl}${config.url}`;
+  return new Request(fullUrl, {
+    method: config.method,
+    headers: {
+      "Content-Type": "application/json",
+      Accept: getAcceptHeader(options == null ? void 0 : options.includeODataAnnotations)
+    }
+  });
+}
+export {
+  createODataRequest,
+  mergeEntityIdOptions,
+  mergeExecuteOptions,
+  resolveTableId
+};
+//# sourceMappingURL=table-utils.js.map

package/dist/esm/client/builders/table-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-utils.js","sources":["../../../../src/client/builders/table-utils.ts"],"sourcesContent":["import type { ExecutionContext } from \"../../types\";\nimport { getAcceptHeader } from \"../../types\";\nimport type { FMTable } from \"../../orm/table\";\nimport {\n  getTableName,\n  getTableId as getTableIdHelper,\n  isUsingEntityIds,\n} from \"../../orm/table\";\nimport type { FFetchOptions } from \"@fetchkit/ffetch\";\nimport type { ExecuteOptions } from \"../../types\";\n\n/**\n * Resolves table identifier based on entity ID settings.\n * Used by both QueryBuilder and RecordBuilder.\n */\nexport function resolveTableId(\n  table: FMTable<any, any> | undefined,\n  fallbackTableName: string,\n  context: ExecutionContext,\n  useEntityIdsOverride?: boolean,\n): string {\n  if (!table) {\n    return fallbackTableName;\n  }\n\n  const contextDefault = context._getUseEntityIds?.() ?? false;\n  const shouldUseIds = useEntityIdsOverride ?? contextDefault;\n\n  if (shouldUseIds) {\n    if (!isUsingEntityIds(table)) {\n      throw new Error(\n        `useEntityIds is true but table \"${getTableName(table)}\" does not have entity IDs configured`,\n      );\n    }\n    return getTableIdHelper(table);\n  }\n\n  return getTableName(table);\n}\n\n/**\n * Merges database-level useEntityIds with per-request options.\n */\nexport function mergeEntityIdOptions<T extends Record<string, any>>(\n  options: T | undefined,\n  databaseDefault: boolean,\n): T & { useEntityIds?: boolean } {\n  return {\n    ...options,\n    useEntityIds: (options as any)?.useEntityIds ?? databaseDefault,\n  } as T & { useEntityIds?: boolean };\n}\n\n/**\n * Type-safe helper for merging execute options with entity ID settings\n */\nexport function mergeExecuteOptions(\n  options: (RequestInit & FFetchOptions & ExecuteOptions) | undefined,\n  databaseUseEntityIds: boolean,\n): RequestInit & FFetchOptions & { useEntityIds?: boolean } {\n  return mergeEntityIdOptions(options, databaseUseEntityIds);\n}\n\n/**\n * Creates an OData Request object with proper headers.\n * Used by both QueryBuilder and RecordBuilder to eliminate duplication.\n *\n * @param baseUrl - Base URL for the request\n * @param config - Request configuration with method and url\n * @param options - Optional execution options\n * @returns Request object ready to use\n */\nexport function createODataRequest(\n  baseUrl: string,\n  config: { method: string; url: string },\n  options?: { includeODataAnnotations?: boolean },\n): Request {\n  const fullUrl = `${baseUrl}${config.url}`;\n\n  return new Request(fullUrl, {\n    method: config.method,\n    headers: {\n      \"Content-Type\": \"application/json\",\n      Accept: getAcceptHeader(options?.includeODataAnnotations),\n    },\n  });\n}\n"],"names":["getTableIdHelper"],"mappings":";;AAeO,SAAS,eACd,OACA,mBACA,SACA,sBACQ;;AACR,MAAI,CAAC,OAAO;AACH,WAAA;AAAA,EAAA;AAGH,QAAA,mBAAiB,aAAQ,qBAAR,qCAAgC;AACvD,QAAM,eAAe,wBAAwB;AAE7C,MAAI,cAAc;AACZ,QAAA,CAAC,iBAAiB,KAAK,GAAG;AAC5B,YAAM,IAAI;AAAA,QACR,mCAAmC,aAAa,KAAK,CAAC;AAAA,MACxD;AAAA,IAAA;AAEF,WAAOA,WAAiB,KAAK;AAAA,EAAA;AAG/B,SAAO,aAAa,KAAK;AAC3B;AAKgB,SAAA,qBACd,SACA,iBACgC;AACzB,SAAA;AAAA,IACL,GAAG;AAAA,IACH,eAAe,mCAAiB,iBAAgB;AAAA,EAClD;AACF;AAKgB,SAAA,oBACd,SACA,sBAC0D;AACnD,SAAA,qBAAqB,SAAS,oBAAoB;AAC3D;AAWgB,SAAA,mBACd,SACA,QACA,SACS;AACT,QAAM,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG;AAEhC,SAAA,IAAI,QAAQ,SAAS;AAAA,IAC1B,QAAQ,OAAO;AAAA,IACf,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,QAAQ,gBAAgB,mCAAS,uBAAuB;AAAA,IAAA;AAAA,EAC1D,CACD;AACH;"}

package/dist/esm/client/database.d.ts

@@ -1,24 +1,15 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { ExecutionContext, ExecutableBuilder, Metadata } from '../types.js';
-import { BaseTable } from './base-table.js';
-import { TableOccurrence } from './table-occurrence.js';
 import { EntitySet } from './entity-set.js';
 import { BatchBuilder } from './batch-builder.js';
 import { SchemaManager } from './schema-manager.js';
-type ExtractSchemaFromOccurrence<O> = O extends TableOccurrence<infer BT, any, any, any> ? BT extends BaseTable<infer S, any, any, any> ? S : never : never;
-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;
-type ExtractOccurrenceNames<Occurrences extends readonly TableOccurrence<any, any, any, any>[]> = Occurrences extends readonly [] ? string : Occurrences[number]["name"];
-export declare class Database<Occurrences extends readonly TableOccurrence<any, any, any, any>[] = readonly []> {
+import { FMTable } from '../orm/table.js';
+export declare class Database {
     private readonly databaseName;
     private readonly context;
-    private occurrenceMap;
     private _useEntityIds;
     readonly schema: SchemaManager;
     constructor(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
@@ -26,16 +17,7 @@ export declare class Database<Occurrences extends readonly TableOccurrence<any,
          */
         useEntityIds?: boolean;
     });
-    /**
-     * Returns true if any table occurrence in this database is using entity IDs.
-     */
-    isUsingEntityIds(): boolean;
-    /**
-     * Gets a table occurrence by name.
-     * @internal
-     */
-    getOccurrence(name: string): TableOccurrence<any, any, any, any> | undefined;
-    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>;
+    from<T extends FMTable<any, any>>(table: T): EntitySet<T>;
     /**
      * Retrieves the OData metadata for this database.
      * @param args Optional configuration object
@@ -95,4 +77,3 @@ export declare class Database<Occurrences extends readonly TableOccurrence<any,
      */
     batch<const Builders extends readonly ExecutableBuilder<any>[]>(builders: Builders): BatchBuilder<Builders>;
 }
-export {};

package/dist/esm/client/database.js

@@ -4,91 +4,29 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 import { EntitySet } from "./entity-set.js";
 import { BatchBuilder } from "./batch-builder.js";
 import { SchemaManager } from "./schema-manager.js";
+import { FMTable } from "../orm/table.js";
 class Database {
   constructor(databaseName, context, config) {
-    __publicField(this, "occurrenceMap");
     __publicField(this, "_useEntityIds", false);
     __publicField(this, "schema");
     this.databaseName = databaseName;
     this.context = context;
-    this.occurrenceMap = /* @__PURE__ */ new Map();
-    if (config == null ? void 0 : config.occurrences) {
-      const occurrencesWithIds = [];
-      const occurrencesWithoutIds = [];
-      for (const occ of config.occurrences) {
-        this.occurrenceMap.set(occ.name, occ);
-        const hasTableId = occ.isUsingTableId();
-        const hasFieldIds = occ.baseTable.isUsingFieldIds();
-        if (hasTableId && hasFieldIds) {
-          occurrencesWithIds.push(occ.name);
-        } else if (!hasTableId && !hasFieldIds) {
-          occurrencesWithoutIds.push(occ.name);
-        } else {
-          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.`
-          );
-        }
-      }
-      const allOccurrencesUseEntityIds = occurrencesWithIds.length > 0 && occurrencesWithoutIds.length === 0;
-      const hasMixedUsage = occurrencesWithIds.length > 0 && occurrencesWithoutIds.length > 0;
-      if (config.useEntityIds !== void 0) {
-        if (config.useEntityIds === false) {
-          this._useEntityIds = false;
-        } else if (config.useEntityIds === true) {
-          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 {
-        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 {
-      this._useEntityIds = (config == null ? void 0 : config.useEntityIds) ?? false;
-    }
-    if (this.context._setUseEntityIds) {
-      this.context._setUseEntityIds(this._useEntityIds);
-    }
     this.schema = new SchemaManager(this.databaseName, this.context);
+    this._useEntityIds = (config == null ? void 0 : config.useEntityIds) ?? false;
   }
-  /**
-   * Returns true if any table occurrence in this database is using entity IDs.
-   */
-  isUsingEntityIds() {
-    return this._useEntityIds;
-  }
-  /**
-   * Gets a table occurrence by name.
-   * @internal
-   */
-  getOccurrence(name) {
-    return this.occurrenceMap.get(name);
-  }
-  from(name) {
-    const occurrence = this.occurrenceMap.get(name);
-    if (occurrence) {
-      return EntitySet.create({
-        occurrence,
-        tableName: name,
-        databaseName: this.databaseName,
-        context: this.context,
-        database: this
-      });
-    } else {
-      return new EntitySet({
-        tableName: name,
-        databaseName: this.databaseName,
-        context: this.context,
-        database: this
-      });
+  from(table) {
+    if (Object.prototype.hasOwnProperty.call(table, FMTable.Symbol.UseEntityIds)) {
+      const tableUseEntityIds = table[FMTable.Symbol.UseEntityIds];
+      if (typeof tableUseEntityIds === "boolean") {
+        this._useEntityIds = tableUseEntityIds;
+      }
     }
+    return new EntitySet({
+      occurrence: table,
+      databaseName: this.databaseName,
+      context: this.context,
+      database: this
+    });
   }
   async getMetadata(args) {
     const result = await this.context._makeRequest(`/${this.databaseName}/$metadata`, {