@objectql/types 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @objectql/core
 
+## 1.5.0
+
+### Minor Changes
+
+- Minor version release - 1.5.0
+
+## 1.4.0
+
+### Minor Changes
+
+- Release version 1.4.0 with new features and enhancements:
+  - Added complete REST API implementation with CRUD operations
+  - Enhanced error handling with standardized error codes and HTTP status mapping
+  - Added AI context support for tracking intent and use cases
+  - Enhanced metadata API with detailed field information and action listing
+  - Improved JSON-RPC API with better error categorization
+  - Added hooks and actions validation and implementation
+  - Updated documentation and examples
+
 ## 1.3.1
 
 ## 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ObjectQL Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,53 +1,260 @@
-# @objectql/core
+# @objectql/types
 
-The core ORM and runtime engine for ObjectQL. This package handles object querying, CRUD operations, database driver coordination, and transaction management.
+Type definitions for the ObjectQL system, including object schemas, field configurations, validation rules, queries, hooks, and actions.
 
 ## Features
 
-- **Unified Query Language**: A generic way to query data across different databases (SQL, Mongo, etc.).
-- **Repository Pattern**: `ObjectRepository` for managing object records.
-- **Driver Agnostic**: Abstraction layer for database drivers.
-- **Dynamic Schema**: Loads object definitions from `@objectql/metadata`.
-- **Hooks & Actions**: Runtime logic injection.
+- **Object & Field Types**: Define data models with `ObjectConfig` and `FieldConfig`
+- **Query Types**: Type-safe query definitions with `UnifiedQuery`
+- **Validation Types**: Comprehensive validation rule types and interfaces
+- **Hook & Action Types**: Event-driven logic type definitions
+- **Driver Interface**: Abstraction layer for database drivers
+- **AI Context**: Metadata for AI-friendly documentation
 
 ## Installation
 
 ```bash
-npm install @objectql/core
+npm install @objectql/types
 ```
 
-## Usage
+## Exported Types
+
+### Core Types
+- `ObjectConfig` - Object schema definition
+- `FieldConfig` - Field configuration with validation
+- `FieldType` - Supported field data types
+- `ObjectDoc` - Base interface for all documents
+
+### Validation Types
+- `ValidationRule` - Base validation rule interface
+- `AnyValidationRule` - Union of all validation rule types
+- `ValidationContext` - Context provided to validators
+- `ValidationResult` - Result of validation execution
+- `ValidationRuleResult` - Result of a single rule
+- `ValidationError` - Validation error class
+- `ValidatorOptions` - Configuration for Validator class
+
+**Validation Rule Types:**
+- `CrossFieldValidationRule` - Compare fields with operators
+- `StateMachineValidationRule` - Enforce state transitions
+- `BusinessRuleValidationRule` - Complex business rules
+- `UniquenessValidationRule` - Uniqueness constraints
+- `DependencyValidationRule` - Related record validation
+- `CustomValidationRule` - Custom validation functions
+
+**Helper Types:**
+- `ValidationRuleType` - Types of validation rules
+- `ValidationSeverity` - Error severity levels (error, warning, info)
+- `ValidationTrigger` - When to run validation (create, update, delete)
+- `ValidationOperator` - Comparison operators (=, !=, >, >=, <, <=, in, contains, etc.)
+- `ValidationCondition` - Condition structure for rules
+- `ValidationAiContext` - AI-friendly metadata for rules
+- `FieldValidation` - Field-level validation configuration
+
+### Query Types
+- `UnifiedQuery` - Generic query structure
+- `QueryFilter` - Filter conditions
+- `QuerySort` - Sort specifications
+
+### Hook & Action Types
+- `HookContext` - Context for hook execution
+- `ActionContext` - Context for action execution
+- `HookHandler` - Hook function signature
+- `ActionHandler` - Action function signature
+
+### Driver Types
+- `Driver` - Database driver interface
+- `DriverConfig` - Driver configuration
+
+## Usage Examples
+
+### Object Definition with Validation
+
+```typescript
+import { ObjectConfig, FieldConfig } from '@objectql/types';
+
+const projectObject: ObjectConfig = {
+    name: 'project',
+    label: 'Project',
+    fields: {
+        name: {
+            type: 'text',
+            label: 'Project Name',
+            required: true,
+            validation: {
+                min_length: 3,
+                max_length: 100,
+                pattern: '^[a-zA-Z0-9\\s]+$',
+                message: 'Name must be 3-100 alphanumeric characters'
+            }
+        },
+        email: {
+            type: 'email',
+            validation: {
+                format: 'email',
+                message: 'Please enter a valid email address'
+            }
+        },
+        status: {
+            type: 'select',
+            options: [
+                { label: 'Planning', value: 'planning' },
+                { label: 'Active', value: 'active' },
+                { label: 'Completed', value: 'completed' }
+            ],
+            ai_context: {
+                intent: 'Track project lifecycle',
+                rationale: 'Projects follow a controlled workflow'
+            }
+        }
+    },
+    validation: {
+        rules: [
+            {
+                name: 'valid_date_range',
+                type: 'cross_field',
+                rule: {
+                    field: 'end_date',
+                    operator: '>=',
+                    compare_to: 'start_date'
+                },
+                message: 'End date must be on or after start date',
+                error_code: 'INVALID_DATE_RANGE'
+            }
+        ]
+    }
+};
+```
+
+### Validation Rule Definition
+
+```typescript
+import { 
+    CrossFieldValidationRule, 
+    StateMachineValidationRule,
+    ValidationContext 
+} from '@objectql/types';
+
+// Cross-field validation
+const dateRangeRule: CrossFieldValidationRule = {
+    name: 'valid_date_range',
+    type: 'cross_field',
+    rule: {
+        field: 'end_date',
+        operator: '>=',
+        compare_to: 'start_date'
+    },
+    message: 'End date must be on or after start date',
+    severity: 'error',
+    trigger: ['create', 'update']
+};
+
+// State machine validation
+const statusRule: StateMachineValidationRule = {
+    name: 'status_transition',
+    type: 'state_machine',
+    field: 'status',
+    transitions: {
+        planning: {
+            allowed_next: ['active', 'cancelled'],
+            ai_context: {
+                rationale: 'Can start work or cancel before beginning'
+            }
+        },
+        active: {
+            allowed_next: ['completed', 'cancelled']
+        },
+        completed: {
+            allowed_next: [],
+            is_terminal: true
+        }
+    },
+    message: 'Invalid status transition from {{old_status}} to {{new_status}}'
+};
+```
+
+### Using Validation Context
 
 ```typescript
-import { ObjectQL } from '@objectql/core';
-import { MetadataRegistry } from '@objectql/metadata';
-// Import a driver, e.g., @objectql/driver-knex
+import { ValidationContext, ValidationTrigger } from '@objectql/types';
 
-const objectql = new ObjectQL({
-    datasources: {
-        default: new MyDriver({ ... })
+const context: ValidationContext = {
+    record: {
+        start_date: '2024-01-01',
+        end_date: '2024-12-31',
+        status: 'active'
+    },
+    previousRecord: {
+        status: 'planning'
+    },
+    operation: 'update',
+    changedFields: ['status'],
+    metadata: {
+        objectName: 'project',
+        ruleName: 'status_transition'
     }
-});
+};
+```
+
+## Type Reference
+
+### ValidationRule
 
-await objectql.init();
+Base interface for all validation rules:
 
-// Use context for operations
-const ctx = objectql.createContext({ userId: 'u-1' });
-const projects = await ctx.object('project').find({
-    filters: [['status', '=', 'active']]
-});
+```typescript
+interface ValidationRule {
+    name: string;
+    type: ValidationRuleType;
+    message: string | Record<string, string>;
+    error_code?: string;
+    severity?: ValidationSeverity;
+    trigger?: ValidationTrigger[];
+    fields?: string[];
+    context?: string[];
+    skip_bulk?: boolean;
+    ai_context?: ValidationAiContext;
+    apply_when?: ValidationCondition;
+    async?: boolean;
+    timeout?: number;
+}
 ```
 
-## Shared Metadata
+### ValidationCondition
 
-You can pass an existing `MetadataRegistry` (e.g., from a low-code platform loader) to ObjectQL:
+Condition structure for validation rules:
 
 ```typescript
-const registry = new MetadataRegistry();
-// ... pre-load metadata ...
+interface ValidationCondition {
+    field?: string;
+    operator?: ValidationOperator;
+    value?: any;
+    compare_to?: string;  // For cross-field comparison
+    expression?: string;
+    all_of?: ValidationCondition[];
+    any_of?: ValidationCondition[];
+}
+```
+
+### FieldValidation
+
+Field-level validation configuration:
 
-const objectql = new ObjectQL({
-    registry: registry,
-    datasources: { ... }
-});
+```typescript
+interface FieldValidation {
+    format?: 'email' | 'url' | 'phone' | 'date' | 'datetime';
+    protocols?: string[];
+    min?: number;
+    max?: number;
+    min_length?: number;
+    max_length?: number;
+    pattern?: string;
+    message?: string;
+}
 ```
+
+## See Also
+
+- [@objectql/core](../core) - Core engine with Validator class
+- [Validation Specification](../../docs/spec/validation.md) - Complete validation metadata specification
+

package/dist/app.d.ts

@@ -15,6 +15,11 @@ export interface IObjectQL {
     registerObject(object: ObjectConfig): void;
     loadFromDirectory(dir: string): void;
     addLoader(plugin: LoaderPlugin): void;
+    /**
+     * Updates and persists metadata content.
+     * Only works if the metadata was loaded from a writable file source (e.g. local disk).
+     */
+    updateMetadata(type: string, id: string, content: any): Promise<void>;
     on(event: HookName, objectName: string, handler: HookHandler): void;
     triggerHook(event: HookName, objectName: string, ctx: HookContext): Promise<void>;
     registerAction(objectName: string, actionName: string, handler: ActionHandler): void;

package/dist/field.d.ts

@@ -1,3 +1,4 @@
+import { FieldValidation, ValidationAiContext } from './validation';
 /**
  * Represents the supported field data types in the ObjectQL schema.
  * These types determine how data is stored, validated, and rendered.
@@ -72,6 +73,16 @@ export interface FieldConfig {
     max_length?: number;
     /** Regular expression pattern for validation. */
     regex?: string;
+    /**
+     * Field validation configuration.
+     * Defines validation rules applied at the field level.
+     */
+    validation?: FieldValidation;
+    /**
+     * AI context for the field.
+     * Provides semantic information for AI tools.
+     */
+    ai_context?: ValidationAiContext;
     /** Dimension of the vector for 'vector' type fields. */
     dimension?: number;
 }

package/dist/hook.d.ts

@@ -67,18 +67,17 @@ export interface MutationHookContext<T = any> extends BaseHookContext<T> {
      * Only available in 'after' hooks.
      */
     result?: T;
+    /**
+     * The existing record fetched from DB before operation.
+     * Available in 'update' and 'delete' hooks.
+     */
+    previousData?: T;
 }
 /**
  * Specialized context for Updates, including change tracking.
  */
 export interface UpdateHookContext<T = any> extends MutationHookContext<T> {
     operation: 'update';
-    /**
-     * The record state BEFORE the update.
-     * Useful for comparison logic (e.g. status changed from A to B).
-     * Note: This may require a pre-fetch lookup depending on engine configuration.
-     */
-    previousData?: T;
     /**
      * Helper to check if a specific field is being modified.
      * Checks if the field exists in 'data' AND is different from 'previousData'.

package/dist/index.d.ts

@@ -10,4 +10,5 @@ export * from './app';
 export * from './plugin';
 export * from './config';
 export * from './context';
+export * from './validation';
 export * from './loader';

package/dist/index.js

@@ -26,5 +26,6 @@ __exportStar(require("./app"), exports);
 __exportStar(require("./plugin"), exports);
 __exportStar(require("./config"), exports);
 __exportStar(require("./context"), exports);
+__exportStar(require("./validation"), exports);
 __exportStar(require("./loader"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,+CAA6B;AAC7B,wCAAsB;AACtB,2CAAyB;AACzB,2CAAyB;AACzB,4CAA0B;AAG1B,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,+CAA6B;AAC7B,wCAAsB;AACtB,2CAAyB;AACzB,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAG7B,2CAAyB"}

package/dist/object.d.ts

@@ -1,5 +1,6 @@
 import { FieldConfig } from './field';
 import { ActionConfig } from './action';
+import { AnyValidationRule } from './validation';
 export interface IndexConfig {
     /** List of fields involved in the index */
     fields: string[];
@@ -31,6 +32,16 @@ export interface ObjectConfig {
     /** AI capabilities configuration */
     ai?: ObjectAiConfig;
     actions?: Record<string, ActionConfig>;
+    /** Validation rules for this object */
+    validation?: {
+        /** Validation rules */
+        rules?: AnyValidationRule[];
+        /** AI context for validation strategy */
+        ai_context?: {
+            intent?: string;
+            validation_strategy?: string;
+        };
+    };
 }
 /**
  * Base interface for all ObjectQL documents.