proofkit-fmodata（证明套件 fmodata）

ProofKit FMOData

Type-safe ORM for FileMaker's OData API with TypeScript code generation.

Up-to-Date Documentation

For the latest docs, fetch from proofkit.dev:

• FMOData: https://proofkit.dev/llms/fmodata
• Typegen: https://proofkit.dev/llms/typegen
• All packages: https://proofkit.dev/llms-full.txt

Quick Setup

# 1. Install packages
pnpm add @proofkit/fmodata@beta @proofkit/typegen

# 2. Create config (proofkit-typegen.config.jsonc)
npx @proofkit/typegen init

# 3. Set env vars
FM_SERVER=https://your-server.com
FM_DATABASE=YourDatabase.fmp12
OTTO_API_KEY=your-api-key  # or FM_USERNAME/FM_PASSWORD

# 4. Generate types
npx @proofkit/typegen generate

# 5. Or use interactive UI
npx @proofkit/typegen ui

Define Tables

import { fmTableOccurrence, textField, numberField, timestampField } from "@proofkit/fmodata";
import { z } from "zod";

export const Users = fmTableOccurrence("Users", {
  id: textField().primaryKey().entityId("FMFID:100001"),
  name: textField().notNull(),
  email: textField().notNull(),
  active: numberField()
    .readValidator(z.coerce.boolean())
    .writeValidator(z.boolean().transform(v => v ? 1 : 0)),
  createdAt: timestampField().readOnly(),
}, {
  entityId: "FMTID:1000001",
  navigationPaths: ["Contacts", "Orders"],
});

Query Patterns

import { FMServerConnection, eq, and, gt, asc, contains } from "@proofkit/fmodata";

const connection = new FMServerConnection({
  serverUrl: process.env.FM_SERVER,
  auth: { apiKey: process.env.OTTO_API_KEY }
});
const db = connection.database("MyDatabase.fmp12");

// List with filters
const result = await db.from(Users).list()
  .where(and(eq(Users.active, true), gt(Users.age, 18)))
  .orderBy(asc(Users.name))
  .top(10)
  .execute();

// Get single record
const user = await db.from(Users).get("user-123").execute();

// Select specific fields
const result = await db.from(Users).list()
  .select({ userId: Users.id, userName: Users.name })
  .execute();

// String filters
.where(contains(Users.email, "@example.com"))
.where(startsWith(Users.name, "John"))

CRUD Operations

// Insert
const result = await db.from(Users)
  .insert({ name: "John", email: "john@example.com" })
  .execute();

// Update
const result = await db.from(Users)
  .update({ name: "Jane" })
  .byId("user-123")
  .execute();

// Delete
const result = await db.from(Users)
  .delete()
  .byId("user-123")
  .execute();

// Batch operations (atomic)
const result = await db.batch([
  db.from(Users).list().top(10),
  db.from(Users).insert({ name: "Alice", email: "alice@example.com" }),
]).execute();

Relationships

// Expand related records
const result = await db.from(Users).list()
  .expand(Contacts, (b) =>
    b.select({ name: Contacts.name })
     .where(eq(Contacts.active, true))
  )
  .execute();

// Navigate from a record
const result = await db.from(Contacts).get("contact-123")
  .navigate(Users)
  .select({ username: Users.username })
  .execute();

Error Handling

import { isHTTPError, ValidationError, TimeoutError } from "@proofkit/fmodata";

const result = await db.from(Users).list().execute();

if (result.error) {
  if (isHTTPError(result.error)) {
    if (result.error.isNotFound()) console.log("Not found");
    if (result.error.is5xx()) console.log("Server error");
  } else if (result.error instanceof ValidationError) {
    console.log("Validation failed:", result.error.issues);
  } else if (result.error instanceof TimeoutError) {
    console.log("Request timed out");
  }
}

Troubleshooting

Connection Issues

"Unauthorized" or 401 errors

• Verify OTTO_API_KEY or FM_USERNAME/FM_PASSWORD env vars
• Ensure FM account has fmodata privilege enabled
• Check OData service is enabled on FM Server

"Not Found" or 404 errors

• Verify database name includes .fmp12 extension
• Check table/layout name matches exactly (case-sensitive)
• Ensure OData is enabled for the table occurrence

Type Generation Issues

typegen can't connect

• Run npx @proofkit/typegen ui to debug interactively
• Check connection health indicator in UI
• Verify env vars are loaded (check --env-path flag)

Generated types don't match FM schema

• Re-run npx @proofkit/typegen generate after FM schema changes
• Use --reset-overrides to recreate override files
• Check field type mappings in config

Query Issues

"Field not found" errors

• Ensure field is defined in fmTableOccurrence
• Check entityId matches FM field ID (use typegen to auto-generate)
• Verify field is on the OData-exposed table occurrence

Validation errors on read/write

• Check readValidator/writeValidator schemas match FM data types
• FM stores booleans as 0/1 numbers - use coercion validators
• Empty strings may need .catch("") or .nullable()

Performance Issues

Slow queries

• Add .top(n) to limit results
• Use .select() to fetch only needed fields
• Avoid expanding large related record sets

References

• fmodata-api.md - Complete API reference: field builders, operators, query methods
• typegen-config.md - Configuration options and examples