mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-25 22:34:56 +00:00
414 lines
9.6 KiB
Markdown
414 lines
9.6 KiB
Markdown
# JSON Script Modules & Import/Export System
|
|
|
|
## Overview
|
|
|
|
JSON scripts support modular organization through:
|
|
1. **Multiple script files** - Split code into logical modules
|
|
2. **Import/Export** - Share functions and constants between modules
|
|
3. **Metadata configuration** - Define which scripts belong to a package
|
|
|
|
## Package Structure
|
|
|
|
```
|
|
json_script_example/
|
|
├── seed/
|
|
│ ├── metadata.json # Package configuration
|
|
│ ├── script.json # Main script (examples)
|
|
│ ├── math_utils.json # Math utility module
|
|
│ ├── validation.json # Validation module
|
|
│ └── combined_example.json # Uses imports from other modules
|
|
```
|
|
|
|
## 1. Configuring Multiple Scripts
|
|
|
|
In `metadata.json`:
|
|
|
|
```json
|
|
{
|
|
"runtime": {
|
|
"scripts": [
|
|
"seed/script.json", // Main script
|
|
"seed/math_utils.json", // Math utilities
|
|
"seed/validation.json" // Validation utilities
|
|
],
|
|
"main": "seed/script.json",
|
|
"executor": {
|
|
"lua": "../shared/seed/scripts/runtime/script_executor.lua",
|
|
"javascript": "../shared/seed/scripts/runtime/script_executor.cjs"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
- **`scripts`** - Array of all script files in the package
|
|
- **`main`** - Entry point script (default for execution)
|
|
- **`executor`** - Runtime executors for different platforms
|
|
|
|
## 2. Exporting from a Module
|
|
|
|
### `math_utils.json` - Exporting Functions and Constants
|
|
|
|
```json
|
|
{
|
|
"schema_version": "2.1.0",
|
|
"package": "json_script_example",
|
|
|
|
"exports": {
|
|
"functions": ["add", "multiply", "clamp"],
|
|
"constants": ["PI", "E"]
|
|
},
|
|
|
|
"constants": [
|
|
{
|
|
"id": "pi_const",
|
|
"name": "PI",
|
|
"value": 3.14159265359,
|
|
"exported": true
|
|
}
|
|
],
|
|
|
|
"functions": [
|
|
{
|
|
"id": "add_fn",
|
|
"name": "add",
|
|
"exported": true,
|
|
"params": [
|
|
{"name": "a", "type": "number"},
|
|
{"name": "b", "type": "number"}
|
|
],
|
|
"body": [
|
|
{
|
|
"type": "return",
|
|
"value": {
|
|
"type": "binary_expression",
|
|
"left": "$ref:params.a",
|
|
"operator": "+",
|
|
"right": "$ref:params.b"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Key Points**:
|
|
- ✅ Set `"exported": true` on functions/constants you want to share
|
|
- ✅ List exported items in `exports` object
|
|
- ✅ Use clear, descriptive names (will be imported by name)
|
|
|
|
## 3. Importing into Another Module
|
|
|
|
### `combined_example.json` - Using Imports
|
|
|
|
```json
|
|
{
|
|
"schema_version": "2.1.0",
|
|
"package": "json_script_example",
|
|
|
|
"imports": [
|
|
{
|
|
"from": "math_utils",
|
|
"import": ["add", "multiply", "clamp", "PI"]
|
|
},
|
|
{
|
|
"from": "validation",
|
|
"import": ["validateRange", "isNotEmpty"]
|
|
}
|
|
],
|
|
|
|
"functions": [
|
|
{
|
|
"name": "calculateArea",
|
|
"params": [
|
|
{"name": "width", "type": "number"},
|
|
{"name": "height", "type": "number"}
|
|
],
|
|
"body": [
|
|
{
|
|
"type": "const_declaration",
|
|
"name": "area",
|
|
"value": {
|
|
"type": "call_expression",
|
|
"callee": "$ref:imports.math_utils.multiply",
|
|
"args": ["$ref:params.width", "$ref:params.height"]
|
|
}
|
|
},
|
|
{
|
|
"type": "return",
|
|
"value": {
|
|
"type": "call_expression",
|
|
"callee": "$ref:imports.math_utils.clamp",
|
|
"args": ["$ref:local.area", 0, 1000]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Import Syntax**:
|
|
- `from` - Name of the module (file name without `.json`)
|
|
- `import` - Array of function/constant names to import
|
|
|
|
**Usage**:
|
|
- Access via `$ref:imports.module_name.function_name`
|
|
- Example: `$ref:imports.math_utils.multiply`
|
|
|
|
## 4. Import/Export Patterns
|
|
|
|
### Pattern 1: Utility Module
|
|
|
|
**math_utils.json** - Pure utility functions
|
|
```json
|
|
{
|
|
"exports": {
|
|
"functions": ["add", "subtract", "multiply", "divide"]
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage in other modules**:
|
|
```json
|
|
{
|
|
"imports": [{"from": "math_utils", "import": ["add", "multiply"]}],
|
|
"functions": [{
|
|
"body": [
|
|
{
|
|
"type": "call_expression",
|
|
"callee": "$ref:imports.math_utils.add",
|
|
"args": [5, 3]
|
|
}
|
|
]
|
|
}]
|
|
}
|
|
```
|
|
|
|
### Pattern 2: Constants Module
|
|
|
|
**constants.json** - Shared configuration
|
|
```json
|
|
{
|
|
"exports": {
|
|
"constants": ["API_URL", "MAX_RETRIES", "TIMEOUT"]
|
|
},
|
|
"constants": [
|
|
{"name": "API_URL", "value": "https://api.example.com", "exported": true},
|
|
{"name": "MAX_RETRIES", "value": 3, "exported": true},
|
|
{"name": "TIMEOUT", "value": 5000, "exported": true}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Usage**:
|
|
```json
|
|
{
|
|
"imports": [{"from": "constants", "import": ["API_URL", "TIMEOUT"]}],
|
|
"functions": [{
|
|
"body": [
|
|
{
|
|
"type": "const_declaration",
|
|
"name": "url",
|
|
"value": "$ref:imports.constants.API_URL"
|
|
}
|
|
]
|
|
}]
|
|
}
|
|
```
|
|
|
|
### Pattern 3: Feature Module
|
|
|
|
**user_auth.json** - Related functionality grouped together
|
|
```json
|
|
{
|
|
"exports": {
|
|
"functions": ["login", "logout", "checkAuth", "refreshToken"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Pattern 4: Type Definitions
|
|
|
|
**types.json** - Shared type constants and validators
|
|
```json
|
|
{
|
|
"exports": {
|
|
"constants": ["USER_ROLES", "PERMISSION_LEVELS"],
|
|
"functions": ["isValidRole", "hasPermission"]
|
|
}
|
|
}
|
|
```
|
|
|
|
## 5. Module Resolution
|
|
|
|
### Intra-Package Imports
|
|
|
|
Import from modules in the same package:
|
|
|
|
```json
|
|
{
|
|
"imports": [
|
|
{"from": "math_utils", "import": ["add"]}
|
|
]
|
|
}
|
|
```
|
|
|
|
Resolves to: `<package>/seed/math_utils.json`
|
|
|
|
### Cross-Package Imports (Future)
|
|
|
|
Import from other packages:
|
|
|
|
```json
|
|
{
|
|
"imports": [
|
|
{
|
|
"from": "@shared/permissions",
|
|
"import": ["check_access"]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Resolves to: `packages/shared/seed/permissions.json`
|
|
|
|
## 6. Execution Context
|
|
|
|
When a function is called from an imported module, the runtime:
|
|
|
|
1. Loads all script files defined in `metadata.json`
|
|
2. Builds import map based on `imports` declarations
|
|
3. Resolves `$ref:imports.module.function` references
|
|
4. Executes the function in the imported module's context
|
|
|
|
```javascript
|
|
const { executeFunction } = require('./script_executor.cjs');
|
|
|
|
// Load all modules
|
|
const modules = {
|
|
main: JSON.parse(fs.readFileSync('seed/script.json')),
|
|
math_utils: JSON.parse(fs.readFileSync('seed/math_utils.json')),
|
|
validation: JSON.parse(fs.readFileSync('seed/validation.json'))
|
|
};
|
|
|
|
// Execute function from main, which imports from other modules
|
|
const result = executeFunction(modules.main, 'myFunction', [args]);
|
|
```
|
|
|
|
## 7. Best Practices
|
|
|
|
### ✅ DO
|
|
|
|
- **Group related functions** - Keep related functionality in the same module
|
|
- **Use clear names** - Module and function names should be descriptive
|
|
- **Export intentionally** - Only export what others need to use
|
|
- **Document exports** - Add descriptions to exported functions
|
|
- **Keep modules focused** - Each module should have a single responsibility
|
|
|
|
### ❌ DON'T
|
|
|
|
- **Circular imports** - Avoid Module A importing Module B which imports Module A
|
|
- **Too many imports** - If you need to import 10+ items, consider refactoring
|
|
- **Deep nesting** - Keep module hierarchy flat (2-3 levels max)
|
|
- **Implicit dependencies** - Always declare imports explicitly
|
|
|
|
## 8. Example: Form Validation System
|
|
|
|
### Structure
|
|
|
|
```
|
|
packages/form_builder/seed/
|
|
├── validation/
|
|
│ ├── rules.json # Validation rule functions
|
|
│ ├── formatters.json # Input formatters
|
|
│ └── messages.json # Error message constants
|
|
├── forms/
|
|
│ ├── contact_form.json # Contact form logic
|
|
│ └── user_form.json # User registration form logic
|
|
└── metadata.json # Lists all modules
|
|
```
|
|
|
|
### metadata.json
|
|
|
|
```json
|
|
{
|
|
"runtime": {
|
|
"scripts": [
|
|
"seed/validation/rules.json",
|
|
"seed/validation/formatters.json",
|
|
"seed/validation/messages.json",
|
|
"seed/forms/contact_form.json",
|
|
"seed/forms/user_form.json"
|
|
],
|
|
"main": "seed/forms/contact_form.json"
|
|
}
|
|
}
|
|
```
|
|
|
|
### validation/rules.json
|
|
|
|
```json
|
|
{
|
|
"exports": {
|
|
"functions": ["isEmail", "isNotEmpty", "minLength", "maxLength"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### forms/contact_form.json
|
|
|
|
```json
|
|
{
|
|
"imports": [
|
|
{"from": "validation/rules", "import": ["isEmail", "isNotEmpty"]},
|
|
{"from": "validation/messages", "import": ["ERROR_MESSAGES"]}
|
|
],
|
|
|
|
"functions": [{
|
|
"name": "validateContactForm",
|
|
"body": [
|
|
{
|
|
"type": "call_expression",
|
|
"callee": "$ref:imports.validation/rules.isEmail",
|
|
"args": ["$ref:params.email"]
|
|
}
|
|
]
|
|
}]
|
|
}
|
|
```
|
|
|
|
## 9. Runtime Support
|
|
|
|
### Current Status
|
|
|
|
- ✅ Multiple script files in metadata
|
|
- ⏳ Import/export resolution (needs runtime implementation)
|
|
- ⏳ Cross-package imports
|
|
- ⏳ Circular dependency detection
|
|
|
|
### Roadmap
|
|
|
|
1. **Phase 1**: Basic import/export within package
|
|
2. **Phase 2**: Cross-package imports with `@package/module` syntax
|
|
3. **Phase 3**: Tree shaking (only load what's used)
|
|
4. **Phase 4**: Hot module reload (reload changed modules only)
|
|
|
|
## 10. Testing Modular Scripts
|
|
|
|
Test modules independently:
|
|
|
|
```bash
|
|
# Test math_utils module
|
|
node test_cli.cjs math_utils.json math_utils.test.json
|
|
|
|
# Test combined_example (with imports)
|
|
node test_cli.cjs combined_example.json combined.test.json
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [JSON Script Runtime README](../../shared/seed/scripts/runtime/README.md)
|
|
- [Testing Guide](tests/README.md)
|
|
- [Package README](README.md)
|