@objectql/types

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

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

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

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

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

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:

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:

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:

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:

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):

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:

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 engine with Validator class
• Validation Specification - Complete validation metadata specification