# @objectql/types

> **Implementation Status**: ✅ **Complete** - All type definitions available. See [Implementation Status](https://github.com/objectstack-ai/objectql/blob/main/IMPLEMENTATION_STATUS.md) for runtime implementation details.

Type definitions for the ObjectQL system, including object schemas, field configurations, validation rules, queries, hooks, and actions.

> **Note**: This package defines the type system. Some types (like permissions and workflows) are defined but require application-layer implementation. See the implementation status document for details.

## Features

- **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/types
```

## 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

### Migration & Schema Evolution Types
- `SchemaChangeType` - Types of schema change operations
- `SchemaChangeInstruction` - Union of all schema change instructions
- `FieldUpdateInstruction` - Instruction to update/modify a field
- `FieldDeleteInstruction` - Instruction to delete/remove a field
- `ObjectUpdateInstruction` - Instruction to update/modify an object
- `ObjectDeleteInstruction` - Instruction to delete/remove an object
- `MigrationConfig` - Complete migration configuration
- `MigrationStep` - Single step in a migration
- `MigrationStatus` - Execution status of a migration

## 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 { ValidationContext, ValidationTrigger } from '@objectql/types';

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

Base interface for all validation rules:

```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;
}
```

### ValidationCondition

Condition structure for validation rules:

```typescript
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:

```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;
}
```

### Migration & Schema Evolution

Define schema changes declaratively for object and field updates/deletions:

```typescript
import { 
    MigrationConfig, 
    FieldUpdateInstruction, 
    FieldDeleteInstruction,
    ObjectUpdateInstruction,
    ObjectDeleteInstruction 
} from '@objectql/types';

// Define a migration with multiple schema changes
const migration: MigrationConfig = {
    id: 'v1.2_refactor_user_fields',
    version: '1.2.0',
    name: 'Refactor User Fields',
    description: 'Update user object schema and remove deprecated fields',
    author: 'dev-team',
    created_at: '2026-01-14T00:00:00Z',
    steps: [
        {
            id: 'rename_username_field',
            name: 'Rename username to user_name',
            instruction: {
                type: 'field_update',
                object_name: 'users',
                field_name: 'username',
                new_field_name: 'user_name',
                changes: {
                    label: 'User Name',
                    description: 'Updated field name for consistency'
                },
                data_migration_strategy: 'auto'
            } as FieldUpdateInstruction,
            reversible: true
        },
        {
            id: 'update_email_field',
            name: 'Make email field required',
            instruction: {
                type: 'field_update',
                object_name: 'users',
                field_name: 'email',
                changes: {
                    required: true,
                    unique: true
                },
                data_migration_strategy: 'auto'
            } as FieldUpdateInstruction,
            reversible: true
        },
        {
            id: 'delete_legacy_field',
            name: 'Remove deprecated legacy_id field',
            instruction: {
                type: 'field_delete',
                object_name: 'users',
                field_name: 'legacy_id',
                deletion_strategy: 'archive',
                archive_location: 'backup/users_legacy_id'
            } as FieldDeleteInstruction,
            reversible: true
        },
        {
            id: 'update_object_label',
            name: 'Update Users object label',
            instruction: {
                type: 'object_update',
                object_name: 'users',
                changes: {
                    label: 'System Users',
                    description: 'Updated to reflect new naming convention'
                }
            } as ObjectUpdateInstruction,
            reversible: true
        }
    ],
    reversible: true,
    tags: ['schema', 'refactor']
};
```

**Field Update Example (Type Change):**

```typescript
const changeFieldType: FieldUpdateInstruction = {
    type: 'field_update',
    object_name: 'products',
    field_name: 'price',
    changes: {
        type: 'currency',  // Changed from 'number' to 'currency'
        defaultValue: 0
    },
    data_migration_strategy: 'manual',
    transform_script: `
        // Custom transformation for price field
        return {
            amount: oldValue,
            currency: 'USD'
        };
    `,
    description: 'Convert price from number to currency type',
    reason: 'Support multi-currency pricing'
};
```

**Object Deletion Example:**

```typescript
const deleteObject: ObjectDeleteInstruction = {
    type: 'object_delete',
    object_name: 'temp_imports',
    deletion_strategy: 'archive',
    archive_location: 'backups/temp_imports_archive',
    cascade_strategy: 'nullify',
    description: 'Remove temporary import table',
    reason: 'No longer needed after migration to new import system'
};
```

## See Also

- [@objectql/core](../core) - Core engine with Validator class
- [Validation Specification](../../../docs/spec/validation.md) - Complete validation metadata specification