@proofkit/fmodata 0.1.0-alpha.0

package/src/client/database.ts

@@ -0,0 +1,177 @@
+import { z } from "zod/v4";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { ExecutionContext } from "../types";
+import type { BaseTable } from "./base-table";
+import type { TableOccurrence } from "./table-occurrence";
+import { EntitySet } from "./entity-set";
+
+// 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 find an occurrence by name in the occurrences tuple
+type FindOccurrenceByName<
+  Occurrences extends readonly TableOccurrence<any, any, any, any>[],
+  Name extends string,
+> = Occurrences extends readonly [
+  infer First,
+  ...infer Rest extends readonly TableOccurrence<any, any, any, any>[],
+]
+  ? First extends TableOccurrence<any, any, any, any>
+    ? First["name"] extends Name
+      ? First
+      : FindOccurrenceByName<Rest, Name>
+    : never
+  : never;
+
+// Helper type to extract all occurrence names from the tuple
+type ExtractOccurrenceNames<
+  Occurrences extends readonly TableOccurrence<any, any, any, any>[],
+> = Occurrences extends readonly []
+  ? string // If no occurrences, allow any string
+  : Occurrences[number]["name"]; // Otherwise, extract union of names
+
+export class Database<
+  Occurrences extends readonly TableOccurrence<
+    any,
+    any,
+    any,
+    any
+  >[] = readonly [],
+> {
+  private occurrenceMap: Map<string, TableOccurrence<any, any, any, any>>;
+
+  constructor(
+    private readonly databaseName: string,
+    private readonly context: ExecutionContext,
+    config?: { occurrences?: Occurrences },
+  ) {
+    this.occurrenceMap = new Map();
+    if (config?.occurrences) {
+      for (const occ of config.occurrences) {
+        this.occurrenceMap.set(occ.name, occ);
+      }
+    }
+  }
+
+  from<Name extends ExtractOccurrenceNames<Occurrences> | (string & {})>(
+    name: Name,
+  ): Occurrences extends readonly []
+    ? EntitySet<Record<string, z.ZodTypeAny>, undefined>
+    : Name extends ExtractOccurrenceNames<Occurrences>
+      ? EntitySet<
+          ExtractSchemaFromOccurrence<FindOccurrenceByName<Occurrences, Name>>,
+          FindOccurrenceByName<Occurrences, Name>
+        >
+      : EntitySet<Record<string, z.ZodTypeAny>, undefined> {
+    const occurrence = this.occurrenceMap.get(name as string);
+
+    if (occurrence) {
+      // Use EntitySet.create to preserve types better
+      type OccType = FindOccurrenceByName<Occurrences, Name>;
+      type SchemaType = ExtractSchemaFromOccurrence<OccType>;
+
+      return EntitySet.create<SchemaType, OccType>({
+        occurrence: occurrence as any,
+        tableName: name as string,
+        databaseName: this.databaseName,
+        context: this.context,
+      }) as any;
+    } else {
+      // Return untyped EntitySet for dynamic table access
+      return new EntitySet<Record<string, z.ZodTypeAny>, undefined>({
+        tableName: name as string,
+        databaseName: this.databaseName,
+        context: this.context,
+      }) as any;
+    }
+  }
+
+  // Example method showing how to use the request method
+  async getMetadata() {
+    return this.context._makeRequest(`/${this.databaseName}/$metadata`);
+  }
+
+  /**
+   * Lists all available tables (entity sets) in this database.
+   * @returns Promise resolving to an array of table names
+   */
+  async listTableNames(): Promise<string[]> {
+    const response = (await this.context._makeRequest(
+      `/${this.databaseName}`,
+    )) as {
+      value?: Array<{ name: string }>;
+    };
+    if (response.value && Array.isArray(response.value)) {
+      return response.value.map((item) => item.name);
+    }
+    return [];
+  }
+
+  /**
+   * Executes a FileMaker script.
+   * @param scriptName - The name of the script to execute (must be valid according to OData rules)
+   * @param options - Optional script parameter and result schema
+   * @returns Promise resolving to script execution result
+   */
+  async runScript<ResultSchema extends StandardSchemaV1<string, any> = never>(
+    scriptName: string,
+    options?: {
+      scriptParam?: string | number | Record<string, any>;
+      resultSchema?: ResultSchema;
+    },
+  ): Promise<
+    [ResultSchema] extends [never]
+      ? { resultCode: number; result?: string }
+      : ResultSchema extends StandardSchemaV1<string, infer Output>
+        ? { resultCode: number; result: Output }
+        : { resultCode: number; result?: string }
+  > {
+    const body: { scriptParameterValue?: unknown } = {};
+    if (options?.scriptParam !== undefined) {
+      body.scriptParameterValue = options.scriptParam;
+    }
+
+    const response = await this.context._makeRequest<{
+      scriptResult: {
+        code: number;
+        resultParameter?: string;
+      };
+    }>(`/${this.databaseName}/Script.${scriptName}`, {
+      method: "POST",
+      body: Object.keys(body).length > 0 ? JSON.stringify(body) : undefined,
+    });
+
+    // If resultSchema is provided, validate the result through it
+    if (options?.resultSchema && response.scriptResult !== undefined) {
+      const validationResult = options.resultSchema["~standard"].validate(
+        response.scriptResult.resultParameter,
+      );
+      // Handle both sync and async validation
+      const result =
+        validationResult instanceof Promise
+          ? await validationResult
+          : validationResult;
+
+      if (result.issues) {
+        throw new Error(
+          `Script result validation failed: ${JSON.stringify(result.issues)}`,
+        );
+      }
+
+      return {
+        resultCode: response.scriptResult.code,
+        result: result.value,
+      } as any;
+    }
+
+    return {
+      resultCode: response.scriptResult.code,
+      result: response.scriptResult.resultParameter,
+    } as any;
+  }
+}

package/src/client/delete-builder.ts

@@ -0,0 +1,193 @@
+import type {
+  ExecutionContext,
+  ExecutableBuilder,
+  Result,
+  WithSystemFields,
+} from "../types";
+import type { TableOccurrence } from "./table-occurrence";
+import { QueryBuilder } from "./query-builder";
+import { type FFetchOptions } from "@fetchkit/ffetch";
+import buildQuery from "odata-query";
+
+/**
+ * Initial delete builder returned from EntitySet.delete()
+ * Requires calling .byId() or .where() before .execute() is available
+ */
+export class DeleteBuilder<T extends Record<string, any>> {
+  private tableName: string;
+  private databaseName: string;
+  private context: ExecutionContext;
+  private occurrence?: TableOccurrence<any, any, any, any>;
+
+  constructor(config: {
+    occurrence?: TableOccurrence<any, any, any, any>;
+    tableName: string;
+    databaseName: string;
+    context: ExecutionContext;
+  }) {
+    this.occurrence = config.occurrence;
+    this.tableName = config.tableName;
+    this.databaseName = config.databaseName;
+    this.context = config.context;
+  }
+
+  /**
+   * Delete a single record by ID
+   */
+  byId(id: string | number): ExecutableDeleteBuilder<T> {
+    return new ExecutableDeleteBuilder<T>({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+      mode: "byId",
+      recordId: id,
+    });
+  }
+
+  /**
+   * Delete records matching a filter query
+   * @param fn Callback that receives a QueryBuilder for building the filter
+   */
+  where(
+    fn: (
+      q: QueryBuilder<WithSystemFields<T>>,
+    ) => QueryBuilder<WithSystemFields<T>>,
+  ): ExecutableDeleteBuilder<T> {
+    // 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 ExecutableDeleteBuilder<T>({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+      mode: "byFilter",
+      queryBuilder: configuredBuilder,
+    });
+  }
+}
+
+/**
+ * Executable delete builder - has execute() method
+ * Returned after calling .byId() or .where()
+ */
+export class ExecutableDeleteBuilder<T extends Record<string, any>>
+  implements ExecutableBuilder<{ deletedCount: number }>
+{
+  private tableName: string;
+  private databaseName: string;
+  private context: ExecutionContext;
+  private occurrence?: TableOccurrence<any, any, any, any>;
+  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;
+    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.mode = config.mode;
+    this.recordId = config.recordId;
+    this.queryBuilder = config.queryBuilder;
+  }
+
+  async execute(
+    options?: RequestInit & FFetchOptions,
+  ): Promise<Result<{ deletedCount: number }>> {
+    try {
+      let url: string;
+
+      if (this.mode === "byId") {
+        // Delete single record by ID: DELETE /{database}/{table}('id')
+        url = `/${this.databaseName}/${this.tableName}('${this.recordId}')`;
+      } else {
+        // Delete by filter: DELETE /{database}/{table}?$filter=...
+        if (!this.queryBuilder) {
+          throw new Error("Query builder is required for filter-based delete");
+        }
+
+        // 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 DELETE request
+      const response = await this.context._makeRequest(url, {
+        method: "DELETE",
+        ...options,
+      });
+
+      // OData returns 204 No Content with fmodata.affected_rows header
+      // The _makeRequest should handle extracting the header value
+      // For now, we'll check if response contains the count
+      let deletedCount = 0;
+
+      if (typeof response === "number") {
+        deletedCount = response;
+      } else if (response && typeof response === "object") {
+        // Check if the response has a count property (fallback)
+        deletedCount = (response as any).deletedCount || 0;
+      }
+
+      return { data: { deletedCount }, 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 delete");
+      }
+
+      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: "DELETE",
+      url,
+    };
+  }
+}

package/src/client/entity-set.ts

@@ -0,0 +1,310 @@
+import { z } from "zod/v4";
+import type {
+  ExecutionContext,
+  InferSchemaType,
+  WithSystemFields,
+  InsertData,
+  UpdateData,
+} from "../types";
+import type { BaseTable } from "./base-table";
+import type { TableOccurrence } from "./table-occurrence";
+import { QueryBuilder } from "./query-builder";
+import { RecordBuilder } from "./record-builder";
+import { InsertBuilder } from "./insert-builder";
+import { DeleteBuilder } from "./delete-builder";
+import { UpdateBuilder } from "./update-builder";
+
+// 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 & string
+      : never
+    : never;
+
+// 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 defaultSelect from a TableOccurrence
+type ExtractDefaultSelect<O> =
+  O extends TableOccurrence<infer BT, any, any, infer DefSelect>
+    ? BT extends BaseTable<infer S, any>
+      ? DefSelect extends "all"
+        ? keyof S
+        : DefSelect extends "schema"
+          ? keyof S
+          : DefSelect extends readonly (infer K)[]
+            ? K & keyof S
+            : keyof S
+      : 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>
+    ? Nav extends Record<string, any>
+      ? Name extends keyof Nav
+        ? ResolveNavigationItem<Nav[Name]>
+        : TableOccurrence<
+            BaseTable<Record<string, z.ZodTypeAny>, any>,
+            any,
+            any,
+            any
+          >
+      : TableOccurrence<
+          BaseTable<Record<string, z.ZodTypeAny>, any>,
+          any,
+          any,
+          any
+        >
+    : TableOccurrence<
+        BaseTable<Record<string, z.ZodTypeAny>, any>,
+        any,
+        any,
+        any
+      >;
+
+// Helper type to get the inferred schema type from a target occurrence
+type GetTargetSchemaType<
+  O extends TableOccurrence<any, any, any, any> | undefined,
+  Rel extends string,
+> = [FindNavigationTarget<O, Rel>] extends [
+  TableOccurrence<infer BT, any, any, any>,
+]
+  ? [BT] extends [BaseTable<infer S, any>]
+    ? [S] extends [Record<string, z.ZodType>]
+      ? InferSchemaType<S>
+      : Record<string, any>
+    : Record<string, any>
+  : Record<string, any>;
+
+export class EntitySet<
+  Schema extends Record<string, z.ZodType> = any,
+  Occ extends TableOccurrence<any, any, any, any> | undefined = undefined,
+> {
+  private occurrence?: Occ;
+  private tableName: string;
+  private databaseName: string;
+  private context: ExecutionContext;
+  private isNavigateFromEntitySet?: boolean;
+  private navigateRelation?: string;
+  private navigateSourceTableName?: string;
+
+  constructor(config: {
+    occurrence?: Occ;
+    tableName: string;
+    databaseName: string;
+    context: ExecutionContext;
+  }) {
+    this.occurrence = config.occurrence;
+    this.tableName = config.tableName;
+    this.databaseName = config.databaseName;
+    this.context = config.context;
+  }
+
+  // Type-only method to help TypeScript infer the schema from occurrence
+  static create<
+    OccurrenceSchema extends Record<string, z.ZodType>,
+    Occ extends
+      | TableOccurrence<BaseTable<OccurrenceSchema, any>, any, any, any>
+      | undefined = undefined,
+  >(config: {
+    occurrence?: Occ;
+    tableName: string;
+    databaseName: string;
+    context: ExecutionContext;
+  }): EntitySet<OccurrenceSchema, Occ> {
+    return new EntitySet<OccurrenceSchema, Occ>({
+      occurrence: config.occurrence,
+      tableName: config.tableName,
+      databaseName: config.databaseName,
+      context: config.context,
+    });
+  }
+
+  list(): QueryBuilder<
+    InferSchemaType<Schema>,
+    Occ extends TableOccurrence<any, any, any, any>
+      ? ExtractDefaultSelect<Occ>
+      : keyof InferSchemaType<Schema>,
+    false,
+    false,
+    Occ
+  > {
+    const builder = new QueryBuilder<
+      InferSchemaType<Schema>,
+      Occ extends TableOccurrence<any, any, any, any>
+        ? ExtractDefaultSelect<Occ>
+        : keyof InferSchemaType<Schema>,
+      false,
+      false,
+      Occ
+    >({
+      occurrence: this.occurrence as Occ,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+    });
+
+    // Apply defaultSelect if occurrence exists and select hasn't been called
+    if (this.occurrence) {
+      const defaultSelect = this.occurrence.defaultSelect;
+
+      if (defaultSelect === "schema") {
+        // Extract field names from schema
+        const schema = this.occurrence.baseTable.schema;
+        const fields = Object.keys(schema) as (keyof InferSchemaType<Schema>)[];
+        // Deduplicate fields (same as select method)
+        const uniqueFields = [...new Set(fields)];
+        return builder.select(...uniqueFields);
+      } else if (Array.isArray(defaultSelect)) {
+        // Use the provided field names, deduplicated
+        const uniqueFields = [
+          ...new Set(defaultSelect),
+        ] as (keyof InferSchemaType<Schema>)[];
+        return builder.select(...uniqueFields);
+      }
+      // If defaultSelect is "all", no changes needed (current behavior)
+    }
+
+    // Propagate navigation context if present
+    if (this.isNavigateFromEntitySet) {
+      (builder as any).isNavigate = true;
+      (builder as any).navigateRelation = this.navigateRelation;
+      (builder as any).navigateSourceTableName = this.navigateSourceTableName;
+      // navigateRecordId is intentionally not set (undefined) to indicate navigation from EntitySet
+    }
+    return builder;
+  }
+
+  get(
+    id: string | number,
+  ): RecordBuilder<
+    InferSchemaType<Schema>,
+    false,
+    keyof InferSchemaType<Schema>,
+    Occ
+  > {
+    const builder = new RecordBuilder<
+      InferSchemaType<Schema>,
+      false,
+      keyof InferSchemaType<Schema>,
+      Occ
+    >({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+      recordId: id,
+    });
+    // Propagate navigation context if present
+    if (this.isNavigateFromEntitySet) {
+      (builder as any).isNavigateFromEntitySet = true;
+      (builder as any).navigateRelation = this.navigateRelation;
+      (builder as any).navigateSourceTableName = this.navigateSourceTableName;
+    }
+    return builder;
+  }
+
+  insert(
+    data: Occ extends TableOccurrence<infer BT, any, any, any>
+      ? BT extends BaseTable<any, any, any, any>
+        ? InsertData<BT>
+        : Partial<InferSchemaType<Schema>>
+      : Partial<InferSchemaType<Schema>>,
+  ): InsertBuilder<InferSchemaType<Schema>, Occ> {
+    return new InsertBuilder<InferSchemaType<Schema>, Occ>({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+      data: data as Partial<InferSchemaType<Schema>>,
+    });
+  }
+
+  update(
+    data: Occ extends TableOccurrence<infer BT, any, any, any>
+      ? BT extends BaseTable<any, any, any, any>
+        ? UpdateData<BT>
+        : Partial<InferSchemaType<Schema>>
+      : Partial<InferSchemaType<Schema>>,
+  ): UpdateBuilder<
+    InferSchemaType<Schema>,
+    Occ extends TableOccurrence<infer BT, any, any, any>
+      ? BT extends BaseTable<any, any, any, any>
+        ? BT
+        : BaseTable<Schema, any, any, any>
+      : BaseTable<Schema, any, any, any>
+  > {
+    return new UpdateBuilder<
+      InferSchemaType<Schema>,
+      Occ extends TableOccurrence<infer BT, any, any, any>
+        ? BT extends BaseTable<any, any, any, any>
+          ? BT
+          : BaseTable<Schema, any, any, any>
+        : BaseTable<Schema, any, any, any>
+    >({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+      data: data as Partial<InferSchemaType<Schema>>,
+    });
+  }
+
+  delete(): DeleteBuilder<InferSchemaType<Schema>> {
+    return new DeleteBuilder<InferSchemaType<Schema>>({
+      occurrence: this.occurrence,
+      tableName: this.tableName,
+      databaseName: this.databaseName,
+      context: this.context,
+    });
+  }
+
+  // Overload for valid relation names - returns typed EntitySet
+  navigate<RelationName extends ExtractNavigationNames<Occ>>(
+    relationName: RelationName,
+  ): EntitySet<
+    ExtractSchemaFromOccurrence<
+      FindNavigationTarget<Occ, RelationName>
+    > extends Record<string, z.ZodType>
+      ? ExtractSchemaFromOccurrence<FindNavigationTarget<Occ, RelationName>>
+      : Record<string, z.ZodTypeAny>,
+    FindNavigationTarget<Occ, RelationName>
+  >;
+  // Overload for arbitrary strings - returns generic EntitySet
+  navigate(
+    relationName: string,
+  ): EntitySet<Record<string, z.ZodTypeAny>, undefined>;
+  // Implementation
+  navigate(relationName: string): EntitySet<any, any> {
+    // Use the target occurrence if available, otherwise allow untyped navigation
+    // (useful when types might be incomplete)
+    const targetOccurrence = this.occurrence?.navigation[relationName];
+    const entitySet = new EntitySet<any, any>({
+      occurrence: targetOccurrence,
+      tableName: targetOccurrence?.name ?? relationName,
+      databaseName: this.databaseName,
+      context: this.context,
+    });
+    // Store the navigation info in the EntitySet
+    // We'll need to pass this through when creating QueryBuilders
+    (entitySet as any).isNavigateFromEntitySet = true;
+    (entitySet as any).navigateRelation = relationName;
+    (entitySet as any).navigateSourceTableName = this.tableName;
+    return entitySet;
+  }
+}