@ea-lab/reactive-json-docs 0.3.0 → 0.4.0

package/public/rjbuild/docs/advanced-concepts/data-processors.yaml

@@ -0,0 +1,309 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Data Processors
+
+      Data Processors are a powerful feature in Reactive-JSON that allow you to intercept and modify data received via `fetchData`, `submitData`, and `additionalDataSources`. This enables you to implement data transformation, validation, security filtering, and other data processing logic in a centralized and reusable way.
+
+      ## How Data Processors Work
+
+      When Reactive-JSON receives data from HTTP requests, it automatically passes the data through all registered Data Processors in order. Each processor:
+
+      1. **Examines the request and response context** (URL, method, headers, status, etc.)
+      2. **Receives the current data** being processed
+      3. **Must return the data** - either transformed or unchanged
+      4. **Chains with other processors** (processed data flows to the next processor)
+
+  - type: Markdown
+    content: |
+      ## Basic Structure
+
+      A Data Processor is a function that receives context and data, then **must return** the processed data:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      const myDataProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+          // Check if we want to process this data
+          if (!requestContext.url.includes('/api/users')) {
+              return dataToProcess; // Return unchanged data
+          }
+          
+          // Check response status
+          if (responseContext.status >= 400) {
+              return dataToProcess; // Return unchanged data
+          }
+          
+          // Transform the data
+          const processedData = {
+              ...dataToProcess,
+              timestamp: new Date().toISOString(),
+              source: requestContext.url
+          };
+          
+          return processedData; // Return transformed data
+      };
+
+  - type: Markdown
+    content: |
+      ## Function Parameters
+
+  - type: DefinitionList
+    content:
+      - term: requestContext
+        details:
+          type: Markdown
+          content: |
+            Information about the HTTP request:
+            - `url`: The URL that was called
+            - `method`: HTTP method (GET, POST, etc.)
+            - `headers`: Request headers object
+            - `body`: Request body (for POST, PUT, etc.)
+
+      - term: responseContext
+        details:
+          type: Markdown
+          content: |
+            Information about the HTTP response:
+            - `headers`: Response headers object
+            - `status`: HTTP status code (200, 404, etc.)
+            - `data`: Raw response data
+
+      - term: dataToProcess
+        details:
+          type: Markdown
+          content: |
+            The data currently being processed. This may have been modified by previous Data Processors in the chain.
+
+      - term: originalDataToProcess
+        details:
+          type: Markdown
+          content: |
+            The original data before any processing, useful for comparison or logging.
+
+  - type: Markdown
+    content: |
+      ## Plugin Registration
+
+      Data Processors are registered through the plugin system:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      import { mergeComponentCollections } from "@ea-lab/reactive-json";
+
+      const myPlugins = {
+          element: {
+              // Your custom components
+          },
+          dataProcessor: {
+              "timestamp-processor": { 
+                  callback: timestampProcessor, 
+                  order: 0 
+              },
+              "security-filter": { 
+                  callback: securityProcessor, 
+                  order: 10 
+              }
+          }
+      };
+
+      export const MyReactiveJsonRoot = (props) => {
+          const plugins = mergeComponentCollections([myPlugins]);
+          return <ReactiveJsonRoot {...props} plugins={plugins} />;
+      };
+
+  - type: Markdown
+    content: |
+      ### Plugin Structure
+
+  - type: DefinitionList
+    content:
+      - term: Key
+        details: Unique identifier for the processor.
+      - term: callback
+        details: The processor function.
+      - term:
+          code: order
+          after: "(number)"
+        details: Execution order (lower numbers run first).
+
+  - type: Markdown
+    content: |
+      ## Common Use Cases
+
+      ### Adding Timestamps
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      const timestampProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+          if (typeof dataToProcess !== 'object' || dataToProcess === null) {
+              return dataToProcess; // Return unchanged for non-objects
+          }
+          
+          return {
+              ...dataToProcess,
+              __metadata: {
+                  processedAt: new Date().toISOString(),
+                  sourceUrl: requestContext.url,
+                  responseStatus: responseContext.status
+              }
+          };
+      };
+
+  - type: Markdown
+    content: |
+      ### Security Filtering
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      const securityProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+          // Only filter external API responses
+          if (!requestContext.url.includes('external-api')) {
+              return dataToProcess; // Return unchanged
+          }
+          
+          if (typeof dataToProcess !== 'object' || dataToProcess === null) {
+              return dataToProcess; // Return unchanged for non-objects
+          }
+          
+          // Remove sensitive fields
+          const sensitiveFields = ['password', 'secret', 'apiKey', 'token'];
+          const cleanedData = { ...dataToProcess };
+          
+          sensitiveFields.forEach(field => {
+              if (cleanedData.hasOwnProperty(field)) {
+                  delete cleanedData[field];
+                  console.log(`🔒 Removed sensitive field: ${field}`);
+              }
+          });
+          
+          return cleanedData;
+      };
+
+  - type: Markdown
+    content: |
+      ### Data Format Transformation
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      const dateFormatProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+          if (typeof dataToProcess !== 'object' || dataToProcess === null) {
+              return dataToProcess; // Return unchanged for non-objects
+          }
+          
+          const processedData = { ...dataToProcess };
+          
+          // Convert DD/MM/YYYY dates to YYYY-MM-DD
+          Object.keys(processedData).forEach(key => {
+              if (typeof processedData[key] === 'string' && /^\d{2}\/\d{2}\/\d{4}$/.test(processedData[key])) {
+                  const [day, month, year] = processedData[key].split('/');
+                  processedData[key] = `${year}-${month}-${day}`;
+              }
+          });
+          
+          return processedData;
+      };
+
+  - type: Markdown
+    content: |
+      ## Best Practices
+
+      ### Always Return Data
+      Data Processors **must always return data**. To skip processing, return the original data:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      const myProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+          // Skip processing for certain conditions
+          if (!requestContext.url.includes('/api/')) {
+              return dataToProcess; // Return unchanged
+          }
+          if (responseContext.status >= 400) {
+              return dataToProcess; // Return unchanged
+          }
+          if (typeof dataToProcess !== 'object') {
+              return dataToProcess; // Return unchanged
+          }
+          
+          // Process and return transformed data
+          return { ...dataToProcess, processed: true };
+      };
+
+  - type: Markdown
+    content: |
+      ### Immutable Updates
+      Always clone data before modifying:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      const processedData = { ...dataToProcess }; // Shallow clone
+      // Or for deep cloning, use JSON.parse(JSON.stringify(...)):
+      const processedData = JSON.parse(JSON.stringify(dataToProcess));
+      // Or with lodash:
+      const processedData = _.cloneDeep(dataToProcess);
+
+  - type: Markdown
+    content: |
+      ### Error Handling
+      The system automatically catches errors, but you can add your own:
+
+  - type: SyntaxHighlighter
+    language: javascript
+    content: |
+      const safeProcessor = ({ requestContext, responseContext, dataToProcess, originalDataToProcess }) => {
+          try {
+              // Your processing logic
+              return processedData;
+          } catch (error) {
+              console.error('Processing failed:', error);
+              return dataToProcess; // Return original data on error
+          }
+      };
+
+  - type: Markdown
+    content: |
+      ## RjBuild vs Data Processing
+
+      The system automatically detects whether the response is a complete RjBuild or just data:
+
+      - **Complete RjBuild**: Processors only modify the `data` section
+      - **Data only**: Processors modify the entire response
+
+      This happens automatically based on the `updateOnlyData` parameter in `fetchData`/`submitData`.
+
+      ## Execution Context
+
+      ### With `fetchData`/`submitData`
+
+  - type: SyntaxHighlighter
+    language: yaml
+    content: |
+      - type: button
+        content: "Load User Data"
+        actions:
+          - what: fetchData
+            on: click
+            url: "/api/users/123"
+            refreshAppOnResponse: true
+            updateOnlyData: false # The response is expected to be a complete RjBuild.
+            # When the response is a complete RjBuild, the processors will receive the data only.
+
+  - type: Markdown
+    content: |
+      ### With `additionalDataSources`
+
+  - type: SyntaxHighlighter
+    language: yaml
+    content: |
+      additionalDataSource:
+        - src: "/api/config"
+          path: "~~.config"
+          # Processors will automatically process this data
+
+data:

package/public/rjbuild/docs/advanced-concepts/index.md

@@ -0,0 +1,9 @@
+# Advanced Concepts
+
+This section covers advanced features and concepts in Reactive-JSON that enable more sophisticated data processing and application behavior.
+
+## Topics
+
+- **[Data Mapping](data-mapping.md)**: Learn how to selectively dispatch and transform response data using the Data Mapping system
+- **[Data Processors](data-processors.md)**: Learn how to intercept and modify data from HTTP requests using the DataProcessor system
+- **[Plugins](plugins/index.md)**: Learn how to extend Reactive-JSON with custom components and plugins.

package/public/rjbuild/docs/advanced-concepts/index.yaml

@@ -0,0 +1,15 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Advanced Concepts
+
+      This section covers advanced features and concepts in Reactive-JSON that enable more sophisticated data processing and application behavior.
+
+      ## Topics
+
+      - **[Data Mapping](data-mapping)**: Learn how to selectively dispatch and transform response data using the Data Mapping system.
+      - **[Data Processors](data-processors)**: Learn how to intercept and modify data from HTTP requests using the DataProcessor system.
+      - **[Plugins](plugins/index)**: Learn how to extend Reactive-JSON with custom components and plugins.
+
+data:
+  page_title: "Advanced Concepts - Reactive-JSON Documentation" 

package/public/rjbuild/docs/{extend → advanced-concepts/plugins}/component-development-guide-llm.md

@@ -277,6 +277,8 @@ export const CustomRoot = (props) => {
 ```js
 {
     action: { /* Action components */ },
+    dataMapping: { /* Data mapping processors */ },
+    dataProcessor: { /* Data processing functions */ },
     element: { /* Element components */ },
     hook: { /* React hooks */ },
     reaction: { /* Reaction functions */ },

package/public/rjbuild/docs/{extend → advanced-concepts/plugins}/plugin-system.md

@@ -12,6 +12,8 @@ A plugin is a JavaScript object that exports components organized by type. The s
 - **action**: Components that perform side effects or modify behavior
 - **reaction**: Event-driven components that respond to user interactions
 - **hook**: React hooks that provide additional functionality
+- **dataProcessor**: Functions that intercept and modify HTTP response data
+- **dataMapping**: Processors that selectively dispatch response data to specific locations
 
 ## Plugin Registration
 

package/public/rjbuild/docs/{extend → advanced-concepts/plugins}/plugin-system.yaml

@@ -15,6 +15,8 @@ renderView:
       - **action**: Components that perform side effects or modify behavior
       - **reaction**: Event-driven components that respond to user interactions
       - **hook**: React hooks that provide additional functionality
+      - **dataProcessor**: Functions that intercept and modify HTTP response data
+      - **dataMapping**: Processors that selectively dispatch response data to specific locations
 
       ## Plugin Registration
 

package/public/rjbuild/docs/core/dataMapping/index.md

@@ -0,0 +1,31 @@
+# Data Mapping Components
+
+Data mapping components process and transform HTTP response data to specific locations in your application state. These components work with `fetchData`, `submitData` reactions, and `additionalDataSources`.
+
+## Core Data Mappers
+
+### SimpleMapping
+The foundational data mapper that provides string-based mappings for selective data dispatch.
+
+- **Purpose**: Map HTTP response fields to application data paths
+- **Configuration**: YAML-based string mappings with destination templates
+- **Features**: Required fields, default values, error handling, update modes
+- **Use Cases**: User profiles, settings, API data transformation
+- **Documentation**: [SimpleMapping Guide](simpleMapping.md) | [Interactive Examples](simpleMapping)
+
+## Architecture
+
+Data mapping processes HTTP response data to selectively dispatch it to application state:
+
+1. **HTTP Request** → Server responds with data
+2. **Data Mapping** → Selectively dispatch response data to application state
+3. **Application State** → Updated with mapped data
+
+## Creating Custom Data Mappers
+
+For information about creating custom data mappers and the broader Data Mapping system architecture, see the [Data Mapping Documentation](../../advanced-concepts/data-mapping).
+
+## Related
+
+- [Data Mapping System](../../advanced-concepts/data-mapping) - System overview and custom mappers
+- [Plugin System](../../advanced-concepts/plugins/plugin-system) - Component architecture 

package/public/rjbuild/docs/core/dataMapping/index.yaml

@@ -0,0 +1,24 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Data Mapping Components
+
+      Data mapping components process and transform HTTP response data to specific locations in your application state. These components work with `fetchData`, `submitData` reactions, and `additionalDataSources`.
+
+      ## Core Data Mappers
+
+      ### [SimpleMapping](simpleMapping)
+      The foundational data mapper that provides string-based mappings for selective data dispatch.
+
+      - **Purpose**: Map HTTP response fields to application data paths
+      - **Configuration**: YAML-based string mappings with destination templates
+      - **Features**: Required fields, default values, error handling, update modes
+      - **Use Cases**: User profiles, settings, API data transformation
+
+      ## Creating Custom Data Mappers
+
+      For information about creating custom data mappers and the broader Data Mapping system architecture, see the **[Data Mapping Documentation](../../advanced-concepts/data-mapping)**.
+
+templates:
+
+data: 

package/public/rjbuild/docs/core/dataMapping/simpleMapping.md

@@ -0,0 +1,131 @@
+# SimpleMapping
+
+SimpleMapping is the core data mapping processor in Reactive-JSON that enables selective dispatch and transformation of HTTP response data to specific locations in your application state. It provides a straightforward, configuration-driven approach to map response fields to application data paths.
+
+## Properties
+
+### stringMap Configuration
+
+- `value` (string, required): Source path in the HTTP response (e.g., `user.firstName`)
+- `required` (boolean, optional, default: true): Whether the source value must exist
+- `defaultValue` (any, optional): Fallback value when source is missing and not required
+- `updateMode` (string, optional, default: "replace"): How to apply the value (`replace`, `add`, `move`, `remove`)
+
+### onErrorMap Configuration
+
+- `value` (string, required): Can be either static values (e.g., `Error occurred`) or template references (e.g., `~~.errorTimestamp`)
+
+## Configuration Structure
+
+The `onErrorMap` works like `stringMap`, but provides fallback values when main mappings fail. Same key-value structure as `stringMap` (destination → configuration). Applied only when corresponding `stringMap` entries fail and are marked as `required: true`.
+
+## Basic Example
+
+```yaml
+- what: fetchData
+  url: "/api/user-profile"
+  updateOnlyData: true
+  dataMapping:
+    simpleMapping:
+      stringMap:
+        "~~.currentUser.name":
+          value: "user.firstName"
+        "~~.currentUser.email":
+          value: "user.email"
+        "~~.settings.theme":
+          value: "user.preferences.theme"
+          required: false
+          defaultValue: "light"
+
+data:
+  currentUser: {}
+  settings: {}
+```
+
+## Error Handling Example
+
+```yaml
+- what: fetchData
+  url: "/api/incomplete-data"
+  updateOnlyData: true
+  dataMapping:
+    simpleMapping:
+      stringMap:
+        "~~.profile.name":
+          value: "user.name"
+          required: true
+        "~~.profile.email":
+          value: "user.email"
+          required: true
+      onErrorMap:
+        "~~.profile.status":
+          value: "Error loading profile"
+        "~~.profile.name":
+          value: "Unknown User"
+        "~~.profile.email":
+          value: "unknown@example.com"
+        "~~.profile.loadedAt":
+          value: "~~.currentTimestamp"
+
+data:
+  profile: {}
+  currentTimestamp: "2024-01-15T10:30:00Z"
+```
+
+## Advanced Configuration
+
+```yaml
+dataMapping:
+  simpleMapping:
+    stringMap:
+      "~~.order.id":
+        value: "order.id"
+      "~~.order.customerName":
+        value: "order.customer.name"
+      "~~.order.customerEmail":
+        value: "order.customer.contact.email"
+      "~~.order.total":
+        value: "order.billing.total"
+      "~~.order.currency":
+        value: "order.billing.currency"
+        required: false
+        defaultValue: "USD"
+```
+
+## Integration with additionalDataSources
+
+```yaml
+additionalDataSource:
+  - src: "/api/user-profile"
+    blocking: true
+    dataMapping:
+      simpleMapping:
+        stringMap:
+          "~~.profile.displayName":
+            value: "user.name"
+          "~~.profile.email":
+            value: "user.email"
+          "~~.settings.theme":
+            value: "user.preferences.theme"
+            required: false
+            defaultValue: "light"
+
+data:
+  profile: {}
+  settings: {}
+```
+
+## Usage Context
+
+SimpleMapping is automatically available as part of the core Reactive-JSON plugins and can be used in:
+
+- **fetchData reactions**: Process API responses selectively
+- **submitData reactions**: Handle server responses after form submissions
+- **additionalDataSources**: Map initial data loading responses
+
+## Related
+
+- [Data Mapping System Overview](../../advanced-concepts/data-mapping) - Complete system architecture and custom mappers
+- [FetchData Reaction](../reaction/fetchData) - HTTP request handling with data mapping
+- [SubmitData Reaction](../reaction/submitData) - Form submission with data mapping
+- [Plugin System](../../advanced-concepts/plugins/plugin-system) - Component architecture