@proofkit/fmodata 0.1.0-alpha.9 → 0.1.0-beta.23

package/README.md

@@ -26,8 +26,10 @@ Here's a minimal example to get you started:
 ```typescript
 import {
   FMServerConnection,
-  defineBaseTable,
-  defineTableOccurrence,
+  fmTableOccurrence,
+  textField,
+  numberField,
+  eq,
 } from "@proofkit/fmodata";
 import { z } from "zod/v4";
 
@@ -44,30 +46,21 @@ const connection = new FMServerConnection({
   },
 });
 
-// 2. Define your table schema
-const usersBase = defineBaseTable({
-  schema: {
-    id: z.string(),
-    username: z.string(),
-    email: z.string(),
-    active: z.boolean(),
-  },
-  idField: "id",
+// 2. Define your table schema using field builders
+const users = fmTableOccurrence("users", {
+  id: textField().primaryKey(),
+  username: textField().notNull(),
+  email: textField().notNull(),
+  active: numberField()
+    .readValidator(z.coerce.boolean())
+    .writeValidator(z.boolean().transform((v) => (v ? 1 : 0))),
 });
 
-// 3. Create a table occurrence
-const usersTO = defineTableOccurrence({
-  name: "users",
-  baseTable: usersBase,
-});
+// 3. Create a database instance
+const db = connection.database("MyDatabase.fmp12");
 
-// 4. Create a database instance
-const db = connection.database("MyDatabase.fmp12", {
-  occurrences: [usersTO],
-});
-
-// 5. Query your data
-const { data, error } = await db.from("users").list().execute();
+// 4. Query your data
+const { data, error } = await db.from(users).list().execute();
 
 if (error) {
   console.error(error);
@@ -86,8 +79,7 @@ This library relies heavily on the builder pattern for defining your queries and
 As such, there are layers to the library to help you build your queries and operations.
 
 - `FMServerConnection` - 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
+- `FMTable` (created via `fmTableOccurrence()`) - defines the fields, validators, and metadata for a table occurrence
 - `Database` - connects the table occurrences to the server connection
 
 ### FileMaker Server prerequisites
@@ -100,7 +92,7 @@ To use this library you need:
 
 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.
+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 file. We've found this especially helpful for larger projects that have very large graphs with lots of redundant table occurances compared to actual number of base tables.
 
 ### Server Connection
 
@@ -127,93 +119,118 @@ const connection = new FMServerConnection({
 
 ### Schema Definitions
 
-This library relies on a schema-first approach for good type-safety and optional runtime validation. These are abstracted into BaseTable and TableOccurrence classes to match FileMaker concepts.
+This library relies on a schema-first approach for good type-safety and optional runtime validation. Use **`fmTableOccurrence()`** with field builders to create your schemas. This provides full TypeScript type inference for field names in queries.
 
-**Helper Functions vs Constructors:**
+#### Field Builders
 
-- **`defineBaseTable()`** and **`defineTableOccurrence()`** - Recommended for better type inference, especially when using entity IDs (FMFID/FMTID). These functions provide improved TypeScript type inference for field names in queries.
+Field builders provide a fluent API for defining table fields with type-safe metadata. These field types map directly to the FileMaker field types
 
-- **`new BaseTable()`** and **`new TableOccurrence()`** - Still supported for backward compatibility, but may have slightly less precise type inference in some cases.
+- `textField()`
+- `numberField()`
+- `dateField()`
+- `timeField()`
+- `timestampField()`
+- `containerField()`
+- `calcField()`
 
-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.
+Each field builder supports chainable methods:
 
-```typescript
-import { z } from "zod/v4";
-import { defineBaseTable } from "@proofkit/fmodata";
-
-const contactsBase = defineBaseTable({
-  schema: {
-    id: z.string(),
-    name: z.string(),
-    email: z.string(),
-    phone: z.string().optional(),
-    createdAt: z.string(),
-  },
-  idField: "id", // The primary key field (automatically read-only)
-  required: ["phone"], // optional: additional required fields for insert (beyond auto-inferred)
-  readOnly: ["createdAt"], // optional: fields excluded from insert/update
-});
-```
+- `.primaryKey()` - Mark as primary key (automatically read-only)
+- `.notNull()` - Make field non-nullable (required for inserts)
+- `.readOnly()` - Exclude from insert/update operations
+- `.entityId(id)` - Assign FileMaker field ID (FMFID), allowing your API calls to survive FileMaker name changes
+- `.readValidator(validator)` - Transform/validate data when reading from database
+- `.writeValidator(validator)` - Transform/validate data when writing to database
 
-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.
+#### Defining Tables
 
-**Recommended:** Use `defineTableOccurrence()` for better type inference. You can also use `new TableOccurrence()` directly.
+Use `fmTableOccurrence()` to define a table with field builders:
 
 ```typescript
-import { defineTableOccurrence } from "@proofkit/fmodata";
+import { z } from "zod/v4";
+import {
+  fmTableOccurrence,
+  textField,
+  numberField,
+  timestampField,
+} from "@proofkit/fmodata";
 
-const contactsTO = defineTableOccurrence({
-  name: "contacts", // The table occurrence name in FileMaker
-  baseTable: contactsBase,
-});
+const contacts = fmTableOccurrence(
+  "contacts",
+  {
+    id: textField().primaryKey().entityId("FMFID:1"),
+    name: textField().notNull().entityId("FMFID:2"),
+    email: textField().notNull().entityId("FMFID:3"),
+    phone: textField().entityId("FMFID:4"), // Optional (nullable by default)
+    createdAt: timestampField().readOnly().entityId("FMFID:5"),
+  },
+  {
+    entityId: "FMTID:100", // Optional: FileMaker table occurrence ID
+    defaultSelect: "schema", // Optional: "all", "schema", or function. Defaults to "schema".
+    navigationPaths: ["users"], // Optional: valid navigation targets to provide type-errors when navigating/expanding
+  },
+);
 ```
 
+The function returns a table object that provides:
+
+- Column references for each field (e.g., `contacts.id`, `contacts.name`)
+- Type-safe schema for queries and operations
+- Metadata stored via Symbols (hidden from IDE autocomplete)
+
 #### Default Field Selection
 
-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`.
+FileMaker will automatically return all non-container fields from a schema if you don't specify a $select parameter in your query. This library allows you to configure default field selection behavior using the `defaultSelect` option:
 
 ```typescript
-// Option 1 (default): "schema" - Select all fields from the schema (same as "all" but more explicit)
-const usersTO = defineTableOccurrence({
-  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 1 (default): "schema" - Select all fields from the schema
+const users = fmTableOccurrence(
+  "users",
+  {
+    /* fields */
+  },
+  {
+    defaultSelect: "schema", // A $select parameter will always be added for only the fields defined in the schema
+  },
+);
 
-// Option 2: "all" - Select all fields (default behavior)
-const usersTO = defineTableOccurrence({
-  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 2: "all" - Select all fields (FileMaker default behavior)
+const users = fmTableOccurrence(
+  "users",
+  {
+    /* fields */
+  },
+  {
+    defaultSelect: "all", // No $select parameter by default; FileMaker returns all non-container fields
+  },
+);
 
-// Option 3: Array of field names - Select only specific fields by default
-const usersTO = defineTableOccurrence({
-  name: "users",
-  baseTable: usersBase,
-  defaultSelect: ["username", "email"], // Only select these fields by default
-});
+// Option 3: Function - Select specific columns by default
+const users = fmTableOccurrence(
+  "users",
+  {
+    /* fields */
+  },
+  {
+    defaultSelect: (cols) => ({
+      username: cols.username,
+      email: cols.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
+// When you call list() or get(), the defaultSelect is applied automatically
+const result = await db.from(users).list().execute();
+// If defaultSelect is a function returning { username, email }, result.data will only contain those fields
 
 // You can still override with explicit select()
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .select("username", "email", "age") // Always overrides at the per-request level
+  .select({ username: users.username, email: users.email, age: users.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 `FMServerConnection` client class.
-
-```typescript
-const db = connection.database("MyDatabase.fmp12", {
-  occurrences: [contactsTO, usersTO], // Register your table occurrences
-});
-```
-
 ## Querying Data
 
 ### Basic Queries
@@ -245,9 +262,9 @@ Get a single field value:
 
 ```typescript
 const result = await db
-  .from("users")
+  .from(users)
   .get("user-123")
-  .getSingleField("email")
+  .getSingleField(users.email)
   .execute();
 
 if (result.data) {
@@ -257,173 +274,103 @@ if (result.data) {
 
 ### 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" }] }
-```
-
-**2. Single operator object:**
-
-```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
+fmodata provides type-safe filter operations that prevent common errors at compile time. You can use either the new ORM-style API with operators and column references, or the legacy filter API.
 
-#### Shorthand Syntax
+#### New ORM-Style API (Recommended)
 
-For simple equality checks, use the shorthand:
+Use the `where()` method with filter operators and column references for type-safe filtering:
 
 ```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();
+import { eq, gt, and, or, contains } from "@proofkit/fmodata";
 
-// 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
+// Simple equality
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .filter({
-    and: [{ active: [{ eq: true }] }, { age: [{ gt: 18 }] }],
-  })
+  .where(eq(users.active, true))
   .execute();
 
-// Combine filters with OR
+// Comparison operators
+const result = await db.from(users).list().where(gt(users.age, 18)).execute();
+
+// String operators
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .filter({
-    or: [{ name: [{ eq: "John" }] }, { name: [{ eq: "Jane" }] }],
-  })
+  .where(contains(users.name, "John"))
   .execute();
 
-// IN operator
+// Combine with AND
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .filter({ age: [{ in: [18, 21, 25] }] })
+  .where(and(eq(users.active, true), gt(users.age, 18)))
   .execute();
 
-// Null checks
+// Combine with OR
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .filter({ deletedAt: [{ eq: null }] })
+  .where(or(eq(users.role, "admin"), eq(users.role, "moderator")))
   .execute();
 ```
 
-#### Logical Operators
+Available operators:
+
+- **Comparison**: `eq()`, `ne()`, `gt()`, `gte()`, `lt()`, `lte()`
+- **String**: `contains()`, `startsWith()`, `endsWith()`
+- **Array**: `inArray()`, `notInArray()`
+- **Null**: `isNull()`, `isNotNull()`
+- **Logical**: `and()`, `or()`, `not()`
+
+### Sorting
+
+Sort results using `orderBy()`. The method supports both column references (new ORM API) and string field names (legacy API).
 
-Combine multiple conditions with `and`, `or`, `not`:
+#### Using Column References (New ORM API)
 
 ```typescript
+import { asc, desc } from "@proofkit/fmodata";
+
+// Single field (ascending by default)
+const result = await db.from(users).list().orderBy(users.name).execute();
+
+// Single field with explicit direction
+const result = await db.from(users).list().orderBy(asc(users.name)).execute();
+const result = await db.from(users).list().orderBy(desc(users.age)).execute();
+
+// Multiple fields (variadic)
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .filter({
-    and: [{ name: [{ contains: "John" }] }, { age: [{ gt: 18 }] }],
-  })
+  .orderBy(asc(users.lastName), desc(users.firstName))
   .execute();
-```
-
-#### Escape Hatch
-
-For unsupported edge cases, pass a raw OData filter string:
 
-```typescript
+// Multiple fields (array syntax)
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .filter("substringof('John', name)")
+  .orderBy([
+    [users.lastName, "asc"],
+    [users.firstName, "desc"],
+  ])
   .execute();
 ```
 
-### Sorting
+#### Type Safety
 
-Sort results using `orderBy()`:
+For typed databases, `orderBy()` provides full type safety:
 
 ```typescript
-// Sort ascending
-const result = await db.from("users").list().orderBy("name").execute();
+// ✅ Valid - "name" is a field in the schema
+db.from(users).list().orderBy(users.name);
 
-// Sort descending
-const result = await db.from("users").list().orderBy("name desc").execute();
+// ✅ Valid - tuple with field and direction
+db.from(users).list().orderBy(asc(users.name));
+db.from(users).list().orderBy(desc(users.name));
 
-// Multiple sort fields
-const result = await db
-  .from("users")
-  .list()
-  .orderBy("lastName, firstName desc")
-  .execute();
+// ✅ Valid - multiple fields
+db.from(users).list().orderBy(asc(users.lastName), desc(users.firstName));
 ```
 
 ### Pagination
@@ -432,24 +379,29 @@ Control the number of records returned and pagination:
 
 ```typescript
 // Limit results
-const result = await db.from("users").list().top(10).execute();
+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();
+const result = await db.from(users).list().top(10).skip(20).execute();
 
 // Count total records
-const result = await db.from("users").list().count().execute();
+const result = await db.from(users).list().count().execute();
 ```
 
 ### Selecting Fields
 
-Select specific fields to return:
+Select specific fields to return. You can use either column references (new ORM API) or string field names (legacy API):
 
 ```typescript
+// New ORM API: Using column references (type-safe, supports renaming)
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .select("username", "email")
+  .select({
+    username: users.username,
+    email: users.email,
+    userId: users.id, // Renamed from "id" to "userId"
+  })
   .execute();
 
 // result.data[0] will only have username and email fields
@@ -461,9 +413,9 @@ Use `single()` to ensure exactly one record is returned (returns an error if zer
 
 ```typescript
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .filter({ email: { eq: "user@example.com" } })
+  .where(eq(users.email, "user@example.com"))
   .single()
   .execute();
 
@@ -477,9 +429,9 @@ Use `maybeSingle()` when you want at most one record (returns `null` if no recor
 
 ```typescript
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .filter({ email: { eq: "user@example.com" } })
+  .where(eq(users.email, "user@example.com"))
   .maybeSingle()
   .execute();
 
@@ -502,12 +454,17 @@ if (result.data) {
 All query methods can be chained together:
 
 ```typescript
+// Using new ORM API
 const result = await db
-  .from("users")
+  .from(users)
   .list()
-  .select("username", "email", "age")
-  .filter({ age: { gt: 18 } })
-  .orderBy("username")
+  .select({
+    username: users.username,
+    email: users.email,
+    age: users.age,
+  })
+  .where(gt(users.age, 18))
+  .orderBy(asc(users.username))
   .top(10)
   .skip(0)
   .execute();
@@ -522,7 +479,7 @@ Insert new records with type-safe data:
 ```typescript
 // Insert a new user
 const result = await db
-  .from("users")
+  .from(users)
   .insert({
     username: "johndoe",
     email: "john@example.com",
@@ -535,30 +492,25 @@ if (result.data) {
 }
 ```
 
-Fields are automatically required for insert if their validator doesn't allow `null` or `undefined`. You can specify additional required fields:
+Fields are automatically required for insert if they use `.notNull()`. Read-only fields (including primary keys) are automatically excluded:
 
 ```typescript
-const usersBase = defineBaseTable({
-  schema: {
-    id: z.string(), // Auto-required (not nullable), but excluded from insert (idField)
-    username: z.string(), // Auto-required (not nullable)
-    email: z.string(), // Auto-required (not nullable)
-    phone: z.string().nullable(), // Optional by default
-    createdAt: z.string(), // Auto-required, but excluded (readOnly)
-  },
-  idField: "id", // Automatically excluded from insert/update
-  required: ["phone"], // Make phone required for inserts despite being nullable
-  readOnly: ["createdAt"], // Exclude from insert/update operations
+const users = fmTableOccurrence("users", {
+  id: textField().primaryKey(), // Auto-required, but excluded from insert (primaryKey)
+  username: textField().notNull(), // Auto-required (notNull)
+  email: textField().notNull(), // Auto-required (notNull)
+  phone: textField(), // Optional by default (nullable)
+  createdAt: timestampField().readOnly(), // Excluded from insert/update
 });
 
-// TypeScript enforces: username, email, and phone are required
+// TypeScript enforces: username and email are required
 // TypeScript excludes: id and createdAt cannot be provided
 const result = await db
-  .from("users")
+  .from(users)
   .insert({
     username: "johndoe",
     email: "john@example.com",
-    phone: "+1234567890", // Required because specified in 'required' array
+    phone: "+1234567890", // Optional
   })
   .execute();
 ```
@@ -570,7 +522,7 @@ Update records by ID or filter:
 ```typescript
 // Update by ID
 const result = await db
-  .from("users")
+  .from(users)
   .update({ username: "newname" })
   .byId("user-123")
   .execute();
@@ -579,29 +531,27 @@ if (result.data) {
   console.log(`Updated ${result.data.updatedCount} record(s)`);
 }
 
-// Update by filter
+// Update by filter (using new ORM API)
+import { lt, and, eq } from "@proofkit/fmodata";
+
 const result = await db
-  .from("users")
+  .from(users)
   .update({ active: false })
-  .where((q) => q.filter({ lastLogin: { lt: "2023-01-01" } }))
+  .where(lt(users.lastLogin, "2023-01-01"))
   .execute();
 
 // Complex filter example
 const result = await db
-  .from("users")
+  .from(users)
   .update({ active: false })
-  .where((q) =>
-    q.filter({
-      and: [{ active: true }, { count: { lt: 5 } }],
-    }),
-  )
+  .where(and(eq(users.active, true), lt(users.count, 5)))
   .execute();
 
-// Update with additional query options
+// Update with additional query options (legacy filter API)
 const result = await db
   .from("users")
   .update({ active: false })
-  .where((q) => q.filter({ active: true }).top(10))
+  .where((q) => q.where(eq(users.active, true)).top(10))
   .execute();
 ```
 
@@ -611,28 +561,26 @@ Delete records by ID or filter:
 
 ```typescript
 // Delete by ID
-const result = await db.from("users").delete().byId("user-123").execute();
+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
+// Delete by filter (using new ORM API)
+import { eq, and, lt } from "@proofkit/fmodata";
+
 const result = await db
-  .from("users")
+  .from(users)
   .delete()
-  .where((q) => q.filter({ active: false }))
+  .where(eq(users.active, false))
   .execute();
 
 // Delete with complex filters
 const result = await db
-  .from("users")
+  .from(users)
   .delete()
-  .where((q) =>
-    q.filter({
-      and: [{ active: false }, { lastLogin: { lt: "2023-01-01" } }],
-    }),
-  )
+  .where(and(eq(users.active, false), lt(users.lastLogin, "2023-01-01")))
   .execute();
 ```
 
@@ -640,132 +588,145 @@ const result = await db
 
 ### Defining Navigation
 
-Define relationships between tables using the `navigation` option:
+Define navigation relationships using the `navigationPaths` option when creating table occurrences:
 
 ```typescript
-const contactsBase = defineBaseTable({
-  schema: {
-    id: z.string(),
-    name: z.string(),
-    userId: z.string(),
-  },
-  idField: "id",
-});
+import { fmTableOccurrence, textField } from "@proofkit/fmodata";
 
-const usersBase = defineBaseTable({
-  schema: {
-    id: z.string(),
-    username: z.string(),
-    email: z.string(),
+const contacts = fmTableOccurrence(
+  "contacts",
+  {
+    id: textField().primaryKey(),
+    name: textField().notNull(),
+    userId: textField().notNull(),
   },
-  idField: "id",
-});
-
-// Define navigation using functions to handle circular dependencies
-// Create base occurrences first, then add navigation
-const _contactsTO = defineTableOccurrence({
-  name: "contacts",
-  baseTable: contactsBase,
-});
+  {
+    navigationPaths: ["users"], // Valid navigation targets
+  },
+);
 
-const _usersTO = defineTableOccurrence({
-  name: "users",
-  baseTable: usersBase,
-});
+const users = fmTableOccurrence(
+  "users",
+  {
+    id: textField().primaryKey(),
+    username: textField().notNull(),
+    email: textField().notNull(),
+  },
+  {
+    navigationPaths: ["contacts"], // Valid navigation targets
+  },
+);
 
-// Then add navigation
-const contactsTO = _contactsTO.addNavigation({
-  users: () => _usersTO,
+// Use with your database
+const db = connection.database("MyDB", {
+  occurrences: [contacts, users],
 });
+```
 
-const usersTO = _usersTO.addNavigation({
-  contacts: () => _contactsTO,
-});
+The `navigationPaths` option:
 
-// You can also add navigation after creation
-const updatedUsersTO = usersTO.addNavigation({
-  profile: () => profileTO,
-});
-```
+- Specifies which table occurrences can be navigated to from this table
+- Enables runtime validation when using `expand()` or `navigate()`
+- Throws descriptive errors if you try to navigate to an invalid path
 
 ### Navigating Between Tables
 
 Navigate to related records:
 
 ```typescript
-// Navigate from a specific record
+// Navigate from a specific record (using column references)
 const result = await db
-  .from("contacts")
+  .from(contacts)
   .get("contact-123")
-  .navigate("users")
-  .select("username", "email")
+  .navigate(users)
+  .select({
+    username: users.username,
+    email: users.email,
+  })
   .execute();
 
 // Navigate without specifying a record first
-const result = await db.from("contacts").navigate("users").list().execute();
+const result = await db.from(contacts).navigate(users).list().execute();
 
-// You can navigate to arbitrary tables not in your schema
+// Using legacy API with string field names
 const result = await db
-  .from("contacts")
-  .navigate("some_other_table")
-  .list()
+  .from(contacts)
+  .get("contact-123")
+  .navigate(users)
+  .select({ username: users.username, email: users.email })
   .execute();
 ```
 
 ### Expanding Related Records
 
-Use `expand()` to include related records in your query results:
+Use `expand()` to include related records in your query results. The library validates that the target table is in the source table's `navigationPaths`:
 
 ```typescript
 // Simple expand
-const result = await db.from("contacts").list().expand("users").execute();
+const result = await db.from(contacts).list().expand(users).execute();
 
-// Expand with field selection
+// Expand with field selection (using column references)
 const result = await db
-  .from("contacts")
+  .from(contacts)
   .list()
-  .expand("users", (b) => b.select("username", "email"))
+  .expand(users, (b) =>
+    b.select({
+      username: users.username,
+      email: users.email,
+    }),
+  )
   .execute();
 
-// Expand with filtering
+// Expand with filtering (using new ORM API)
+import { eq } from "@proofkit/fmodata";
+
 const result = await db
-  .from("contacts")
+  .from(contacts)
   .list()
-  .expand("users", (b) => b.filter({ active: true }))
+  .expand(users, (b) => b.where(eq(users.active, true)))
   .execute();
 
 // Multiple expands
 const result = await db
-  .from("contacts")
+  .from(contacts)
   .list()
-  .expand("users", (b) => b.select("username"))
-  .expand("orders", (b) => b.select("total").top(5))
+  .expand(users, (b) => b.select({ username: users.username }))
+  .expand(orders, (b) => b.select({ total: orders.total }).top(5))
   .execute();
 
 // Nested expands
 const result = await db
-  .from("contacts")
+  .from(contacts)
   .list()
-  .expand("users", (usersBuilder) =>
+  .expand(users, (usersBuilder) =>
     usersBuilder
-      .select("username", "email")
-      .expand("customer", (customerBuilder) =>
-        customerBuilder.select("name", "tier"),
+      .select({
+        username: users.username,
+        email: users.email,
+      })
+      .expand(customers, (customerBuilder) =>
+        customerBuilder.select({
+          name: customers.name,
+          tier: customers.tier,
+        }),
       ),
   )
   .execute();
 
 // Complex expand with multiple options
 const result = await db
-  .from("contacts")
+  .from(contacts)
   .list()
-  .expand("users", (b) =>
+  .expand(users, (b) =>
     b
-      .select("username", "email")
-      .filter({ active: true })
-      .orderBy("username")
+      .select({
+        username: users.username,
+        email: users.email,
+      })
+      .where(eq(users.active, true))
+      .orderBy(asc(users.username))
       .top(10)
-      .expand("customer", (nested) => nested.select("name")),
+      .expand(customers, (nested) => nested.select({ name: customers.name })),
   )
   .execute();
 ```
@@ -817,29 +778,226 @@ 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.
 
+## Webhooks
+
+Webhooks allow you to receive notifications when data changes in your FileMaker database. The library provides a type-safe API for managing webhooks through the `db.webhook` property.
+
+### Adding a Webhook
+
+Create a new webhook to monitor a table for changes:
+
+```typescript
+// Basic webhook
+const result = await db.webhook.add({
+  webhook: "https://example.com/webhook",
+  tableName: contactsTable,
+});
+
+// Access the created webhook ID
+console.log(result.webHookResult.webHookID);
+```
+
+### Webhook Configuration Options
+
+Webhooks support various configuration options:
+
+```typescript
+// With custom headers
+const result = await db.webhook.add({
+  webhook: "https://example.com/webhook",
+  tableName: contactsTable,
+  headers: {
+    "X-Custom-Header": "value",
+    Authorization: "Bearer token",
+  },
+  notifySchemaChanges: true, // Notify when schema changes
+});
+
+// With field selection (using column references)
+const result = await db.webhook.add({
+  webhook: "https://example.com/webhook",
+  tableName: contacts,
+  select: [contacts.name, contacts.email, contacts.PrimaryKey],
+});
+
+// With filtering (using filter expressions)
+import { eq, gt } from "@proofkit/fmodata";
+
+const result = await db.webhook.add({
+  webhook: "https://example.com/webhook",
+  tableName: contacts,
+  filter: eq(contacts.active, true),
+  select: [contacts.name, contacts.email],
+});
+
+// Complex filter example
+const result = await db.webhook.add({
+  webhook: "https://example.com/webhook",
+  tableName: users,
+  filter: and(eq(users.active, true), gt(users.age, 18)),
+  select: [users.username, users.email],
+});
+```
+
+**Webhook Configuration Properties:**
+
+- `webhook` (required) - The URL to call when the webhook is triggered
+- `tableName` (required) - The `FMTable` instance for the table to monitor
+- `headers` (optional) - Custom headers to include in webhook requests
+- `notifySchemaChanges` (optional) - Whether to notify on schema changes
+- `select` (optional) - Field selection as a string or array of `Column` references
+- `filter` (optional) - Filter expression (string or `FilterExpression`) to limit which records trigger the webhook
+
+### Listing Webhooks
+
+Get all webhooks configured for the database:
+
+```typescript
+const result = await db.webhook.list();
+
+console.log(result.Status); // Status of the operation
+console.log(result.WebHook); // Array of webhook configurations
+
+result.WebHook.forEach((webhook) => {
+  console.log(`Webhook ${webhook.webHookID}:`);
+  console.log(`  Table: ${webhook.tableName}`);
+  console.log(`  URL: ${webhook.url}`);
+  console.log(`  Notify Schema Changes: ${webhook.notifySchemaChanges}`);
+  console.log(`  Select: ${webhook.select}`);
+  console.log(`  Filter: ${webhook.filter}`);
+  console.log(`  Pending Operations: ${webhook.pendingOperations.length}`);
+});
+```
+
+### Getting a Webhook
+
+Retrieve a specific webhook by ID:
+
+```typescript
+const webhook = await db.webhook.get(1);
+
+console.log(webhook.webHookID);
+console.log(webhook.tableName);
+console.log(webhook.url);
+console.log(webhook.headers);
+console.log(webhook.notifySchemaChanges);
+console.log(webhook.select);
+console.log(webhook.filter);
+console.log(webhook.pendingOperations);
+```
+
+### Removing a Webhook
+
+Delete a webhook by ID:
+
+```typescript
+await db.webhook.remove(1);
+```
+
+### Invoking a Webhook
+
+Manually trigger a webhook. This is useful for testing or triggering webhooks on-demand:
+
+```typescript
+// Invoke for all rows matching the webhook's filter
+await db.webhook.invoke(1);
+
+// Invoke for specific row IDs
+await db.webhook.invoke(1, { rowIDs: [63, 61] });
+```
+
+### Complete Example
+
+Here's a complete example of setting up and managing webhooks:
+
+```typescript
+import { eq } from "@proofkit/fmodata";
+
+// Add a webhook to monitor active contacts
+const addResult = await db.webhook.add({
+  webhook: "https://api.example.com/webhooks/contacts",
+  tableName: contacts,
+  headers: {
+    "X-API-Key": "your-api-key",
+  },
+  filter: eq(contacts.active, true),
+  select: [contacts.name, contacts.email, contacts.PrimaryKey],
+  notifySchemaChanges: false,
+});
+
+const webhookId = addResult.webHookResult.webHookID;
+console.log(`Created webhook with ID: ${webhookId}`);
+
+// List all webhooks
+const listResult = await db.webhook.list();
+console.log(`Total webhooks: ${listResult.WebHook.length}`);
+
+// Get the webhook we just created
+const webhook = await db.webhook.get(webhookId);
+console.log(`Webhook URL: ${webhook.url}`);
+
+// Manually invoke the webhook for specific records
+await db.webhook.invoke(webhookId, { rowIDs: [1, 2, 3] });
+
+// Remove the webhook when done
+await db.webhook.remove(webhookId);
+```
+
+**Note:** Webhooks are triggered automatically by FileMaker when records matching the webhook's filter are created, updated, or deleted. The `invoke()` method allows you to manually trigger webhooks for testing or on-demand processing.
+
 ## Batch Operations
 
 Batch operations allow you to execute multiple queries and operations together in a single request. All operations in a batch are executed atomically - they all succeed or all fail together. This is both more efficient (fewer network round-trips) and ensures data consistency across related operations.
 
+### Batch Result Structure
+
+Batch operations return a `BatchResult` object that contains individual results for each operation. Each result has its own `data`, `error`, and `status` properties, allowing you to handle success and failure on a per-operation basis:
+
+```typescript
+type BatchItemResult<T> = {
+  data: T | undefined;
+  error: FMODataErrorType | undefined;
+  status: number; // HTTP status code (0 for truncated operations)
+};
+
+type BatchResult<T extends readonly any[]> = {
+  results: { [K in keyof T]: BatchItemResult<T[K]> };
+  successCount: number;
+  errorCount: number;
+  truncated: boolean; // true if FileMaker stopped processing due to an error
+  firstErrorIndex: number | null; // Index of the first operation that failed
+};
+```
+
 ### Basic Batch with Multiple Queries
 
 Execute multiple read operations in a single batch:
 
 ```typescript
 // Create query builders
-const contactsQuery = db.from("contacts").list().top(5);
-const usersQuery = db.from("users").list().top(5);
+const contactsQuery = db.from(contacts).list().top(5);
+const usersQuery = db.from(users).list().top(5);
 
 // Execute both queries in a single batch
 const result = await db.batch([contactsQuery, usersQuery]).execute();
 
-if (result.data) {
-  // Result is a tuple matching the input builders
-  const [contacts, users] = result.data;
+// Access individual results
+const [r1, r2] = result.results;
 
-  console.log("Contacts:", contacts);
-  console.log("Users:", users);
+if (r1.error) {
+  console.error("Contacts query failed:", r1.error);
+} else {
+  console.log("Contacts:", r1.data);
+}
+
+if (r2.error) {
+  console.error("Users query failed:", r2.error);
+} else {
+  console.log("Users:", r2.data);
 }
+
+// Check summary statistics
+console.log(`Success: ${result.successCount}, Errors: ${result.errorCount}`);
 ```
 
 ### Mixed Operations (Reads and Writes)
@@ -848,22 +1006,73 @@ Combine queries, inserts, updates, and deletes in a single batch:
 
 ```typescript
 // Mix different operation types
-const listQuery = db.from("contacts").list().top(10);
-const insertOp = db.from("contacts").insert({
+const listQuery = db.from(contacts).list().top(10);
+const insertOp = db.from(contacts).insert({
   name: "John Doe",
   email: "john@example.com",
 });
-const updateOp = db.from("users").update({ active: true }).byId("user-123");
+const updateOp = db.from(users).update({ active: true }).byId("user-123");
 
 // All operations execute atomically
 const result = await db.batch([listQuery, insertOp, updateOp]).execute();
 
-if (result.data) {
-  const [contactsList, insertResult, updateResult] = result.data;
+// Access individual results
+const [r1, r2, r3] = result.results;
+
+if (r1.error) {
+  console.error("List query failed:", r1.error);
+} else {
+  console.log("Fetched contacts:", r1.data);
+}
+
+if (r2.error) {
+  console.error("Insert failed:", r2.error);
+} else {
+  console.log("Inserted contact:", r2.data);
+}
+
+if (r3.error) {
+  console.error("Update failed:", r3.error);
+} else {
+  console.log("Updated user:", r3.data);
+}
+```
+
+### Handling Errors in Batches
+
+When FileMaker encounters an error in a batch operation, it **stops processing** subsequent operations. Operations that were never executed due to an earlier error will have a `BatchTruncatedError`:
+
+```typescript
+import { BatchTruncatedError, isBatchTruncatedError } from "@proofkit/fmodata";
+
+const result = await db.batch([query1, query2, query3]).execute();
+
+const [r1, r2, r3] = result.results;
+
+// First operation succeeded
+if (r1.error) {
+  console.error("First query failed:", r1.error);
+} else {
+  console.log("First query succeeded:", r1.data);
+}
+
+// Second operation failed
+if (r2.error) {
+  console.error("Second query failed:", r2.error);
+  console.log("HTTP Status:", r2.status); // e.g., 404
+}
+
+// Third operation was never executed (truncated)
+if (r3.error && isBatchTruncatedError(r3.error)) {
+  console.log("Third operation was not executed");
+  console.log(`Failed at operation ${r3.error.failedAtIndex}`);
+  console.log(`This operation index: ${r3.error.operationIndex}`);
+  console.log("Status:", r3.status); // 0 (never executed)
+}
 
-  console.log("Fetched contacts:", contactsList);
-  console.log("Inserted contact:", insertResult);
-  console.log("Updated user:", updateResult);
+// Check if batch was truncated
+if (result.truncated) {
+  console.log(`Batch stopped early at index ${result.firstErrorIndex}`);
 }
 ```
 
@@ -874,18 +1083,31 @@ Batch operations are transactional for write operations (inserts, updates, delet
 ```typescript
 const result = await db
   .batch([
-    db.from("users").insert({ username: "alice", email: "alice@example.com" }),
-    db.from("users").insert({ username: "bob", email: "bob@example.com" }),
-    db.from("users").insert({ username: "charlie", email: "invalid" }), // This fails
+    db.from(users).insert({ username: "alice", email: "alice@example.com" }),
+    db.from(users).insert({ username: "bob", email: "bob@example.com" }),
+    db.from(users).insert({ username: "charlie", email: "invalid" }), // This fails
   ])
   .execute();
 
-if (result.error) {
+// Check individual results
+const [r1, r2, r3] = result.results;
+
+if (r1.error || r2.error || r3.error) {
   // All three inserts are rolled back - no users were created
-  console.error("Batch failed:", result.error);
+  console.error("Batch had errors:");
+  if (r1.error) console.error("Operation 1:", r1.error);
+  if (r2.error) console.error("Operation 2:", r2.error);
+  if (r3.error) console.error("Operation 3:", r3.error);
 }
 ```
 
+### Important Notes
+
+- **FileMaker stops on first error**: When an error occurs, FileMaker stops processing subsequent operations in the batch. Truncated operations will have `BatchTruncatedError` with `status: 0`.
+- **Insert operations in batches**: FileMaker ignores `Prefer: return=representation` in batch requests. Insert operations return `{}` or `{ ROWID?: number }` instead of the full created record.
+- **All results are always defined**: Every operation in the batch will have a corresponding result in `result.results`, even if it was never executed (truncated operations).
+- **Summary statistics**: Use `result.successCount`, `result.errorCount`, `result.truncated`, and `result.firstErrorIndex` for quick batch status checks.
+
 **Note:** Batch operations automatically group write operations (POST, PATCH, DELETE) into changesets for transactional behavior, while read operations (GET) are executed individually within the batch.
 
 ## Schema Management
@@ -1147,94 +1369,50 @@ await db.schema.createIndex("users", "email");
 
 ## Advanced Features
 
-### Type Safety
-
-The library provides full TypeScript type inference:
-
-```typescript
-const usersBase = defineBaseTable({
-  schema: {
-    id: z.string(),
-    username: z.string(),
-    email: z.string(),
-  },
-  idField: "id",
-});
-
-const usersTO = defineTableOccurrence({
-  name: "users",
-  baseTable: usersBase,
-});
-
-const db = connection.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 and Read-Only Fields
 
-The library automatically infers which fields are required based on whether their validator allows `null` or `undefined`:
+The library automatically infers which fields are required based on field builder configuration:
 
 ```typescript
-const usersBase = defineBaseTable({
-  schema: {
-    id: z.string(), // Auto-required, auto-readOnly (idField)
-    username: z.string(), // Auto-required (not nullable)
-    email: z.string(), // Auto-required (not nullable)
-    status: z.string().nullable(), // Optional (nullable)
-    createdAt: z.string(), // Read-only system field
-    updatedAt: z.string().nullable(), // Optional
-  },
-  idField: "id", // Automatically excluded from insert/update
-  required: ["status"], // Make status required despite being nullable
-  readOnly: ["createdAt"], // Exclude createdAt from insert/update
+const users = fmTableOccurrence("users", {
+  id: textField().primaryKey(), // Auto-required, auto-readOnly (primaryKey)
+  username: textField().notNull(), // Auto-required (notNull)
+  email: textField().notNull(), // Auto-required (notNull)
+  status: textField(), // Optional (nullable by default)
+  createdAt: timestampField().readOnly(), // Read-only system field
+  updatedAt: timestampField(), // Optional (nullable)
 });
 
-// Insert: username, email, and status are required
-// Insert: id and createdAt are excluded (cannot be provided)
-db.from("users").insert({
+// Insert: username and email are required
+// Insert: id and createdAt are excluded (cannot be provided - read-only)
+db.from(users).insert({
   username: "john",
   email: "john@example.com",
-  status: "active", // Required due to 'required' array
+  status: "active", // Optional
   updatedAt: new Date().toISOString(), // Optional
 });
 
 // Update: all fields are optional except id and createdAt are excluded
-db.from("users")
+db.from(users)
   .update({
     status: "active", // Optional
-    // id and createdAt cannot be modified
+    // id and createdAt cannot be modified (read-only)
   })
   .byId("user-123");
 ```
 
 **Key Features:**
 
-- **Auto-inference:** Non-nullable fields are automatically required for insert
-- **Additional requirements:** Use `required` to make nullable fields required for new records
-- **Read-only fields:** Use `readOnly` to exclude fields from insert/update (e.g., timestamps)
-- **Automatic ID exclusion:** The `idField` is always read-only without needing to specify it
+- **Auto-inference:** Fields with `.notNull()` are automatically required for insert
+- **Primary keys:** Fields with `.primaryKey()` are automatically read-only
+- **Read-only fields:** Use `.readOnly()` to exclude fields from insert/update (e.g., timestamps, calculated fields)
 - **Update flexibility:** All fields are optional for updates (except read-only fields)
 
 ### Prefer: fmodata.entity-ids
 
 This library supports using FileMaker's internal field identifiers (FMFID) and table occurrence identifiers (FMTID) instead of names. This protects your integration from both field and table occurrence name changes.
 
-To enable this feature, simply define your schema with entity IDs using the `defineBaseTable` and `defineTableOccurrence` functions. Behind the scenes, the library will transform your request and the response back to the names you specify in these schemas. This is an all-or-nothing feature. For it to work properly, you must define all table occurrences passed to a `Database` with entity IDs (both `fmfIds` on the base table and `fmtId` on the table occurrence).
+To enable this feature, simply define your schema with entity IDs using the `.entityId()` method on field builders and the `entityId` option in `fmTableOccurrence()`. Behind the scenes, the library will transform your request and the response back to the names you specify in your schema. This is an all-or-nothing feature. For it to work properly, you must define all table occurrences passed to a `Database` with entity IDs (both field IDs via `.entityId()` and table ID via the `entityId` option).
 
 _Note for OttoFMS proxy: This feature requires version 4.14 or later of OttoFMS_
 
@@ -1243,34 +1421,58 @@ How do I find these ids? They can be found in the XML version of the `$metadata`
 #### Basic Usage
 
 ```typescript
-import { defineBaseTable, defineTableOccurrence } from "@proofkit/fmodata";
-import { z } from "zod/v4";
+import {
+  fmTableOccurrence,
+  textField,
+  timestampField,
+} from "@proofkit/fmodata";
 
-// Define a base table with FileMaker field IDs
-const usersBase = defineBaseTable({
-  schema: {
-    id: z.string(),
-    username: z.string(),
-    email: z.string().nullable(),
-    createdAt: z.string(),
+// Define a table with FileMaker field IDs and table occurrence ID
+const users = fmTableOccurrence(
+  "users",
+  {
+    id: textField().primaryKey().entityId("FMFID:12039485"),
+    username: textField().notNull().entityId("FMFID:34323433"),
+    email: textField().entityId("FMFID:12232424"),
+    createdAt: timestampField().readOnly().entityId("FMFID:43234355"),
   },
-  idField: "id",
-  fmfIds: {
-    id: "FMFID:12039485",
-    username: "FMFID:34323433",
-    email: "FMFID:12232424",
-    createdAt: "FMFID:43234355",
+  {
+    entityId: "FMTID:12432533", // FileMaker table occurrence ID
   },
+);
+```
+
+### Special Columns (ROWID and ROWMODID)
+
+FileMaker provides special columns `ROWID` and `ROWMODID` that uniquely identify records and track modifications. These can be included in query responses when enabled.
+
+Enable special columns at the database level:
+
+```typescript
+const db = connection.database("MyDatabase", {
+  includeSpecialColumns: true,
+});
+
+const result = await db.from(users).list().execute();
+// result.data[0] will have ROWID and ROWMODID properties
+```
+
+Override at the request level:
+
+```typescript
+// Enable for this request only
+const result = await db.from(users).list().execute({
+  includeSpecialColumns: true,
 });
 
-// Create a table occurrence with a FileMaker table occurrence ID
-const usersTO = defineTableOccurrence({
-  name: "users",
-  baseTable: usersBase,
-  fmtId: "FMTID:12432533",
+// Disable for this request
+const result = await db.from(users).list().execute({
+  includeSpecialColumns: false,
 });
 ```
 
+**Important:** Special columns are only included when no `$select` query is applied (per OData specification). When using `.select()`, special columns are excluded even if `includeSpecialColumns` is enabled.
+
 ### Error Handling
 
 All operations return a `Result` type with either `data` or `error`. The library provides rich error types that help you handle different error scenarios appropriately.
@@ -1278,7 +1480,7 @@ All operations return a `Result` type with either `data` or `error`. The library
 #### Basic Error Checking
 
 ```typescript
-const result = await db.from("users").list().execute();
+const result = await db.from(users).list().execute();
 
 if (result.error) {
   console.error("Query failed:", result.error.message);
@@ -1297,7 +1499,7 @@ Handle HTTP status codes (4xx, 5xx) with the `HTTPError` class:
 ```typescript
 import { HTTPError, isHTTPError } from "@proofkit/fmodata";
 
-const result = await db.from("users").list().execute();
+const result = await db.from(users).list().execute();
 
 if (result.error) {
   if (isHTTPError(result.error)) {
@@ -1334,7 +1536,7 @@ import {
   CircuitOpenError,
 } from "@proofkit/fmodata";
 
-const result = await db.from("users").list().execute();
+const result = await db.from(users).list().execute();
 
 if (result.error) {
   if (result.error instanceof TimeoutError) {
@@ -1360,7 +1562,7 @@ When schema validation fails, you get a `ValidationError` with rich context:
 ```typescript
 import { ValidationError, isValidationError } from "@proofkit/fmodata";
 
-const result = await db.from("users").list().execute();
+const result = await db.from(users).list().execute();
 
 if (result.error) {
   if (isValidationError(result.error)) {
@@ -1379,7 +1581,7 @@ The library uses [Standard Schema](https://github.com/standard-schema/standard-s
 ```typescript
 import { ValidationError } from "@proofkit/fmodata";
 
-const result = await db.from("users").list().execute();
+const result = await db.from(users).list().execute();
 
 if (result.error instanceof ValidationError) {
   // The cause property (ES2022 Error.cause) contains the Standard Schema issues array
@@ -1432,7 +1634,7 @@ Handle OData-specific protocol errors:
 ```typescript
 import { ODataError, isODataError } from "@proofkit/fmodata";
 
-const result = await db.from("users").list().execute();
+const result = await db.from(users).list().execute();
 
 if (result.error) {
   if (isODataError(result.error)) {
@@ -1455,7 +1657,7 @@ import {
   NetworkError,
 } from "@proofkit/fmodata";
 
-const result = await db.from("users").list().execute();
+const result = await db.from(users).list().execute();
 
 if (result.error) {
   if (result.error instanceof TimeoutError) {
@@ -1477,7 +1679,7 @@ if (result.error) {
 **Pattern 2: Using kind property (for exhaustive matching):**
 
 ```typescript
-const result = await db.from("users").list().execute();
+const result = await db.from(users).list().execute();
 
 if (result.error) {
   switch (result.error.kind) {
@@ -1633,7 +1835,7 @@ const queryString = db
   .from("users")
   .list()
   .select("username", "email")
-  .filter({ active: true })
+  .where(eq(users.active, true))
   .orderBy("username")
   .top(10)
   .getQueryString();