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

package/src/errors.ts

@@ -0,0 +1,217 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/**
+ * Base class for all fmodata errors
+ */
+export abstract class FMODataError extends Error {
+  abstract readonly kind: string;
+  readonly timestamp: Date;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = this.constructor.name;
+    this.timestamp = new Date();
+  }
+}
+
+// ============================================
+// HTTP Errors (with status codes)
+// ============================================
+
+export class HTTPError extends FMODataError {
+  readonly kind = "HTTPError" as const;
+  readonly url: string;
+  readonly status: number;
+  readonly statusText: string;
+  readonly response?: any;
+
+  constructor(url: string, status: number, statusText: string, response?: any) {
+    super(`HTTP ${status} ${statusText} for ${url}`);
+    this.url = url;
+    this.status = status;
+    this.statusText = statusText;
+    this.response = response;
+  }
+
+  // Helper methods for common status checks
+  is4xx(): boolean {
+    return this.status >= 400 && this.status < 500;
+  }
+
+  is5xx(): boolean {
+    return this.status >= 500 && this.status < 600;
+  }
+
+  isNotFound(): boolean {
+    return this.status === 404;
+  }
+
+  isUnauthorized(): boolean {
+    return this.status === 401;
+  }
+
+  isForbidden(): boolean {
+    return this.status === 403;
+  }
+}
+
+// ============================================
+// OData Specific Errors
+// ============================================
+
+export class ODataError extends FMODataError {
+  readonly kind = "ODataError" as const;
+  readonly url: string;
+  readonly code?: string;
+  readonly details?: any;
+
+  constructor(url: string, message: string, code?: string, details?: any) {
+    super(`OData error: ${message}`);
+    this.url = url;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class SchemaLockedError extends FMODataError {
+  readonly kind = "SchemaLockedError" as const;
+  readonly url: string;
+  readonly code: string;
+  readonly details?: any;
+
+  constructor(url: string, message: string, details?: any) {
+    super(`OData error: ${message}`);
+    this.url = url;
+    this.code = "303";
+    this.details = details;
+  }
+}
+
+// ============================================
+// Validation Errors
+// ============================================
+
+export class ValidationError extends FMODataError {
+  readonly kind = "ValidationError" as const;
+  readonly field?: string;
+  readonly issues: readonly StandardSchemaV1.Issue[];
+  readonly value?: unknown;
+
+  constructor(
+    message: string,
+    issues: readonly StandardSchemaV1.Issue[],
+    options?: {
+      field?: string;
+      value?: unknown;
+      cause?: Error["cause"];
+    },
+  ) {
+    super(
+      message,
+      options?.cause !== undefined ? { cause: options.cause } : undefined,
+    );
+    this.field = options?.field;
+    this.issues = issues;
+    this.value = options?.value;
+  }
+}
+
+export class ResponseStructureError extends FMODataError {
+  readonly kind = "ResponseStructureError" as const;
+  readonly expected: string;
+  readonly received: any;
+
+  constructor(expected: string, received: any) {
+    super(`Invalid response structure: expected ${expected}`);
+    this.expected = expected;
+    this.received = received;
+  }
+}
+
+export class RecordCountMismatchError extends FMODataError {
+  readonly kind = "RecordCountMismatchError" as const;
+  readonly expected: number | "one" | "at-most-one";
+  readonly received: number;
+
+  constructor(expected: number | "one" | "at-most-one", received: number) {
+    const expectedStr = typeof expected === "number" ? expected : expected;
+    super(`Expected ${expectedStr} record(s), but received ${received}`);
+    this.expected = expected;
+    this.received = received;
+  }
+}
+
+export class InvalidLocationHeaderError extends FMODataError {
+  readonly kind = "InvalidLocationHeaderError" as const;
+  readonly locationHeader?: string;
+
+  constructor(message: string, locationHeader?: string) {
+    super(message);
+    this.locationHeader = locationHeader;
+  }
+}
+
+// ============================================
+// Type Guards
+// ============================================
+
+export function isHTTPError(error: unknown): error is HTTPError {
+  return error instanceof HTTPError;
+}
+
+export function isValidationError(error: unknown): error is ValidationError {
+  return error instanceof ValidationError;
+}
+
+export function isODataError(error: unknown): error is ODataError {
+  return error instanceof ODataError;
+}
+
+export function isSchemaLockedError(
+  error: unknown,
+): error is SchemaLockedError {
+  return error instanceof SchemaLockedError;
+}
+
+export function isResponseStructureError(
+  error: unknown,
+): error is ResponseStructureError {
+  return error instanceof ResponseStructureError;
+}
+
+export function isRecordCountMismatchError(
+  error: unknown,
+): error is RecordCountMismatchError {
+  return error instanceof RecordCountMismatchError;
+}
+
+export function isFMODataError(error: unknown): error is FMODataError {
+  return error instanceof FMODataError;
+}
+
+// ============================================
+// Union type for all possible errors
+// ============================================
+
+// Re-export ffetch errors (they'll be imported from @fetchkit/ffetch)
+export type {
+  TimeoutError,
+  AbortError,
+  NetworkError,
+  RetryLimitError,
+  CircuitOpenError,
+} from "@fetchkit/ffetch";
+
+export type FMODataErrorType =
+  | import("@fetchkit/ffetch").TimeoutError
+  | import("@fetchkit/ffetch").AbortError
+  | import("@fetchkit/ffetch").NetworkError
+  | import("@fetchkit/ffetch").RetryLimitError
+  | import("@fetchkit/ffetch").CircuitOpenError
+  | HTTPError
+  | ODataError
+  | SchemaLockedError
+  | ValidationError
+  | ResponseStructureError
+  | RecordCountMismatchError
+  | InvalidLocationHeaderError;

package/src/index.ts

@@ -1,8 +1,10 @@
 // Barrel file - exports all public API from the client folder
-export { BaseTable } from "./client/base-table";
+export { BaseTable, BaseTableWithIds } from "./client/base-table";
 export {
   TableOccurrence,
   createTableOccurrence,
+  TableOccurrenceWithIds,
+  createTableOccurrenceWithIds,
 } from "./client/table-occurrence";
 export { FMServerConnection } from "./client/filemaker-odata";
 
@@ -10,6 +12,16 @@ export { FMServerConnection } from "./client/filemaker-odata";
 // Users get these instances from the builder pattern, not by direct instantiation
 export type { Database } from "./client/database";
 export type { EntitySet } from "./client/entity-set";
+export type {
+  SchemaManager,
+  Field,
+  StringField,
+  NumericField,
+  DateField,
+  TimeField,
+  TimestampField,
+  ContainerField,
+} from "./client/schema-manager";
 
 // Utility types for type annotations
 export type {
@@ -18,6 +30,7 @@ export type {
   InsertData,
   UpdateData,
   ODataRecordMetadata,
+  Metadata,
 } from "./types";
 
 // Filter types
@@ -31,3 +44,32 @@ export type {
   DateOperators,
   LogicalFilter,
 } from "./filter-types";
+
+// Re-export ffetch errors
+export {
+  TimeoutError,
+  AbortError,
+  NetworkError,
+  RetryLimitError,
+  CircuitOpenError,
+} from "@fetchkit/ffetch";
+
+// Export our errors
+export {
+  FMODataError,
+  HTTPError,
+  ODataError,
+  SchemaLockedError,
+  ValidationError,
+  ResponseStructureError,
+  RecordCountMismatchError,
+  isHTTPError,
+  isValidationError,
+  isODataError,
+  isSchemaLockedError,
+  isResponseStructureError,
+  isRecordCountMismatchError,
+  isFMODataError,
+} from "./errors";
+
+export type { FMODataErrorType } from "./errors";

package/src/transform.ts

@@ -0,0 +1,249 @@
+import type { BaseTable } from "./client/base-table";
+import type { TableOccurrence } from "./client/table-occurrence";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/**
+ * Transforms field names to FileMaker field IDs (FMFID) in an object
+ * @param data - Object with field names as keys
+ * @param baseTable - BaseTable instance to get field IDs from
+ * @returns Object with FMFID keys instead of field names
+ */
+export function transformFieldNamesToIds<T extends Record<string, any>>(
+  data: T,
+  baseTable: BaseTable<any, any, any, any>,
+): Record<string, any> {
+  if (!baseTable.isUsingFieldIds()) {
+    return data;
+  }
+
+  const transformed: Record<string, any> = {};
+  for (const [fieldName, value] of Object.entries(data)) {
+    const fieldId = baseTable.getFieldId(fieldName as any);
+    transformed[fieldId] = value;
+  }
+  return transformed;
+}
+
+/**
+ * Transforms FileMaker field IDs (FMFID) to field names in an object
+ * @param data - Object with FMFID keys
+ * @param baseTable - BaseTable instance to get field names from
+ * @returns Object with field names as keys instead of FMFIDs
+ */
+export function transformFieldIdsToNames<T extends Record<string, any>>(
+  data: T,
+  baseTable: BaseTable<any, any, any, any>,
+): Record<string, any> {
+  if (!baseTable.isUsingFieldIds()) {
+    return data;
+  }
+
+  const transformed: Record<string, any> = {};
+  for (const [key, value] of Object.entries(data)) {
+    // Check if this is an OData metadata field (starts with @)
+    if (key.startsWith("@")) {
+      transformed[key] = value;
+      continue;
+    }
+
+    const fieldName = baseTable.getFieldName(key);
+    transformed[fieldName] = value;
+  }
+  return transformed;
+}
+
+/**
+ * Transforms a field name to FMFID or returns the field name if not using IDs
+ * @param fieldName - The field name to transform
+ * @param baseTable - BaseTable instance to get field ID from
+ * @returns The FMFID or field name
+ */
+export function transformFieldName(
+  fieldName: string,
+  baseTable: BaseTable<any, any, any, any>,
+): string {
+  return baseTable.getFieldId(fieldName as any);
+}
+
+/**
+ * Transforms a table occurrence name to FMTID or returns the name if not using IDs
+ * @param occurrence - TableOccurrence instance to get table ID from
+ * @returns The FMTID or table name
+ */
+export function transformTableName(
+  occurrence: TableOccurrence<any, any, any, any>,
+): string {
+  return occurrence.getTableId();
+}
+
+/**
+ * Gets both table name and ID from an occurrence
+ * @param occurrence - TableOccurrence instance
+ * @returns Object with name (always present) and id (may be undefined if not using IDs)
+ */
+export function getTableIdentifiers(
+  occurrence: TableOccurrence<any, any, any, any>,
+): { name: string; id: string | undefined } {
+  return {
+    name: occurrence.getTableName(),
+    id: occurrence.isUsingTableId() ? occurrence.getTableId() : undefined,
+  };
+}
+
+/**
+ * Transforms response data by converting field IDs back to field names recursively.
+ * Handles both single records and arrays of records, as well as nested expand relationships.
+ *
+ * @param data - Response data from FileMaker (can be single record, array, or wrapped in value property)
+ * @param baseTable - BaseTable instance for the main table
+ * @param expandConfigs - Configuration for expanded relations (optional)
+ * @returns Transformed data with field names instead of IDs
+ */
+export function transformResponseFields(
+  data: any,
+  baseTable: BaseTable<any, any, any, any>,
+  expandConfigs?: Array<{
+    relation: string;
+    occurrence?: TableOccurrence<any, any, any, any>;
+  }>,
+): any {
+  if (!baseTable.isUsingFieldIds()) {
+    return data;
+  }
+
+  // Handle null/undefined
+  if (data === null || data === undefined) {
+    return data;
+  }
+
+  // Handle OData list response with value array
+  if (data.value && Array.isArray(data.value)) {
+    return {
+      ...data,
+      value: data.value.map((record: any) =>
+        transformSingleRecord(record, baseTable, expandConfigs),
+      ),
+    };
+  }
+
+  // Handle array of records
+  if (Array.isArray(data)) {
+    return data.map((record) =>
+      transformSingleRecord(record, baseTable, expandConfigs),
+    );
+  }
+
+  // Handle single record
+  return transformSingleRecord(data, baseTable, expandConfigs);
+}
+
+/**
+ * Transforms a single record, converting field IDs to names and handling nested expands
+ */
+function transformSingleRecord(
+  record: any,
+  baseTable: BaseTable<any, any, any, any>,
+  expandConfigs?: Array<{
+    relation: string;
+    occurrence?: TableOccurrence<any, any, any, any>;
+  }>,
+): any {
+  if (!record || typeof record !== "object") {
+    return record;
+  }
+
+  const transformed: Record<string, any> = {};
+
+  for (const [key, value] of Object.entries(record)) {
+    // Preserve OData metadata fields
+    if (key.startsWith("@")) {
+      transformed[key] = value;
+      continue;
+    }
+
+    // Check if this is an expanded relation (by relation name)
+    let expandConfig = expandConfigs?.find((ec) => ec.relation === key);
+
+    // If not found by relation name, check if this key is a FMTID
+    // (FileMaker returns expanded relations with FMTID keys when using entity IDs)
+    if (!expandConfig && key.startsWith("FMTID:")) {
+      expandConfig = expandConfigs?.find(
+        (ec) =>
+          ec.occurrence &&
+          ec.occurrence.isUsingTableId() &&
+          ec.occurrence.getTableId() === key,
+      );
+    }
+
+    if (expandConfig && expandConfig.occurrence) {
+      // Transform the expanded relation data recursively
+      // Use the relation name (not the FMTID) as the key
+      const relationKey = expandConfig.relation;
+
+      if (Array.isArray(value)) {
+        transformed[relationKey] = value.map((nestedRecord) =>
+          transformSingleRecord(
+            nestedRecord,
+            expandConfig.occurrence!.baseTable,
+            undefined, // Don't pass nested expand configs for now
+          ),
+        );
+      } else if (value && typeof value === "object") {
+        transformed[relationKey] = transformSingleRecord(
+          value,
+          expandConfig.occurrence.baseTable,
+          undefined,
+        );
+      } else {
+        transformed[relationKey] = value;
+      }
+      continue;
+    }
+
+    // Transform field ID to field name
+    const fieldName = baseTable.getFieldName(key);
+    transformed[fieldName] = value;
+  }
+
+  return transformed;
+}
+
+/**
+ * Transforms an array of field names to FMFIDs
+ * @param fieldNames - Array of field names
+ * @param baseTable - BaseTable instance to get field IDs from
+ * @returns Array of FMFIDs or field names
+ */
+export function transformFieldNamesArray(
+  fieldNames: string[],
+  baseTable: BaseTable<any, any, any, any>,
+): string[] {
+  if (!baseTable.isUsingFieldIds()) {
+    return fieldNames;
+  }
+
+  return fieldNames.map((fieldName) => baseTable.getFieldId(fieldName as any));
+}
+
+/**
+ * Transforms a field name in an orderBy string (e.g., "name desc" -> "FMFID:1 desc")
+ * @param orderByString - The orderBy string (field name with optional asc/desc)
+ * @param baseTable - BaseTable instance to get field ID from
+ * @returns Transformed orderBy string with FMFID
+ */
+export function transformOrderByField(
+  orderByString: string,
+  baseTable: BaseTable<any, any, any, any>,
+): string {
+  if (!baseTable.isUsingFieldIds()) {
+    return orderByString;
+  }
+
+  // Parse the orderBy string to extract field name and direction
+  const parts = orderByString.trim().split(/\s+/);
+  const fieldName = parts[0];
+  const direction = parts[1]; // "asc" or "desc" or undefined
+
+  const fieldId = baseTable.getFieldId(fieldName as any);
+  return direction ? `${fieldId} ${direction}` : fieldId;
+}