@objectql/types 3.0.0 → 4.0.0

package/dist/action.d.ts

@@ -1,5 +1,23 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { Action } from '@objectstack/spec';
 import { FieldConfig } from "./field";
 import { HookAPI } from "./hook";
+/**
+ * Re-export Protocol Types from the Constitution
+ *
+ * @deprecated Import directly from @objectstack/spec instead
+ */
+export type { Action as SpecAction };
+/**
+ * RUNTIME-SPECIFIC TYPES
+ * The following types extend the Protocol Action definition with runtime execution capabilities
+ */
 /**
  * Defines the scope of the action.
  * - `record`: Acts on a specific record instance (e.g. "Approve Order").
@@ -13,6 +31,8 @@ export type ActionType = 'record' | 'global';
 export type ActionInputDefinition = Record<string, FieldConfig>;
 /**
  * Context passed to the action handler execution.
+ *
+ * RUNTIME TYPE: Used during action execution.
  */
 export interface ActionContext<BaseT = any, InputT = any> {
     /** The object this action belongs to. */
@@ -41,11 +61,17 @@ export interface ActionContext<BaseT = any, InputT = any> {
     };
 }
 /**
+ * Runtime Action Configuration
+ *
  * The configuration of an Action visible to the Metadata engine (YAML/JSON side).
+ * Compatible with Protocol Action but adds runtime-specific options.
  */
 export interface ActionConfig {
+    /** Display label */
     label?: string;
+    /** Description */
     description?: string;
+    /** Icon name */
     icon?: string;
     /**
      * Default: 'global' if no fields defined, but usually specified explicitly.
@@ -70,6 +96,8 @@ export interface ActionConfig {
 }
 /**
  * The full implementation definition (Code side).
+ *
+ * RUNTIME TYPE: Includes the handler function for execution.
  */
 export interface ActionDefinition<BaseT = any, InputT = any, ReturnT = any> extends ActionConfig {
     /**

package/dist/action.js

@@ -1,3 +1,10 @@
 "use strict";
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=action.js.map

package/dist/action.js.map

@@ -1 +1 @@
-{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":""}
+{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/api.d.ts

@@ -1,10 +1,17 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 /**
  * API Type Definitions for ObjectQL
  *
  * This file contains TypeScript interfaces for Data API and Metadata API endpoints.
  * These types enable frontend applications to make type-safe API calls.
  */
-import { UnifiedQuery, FilterExpression } from './query';
+import { UnifiedQuery, Filter } from './query';
 import { ObjectConfig } from './object';
 import { FieldConfig } from './field';
 import { ActionConfig } from './action';
@@ -104,8 +111,8 @@ export interface DataApiItemResponse<T = unknown> extends DataApiResponse<T> {
  * Query parameters for GET /api/data/:object (list records)
  */
 export interface DataApiListParams {
-    /** Filter expression (can be FilterExpression array or JSON string) */
-    filter?: FilterExpression | string;
+    /** Filter expression (can be Filter object or JSON string) */
+    filter?: Filter | string;
     /** Fields to return (array or comma-separated string) */
     fields?: string[] | string;
     /** Sort criteria - array of [field, direction] tuples */
@@ -142,7 +149,7 @@ export interface DataApiUpdateRequest {
  */
 export interface DataApiBulkUpdateRequest {
     /** Filter criteria to select records to update */
-    filters: FilterExpression;
+    filters: Filter;
     /** Data to update */
     data: Record<string, unknown>;
 }
@@ -151,7 +158,7 @@ export interface DataApiBulkUpdateRequest {
  */
 export interface DataApiBulkDeleteRequest {
     /** Filter criteria to select records to delete */
-    filters: FilterExpression;
+    filters: Filter;
 }
 /**
  * Response for count operations
@@ -391,7 +398,7 @@ export interface IDataApiClient {
      * @param objectName - Name of the object
      * @param filters - Filter criteria
      */
-    count(objectName: string, filters?: FilterExpression): Promise<DataApiCountResponse>;
+    count(objectName: string, filters?: Filter): Promise<DataApiCountResponse>;
 }
 /**
  * Interface for Metadata API client operations

package/dist/api.js

@@ -1,9 +1,10 @@
 "use strict";
 /**
- * API Type Definitions for ObjectQL
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
  *
- * This file contains TypeScript interfaces for Data API and Metadata API endpoints.
- * These types enable frontend applications to make type-safe API calls.
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_API_ROUTES = exports.ObjectQLError = exports.ApiErrorCode = void 0;

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAgjBH,4CASC;AAljBD,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;GAEG;AACH,IAAY,YAUX;AAVD,WAAY,YAAY;IACpB,mDAAmC,CAAA;IACnC,qDAAqC,CAAA;IACrC,6CAA6B,CAAA;IAC7B,uCAAuB,CAAA;IACvB,uCAAuB,CAAA;IACvB,qCAAqB,CAAA;IACrB,iDAAiC,CAAA;IACjC,iDAAiC,CAAA;IACjC,2DAA2C,CAAA;AAC/C,CAAC,EAVW,YAAY,4BAAZ,YAAY,QAUvB;AAwBD;;GAEG;AACH,MAAa,aAAc,SAAQ,KAAK;IAIpC,YAAY,KAAkF;QAC1F,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAE7B,uDAAuD;QACvD,MAAM,gBAAgB,GAAG,KAA2F,CAAC;QACrH,IAAI,OAAO,gBAAgB,CAAC,iBAAiB,KAAK,UAAU,EAAE,CAAC;YAC3D,gBAAgB,CAAC,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;CACJ;AAhBD,sCAgBC;AA+dD;;GAEG;AACU,QAAA,kBAAkB,GAA2B;IACtD,GAAG,EAAE,eAAe;IACpB,IAAI,EAAE,WAAW;IACjB,QAAQ,EAAE,eAAe;IACzB,KAAK,EAAE,YAAY;CACtB,CAAC;AAEF;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,MAAuB;;IACpD,MAAM,aAAa,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IAEzF,OAAO;QACH,GAAG,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,GAAG,mCAAI,0BAAkB,CAAC,GAAG,CAAC;QACzD,IAAI,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,mCAAI,0BAAkB,CAAC,IAAI,CAAC;QAC5D,QAAQ,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,QAAQ,mCAAI,0BAAkB,CAAC,QAAQ,CAAC;QACxE,KAAK,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,mCAAI,0BAAkB,CAAC,KAAK,CAAC;KAClE,CAAC;AACN,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAujBH,4CASC;AAljBD,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;GAEG;AACH,IAAY,YAUX;AAVD,WAAY,YAAY;IACpB,mDAAmC,CAAA;IACnC,qDAAqC,CAAA;IACrC,6CAA6B,CAAA;IAC7B,uCAAuB,CAAA;IACvB,uCAAuB,CAAA;IACvB,qCAAqB,CAAA;IACrB,iDAAiC,CAAA;IACjC,iDAAiC,CAAA;IACjC,2DAA2C,CAAA;AAC/C,CAAC,EAVW,YAAY,4BAAZ,YAAY,QAUvB;AAwBD;;GAEG;AACH,MAAa,aAAc,SAAQ,KAAK;IAIpC,YAAY,KAAkF;QAC1F,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAE7B,uDAAuD;QACvD,MAAM,gBAAgB,GAAG,KAA2F,CAAC;QACrH,IAAI,OAAO,gBAAgB,CAAC,iBAAiB,KAAK,UAAU,EAAE,CAAC;YAC3D,gBAAgB,CAAC,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;CACJ;AAhBD,sCAgBC;AA+dD;;GAEG;AACU,QAAA,kBAAkB,GAA2B;IACtD,GAAG,EAAE,eAAe;IACpB,IAAI,EAAE,WAAW;IACjB,QAAQ,EAAE,eAAe;IACzB,KAAK,EAAE,YAAY;CACtB,CAAC;AAEF;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,MAAuB;;IACpD,MAAM,aAAa,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IAEzF,OAAO;QACH,GAAG,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,GAAG,mCAAI,0BAAkB,CAAC,GAAG,CAAC;QACzD,IAAI,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,mCAAI,0BAAkB,CAAC,IAAI,CAAC;QAC5D,QAAQ,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,QAAQ,mCAAI,0BAAkB,CAAC,QAAQ,CAAC;QACxE,KAAK,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,mCAAI,0BAAkB,CAAC,KAAK,CAAC;KAClE,CAAC;AACN,CAAC"}

package/dist/app.d.ts

@@ -1,3 +1,10 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 import { ObjectConfig } from "./object";
 import { Driver } from "./driver";
 import { MetadataRegistry } from "./registry";
@@ -16,4 +23,9 @@ export interface IObjectQL {
     triggerHook(event: HookName, objectName: string, ctx: HookContext): Promise<void>;
     registerAction(objectName: string, actionName: string, handler: ActionHandler): void;
     executeAction(objectName: string, actionName: string, ctx: ActionContext): Promise<any>;
+    /**
+     * Get the underlying ObjectStackKernel instance
+     * @returns The ObjectStackKernel instance
+     */
+    getKernel(): any;
 }

package/dist/app.js

@@ -1,3 +1,10 @@
 "use strict";
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":""}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/application.d.ts

@@ -1,3 +1,10 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 export interface AppConfig {
     /**
      * Unique identifier for the application

package/dist/application.js

@@ -1,3 +1,10 @@
 "use strict";
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=application.js.map

package/dist/application.js.map

@@ -1 +1 @@
-{"version":3,"file":"application.js","sourceRoot":"","sources":["../src/application.ts"],"names":[],"mappings":""}
+{"version":3,"file":"application.js","sourceRoot":"","sources":["../src/application.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/config.d.ts

@@ -1,7 +1,14 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 import { MetadataRegistry } from "./registry";
 import { Driver } from "./driver";
 import { ObjectConfig } from "./object";
-import { ObjectQLPlugin } from "./plugin";
+import type { RuntimePlugin } from "@objectstack/runtime";
 export interface ObjectQLConfig {
     registry?: MetadataRegistry;
     datasources?: Record<string, Driver>;
@@ -30,9 +37,10 @@ export interface ObjectQLConfig {
     modules?: string[];
     /**
      * List of plugins to load.
-     * Can be an instance of ObjectQLPlugin or a package name string.
+     * Must implement the RuntimePlugin interface from @objectstack/runtime.
+     * String plugins (package names) are not supported in core.
      */
-    plugins?: (ObjectQLPlugin | string)[];
+    plugins?: (RuntimePlugin | string)[];
     /**
      * List of remote ObjectQL instances to connect to.
      * e.g. ["http://user-service:3000", "http://order-service:3000"]

package/dist/config.js

@@ -1,3 +1,10 @@
 "use strict";
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":""}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/context.d.ts

@@ -1,3 +1,10 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 import { IObjectRepository } from './repository';
 export interface ObjectQLContext {
     userId?: string;

package/dist/context.js

@@ -1,3 +1,10 @@
 "use strict";
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":""}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/driver.d.ts

@@ -1,3 +1,10 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 /**
  * Column metadata from database introspection.
  */
@@ -51,12 +58,36 @@ export interface IntrospectedSchema {
     tables: Record<string, IntrospectedTable>;
 }
 export interface Driver {
+    name?: string;
+    version?: string;
+    supports?: {
+        transactions?: boolean;
+        joins?: boolean;
+        fullTextSearch?: boolean;
+        jsonFields?: boolean;
+        arrayFields?: boolean;
+    };
     find(objectName: string, query: any, options?: any): Promise<any[]>;
     findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any>;
     create(objectName: string, data: any, options?: any): Promise<any>;
     update(objectName: string, id: string | number, data: any, options?: any): Promise<any>;
     delete(objectName: string, id: string | number, options?: any): Promise<any>;
     count(objectName: string, filters: any, options?: any): Promise<number>;
+    connect?(): Promise<void>;
+    disconnect?(): Promise<void>;
+    checkHealth?(): Promise<boolean>;
+    execute?(command: any, parameters?: any[], options?: any): Promise<any>;
+    bulkCreate?(objectName: string, data: any[], options?: any): Promise<any>;
+    bulkUpdate?(objectName: string, updates: Array<{
+        id: string | number;
+        data: any;
+    }>, options?: any): Promise<any>;
+    bulkDelete?(objectName: string, ids: Array<string | number>, options?: any): Promise<any>;
+    distinct?(objectName: string, field: string, filters?: any, options?: any): Promise<any[]>;
+    aggregate?(objectName: string, aggregations: any[], filters?: any, options?: any): Promise<any[]>;
+    beginTransaction?(): Promise<any>;
+    commitTransaction?(transaction: any): Promise<void>;
+    rollbackTransaction?(transaction: any): Promise<void>;
     init?(objects: any[]): Promise<void>;
     /**
      * Introspect the database schema to discover existing tables, columns, and relationships.
@@ -74,4 +105,34 @@ export interface Driver {
     commitTransaction?(trx: any): Promise<void>;
     rollbackTransaction?(trx: any): Promise<void>;
     disconnect?(): Promise<void>;
+    /**
+     * Execute a query using QueryAST format (DriverInterface v4.0)
+     * @param ast - The QueryAST to execute
+     * @param options - Driver-specific options
+     * @returns Query result with value and optional count
+     */
+    executeQuery?(ast: any, options?: any): Promise<{
+        value: any[];
+        count?: number;
+    }>;
+    /**
+     * Execute a command using Command format (DriverInterface v4.0)
+     * @param command - The command to execute (create/update/delete/bulk operations)
+     * @param options - Driver-specific options
+     * @returns Command result with success status and affected count
+     */
+    executeCommand?(command: any, options?: any): Promise<{
+        success: boolean;
+        data?: any;
+        affected: number;
+    }>;
+    /**
+     * Alternative method names for findOne (some drivers use 'get')
+     */
+    get?(objectName: string, id: string, options?: any): Promise<any>;
+    /**
+     * Direct query execution (legacy, some drivers)
+     */
+    directQuery?(sql: string, params?: any[]): Promise<any[]>;
+    query?(sql: string, params?: any[]): Promise<any[]>;
 }

package/dist/driver.js

@@ -1,3 +1,10 @@
 "use strict";
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=driver.js.map

package/dist/driver.js.map

@@ -1 +1 @@
-{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":""}
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/field.d.ts

@@ -1,7 +1,28 @@
-import { FieldValidation, ValidationAiContext } from './validation';
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { FieldType as ProtocolFieldType, Field, SelectOption as SpecSelectOption } from '@objectstack/spec';
+/**
+ * Re-export Protocol Types from the Constitution
+ * These are the wire-protocol standard types defined in @objectstack/spec
+ *
+ * @deprecated Import directly from @objectstack/spec instead
+ */
+export type { Field as SpecField, SpecSelectOption, ProtocolFieldType };
+/**
+ * RUNTIME-SPECIFIC TYPES
+ * The following types extend or complement the Protocol Constitution
+ * with runtime-specific properties that don't belong in the wire protocol.
+ */
 /**
  * Attachment field data structure for file and image types.
  * Stores metadata about uploaded files, with actual file content stored separately.
+ *
+ * This is a RUNTIME type - not part of the wire protocol.
  */
 export interface AttachmentData {
     /** Unique identifier for this file */
@@ -24,6 +45,8 @@ export interface AttachmentData {
 /**
  * Image-specific attachment data with additional metadata.
  * Extends AttachmentData with image-specific properties.
+ *
+ * This is a RUNTIME type - not part of the wire protocol.
  */
 export interface ImageAttachmentData extends AttachmentData {
     /** Image width in pixels */
@@ -40,69 +63,109 @@ export interface ImageAttachmentData extends AttachmentData {
     };
 }
 /**
- * Represents the supported field data types in the ObjectQL schema.
- * These types determine how data is stored, validated, and rendered.
+ * Runtime Field Type
  *
- * - `text`: Simple string.
- * - `textarea`: Long string.
- * - `select`: Choice from a list.
- * - `lookup`: Relationship to another object.
- * - `file`: File attachment. Value stored as AttachmentData (single) or AttachmentData[] (multiple).
- * - `image`: Image attachment. Value stored as ImageAttachmentData (single) or ImageAttachmentData[] (multiple).
+ * Extends the Protocol FieldType with runtime-specific types.
+ * The Protocol Constitution defines the core field types.
+ * We add runtime-specific types like 'vector', 'grid', 'location', 'object' here.
  */
-export type FieldType = 'text' | 'textarea' | 'markdown' | 'html' | 'select' | 'date' | 'datetime' | 'time' | 'number' | 'currency' | 'percent' | 'boolean' | 'email' | 'phone' | 'url' | 'image' | 'file' | 'location' | 'lookup' | 'master_detail' | 'password' | 'formula' | 'summary' | 'auto_number' | 'object' | 'vector' | 'grid';
+export type FieldType = ProtocolFieldType | 'location' | 'object' | 'vector' | 'grid';
 /**
- * Defines a single option for select/multiselect fields.
+ * Runtime Field Option
+ *
+ * Extends the Protocol SelectOption to allow number values (for backwards compatibility).
  */
 export interface FieldOption {
     /** The display label for the option. */
     label: string;
     /** The actual value stored in the database. */
     value: string | number;
+    /** Optional color for visual representation */
+    color?: string;
+    /** Whether this is the default option */
+    default?: boolean;
 }
 /**
- * Configuration for a single field on an object.
- * This defines the schema, validation rules, and UI hints for the attribute.
+ * Runtime Field Configuration
+ *
+ * Extends the Protocol Field definition with runtime-specific properties.
+ * The Protocol Constitution (SpecField) defines the core field schema.
+ * This adds runtime conveniences and extensions.
+ *
+ * Properties from the protocol Field interface that are re-declared here:
+ * - `name`, `label`: Made optional for runtime convenience (auto-populated from Record key)
+ * - `type`: Extended union type to include runtime-specific types (vector, grid, location, object)
+ * - `options`: Extended to allow numeric values for backwards compatibility
+ * - Boolean flags (`required`, `multiple`, `unique`, `hidden`, `readonly`, `encryption`, `index`, `externalId`):
+ *   Made optional since Zod applies defaults at parse time, but runtime usage typically specifies these explicitly
+ * - `deleteBehavior`: Made optional with protocol-compatible enum values
+ *
+ * All other protocol properties (description, defaultValue, maxLength, minLength, precision, scale, min, max,
+ * reference, referenceFilters, writeRequiresMasterRead, expression, formula, summaryOperations) are inherited as-is.
  */
-export interface FieldConfig {
-    /**
-     * The unique API name of the field.
-     * If defined within an object map, this is often automatically populated from the key.
-     */
+export interface FieldConfig extends Omit<Field, 'name' | 'label' | 'type' | 'options' | 'required' | 'multiple' | 'unique' | 'deleteBehavior' | 'hidden' | 'readonly' | 'encryption' | 'index' | 'externalId' | 'searchable'> {
+    /** Field name (inferred from Record key when used in ObjectConfig.fields) */
     name?: string;
-    /** The human-readable label used in UIs. */
+    /** Display label (derived from name if not provided) */
     label?: string;
-    /** Description of the field for documentation or tooltip. */
-    description?: string;
-    /** The data type of the field. */
+    /** The data type of the field (extended with runtime types) */
     type: FieldType;
+    /** Options for select fields (extended to allow number values) */
+    options?: FieldOption[];
     /** Whether the field is mandatory. Defaults to false. */
     required?: boolean;
+    /** Whether the field allows multiple values. */
+    multiple?: boolean;
     /** Whether the field is unique in the table. */
     unique?: boolean;
-    /** Whether to create a database index for this field. */
-    index?: boolean;
-    /** Whether the field is read-only in UI. */
-    readonly?: boolean;
+    /** Whether the field is searchable (full-text search). Defaults to false. */
+    searchable?: boolean;
+    /** Delete behavior for relationships */
+    deleteBehavior?: 'set_null' | 'cascade' | 'restrict';
     /** Whether the field is hidden from default UI/API response. */
     hidden?: boolean;
-    /** The default value if not provided during creation. */
-    defaultValue?: any;
-    /** Tooltip or help text for the user. */
-    help_text?: string;
-    /**
-     * Whether the field allows multiple values.
-     * Supported by 'select', 'lookup', 'file', 'image'.
-     */
-    multiple?: boolean;
+    /** Whether the field is read-only in UI. */
+    readonly?: boolean;
+    /** Whether the field is encrypted */
+    encryption?: boolean;
+    /** Whether to create a database index for this field. */
+    index?: boolean;
+    /** Whether this is an external ID field */
+    externalId?: boolean;
     /**
-     * Options for select fields.
-     * List of available choices for select/multiselect fields.
+     * RUNTIME EXTENSIONS BELOW
+     * These properties are NOT in the wire protocol but are useful for the runtime.
      */
-    options?: FieldOption[];
+    /** Tooltip or help text for the user. */
+    help_text?: string;
     /**
      * Reference to another object for lookup/master_detail fields.
-     * Specifies the target object name for relationship fields.
+     *
+     * @deprecated Legacy alias for the protocol-level `reference` field (inherited from {@link Field}).
+     *
+     * **Migration Guidance:**
+     * - **New schemas MUST** use the `reference` field (defined in the protocol Field interface) instead of `reference_to`.
+     * - **During migration**, engines and tooling SHOULD:
+     *   - Treat `reference_to` as a fallback alias for `reference` (i.e., if `reference` is undefined and `reference_to`
+     *     is defined, behave as though `reference` were set to the same value).
+     *   - Prefer the protocol `reference` value when both are present.
+     * - This property is retained only for backward compatibility with older *.object.yml definitions and will be
+     *   removed in a future major version once all callers have migrated to `reference`.
+     *
+     * @example
+     * ```yaml
+     * # Old (deprecated):
+     * fields:
+     *   owner:
+     *     type: lookup
+     *     reference_to: users
+     *
+     * # New (protocol-compliant):
+     * fields:
+     *   owner:
+     *     type: lookup
+     *     reference: users
+     * ```
      */
     reference_to?: string;
     /**
@@ -135,30 +198,42 @@ export interface FieldConfig {
      * Minimum image height in pixels for image fields.
      */
     min_height?: number;
-    /** Minimum for number/currency/percent. */
-    min?: number;
-    /** Maximum for number/currency/percent. */
-    max?: number;
-    /** Minimum length for text based fields. */
-    min_length?: number;
-    /** Maximum length for text based fields. */
-    max_length?: number;
-    /** Regular expression pattern for validation. */
-    regex?: string;
     /**
      * Field validation configuration.
      * Defines validation rules applied at the field level.
      */
-    validation?: FieldValidation;
+    validation?: {
+        /** Format validation (email, url, etc.) */
+        format?: 'email' | 'url' | 'phone' | 'date' | 'datetime';
+        /** Allowed protocols for URL validation */
+        protocols?: string[];
+        /** Minimum value for numbers */
+        min?: number;
+        /** Maximum value for numbers */
+        max?: number;
+        /** Minimum length for strings */
+        min_length?: number;
+        /** Maximum length for strings */
+        max_length?: number;
+        /**
+         * Regular expression pattern for validation.
+         * Use this for custom pattern matching (e.g., /^[A-Z]{2}\d{4}$/ for codes).
+         */
+        pattern?: string;
+        /** Custom validation message */
+        message?: string;
+    };
     /**
      * AI context for the field.
      * Provides semantic information for AI tools.
      */
-    ai_context?: ValidationAiContext;
+    ai_context?: {
+        intent?: string;
+        validation_strategy?: string;
+        [key: string]: unknown;
+    };
     /** Dimension of the vector for 'vector' type fields. */
     dimension?: number;
-    /** Formula expression (for 'formula' type fields). */
-    formula?: string;
     /** Expected return data type for formula fields. */
     data_type?: 'number' | 'text' | 'date' | 'datetime' | 'boolean' | 'currency' | 'percent';
     /** Display format for formula results (e.g., "0.00", "YYYY-MM-DD"). */
@@ -175,5 +250,6 @@ export interface FieldConfig {
     summary_field?: string;
     /** Type of summary (count, sum, min, max, avg). */
     summary_type?: string;
+    /** Filters for summary */
     filters?: unknown[];
 }

package/dist/field.js

@@ -1,3 +1,10 @@
 "use strict";
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=field.js.map