@proofkit/fmodata 0.1.0-alpha.6 → 0.1.0-alpha.8

package/README.md

@@ -2,12 +2,14 @@
 
 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 on [GitHub](https://github.com/proofgeist/proofkit/issues).
+⚠️ WARNING: This library is in "alpha" status. It's still in active development and the API is subject to change. Feedback is welcome on the [community forum](https://community.ottomatic.cloud/c/proofkit/13) or on [GitHub](https://github.com/proofgeist/proofkit/issues).
 
 Roadmap:
 
 - [ ] Crossjoin support
-- [ ] Batch operations
+- [x] Batch operations
+  - [ ] Automatically chunk requests into smaller batches (e.g. max 512 inserts per batch)
+- [x] Schema updates (add/update tables and fields)
 - [ ] Proper docs at proofkit.dev
 - [ ] @proofkit/typegen integration
 
@@ -24,8 +26,8 @@ Here's a minimal example to get you started:
 ```typescript
 import {
   FMServerConnection,
-  BaseTable,
-  TableOccurrence,
+  defineBaseTable,
+  defineTableOccurrence,
 } from "@proofkit/fmodata";
 import { z } from "zod/v4";
 
@@ -43,7 +45,7 @@ const connection = new FMServerConnection({
 });
 
 // 2. Define your table schema
-const usersBase = new BaseTable({
+const usersBase = defineBaseTable({
   schema: {
     id: z.string(),
     username: z.string(),
@@ -54,7 +56,7 @@ const usersBase = new BaseTable({
 });
 
 // 3. Create a table occurrence
-const usersTO = new TableOccurrence({
+const usersTO = defineTableOccurrence({
   name: "users",
   baseTable: usersBase,
 });
@@ -79,7 +81,7 @@ if (data) {
 
 ## Core Concepts
 
-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. The builder pattern is designed to support batch operations in the future, allowing you to execute multiple operations in a single request as supported by the FileMaker OData API. **Note:** Batch operations are not yet supported but are planned before the production release. It's also helpful for testing the library, as you can call `getQueryString()` to get the OData query string without executing the request.
+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. The builder pattern allows you to build complex queries and also supports batch operations, allowing you to execute multiple operations in a single request as supported by the FileMaker OData API. It's also helpful for testing the library, as you can 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.
 
@@ -125,15 +127,21 @@ const connection = new FMServerConnection({
 
 ### 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.
+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.
+
+**Helper Functions vs Constructors:**
+
+- **`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.
+
+- **`new BaseTable()`** and **`new TableOccurrence()`** - Still supported for backward compatibility, but may have slightly less precise type inference in some cases.
 
 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";
+import { defineBaseTable } from "@proofkit/fmodata";
 
-const contactsBase = new BaseTable({
+const contactsBase = defineBaseTable({
   schema: {
     id: z.string(),
     name: z.string(),
@@ -149,10 +157,12 @@ const contactsBase = new BaseTable({
 
 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.
 
+**Recommended:** Use `defineTableOccurrence()` for better type inference. You can also use `new TableOccurrence()` directly.
+
 ```typescript
-import { TableOccurrence } from "@proofkit/fmodata";
+import { defineTableOccurrence } from "@proofkit/fmodata";
 
-const contactsTO = new TableOccurrence({
+const contactsTO = defineTableOccurrence({
   name: "contacts", // The table occurrence name in FileMaker
   baseTable: contactsBase,
 });
@@ -164,21 +174,21 @@ FileMaker will automatically return all non-container fields from a schema if yo
 
 ```typescript
 // Option 1 (default): "schema" - Select all fields from the schema (same as "all" but more explicit)
-const usersTO = new TableOccurrence({
+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 2: "all" - Select all fields (default behavior)
-const usersTO = new TableOccurrence({
+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 3: Array of field names - Select only specific fields by default
-const usersTO = new TableOccurrence({
+const usersTO = defineTableOccurrence({
   name: "users",
   baseTable: usersBase,
   defaultSelect: ["username", "email"], // Only select these fields by default
@@ -528,7 +538,7 @@ if (result.data) {
 Fields are automatically required for insert if their validator doesn't allow `null` or `undefined`. You can specify additional required fields:
 
 ```typescript
-const usersBase = new BaseTable({
+const usersBase = defineBaseTable({
   schema: {
     id: z.string(), // Auto-required (not nullable), but excluded from insert (idField)
     username: z.string(), // Auto-required (not nullable)
@@ -633,7 +643,7 @@ const result = await db
 Define relationships between tables using the `navigation` option:
 
 ```typescript
-const contactsBase = new BaseTable({
+const contactsBase = defineBaseTable({
   schema: {
     id: z.string(),
     name: z.string(),
@@ -642,7 +652,7 @@ const contactsBase = new BaseTable({
   idField: "id",
 });
 
-const usersBase = new BaseTable({
+const usersBase = defineBaseTable({
   schema: {
     id: z.string(),
     username: z.string(),
@@ -652,20 +662,24 @@ const usersBase = new BaseTable({
 });
 
 // Define navigation using functions to handle circular dependencies
-const contactsTO = new TableOccurrence({
+// Create base occurrences first, then add navigation
+const _contactsTO = defineTableOccurrence({
   name: "contacts",
   baseTable: contactsBase,
-  navigation: {
-    users: () => usersTO, // Relationship to users table
-  },
 });
 
-const usersTO = new TableOccurrence({
+const _usersTO = defineTableOccurrence({
   name: "users",
   baseTable: usersBase,
-  navigation: {
-    contacts: () => contactsTO, // Relationship to contacts table
-  },
+});
+
+// Then add navigation
+const contactsTO = _contactsTO.addNavigation({
+  users: () => _usersTO,
+});
+
+const usersTO = _usersTO.addNavigation({
+  contacts: () => _contactsTO,
 });
 
 // You can also add navigation after creation
@@ -803,6 +817,334 @@ 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.
 
+## 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.
+
+### 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);
+
+// 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;
+
+  console.log("Contacts:", contacts);
+  console.log("Users:", users);
+}
+```
+
+### Mixed Operations (Reads and Writes)
+
+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({
+  name: "John Doe",
+  email: "john@example.com",
+});
+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;
+
+  console.log("Fetched contacts:", contactsList);
+  console.log("Inserted contact:", insertResult);
+  console.log("Updated user:", updateResult);
+}
+```
+
+### Transactional Behavior
+
+Batch operations are transactional for write operations (inserts, updates, deletes). If any operation in the batch fails, all write operations are rolled back:
+
+```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
+  ])
+  .execute();
+
+if (result.error) {
+  // All three inserts are rolled back - no users were created
+  console.error("Batch failed:", result.error);
+}
+```
+
+**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
+
+The library provides methods for managing database schema through the `db.schema` property. You can create and delete tables, add and remove fields, and manage indexes.
+
+### Creating Tables
+
+Create a new table with field definitions:
+
+```typescript
+import type { Field } from "@proofkit/fmodata";
+
+const fields: Field[] = [
+  {
+    name: "id",
+    type: "string",
+    primary: true,
+    maxLength: 36,
+  },
+  {
+    name: "username",
+    type: "string",
+    nullable: false,
+    unique: true,
+    maxLength: 50,
+  },
+  {
+    name: "email",
+    type: "string",
+    nullable: false,
+    maxLength: 255,
+  },
+  {
+    name: "age",
+    type: "numeric",
+    nullable: true,
+  },
+  {
+    name: "created_at",
+    type: "timestamp",
+    default: "CURRENT_TIMESTAMP",
+  },
+];
+
+const tableDefinition = await db.schema.createTable("users", fields);
+console.log(tableDefinition.tableName); // "users"
+console.log(tableDefinition.fields); // Array of field definitions
+```
+
+### Field Types
+
+The library supports various field types:
+
+**String Fields:**
+
+```typescript
+{
+  name: "username",
+  type: "string",
+  maxLength: 100, // Optional: varchar(100)
+  nullable: true,
+  unique: true,
+  default: "USER" | "USERNAME" | "CURRENT_USER", // Optional
+  repetitions: 5, // Optional: for repeating fields
+}
+```
+
+**Numeric Fields:**
+
+```typescript
+{
+  name: "age",
+  type: "numeric",
+  nullable: true,
+  primary: false,
+  unique: false,
+}
+```
+
+**Date Fields:**
+
+```typescript
+{
+  name: "birth_date",
+  type: "date",
+  default: "CURRENT_DATE" | "CURDATE", // Optional
+  nullable: true,
+}
+```
+
+**Time Fields:**
+
+```typescript
+{
+  name: "start_time",
+  type: "time",
+  default: "CURRENT_TIME" | "CURTIME", // Optional
+  nullable: true,
+}
+```
+
+**Timestamp Fields:**
+
+```typescript
+{
+  name: "created_at",
+  type: "timestamp",
+  default: "CURRENT_TIMESTAMP" | "CURTIMESTAMP", // Optional
+  nullable: false,
+}
+```
+
+**Container Fields:**
+
+```typescript
+{
+  name: "avatar",
+  type: "container",
+  externalSecurePath: "/secure/path", // Optional
+  nullable: true,
+}
+```
+
+### Adding Fields to Existing Tables
+
+Add new fields to an existing table:
+
+```typescript
+const newFields: Field[] = [
+  {
+    name: "phone",
+    type: "string",
+    nullable: true,
+    maxLength: 20,
+  },
+  {
+    name: "bio",
+    type: "string",
+    nullable: true,
+    maxLength: 1000,
+  },
+];
+
+const updatedTable = await db.schema.addFields("users", newFields);
+```
+
+### Deleting Tables and Fields
+
+Delete an entire table:
+
+```typescript
+await db.schema.deleteTable("old_table");
+```
+
+Delete a specific field from a table:
+
+```typescript
+await db.schema.deleteField("users", "old_field");
+```
+
+### Managing Indexes
+
+Create an index on a field:
+
+```typescript
+const index = await db.schema.createIndex("users", "email");
+console.log(index.indexName); // "email"
+```
+
+Delete an index:
+
+```typescript
+await db.schema.deleteIndex("users", "email");
+```
+
+### Complete Example
+
+Here's a complete example of creating a table with various field types:
+
+```typescript
+const fields: Field[] = [
+  // Primary key
+  {
+    name: "id",
+    type: "string",
+    primary: true,
+    maxLength: 36,
+  },
+
+  // String fields
+  {
+    name: "username",
+    type: "string",
+    nullable: false,
+    unique: true,
+    maxLength: 50,
+  },
+  {
+    name: "email",
+    type: "string",
+    nullable: false,
+    maxLength: 255,
+  },
+
+  // Numeric field
+  {
+    name: "age",
+    type: "numeric",
+    nullable: true,
+  },
+
+  // Date/time fields
+  {
+    name: "birth_date",
+    type: "date",
+    nullable: true,
+  },
+  {
+    name: "created_at",
+    type: "timestamp",
+    default: "CURRENT_TIMESTAMP",
+    nullable: false,
+  },
+
+  // Container field
+  {
+    name: "avatar",
+    type: "container",
+    nullable: true,
+  },
+
+  // Repeating field
+  {
+    name: "tags",
+    type: "string",
+    repetitions: 5,
+    maxLength: 50,
+  },
+];
+
+// Create the table
+const table = await db.schema.createTable("users", fields);
+
+// Later, add more fields
+await db.schema.addFields("users", [
+  {
+    name: "phone",
+    type: "string",
+    nullable: true,
+  },
+]);
+
+// Create an index on email
+await db.schema.createIndex("users", "email");
+```
+
+**Note:** Schema management operations require appropriate access privileges on your FileMaker account. Operations will throw errors if you don't have the necessary permissions.
+
 ## Advanced Features
 
 ### Type Safety
@@ -810,7 +1152,7 @@ console.log(result.result.recordId);
 The library provides full TypeScript type inference:
 
 ```typescript
-const usersBase = new BaseTable({
+const usersBase = defineBaseTable({
   schema: {
     id: z.string(),
     username: z.string(),
@@ -819,7 +1161,7 @@ const usersBase = new BaseTable({
   idField: "id",
 });
 
-const usersTO = new TableOccurrence({
+const usersTO = defineTableOccurrence({
   name: "users",
   baseTable: usersBase,
 });
@@ -848,7 +1190,7 @@ db.from("users")
 The library automatically infers which fields are required based on whether their validator allows `null` or `undefined`:
 
 ```typescript
-const usersBase = new BaseTable({
+const usersBase = defineBaseTable({
   schema: {
     id: z.string(), // Auto-required, auto-readOnly (idField)
     username: z.string(), // Auto-required (not nullable)
@@ -892,7 +1234,7 @@ db.from("users")
 
 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 the `BaseTableWithIds` and `TableOccurrenceWithIds` classes. 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 the `TableOccurrenceWithIds` class.
+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).
 
 _Note for OttoFMS proxy: This feature requires version 4.14 or later of OttoFMS_
 
@@ -901,11 +1243,11 @@ How do I find these ids? They can be found in the XML version of the `$metadata`
 #### Basic Usage
 
 ```typescript
-import { BaseTableWithIds, TableOccurrenceWithIds } from "@proofkit/fmodata";
+import { defineBaseTable, defineTableOccurrence } from "@proofkit/fmodata";
 import { z } from "zod/v4";
 
 // Define a base table with FileMaker field IDs
-const usersBase = new BaseTableWithIds({
+const usersBase = defineBaseTable({
   schema: {
     id: z.string(),
     username: z.string(),
@@ -922,9 +1264,9 @@ const usersBase = new BaseTableWithIds({
 });
 
 // Create a table occurrence with a FileMaker table occurrence ID
-const usersTO = new TableOccurrenceWithIds({
+const usersTO = defineTableOccurrence({
   name: "users",
-  baseTable: usersBase, // Must be a BaseTableWithIds
+  baseTable: usersBase,
   fmtId: "FMTID:12432533",
 });
 ```

package/dist/esm/client/base-table.d.ts

@@ -72,6 +72,7 @@ export declare class BaseTable<Schema extends Record<string, StandardSchemaV1> =
         idField?: IdField;
         required?: Required;
         readOnly?: ReadOnly;
+        fmfIds?: Record<string, `FMFID:${string}`>;
     });
     /**
      * Returns the FileMaker field ID (FMFID) for a given field name, or the field name itself if not using IDs.
@@ -91,40 +92,34 @@ export declare class BaseTable<Schema extends Record<string, StandardSchemaV1> =
     isUsingFieldIds(): boolean;
 }
 /**
- * BaseTableWithIds extends BaseTable to require FileMaker field IDs (fmfIds).
- * Use this class when you need to work with FileMaker's internal field identifiers.
+ * Creates a BaseTable with proper TypeScript type inference.
  *
- * @template Schema - Record of field names to StandardSchemaV1 validators
- * @template IdField - The name of the primary key field (optional, automatically read-only)
- * @template Required - Additional field names to require on insert (beyond auto-inferred required fields)
- * @template ReadOnly - Field names that cannot be modified via insert/update (idField is automatically read-only)
+ * This function should be used instead of `new BaseTable()` to ensure
+ * field names are properly typed throughout the library.
  *
- * @example
+ * @example Without entity IDs
  * ```ts
- * import { z } from "zod";
+ * const users = defineBaseTable({
+ *   schema: { id: z.string(), name: z.string() },
+ *   idField: "id",
+ * });
+ * ```
  *
- * const usersTableWithIds = new BaseTableWithIds({
- *   schema: {
- *     id: z.string(),
- *     name: z.string(),
- *     email: z.string().nullable(),
- *   },
+ * @example With entity IDs (FileMaker field IDs)
+ * ```ts
+ * const products = defineBaseTable({
+ *   schema: { id: z.string(), name: z.string() },
  *   idField: "id",
- *   fmfIds: {
- *     id: "FMFID:1",
- *     name: "FMFID:2",
- *     email: "FMFID:3",
- *   },
+ *   fmfIds: { id: "FMFID:1", name: "FMFID:2" },
  * });
  * ```
  */
-export declare class BaseTableWithIds<Schema extends Record<string, StandardSchemaV1> = any, IdField extends keyof Schema | undefined = undefined, Required extends readonly (keyof Schema)[] = readonly [], ReadOnly extends readonly (keyof Schema)[] = readonly []> extends BaseTable<Schema, IdField, Required, ReadOnly> {
-    readonly fmfIds: Record<keyof Schema, `FMFID:${string}`>;
-    constructor(config: {
-        schema: Schema;
-        fmfIds: Record<keyof Schema, `FMFID:${string}`>;
-        idField?: IdField;
-        required?: Required;
-        readOnly?: ReadOnly;
-    });
-}
+export declare function defineBaseTable<const Schema extends Record<string, StandardSchemaV1>, IdField extends keyof Schema | undefined = undefined, const Required extends readonly (keyof Schema)[] = readonly [], const ReadOnly extends readonly (keyof Schema)[] = readonly []>(config: {
+    schema: Schema;
+    idField?: IdField;
+    required?: Required;
+    readOnly?: ReadOnly;
+    fmfIds?: {
+        [K in keyof Schema]: `FMFID:${string}`;
+    };
+}): BaseTable<Schema, IdField, Required, ReadOnly>;

package/dist/esm/client/base-table.js

@@ -12,6 +12,7 @@ class BaseTable {
     this.idField = config.idField;
     this.required = config.required;
     this.readOnly = config.readOnly;
+    this.fmfIds = config.fmfIds;
   }
   /**
    * Returns the FileMaker field ID (FMFID) for a given field name, or the field name itself if not using IDs.
@@ -46,15 +47,11 @@ class BaseTable {
     return this.fmfIds !== void 0;
   }
 }
-class BaseTableWithIds extends BaseTable {
-  constructor(config) {
-    super(config);
-    __publicField(this, "fmfIds");
-    this.fmfIds = config.fmfIds;
-  }
+function defineBaseTable(config) {
+  return new BaseTable(config);
 }
 export {
   BaseTable,
-  BaseTableWithIds
+  defineBaseTable
 };
 //# sourceMappingURL=base-table.js.map