reliant-type 1.0.0

package/docs/QUICK-REFERENCE.md

@@ -0,0 +1,346 @@
+# Quick Reference
+
+Fast reference guide for ReliantType syntax, types, and patterns.
+
+## 🚀 Basic Usage
+
+```typescript
+import { Interface } from "reliant-type";
+
+const Schema = Interface({
+  // Your schema definition
+});
+
+const result = Schema.safeParse(data);
+if (result.success) {
+  // Use result.data (fully typed)
+} else {
+  // Handle result.errors
+}
+```
+
+## 📝 Basic Types
+
+| Type        | Syntax      | Example               |
+| ----------- | ----------- | --------------------- |
+| **String**  | `"string"`  | `name: "string"`      |
+| **Number**  | `"number"`  | `age: "number"`       |
+| **Boolean** | `"boolean"` | `active: "boolean"`   |
+| **Date**    | `"date"`    | `createdAt: "date"`   |
+| **Any**     | `"any"`     | `metadata: "any"`     |
+| **unknown** | `"unknown"` | `property: "unknown"` |
+| **object**  | `"object"`  | `data: "object"`      |
+
+_Note: Bool is an aliax for Boolean_
+
+## 🎯 Constrained Types
+
+| Type              | Syntax              | Example                |
+| ----------------- | ------------------- | ---------------------- |
+| **String Length** | `"string(min,max)"` | `name: "string(2,50)"` |
+| **Number Range**  | `"number(min,max)"` | `age: "number(0,120)"` |
+| **Integer**       | `"int"`             | `count: "int"`         |
+| **Positive**      | `"positive"`        | `id: "positive"`       |
+| **Negative**      | `"negative"`        | `debt: "negative"`     |
+| **double**        | `"double"`          | `fl: "double"`         |
+
+## 📧 Format Types
+
+| Type           | Syntax       | Example                |
+| -------------- | ------------ | ---------------------- |
+| **Email**      | `"email"`    | `email: "email"`       |
+| **text**       | `"text"`     | `description: "text"`  |
+| **password**   | `"password"` | `userPass: "password"` |
+| **URL**        | `"url"`      | `website: "url"`       |
+| **UUID**       | `"uuid"`     | `id: "uuid"`           |
+| **Phone**      | `"phone"`    | `mobile: "phone"`      |
+| **IP Address** | `"ip"`       | `server: "ip"`         |
+| **JSON**       | `"json"`     | `config: "json"`       |
+| **Hex Color**  | `"hexcolor"` | `color: "hexcolor"`    |
+| **Base64**     | `"base64"`   | `data: "base64"`       |
+| **JWT**        | `"jwt"`      | `token: "jwt"`         |
+| **SemVer**     | `"semver"`   | `version: "semver"`    |
+| **slug**       | `"slug"`     | `test: "semver"`       |
+
+See [all types](./ALL_TYPES.md)
+
+## 🔥 V2 Conditional Validation
+
+### Basic Syntax
+
+```typescript
+// Basic conditional
+permissions: "when role=admin *? string[] : string[]?";
+
+// V2 runtime methods
+hasData: "when config.data.$exists() *? boolean : =false";
+```
+
+### V2 Runtime Methods
+
+| Method                  | Syntax                         | Description                 |
+| ----------------------- | ------------------------------ | --------------------------- |
+| **$exists()**           | `property.$exists()`           | Check if property exists    |
+| **$empty()**            | `property.$empty()`            | Check if property is empty  |
+| **$null()**             | `property.$null()`             | Check if property is null   |
+| **$contains(val)**      | `property.$contains(value)`    | Check if contains value     |
+| **$startsWith(prefix)** | `property.$startsWith(prefix)` | Check if starts with prefix |
+| **$endsWith(suffix)**   | `property.$endsWith(suffix)`   | Check if ends with suffix   |
+| **$between(min,max)**   | `property.$between(min,max)`   | Check if value in range     |
+| **$in(val1,val2,...)**  | `property.$in(val1,val2,...)`  | Check if value in list      |
+
+### V2 Examples
+
+```typescript
+const V2Schema = Interface({
+  config: "any?",
+  user: "any?",
+
+  // Property existence
+  hasPermissions: "when config.permissions.$exists() *? boolean : =false",
+
+  // Empty checking
+  hasContent: "when user.bio.$empty() *? =no_bio : =has_bio",
+
+  // String methods
+  isImportant: "when user.message.$contains(urgent) *? boolean : =false",
+  isSystemUser: "when user.email.$endsWith(@system.com) *? boolean : =false",
+
+  // Numeric methods
+  isAdult: "when user.age.$between(18,65) *? boolean : =false",
+  hasElevatedRole: "when user.role.$in(admin,moderator) *? boolean : =false",
+
+  // Complex defaults
+  defaultSettings: 'when config.settings.$exists() *? any : ={"theme":"dark"}',
+  defaultTags: 'when config.tags.$exists() *? string[] : =["default"]',
+});
+```
+
+## 🏗️ Nested Objects
+
+```typescript
+const NestedSchema = Interface({
+  user: {
+    id: "uuid",
+    profile: {
+      name: "string",
+      contact: {
+        email: "email",
+        phone: "phone?",
+        address: {
+          street: "string",
+          city: "string",
+          country: "string(2,2)"
+        }?
+      }
+    }
+  },
+
+  // Optional nested objects
+  settings: {
+    theme: "light|dark",
+    notifications: {
+      email: "boolean",
+      push: "boolean"
+    }
+  }?
+});
+```
+
+## ⚡ Performance Tips
+
+### Efficient Types
+
+```typescript
+// ✅ Fast - Use specific types
+email: "email";
+id: "uuid";
+age: "int(0,120)";
+
+// ❌ Slower - Generic types with validation
+email: "string"; // Then validate in code
+id: "string"; // Then validate format
+age: "number"; // Then check range
+```
+
+### Efficient Conditionals
+
+```typescript
+// ✅ Fast - Simple existence checks first
+hasFeature: "when config.$exists() && config.features.$exists() *? boolean : =false";
+
+// ❌ Slower - Complex operations first
+hasFeature: "when config.features.$contains(advanced) && config.$exists() *? boolean : =false";
+```
+
+## 🛠️ Common Patterns
+
+### User Schema
+
+```typescript
+const UserSchema = Interface({
+  id: "uuid",
+  email: "email",
+  username: "string(3,20)",
+  password: "string(8,)",
+  profile: {
+    firstName: "string(1,50)",
+    lastName: "string(1,50)",
+    avatar: "url?",
+    bio: "string(,500)?",
+  },
+  role: "admin|user|moderator",
+  isActive: "boolean",
+  createdAt: "date",
+  lastLogin: "date?",
+});
+```
+
+### API Response Schema
+
+```typescript
+const APIResponseSchema = Interface({
+  status: "success|error|partial",
+  statusCode: "int(100,599)",
+  message: "string?",
+  data: "any?",
+  errors: {
+    code: "string",
+    message: "string",
+    field: "string?"
+  }[]?,
+  meta: {
+    timestamp: "date",
+    requestId: "uuid",
+    version: "string(/^v\\d+\\.\\d+$/)"
+  }
+});
+```
+
+### E-commerce Product Schema
+
+```typescript
+const ProductSchema = Interface({
+  id: "uuid",
+  sku: "string(/^[A-Z0-9-]{8,20}$/)",
+  name: "string(1,200)",
+  price: "number(0.01,999999.99)",
+  category: "electronics|clothing|books|home",
+  inStock: "boolean",
+  tags: "string[](0,20)",
+  images: {
+    primary: "url",
+    gallery: "url[](0,10)"
+  }?,
+  seo: {
+    title: "string(,60)?",
+    description: "string(,160)?"
+  }?
+});
+```
+
+## 🔧 Validation Methods
+
+### Safe Parsing (Recommended)
+
+```typescript
+const result = Schema.safeParse(data);
+
+if (result.success) {
+  console.log("Valid:", result.data); // Fully typed
+} else {
+  console.log("Errors:", result.errors);
+  result.errors.forEach((error) => {
+    console.log(`${error.path.join(".")}: ${error.message}`);
+  });
+}
+```
+
+### Direct Parsing
+
+```typescript
+try {
+  const validData = Schema.parse(data);
+  // Use validData (fully typed)
+} catch (error) {
+  console.log("Validation failed:", error.message);
+}
+```
+
+## 🎨 VS Code Extension
+
+### Trigger Characters
+
+- `"` - Type suggestions
+- `:` - Field definitions
+- `|` - Union types
+- `=` - Constants
+- `(` - Constraints
+- `.` - Property access
+- `$` - V2 methods
+
+### Commands
+
+- `Ctrl+Shift+V` - Validate Schema
+- `Ctrl+Shift+T` - Apply Color Scheme
+- `F12` - Go to Definition
+- `Ctrl+Space` - Trigger Completion
+
+### Settings
+
+```json
+{
+  "fortify.enableDiagnostics": true,
+  "fortify.colorScheme": "professional",
+  "editor.semanticHighlighting.enabled": true
+}
+```
+
+## 🚨 Common Mistakes
+
+### ❌ Wrong Constraint Syntax
+
+```typescript
+// Wrong
+name: "string(,)"; // Empty constraint
+age: "number()"; // Empty parentheses
+tags: "string[]("; // Incomplete array constraint
+
+// Correct
+name: "string(1,50)"; // Proper min,max
+age: "number(0,120)"; // Proper range
+tags: "string[](1,10)"; // Proper array constraint
+```
+
+### ❌ Invalid Union Syntax
+
+```typescript
+// Wrong
+status: "active | inactive"; // Spaces around |
+role: "admin,user,guest"; // Commas instead of |
+
+// Correct
+status: "active|inactive"; // No spaces
+role: "admin|user|guest"; // Use | separator
+```
+
+### ❌ Incorrect Optional Syntax
+
+```typescript
+// Wrong
+name: "string | undefined"; // TypeScript syntax
+age: "number | null"; // TypeScript syntax
+
+// Correct
+name: "string?"; // Fortify optional syntax
+age: "number?"; // Simple and clean
+```
+
+## 📚 Quick Links
+
+- **[Getting Started](./GETTING-STARTED.md)** - Installation and first steps
+- **[Field Types Reference](./FIELD-TYPES.md)** - Complete type guide
+- **[Conditional Validation](./CONDITIONAL-VALIDATION.md)** - V1 and V2 conditionals
+- **[VS Code Extension](./VSCODE-EXTENSION.md)** - Development tools
+- **[Examples Collection](./EXAMPLES.md)** - Real-world patterns
+- **[API Reference](./API-REFERENCE.md)** - Complete API docs

package/docs/README.md

@@ -0,0 +1,205 @@
+# ReliantType Documentation
+
+Welcome to the comprehensive documentation for ReliantType - the TypeScript-first validation library with interface-native syntax.
+
+## 📚 Documentation Index
+
+### **Getting Started**
+
+- **[Installation & Setup](./GETTING-STARTED.md)** - Quick start guide and installation
+- **[Basic Examples](./BASIC-EXAMPLES.md)** - Simple examples to get you started
+- **[Field Types Reference](./FIELD-TYPES.md)** - Complete guide to all available field types
+
+### **Core Features**
+
+- **[Conditional Validation Guide](./CONDITIONAL-VALIDATION.md)** - V1 and V2 conditional validation
+- **[Live Utility - Real-time Validation](./LIVE-UTILITY.md)** - EventEmitter interface, stream processing, and form integration
+- **[V2 Migration Guide](./V2-MIGRATION.md)** - Migrating from V1 to V2 syntax
+- **[Advanced Features](./ADVANCED-FEATURES.md)** - Schema transformations and validation modes
+
+### **Tooling & Development**
+
+- **[VS Code Extension](./VSCODE-EXTENSION.md)** - Complete extension guide and features
+- **[API Reference](./API-REFERENCE.md)** - Complete API documentation
+- **[Performance Guide](./PERFORMANCE.md)** - Optimization and benchmarking
+
+### **Examples & References**
+
+- **[Examples Collection](./EXAMPLES.md)** - Real-world examples and patterns
+- **[Quick Reference](./QUICK-REFERENCE.md)** - Syntax cheat sheet
+- **[Best Practices](./BEST-PRACTICES.md)** - Recommended patterns and practices
+
+### **Production & Enterprise**
+
+- **[Production Deployment](./PRODUCTION-DEPLOYMENT.md)** - Production deployment guide
+- **[API Stability](./API-STABILITY.md)** - Production readiness and stability guarantees
+- **[Enterprise Features](./ENTERPRISE.md)** - Enterprise-specific features and support
+
+## 🚀 Quick Navigation
+
+### **New to ReliantType?**
+
+1. Start with **[Getting Started](./GETTING-STARTED.md)**
+2. Learn the basics with **[Basic Examples](./BASIC-EXAMPLES.md)**
+3. Explore **[Field Types](./FIELD-TYPES.md)** for validation options
+
+### **Upgrading from V1?**
+
+1. Read the **[V2 Migration Guide](./V2-MIGRATION.md)**
+2. Learn **[V2 Conditional Validation](./CONDITIONAL-VALIDATION.md)**
+3. Check **[API Stability](./API-STABILITY.md)** for compatibility
+
+### **Building Production Apps?**
+
+1. Review **[Best Practices](./BEST-PRACTICES.md)**
+2. Follow **[Production Deployment](./PRODUCTION-DEPLOYMENT.md)**
+3. Consider **[Enterprise Features](./ENTERPRISE.md)**
+
+### **Need Development Tools?**
+
+1. Install **[VS Code Extension](./VSCODE-EXTENSION.md)**
+2. Check **[Performance Guide](./PERFORMANCE.md)**
+3. Use **[Quick Reference](./QUICK-REFERENCE.md)** for syntax
+
+### **Building Real-time Applications?**
+
+1. Learn **[Live Utility](./LIVE-UTILITY.md)** for stream processing
+2. Implement real-time form validation
+3. Use EventEmitter interface for reactive validation
+
+## 🎯 Key Concepts
+
+### **Interface-Native Syntax**
+
+ReliantType uses TypeScript interface-like syntax for intuitive schema definition:
+
+```typescript
+const UserSchema = Interface({
+  id: "uuid",
+  email: "email",
+  name: "string(2,50)",
+  age: "number(18,120)?",
+  role: "admin|user|guest",
+});
+```
+
+### **V2 Conditional Validation**
+
+Enhanced runtime property checking with powerful method syntax:
+
+```typescript
+const AdvancedSchema = Interface({
+  config: "any?",
+
+  // V2 Runtime Methods
+  hasPermissions: "when config.permissions.$exists() *? boolean : =false",
+  isListEmpty: "when config.items.$empty() *? boolean : =true",
+  hasAdminRole: "when config.roles.$contains(admin) *? boolean : =false",
+});
+```
+
+### **Type Safety**
+
+Full TypeScript integration with perfect type inference:
+
+```typescript
+const result = UserSchema.safeParse(data);
+if (result.success) {
+  // result.data is fully typed!
+  console.log(result.data.email); // TypeScript knows this is a string
+}
+```
+
+## 🔥 What's New in V2
+
+### **Enhanced Runtime Methods**
+
+- **8 new runtime methods**: `$exists()`, `$empty()`, `$null()`, `$contains()`, `$startsWith()`, `$endsWith()`, `$between()`, `$in()`
+- **Deep property access**: `user.profile.settings.advanced.$exists()`
+- **Special character support**: `config["admin-override"].$exists()`
+- **Unicode support**: `features.feature_🚀.$exists()`
+
+### **Complex Default Values**
+
+- **Object defaults**: `={"theme":"dark","lang":"en"}`
+- **Array defaults**: `=["default","user"]`
+- **Type-safe defaults**: Full TypeScript inference
+
+### **Performance Improvements**
+
+- **258,910 ops/sec** for array validation (1.6x faster than Zod)
+- **460,214 ops/sec** for union types
+- **Sub-millisecond validation** for typical schemas
+
+## 🛠️ Development Tools
+
+### **VS Code Extension**
+
+Professional development experience with:
+
+- **Syntax Highlighting** - Context-aware highlighting
+- **IntelliSense** - Smart autocomplete for all features
+- **Real-time Validation** - Instant error detection
+- **Hover Documentation** - Detailed information on hover
+- **Go-to-Definition** - Navigate to property definitions
+
+### **Performance Monitoring**
+
+Built-in performance tracking and optimization:
+
+- **Validation metrics** - Track performance in production
+- **Memory monitoring** - Detect memory leaks
+- **Benchmark tools** - Compare with other libraries
+
+## 📖 Learning Path
+
+### **Beginner (0-1 hour)**
+
+1. **[Getting Started](./GETTING-STARTED.md)** - Installation and first schema
+2. **[Basic Examples](./BASIC-EXAMPLES.md)** - Simple validation patterns
+3. **[Field Types](./FIELD-TYPES.md)** - Available validation types
+
+### **Intermediate (1-3 hours)**
+
+1. **[Conditional Validation](./CONDITIONAL-VALIDATION.md)** - Business logic validation
+2. **[Advanced Features](./ADVANCED-FEATURES.md)** - Schema transformations
+3. **[VS Code Extension](./VSCODE-EXTENSION.md)** - Development tools
+
+### **Advanced (3+ hours)**
+
+1. **[V2 Migration](./V2-MIGRATION.md)** - Upgrading existing schemas
+2. **[Performance Guide](./PERFORMANCE.md)** - Optimization techniques
+3. **[Production Deployment](./PRODUCTION-DEPLOYMENT.md)** - Enterprise deployment
+
+## 🤝 Community & Support
+
+### **Getting Help**
+
+- **[GitHub Issues](https://github.com/Nehonix-Team/reliant-type/issues)** - Bug reports and feature requests
+- **[GitHub Discussions](https://github.com/Nehonix-Team/reliant-type/discussions)** - Community Q&A
+- **[Examples Collection](./EXAMPLES.md)** - Real-world usage patterns
+
+### **Contributing**
+
+- **[Contributing Guide](../CONTRIBUTING.md)** - How to contribute
+- **[Best Practices](./BEST-PRACTICES.md)** - Recommended patterns
+- **[API Reference](./API-REFERENCE.md)** - Complete API documentation
+
+### **Enterprise Support**
+
+- **[Enterprise Features](./ENTERPRISE.md)** - Enterprise-specific capabilities
+- **[API Stability](./API-STABILITY.md)** - Production guarantees
+- **Email**: https://github.com/Nehonix-Team/reliant-type/discussions
+
+## 🎉 Ready to Start?
+
+Choose your path:
+
+**🚀 New Project**: Start with **[Getting Started](./GETTING-STARTED.md)**
+**🔄 Existing Project**: Check **[V2 Migration Guide](./V2-MIGRATION.md)**
+**🏢 Enterprise**: Review **[Production Deployment](./PRODUCTION-DEPLOYMENT.md)**
+**🛠️ Development**: Install **[VS Code Extension](./VSCODE-EXTENSION.md)**
+
+---
+
+_Built with precision and care by the Nehonix Team_