Interface KosExpressionEvaluatorModel<T>

KOS Expression Evaluator Model - Reactive expression evaluation with dynamic context and type-safe named expressions.

This model provides a reactive expression evaluation system that automatically re-evaluates expressions when their context data changes. Perfect for business rules, computed values, and conditional logic that needs to stay synchronized with changing data.

Key Features

  • Automatic reactivity - Expressions re-evaluate when dependencies change thanks to KOS reactive patterns
  • Type safety - Generic type parameter provides compile-time checking for expression names
  • Efficient updates - Only affected expressions recalculate when their data dependencies change
  • Synchronous access - Results available immediately via getters
  • Error handling - Expressions with runtime errors are handled gracefully
  • KOS model integration - Add any KOS model to context for fully reactive expressions

Example: Basic Usage

const evaluator = KosExpressionEvaluatorModel.instance('my-evaluator').build();

evaluator.setContextData({ temperature: 72, humidity: 45 });
evaluator.addExpression('isComfortable', 'temperature >= 68 && temperature <= 78');

console.log(evaluator.results.isComfortable?.value); // true

Use Declared Type

interface KosExpressionEvaluatorModel<T> {
    setContextData(newData): void;
    updateContextValue(key, value): void;
    updateNestedValue(path, value): void;
    addModelToContext(key, model): void;
    addExpression(name, expressionString): void;
    getCachedExpressionValue(name): undefined | ExpressionResult;
    createExpression(expressionString): string;
}

Type Parameters

  • T extends string = string

Methods

setContextData updateContextValue updateNestedValue addModelToContext addExpression getCachedExpressionValue createExpression

Methods

setContextData

  • setContextData(newData): void

  • Replace the entire context data with new values. All expressions will automatically re-evaluate against the new context.

    Parameters

    • newData: Record<string, unknown>

      Complete new context data to replace existing data

    Returns void

    Example

    evaluator.setContextData({ temperature: 75, humidity: 40 });

updateContextValue

  • updateContextValue(key, value): void

  • Update a single value in the context data. All expressions using this value will automatically re-evaluate.

    Parameters

    • key: string

      The context data key to update

    • value: unknown

      The new value to set

    Returns void

    Example

    evaluator.updateContextValue('temperature', 85);

updateNestedValue

  • updateNestedValue(path, value): void

  • Update a nested property in the context data using dot notation. This method safely updates nested properties without replacing the entire object structure.

    Parameters

    • path: string

      Dot-separated path to the nested property (e.g., 'sensors.humidity', 'config.thresholds.temp')

    • value: unknown

      The new value to set at the nested path

    Returns void

    Example

    evaluator.updateNestedValue('sensors.humidity', 60);

addModelToContext

  • addModelToContext(key, model): void

  • Add a KOS model to the evaluation context. The model's observable properties will be accessible via dotted notation and expressions will automatically re-evaluate when the model's data changes.

    Parameters

    • key: string

      The context key to store the model under

    • model: unknown

      Any KOS model instance (must be observable)

    Returns void

    Example

    const sensorModel = SensorModel.instance('main-sensor').build();
    evaluator.addModelToContext('sensor', sensorModel);
    evaluator.addExpression('isCritical', 'sensor.temperature > 80');

addExpression

  • addExpression(name, expressionString): void

  • Add a named expression that will be automatically evaluated against context data. The expression will re-evaluate whenever its dependencies in the context change.

    Parameters

    • name: T

      Unique identifier for this expression (type-safe when using generic)

    • expressionString: string

      JavaScript-like expression string

    Returns void

    Throws

    If the expression has invalid syntax

    Example

    evaluator.addExpression('isHot', 'temperature > 80');

getCachedExpressionValue

  • getCachedExpressionValue(name): undefined | ExpressionResult

  • Get the cached result of an expression without triggering re-evaluation. This is useful for dependency tracking in effects where you want to avoid creating reactive chains through the expression evaluation.

    Parameters

    • name: T

      The expression name to get the cached result for

    Returns undefined | ExpressionResult

    The last cached result, or undefined if expression doesn't exist

    Example

    const cached = evaluator.getCachedExpressionValue('myExpression');

createExpression

  • createExpression(expressionString): string

  • Create an anonymous reactive expression and return its generated ID. The expression becomes fully reactive and can be accessed via the returned ID.

    Parameters

    • expressionString: string

      JavaScript-like expression string

    Returns string

    Generated UUID that can be used to access the expression via getExpressionValue(id) or results[id]

    Example

    const tempCheckId = evaluator.createExpression('temperature > 75');
    const result = evaluator.getExpressionValue(tempCheckId);

Settings

Member Visibility

Theme

On This Page

setContextDataupdateContextValueupdateNestedValueaddModelToContextaddExpressiongetCachedExpressionValuecreateExpression