change PrepareContext to AddDataToContext, and update the interface for sending data through to the data.Provider

Author: robbyt

README.md

@@ -106,7 +106,7 @@ evaluator, _ := polyscript.FromRisorString(script, logHandler)
 
 ctx := context.Background()
 runtimeData := map[string]any{"name": "Billie Jean", "relationship": false}
-enrichedCtx, _ := evaluator.PrepareContext(ctx, runtimeData)
+enrichedCtx, _ := evaluator.AddDataToContext(ctx, runtimeData)
 
 // Execute with the "enriched" context containing the link to the input data
 result, _ := evaluator.Eval(enrichedCtx)
@@ -127,14 +127,14 @@ evaluator, _ := polyscript.FromRisorStringWithData(script, staticData, logHandle
 
 // For each request, prepare dynamic data
 requestData := map[string]any{"userId": 123}
-enrichedCtx, _ := evaluator.PrepareContext(context.Background(), requestData)
+enrichedCtx, _ := evaluator.AddDataToContext(context.Background(), requestData)
 
 // Execute with both static and dynamic data available
 result, _ := evaluator.Eval(enrichedCtx)
 
-// In scripts, data can be accessed from both locations:
-// appName := ctx["appName"]  // Static data: "MyApp"
-// userId := ctx["input_data"]["userId"]  // Dynamic data: 123
+// In scripts, all data is accessed from the context:
+// appName := ctx["appName"]    // From static data: "MyApp"
+// userId := ctx["userId"]      // From dynamic data: 123
 ```
 
 ## Architecture
@@ -151,11 +151,13 @@ go-polyscript is structured around a few key concepts:
 
 ### Note on Data Access Patterns
 
-go-polyscript uses a unified `Provider` interface to supply data to scripts. The library has standardized on storing dynamic runtime data under the `input_data` key (previously `script_data`). For maximum compatibility, scripts should handle two data access patterns:
+go-polyscript uses a two-layer approach for handling data:
 
-1. Top-level access for static data: `ctx["config_value"]`
-2. Nested access for dynamic data: `ctx["input_data"]["user_data"]`
-3. HTTP request data access: `ctx["input_data"]["request"]["method"]` (request objects are always stored under input_data)
+1. **Data Provider Layer**: The `Provider` interface (via `AddDataToContext`) handles storage mechanisms and general type conversions. This layer is pluggable, allowing data to be stored in various backends while maintaining a consistent API.
+
+2. **Engine-Specific Layer**: Each engine's `Evaluator` implementation handles the engine-specific conversions between the stored data and the format required by that particular scripting engine.
+
+This separation allows scripts to access data with consistent patterns regardless of the storage mechanism or script engine. For example, data you store with `{"config": value}` will be accessible in your scripts as `ctx["config"]`, with each engine handling the specific conversions needed for its runtime.
 
 See the [Data Providers](#working-with-data-providers) section for more details.
 

engines/README.md

@@ -32,12 +32,12 @@ This package contains virtual machine implementations for executing scripts in v
 
 4. **Data Preparation Stage**
    - This phase is optional, and must happen prior to evaluation when runtime input data is used
-   - The `Evaluator` implements the `evaluationEvaluator` interface, which has a `PrepareContext` method
-   - The `PrepareContext` method takes a `context.Context` and a variadic list of `any`
-   - `PrepareContext` calls the `data.Provider` to convert and store the data, somewhere accessible to the Evaluator
+   - The `Evaluator` implements the `data.Setter` interface, which has an `AddDataToContext` method
+   - The `AddDataToContext` method takes a `context.Context` and a variadic list of `map[string]any`
+   - `AddDataToContext` calls the `data.Provider` to store the data, somewhere accessible to the Evaluator
    - The conversion is fairly opinionated, and handled by the `data.Provider`
    - For example, it converts an `http.Request` into a `map[string]any` using the schema in `helper.RequestToMap`
-   - The `PrepareContext` method returns a new context with the data stored or linked in it
+   - The `AddDataToContext` method returns a new context with the data stored or linked in it
 
 5. **Execution Stage**
    - When `Eval(ctx)` is called, the `data.Provider` first loads the input data into the VM

engines/TESTING.md

@@ -36,7 +36,7 @@ This document outlines standardized testing principles for go-polyscript to ensu
 | Options             | `TestCompilerOptions`      |
 | Executables         | `TestExecutable`           |
 | Evaluator execution | `TestEvaluator_Evaluate`   |
-| Context preparation | `TestEvaluator_PrepareContext` |
+| Context preparation | `TestEvaluator_AddDataToContext` |
 | Response handling   | `TestResponseMethods`      |
 | Type conversion     | `TestToGoType` / `TestToMachineType` |
 

engines/benchmarks/README.md

@@ -24,7 +24,7 @@ For distributed architectures, separate data preparation from evaluation to impr
 
 ```go
 // PREPARE DATA (can happen on system A)
-enrichedCtx, _ := evaluator.PrepareContext(ctx, inputData)
+enrichedCtx, _ := evaluator.AddDataToContext(ctx, inputData)
 
 // EVALUATE (can happen on system B)
 result, _ := evaluator.Eval(enrichedCtx)

engines/benchmarks/benchmark_test.go

@@ -166,9 +166,9 @@ func BenchmarkDataProviders(b *testing.B) {
 
 	b.Run("CompositeProvider", func(b *testing.B) {
 		// For CompositeProvider use case, we can prepare the context separately
-		// We need a special script that accesses the name via input_data
+		// We access the name directly from the context
 		compositeScript := `
-			name := ctx["input_data"]["name"]
+			name := ctx["name"]
 			message := "Hello, " + name + "!"
 			{
 				"greeting": message,
@@ -186,8 +186,8 @@ func BenchmarkDataProviders(b *testing.B) {
 		}
 
 		ctx := context.Background()
-		// Use PrepareContext to add the dynamic part
-		ctx, err = evaluator.PrepareContext(ctx, inputData)
+		// Use AddDataToContext to add the dynamic part
+		ctx, err = evaluator.AddDataToContext(ctx, map[string]any{"name": "World"})
 		if err != nil {
 			b.Fatalf("Failed to prepare context: %v", err)
 		}

engines/extism/evaluator/evaluator.go

@@ -208,21 +208,21 @@ func (be *Evaluator) Eval(ctx context.Context) (platform.EvaluatorResponse, erro
 	return result, nil
 }
 
-// PrepareContext implements the EvalDataPreparer interface for Extism WebAssembly modules.
+// AddDataToContext implements the data.Setter interface for Extism WebAssembly modules.
 // It enriches the provided context with data for script evaluation, using the
 // ExecutableUnit's DataProvider to store the data.
-func (be *Evaluator) PrepareContext(
+func (be *Evaluator) AddDataToContext(
 	ctx context.Context,
-	d ...any,
+	d ...map[string]any,
 ) (context.Context, error) {
-	logger := be.logger.WithGroup("PrepareContext")
+	logger := be.logger.WithGroup("AddDataToContext")
 
 	// Use the shared helper function for context preparation
 	if be.execUnit == nil || be.execUnit.GetDataProvider() == nil {
 		return ctx, fmt.Errorf("no data provider available")
 	}
 
-	return data.PrepareContextHelper(
+	return data.AddDataToContextHelper(
 		ctx,
 		logger,
 		be.execUnit.GetDataProvider(),

engines/extism/evaluator/evaluator_test.go

@@ -61,7 +61,7 @@ func (m *mockErrProvider) GetData(ctx context.Context) (map[string]any, error) {
 
 func (m *mockErrProvider) AddDataToContext(
 	ctx context.Context,
-	data ...any,
+	data ...map[string]any,
 ) (context.Context, error) {
 	return ctx, m.err
 }
@@ -607,14 +607,14 @@ func TestEvaluator_Evaluate(t *testing.T) {
 	})
 }
 
-// TestEvaluator_PrepareContext tests the PrepareContext method with various scenarios
-func TestEvaluator_PrepareContext(t *testing.T) {
+// TestEvaluator_AddDataToContext tests the AddDataToContext method with various scenarios
+func TestEvaluator_AddDataToContext(t *testing.T) {
 	t.Parallel()
 
 	tests := []struct {
 		name        string
 		setupExe    func(t *testing.T) *script.ExecutableUnit
-		inputs      []any
+		inputs      []map[string]any
 		wantError   bool
 		expectedErr string
 	}{
@@ -633,7 +633,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 					Content:      content,
 				}
 			},
-			inputs:      []any{map[string]any{"test": "data"}},
+			inputs:      []map[string]any{{"test": "data"}},
 			wantError:   true,
 			expectedErr: "no data provider available",
 		},
@@ -652,7 +652,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 					Content:      content,
 				}
 			},
-			inputs:    []any{map[string]any{"test": "data"}},
+			inputs:    []map[string]any{{"test": "data"}},
 			wantError: false,
 		},
 		{
@@ -670,7 +670,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 					Content:      content,
 				}
 			},
-			inputs:    []any{},
+			inputs:    []map[string]any{{}},
 			wantError: false,
 		},
 		{
@@ -679,7 +679,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 				t.Helper()
 				return nil
 			},
-			inputs:      []any{map[string]any{"test": "data"}},
+			inputs:      []map[string]any{{"test": "data"}},
 			wantError:   true,
 			expectedErr: "no data provider available",
 		},
@@ -701,7 +701,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 					Content:      content,
 				}
 			},
-			inputs:      []any{map[string]any{"test": "data"}},
+			inputs:      []map[string]any{{"test": "data"}},
 			wantError:   true,
 			expectedErr: "provider error",
 		},
@@ -714,7 +714,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 			evaluator := New(handler, exe)
 
 			ctx := context.Background()
-			enrichedCtx, err := evaluator.PrepareContext(ctx, tt.inputs...)
+			enrichedCtx, err := evaluator.AddDataToContext(ctx, tt.inputs...)
 
 			// Check error expectations
 			if tt.wantError {

engines/extism/new.go

@@ -34,7 +34,7 @@ func FromExtismLoader(
 }
 
 // FromExtismLoaderWithData creates an Extism evaluator with both static and dynamic data capabilities.
-// To add runtime data, use the `PrepareContext` method on the evaluator to add data to the context.
+// To add runtime data, use the `AddDataToContext` method on the evaluator to add data to the context.
 //
 // Input parameters:
 // - l: loader implementation for loading the WASM content

engines/mocks/evaluator.go

@@ -31,8 +31,11 @@ func (m *Evaluator) Load(newVersion script.ExecutableUnit) error {
 	return args.Error(0)
 }
 
-// PrepareContext is a mock implementation of the PrepareContext method.
-func (m *Evaluator) PrepareContext(ctx context.Context, d ...any) (context.Context, error) {
+// AddDataToContext is a mock implementation of the AddDataToContext method.
+func (m *Evaluator) AddDataToContext(
+	ctx context.Context,
+	d ...map[string]any,
+) (context.Context, error) {
 	args := m.Called(ctx, d)
 	return args.Get(0).(context.Context), args.Error(1)
 }

engines/risor/evaluator/evaluator.go

@@ -155,21 +155,21 @@ func (be *Evaluator) Eval(ctx context.Context) (platform.EvaluatorResponse, erro
 	return result, nil
 }
 
-// PrepareContext implements the EvalDataPreparer interface for Risor scripts.
+// AddDataToContext implements the data.Setter interface for Risor scripts.
 // It enriches the provided context with data for script evaluation, using the
 // ExecutableUnit's DataProvider to store the data.
-func (be *Evaluator) PrepareContext(
+func (be *Evaluator) AddDataToContext(
 	ctx context.Context,
-	d ...any,
+	d ...map[string]any,
 ) (context.Context, error) {
-	logger := be.logger.WithGroup("PrepareContext")
+	logger := be.logger.WithGroup("AddDataToContext")
 
 	// Use the shared helper function for context preparation
 	if be.execUnit == nil || be.execUnit.GetDataProvider() == nil {
 		return ctx, fmt.Errorf("no data provider available")
 	}
 
-	return data.PrepareContextHelper(
+	return data.AddDataToContextHelper(
 		ctx,
 		logger,
 		be.execUnit.GetDataProvider(),

engines/risor/evaluator/evaluator_test.go

@@ -36,7 +36,10 @@ func (m *MockProvider) GetData(ctx context.Context) (map[string]any, error) {
 	return nil, args.Error(1)
 }
 
-func (m *MockProvider) AddDataToContext(ctx context.Context, data ...any) (context.Context, error) {
+func (m *MockProvider) AddDataToContext(
+	ctx context.Context,
+	data ...map[string]any,
+) (context.Context, error) {
 	args := m.Called(ctx, data)
 	if ctx, ok := args.Get(0).(context.Context); ok {
 		return ctx, args.Error(1)
@@ -170,7 +173,6 @@ func TestEvaluator_Evaluate(t *testing.T) {
 
 		for _, tt := range tests {
 			t.Run(tt.name, func(t *testing.T) {
-				// Set up the environment
 				handler := slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
 					Level: slog.LevelDebug,
 				})
@@ -194,7 +196,7 @@ func TestEvaluator_Evaluate(t *testing.T) {
 
 				// Create the context with eval data
 				evalData := map[string]any{
-					constants.Request: rMap,
+					"request": rMap,
 				}
 				ctx := context.WithValue(context.Background(), constants.EvalData, evalData)
 
@@ -456,15 +458,14 @@ func TestEvaluator_Evaluate(t *testing.T) {
 	})
 }
 
-// TestEvaluator_PrepareContext tests the PrepareContext method with various scenarios
-func TestEvaluator_PrepareContext(t *testing.T) {
+func TestEvaluator_AddDataToContext(t *testing.T) {
 	t.Parallel()
 
 	// The test cases
 	tests := []struct {
 		name         string
 		setupExe     func(t *testing.T) *script.ExecutableUnit
-		inputs       []any
+		inputs       []map[string]any
 		wantError    bool
 		errorMessage string
 	}{
@@ -484,7 +485,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 
 				return &script.ExecutableUnit{DataProvider: mockProvider}
 			},
-			inputs:    []any{map[string]any{"test": "data"}},
+			inputs:    []map[string]any{{"test": "data"}},
 			wantError: false,
 		},
 		{
@@ -499,7 +500,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 
 				return &script.ExecutableUnit{DataProvider: mockProvider}
 			},
-			inputs:       []any{map[string]any{"test": "data"}},
+			inputs:       []map[string]any{{"test": "data"}},
 			wantError:    true,
 			errorMessage: "provider error",
 		},
@@ -509,7 +510,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 				t.Helper()
 				return &script.ExecutableUnit{DataProvider: nil}
 			},
-			inputs:       []any{map[string]any{"test": "data"}},
+			inputs:       []map[string]any{{"test": "data"}},
 			wantError:    true,
 			errorMessage: "no data provider available",
 		},
@@ -519,7 +520,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 				t.Helper()
 				return nil
 			},
-			inputs:       []any{map[string]any{"test": "data"}},
+			inputs:       []map[string]any{{"test": "data"}},
 			wantError:    true,
 			errorMessage: "no data provider available",
 		},
@@ -539,7 +540,7 @@ func TestEvaluator_PrepareContext(t *testing.T) {
 			}
 
 			ctx := context.Background()
-			result, err := evaluator.PrepareContext(ctx, tt.inputs...)
+			result, err := evaluator.AddDataToContext(ctx, tt.inputs...)
 
 			if tt.wantError {
 				require.Error(t, err)

engines/risor/new.go

@@ -31,7 +31,7 @@ func FromRisorLoader(
 }
 
 // FromRisorLoaderWithData creates a Risor evaluator with both static and dynamic data capabilities.
-// To add runtime data, use the `PrepareContext` method on the evaluator to add data to the context.
+// To add runtime data, use the `AddDataToContext` method on the evaluator to add data to the context.
 //
 // Input parameters:
 // - logHandler: logger handler for logging

engines/starlark/evaluator/evaluator.go

@@ -222,21 +222,21 @@ func (be *Evaluator) Eval(ctx context.Context) (platform.EvaluatorResponse, erro
 	return result, nil
 }
 
-// PrepareContext implements the EvalDataPreparer interface for Starlark scripts.
+// AddDataToContext implements the data.Setter interface for Starlark scripts.
 // It enriches the provided context with data for script evaluation, using the
 // ExecutableUnit's DataProvider to store the data.
-func (be *Evaluator) PrepareContext(
+func (be *Evaluator) AddDataToContext(
 	ctx context.Context,
-	d ...any,
+	d ...map[string]any,
 ) (context.Context, error) {
-	logger := be.logger.WithGroup("PrepareContext")
+	logger := be.logger.WithGroup("AddDataToContext")
 
 	// Use the shared helper function for context preparation
 	if be.execUnit == nil || be.execUnit.GetDataProvider() == nil {
 		return ctx, fmt.Errorf("no data provider available")
 	}
 
-	return data.PrepareContextHelper(
+	return data.AddDataToContextHelper(
 		ctx,
 		logger,
 		be.execUnit.GetDataProvider(),