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

package/src/client/response-processor.ts

@@ -0,0 +1,103 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { BaseTable } from "./base-table";
+import type { ExecuteOptions } from "../types";
+import type { ExpandValidationConfig } from "../validation";
+import { ValidationError, ResponseStructureError } from "../errors";
+import { transformResponseFields } from "../transform";
+import { validateListResponse, validateRecord } from "../validation";
+
+// Type for raw OData responses
+export type ODataResponse<T = unknown> = T & {
+  "@odata.context"?: string;
+  "@odata.count"?: number;
+};
+
+export type ODataListResponse<T = unknown> = ODataResponse<{
+  value: T[];
+}>;
+
+export type ODataRecordResponse<T = unknown> = ODataResponse<
+  T & {
+    "@id"?: string;
+    "@editLink"?: string;
+  }
+>;
+
+/**
+ * Strip OData annotations from a single record
+ */
+export function stripODataAnnotations<T extends Record<string, unknown>>(
+  record: ODataRecordResponse<T>,
+  options?: ExecuteOptions,
+): T {
+  if (options?.includeODataAnnotations === true) {
+    return record as T;
+  }
+  const { "@id": _id, "@editLink": _editLink, ...rest } = record;
+  return rest as T;
+}
+
+/**
+ * Transform field IDs back to names using the base table configuration
+ */
+export function applyFieldTransformation<T extends Record<string, unknown>>(
+  response: ODataResponse<T> | ODataListResponse<T>,
+  baseTable: BaseTable<Record<string, StandardSchemaV1>, any, any, any>,
+  expandConfigs?: ExpandValidationConfig[],
+): ODataResponse<T> | ODataListResponse<T> {
+  return transformResponseFields(response, baseTable, expandConfigs) as
+    | ODataResponse<T>
+    | ODataListResponse<T>;
+}
+
+/**
+ * Apply schema validation and transformation to data
+ */
+export async function applyValidation<T extends Record<string, unknown>>(
+  data: T | T[],
+  schema?: Record<string, StandardSchemaV1>,
+  selectedFields?: (keyof T)[],
+  expandConfigs?: ExpandValidationConfig[],
+): Promise<
+  | { valid: true; data: T | T[] }
+  | { valid: false; error: ValidationError | ResponseStructureError }
+> {
+  if (Array.isArray(data)) {
+    // Validate as a list
+    const validation = await validateListResponse<T>(
+      { value: data },
+      schema,
+      selectedFields as string[] | undefined,
+      expandConfigs,
+    );
+    if (!validation.valid) {
+      return { valid: false, error: validation.error };
+    }
+    return { valid: true, data: validation.data };
+  } else {
+    // Validate as a single record
+    const validation = await validateRecord<T>(
+      data,
+      schema,
+      selectedFields,
+      expandConfigs,
+    );
+    if (!validation.valid) {
+      return { valid: false, error: validation.error };
+    }
+    return { valid: true, data: validation.data };
+  }
+}
+
+/**
+ * Extract value array from OData list response, or wrap single record in array
+ */
+export function extractListValue<T>(
+  response: ODataListResponse<T> | ODataRecordResponse<T>,
+): T[] {
+  if ("value" in response && Array.isArray(response.value)) {
+    return response.value;
+  }
+  // Single record responses return the record directly
+  return [response as T];
+}

package/src/client/schema-manager.ts

@@ -0,0 +1,246 @@
+import type { FFetchOptions } from "@fetchkit/ffetch";
+import type { ExecutionContext } from "../types";
+
+type GenericField = {
+  name: string;
+  nullable?: boolean;
+  primary?: boolean;
+  unique?: boolean;
+  global?: boolean;
+  repetitions?: number;
+};
+
+type StringField = GenericField & {
+  type: "string";
+  maxLength?: number;
+  default?: "USER" | "USERNAME" | "CURRENT_USER";
+};
+
+type NumericField = GenericField & {
+  type: "numeric";
+};
+
+type DateField = GenericField & {
+  type: "date";
+  default?: "CURRENT_DATE" | "CURDATE";
+};
+
+type TimeField = GenericField & {
+  type: "time";
+  default?: "CURRENT_TIME" | "CURTIME";
+};
+
+type TimestampField = GenericField & {
+  type: "timestamp";
+  default?: "CURRENT_TIMESTAMP" | "CURTIMESTAMP";
+};
+
+type ContainerField = GenericField & {
+  type: "container";
+  externalSecurePath?: string;
+};
+
+export type Field =
+  | StringField
+  | NumericField
+  | DateField
+  | TimeField
+  | TimestampField
+  | ContainerField;
+
+export type {
+  StringField,
+  NumericField,
+  DateField,
+  TimeField,
+  TimestampField,
+  ContainerField,
+};
+
+type FileMakerField = Omit<Field, "type" | "repetitions" | "maxLength"> & {
+  type: string;
+};
+
+type TableDefinition = {
+  tableName: string;
+  fields: FileMakerField[];
+};
+
+export class SchemaManager {
+  public constructor(
+    private readonly databaseName: string,
+    private readonly context: ExecutionContext,
+  ) {}
+
+  public async createTable(
+    tableName: string,
+    fields: Field[],
+    options?: RequestInit & FFetchOptions,
+  ): Promise<TableDefinition> {
+    const result = await this.context._makeRequest<TableDefinition>(
+      `/${this.databaseName}/FileMaker_Tables`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          tableName,
+          fields: fields.map(SchemaManager.compileFieldDefinition),
+        }),
+        ...options,
+      },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.data;
+  }
+
+  public async addFields(
+    tableName: string,
+    fields: Field[],
+    options?: RequestInit & FFetchOptions,
+  ): Promise<TableDefinition> {
+    const result = await this.context._makeRequest<TableDefinition>(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}`,
+      {
+        method: "PATCH",
+        body: JSON.stringify({
+          fields: fields.map(SchemaManager.compileFieldDefinition),
+        }),
+        ...options,
+      },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.data;
+  }
+
+  public async deleteTable(
+    tableName: string,
+    options?: RequestInit & FFetchOptions,
+  ): Promise<void> {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}`,
+      { method: "DELETE", ...options },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+  }
+
+  public async deleteField(
+    tableName: string,
+    fieldName: string,
+    options?: RequestInit & FFetchOptions,
+  ): Promise<void> {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}/${fieldName}`,
+      {
+        method: "DELETE",
+        ...options,
+      },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+  }
+
+  public async createIndex(
+    tableName: string,
+    fieldName: string,
+    options?: RequestInit & FFetchOptions,
+  ): Promise<{ indexName: string }> {
+    const result = await this.context._makeRequest<{ indexName: string }>(
+      `/${this.databaseName}/FileMaker_Indexes/${tableName}`,
+      {
+        method: "POST",
+        body: JSON.stringify({ indexName: fieldName }),
+        ...options,
+      },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+
+    return result.data;
+  }
+
+  public async deleteIndex(
+    tableName: string,
+    fieldName: string,
+    options?: RequestInit & FFetchOptions,
+  ): Promise<void> {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Indexes/${tableName}/${fieldName}`,
+      {
+        method: "DELETE",
+        ...options,
+      },
+    );
+
+    if (result.error) {
+      throw result.error;
+    }
+  }
+
+  private static compileFieldDefinition(field: Field): FileMakerField {
+    let type: string = field.type;
+    const repetitions = field.repetitions;
+
+    // Handle string fields - convert to varchar and add maxLength if present
+    if (field.type === "string") {
+      type = "varchar";
+      const stringField = field as StringField;
+      if (stringField.maxLength !== undefined) {
+        type += `(${stringField.maxLength})`;
+      }
+    }
+
+    // Add repetitions suffix if present
+    if (repetitions !== undefined) {
+      type += `[${repetitions}]`;
+    }
+
+    // Build the result object, excluding type, maxLength, and repetitions
+    const result: any = {
+      name: field.name,
+      type,
+    };
+
+    // Add optional properties that FileMaker expects
+    if (field.nullable !== undefined) result.nullable = field.nullable;
+    if (field.primary !== undefined) result.primary = field.primary;
+    if (field.unique !== undefined) result.unique = field.unique;
+    if (field.global !== undefined) result.global = field.global;
+
+    // Add type-specific properties
+    if (field.type === "string") {
+      const stringField = field as StringField;
+      if (stringField.default !== undefined)
+        result.default = stringField.default;
+    } else if (field.type === "date") {
+      const dateField = field as DateField;
+      if (dateField.default !== undefined) result.default = dateField.default;
+    } else if (field.type === "time") {
+      const timeField = field as TimeField;
+      if (timeField.default !== undefined) result.default = timeField.default;
+    } else if (field.type === "timestamp") {
+      const timestampField = field as TimestampField;
+      if (timestampField.default !== undefined)
+        result.default = timestampField.default;
+    } else if (field.type === "container") {
+      const containerField = field as ContainerField;
+      if (containerField.externalSecurePath !== undefined)
+        result.externalSecurePath = containerField.externalSecurePath;
+    }
+
+    return result as FileMakerField;
+  }
+}

package/src/client/table-occurrence.ts

@@ -4,43 +4,13 @@ import { BaseTable } from "./base-table";
 type ExtractSchema<BT> =
   BT extends BaseTable<infer S, any, any, any> ? S : never;
 
-// Helper type to resolve navigation functions to their return types
-type ResolveNavigation<T> = {
-  [K in keyof T]: T[K] extends () => infer R ? R : T[K];
-};
-
-// Helper to create a getter-based navigation object
-function createNavigationGetters<
-  Nav extends Record<
-    string,
-    | TableOccurrence<any, any, any, any>
-    | (() => TableOccurrence<any, any, any, any>)
-  >,
->(navConfig: Nav): ResolveNavigation<Nav> {
-  const result: any = {};
-
-  for (const key in navConfig) {
-    Object.defineProperty(result, key, {
-      get() {
-        const navItem = navConfig[key];
-        return typeof navItem === "function" ? navItem() : navItem;
-      },
-      enumerable: true,
-      configurable: true,
-    });
-  }
-
-  return result as ResolveNavigation<Nav>;
-}
+// Symbol for internal navigation setting (used by buildOccurrences)
+const INTERNAL_NAV = Symbol("internal-navigation");
 
 export class TableOccurrence<
   BT extends BaseTable<any, any, any, any> = any,
   Name extends string = string,
-  Nav extends Record<
-    string,
-    | TableOccurrence<any, any, any, any>
-    | (() => TableOccurrence<any, any, any, any>)
-  > = {},
+  Nav extends Record<string, TableOccurrence<any, any, any, any>> = {},
   DefSelect extends
     | "all"
     | "schema"
@@ -48,38 +18,70 @@ export class TableOccurrence<
 > {
   public readonly name: Name;
   public readonly baseTable: BT;
-  private _navigationConfig: Nav;
-  public readonly navigation: ResolveNavigation<Nav>;
+  public readonly navigation: Nav;
   public readonly defaultSelect: DefSelect;
+  public readonly fmtId?: `FMTID:${string}`;
 
   constructor(config: {
     readonly name: Name;
     readonly baseTable: BT;
-    readonly navigation?: Nav;
     readonly defaultSelect?: DefSelect;
+    readonly fmtId?: `FMTID:${string}`;
+    /** @internal Used by buildOccurrences - do not use directly */
+    readonly [INTERNAL_NAV]?: Nav;
   }) {
     this.name = config.name;
     this.baseTable = config.baseTable;
-    this._navigationConfig = (config.navigation ?? {}) as Nav;
+    this.navigation = (config[INTERNAL_NAV] ?? {}) as Nav;
     this.defaultSelect = (config.defaultSelect ?? "schema") as DefSelect;
+    this.fmtId = config.fmtId;
+  }
+
+  /**
+   * Returns the FileMaker table occurrence ID (FMTID) if available, or the table name.
+   * @returns The FMTID string or the table name
+   */
+  getTableId(): string {
+    return this.fmtId ?? this.name;
+  }
+
+  /**
+   * Returns the table occurrence name.
+   * @returns The table name
+   */
+  getTableName(): string {
+    return this.name;
+  }
 
-    // Create navigation getters that lazily resolve functions
-    this.navigation = createNavigationGetters(this._navigationConfig);
+  /**
+   * Returns true if this TableOccurrence is using FileMaker table occurrence IDs.
+   */
+  isUsingTableId(): boolean {
+    return this.fmtId !== undefined;
   }
 
-  addNavigation<
-    NewNav extends Record<
-      string,
-      | TableOccurrence<any, any, any, any>
-      | (() => TableOccurrence<any, any, any, any>)
-    >,
-  >(nav: NewNav): TableOccurrence<BT, Name, Nav & NewNav, DefSelect> {
+  /**
+   * @internal Creates a new TableOccurrence with navigation - used by buildOccurrences
+   */
+  static _withNavigation<
+    BT extends BaseTable<any, any, any, any>,
+    Name extends string,
+    Nav extends Record<string, TableOccurrence<any, any, any, any>>,
+    DefSelect extends
+      | "all"
+      | "schema"
+      | readonly (keyof ExtractSchema<BT>)[] = "schema",
+  >(
+    base: TableOccurrence<BT, Name, any, DefSelect>,
+    navigation: Nav,
+  ): TableOccurrence<BT, Name, Nav, DefSelect> {
     return new TableOccurrence({
-      name: this.name,
-      baseTable: this.baseTable,
-      navigation: { ...this._navigationConfig, ...nav } as Nav & NewNav,
-      defaultSelect: this.defaultSelect,
-    });
+      name: base.name,
+      baseTable: base.baseTable,
+      defaultSelect: base.defaultSelect,
+      fmtId: base.fmtId,
+      [INTERNAL_NAV]: navigation,
+    }) as TableOccurrence<BT, Name, Nav, DefSelect>;
   }
 }
 
@@ -95,6 +97,60 @@ export function createTableOccurrence<
   name: Name;
   baseTable: BT;
   defaultSelect?: DefSelect;
+  fmtId?: `FMTID:${string}`;
+}): TableOccurrence<BT, Name, {}, DefSelect> {
+  return new TableOccurrence(config);
+}
+
+/**
+ * Creates a TableOccurrence with proper TypeScript type inference.
+ *
+ * Use this function to create TableOccurrence instances with full type safety.
+ * For navigation between tables, use `buildOccurrences()` after defining your TOs.
+ *
+ * @example
+ * ```ts
+ * const users = defineTableOccurrence({
+ *   name: "users",
+ *   baseTable: usersBase,
+ * });
+ * ```
+ *
+ * @example With entity IDs
+ * ```ts
+ * const products = defineTableOccurrence({
+ *   name: "products",
+ *   baseTable: productsBase,
+ *   fmtId: "FMTID:12345",
+ * });
+ * ```
+ *
+ * @example With navigation (use buildOccurrences)
+ * ```ts
+ * const _users = defineTableOccurrence({ name: "users", baseTable: usersBase });
+ * const _contacts = defineTableOccurrence({ name: "contacts", baseTable: contactsBase });
+ *
+ * const [users, contacts] = buildOccurrences({
+ *   occurrences: [_users, _contacts],
+ *   navigation: {
+ *     users: ["contacts"],
+ *     contacts: ["users"],
+ *   },
+ * });
+ * ```
+ */
+export function defineTableOccurrence<
+  const Name extends string,
+  BT extends BaseTable<any, any, any, any>,
+  const DefSelect extends
+    | "all"
+    | "schema"
+    | readonly (keyof ExtractSchema<BT>)[] = "schema",
+>(config: {
+  readonly name: Name;
+  readonly baseTable: BT;
+  readonly fmtId?: `FMTID:${string}`;
+  readonly defaultSelect?: DefSelect;
 }): TableOccurrence<BT, Name, {}, DefSelect> {
   return new TableOccurrence(config);
 }