@proofkit/fmodata 0.1.0-alpha.0

package/src/client/record-builder.ts

@@ -0,0 +1,240 @@
+import type {
+  ExecutionContext,
+  ExecutableBuilder,
+  Result,
+  ODataRecordMetadata,
+  ODataFieldResponse,
+  InferSchemaType,
+} from "../types";
+import type { TableOccurrence } from "./table-occurrence";
+import type { BaseTable } from "./base-table";
+import { QueryBuilder } from "./query-builder";
+import { validateSingleResponse } from "../validation";
+import { type FFetchOptions } from "@fetchkit/ffetch";
+import { z } from "zod/v4";
+
+// 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>
+      ? S
+      : never
+    : never;
+
+// Helper type to extract navigation relation names from an occurrence
+type ExtractNavigationNames<
+  O extends TableOccurrence<any, any, any, any> | undefined,
+> =
+  O extends TableOccurrence<any, any, infer Nav, any>
+    ? Nav extends Record<string, any>
+      ? keyof Nav
+      : never
+    : never;
+
+// Helper type to resolve a navigation item (handles both direct and lazy-loaded)
+type ResolveNavigationItem<T> = T extends () => infer R ? R : T;
+
+// Helper type to find target occurrence by relation name
+type FindNavigationTarget<
+  O extends TableOccurrence<any, any, any, any> | undefined,
+  Name extends string,
+> =
+  O extends TableOccurrence<any, any, infer Nav, any>
+    ? Name extends keyof Nav
+      ? ResolveNavigationItem<Nav[Name]>
+      : never
+    : never;
+
+export class RecordBuilder<
+  T extends Record<string, any>,
+  IsSingleField extends boolean = false,
+  FieldKey extends keyof T = keyof T,
+  Occ extends TableOccurrence<any, any, any, any> | undefined =
+    | TableOccurrence<any, any, any, any>
+    | undefined,
+> implements
+    ExecutableBuilder<
+      IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata
+    >
+{
+  private occurrence?: Occ;
+  private tableName: string;
+  private databaseName: string;
+  private context: ExecutionContext;
+  private recordId: string | number;
+  private operation?: "getSingleField" | "navigate";
+  private operationParam?: string;
+  private isNavigateFromEntitySet?: boolean;
+  private navigateRelation?: string;
+  private navigateSourceTableName?: string;
+
+  constructor(config: {
+    occurrence?: Occ;
+    tableName: string;
+    databaseName: string;
+    context: ExecutionContext;
+    recordId: string | number;
+  }) {
+    this.occurrence = config.occurrence;
+    this.tableName = config.tableName;
+    this.databaseName = config.databaseName;
+    this.context = config.context;
+    this.recordId = config.recordId;
+  }
+
+  getSingleField<K extends keyof T>(field: K): RecordBuilder<T, true, K, Occ> {
+    const newBuilder = new RecordBuilder<T, true, K, Occ>({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+      recordId: this.recordId,
+    });
+    newBuilder.operation = "getSingleField";
+    newBuilder.operationParam = field.toString();
+    // Preserve navigation context
+    newBuilder.isNavigateFromEntitySet = this.isNavigateFromEntitySet;
+    newBuilder.navigateRelation = this.navigateRelation;
+    newBuilder.navigateSourceTableName = this.navigateSourceTableName;
+    return newBuilder;
+  }
+
+  // Overload for valid relation names - returns typed QueryBuilder
+  navigate<RelationName extends ExtractNavigationNames<Occ>>(
+    relationName: RelationName,
+  ): QueryBuilder<
+    ExtractSchemaFromOccurrence<
+      FindNavigationTarget<Occ, RelationName>
+    > extends Record<string, z.ZodType>
+      ? InferSchemaType<
+          ExtractSchemaFromOccurrence<FindNavigationTarget<Occ, RelationName>>
+        >
+      : Record<string, any>
+  >;
+  // Overload for arbitrary strings - returns generic QueryBuilder with system fields
+  navigate(
+    relationName: string,
+  ): QueryBuilder<{ ROWID: number; ROWMODID: number; [key: string]: any }>;
+  // Implementation
+  navigate(relationName: string): QueryBuilder<any> {
+    // Use the target occurrence if available, otherwise allow untyped navigation
+    // (useful when types might be incomplete)
+    const targetOccurrence = this.occurrence?.navigation[relationName];
+    const builder = new QueryBuilder<any>({
+      occurrence: targetOccurrence,
+      tableName: targetOccurrence?.name ?? relationName,
+      databaseName: this.databaseName,
+      context: this.context,
+    });
+    // Store the navigation info - we'll use it in execute
+    (builder as any).isNavigate = true;
+    (builder as any).navigateRecordId = this.recordId;
+    (builder as any).navigateRelation = relationName;
+
+    // If this RecordBuilder came from a navigated EntitySet, we need to preserve that base path
+    if (
+      this.isNavigateFromEntitySet &&
+      this.navigateSourceTableName &&
+      this.navigateRelation
+    ) {
+      // Build the base path: /sourceTable/relation('recordId')/newRelation
+      (builder as any).navigateSourceTableName = this.navigateSourceTableName;
+      (builder as any).navigateBaseRelation = this.navigateRelation;
+    } else {
+      // Normal record navigation: /tableName('recordId')/relation
+      (builder as any).navigateSourceTableName = this.tableName;
+    }
+
+    return builder;
+  }
+
+  async execute(
+    options?: RequestInit & FFetchOptions,
+  ): Promise<
+    Result<IsSingleField extends true ? T[FieldKey] : T & ODataRecordMetadata>
+  > {
+    try {
+      let url: string;
+
+      // Build the base URL depending on whether this came from a navigated EntitySet
+      if (
+        this.isNavigateFromEntitySet &&
+        this.navigateSourceTableName &&
+        this.navigateRelation
+      ) {
+        // From navigated EntitySet: /sourceTable/relation('recordId')
+        url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
+      } else {
+        // Normal record: /tableName('recordId')
+        url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
+      }
+
+      if (this.operation === "getSingleField" && this.operationParam) {
+        url += `/${this.operationParam}`;
+      }
+
+      const response = await this.context._makeRequest(url, options);
+
+      // Handle single field operation
+      if (this.operation === "getSingleField") {
+        // Single field returns a JSON object with @context and value
+        const fieldResponse = response as ODataFieldResponse<T>;
+        return { data: fieldResponse.value as any, error: undefined };
+      }
+
+      // Get schema from occurrence if available
+      const schema = this.occurrence?.baseTable?.schema;
+
+      // Validate the single record response
+      const validation = await validateSingleResponse<any>(
+        response,
+        schema,
+        undefined, // No selected fields for record.get()
+        undefined, // No expand configs
+        "exact", // Expect exactly one record
+      );
+
+      if (!validation.valid) {
+        return { data: undefined, error: validation.error };
+      }
+
+      // Handle null response
+      if (validation.data === null) {
+        return { data: null as any, error: undefined };
+      }
+
+      return { data: validation.data, error: undefined };
+    } catch (error) {
+      return {
+        data: undefined,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  }
+
+  getRequestConfig(): { method: string; url: string; body?: any } {
+    let url: string;
+
+    // Build the base URL depending on whether this came from a navigated EntitySet
+    if (
+      this.isNavigateFromEntitySet &&
+      this.navigateSourceTableName &&
+      this.navigateRelation
+    ) {
+      // From navigated EntitySet: /sourceTable/relation('recordId')
+      url = `/${this.databaseName}/${this.navigateSourceTableName}/${this.navigateRelation}('${this.recordId}')`;
+    } else {
+      // Normal record: /tableName('recordId')
+      url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
+    }
+
+    if (this.operation === "getSingleField" && this.operationParam) {
+      url += `/${this.operationParam}`;
+    }
+
+    return {
+      method: "GET",
+      url,
+    };
+  }
+}

package/src/client/table-occurrence.ts

@@ -0,0 +1,100 @@
+import { BaseTable } from "./base-table";
+
+// Helper type to extract schema from BaseTable
+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>;
+}
+
+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>)
+  > = {},
+  DefSelect extends
+    | "all"
+    | "schema"
+    | readonly (keyof ExtractSchema<BT>)[] = "schema",
+> {
+  public readonly name: Name;
+  public readonly baseTable: BT;
+  private _navigationConfig: Nav;
+  public readonly navigation: ResolveNavigation<Nav>;
+  public readonly defaultSelect: DefSelect;
+
+  constructor(config: {
+    readonly name: Name;
+    readonly baseTable: BT;
+    readonly navigation?: Nav;
+    readonly defaultSelect?: DefSelect;
+  }) {
+    this.name = config.name;
+    this.baseTable = config.baseTable;
+    this._navigationConfig = (config.navigation ?? {}) as Nav;
+    this.defaultSelect = (config.defaultSelect ?? "schema") as DefSelect;
+
+    // Create navigation getters that lazily resolve functions
+    this.navigation = createNavigationGetters(this._navigationConfig);
+  }
+
+  addNavigation<
+    NewNav extends Record<
+      string,
+      | TableOccurrence<any, any, any, any>
+      | (() => TableOccurrence<any, any, any, any>)
+    >,
+  >(nav: NewNav): TableOccurrence<BT, Name, Nav & NewNav, DefSelect> {
+    return new TableOccurrence({
+      name: this.name,
+      baseTable: this.baseTable,
+      navigation: { ...this._navigationConfig, ...nav } as Nav & NewNav,
+      defaultSelect: this.defaultSelect,
+    });
+  }
+}
+
+// Helper function to create TableOccurrence with proper type inference
+export function createTableOccurrence<
+  const Name extends string,
+  BT extends BaseTable<any, any, any, any>,
+  DefSelect extends
+    | "all"
+    | "schema"
+    | readonly (keyof ExtractSchema<BT>)[] = "schema",
+>(config: {
+  name: Name;
+  baseTable: BT;
+  defaultSelect?: DefSelect;
+}): TableOccurrence<BT, Name, {}, DefSelect> {
+  return new TableOccurrence(config);
+}

package/src/client/update-builder.ts

@@ -0,0 +1,212 @@
+import type {
+  ExecutionContext,
+  ExecutableBuilder,
+  Result,
+  WithSystemFields,
+} from "../types";
+import type { TableOccurrence } from "./table-occurrence";
+import type { BaseTable } from "./base-table";
+import { QueryBuilder } from "./query-builder";
+import { type FFetchOptions } from "@fetchkit/ffetch";
+
+/**
+ * Initial update builder returned from EntitySet.update(data)
+ * Requires calling .byId() or .where() before .execute() is available
+ */
+export class UpdateBuilder<
+  T extends Record<string, any>,
+  BT extends BaseTable<any, any, any, any>,
+> {
+  private tableName: string;
+  private databaseName: string;
+  private context: ExecutionContext;
+  private occurrence?: TableOccurrence<any, any, any, any>;
+  private data: Partial<T>;
+
+  constructor(config: {
+    occurrence?: TableOccurrence<any, any, any, any>;
+    tableName: string;
+    databaseName: string;
+    context: ExecutionContext;
+    data: Partial<T>;
+  }) {
+    this.occurrence = config.occurrence;
+    this.tableName = config.tableName;
+    this.databaseName = config.databaseName;
+    this.context = config.context;
+    this.data = config.data;
+  }
+
+  /**
+   * Update a single record by ID
+   * Returns the count of updated records (0 or 1)
+   */
+  byId(id: string | number): ExecutableUpdateBuilder<T, true> {
+    return new ExecutableUpdateBuilder<T, true>({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+      data: this.data,
+      mode: "byId",
+      recordId: id,
+    });
+  }
+
+  /**
+   * Update records matching a filter query
+   * Returns the count of updated records
+   * @param fn Callback that receives a QueryBuilder for building the filter
+   */
+  where(
+    fn: (
+      q: QueryBuilder<WithSystemFields<T>>,
+    ) => QueryBuilder<WithSystemFields<T>>,
+  ): ExecutableUpdateBuilder<T, true> {
+    // Create a QueryBuilder for the user to configure
+    const queryBuilder = new QueryBuilder<
+      WithSystemFields<T>,
+      keyof WithSystemFields<T>,
+      false,
+      false,
+      undefined
+    >({
+      occurrence: undefined,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+    });
+
+    // Let the user configure it
+    const configuredBuilder = fn(queryBuilder);
+
+    return new ExecutableUpdateBuilder<T, true>({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+      data: this.data,
+      mode: "byFilter",
+      queryBuilder: configuredBuilder,
+    });
+  }
+}
+
+/**
+ * Executable update builder - has execute() method
+ * Returned after calling .byId() or .where()
+ * Both modes return the count of updated records
+ */
+export class ExecutableUpdateBuilder<
+  T extends Record<string, any>,
+  IsByFilter extends boolean,
+> implements ExecutableBuilder<{ updatedCount: number }>
+{
+  private tableName: string;
+  private databaseName: string;
+  private context: ExecutionContext;
+  private occurrence?: TableOccurrence<any, any, any, any>;
+  private data: Partial<T>;
+  private mode: "byId" | "byFilter";
+  private recordId?: string | number;
+  private queryBuilder?: QueryBuilder<any>;
+
+  constructor(config: {
+    occurrence?: TableOccurrence<any, any, any, any>;
+    tableName: string;
+    databaseName: string;
+    context: ExecutionContext;
+    data: Partial<T>;
+    mode: "byId" | "byFilter";
+    recordId?: string | number;
+    queryBuilder?: QueryBuilder<any>;
+  }) {
+    this.occurrence = config.occurrence;
+    this.tableName = config.tableName;
+    this.databaseName = config.databaseName;
+    this.context = config.context;
+    this.data = config.data;
+    this.mode = config.mode;
+    this.recordId = config.recordId;
+    this.queryBuilder = config.queryBuilder;
+  }
+
+  async execute(
+    options?: RequestInit & FFetchOptions,
+  ): Promise<Result<{ updatedCount: number }>> {
+    try {
+      let url: string;
+
+      if (this.mode === "byId") {
+        // Update single record by ID: PATCH /{database}/{table}('id')
+        url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
+      } else {
+        // Update by filter: PATCH /{database}/{table}?$filter=...
+        if (!this.queryBuilder) {
+          throw new Error("Query builder is required for filter-based update");
+        }
+
+        // Get the query string from the configured QueryBuilder
+        const queryString = this.queryBuilder.getQueryString();
+        // Remove the leading "/" from the query string as we'll build our own URL
+        const queryParams = queryString.startsWith(`/${this.tableName}`)
+          ? queryString.slice(`/${this.tableName}`.length)
+          : queryString;
+
+        url = `/${this.databaseName}/${this.tableName}${queryParams}`;
+      }
+
+      // Make PATCH request with JSON body
+      const response = await this.context._makeRequest(url, {
+        method: "PATCH",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(this.data),
+        ...options,
+      });
+
+      // Both byId and byFilter return affected row count
+      let updatedCount = 0;
+
+      if (typeof response === "number") {
+        updatedCount = response;
+      } else if (response && typeof response === "object") {
+        // Check if the response has a count property (fallback)
+        updatedCount = (response as any).updatedCount || 0;
+      }
+
+      return { data: { updatedCount }, error: undefined };
+    } catch (error) {
+      return {
+        data: undefined,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  }
+
+  getRequestConfig(): { method: string; url: string; body?: any } {
+    let url: string;
+
+    if (this.mode === "byId") {
+      url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
+    } else {
+      if (!this.queryBuilder) {
+        throw new Error("Query builder is required for filter-based update");
+      }
+
+      const queryString = this.queryBuilder.getQueryString();
+      const queryParams = queryString.startsWith(`/${this.tableName}`)
+        ? queryString.slice(`/${this.tableName}`.length)
+        : queryString;
+
+      url = `/${this.databaseName}/${this.tableName}${queryParams}`;
+    }
+
+    return {
+      method: "PATCH",
+      url,
+      body: JSON.stringify(this.data),
+    };
+  }
+}

package/src/filter-types.ts

@@ -0,0 +1,97 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+// Operator types for each value type
+export type StringOperators = 
+  | { eq: string | null }
+  | { ne: string | null }
+  | { gt: string }
+  | { ge: string }
+  | { lt: string }
+  | { le: string }
+  | { contains: string }
+  | { startswith: string }
+  | { endswith: string }
+  | { in: string[] };
+
+export type NumberOperators =
+  | { eq: number | null }
+  | { ne: number | null }
+  | { gt: number }
+  | { ge: number }
+  | { lt: number }
+  | { le: number }
+  | { in: number[] };
+
+export type BooleanOperators =
+  | { eq: boolean | null }
+  | { ne: boolean | null };
+
+export type DateOperators =
+  | { eq: Date | null }
+  | { ne: Date | null }
+  | { gt: Date }
+  | { ge: Date }
+  | { lt: Date }
+  | { le: Date }
+  | { in: Date[] };
+
+// Infer output type from StandardSchemaV1
+export type InferOutput<S> = S extends StandardSchemaV1<any, infer Output> 
+  ? Output 
+  : never;
+
+// Map inferred types to their operators
+export type OperatorsForType<T> =
+  T extends string | null | undefined ? StringOperators :
+  T extends number | null | undefined ? NumberOperators :
+  T extends boolean | null | undefined ? BooleanOperators :
+  T extends Date | null | undefined ? DateOperators :
+  never;
+
+// Get operators for a schema field
+export type OperatorsForSchemaField<S extends StandardSchemaV1> =
+  OperatorsForType<InferOutput<S>>;
+
+// Field filter: shorthand, single operator, or operator array
+export type FieldFilter<S extends StandardSchemaV1> =
+  | InferOutput<S>  // Shorthand: { name: "John" }
+  | OperatorsForSchemaField<S>  // Single operator: { age: { gt: 18 } }
+  | Array<OperatorsForSchemaField<S>>;  // Multiple operators: { age: [{ gt: 18 }, { lt: 65 }] }
+
+// Logical operators (recursive)
+export type LogicalFilter<Schema extends Record<string, StandardSchemaV1>> = {
+  and?: Array<TypedFilter<Schema>>;
+  or?: Array<TypedFilter<Schema>>;
+  not?: TypedFilter<Schema>;
+};
+
+// Helper to check if Schema is exactly Record<string, StandardSchemaV1> (untyped)
+// Uses double extends check to ensure Schema is exactly the generic type, not a more specific type
+type IsUntypedSchema<Schema> = 
+  [Record<string, StandardSchemaV1>] extends [Schema]
+    ? [Schema] extends [Record<string, StandardSchemaV1>]
+      ? true
+      : false
+    : false;
+
+// Main filter type
+export type TypedFilter<Schema extends Record<string, StandardSchemaV1>> = 
+  | LogicalFilter<Schema>
+  | (
+      IsUntypedSchema<Schema> extends true
+        ? {
+            // For untyped schemas, allow arbitrary string keys with empty object intersection (preserves autocomplete)
+            [key: string]: FieldFilter<any> | any;
+          } & {}
+        : {
+            // For typed schemas, use specific keys (preserves autocomplete)
+            [K in keyof Schema]?: FieldFilter<Schema[K]>;
+          }
+    );
+
+// Top-level filter (can be array for implicit AND)
+export type Filter<Schema extends Record<string, StandardSchemaV1>> =
+  | TypedFilter<Schema>
+  | Array<TypedFilter<Schema>>
+  | string;  // Escape hatch for raw OData expressions
+

package/src/index.ts

@@ -0,0 +1,17 @@
+// Barrel file - exports all public API from the client folder
+export { BaseTable } from "./client/base-table";
+export {
+  TableOccurrence,
+  createTableOccurrence,
+} from "./client/table-occurrence";
+export { FileMakerOData } from "./client/filemaker-odata";
+export type {
+  Filter,
+  TypedFilter,
+  FieldFilter,
+  StringOperators,
+  NumberOperators,
+  BooleanOperators,
+  DateOperators,
+  LogicalFilter,
+} from "./filter-types";