reliant-type 1.0.0

package/docs/ALL_TYPES.md

@@ -0,0 +1,120 @@
+
+## 📝 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"`       |
+
+## 🔗 Union Types
+
+```typescript
+// Basic unions
+status: "active|inactive|pending";
+role: "admin|user|guest";
+
+// Mixed type unions
+id: "string|number";
+value: "string|number|boolean";
+```
+
+## 📋 Array Types
+
+```typescript
+// Basic arrays
+tags: "string[]";
+scores: "number[]";
+
+// Optional arrays
+categories: "string[]?";
+
+// Array constraints
+limitedTags: "string[](1,5)"; // 1-5 items
+minItems: "string[](2,)"; // Minimum 2 items
+maxItems: "string[](,10)"; // Maximum 10 items
+
+// Combined constraints
+usernames: "string(3,20)[](1,100)"; // 1-100 usernames, each 3-20 chars
+```
+
+## ❓ Optional Types
+
+```typescript
+// Optional fields (can be undefined)
+nickname: "string?";
+bio: "string(,500)?";
+avatar: "url?";
+
+// Optional arrays
+tags: "string[]?";
+scores: "number[]?";
+```
+
+## 🎨 Literal Values
+
+```typescript
+// String literals
+type: "=user";
+version: "=2.0";
+
+// Number literals
+apiVersion: "=1";
+maxRetries: "=3";
+
+// Boolean literals
+isEnabled: "=true";
+isLegacy: "=false";
+
+// Complex literals
+config: '={"theme":"dark"}';
+tags: '=["default","user"]';
+```
+
+## 🔍 Custom Patterns
+
+```typescript
+// Regex patterns
+zipCode: "string(/^\\d{5}(-\\d{4})?$/)";
+username: "string(/^[a-zA-Z0-9_]{3,20}$/)";
+hexColor: "string(/^#[0-9A-Fa-f]{6}$/)";
+
+// Common patterns
+creditCard: "string(/^\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}$/)";
+ssn: "string(/^\\d{3}-\\d{2}-\\d{4}$/)";
+```

package/docs/API-STABILITY.md

@@ -0,0 +1,336 @@
+# API Stability and Production Readiness
+
+## Current Status: **STABLE** (v2.0.1)
+
+ReliantType has reached **STABLE** status with v2.0.1, meaning the core API is production-ready with comprehensive stability guarantees and enterprise-grade support.
+
+## API Stability Guarantee
+
+### Production Ready (Stable APIs) ✅
+
+- **Core Interface() function** - API locked, guaranteed stable
+- **Basic field types** (string, number, boolean, date, email, url, uuid, phone)
+- **Type constraints** (min/max, length, regex patterns, array constraints)
+- **Union types** (value1|value2|value3) with full TypeScript inference
+- **Optional fields** (type?) with proper null/undefined handling
+- **Array types** (type[], type[](min,max)) with comprehensive validation
+- **Nested objects** - Deep nesting with full type safety
+- **safeParse() and parse() methods** - API locked with comprehensive error handling
+- **V2 Conditional Validation** - Runtime method syntax (property.$method()) is stable
+- **Performance characteristics** - Guaranteed performance levels maintained
+
+### Recently Stabilized (v2.0.1) 🎯
+
+- **V2 Runtime Methods** - All 8 methods ($exists, $empty, $null, $contains, $startsWith, $endsWith, $between, $in)
+- **Advanced property access** - Deep nested properties, special characters, Unicode support
+- **Complex default values** - Object and array defaults with proper type inference
+- **Method combinations** - Logical operators (&&, ||) in conditional expressions
+- **Error message formats** - Standardized, detailed error reporting
+- **VS Code Extension** - Full V2 syntax support with IntelliSense
+
+### Experimental (Use with Caution) ⚠️
+
+- **Schema transformation utilities** (Mod.\*) - API may evolve
+- **Advanced validation modes** (strict, loose) - Implementation may change
+- **Custom validation functions** - Interface may be refined
+
+## Version Compatibility & Semantic Versioning
+
+### Semantic Versioning Promise
+
+We follow strict semantic versioning with enterprise-grade guarantees:
+
+- **MAJOR** (x.0.0): Breaking changes to stable APIs (rare, with 6-month notice)
+- **MINOR** (0.x.0): New features, 100% backward compatible
+- **PATCH** (0.0.x): Bug fixes, performance improvements, security patches
+
+### Breaking Change Policy
+
+- **6 months advance notice** for any breaking changes to stable APIs
+- **Comprehensive migration guides** with automated tooling where possible
+- **Deprecation warnings** added 3 months before removal with clear upgrade paths
+- **LTS versions** supported for 18 months minimum
+- **Enterprise customers** get 12 months advance notice and dedicated migration support
+
+### Version Support Matrix
+
+| Version    | Status             | Support Until | Production Ready   |
+| ---------- | ------------------ | ------------- | ------------------ |
+| **v2.0.x** | **Current Stable** | **June 2025** | **✅ Recommended** |
+
+## Production Deployment Guidelines
+
+### ✅ Recommended for Production (Stable APIs)
+
+```typescript
+// Production-ready schema with all stable features
+const ProductionUserSchema = Interface({
+  // Core identification
+  id: "uuid",
+  email: "email",
+  username: "string(/^[a-zA-Z0-9_]{3,20}$/)",
+
+  // Profile data with constraints
+  profile: {
+    firstName: "string(1,50)",
+    lastName: "string(1,50)",
+    avatar: "url?",
+    bio: "string(,500)?",
+    dateOfBirth: "date?",
+    preferences: {
+      theme: "light|dark|auto",
+      language: "string(/^[a-z]{2}(-[A-Z]{2})?$/)",
+      notifications: "boolean",
+    },
+  },
+
+  // Authorization
+  role: "user|moderator|admin|super_admin",
+  permissions: "string[]",
+
+  // V2 Conditional Validation (Stable)
+  config: "any?",
+  features: "any?",
+
+  // Runtime property checking
+  hasPermissions: "when  config.permissions.$exists() *? boolean : =false",
+  hasProfile: "when config.profile.$exists() *? boolean : =false",
+  isAdmin: "when role.$in(admin,super_admin) *? boolean : =false",
+  betaFeatures: "when features.beta.$exists() *? string[] : =[]",
+
+  // Complex business logic
+  canModerate:
+    "when role.$in(moderator,admin) && config.moderation.$exists() *? boolean : =false",
+
+  // Audit fields
+  createdAt: "date",
+  updatedAt: "date",
+  lastLogin: "date?",
+});
+
+// Production usage with comprehensive error handling
+const result = ProductionUserSchema.safeParse(userData);
+if (result.success) {
+  // Fully typed, validated data
+  processUser(result.data);
+} else {
+  // Detailed error information for logging/debugging
+  logValidationErrors(result.errors);
+}
+```
+
+### ⚠️ Use with Testing (Experimental APIs)
+
+```typescript
+// Experimental features - test thoroughly before production
+const ExperimentalSchema = Interface({
+  baseData: "string",
+
+  // Experimental: Schema transformations
+  transformedData: "string",
+});
+
+// Apply experimental transformations
+const PartialSchema = Mod.partial(ExperimentalSchema); // ⚠️ API may change
+const ExtendedSchema = Mod.extend(ExperimentalSchema, {
+  // ⚠️ API may change
+  newField: "string",
+});
+```
+
+## Performance Guarantees
+
+### Validated Performance Benchmarks
+
+| Operation                 | Guaranteed Minimum | Typical Performance | Enterprise SLA  |
+| ------------------------- | ------------------ | ------------------- | --------------- |
+| **Array Validation**      | 200,000 ops/sec    | 258,910 ops/sec     | 250,000 ops/sec |
+| **Union Types**           | 400,000 ops/sec    | 460,214 ops/sec     | 450,000 ops/sec |
+| **Simple Schema**         | 150,000 ops/sec    | 178,496 ops/sec     | 170,000 ops/sec |
+| **Complex Schema**        | 80,000 ops/sec     | 100,985 ops/sec     | 95,000 ops/sec  |
+| **Memory per Validation** | <150 bytes         | <100 bytes          | <120 bytes      |
+
+### Performance Monitoring
+
+```typescript
+// Production performance monitoring
+const performanceMonitor = {
+  validationCount: 0,
+  totalTime: 0,
+  errorCount: 0,
+
+  validate(schema, data) {
+    const start = performance.now();
+    const result = schema.safeParse(data);
+    const duration = performance.now() - start;
+
+    this.validationCount++;
+    this.totalTime += duration;
+    if (!result.success) this.errorCount++;
+
+    // Alert if performance degrades below SLA
+    const avgTime = this.totalTime / this.validationCount;
+    if (avgTime > 0.01) {
+      // 10ms threshold
+      console.warn("Validation performance degraded:", avgTime);
+    }
+
+    return result;
+  },
+
+  getMetrics() {
+    return {
+      averageTime: this.totalTime / this.validationCount,
+      operationsPerSecond: 1000 / (this.totalTime / this.validationCount),
+      errorRate: this.errorCount / this.validationCount,
+      totalValidations: this.validationCount,
+    };
+  },
+};
+```
+
+_See [Performance Benchmarks](./../src/bench/BENCHMARK-RESULTS.md) for up-to-date more details_
+
+## Enterprise Production Features
+
+### Security & Compliance
+
+- **Input Sanitization**: Automatic XSS prevention for string fields
+- **Data Validation**: Comprehensive type checking prevents injection attacks
+- **Audit Logging**: Built-in validation event logging for compliance
+- **GDPR Compliance**: Data validation without data retention
+
+### Monitoring & Observability
+
+- **Performance Metrics**: Built-in performance tracking
+- **Error Analytics**: Detailed validation failure analysis
+- **Health Checks**: Schema validation health endpoints
+- **Custom Metrics**: Integration with monitoring systems (Prometheus, DataDog, etc.)
+
+### Scalability & Reliability
+
+- **Memory Management**: Predictable memory usage patterns
+- **Concurrent Validation**: Thread-safe validation for high-concurrency applications
+- **Caching**: Intelligent schema compilation caching
+- **Failover**: Graceful degradation for validation failures
+
+## Migration Strategy
+
+### From v1.x to v2.0
+
+```typescript
+// v1.x (Legacy) - Still supported until December 2024
+const V1Schema = Interface({
+  name: "string",
+  role: "admin|user",
+  permissions: "when role=admin *? string[] : string[]?",
+});
+
+// v2.0 (Current) - Enhanced with runtime methods
+const V2Schema = Interface({
+  name: "string",
+  role: "admin|user",
+  config: "any?",
+
+  // Enhanced conditional validation
+  permissions: "when config.hasPermissions.$exists() *? string[] : =[]",
+
+  // New capabilities
+  advancedFeatures: "when config.features.$exists() *? any : ={}",
+});
+
+// Migration helper (provided)
+const migratedSchema = migrateV1ToV2(V1Schema);
+```
+
+## Risk Assessment & Mitigation
+
+### Low Risk (Production Ready) ✅
+
+- **Core validation APIs**: Extensively tested, API locked
+- **Performance characteristics**: Benchmarked and guaranteed
+- **TypeScript integration**: Full type safety guaranteed
+- **Error handling**: Comprehensive and stable
+
+**Mitigation**: None required - production ready
+
+### Medium Risk (Stable but Evolving) ⚠️
+
+- **New runtime methods**: May be added in minor versions
+- **Error message improvements**: May change for clarity
+- **Performance optimizations**: Internal changes, API stable
+
+**Mitigation**:
+
+- Monitor release notes for new features
+- Test thoroughly in staging before production deployment
+- Use semantic versioning for controlled updates
+
+### High Risk (Experimental) 🧪
+
+- **Schema transformation utilities**: API may change
+- **Advanced validation modes**: Implementation may change
+- **Undocumented features**: No stability guarantee
+
+**Mitigation**:
+
+- Use only in development/testing environments
+- Have rollback plans ready
+- Monitor GitHub discussions for API changes
+
+## Production Deployment Checklist
+
+### Pre-Deployment
+
+- [ ] **Performance Testing**: Validate performance meets requirements
+- [ ] **Error Handling**: Implement comprehensive error logging
+- [ ] **Monitoring**: Set up validation metrics and alerts
+- [ ] **Fallback Strategy**: Plan for validation failures
+- [ ] **Security Review**: Validate input sanitization requirements
+
+### Deployment
+
+- [ ] **Gradual Rollout**: Deploy to percentage of traffic first
+- [ ] **Performance Monitoring**: Watch for performance regressions
+- [ ] **Error Rate Monitoring**: Track validation failure rates
+- [ ] **Memory Monitoring**: Ensure no memory leaks
+- [ ] **Rollback Plan**: Ready to revert if issues arise
+
+### Post-Deployment
+
+- [ ] **Performance Validation**: Confirm SLA compliance
+- [ ] **Error Analysis**: Review and address validation failures
+- [ ] **User Feedback**: Monitor for user-reported issues
+- [ ] **Optimization**: Identify opportunities for improvement
+
+## Conclusion
+
+**ReliantType v2.0 is production-ready** with comprehensive stability guarantees, enterprise-grade support, and proven performance characteristics.
+
+### Recommendations by Use Case
+
+**🏢 Enterprise Applications**:
+
+- Use stable APIs with enterprise support
+- Implement comprehensive monitoring
+- Plan gradual migration from legacy systems
+
+**🚀 New Projects**:
+
+- Start with v2.0 stable APIs
+- Leverage V2 conditional validation for complex business logic
+- Use VS Code extension for enhanced developer experience
+
+**🔄 Existing Projects**:
+
+- Migrate gradually from v1.x to v2.0
+- Test thoroughly in staging environments
+- Take advantage of LTS support during transition
+
+**📈 High-Performance Applications**:
+
+- Leverage proven performance benchmarks
+- Implement performance monitoring
+- Use array validation for optimal performance
+
+For questions about production deployment, contact our enterprise support team at https://github.com/Nehonix-Team/reliant-type/discussions.