index Logic Documentation

Overview

The "index" logic block is responsible for dynamically loading other logic blocks from the /logic/ directory in Vantage. This facility allows for modular addition of functionalities, enabling users to maintain scalability and flexibility within their analytics and data processes.

Purpose

The primary goal of this logic is to enhance the modular architecture of the Vantage platform by allowing logic blocks like analytics functions to be imported and executed dynamically at runtime based on specified paths. This means users can extend their data processing capabilities without having to directly modify core system files or code.

Function Signature

export async function loadBlockFunction(path, input = {}, context = {})

Parameters

• path (string): This is the path to the logic function file that needs to be loaded, relative to the /logic/ directory.
• input (object): Optional parameter that accepts an object containing input data for the loaded function.
• context (object): Optional parameter that provides runtime context, potentially useful for logging or state management.

Expected Data

The function expects:

• path: A valid string representing the relative path to the function within the /logic/ directory.
• input: An object that may vary in structure depending on the specific logic block being loaded.
• context: An object that conveys pertinent runtime context information, such as user data or session details.

Settings

While the function does not explicitly define settings in its structure, it is influenced by the following principles and protections within its implementation:

1. path:

   • Input Type: String
   • Description: The path to the desired logic function file. This must conform to specific safety checks to prevent exploitation (e.g., path traversal attacks).
   • Compliance: Changing the path impacts which logic block is loaded. Providing an incorrect path will result in an error.
   • Default Value: N/A (must be provided during the function call).

2. input:

   • Input Type: Object
   • Description: An object that may contain any necessary data the loaded logic block requires to execute successfully.
   • Compliance: Changing this object modifies the input data that the dynamically loaded function receives. Defaults to an empty object if not provided.
   • Default Value: {} (an empty object).

3. context:

   • Input Type: Object
   • Description: Contains contextual information relevant to the execution environment. This may include user-specific data or stateful information necessary for logic execution.
   • Compliance: Changes to this object can impact how the loaded function behaves or interacts with the system. Defaults to an empty object if not provided.
   • Default Value: {} (an empty object).

How It Works

The loadBlockFunction function performs the following steps:

1. Validates that the path is a string.
2. Conducts a path safety check to ensure no directory traversal or unsafe path access is attempted.
3. Dynamically imports the specified logic block module using ECMAScript Modules syntax.
4. Checks if the loaded module exports a default function; if not, it raises an error.
5. Returns the loaded function for further execution, passing along any input and context provided.

Error Handling

The function implements robust error handling:

• Throws an error if the path is not a valid string.
• Throws an error for unsafe paths that could lead to security vulnerabilities.
• Logs an error to the console and throws a new error if the dynamic import fails or does not yield a valid function.

Use Cases & Examples

Use Cases

1. Dynamic Analytics Reporting: Load different analytics logic blocks as needed based on user selection. This allows users to create customized reporting experiences without hard coding the function calls.
2. Modular Feature Extensions: New logic functions can be added without altering the core system; developers can write plugins that are loaded dynamically by referencing new paths.
3. User-Centric Data Processing: Depending on user access levels or special parameters, different data processing functions can be loaded, giving tailored experiences to different users or roles.

Example Configuration

Use Case: Dynamic Analytics Reporting

Scenario: A user wants to generate reports based on selected data sources for a financial audit, and the report logic is implemented as separate modules.

Sample Configuration:

const path = "blocks/quickbooks/netRevenue"; 
const input = {
    userId: "user123",
    sessionToken: "abcde12345",
    dateRange: {
        start: "2023-01-01",
        end: "2023-01-31"
    }
};
const context = {
    userRole: "auditor",
    companyId: "companyXYZ"
};

const loadAnalytics = async () => {
    try {
        const revenueFunction = await loadBlockFunction(path, input, context);
        const result = await revenueFunction(input); // Execute the function
        console.log(result);
    } catch (error) {
        console.error("Error loading analytics function:", error);
    }
};

loadAnalytics();

In this example, the appropriate revenue generating function is loaded dynamically based on the specified path, and it receives tailored input and context that could affect how it processes data and returns results.