JSON-Based Contract

[andrehrferreira]

🚀 @cmmv/core - JSON-Based Contract System

🎯 Overview

The @cmmv/core module currently manages CMMV contracts, which are written in TypeScript decorators enriched with metadata, validations, and type definitions. These contracts serve as a single source of truth for various modules, including HTTP, GraphQL, Protobuf, and other transpilers.

To enhance integration with @cmmv/admin, the goal is to support JSON-based contract representation, enabling:

1. Bidirectional conversion: Convert a TypeScript contract → JSON and vice versa.
2. Seamless visual editing in @cmmv/admin using @cmmv/ui components.
3. Simplified contract modifications without direct code changes.

---

✅ Feature Checklist & Implementation Plan

🔄 JSON-Based Contract Conversion

• Export contracts to JSON (preserving all metadata, validations, and configurations).
• Import contracts from JSON and regenerate valid TypeScript contract files.
• Ensure all decorators and metadata are correctly mapped in JSON format.
• Validate the JSON structure before parsing it into a contract.
• Support for schema versioning (to ensure backward compatibility).

---

🛠 JSON Schema for Contracts

• Define JSON format for contracts, including:

  • General contract metadata (name, type, controller, etc.).
  • Fields with decorators & validation rules.
  • Index definitions.
  • Linked relationships.
  • Service and message definitions (for RPC integration).
  • Options for database persistence & timestamps.

• Ensure JSON format is extendable for future use cases.

---

🖥️ Integration with @cmmv/admin

• Visual contract editor in @cmmv/admin:

  • Drag-and-drop field creation.
  • Property editing UI for metadata and validation rules.
  • Schema visualization (tree-based or table-based view).
  • Real-time contract preview.

• Ability to modify contracts visually and export as TypeScript.

• Ensure compatibility with form-editing components in @cmmv/ui.

---

📦 File Handling & Storage

• Store JSON contracts in a structured format (contracts/ directory).
• Enable version control for JSON contracts.
• Support importing/exporting contracts in @cmmv/admin.

---

🔮 Future Enhancements

• Live contract updates (hot-reloading of contract changes).
• SDK generation from JSON contracts (for frontend/backend clients).
• Multi-language contract export (e.g., TypeScript, Python, Go).

---

📅 Development Roadmap

• Phase 1: JSON Export/Import system
• Phase 2: @cmmv/admin UI integration
• Phase 3: Transpiler validation & module synchronization
• Phase 4: Advanced features (real-time updates, multi-language support)

---

💡 Contributions & Feedback

Have ideas? Want to contribute? Feel free to open a discussion or pull request! 🚀