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

package/dist/esm/client/schema-manager.d.ts

@@ -0,0 +1,57 @@
+import { FFetchOptions } from '@fetchkit/ffetch';
+import { ExecutionContext } from '../types.js';
+type GenericField = {
+    name: string;
+    nullable?: boolean;
+    primary?: boolean;
+    unique?: boolean;
+    global?: boolean;
+    repetitions?: number;
+};
+type StringField = GenericField & {
+    type: "string";
+    maxLength?: number;
+    default?: "USER" | "USERNAME" | "CURRENT_USER";
+};
+type NumericField = GenericField & {
+    type: "numeric";
+};
+type DateField = GenericField & {
+    type: "date";
+    default?: "CURRENT_DATE" | "CURDATE";
+};
+type TimeField = GenericField & {
+    type: "time";
+    default?: "CURRENT_TIME" | "CURTIME";
+};
+type TimestampField = GenericField & {
+    type: "timestamp";
+    default?: "CURRENT_TIMESTAMP" | "CURTIMESTAMP";
+};
+type ContainerField = GenericField & {
+    type: "container";
+    externalSecurePath?: string;
+};
+export type Field = StringField | NumericField | DateField | TimeField | TimestampField | ContainerField;
+export type { StringField, NumericField, DateField, TimeField, TimestampField, ContainerField, };
+type FileMakerField = Omit<Field, "type" | "repetitions" | "maxLength"> & {
+    type: string;
+};
+type TableDefinition = {
+    tableName: string;
+    fields: FileMakerField[];
+};
+export declare class SchemaManager {
+    private readonly databaseName;
+    private readonly context;
+    constructor(databaseName: string, context: ExecutionContext);
+    createTable(tableName: string, fields: Field[], options?: RequestInit & FFetchOptions): Promise<TableDefinition>;
+    addFields(tableName: string, fields: Field[], options?: RequestInit & FFetchOptions): Promise<TableDefinition>;
+    deleteTable(tableName: string, options?: RequestInit & FFetchOptions): Promise<void>;
+    deleteField(tableName: string, fieldName: string, options?: RequestInit & FFetchOptions): Promise<void>;
+    createIndex(tableName: string, fieldName: string, options?: RequestInit & FFetchOptions): Promise<{
+        indexName: string;
+    }>;
+    deleteIndex(tableName: string, fieldName: string, options?: RequestInit & FFetchOptions): Promise<void>;
+    private static compileFieldDefinition;
+}

package/dist/esm/client/schema-manager.js

@@ -0,0 +1,132 @@
+class SchemaManager {
+  constructor(databaseName, context) {
+    this.databaseName = databaseName;
+    this.context = context;
+  }
+  async createTable(tableName, fields, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          tableName,
+          fields: fields.map(SchemaManager.compileFieldDefinition)
+        }),
+        ...options
+      }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+    return result.data;
+  }
+  async addFields(tableName, fields, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}`,
+      {
+        method: "PATCH",
+        body: JSON.stringify({
+          fields: fields.map(SchemaManager.compileFieldDefinition)
+        }),
+        ...options
+      }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+    return result.data;
+  }
+  async deleteTable(tableName, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}`,
+      { method: "DELETE", ...options }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+  }
+  async deleteField(tableName, fieldName, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Tables/${tableName}/${fieldName}`,
+      {
+        method: "DELETE",
+        ...options
+      }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+  }
+  async createIndex(tableName, fieldName, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Indexes/${tableName}`,
+      {
+        method: "POST",
+        body: JSON.stringify({ indexName: fieldName }),
+        ...options
+      }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+    return result.data;
+  }
+  async deleteIndex(tableName, fieldName, options) {
+    const result = await this.context._makeRequest(
+      `/${this.databaseName}/FileMaker_Indexes/${tableName}/${fieldName}`,
+      {
+        method: "DELETE",
+        ...options
+      }
+    );
+    if (result.error) {
+      throw result.error;
+    }
+  }
+  static compileFieldDefinition(field) {
+    let type = field.type;
+    const repetitions = field.repetitions;
+    if (field.type === "string") {
+      type = "varchar";
+      const stringField = field;
+      if (stringField.maxLength !== void 0) {
+        type += `(${stringField.maxLength})`;
+      }
+    }
+    if (repetitions !== void 0) {
+      type += `[${repetitions}]`;
+    }
+    const result = {
+      name: field.name,
+      type
+    };
+    if (field.nullable !== void 0) result.nullable = field.nullable;
+    if (field.primary !== void 0) result.primary = field.primary;
+    if (field.unique !== void 0) result.unique = field.unique;
+    if (field.global !== void 0) result.global = field.global;
+    if (field.type === "string") {
+      const stringField = field;
+      if (stringField.default !== void 0)
+        result.default = stringField.default;
+    } else if (field.type === "date") {
+      const dateField = field;
+      if (dateField.default !== void 0) result.default = dateField.default;
+    } else if (field.type === "time") {
+      const timeField = field;
+      if (timeField.default !== void 0) result.default = timeField.default;
+    } else if (field.type === "timestamp") {
+      const timestampField = field;
+      if (timestampField.default !== void 0)
+        result.default = timestampField.default;
+    } else if (field.type === "container") {
+      const containerField = field;
+      if (containerField.externalSecurePath !== void 0)
+        result.externalSecurePath = containerField.externalSecurePath;
+    }
+    return result;
+  }
+}
+export {
+  SchemaManager
+};
+//# sourceMappingURL=schema-manager.js.map

package/dist/esm/client/schema-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-manager.js","sources":["../../../src/client/schema-manager.ts"],"sourcesContent":["import type { FFetchOptions } from \"@fetchkit/ffetch\";\nimport type { ExecutionContext } from \"../types\";\n\ntype GenericField = {\n  name: string;\n  nullable?: boolean;\n  primary?: boolean;\n  unique?: boolean;\n  global?: boolean;\n  repetitions?: number;\n};\n\ntype StringField = GenericField & {\n  type: \"string\";\n  maxLength?: number;\n  default?: \"USER\" | \"USERNAME\" | \"CURRENT_USER\";\n};\n\ntype NumericField = GenericField & {\n  type: \"numeric\";\n};\n\ntype DateField = GenericField & {\n  type: \"date\";\n  default?: \"CURRENT_DATE\" | \"CURDATE\";\n};\n\ntype TimeField = GenericField & {\n  type: \"time\";\n  default?: \"CURRENT_TIME\" | \"CURTIME\";\n};\n\ntype TimestampField = GenericField & {\n  type: \"timestamp\";\n  default?: \"CURRENT_TIMESTAMP\" | \"CURTIMESTAMP\";\n};\n\ntype ContainerField = GenericField & {\n  type: \"container\";\n  externalSecurePath?: string;\n};\n\nexport type Field =\n  | StringField\n  | NumericField\n  | DateField\n  | TimeField\n  | TimestampField\n  | ContainerField;\n\nexport type {\n  StringField,\n  NumericField,\n  DateField,\n  TimeField,\n  TimestampField,\n  ContainerField,\n};\n\ntype FileMakerField = Omit<Field, \"type\" | \"repetitions\" | \"maxLength\"> & {\n  type: string;\n};\n\ntype TableDefinition = {\n  tableName: string;\n  fields: FileMakerField[];\n};\n\nexport class SchemaManager {\n  public constructor(\n    private readonly databaseName: string,\n    private readonly context: ExecutionContext,\n  ) {}\n\n  public async createTable(\n    tableName: string,\n    fields: Field[],\n    options?: RequestInit & FFetchOptions,\n  ): Promise<TableDefinition> {\n    const result = await this.context._makeRequest<TableDefinition>(\n      `/${this.databaseName}/FileMaker_Tables`,\n      {\n        method: \"POST\",\n        body: JSON.stringify({\n          tableName,\n          fields: fields.map(SchemaManager.compileFieldDefinition),\n        }),\n        ...options,\n      },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n\n    return result.data;\n  }\n\n  public async addFields(\n    tableName: string,\n    fields: Field[],\n    options?: RequestInit & FFetchOptions,\n  ): Promise<TableDefinition> {\n    const result = await this.context._makeRequest<TableDefinition>(\n      `/${this.databaseName}/FileMaker_Tables/${tableName}`,\n      {\n        method: \"PATCH\",\n        body: JSON.stringify({\n          fields: fields.map(SchemaManager.compileFieldDefinition),\n        }),\n        ...options,\n      },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n\n    return result.data;\n  }\n\n  public async deleteTable(\n    tableName: string,\n    options?: RequestInit & FFetchOptions,\n  ): Promise<void> {\n    const result = await this.context._makeRequest(\n      `/${this.databaseName}/FileMaker_Tables/${tableName}`,\n      { method: \"DELETE\", ...options },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n  }\n\n  public async deleteField(\n    tableName: string,\n    fieldName: string,\n    options?: RequestInit & FFetchOptions,\n  ): Promise<void> {\n    const result = await this.context._makeRequest(\n      `/${this.databaseName}/FileMaker_Tables/${tableName}/${fieldName}`,\n      {\n        method: \"DELETE\",\n        ...options,\n      },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n  }\n\n  public async createIndex(\n    tableName: string,\n    fieldName: string,\n    options?: RequestInit & FFetchOptions,\n  ): Promise<{ indexName: string }> {\n    const result = await this.context._makeRequest<{ indexName: string }>(\n      `/${this.databaseName}/FileMaker_Indexes/${tableName}`,\n      {\n        method: \"POST\",\n        body: JSON.stringify({ indexName: fieldName }),\n        ...options,\n      },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n\n    return result.data;\n  }\n\n  public async deleteIndex(\n    tableName: string,\n    fieldName: string,\n    options?: RequestInit & FFetchOptions,\n  ): Promise<void> {\n    const result = await this.context._makeRequest(\n      `/${this.databaseName}/FileMaker_Indexes/${tableName}/${fieldName}`,\n      {\n        method: \"DELETE\",\n        ...options,\n      },\n    );\n\n    if (result.error) {\n      throw result.error;\n    }\n  }\n\n  private static compileFieldDefinition(field: Field): FileMakerField {\n    let type: string = field.type;\n    const repetitions = field.repetitions;\n\n    // Handle string fields - convert to varchar and add maxLength if present\n    if (field.type === \"string\") {\n      type = \"varchar\";\n      const stringField = field as StringField;\n      if (stringField.maxLength !== undefined) {\n        type += `(${stringField.maxLength})`;\n      }\n    }\n\n    // Add repetitions suffix if present\n    if (repetitions !== undefined) {\n      type += `[${repetitions}]`;\n    }\n\n    // Build the result object, excluding type, maxLength, and repetitions\n    const result: any = {\n      name: field.name,\n      type,\n    };\n\n    // Add optional properties that FileMaker expects\n    if (field.nullable !== undefined) result.nullable = field.nullable;\n    if (field.primary !== undefined) result.primary = field.primary;\n    if (field.unique !== undefined) result.unique = field.unique;\n    if (field.global !== undefined) result.global = field.global;\n\n    // Add type-specific properties\n    if (field.type === \"string\") {\n      const stringField = field as StringField;\n      if (stringField.default !== undefined)\n        result.default = stringField.default;\n    } else if (field.type === \"date\") {\n      const dateField = field as DateField;\n      if (dateField.default !== undefined) result.default = dateField.default;\n    } else if (field.type === \"time\") {\n      const timeField = field as TimeField;\n      if (timeField.default !== undefined) result.default = timeField.default;\n    } else if (field.type === \"timestamp\") {\n      const timestampField = field as TimestampField;\n      if (timestampField.default !== undefined)\n        result.default = timestampField.default;\n    } else if (field.type === \"container\") {\n      const containerField = field as ContainerField;\n      if (containerField.externalSecurePath !== undefined)\n        result.externalSecurePath = containerField.externalSecurePath;\n    }\n\n    return result as FileMakerField;\n  }\n}\n"],"names":[],"mappings":"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"}

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

@@ -1,25 +1,86 @@
 import { BaseTable } from './base-table.js';
 type ExtractSchema<BT> = BT extends BaseTable<infer S, any, any, any> ? S : never;
-type ResolveNavigation<T> = {
-    [K in keyof T]: T[K] extends () => infer R ? R : T[K];
-};
-export declare class TableOccurrence<BT extends BaseTable<any, any, any, any> = any, Name extends string = string, Nav extends Record<string, TableOccurrence<any, any, any, any> | (() => TableOccurrence<any, any, any, any>)> = {}, DefSelect extends "all" | "schema" | readonly (keyof ExtractSchema<BT>)[] = "schema"> {
+declare const INTERNAL_NAV: unique symbol;
+export declare class TableOccurrence<BT extends BaseTable<any, any, any, any> = any, Name extends string = string, Nav extends Record<string, TableOccurrence<any, any, any, any>> = {}, DefSelect extends "all" | "schema" | readonly (keyof ExtractSchema<BT>)[] = "schema"> {
     readonly name: Name;
     readonly baseTable: BT;
-    private _navigationConfig;
-    readonly navigation: ResolveNavigation<Nav>;
+    readonly navigation: Nav;
     readonly defaultSelect: DefSelect;
+    readonly fmtId?: `FMTID:${string}`;
     constructor(config: {
         readonly name: Name;
         readonly baseTable: BT;
-        readonly navigation?: Nav;
         readonly defaultSelect?: DefSelect;
+        readonly fmtId?: `FMTID:${string}`;
+        /** @internal Used by buildOccurrences - do not use directly */
+        readonly [INTERNAL_NAV]?: Nav;
     });
-    addNavigation<NewNav extends Record<string, TableOccurrence<any, any, any, any> | (() => TableOccurrence<any, any, any, any>)>>(nav: NewNav): TableOccurrence<BT, Name, Nav & NewNav, DefSelect>;
+    /**
+     * Returns the FileMaker table occurrence ID (FMTID) if available, or the table name.
+     * @returns The FMTID string or the table name
+     */
+    getTableId(): string;
+    /**
+     * Returns the table occurrence name.
+     * @returns The table name
+     */
+    getTableName(): string;
+    /**
+     * Returns true if this TableOccurrence is using FileMaker table occurrence IDs.
+     */
+    isUsingTableId(): boolean;
+    /**
+     * @internal Creates a new TableOccurrence with navigation - used by buildOccurrences
+     */
+    static _withNavigation<BT extends BaseTable<any, any, any, any>, Name extends string, Nav extends Record<string, TableOccurrence<any, any, any, any>>, DefSelect extends "all" | "schema" | readonly (keyof ExtractSchema<BT>)[] = "schema">(base: TableOccurrence<BT, Name, any, DefSelect>, navigation: Nav): TableOccurrence<BT, Name, Nav, DefSelect>;
 }
 export declare function createTableOccurrence<const Name extends string, BT extends BaseTable<any, any, any, any>, DefSelect extends "all" | "schema" | readonly (keyof ExtractSchema<BT>)[] = "schema">(config: {
     name: Name;
     baseTable: BT;
     defaultSelect?: DefSelect;
+    fmtId?: `FMTID:${string}`;
+}): TableOccurrence<BT, Name, {}, DefSelect>;
+/**
+ * Creates a TableOccurrence with proper TypeScript type inference.
+ *
+ * Use this function to create TableOccurrence instances with full type safety.
+ * For navigation between tables, use `buildOccurrences()` after defining your TOs.
+ *
+ * @example
+ * ```ts
+ * const users = defineTableOccurrence({
+ *   name: "users",
+ *   baseTable: usersBase,
+ * });
+ * ```
+ *
+ * @example With entity IDs
+ * ```ts
+ * const products = defineTableOccurrence({
+ *   name: "products",
+ *   baseTable: productsBase,
+ *   fmtId: "FMTID:12345",
+ * });
+ * ```
+ *
+ * @example With navigation (use buildOccurrences)
+ * ```ts
+ * const _users = defineTableOccurrence({ name: "users", baseTable: usersBase });
+ * const _contacts = defineTableOccurrence({ name: "contacts", baseTable: contactsBase });
+ *
+ * const [users, contacts] = buildOccurrences({
+ *   occurrences: [_users, _contacts],
+ *   navigation: {
+ *     users: ["contacts"],
+ *     contacts: ["users"],
+ *   },
+ * });
+ * ```
+ */
+export declare function defineTableOccurrence<const Name extends string, BT extends BaseTable<any, any, any, any>, const DefSelect extends "all" | "schema" | readonly (keyof ExtractSchema<BT>)[] = "schema">(config: {
+    readonly name: Name;
+    readonly baseTable: BT;
+    readonly fmtId?: `FMTID:${string}`;
+    readonly defaultSelect?: DefSelect;
 }): TableOccurrence<BT, Name, {}, DefSelect>;
 export {};

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

@@ -1,47 +1,58 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-function createNavigationGetters(navConfig) {
-  const result = {};
-  for (const key in navConfig) {
-    Object.defineProperty(result, key, {
-      get() {
-        const navItem = navConfig[key];
-        return typeof navItem === "function" ? navItem() : navItem;
-      },
-      enumerable: true,
-      configurable: true
-    });
-  }
-  return result;
-}
+const INTERNAL_NAV = Symbol("internal-navigation");
 class TableOccurrence {
   constructor(config) {
     __publicField(this, "name");
     __publicField(this, "baseTable");
-    __publicField(this, "_navigationConfig");
     __publicField(this, "navigation");
     __publicField(this, "defaultSelect");
+    __publicField(this, "fmtId");
     this.name = config.name;
     this.baseTable = config.baseTable;
-    this._navigationConfig = config.navigation ?? {};
+    this.navigation = config[INTERNAL_NAV] ?? {};
     this.defaultSelect = config.defaultSelect ?? "schema";
-    this.navigation = createNavigationGetters(this._navigationConfig);
+    this.fmtId = config.fmtId;
+  }
+  /**
+   * Returns the FileMaker table occurrence ID (FMTID) if available, or the table name.
+   * @returns The FMTID string or the table name
+   */
+  getTableId() {
+    return this.fmtId ?? this.name;
+  }
+  /**
+   * Returns the table occurrence name.
+   * @returns The table name
+   */
+  getTableName() {
+    return this.name;
+  }
+  /**
+   * Returns true if this TableOccurrence is using FileMaker table occurrence IDs.
+   */
+  isUsingTableId() {
+    return this.fmtId !== void 0;
   }
-  addNavigation(nav) {
+  /**
+   * @internal Creates a new TableOccurrence with navigation - used by buildOccurrences
+   */
+  static _withNavigation(base, navigation) {
     return new TableOccurrence({
-      name: this.name,
-      baseTable: this.baseTable,
-      navigation: { ...this._navigationConfig, ...nav },
-      defaultSelect: this.defaultSelect
+      name: base.name,
+      baseTable: base.baseTable,
+      defaultSelect: base.defaultSelect,
+      fmtId: base.fmtId,
+      [INTERNAL_NAV]: navigation
     });
   }
 }
-function createTableOccurrence(config) {
+function defineTableOccurrence(config) {
   return new TableOccurrence(config);
 }
 export {
   TableOccurrence,
-  createTableOccurrence
+  defineTableOccurrence
 };
 //# sourceMappingURL=table-occurrence.js.map

package/dist/esm/client/table-occurrence.js.map

@@ -1 +1 @@
-{"version":3,"file":"table-occurrence.js","sources":["../../../src/client/table-occurrence.ts"],"sourcesContent":["import { BaseTable } from \"./base-table\";\n\n// Helper type to extract schema from BaseTable\ntype ExtractSchema<BT> =\n  BT extends BaseTable<infer S, any, any, any> ? S : never;\n\n// Helper type to resolve navigation functions to their return types\ntype ResolveNavigation<T> = {\n  [K in keyof T]: T[K] extends () => infer R ? R : T[K];\n};\n\n// Helper to create a getter-based navigation object\nfunction createNavigationGetters<\n  Nav extends Record<\n    string,\n    | TableOccurrence<any, any, any, any>\n    | (() => TableOccurrence<any, any, any, any>)\n  >,\n>(navConfig: Nav): ResolveNavigation<Nav> {\n  const result: any = {};\n\n  for (const key in navConfig) {\n    Object.defineProperty(result, key, {\n      get() {\n        const navItem = navConfig[key];\n        return typeof navItem === \"function\" ? navItem() : navItem;\n      },\n      enumerable: true,\n      configurable: true,\n    });\n  }\n\n  return result as ResolveNavigation<Nav>;\n}\n\nexport class TableOccurrence<\n  BT extends BaseTable<any, any, any, any> = any,\n  Name extends string = string,\n  Nav extends Record<\n    string,\n    | TableOccurrence<any, any, any, any>\n    | (() => TableOccurrence<any, any, any, any>)\n  > = {},\n  DefSelect extends\n    | \"all\"\n    | \"schema\"\n    | readonly (keyof ExtractSchema<BT>)[] = \"schema\",\n> {\n  public readonly name: Name;\n  public readonly baseTable: BT;\n  private _navigationConfig: Nav;\n  public readonly navigation: ResolveNavigation<Nav>;\n  public readonly defaultSelect: DefSelect;\n\n  constructor(config: {\n    readonly name: Name;\n    readonly baseTable: BT;\n    readonly navigation?: Nav;\n    readonly defaultSelect?: DefSelect;\n  }) {\n    this.name = config.name;\n    this.baseTable = config.baseTable;\n    this._navigationConfig = (config.navigation ?? {}) as Nav;\n    this.defaultSelect = (config.defaultSelect ?? \"schema\") as DefSelect;\n\n    // Create navigation getters that lazily resolve functions\n    this.navigation = createNavigationGetters(this._navigationConfig);\n  }\n\n  addNavigation<\n    NewNav extends Record<\n      string,\n      | TableOccurrence<any, any, any, any>\n      | (() => TableOccurrence<any, any, any, any>)\n    >,\n  >(nav: NewNav): TableOccurrence<BT, Name, Nav & NewNav, DefSelect> {\n    return new TableOccurrence({\n      name: this.name,\n      baseTable: this.baseTable,\n      navigation: { ...this._navigationConfig, ...nav } as Nav & NewNav,\n      defaultSelect: this.defaultSelect,\n    });\n  }\n}\n\n// Helper function to create TableOccurrence with proper type inference\nexport function createTableOccurrence<\n  const Name extends string,\n  BT extends BaseTable<any, any, any, any>,\n  DefSelect extends\n    | \"all\"\n    | \"schema\"\n    | readonly (keyof ExtractSchema<BT>)[] = \"schema\",\n>(config: {\n  name: Name;\n  baseTable: BT;\n  defaultSelect?: DefSelect;\n}): TableOccurrence<BT, Name, {}, DefSelect> {\n  return new TableOccurrence(config);\n}\n"],"names":[],"mappings":";;;AAYA,SAAS,wBAMP,WAAwC;AACxC,QAAM,SAAc,CAAC;AAErB,aAAW,OAAO,WAAW;AACpB,WAAA,eAAe,QAAQ,KAAK;AAAA,MACjC,MAAM;AACE,cAAA,UAAU,UAAU,GAAG;AAC7B,eAAO,OAAO,YAAY,aAAa,QAAY,IAAA;AAAA,MACrD;AAAA,MACA,YAAY;AAAA,MACZ,cAAc;AAAA,IAAA,CACf;AAAA,EAAA;AAGI,SAAA;AACT;AAEO,MAAM,gBAYX;AAAA,EAOA,YAAY,QAKT;AAXa;AACA;AACR;AACQ;AACA;AAQd,SAAK,OAAO,OAAO;AACnB,SAAK,YAAY,OAAO;AACnB,SAAA,oBAAqB,OAAO,cAAc,CAAC;AAC3C,SAAA,gBAAiB,OAAO,iBAAiB;AAGzC,SAAA,aAAa,wBAAwB,KAAK,iBAAiB;AAAA,EAAA;AAAA,EAGlE,cAME,KAAiE;AACjE,WAAO,IAAI,gBAAgB;AAAA,MACzB,MAAM,KAAK;AAAA,MACX,WAAW,KAAK;AAAA,MAChB,YAAY,EAAE,GAAG,KAAK,mBAAmB,GAAG,IAAI;AAAA,MAChD,eAAe,KAAK;AAAA,IAAA,CACrB;AAAA,EAAA;AAEL;AAGO,SAAS,sBAOd,QAI2C;AACpC,SAAA,IAAI,gBAAgB,MAAM;AACnC;"}
+{"version":3,"file":"table-occurrence.js","sources":["../../../src/client/table-occurrence.ts"],"sourcesContent":["import { BaseTable } from \"./base-table\";\n\n// Helper type to extract schema from BaseTable\ntype ExtractSchema<BT> =\n  BT extends BaseTable<infer S, any, any, any> ? S : never;\n\n// Symbol for internal navigation setting (used by buildOccurrences)\nconst INTERNAL_NAV = Symbol(\"internal-navigation\");\n\nexport class TableOccurrence<\n  BT extends BaseTable<any, any, any, any> = any,\n  Name extends string = string,\n  Nav extends Record<string, TableOccurrence<any, any, any, any>> = {},\n  DefSelect extends\n    | \"all\"\n    | \"schema\"\n    | readonly (keyof ExtractSchema<BT>)[] = \"schema\",\n> {\n  public readonly name: Name;\n  public readonly baseTable: BT;\n  public readonly navigation: Nav;\n  public readonly defaultSelect: DefSelect;\n  public readonly fmtId?: `FMTID:${string}`;\n\n  constructor(config: {\n    readonly name: Name;\n    readonly baseTable: BT;\n    readonly defaultSelect?: DefSelect;\n    readonly fmtId?: `FMTID:${string}`;\n    /** @internal Used by buildOccurrences - do not use directly */\n    readonly [INTERNAL_NAV]?: Nav;\n  }) {\n    this.name = config.name;\n    this.baseTable = config.baseTable;\n    this.navigation = (config[INTERNAL_NAV] ?? {}) as Nav;\n    this.defaultSelect = (config.defaultSelect ?? \"schema\") as DefSelect;\n    this.fmtId = config.fmtId;\n  }\n\n  /**\n   * Returns the FileMaker table occurrence ID (FMTID) if available, or the table name.\n   * @returns The FMTID string or the table name\n   */\n  getTableId(): string {\n    return this.fmtId ?? this.name;\n  }\n\n  /**\n   * Returns the table occurrence name.\n   * @returns The table name\n   */\n  getTableName(): string {\n    return this.name;\n  }\n\n  /**\n   * Returns true if this TableOccurrence is using FileMaker table occurrence IDs.\n   */\n  isUsingTableId(): boolean {\n    return this.fmtId !== undefined;\n  }\n\n  /**\n   * @internal Creates a new TableOccurrence with navigation - used by buildOccurrences\n   */\n  static _withNavigation<\n    BT extends BaseTable<any, any, any, any>,\n    Name extends string,\n    Nav extends Record<string, TableOccurrence<any, any, any, any>>,\n    DefSelect extends\n      | \"all\"\n      | \"schema\"\n      | readonly (keyof ExtractSchema<BT>)[] = \"schema\",\n  >(\n    base: TableOccurrence<BT, Name, any, DefSelect>,\n    navigation: Nav,\n  ): TableOccurrence<BT, Name, Nav, DefSelect> {\n    return new TableOccurrence({\n      name: base.name,\n      baseTable: base.baseTable,\n      defaultSelect: base.defaultSelect,\n      fmtId: base.fmtId,\n      [INTERNAL_NAV]: navigation,\n    }) as TableOccurrence<BT, Name, Nav, DefSelect>;\n  }\n}\n\n// Helper function to create TableOccurrence with proper type inference\nexport function createTableOccurrence<\n  const Name extends string,\n  BT extends BaseTable<any, any, any, any>,\n  DefSelect extends\n    | \"all\"\n    | \"schema\"\n    | readonly (keyof ExtractSchema<BT>)[] = \"schema\",\n>(config: {\n  name: Name;\n  baseTable: BT;\n  defaultSelect?: DefSelect;\n  fmtId?: `FMTID:${string}`;\n}): TableOccurrence<BT, Name, {}, DefSelect> {\n  return new TableOccurrence(config);\n}\n\n/**\n * Creates a TableOccurrence with proper TypeScript type inference.\n *\n * Use this function to create TableOccurrence instances with full type safety.\n * For navigation between tables, use `buildOccurrences()` after defining your TOs.\n *\n * @example\n * ```ts\n * const users = defineTableOccurrence({\n *   name: \"users\",\n *   baseTable: usersBase,\n * });\n * ```\n *\n * @example With entity IDs\n * ```ts\n * const products = defineTableOccurrence({\n *   name: \"products\",\n *   baseTable: productsBase,\n *   fmtId: \"FMTID:12345\",\n * });\n * ```\n *\n * @example With navigation (use buildOccurrences)\n * ```ts\n * const _users = defineTableOccurrence({ name: \"users\", baseTable: usersBase });\n * const _contacts = defineTableOccurrence({ name: \"contacts\", baseTable: contactsBase });\n *\n * const [users, contacts] = buildOccurrences({\n *   occurrences: [_users, _contacts],\n *   navigation: {\n *     users: [\"contacts\"],\n *     contacts: [\"users\"],\n *   },\n * });\n * ```\n */\nexport function defineTableOccurrence<\n  const Name extends string,\n  BT extends BaseTable<any, any, any, any>,\n  const DefSelect extends\n    | \"all\"\n    | \"schema\"\n    | readonly (keyof ExtractSchema<BT>)[] = \"schema\",\n>(config: {\n  readonly name: Name;\n  readonly baseTable: BT;\n  readonly fmtId?: `FMTID:${string}`;\n  readonly defaultSelect?: DefSelect;\n}): TableOccurrence<BT, Name, {}, DefSelect> {\n  return new TableOccurrence(config);\n}\n"],"names":[],"mappings":";;;AAOA,MAAM,eAAe,OAAO,qBAAqB;AAE1C,MAAM,gBAQX;AAAA,EAOA,YAAY,QAOT;AAba;AACA;AACA;AACA;AACA;AAUd,SAAK,OAAO,OAAO;AACnB,SAAK,YAAY,OAAO;AACxB,SAAK,aAAc,OAAO,YAAY,KAAK,CAAC;AACvC,SAAA,gBAAiB,OAAO,iBAAiB;AAC9C,SAAK,QAAQ,OAAO;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOtB,aAAqB;AACZ,WAAA,KAAK,SAAS,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAO5B,eAAuB;AACrB,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,iBAA0B;AACxB,WAAO,KAAK,UAAU;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMxB,OAAO,gBASL,MACA,YAC2C;AAC3C,WAAO,IAAI,gBAAgB;AAAA,MACzB,MAAM,KAAK;AAAA,MACX,WAAW,KAAK;AAAA,MAChB,eAAe,KAAK;AAAA,MACpB,OAAO,KAAK;AAAA,MACZ,CAAC,YAAY,GAAG;AAAA,IAAA,CACjB;AAAA,EAAA;AAEL;AAwDO,SAAS,sBAOd,QAK2C;AACpC,SAAA,IAAI,gBAAgB,MAAM;AACnC;"}

package/dist/esm/client/update-builder.d.ts

@@ -1,4 +1,4 @@
-import { ExecutionContext, ExecutableBuilder, Result, WithSystemFields } from '../types.js';
+import { ExecutionContext, ExecutableBuilder, Result, WithSystemFields, ExecuteOptions } from '../types.js';
 import { TableOccurrence } from './table-occurrence.js';
 import { BaseTable } from './base-table.js';
 import { QueryBuilder } from './query-builder.js';
@@ -7,39 +7,43 @@ import { FFetchOptions } from '@fetchkit/ffetch';
  * Initial update builder returned from EntitySet.update(data)
  * Requires calling .byId() or .where() before .execute() is available
  */
-export declare class UpdateBuilder<T extends Record<string, any>, BT extends BaseTable<any, any, any, any>> {
+export declare class UpdateBuilder<T extends Record<string, any>, BT extends BaseTable<any, any, any, any>, ReturnPreference extends "minimal" | "representation" = "minimal"> {
     private tableName;
     private databaseName;
     private context;
     private occurrence?;
     private data;
+    private returnPreference;
+    private databaseUseEntityIds;
     constructor(config: {
         occurrence?: TableOccurrence<any, any, any, any>;
         tableName: string;
         databaseName: string;
         context: ExecutionContext;
         data: Partial<T>;
+        returnPreference: ReturnPreference;
+        databaseUseEntityIds?: boolean;
     });
     /**
      * Update a single record by ID
-     * Returns the count of updated records (0 or 1)
+     * Returns updated count by default, or full record if returnFullRecord was set to true
      */
-    byId(id: string | number): ExecutableUpdateBuilder<T, true>;
+    byId(id: string | number): ExecutableUpdateBuilder<T, true, ReturnPreference>;
     /**
      * Update records matching a filter query
-     * Returns the count of updated records
+     * Returns updated count by default, or full record if returnFullRecord was set to true
      * @param fn Callback that receives a QueryBuilder for building the filter
      */
-    where(fn: (q: QueryBuilder<WithSystemFields<T>>) => QueryBuilder<WithSystemFields<T>>): ExecutableUpdateBuilder<T, true>;
+    where(fn: (q: QueryBuilder<WithSystemFields<T>>) => QueryBuilder<WithSystemFields<T>>): ExecutableUpdateBuilder<T, true, ReturnPreference>;
 }
 /**
  * Executable update builder - has execute() method
  * Returned after calling .byId() or .where()
- * Both modes return the count of updated records
+ * Can return either updated count or full record based on returnFullRecord option
  */
-export declare class ExecutableUpdateBuilder<T extends Record<string, any>, IsByFilter extends boolean> implements ExecutableBuilder<{
+export declare class ExecutableUpdateBuilder<T extends Record<string, any>, IsByFilter extends boolean, ReturnPreference extends "minimal" | "representation" = "minimal"> implements ExecutableBuilder<ReturnPreference extends "minimal" ? {
     updatedCount: number;
-}> {
+} : T> {
     private tableName;
     private databaseName;
     private context;
@@ -48,6 +52,8 @@ export declare class ExecutableUpdateBuilder<T extends Record<string, any>, IsBy
     private mode;
     private recordId?;
     private queryBuilder?;
+    private returnPreference;
+    private databaseUseEntityIds;
     constructor(config: {
         occurrence?: TableOccurrence<any, any, any, any>;
         tableName: string;
@@ -57,13 +63,30 @@ export declare class ExecutableUpdateBuilder<T extends Record<string, any>, IsBy
         mode: "byId" | "byFilter";
         recordId?: string | number;
         queryBuilder?: QueryBuilder<any>;
+        returnPreference: ReturnPreference;
+        databaseUseEntityIds?: boolean;
     });
-    execute(options?: RequestInit & FFetchOptions): Promise<Result<{
+    /**
+     * Helper to merge database-level useEntityIds with per-request options
+     */
+    private mergeExecuteOptions;
+    /**
+     * Gets the table ID (FMTID) if using entity IDs, otherwise returns the table name
+     * @param useEntityIds - Optional override for entity ID usage
+     */
+    private getTableId;
+    execute(options?: RequestInit & FFetchOptions & {
+        useEntityIds?: boolean;
+    }): Promise<Result<ReturnPreference extends "minimal" ? {
         updatedCount: number;
-    }>>;
+    } : T>>;
     getRequestConfig(): {
         method: string;
         url: string;
         body?: any;
     };
+    toRequest(baseUrl: string): Request;
+    processResponse(response: Response, options?: ExecuteOptions): Promise<Result<ReturnPreference extends "minimal" ? {
+        updatedCount: number;
+    } : T>>;
 }