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

package/dist/esm/logger.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/orm/column.d.ts

@@ -0,0 +1,62 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+/**
+ * Column represents a type-safe reference to a table field.
+ * Used in queries, filters, and operators to provide autocomplete and type checking.
+ *
+ * @template TOutput - The TypeScript type when reading from the database (output type)
+ * @template TInput - The TypeScript type when writing to the database (input type, for filters)
+ * @template TableName - The table name as a string literal type (for validation)
+ * @template IsContainer - Whether this column represents a container field (cannot be selected)
+ */
+export declare class Column<TOutput = any, TInput = TOutput, TableName extends string = string, IsContainer extends boolean = false> {
+    readonly fieldName: string;
+    readonly entityId?: `FMFID:${string}`;
+    readonly tableName: TableName;
+    readonly tableEntityId?: `FMTID:${string}`;
+    readonly inputValidator?: StandardSchemaV1<TInput, any>;
+    readonly _phantomOutput: TOutput;
+    readonly _phantomInput: TInput;
+    readonly _isContainer: IsContainer;
+    constructor(config: {
+        fieldName: string;
+        entityId?: `FMFID:${string}`;
+        tableName: TableName;
+        tableEntityId?: `FMTID:${string}`;
+        inputValidator?: StandardSchemaV1<TInput, any>;
+    });
+    /**
+     * Get the field identifier (entity ID if available, otherwise field name).
+     * Used when building OData queries.
+     */
+    getFieldIdentifier(useEntityIds?: boolean): string;
+    /**
+     * Get the table identifier (entity ID if available, otherwise table name).
+     * Used when building OData queries.
+     */
+    getTableIdentifier(useEntityIds?: boolean): string;
+    /**
+     * Check if this column is from a specific table.
+     * Useful for validation in cross-table operations.
+     */
+    isFromTable(tableName: string): boolean;
+    /**
+     * Create a string representation for debugging.
+     */
+    toString(): string;
+}
+/**
+ * Type guard to check if a value is a Column instance.
+ */
+export declare function isColumn(value: any): value is Column<any, any, any, any>;
+/**
+ * Create a Column with proper type inference from the inputValidator.
+ * This helper ensures TypeScript can infer TInput from the validator's input type.
+ * @internal
+ */
+export declare function createColumn<TOutput, TInput, TName extends string, IsContainer extends boolean = false>(config: {
+    fieldName: string;
+    entityId?: `FMFID:${string}`;
+    tableName: TName;
+    tableEntityId?: `FMTID:${string}`;
+    inputValidator?: StandardSchemaV1<TInput, any>;
+}): Column<TOutput, TInput, TName, IsContainer>;

package/dist/esm/orm/column.js

@@ -0,0 +1,63 @@
+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);
+class Column {
+  constructor(config) {
+    __publicField(this, "fieldName");
+    __publicField(this, "entityId");
+    __publicField(this, "tableName");
+    __publicField(this, "tableEntityId");
+    // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer
+    __publicField(this, "inputValidator");
+    // Phantom types for TypeScript inference - never actually hold values
+    __publicField(this, "_phantomOutput");
+    __publicField(this, "_phantomInput");
+    __publicField(this, "_isContainer");
+    this.fieldName = config.fieldName;
+    this.entityId = config.entityId;
+    this.tableName = config.tableName;
+    this.tableEntityId = config.tableEntityId;
+    this.inputValidator = config.inputValidator;
+  }
+  /**
+   * Get the field identifier (entity ID if available, otherwise field name).
+   * Used when building OData queries.
+   */
+  getFieldIdentifier(useEntityIds) {
+    if (useEntityIds && this.entityId) {
+      return this.entityId;
+    }
+    return this.fieldName;
+  }
+  /**
+   * Get the table identifier (entity ID if available, otherwise table name).
+   * Used when building OData queries.
+   */
+  getTableIdentifier(useEntityIds) {
+    if (useEntityIds && this.tableEntityId) {
+      return this.tableEntityId;
+    }
+    return this.tableName;
+  }
+  /**
+   * Check if this column is from a specific table.
+   * Useful for validation in cross-table operations.
+   */
+  isFromTable(tableName) {
+    return this.tableName === tableName;
+  }
+  /**
+   * Create a string representation for debugging.
+   */
+  toString() {
+    return `${this.tableName}.${this.fieldName}`;
+  }
+}
+function isColumn(value) {
+  return value instanceof Column;
+}
+export {
+  Column,
+  isColumn
+};
+//# sourceMappingURL=column.js.map

package/dist/esm/orm/column.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"column.js","sources":["../../../src/orm/column.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * Column represents a type-safe reference to a table field.\n * Used in queries, filters, and operators to provide autocomplete and type checking.\n *\n * @template TOutput - The TypeScript type when reading from the database (output type)\n * @template TInput - The TypeScript type when writing to the database (input type, for filters)\n * @template TableName - The table name as a string literal type (for validation)\n * @template IsContainer - Whether this column represents a container field (cannot be selected)\n */\nexport class Column<\n  // biome-ignore lint/suspicious/noExplicitAny: Default type parameter for flexibility\n  TOutput = any,\n  TInput = TOutput,\n  TableName extends string = string,\n  IsContainer extends boolean = false,\n> {\n  readonly fieldName: string;\n  readonly entityId?: `FMFID:${string}`;\n  readonly tableName: TableName;\n  readonly tableEntityId?: `FMTID:${string}`;\n  // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer\n  readonly inputValidator?: StandardSchemaV1<TInput, any>;\n\n  // Phantom types for TypeScript inference - never actually hold values\n  readonly _phantomOutput!: TOutput;\n  readonly _phantomInput!: TInput;\n  readonly _isContainer!: IsContainer;\n\n  constructor(config: {\n    fieldName: string;\n    entityId?: `FMFID:${string}`;\n    tableName: TableName;\n    tableEntityId?: `FMTID:${string}`;\n    // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer\n    inputValidator?: StandardSchemaV1<TInput, any>;\n  }) {\n    this.fieldName = config.fieldName;\n    this.entityId = config.entityId;\n    this.tableName = config.tableName;\n    this.tableEntityId = config.tableEntityId;\n    this.inputValidator = config.inputValidator;\n  }\n\n  /**\n   * Get the field identifier (entity ID if available, otherwise field name).\n   * Used when building OData queries.\n   */\n  getFieldIdentifier(useEntityIds?: boolean): string {\n    if (useEntityIds && this.entityId) {\n      return this.entityId;\n    }\n    return this.fieldName;\n  }\n\n  /**\n   * Get the table identifier (entity ID if available, otherwise table name).\n   * Used when building OData queries.\n   */\n  getTableIdentifier(useEntityIds?: boolean): string {\n    if (useEntityIds && this.tableEntityId) {\n      return this.tableEntityId;\n    }\n    return this.tableName;\n  }\n\n  /**\n   * Check if this column is from a specific table.\n   * Useful for validation in cross-table operations.\n   */\n  isFromTable(tableName: string): boolean {\n    return this.tableName === tableName;\n  }\n\n  /**\n   * Create a string representation for debugging.\n   */\n  toString(): string {\n    return `${this.tableName}.${this.fieldName}`;\n  }\n}\n\n/**\n * Type guard to check if a value is a Column instance.\n */\n// biome-ignore lint/suspicious/noExplicitAny: Type guard accepting any value type, generic constraint accepting any Column configuration\nexport function isColumn(value: any): value is Column<any, any, any, any> {\n  return value instanceof Column;\n}\n\n/**\n * Create a Column with proper type inference from the inputValidator.\n * This helper ensures TypeScript can infer TInput from the validator's input type.\n * @internal\n */\nexport function createColumn<TOutput, TInput, TName extends string, IsContainer extends boolean = false>(config: {\n  fieldName: string;\n  entityId?: `FMFID:${string}`;\n  tableName: TName;\n  tableEntityId?: `FMTID:${string}`;\n  // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer\n  inputValidator?: StandardSchemaV1<TInput, any>;\n}): Column<TOutput, TInput, TName, IsContainer> {\n  return new Column(config) as Column<TOutput, TInput, TName, IsContainer>;\n}\n"],"names":[],"mappings":";;;AAWO,MAAM,OAMX;AAAA,EAaA,YAAY,QAOT;AAnBM;AACA;AACA;AACA;AAEA;AAAA;AAGA;AAAA;AACA;AACA;AAUP,SAAK,YAAY,OAAO;AACxB,SAAK,WAAW,OAAO;AACvB,SAAK,YAAY,OAAO;AACxB,SAAK,gBAAgB,OAAO;AAC5B,SAAK,iBAAiB,OAAO;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAO/B,mBAAmB,cAAgC;AAC7C,QAAA,gBAAgB,KAAK,UAAU;AACjC,aAAO,KAAK;AAAA,IAAA;AAEd,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOd,mBAAmB,cAAgC;AAC7C,QAAA,gBAAgB,KAAK,eAAe;AACtC,aAAO,KAAK;AAAA,IAAA;AAEd,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOd,YAAY,WAA4B;AACtC,WAAO,KAAK,cAAc;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAM5B,WAAmB;AACjB,WAAO,GAAG,KAAK,SAAS,IAAI,KAAK,SAAS;AAAA,EAAA;AAE9C;AAMO,SAAS,SAAS,OAAiD;AACxE,SAAO,iBAAiB;AAC1B;"}

package/dist/esm/orm/field-builders.d.ts

@@ -0,0 +1,164 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+/**
+ * Branded type for container field's database type.
+ * This allows TypeScript to distinguish container fields from regular string fields
+ * at the type level, enabling compile-time exclusion from select operations.
+ */
+export type ContainerDbType = string & {
+    readonly __container: true;
+};
+/**
+ * FieldBuilder provides a fluent API for defining table fields with type-safe metadata.
+ * Supports chaining methods to configure primary keys, nullability, read-only status, entity IDs, and validators.
+ *
+ * @template TOutput - The output type after applying outputValidator (what you get when reading)
+ * @template TInput - The input type after applying inputValidator (what you pass when writing)
+ * @template TDbType - The database type (what FileMaker stores/expects)
+ * @template TReadOnly - Whether this field is read-only (for type-level exclusion from insert/update)
+ */
+export declare class FieldBuilder<TOutput = any, TInput = TOutput, TDbType = TOutput, TReadOnly extends boolean = false> {
+    private _primaryKey;
+    private _notNull;
+    private _readOnly;
+    private _entityId?;
+    private _outputValidator?;
+    private _inputValidator?;
+    private readonly _fieldType;
+    private _comment?;
+    constructor(fieldType: string);
+    /**
+     * Mark this field as the primary key for the table.
+     * Primary keys are automatically read-only and non-nullable.
+     */
+    primaryKey(): FieldBuilder<NonNullable<TOutput>, NonNullable<TInput>, NonNullable<TDbType>, true>;
+    /**
+     * Mark this field as non-nullable.
+     * Updates the type to exclude null/undefined.
+     */
+    notNull(): FieldBuilder<NonNullable<TOutput>, NonNullable<TInput>, NonNullable<TDbType>, TReadOnly>;
+    /**
+     * Mark this field as read-only.
+     * Read-only fields are excluded from insert and update operations.
+     */
+    readOnly(): FieldBuilder<TOutput, TInput, TDbType, true>;
+    /**
+     * Assign a FileMaker field ID (FMFID) to this field.
+     * When useEntityIds is enabled, this ID will be used in API requests instead of the field name.
+     */
+    entityId(id: `FMFID:${string}`): FieldBuilder<TOutput, TInput, TDbType, TReadOnly>;
+    /**
+     * Set a validator for the output (reading from database).
+     * The output validator transforms/validates data coming FROM the database in list or get operations.
+     *
+     * @example
+     * numberField().readValidator(z.coerce.boolean())
+     * // FileMaker returns 0/1, you get true/false
+     */
+    readValidator<O, VInput = TDbType>(validator: StandardSchemaV1<VInput, O>): FieldBuilder<O, TInput, TDbType, TReadOnly>;
+    /**
+     * Set a validator for the input (writing to database).
+     * The input validator transforms/validates data going TO the database in insert, update, and filter operations.
+     *
+     * @example
+     * numberField().writeValidator(z.boolean().transform(v => v ? 1 : 0))
+     * // You pass true/false, FileMaker gets 1/0
+     */
+    writeValidator<I>(validator: StandardSchemaV1<I, TDbType>): FieldBuilder<TOutput, I, TDbType, TReadOnly>;
+    /**
+     * Add a comment to this field for metadata purposes.
+     * This helps future developers understand the purpose of the field.
+     *
+     * @example
+     * textField().comment("Account name of the user who last modified each record")
+     */
+    comment(comment: string): FieldBuilder<TOutput, TInput, TDbType, TReadOnly>;
+    /**
+     * Get the metadata configuration for this field.
+     * @internal Used by fmTableOccurrence to extract field configuration
+     */
+    _getConfig(): {
+        fieldType: string;
+        primaryKey: boolean;
+        notNull: boolean;
+        readOnly: boolean;
+        entityId: `FMFID:${string}` | undefined;
+        outputValidator: StandardSchemaV1<any, TOutput> | undefined;
+        inputValidator: StandardSchemaV1<TInput, any> | undefined;
+        comment: string | undefined;
+    };
+    /**
+     * Clone this builder to allow immutable chaining.
+     * @private
+     */
+    private _clone;
+}
+/**
+ * Create a text field (Edm.String in FileMaker OData).
+ * By default, text fields are nullable.
+ *
+ * @example
+ * textField()                    // string | null
+ * textField().notNull()          // string
+ * textField().entityId("FMFID:1") // with entity ID
+ */
+export declare function textField(): FieldBuilder<string | null, string | null, string | null, false>;
+/**
+ * Create a number field (Edm.Decimal in FileMaker OData).
+ * By default, number fields are nullable.
+ *
+ * @example
+ * numberField()                   // number | null
+ * numberField().notNull()         // number
+ * numberField().outputValidator(z.coerce.boolean()) // transform to boolean on read
+ */
+export declare function numberField(): FieldBuilder<number | null, number | null, number | null, false>;
+/**
+ * Create a date field (Edm.Date in FileMaker OData).
+ * By default, date fields are nullable and represented as ISO date strings (YYYY-MM-DD).
+ *
+ * @example
+ * dateField()         // string | null (ISO date format)
+ * dateField().notNull() // string
+ */
+export declare function dateField(): FieldBuilder<string | null, string | null, string | null, false>;
+/**
+ * Create a time field (Edm.TimeOfDay in FileMaker OData).
+ * By default, time fields are nullable and represented as ISO time strings (HH:mm:ss).
+ *
+ * @example
+ * timeField()         // string | null (ISO time format)
+ * timeField().notNull() // string
+ */
+export declare function timeField(): FieldBuilder<string | null, string | null, string | null, false>;
+/**
+ * Create a timestamp field (Edm.DateTimeOffset in FileMaker OData).
+ * By default, timestamp fields are nullable and represented as ISO 8601 strings.
+ *
+ * @example
+ * timestampField()         // string | null (ISO 8601 format)
+ * timestampField().notNull() // string
+ * timestampField().readOnly() // typical for CreationTimestamp
+ */
+export declare function timestampField(): FieldBuilder<string | null, string | null, string | null, false>;
+/**
+ * Create a container field (Edm.Stream in FileMaker OData).
+ * Container fields store binary data and are represented as base64 strings in the API.
+ * By default, container fields are nullable.
+ *
+ * Note: Container fields cannot be selected via .select() - they can only be accessed
+ * via .getSingleField() due to FileMaker OData API limitations.
+ *
+ * @example
+ * containerField()         // string | null (base64 encoded)
+ * containerField().notNull() // string
+ */
+export declare function containerField(): FieldBuilder<string | null, string | null, ContainerDbType | null, false>;
+/**
+ * Create a calculated field (read-only field computed by FileMaker).
+ * Calculated fields are automatically marked as read-only.
+ *
+ * @example
+ * calcField()         // string | null
+ * calcField().notNull() // string
+ */
+export declare function calcField(): FieldBuilder<string | null, string | null, string | null, true>;

package/dist/esm/orm/field-builders.js

@@ -0,0 +1,158 @@
+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);
+class FieldBuilder {
+  constructor(fieldType) {
+    __publicField(this, "_primaryKey", false);
+    __publicField(this, "_notNull", false);
+    __publicField(this, "_readOnly", false);
+    __publicField(this, "_entityId");
+    // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer
+    __publicField(this, "_outputValidator");
+    // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer
+    __publicField(this, "_inputValidator");
+    __publicField(this, "_fieldType");
+    __publicField(this, "_comment");
+    this._fieldType = fieldType;
+  }
+  /**
+   * Mark this field as the primary key for the table.
+   * Primary keys are automatically read-only and non-nullable.
+   */
+  primaryKey() {
+    const builder = this._clone();
+    builder._primaryKey = true;
+    builder._notNull = true;
+    builder._readOnly = true;
+    return builder;
+  }
+  /**
+   * Mark this field as non-nullable.
+   * Updates the type to exclude null/undefined.
+   */
+  notNull() {
+    const builder = this._clone();
+    builder._notNull = true;
+    return builder;
+  }
+  /**
+   * Mark this field as read-only.
+   * Read-only fields are excluded from insert and update operations.
+   */
+  readOnly() {
+    const builder = this._clone();
+    builder._readOnly = true;
+    return builder;
+  }
+  /**
+   * Assign a FileMaker field ID (FMFID) to this field.
+   * When useEntityIds is enabled, this ID will be used in API requests instead of the field name.
+   */
+  entityId(id) {
+    const builder = this._clone();
+    builder._entityId = id;
+    return builder;
+  }
+  /**
+   * Set a validator for the output (reading from database).
+   * The output validator transforms/validates data coming FROM the database in list or get operations.
+   *
+   * @example
+   * numberField().readValidator(z.coerce.boolean())
+   * // FileMaker returns 0/1, you get true/false
+   */
+  readValidator(validator) {
+    const builder = this._clone();
+    builder._outputValidator = validator;
+    return builder;
+  }
+  /**
+   * Set a validator for the input (writing to database).
+   * The input validator transforms/validates data going TO the database in insert, update, and filter operations.
+   *
+   * @example
+   * numberField().writeValidator(z.boolean().transform(v => v ? 1 : 0))
+   * // You pass true/false, FileMaker gets 1/0
+   */
+  writeValidator(validator) {
+    const builder = this._clone();
+    builder._inputValidator = validator;
+    return builder;
+  }
+  /**
+   * Add a comment to this field for metadata purposes.
+   * This helps future developers understand the purpose of the field.
+   *
+   * @example
+   * textField().comment("Account name of the user who last modified each record")
+   */
+  comment(comment) {
+    const builder = this._clone();
+    builder._comment = comment;
+    return builder;
+  }
+  /**
+   * Get the metadata configuration for this field.
+   * @internal Used by fmTableOccurrence to extract field configuration
+   */
+  _getConfig() {
+    return {
+      fieldType: this._fieldType,
+      primaryKey: this._primaryKey,
+      notNull: this._notNull,
+      readOnly: this._readOnly,
+      entityId: this._entityId,
+      outputValidator: this._outputValidator,
+      inputValidator: this._inputValidator,
+      comment: this._comment
+    };
+  }
+  /**
+   * Clone this builder to allow immutable chaining.
+   * @private
+   */
+  _clone() {
+    const builder = new FieldBuilder(this._fieldType);
+    builder._primaryKey = this._primaryKey;
+    builder._notNull = this._notNull;
+    builder._readOnly = this._readOnly;
+    builder._entityId = this._entityId;
+    builder._outputValidator = this._outputValidator;
+    builder._inputValidator = this._inputValidator;
+    builder._comment = this._comment;
+    return builder;
+  }
+}
+function textField() {
+  return new FieldBuilder("text");
+}
+function numberField() {
+  return new FieldBuilder("number");
+}
+function dateField() {
+  return new FieldBuilder("date");
+}
+function timeField() {
+  return new FieldBuilder("time");
+}
+function timestampField() {
+  return new FieldBuilder("timestamp");
+}
+function containerField() {
+  return new FieldBuilder("container");
+}
+function calcField() {
+  const builder = new FieldBuilder("calculated");
+  return builder.readOnly();
+}
+export {
+  FieldBuilder,
+  calcField,
+  containerField,
+  dateField,
+  numberField,
+  textField,
+  timeField,
+  timestampField
+};
+//# sourceMappingURL=field-builders.js.map

package/dist/esm/orm/field-builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-builders.js","sources":["../../../src/orm/field-builders.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * Branded type for container field's database type.\n * This allows TypeScript to distinguish container fields from regular string fields\n * at the type level, enabling compile-time exclusion from select operations.\n */\nexport type ContainerDbType = string & { readonly __container: true };\n\n/**\n * FieldBuilder provides a fluent API for defining table fields with type-safe metadata.\n * Supports chaining methods to configure primary keys, nullability, read-only status, entity IDs, and validators.\n *\n * @template TOutput - The output type after applying outputValidator (what you get when reading)\n * @template TInput - The input type after applying inputValidator (what you pass when writing)\n * @template TDbType - The database type (what FileMaker stores/expects)\n * @template TReadOnly - Whether this field is read-only (for type-level exclusion from insert/update)\n */\n// biome-ignore lint/suspicious/noExplicitAny: Default type parameter for flexibility\nexport class FieldBuilder<TOutput = any, TInput = TOutput, TDbType = TOutput, TReadOnly extends boolean = false> {\n  private _primaryKey = false;\n  private _notNull = false;\n  private _readOnly = false;\n  private _entityId?: `FMFID:${string}`;\n  // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer\n  private _outputValidator?: StandardSchemaV1<any, TOutput>;\n  // biome-ignore lint/suspicious/noExplicitAny: Required for type inference with infer\n  private _inputValidator?: StandardSchemaV1<TInput, any>;\n  private readonly _fieldType: string;\n  private _comment?: string;\n\n  constructor(fieldType: string) {\n    this._fieldType = fieldType;\n  }\n\n  /**\n   * Mark this field as the primary key for the table.\n   * Primary keys are automatically read-only and non-nullable.\n   */\n  primaryKey(): FieldBuilder<NonNullable<TOutput>, NonNullable<TInput>, NonNullable<TDbType>, true> {\n    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for internal class mutation\n    const builder = this._clone() as any;\n    builder._primaryKey = true;\n    builder._notNull = true; // Primary keys are automatically non-nullable\n    builder._readOnly = true; // Primary keys are automatically read-only\n    return builder;\n  }\n\n  /**\n   * Mark this field as non-nullable.\n   * Updates the type to exclude null/undefined.\n   */\n  notNull(): FieldBuilder<NonNullable<TOutput>, NonNullable<TInput>, NonNullable<TDbType>, TReadOnly> {\n    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for internal class mutation\n    const builder = this._clone() as any;\n    builder._notNull = true;\n    return builder;\n  }\n\n  /**\n   * Mark this field as read-only.\n   * Read-only fields are excluded from insert and update operations.\n   */\n  readOnly(): FieldBuilder<TOutput, TInput, TDbType, true> {\n    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for internal class mutation\n    const builder = this._clone() as any;\n    builder._readOnly = true;\n    return builder;\n  }\n\n  /**\n   * Assign a FileMaker field ID (FMFID) to this field.\n   * When useEntityIds is enabled, this ID will be used in API requests instead of the field name.\n   */\n  entityId(id: `FMFID:${string}`): FieldBuilder<TOutput, TInput, TDbType, TReadOnly> {\n    const builder = this._clone();\n    builder._entityId = id;\n    return builder;\n  }\n\n  /**\n   * Set a validator for the output (reading from database).\n   * The output validator transforms/validates data coming FROM the database in list or get operations.\n   *\n   * @example\n   * numberField().readValidator(z.coerce.boolean())\n   * // FileMaker returns 0/1, you get true/false\n   */\n  readValidator<O, VInput = TDbType>(\n    validator: StandardSchemaV1<VInput, O>,\n  ): FieldBuilder<O, TInput, TDbType, TReadOnly> {\n    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for internal class mutation\n    const builder = this._clone() as any;\n    builder._outputValidator = validator;\n    return builder;\n  }\n\n  /**\n   * Set a validator for the input (writing to database).\n   * The input validator transforms/validates data going TO the database in insert, update, and filter operations.\n   *\n   * @example\n   * numberField().writeValidator(z.boolean().transform(v => v ? 1 : 0))\n   * // You pass true/false, FileMaker gets 1/0\n   */\n  writeValidator<I>(validator: StandardSchemaV1<I, TDbType>): FieldBuilder<TOutput, I, TDbType, TReadOnly> {\n    // biome-ignore lint/suspicious/noExplicitAny: Type assertion for internal class mutation\n    const builder = this._clone() as any;\n    builder._inputValidator = validator;\n    return builder;\n  }\n\n  /**\n   * Add a comment to this field for metadata purposes.\n   * This helps future developers understand the purpose of the field.\n   *\n   * @example\n   * textField().comment(\"Account name of the user who last modified each record\")\n   */\n  comment(comment: string): FieldBuilder<TOutput, TInput, TDbType, TReadOnly> {\n    const builder = this._clone();\n    builder._comment = comment;\n    return builder;\n  }\n\n  /**\n   * Get the metadata configuration for this field.\n   * @internal Used by fmTableOccurrence to extract field configuration\n   */\n  _getConfig() {\n    return {\n      fieldType: this._fieldType,\n      primaryKey: this._primaryKey,\n      notNull: this._notNull,\n      readOnly: this._readOnly,\n      entityId: this._entityId,\n      outputValidator: this._outputValidator,\n      inputValidator: this._inputValidator,\n      comment: this._comment,\n    };\n  }\n\n  /**\n   * Clone this builder to allow immutable chaining.\n   * @private\n   */\n  private _clone(): FieldBuilder<TOutput, TInput, TDbType, TReadOnly> {\n    const builder = new FieldBuilder<TOutput, TInput, TDbType, TReadOnly>(this._fieldType);\n    builder._primaryKey = this._primaryKey;\n    builder._notNull = this._notNull;\n    builder._readOnly = this._readOnly;\n    builder._entityId = this._entityId;\n    builder._outputValidator = this._outputValidator;\n    builder._inputValidator = this._inputValidator;\n    builder._comment = this._comment;\n    return builder;\n  }\n}\n\n/**\n * Create a text field (Edm.String in FileMaker OData).\n * By default, text fields are nullable.\n *\n * @example\n * textField()                    // string | null\n * textField().notNull()          // string\n * textField().entityId(\"FMFID:1\") // with entity ID\n */\nexport function textField(): FieldBuilder<string | null, string | null, string | null, false> {\n  return new FieldBuilder<string | null, string | null, string | null, false>(\"text\");\n}\n\n/**\n * Create a number field (Edm.Decimal in FileMaker OData).\n * By default, number fields are nullable.\n *\n * @example\n * numberField()                   // number | null\n * numberField().notNull()         // number\n * numberField().outputValidator(z.coerce.boolean()) // transform to boolean on read\n */\nexport function numberField(): FieldBuilder<number | null, number | null, number | null, false> {\n  return new FieldBuilder<number | null, number | null, number | null, false>(\"number\");\n}\n\n/**\n * Create a date field (Edm.Date in FileMaker OData).\n * By default, date fields are nullable and represented as ISO date strings (YYYY-MM-DD).\n *\n * @example\n * dateField()         // string | null (ISO date format)\n * dateField().notNull() // string\n */\nexport function dateField(): FieldBuilder<string | null, string | null, string | null, false> {\n  return new FieldBuilder<string | null, string | null, string | null, false>(\"date\");\n}\n\n/**\n * Create a time field (Edm.TimeOfDay in FileMaker OData).\n * By default, time fields are nullable and represented as ISO time strings (HH:mm:ss).\n *\n * @example\n * timeField()         // string | null (ISO time format)\n * timeField().notNull() // string\n */\nexport function timeField(): FieldBuilder<string | null, string | null, string | null, false> {\n  return new FieldBuilder<string | null, string | null, string | null, false>(\"time\");\n}\n\n/**\n * Create a timestamp field (Edm.DateTimeOffset in FileMaker OData).\n * By default, timestamp fields are nullable and represented as ISO 8601 strings.\n *\n * @example\n * timestampField()         // string | null (ISO 8601 format)\n * timestampField().notNull() // string\n * timestampField().readOnly() // typical for CreationTimestamp\n */\nexport function timestampField(): FieldBuilder<string | null, string | null, string | null, false> {\n  return new FieldBuilder<string | null, string | null, string | null, false>(\"timestamp\");\n}\n\n/**\n * Create a container field (Edm.Stream in FileMaker OData).\n * Container fields store binary data and are represented as base64 strings in the API.\n * By default, container fields are nullable.\n *\n * Note: Container fields cannot be selected via .select() - they can only be accessed\n * via .getSingleField() due to FileMaker OData API limitations.\n *\n * @example\n * containerField()         // string | null (base64 encoded)\n * containerField().notNull() // string\n */\nexport function containerField(): FieldBuilder<string | null, string | null, ContainerDbType | null, false> {\n  return new FieldBuilder<string | null, string | null, ContainerDbType | null, false>(\"container\");\n}\n\n/**\n * Create a calculated field (read-only field computed by FileMaker).\n * Calculated fields are automatically marked as read-only.\n *\n * @example\n * calcField()         // string | null\n * calcField().notNull() // string\n */\nexport function calcField(): FieldBuilder<string | null, string | null, string | null, true> {\n  const builder = new FieldBuilder<string | null, string | null, string | null, false>(\"calculated\");\n  return builder.readOnly();\n}\n"],"names":[],"mappings":";;;AAmBO,MAAM,aAAoG;AAAA,EAY/G,YAAY,WAAmB;AAXvB,uCAAc;AACd,oCAAW;AACX,qCAAY;AACZ;AAEA;AAAA;AAEA;AAAA;AACS;AACT;AAGN,SAAK,aAAa;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOpB,aAAkG;AAE1F,UAAA,UAAU,KAAK,OAAO;AAC5B,YAAQ,cAAc;AACtB,YAAQ,WAAW;AACnB,YAAQ,YAAY;AACb,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOT,UAAoG;AAE5F,UAAA,UAAU,KAAK,OAAO;AAC5B,YAAQ,WAAW;AACZ,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOT,WAAyD;AAEjD,UAAA,UAAU,KAAK,OAAO;AAC5B,YAAQ,YAAY;AACb,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOT,SAAS,IAA0E;AAC3E,UAAA,UAAU,KAAK,OAAO;AAC5B,YAAQ,YAAY;AACb,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWT,cACE,WAC6C;AAEvC,UAAA,UAAU,KAAK,OAAO;AAC5B,YAAQ,mBAAmB;AACpB,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWT,eAAkB,WAAuF;AAEjG,UAAA,UAAU,KAAK,OAAO;AAC5B,YAAQ,kBAAkB;AACnB,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUT,QAAQ,SAAoE;AACpE,UAAA,UAAU,KAAK,OAAO;AAC5B,YAAQ,WAAW;AACZ,WAAA;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOT,aAAa;AACJ,WAAA;AAAA,MACL,WAAW,KAAK;AAAA,MAChB,YAAY,KAAK;AAAA,MACjB,SAAS,KAAK;AAAA,MACd,UAAU,KAAK;AAAA,MACf,UAAU,KAAK;AAAA,MACf,iBAAiB,KAAK;AAAA,MACtB,gBAAgB,KAAK;AAAA,MACrB,SAAS,KAAK;AAAA,IAChB;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOM,SAA4D;AAClE,UAAM,UAAU,IAAI,aAAkD,KAAK,UAAU;AACrF,YAAQ,cAAc,KAAK;AAC3B,YAAQ,WAAW,KAAK;AACxB,YAAQ,YAAY,KAAK;AACzB,YAAQ,YAAY,KAAK;AACzB,YAAQ,mBAAmB,KAAK;AAChC,YAAQ,kBAAkB,KAAK;AAC/B,YAAQ,WAAW,KAAK;AACjB,WAAA;AAAA,EAAA;AAEX;AAWO,SAAS,YAA8E;AACrF,SAAA,IAAI,aAAiE,MAAM;AACpF;AAWO,SAAS,cAAgF;AACvF,SAAA,IAAI,aAAiE,QAAQ;AACtF;AAUO,SAAS,YAA8E;AACrF,SAAA,IAAI,aAAiE,MAAM;AACpF;AAUO,SAAS,YAA8E;AACrF,SAAA,IAAI,aAAiE,MAAM;AACpF;AAWO,SAAS,iBAAmF;AAC1F,SAAA,IAAI,aAAiE,WAAW;AACzF;AAcO,SAAS,iBAA4F;AACnG,SAAA,IAAI,aAA0E,WAAW;AAClG;AAUO,SAAS,YAA6E;AACrF,QAAA,UAAU,IAAI,aAAiE,YAAY;AACjG,SAAO,QAAQ,SAAS;AAC1B;"}

package/dist/esm/orm/index.d.ts

@@ -0,0 +1,5 @@
+/** biome-ignore-all lint/performance/noBarrelFile: Re-exporting all ORM utilities */
+export { Column, isColumn } from './column.js';
+export { type ContainerDbType, calcField, containerField, dateField, FieldBuilder, numberField, textField, timeField, timestampField, } from './field-builders.js';
+export { and, asc, contains, desc, endsWith, eq, FilterExpression, gt, gte, inArray, isNotNull, isNull, isOrderByExpression, lt, lte, ne, not, notInArray, OrderByExpression, or, startsWith, } from './operators.js';
+export { FMTable, type FMTableWithColumns, fmTableOccurrence, getBaseTableConfig, getDefaultSelect, getFieldId, getFieldName, getTableColumns, getTableEntityId, getTableId, getTableName, type InferTableSchema, isUsingEntityIds, } from './table.js';

package/dist/esm/orm/operators.d.ts

@@ -0,0 +1,173 @@
+import { Column } from './column.js';
+/**
+ * FilterExpression represents a filter condition that can be used in where() clauses.
+ * Internal representation of operator expressions that get converted to OData filter syntax.
+ */
+export declare class FilterExpression {
+    readonly operator: string;
+    readonly operands: (Column | any | FilterExpression)[];
+    constructor(operator: string, operands: (Column | any | FilterExpression)[]);
+    /**
+     * Convert this expression to OData filter syntax.
+     * @internal Used by QueryBuilder
+     */
+    toODataFilter(useEntityIds?: boolean): string;
+    private _binaryOp;
+    private _functionOp;
+    private _inOp;
+    private _notInOp;
+    private _isNullOp;
+    private _isNotNullOp;
+    private _logicalOp;
+    private _notOp;
+    private _operandToString;
+}
+/**
+ * Equal operator - checks if column equals a value or another column.
+ *
+ * @example
+ * eq(users.name, "John")           // name equals "John"
+ * eq(users.id, contacts.id_user)   // cross-table comparison
+ */
+export declare function eq<TOutput, TInput>(column1: Column<TOutput, TInput>, column2: Column<TOutput, TInput> | NoInfer<TInput>): FilterExpression;
+/**
+ * Not equal operator - checks if column does not equal a value or another column.
+ *
+ * @example
+ * ne(users.status, "inactive")     // status not equal to "inactive"
+ * ne(users.id, contacts.id_user)   // cross-table comparison
+ */
+export declare function ne<TOutput, TInput>(column1: Column<TOutput, TInput>, column2: Column<TOutput, TInput> | NoInfer<TInput>): FilterExpression;
+/**
+ * Greater than operator - checks if column is greater than a value.
+ *
+ * @example
+ * gt(users.age, 18)               // age greater than 18
+ */
+export declare function gt<TOutput extends number | string | Date | null, TInput>(column: Column<TOutput, TInput>, value: NoInfer<TInput>): FilterExpression;
+/**
+ * Greater than or equal operator - checks if column is >= a value.
+ *
+ * @example
+ * gte(users.age, 18)              // age >= 18
+ */
+export declare function gte<TOutput extends number | string | Date | null, TInput>(column: Column<TOutput, TInput>, value: NoInfer<TInput>): FilterExpression;
+/**
+ * Less than operator - checks if column is less than a value.
+ *
+ * @example
+ * lt(users.age, 65)               // age less than 65
+ */
+export declare function lt<TOutput extends number | string | Date | null, TInput>(column: Column<TOutput, TInput>, value: NoInfer<TInput>): FilterExpression;
+/**
+ * Less than or equal operator - checks if column is <= a value.
+ *
+ * @example
+ * lte(users.age, 65)              // age <= 65
+ */
+export declare function lte<TOutput extends number | string | Date | null, TInput>(column: Column<TOutput, TInput>, value: NoInfer<TInput>): FilterExpression;
+/**
+ * Contains operator - checks if a string column contains a substring.
+ *
+ * @example
+ * contains(users.name, "John")    // name contains "John"
+ */
+export declare function contains<TOutput, TInput>(column: Column<TOutput, TInput>, value: NoInfer<TInput>): FilterExpression;
+/**
+ * Starts with operator - checks if a string column starts with a prefix.
+ *
+ * @example
+ * startsWith(users.email, "admin") // email starts with "admin"
+ */
+export declare function startsWith<TOutput, TInput>(column: Column<TOutput, TInput>, value: NoInfer<TInput>): FilterExpression;
+/**
+ * Ends with operator - checks if a string column ends with a suffix.
+ *
+ * @example
+ * endsWith(users.email, "@example.com") // email ends with "@example.com"
+ */
+export declare function endsWith<TOutput, TInput>(column: Column<TOutput, TInput>, value: NoInfer<TInput>): FilterExpression;
+/**
+ * In array operator - checks if column value is in an array of values.
+ *
+ * @example
+ * inArray(users.status, ["active", "pending"]) // status is "active" or "pending"
+ */
+export declare function inArray<TOutput, TInput>(column: Column<TOutput, TInput>, values: NoInfer<TInput>[]): FilterExpression;
+/**
+ * Not in array operator - checks if column value is not in an array of values.
+ *
+ * @example
+ * notInArray(users.status, ["deleted", "banned"]) // status is neither "deleted" nor "banned"
+ */
+export declare function notInArray<TOutput, TInput>(column: Column<TOutput, TInput>, values: NoInfer<TInput>[]): FilterExpression;
+/**
+ * Is null operator - checks if column value is null.
+ *
+ * @example
+ * isNull(users.deletedAt)         // deletedAt is null
+ */
+export declare function isNull<TOutput, TInput>(column: Column<TOutput, TInput>): FilterExpression;
+/**
+ * Is not null operator - checks if column value is not null.
+ *
+ * @example
+ * isNotNull(users.email)          // email is not null
+ */
+export declare function isNotNull<TOutput, TInput>(column: Column<TOutput, TInput>): FilterExpression;
+/**
+ * AND operator - combines multiple filter expressions with logical AND.
+ * All expressions must be true for the record to match.
+ *
+ * @example
+ * and(
+ *   eq(users.active, true),
+ *   gt(users.age, 18)
+ * ) // active is true AND age > 18
+ */
+export declare function and(...expressions: FilterExpression[]): FilterExpression;
+/**
+ * OR operator - combines multiple filter expressions with logical OR.
+ * At least one expression must be true for the record to match.
+ *
+ * @example
+ * or(
+ *   eq(users.role, "admin"),
+ *   eq(users.role, "moderator")
+ * ) // role is "admin" OR "moderator"
+ */
+export declare function or(...expressions: FilterExpression[]): FilterExpression;
+/**
+ * NOT operator - negates a filter expression.
+ *
+ * @example
+ * not(eq(users.status, "deleted")) // status is NOT "deleted"
+ */
+export declare function not(expression: FilterExpression): FilterExpression;
+/**
+ * OrderByExpression represents a sort order specification for a column.
+ * Used in orderBy() clauses to provide type-safe sorting with direction.
+ */
+export declare class OrderByExpression<TableName extends string = string> {
+    readonly column: Column<any, any, TableName>;
+    readonly direction: "asc" | "desc";
+    constructor(column: Column<any, any, TableName>, direction: "asc" | "desc");
+}
+/**
+ * Type guard to check if a value is an OrderByExpression instance.
+ */
+export declare function isOrderByExpression(value: any): value is OrderByExpression;
+/**
+ * Ascending order operator - sorts a column in ascending order.
+ *
+ * @example
+ * asc(users.name)  // Sort by name ascending
+ */
+export declare function asc<TableName extends string>(column: Column<any, any, TableName>): OrderByExpression<TableName>;
+/**
+ * Descending order operator - sorts a column in descending order.
+ *
+ * @example
+ * desc(users.age)  // Sort by age descending
+ */
+export declare function desc<TableName extends string>(column: Column<any, any, TableName>): OrderByExpression<TableName>;