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

package/README.md

@@ -1,6 +1,8 @@
-# @proofkit/fmodata
+# @proofkit/fmodata Documentation
 
-FileMaker OData API client
+A strongly-typed FileMaker OData API client.
+
+⚠️ WARNING: This library is in "alpha" status. The API is subject to change. Feedback is welcome on the [community forum](https://community.ottomatic.cloud/c/proofkit/13) or here on GitHub.
 
 ## Installation
 
@@ -8,30 +10,953 @@ FileMaker OData API client
 pnpm add @proofkit/fmodata
 ```
 
-## Usage
+## Quick Start
+
+Here's a minimal example to get you started:
 
 ```typescript
-import { createODataClient } from "@proofkit/fmodata";
+import { FileMakerOData, BaseTable, TableOccurrence } from "@proofkit/fmodata";
+import { z } from "zod/v4";
+
+// 1. Create a client
+const client = new FileMakerOData({
+  serverUrl: "https://your-server.com",
+  auth: {
+    // OttoFMS API key
+    apiKey: "your-api-key",
+
+    // or username and password
+    // username: "admin",
+    // password: "password",
+  },
+});
+
+// 2. Define your table schema
+const usersBase = new BaseTable({
+  schema: {
+    id: z.string(),
+    username: z.string(),
+    email: z.string(),
+    active: z.boolean(),
+  },
+  idField: "id",
+});
+
+// 3. Create a table occurrence
+const usersTO = new TableOccurrence({
+  name: "users",
+  baseTable: usersBase,
+});
+
+// 4. Create a database instance
+const db = client.database("MyDatabase.fmp12", {
+  occurrences: [usersTO],
+});
+
+// 5. Query your data
+const { data, error } = await db.from("users").list().execute();
+
+if (error) {
+  console.error(error);
+  return;
+}
 
-// Usage example coming soon
+if (data) {
+  console.log(data); // Array of users, properly typed
+}
 ```
 
-## Development
+## Core Concepts
 
-```bash
-# Install dependencies
-pnpm install
+This library relies heavily on the builder pattern for defining your queries and operations. Most operations require a final call to `execute()` to send the request to the server. This will allow for each batch operations in case you want to execute multiple operations in a single request, as supported by the FileMaker OData API. It's also helpful to testing the library, as you can also call `getQueryString()` to get the OData query string without executing the request.
+
+As such, there are layers to the library to help you build your queries and operations.
+
+- `FileMakerOData` - hold server connection details and authentication
+- `BaseTable` - defines the fields and validators for a base table
+- `TableOccurrence` - references a base table, and other table occurrences for navigation
+- `Database` - connects the table occurrences to the server connection
+
+### FileMaker Server prerequisites
+
+To use this library you need:
+
+- OData service enabled on your FileMaker server
+- A FileMaker account with `fmodata` privilege enabled
+- (if using OttoFMS) a Data API key setup for your FileMaker account with OData enabled
+
+A note on best practices:
+
+OData relies entirely on the table occurances in the relationship graph for data access. Relationships between table occurrences are also used, but maybe not as you expect (in short, only the simplest relationships are supported). Given these constraints, it may be best for you to have a seperate FileMaker file for your OData connection, using external data sources to link to your actual data. We've found this especially helpful for larger projects that have very large graphs with lots of duplicated table occurances compared to actual base tables.
+
+### Server Connection
+
+The client can authenticate using username/password or API key:
+
+```typescript
+// Username and password authentication
+const client = new FileMakerOData({
+  serverUrl: "https://api.example.com",
+  auth: {
+    username: "test",
+    password: "test",
+  },
+});
+
+// API key authentication
+const client = new FileMakerOData({
+  serverUrl: "https://api.example.com",
+  auth: {
+    apiKey: "your-api-key",
+  },
+});
+```
+
+### Schema Definitions
+
+This library relies on a schema-first approach for good type-safety and optional runtime validation. These are absracted into BaseTable and TableOccurrence classes to match FileMaker concepts.
+
+A `BaseTable` defines the schema for your FileMaker table using Standard Schema. These examples show zod, but you can use any other validation library that supports Standard Schema.
+
+```typescript
+import { z } from "zod/v4";
+import { BaseTable } from "@proofkit/fmodata";
+
+const contactsBase = new BaseTable({
+  schema: {
+    id: z.string(),
+    name: z.string(),
+    email: z.string(),
+    phone: z.string().optional(),
+    createdAt: z.string(),
+  },
+  idField: "id", // The primary key field
+  insertRequired: ["name", "email"], // optional: fields that are required on insert
+  updateRequired: ["email"], // optional: fields that are required on update
+});
+```
+
+A `TableOccurrence` is the actual entry point for the OData service on the FileMaker server. It's where you can define the relations between tables and also allows you to reference the same base table multiple times with different names.
+
+```typescript
+import { TableOccurrence } from "@proofkit/fmodata";
+
+const contactsTO = new TableOccurrence({
+  name: "contacts", // The table occurrence name in FileMaker
+  baseTable: contactsBase,
+});
+```
 
-# Build the package
-pnpm build
+#### Default Field Selection
 
-# Run tests
-pnpm test
+FileMaker will automatically return all non-container fields from a schema if you don't specify a $select parameter in your query. This library forces you to be a bit more explicit about what fields you want to return so that the types will more accurately reflect the full data you will get back. To modify this behavior, change the `defaultSelect` option when creating the `TableOccurrence`.
 
-# Watch mode for development
-pnpm dev
+```typescript
+// Option 1 (default): "schema" - Select all fields from the schema (same as "all" but more explicit)
+const usersTO = new TableOccurrence({
+  name: "users",
+  baseTable: usersBase,
+  defaultSelect: "schema", // a $select parameter will be always be added to the query for only the fields you've defined in the BaseTable schema
+});
+
+// Option 2: "all" - Select all fields (default behavior)
+const usersTO = new TableOccurrence({
+  name: "users",
+  baseTable: usersBase,
+  defaultSelect: "all", // Don't always a $select parameter to the query; FileMaker will return all non-container fields from the table
+});
+
+// Option 3: Array of field names - Select only specific fields by default
+const usersTO = new TableOccurrence({
+  name: "users",
+  baseTable: usersBase,
+  defaultSelect: ["username", "email"], // Only select these fields by default
+});
+
+// When you call list(), the defaultSelect is applied automatically
+const result = await db.from("users").list().execute();
+// If defaultSelect is ["username", "email"], result.data will only contain those fields
+
+// You can still override with explicit select()
+const result = await db
+  .from("users")
+  .list()
+  .select("username", "email", "age") // Always overrides at the per-request level
+  .execute();
+```
+
+Lastly, you can combine all table occurrences into a database instance for the full type-safe experience. This is a method on the main `FileMakerOData` client class.
+
+```typescript
+const db = client.database("MyDatabase.fmp12", {
+  occurrences: [contactsTO, usersTO], // Register your table occurrences
+});
+```
+
+## Querying Data
+
+### Basic Queries
+
+Use `list()` to retrieve multiple records:
+
+```typescript
+// Get all users
+const result = await db.from("users").list().execute();
+
+if (result.data) {
+  result.data.forEach((user) => {
+    console.log(user.username);
+  });
+}
+```
+
+Get a specific record by ID:
+
+```typescript
+const result = await db.from("users").get("user-123").execute();
+
+if (result.data) {
+  console.log(result.data.username);
+}
+```
+
+Get a single field value:
+
+```typescript
+const result = await db
+  .from("users")
+  .get("user-123")
+  .getSingleField("email")
+  .execute();
+
+if (result.data) {
+  console.log(result.data); // "user@example.com"
+}
+```
+
+### Filtering
+
+fmodata provides type-safe filter operations that prevent common errors at compile time. The filter system supports three syntaxes: shorthand, single operator objects, and arrays for multiple operators.
+
+#### Operator Syntax
+
+You can use filters in three ways:
+
+**1. Shorthand (direct value):**
+
+```typescript
+.filter({ name: "John" })
+// Equivalent to: { name: [{ eq: "John" }] }
 ```
 
-## License
+**2. Single operator object:**
 
-MIT
+```typescript
+.filter({ age: { gt: 18 } })
+```
+
+**3. Array of operators (for multiple operators on same field):**
+
+```typescript
+.filter({ age: [{ gt: 18 }, { lt: 65 }] })
+// Result: age gt 18 and age lt 65
+```
+
+The array pattern prevents duplicate operators on the same field and allows multiple conditions with implicit AND.
+
+#### Available Operators
+
+**String fields:**
+
+- `eq`, `ne` - equality/inequality
+- `contains`, `startswith`, `endswith` - string functions
+- `gt`, `ge`, `lt`, `le` - comparison
+- `in` - match any value in array
+
+**Number fields:**
+
+- `eq`, `ne`, `gt`, `ge`, `lt`, `le` - comparisons
+- `in` - match any value in array
+
+**Boolean fields:**
+
+- `eq`, `ne` - equality only
+
+**Date fields:**
+
+- `eq`, `ne`, `gt`, `ge`, `lt`, `le` - date comparisons
+- `in` - match any date in array
+
+#### Shorthand Syntax
+
+For simple equality checks, use the shorthand:
+
+```typescript
+const result = await db.from("users").list().filter({ name: "John" }).execute();
+// Equivalent to: { name: [{ eq: "John" }] }
+```
+
+#### Examples
+
+```typescript
+// Equality filter (single operator)
+const activeUsers = await db
+  .from("users")
+  .list()
+  .filter({ active: { eq: true } })
+  .execute();
+
+// Comparison operators (single operator)
+const adultUsers = await db
+  .from("users")
+  .list()
+  .filter({ age: { gt: 18 } })
+  .execute();
+
+// String operators (single operator)
+const johns = await db
+  .from("users")
+  .list()
+  .filter({ name: { contains: "John" } })
+  .execute();
+
+// Multiple operators on same field (array syntax, implicit AND)
+const rangeQuery = await db
+  .from("users")
+  .list()
+  .filter({ age: [{ gt: 18 }, { lt: 65 }] })
+  .execute();
+
+// Combine filters with AND
+const result = await db
+  .from("users")
+  .list()
+  .filter({
+    and: [{ active: [{ eq: true }] }, { age: [{ gt: 18 }] }],
+  })
+  .execute();
+
+// Combine filters with OR
+const result = await db
+  .from("users")
+  .list()
+  .filter({
+    or: [{ name: [{ eq: "John" }] }, { name: [{ eq: "Jane" }] }],
+  })
+  .execute();
+
+// IN operator
+const result = await db
+  .from("users")
+  .list()
+  .filter({ age: [{ in: [18, 21, 25] }] })
+  .execute();
+
+// Null checks
+const result = await db
+  .from("users")
+  .list()
+  .filter({ deletedAt: [{ eq: null }] })
+  .execute();
+```
+
+#### Logical Operators
+
+Combine multiple conditions with `and`, `or`, `not`:
+
+```typescript
+const result = await db
+  .from("users")
+  .list()
+  .filter({
+    and: [{ name: [{ contains: "John" }] }, { age: [{ gt: 18 }] }],
+  })
+  .execute();
+```
+
+#### Escape Hatch
+
+For unsupported edge cases, pass a raw OData filter string:
+
+```typescript
+const result = await db
+  .from("users")
+  .list()
+  .filter("substringof('John', name)")
+  .execute();
+```
+
+### Sorting
+
+Sort results using `orderBy()`:
+
+```typescript
+// Sort ascending
+const result = await db.from("users").list().orderBy("name").execute();
+
+// Sort descending
+const result = await db.from("users").list().orderBy("name desc").execute();
+
+// Multiple sort fields
+const result = await db
+  .from("users")
+  .list()
+  .orderBy("lastName, firstName desc")
+  .execute();
+```
+
+### Pagination
+
+Control the number of records returned and pagination:
+
+```typescript
+// Limit results
+const result = await db.from("users").list().top(10).execute();
+
+// Skip records (pagination)
+const result = await db.from("users").list().top(10).skip(20).execute();
+
+// Count total records
+const result = await db.from("users").list().count().execute();
+```
+
+### Selecting Fields
+
+Select specific fields to return:
+
+```typescript
+const result = await db
+  .from("users")
+  .list()
+  .select("username", "email")
+  .execute();
+
+// result.data[0] will only have username and email fields
+```
+
+### Single Records
+
+Use `single()` to ensure exactly one record is returned (returns an error if zero or multiple records are found):
+
+```typescript
+const result = await db
+  .from("users")
+  .list()
+  .filter({ email: { eq: "user@example.com" } })
+  .single()
+  .execute();
+
+if (result.data) {
+  // result.data is a single record, not an array
+  console.log(result.data.username);
+}
+```
+
+Use `maybeSingle()` when you want at most one record (returns `null` if no record is found, returns an error if multiple records are found):
+
+```typescript
+const result = await db
+  .from("users")
+  .list()
+  .filter({ email: { eq: "user@example.com" } })
+  .maybeSingle()
+  .execute();
+
+if (result.data) {
+  // result.data is a single record or null
+  console.log(result.data?.username);
+} else {
+  // No record found - result.data would be null
+  console.log("User not found");
+}
+```
+
+**Difference between `single()` and `maybeSingle()`:**
+
+- `single()` - Requires exactly one record. Returns an error if zero or multiple records are found.
+- `maybeSingle()` - Allows zero or one record. Returns `null` if no record is found, returns an error only if multiple records are found.
+
+### Chaining Methods
+
+All query methods can be chained together:
+
+```typescript
+const result = await db
+  .from("users")
+  .list()
+  .select("username", "email", "age")
+  .filter({ age: { gt: 18 } })
+  .orderBy("username")
+  .top(10)
+  .skip(0)
+  .execute();
+```
+
+## CRUD Operations
+
+### Insert
+
+Insert new records with type-safe data:
+
+```typescript
+// Insert a new user
+const result = await db
+  .from("users")
+  .insert({
+    username: "johndoe",
+    email: "john@example.com",
+    active: true,
+  })
+  .execute();
+
+if (result.data) {
+  console.log("Created user:", result.data);
+}
+```
+
+If you specify `insertRequired` fields in your base table, those fields become required:
+
+```typescript
+const usersBase = new BaseTable({
+  schema: {
+    id: z.string(),
+    username: z.string(),
+    email: z.string(),
+    createdAt: z.string().optional(),
+  },
+  idField: "id",
+  insertRequired: ["username", "email"], // These fields are required on insert
+});
+
+// TypeScript will enforce that username and email are provided
+const result = await db
+  .from("users")
+  .insert({
+    username: "johndoe",
+    email: "john@example.com",
+    // createdAt is optional
+  })
+  .execute();
+```
+
+### Update
+
+Update records by ID or filter:
+
+```typescript
+// Update by ID
+const result = await db
+  .from("users")
+  .update({ username: "newname" })
+  .byId("user-123")
+  .execute();
+
+if (result.data) {
+  console.log(`Updated ${result.data.updatedCount} record(s)`);
+}
+
+// Update by filter
+const result = await db
+  .from("users")
+  .update({ active: false })
+  .where((q) => q.filter({ lastLogin: { lt: "2023-01-01" } }))
+  .execute();
+
+// Complex filter example
+const result = await db
+  .from("users")
+  .update({ active: false })
+  .where((q) =>
+    q.filter({
+      and: [{ active: true }, { count: { lt: 5 } }],
+    }),
+  )
+  .execute();
+
+// Update with additional query options
+const result = await db
+  .from("users")
+  .update({ active: false })
+  .where((q) => q.filter({ active: true }).top(10))
+  .execute();
+```
+
+### Delete
+
+Delete records by ID or filter:
+
+```typescript
+// Delete by ID
+const result = await db.from("users").delete().byId("user-123").execute();
+
+if (result.data) {
+  console.log(`Deleted ${result.data.deletedCount} record(s)`);
+}
+
+// Delete by filter
+const result = await db
+  .from("users")
+  .delete()
+  .where((q) => q.filter({ active: false }))
+  .execute();
+
+// Delete with complex filters
+const result = await db
+  .from("users")
+  .delete()
+  .where((q) =>
+    q.filter({
+      and: [{ active: false }, { lastLogin: { lt: "2023-01-01" } }],
+    }),
+  )
+  .execute();
+```
+
+## Navigation & Relationships
+
+### Defining Navigation
+
+Define relationships between tables using the `navigation` option:
+
+```typescript
+const contactsBase = new BaseTable({
+  schema: {
+    id: z.string(),
+    name: z.string(),
+    userId: z.string(),
+  },
+  idField: "id",
+});
+
+const usersBase = new BaseTable({
+  schema: {
+    id: z.string(),
+    username: z.string(),
+    email: z.string(),
+  },
+  idField: "id",
+});
+
+// Define navigation using functions to handle circular dependencies
+const contactsTO = new TableOccurrence({
+  name: "contacts",
+  baseTable: contactsBase,
+  navigation: {
+    users: () => usersTO, // Relationship to users table
+  },
+});
+
+const usersTO = new TableOccurrence({
+  name: "users",
+  baseTable: usersBase,
+  navigation: {
+    contacts: () => contactsTO, // Relationship to contacts table
+  },
+});
+
+// You can also add navigation after creation
+const updatedUsersTO = usersTO.addNavigation({
+  profile: () => profileTO,
+});
+```
+
+### Navigating Between Tables
+
+Navigate to related records:
+
+```typescript
+// Navigate from a specific record
+const result = await db
+  .from("contacts")
+  .get("contact-123")
+  .navigate("users")
+  .select("username", "email")
+  .execute();
+
+// Navigate without specifying a record first
+const result = await db.from("contacts").navigate("users").list().execute();
+
+// You can navigate to arbitrary tables not in your schema
+const result = await db
+  .from("contacts")
+  .navigate("some_other_table")
+  .list()
+  .execute();
+```
+
+### Expanding Related Records
+
+Use `expand()` to include related records in your query results:
+
+```typescript
+// Simple expand
+const result = await db.from("contacts").list().expand("users").execute();
+
+// Expand with field selection
+const result = await db
+  .from("contacts")
+  .list()
+  .expand("users", (b) => b.select("username", "email"))
+  .execute();
+
+// Expand with filtering
+const result = await db
+  .from("contacts")
+  .list()
+  .expand("users", (b) => b.filter({ active: true }))
+  .execute();
+
+// Multiple expands
+const result = await db
+  .from("contacts")
+  .list()
+  .expand("users", (b) => b.select("username"))
+  .expand("orders", (b) => b.select("total").top(5))
+  .execute();
+
+// Nested expands
+const result = await db
+  .from("contacts")
+  .list()
+  .expand("users", (usersBuilder) =>
+    usersBuilder
+      .select("username", "email")
+      .expand("customer", (customerBuilder) =>
+        customerBuilder.select("name", "tier"),
+      ),
+  )
+  .execute();
+
+// Complex expand with multiple options
+const result = await db
+  .from("contacts")
+  .list()
+  .expand("users", (b) =>
+    b
+      .select("username", "email")
+      .filter({ active: true })
+      .orderBy("username")
+      .top(10)
+      .expand("customer", (nested) => nested.select("name")),
+  )
+  .execute();
+```
+
+## Running Scripts
+
+Execute FileMaker scripts via OData:
+
+```typescript
+// Simple script execution
+const result = await db.runScript("MyScriptName");
+
+console.log(result.resultCode); // Script result code
+console.log(result.result); // Optional script result string
+
+// Pass parameters to script
+const result = await db.runScript("MyScriptName", {
+  scriptParam: "some value",
+});
+
+// Script parameters can be strings, numbers, or objects
+const result = await db.runScript("ProcessOrder", {
+  scriptParam: {
+    orderId: "12345",
+    action: "approve",
+  }, // Will be JSON stringified
+});
+
+// Validate script result with Zod schema
+// NOTE: Your validator must be able to parse a string.
+// See Zod codecs for how to build a jsonCodec function that does this
+// https://zod.dev/codecs?id=jsonschema
+
+const schema = jsonCodec(
+  z.object({
+    success: z.boolean(),
+    message: z.string(),
+    recordId: z.string(),
+  }),
+);
+
+const result = await db.runScript("CreateRecord", {
+  resultSchema: schema,
+});
+
+// result.result is now typed based on your schema
+console.log(result.result.recordId);
+```
+
+**Note:** OData doesn't support script names with special characters (e.g., `@`, `&`, `/`) or script names beginning with a number. TypeScript will catch these at compile time.
+
+## Advanced Features
+
+### Type Safety
+
+The library provides full TypeScript type inference:
+
+```typescript
+const usersBase = new BaseTable({
+  schema: {
+    id: z.string(),
+    username: z.string(),
+    email: z.string(),
+  },
+  idField: "id",
+});
+
+const usersTO = new TableOccurrence({
+  name: "users",
+  baseTable: usersBase,
+});
+
+const db = client.database("MyDB", {
+  occurrences: [usersTO],
+});
+
+// TypeScript knows these are valid field names
+db.from("users").list().select("username", "email");
+
+// TypeScript error: "invalid" is not a field name
+db.from("users").list().select("invalid"); // TS Error
+
+// Type-safe filters
+db.from("users")
+  .list()
+  .filter({ username: { eq: "john" } }); // ✓
+db.from("users")
+  .list()
+  .filter({ invalid: { eq: "john" } }); // TS Error
+```
+
+### Required Fields
+
+Control which fields are required for insert and update operations:
+
+```typescript
+const usersBase = new BaseTable({
+  schema: {
+    id: z.string(),
+    username: z.string(),
+    email: z.string(),
+    status: z.string(),
+    updatedAt: z.string().optional(),
+  },
+  idField: "id",
+  insertRequired: ["username", "email"], // Required on insert
+  updateRequired: ["status"], // Required on update
+});
+
+// Insert requires username and email
+db.from("users").insert({
+  username: "john",
+  email: "john@example.com",
+  // updatedAt is optional
+});
+
+// Update requires status
+db.from("users")
+  .update({
+    status: "active",
+    // other fields are optional
+  })
+  .byId("user-123");
+```
+
+### Error Handling
+
+All operations return a `Result` type with either `data` or `error`:
+
+```typescript
+const result = await db.from("users").list().execute();
+
+if (result.error) {
+  console.error("Query failed:", result.error.message);
+  return;
+}
+
+if (result.data) {
+  console.log("Query succeeded:", result.data);
+}
+```
+
+### OData Annotations and Validation
+
+By default, the library automatically strips OData annotations fields (`@id` and `@editLink`) from responses. If you need these fields, you can include them by passing `includeODataAnnotations: true`:
+
+```typescript
+const result = await db.from("users").list().execute({
+  includeODataAnnotations: true,
+});
+```
+
+You can also skip runtime validation by passing `skipValidation: true`.
+
+```typescript
+const result = await db.from("users").list().execute({
+  skipValidation: true,
+});
+
+// Response is returned without schema validation
+```
+
+**Note:** Skipping validation means the response won't be validated OR transformed against your schema, so you lose runtime type safety guarantees. Use with caution.
+
+### Custom Fetch Handlers
+
+You can provide custom fetch handlers for testing or custom networking:
+
+```typescript
+const customFetch = async (url, options) => {
+  console.log("Fetching:", url);
+  return fetch(url, options);
+};
+
+const result = await db.from("users").list().execute({
+  fetchHandler: customFetch,
+});
+```
+
+## Testing
+
+The library supports testing with custom fetch handlers. You can create mock fetch functions to return test data:
+
+```typescript
+const mockResponse = {
+  "@odata.context": "...",
+  value: [
+    { id: "1", username: "john", email: "john@example.com" },
+    { id: "2", username: "jane", email: "jane@example.com" },
+  ],
+};
+
+const mockFetch = async () => {
+  return new Response(JSON.stringify(mockResponse), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+};
+
+const result = await db.from("users").list().execute({
+  fetchHandler: mockFetch,
+});
+
+expect(result.data).toHaveLength(2);
+expect(result.data[0].username).toBe("john");
+```
+
+You can also inspect query strings without executing:
+
+```typescript
+const queryString = db
+  .from("users")
+  .list()
+  .select("username", "email")
+  .filter({ active: true })
+  .orderBy("username")
+  .top(10)
+  .getQueryString();
+
+console.log(queryString);
+// Output: "/users?$select=username,email&$filter=active eq true&$orderby=username&$top=10"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proofkit/fmodata",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "FileMaker OData API client",
   "repository": "git@github.com:proofgeist/proofkit.git",
   "author": "Eric <37158449+eluce2@users.noreply.github.com>",