diff options
Diffstat (limited to 'js/scripting-lang/tutorials/15_Integration_Patterns.md')
| -rw-r--r-- | js/scripting-lang/tutorials/15_Integration_Patterns.md | 386 |
1 files changed, 386 insertions, 0 deletions
diff --git a/js/scripting-lang/tutorials/15_Integration_Patterns.md b/js/scripting-lang/tutorials/15_Integration_Patterns.md new file mode 100644 index 0000000..72e31ca --- /dev/null +++ b/js/scripting-lang/tutorials/15_Integration_Patterns.md @@ -0,0 +1,386 @@ +# Integration Patterns + +## What are Integration Patterns? + +Integration patterns show how to connect Baba Yaga programs with external systems, APIs, and other services while maintaining functional purity through the `..emit` and `..listen` pattern. + +## Basic Integration Concepts + +### Emit and Listen Pattern +```plaintext +/* Emit events to external systems */ +..emit "user_created" {id: 123, name: "Alice"}; +..emit "data_processed" {count: 42, success: true}; + +/* Listen for external events */ +..listen "user_created" handle_user_created; +..listen "data_processed" handle_data_processed; +``` + +### State Management +```plaintext +/* Get current state from external system */ +current_state : ..listen; + +/* Process based on state */ +user_id : current_state.user_id; +user_data : current_state.user_data; + +/* Emit processed result */ +..emit "user_processed" { + id: user_id, + processed_data: transform user_data +}; +``` + +## API Integration + +### HTTP Request Pattern +```plaintext +/* Emit HTTP requests */ +..emit { + action: "http_request", + method: "GET", + url: "https://api.example.com/users/123" +}; + +/* Emit POST request with data */ +..emit { + action: "http_request", + method: "POST", + url: "https://api.example.com/users", + data: {name: "Alice", email: "alice@example.com"} +}; +``` + +### API Response Handling +```plaintext +/* Listen for API responses */ +..listen "api_response" handle_api_response; + +handle_api_response : response -> + when response.success is + true then + ..out "API call successful:"; + ..out response.data + false then + ..out "API call failed:"; + ..out response.error; +``` + +## Database Integration + +### Database Operations +```plaintext +/* Emit database queries */ +..emit { + action: "db_query", + type: "select", + table: "users", + where: {id: 123} +}; + +/* Emit insert operation */ +..emit { + action: "db_query", + type: "insert", + table: "users", + data: {name: "Bob", email: "bob@example.com"} +}; +``` + +### Database Response Processing +```plaintext +/* Process database results */ +..listen "db_result" handle_db_result; + +handle_db_result : result -> + when result.type = "select" then + users : result.data; + processed_users : map @format_user users; + ..out "Found " + t.length users + " users"; + processed_users + _ then result.data; +``` + +## File System Integration + +### File Operations +```plaintext +/* Emit file operations */ +..emit { + action: "file_operation", + type: "read", + path: "/data/users.json" +}; + +/* Emit write operation */ +..emit { + action: "file_operation", + type: "write", + path: "/output/processed.json", + content: processed_data +}; +``` + +### File Processing +```plaintext +/* Process file contents */ +..listen "file_result" handle_file_result; + +handle_file_result : result -> + when result.type = "read" then + data : parse_json result.content; + processed : transform_data data; + processed + _ then result; +``` + +## Event-Driven Architecture + +### Event Processing Pipeline +```plaintext +/* Process incoming events */ +process_event : event -> + when event.type = "user_created" then + user : event.data; + validated_user : validate_user user; + when validated_user.valid is + true then + ..emit "user_validated" validated_user.data; + validated_user.data + false then + ..emit "validation_failed" validated_user.errors; + null + _ then event.data; +``` + +### Event Handlers +```plaintext +/* Register event handlers */ +..listen "user_created" process_event; +..listen "order_placed" process_event; +..listen "payment_received" process_event; +``` + +## External Service Integration + +### Third-Party API Integration +```plaintext +/* Integrate with external service */ +integrate_payment : order -> + payment_data : { + amount: order.total, + currency: "USD", + customer_id: order.customer_id + }; + + ..emit { + action: "external_api", + service: "stripe", + endpoint: "/payments", + method: "POST", + data: payment_data + }; + + payment_data; +``` + +### Service Response Handling +```plaintext +/* Handle external service responses */ +..listen "external_api_response" handle_external_response; + +handle_external_response : response -> + when response.service = "stripe" then + when response.success is + true then + ..emit "payment_successful" response.data; + response.data + false then + ..emit "payment_failed" response.error; + null + _ then response; +``` + +## Real-World Integration Example + +### E-commerce Order Processing +```plaintext +/* Complete order processing pipeline */ +process_order : order -> + /* Step 1: Validate order */ + validation_result : validate_order order; + when validation_result.valid is + false then + ..emit "order_invalid" validation_result.errors; + null + _ then + /* Step 2: Check inventory */ + ..emit { + action: "db_query", + type: "select", + table: "inventory", + where: {product_id: order.product_id} + }; + + /* Step 3: Process payment */ + payment_result : integrate_payment order; + + /* Step 4: Update inventory */ + ..emit { + action: "db_query", + type: "update", + table: "inventory", + where: {product_id: order.product_id}, + data: {quantity: decrement_quantity order.quantity} + }; + + /* Step 5: Send confirmation */ + ..emit { + action: "email", + to: order.customer_email, + subject: "Order Confirmed", + template: "order_confirmation", + data: order + }; + + {order_id: order.id, status: "processed"}; +``` + +## Error Handling in Integration + +### Graceful Degradation +```plaintext +/* Handle integration failures */ +safe_api_call : api_request -> + ..emit api_request; + + /* Set timeout for response */ + timeout_result : wait_for_response 5000; + when timeout_result.timeout is + true then + ..emit "api_timeout" api_request; + {error: "API timeout", fallback: true} + _ then timeout_result.response; +``` + +### Retry Logic +```plaintext +/* Retry failed operations */ +retry_operation : operation max_retries -> + attempt_operation : attempt -> + when attempt > max_retries then + ..emit "max_retries_exceeded" operation; + {error: "Max retries exceeded"} + _ then + result : operation; + when result.error is + true then + delay : power 2 attempt; /* Exponential backoff */ + ..emit "retry_attempt" {attempt: attempt, delay: delay}; + retry_operation operation max_retries + false then result; + + attempt_operation 1; +``` + +## Testing Integration + +### Mock External Services +```plaintext +/* Test integration without real services */ +test_payment_integration : -> + /* Mock order */ + test_order : { + id: "test_123", + total: 100, + customer_id: "cust_456" + }; + + /* Test payment integration */ + result : integrate_payment test_order; + + /* Verify emitted events */ + ..assert "Payment data emitted" result.amount = 100; + ..assert "Payment data emitted" result.currency = "USD"; + + ..out "Payment integration test passed"; +``` + +### Integration Test Patterns +```plaintext +/* Test complete integration flow */ +test_order_flow : -> + /* Test order */ + test_order : { + id: "test_123", + product_id: "prod_789", + quantity: 2, + customer_email: "test@example.com", + total: 50 + }; + + /* Process order */ + result : process_order test_order; + + /* Verify result */ + ..assert "Order processed successfully" result.status = "processed"; + ..assert "Order ID preserved" result.order_id = "test_123"; + + ..out "Order flow test passed"; +``` + +## Best Practices + +### Keep Integration Pure +```plaintext +/* Good: Pure function with explicit side effects */ +process_data : data -> + transformed : transform data; + ..emit "data_processed" transformed; + transformed; + +/* Avoid: Hidden side effects */ +bad_process : data -> + ..emit "processing_started"; /* Hidden side effect */ + transform data; +``` + +### Use Structured Events +```plaintext +/* Good: Structured event data */ +..emit { + type: "user_created", + timestamp: now(), + data: {id: 123, name: "Alice"}, + metadata: {source: "web_form", version: "1.0"} +}; + +/* Avoid: Unstructured events */ +..emit "user_created Alice 123"; /* Hard to parse */ +``` + +### Handle Errors Gracefully +```plaintext +/* Good: Explicit error handling */ +safe_integration : request -> + when request.valid is + false then + ..emit "integration_error" {request: request, error: "Invalid request"}; + null + _ then + result : call_external_service request; + when result.error is + true then + ..emit "service_error" result; + result.fallback_value + false then result.data; +``` + +## Next Steps + +Now that you understand integration patterns, explore: +- [Error Handling](13_Error_Handling.md) for robust error management +- [Advanced Combinators](14_Advanced_Combinators.md) for complex integration patterns +- [Best Practices](16_Best_Practices.md) for writing maintainable code \ No newline at end of file |