reliant-type 1.0.0

package/src/core/schema/mode/interfaces/README.md

@@ -0,0 +1,278 @@
+# Interface Schema Architecture
+
+## Overview
+
+The Interface Schema system provides TypeScript-like schema validation with a modular, linked architecture. All modules are designed to work together and link back to the main `Interface.ts` and `InterfaceSchema.ts` components.
+
+## Core Architecture
+
+```
+Interface.ts (Main Entry Point)
+    ↓
+InterfaceSchema.ts (Core Implementation)
+    ↓
+├── validators/ (Core Validation Logic)
+│   ├── TypeValidators.ts (Primary validation engine)
+│   ├── ConstraintParser.ts (Constraint parsing & caching)
+│   ├── TypeGuards.ts (Type checking utilities)
+│   ├── ValidationHelpers.ts (Validation utilities)
+│   └── index.ts (Unified exports)
+│
+├── typescript/ (TypeScript Integration)
+│   ├── TypeInference.ts (Complete type system & inference)
+│   ├── ConditionalTypes.ts (Advanced conditional logic & operators)
+│   └── IDESupport.ts (Developer experience & tooling)
+│
+└── conditional/ (Conditional Validation)
+    ├── parser/ (AST parsing)
+    ├── evaluator/ (Expression evaluation)
+    └── types/ (Conditional type definitions)
+```
+
+## Module Roles & Responsibilities
+
+### Core Modules
+
+#### `Interface.ts`
+
+- **Role**: Main public API and entry point
+- **Responsibilities**:
+  - Export the `Interface()` function
+  - Provide type helpers (`InferType`, `InferSchemaType`)
+  - Export convenience utilities (`FieldTypes`, `QuickSchemas`)
+- **Links to**: `InterfaceSchema.ts`, all type definitions
+
+#### `InterfaceSchema.ts`
+
+- **Role**: Core schema implementation and validation orchestrator
+- **Responsibilities**:
+  - Implement the main `InterfaceSchema` class
+  - Coordinate validation through validators
+  - Handle schema compilation and caching
+  - Manage conditional validation
+- **Links to**: All validator modules, conditional system, type system
+
+### Validation System (`validators/`)
+
+#### `TypeValidators.ts`
+
+- **Role**: Primary validation engine for all data types
+- **Responsibilities**:
+  - Validate basic types (string, number, boolean, etc.)
+  - Handle specialized types (email, url, uuid, etc.)
+  - Apply constraints and transformations
+  - Support loose mode conversions
+- **Used by**: `InterfaceSchema.ts`, extensions
+- **Dependencies**: `ConstraintParser.ts`, `TypeGuards.ts`
+
+#### `ConstraintParser.ts`
+
+- **Role**: Parse and cache constraint syntax
+- **Responsibilities**:
+  - Parse constraint strings like `"string(3,20)"`, `"number(0,100)"`
+  - Cache parsed results for performance
+  - Handle complex constraint combinations
+- **Used by**: `TypeValidators.ts`, `InterfaceSchema.ts`
+
+#### `TypeGuards.ts`
+
+- **Role**: Type checking and validation utilities
+- **Responsibilities**:
+  - Provide type guard functions
+  - Check value types and formats
+  - Validate special constructs (unions, constants)
+- **Used by**: `TypeValidators.ts`, `ValidationHelpers.ts`
+
+#### `ValidationHelpers.ts`
+
+- **Role**: Shared validation utilities
+- **Responsibilities**:
+  - Handle constant value validation
+  - Provide result creation helpers
+  - Cache validation results
+- **Used by**: `TypeValidators.ts`, conditional system
+
+### TypeScript Integration (`typescript/`) - **UNIFIED SYSTEM**
+
+#### `TypeInference.ts` (Core Type System)
+
+- **Role**: Complete TypeScript type inference and analysis
+- **Responsibilities**:
+  - Infer TypeScript types from schema definitions
+  - Handle optional fields, arrays, nested objects
+  - Support advanced type transformations
+  - Analyze conditional expressions for type safety
+  - Provide compile-time type checking
+- **Used by**: `Interface.ts`, `InterfaceSchema.ts`, IDE support
+
+#### `ConditionalTypes.ts` (Advanced Conditional Logic)
+
+- **Role**: Advanced conditional type operations and operators
+- **Responsibilities**:
+  - Define conditional operators (`==`, `!=`, `>`, etc.)
+  - Handle operator precedence and evaluation
+  - Provide type-safe conditional builders
+  - Advanced conditional type utilities
+- **Used by**: Conditional system, type inference
+
+#### `IDESupport.ts` (Developer Experience)
+
+- **Role**: IDE integration and developer tooling
+- **Responsibilities**:
+  - Provide autocomplete for conditional expressions
+  - Generate hover information and diagnostics
+  - Support real-time validation feedback
+- **Used by**: IDE extensions, development tools
+
+
+
+### Conditional System (`conditional/`)
+
+#### `parser/ConditionalParser.ts`
+
+- **Role**: Parse conditional expressions into AST
+- **Responsibilities**:
+  - Parse conditional syntax like `"when field=value ? type1 : type2"`
+  - Generate Abstract Syntax Trees
+  - Handle nested conditionals
+- **Used by**: `InterfaceSchema.ts`, TypeScript integration
+
+#### `evaluator/ConditionalEvaluator.ts`
+
+- **Role**: Evaluate conditional expressions
+- **Responsibilities**:
+  - Execute conditional logic against data
+  - Return appropriate schema types based on conditions
+- **Used by**: `InterfaceSchema.ts`
+
+
+
+## Data Flow
+
+1. **Schema Definition**: User calls `Interface({ ... })` with schema definition
+2. **Schema Creation**: `Interface.ts` creates `InterfaceSchema` instance
+3. **Schema Compilation**: `InterfaceSchema.ts` pre-compiles field definitions using:
+   - `ConstraintParser.ts` for constraint parsing
+   - `ConditionalParser.ts` for conditional expressions
+4. **Validation**: When `safeParse()` is called:
+   - `InterfaceSchema.ts` orchestrates validation
+   - `TypeValidators.ts` performs actual type validation
+   - `ConditionalEvaluator.ts` handles conditional logic
+   - `ValidationHelpers.ts` provides utilities
+
+## Performance Optimizations
+
+- **Pre-compilation**: Constraints and conditionals are parsed once during schema creation
+- **Caching**: Parsed results are cached to avoid repeated parsing
+- **Modular Loading**: Only required modules are loaded based on schema features used
+
+## Extension Points
+
+- **Custom Validators**: Add new validators to `TypeValidators.ts`
+- **New Operators**: Extend `ConditionalOperators.ts`
+- **Type Extensions**: Add new type inference rules to `interface.type.ts`
+- **IDE Features**: Enhance `IDESupport.ts` for better developer experience
+
+## No Duplication Policy
+
+- **Single Source of Truth**: Each validation type has one implementation in `TypeValidators.ts`
+- **Shared Utilities**: Common functionality is in `ValidationHelpers.ts` and `TypeGuards.ts`
+- **Consistent APIs**: All modules use the same result types and error formats
+- **Unified Exports**: All functionality is accessible through `Interface.ts`
+
+## Current Issues & Fixes Applied
+
+### 1. Duplicate Validation Logic (✅ FIXED)
+
+**Problem**: `ValidationEngine` in `extensions/mods` duplicated validation logic from `TypeValidators`
+**Solution**: Refactored `ValidationEngine` to use `TypeValidators` as the single source of truth
+
+- Removed 200+ lines of duplicate validation code
+- ValidationEngine now delegates to TypeValidators for all validation
+- Consistent error handling and result formats across the system
+
+### 2. Scattered TypeScript Support (✅ REORGANIZED)
+
+**Problem**: TypeScript functionality was spread across multiple locations
+**Solution**: Consolidated all TypeScript integration in `typescript/` directory with clear roles
+
+- Created `typescript/index.ts` for unified exports
+- Proper linking through main `Interface.ts`
+- Clear separation of concerns between modules
+
+### 3. Missing Module Linking (✅ ESTABLISHED)
+
+**Problem**: Modules weren't properly linked to main Interface system
+**Solution**: All modules now properly import and link through `Interface.ts` and `InterfaceSchema.ts`
+
+- All validators exported through main Interface
+- TypeScript integration properly linked
+- Conditional system integrated with main schema
+
+### 4. Unclear Dependencies (✅ DOCUMENTED)
+
+**Problem**: Module dependencies and relationships weren't clear
+**Solution**: Created clear dependency graph and documented all relationships
+
+- Complete architecture documentation
+- Module roles and responsibilities defined
+- Data flow and interaction patterns documented
+
+### 5. Code Duplication Eliminated (✅ COMPLETED)
+
+**Problem**: Multiple modules had overlapping functionality
+**Solution**: Established single source of truth for each concern
+
+- TypeValidators: Single validation implementation
+- ConstraintParser: Single constraint parsing logic
+- ValidationHelpers: Shared utilities
+- No duplicate validation methods across modules
+
+## Usage Examples
+
+### Basic Schema Creation
+
+```typescript
+import { Interface } from "./Interface";
+
+const UserSchema = Interface({
+  id: "positive",
+  email: "email",
+  name: "string(2,50)",
+  age: "int(18,120)?",
+  tags: "string[]?",
+});
+```
+
+### With Conditional Validation
+
+```typescript
+const OrderSchema = Interface({
+  type: "pickup|delivery",
+  address: "when type=delivery ? string : string?",
+  fee: "when type=delivery ? number(0,) : number?",
+});
+```
+
+### Advanced Type Inference
+
+```typescript
+import { InferType } from "./Interface";
+
+type User = InferType<typeof UserSchema>;
+// Result: { id: number; email: string; name: string; age?: number; tags?: string[] }
+```
+
+## Testing Strategy
+
+- **Unit Tests**: Each module has comprehensive unit tests
+- **Integration Tests**: Test module interactions and data flow
+- **Performance Tests**: Validate caching and pre-compilation benefits
+- **Type Tests**: Ensure TypeScript type inference works correctly
+
+## Future Enhancements
+
+- **Compiler Integration**: Full TypeScript compiler API integration for `Make.fromType<T>()`
+- **Advanced Conditionals**: Support for more complex conditional expressions
+- **Custom Validators**: Plugin system for custom validation logic
+- **Schema Composition**: Advanced schema merging and composition utilities