types

Documentation

Overview

Package types defines the core types and interfaces for the Kangaroo expression evaluator

Index

• Constants
• Variables
• type ASTExecutor
• type ASTParser
• type EvaluationResult
• type EvaluatorOptions
  • func DefaultEvaluatorOptions() *EvaluatorOptions
• type ExpressionContext
• type ExpressionEvaluator
• type FunctionRegistry
• type Metadata
• type ParsedExpression
• type ProcessedExpression
• type SafeFunction
• type TemplateMatch
• type TemplateResult
• type ValueConverter
  • func NewValueConverter() *ValueConverter
  • func (vc *ValueConverter) CompareValues(left, right interface{}, operator string) (bool, error)
  • func (vc *ValueConverter) GetJavaScriptType(v interface{}) string
  • func (vc *ValueConverter) IsEmpty(v interface{}) bool
  • func (vc *ValueConverter) LooseEquals(left, right interface{}) bool
  • func (vc *ValueConverter) NormalizeValue(v interface{}) interface{}
  • func (vc *ValueConverter) StrictEquals(left, right interface{}) bool
  • func (vc *ValueConverter) ToArray(v interface{}) []interface{}
  • func (vc *ValueConverter) ToArrayIndex(v interface{}) int
  • func (vc *ValueConverter) ToBool(v interface{}) bool
  • func (vc *ValueConverter) ToInt(v interface{}) int
  • func (vc *ValueConverter) ToMap(v interface{}) map[string]interface{}
  • func (vc *ValueConverter) ToNumber(v interface{}) (float64, error)
  • func (vc *ValueConverter) ToString(v interface{}) string

Constants

const (
	ErrorTypeSyntax     = "syntax"
	ErrorTypeSecurity   = "security"
	ErrorTypeRuntime    = "runtime"
	ErrorTypeType       = "type"
	ErrorTypeComplexity = "complexity"
	ErrorTypeTimeout    = "timeout"
)

Error types

const (
	CategoryString      = "string"
	CategoryArray       = "array"
	CategoryObject      = "object"
	CategoryMath        = "math"
	CategoryDate        = "date"
	CategoryJSON        = "json"
	CategoryUtility     = "utility"
	CategoryConditional = "conditional"
	CategoryCrypto      = "crypto"
	CategoryWorkflow    = "workflow"
)

Function categories

Variables

var DefaultConverter = NewValueConverter()

Global value converter instance - singleton pattern

Types

type ASTExecutor

type ASTExecutor interface {
	Execute(node ast.Node, context *ExpressionContext) (*EvaluationResult, error)
	GetStats() map[string]interface{}
	ResetStats()
	ClearCache()
}

ASTExecutor interface for AST execution

type ASTParser

type ASTParser interface {
	Parse(expression string) (*ParsedExpression, error)
	ParseTemplate(template string) ([]*TemplateMatch, error)
	HasTemplateExpressions(text string) bool
	ExtractTemplateExpressions(template string) ([]*TemplateMatch, error)
	AnalyzeComplexity(expression string) (map[string]interface{}, error)
	ClearCache()
	GetCacheStats() map[string]interface{}
}

ASTParser interface for expression parsing

type EvaluationResult

type EvaluationResult struct {
	Success   bool        `json:"success"`
	Value     interface{} `json:"value,omitempty"`
	Error     string      `json:"error,omitempty"`
	ErrorType string      `json:"errorType,omitempty"`
	Metadata  *Metadata   `json:"metadata,omitempty"`
}

EvaluationResult represents the result of expression evaluation

type EvaluatorOptions

type EvaluatorOptions struct {
	MaxComplexity   float64        `json:"maxComplexity"`
	MaxDepth        int            `json:"maxDepth"`
	EnableDebugging bool           `json:"enableDebugging"`
	CustomFunctions []SafeFunction `json:"-"` // Not serializable
	StrictMode      bool           `json:"strictMode"`
	Timeout         int64          `json:"timeout"` // milliseconds
	EnableCaching   bool           `json:"enableCaching"`
	MaxCacheSize    int            `json:"maxCacheSize"`
	CollectMetrics  bool           `json:"collectMetrics"`
}

EvaluatorOptions configures the expression evaluator

func DefaultEvaluatorOptions

func DefaultEvaluatorOptions() *EvaluatorOptions

DefaultEvaluatorOptions returns default evaluator options

type ExpressionContext

type ExpressionContext struct {
	// Primary data item being processed
	Item interface{} `json:"item,omitempty"`

	// Variables for arrow function parameters in array operations
	Variables map[string]interface{} `json:"variables,omitempty"`
}

ExpressionContext provides data to expressions

type ExpressionEvaluator

type ExpressionEvaluator interface {
	Evaluate(expression string, context *ExpressionContext) (*EvaluationResult, error)
	Parse(expression string) (*ParsedExpression, error)
	ExtractDependencies(expression string) ([]string, error)
	AddFunction(fn *SafeFunction)
	RemoveFunction(name string)
	ListFunctions(category string) []*SafeFunction
	GetPerformanceStats() map[string]interface{}
	ResetStats()
	ClearCaches()
}

ExpressionEvaluator is the main interface for expression evaluation

type FunctionRegistry

type FunctionRegistry interface {
	Register(fn *SafeFunction) error
	Unregister(name string)
	Get(name string) (*SafeFunction, bool)
	Has(name string) bool
	List(category string) []*SafeFunction
	GetNames() []string
	GetCategories() []string
	Clear()
	GetStats() map[string]interface{}
}

FunctionRegistry interface for function management

type Metadata

type Metadata struct {
	ExecutionTime        int64    `json:"executionTime,omitempty"` // microseconds
	Complexity           float64  `json:"complexity,omitempty"`
	AccessedVariables    []string `json:"accessedVariables,omitempty"`
	CalledFunctions      []string `json:"calledFunctions,omitempty"`
	EstimatedMemoryUsage int64    `json:"estimatedMemoryUsage,omitempty"`
}

Metadata contains additional information about evaluation

type ParsedExpression

type ParsedExpression struct {
	AST                  ast.Node `json:"-"` // Not serializable
	Dependencies         []string `json:"dependencies"`
	Functions            []string `json:"functions"`
	Complexity           float64  `json:"complexity"`
	IsSimple             bool     `json:"isSimple"`
	HasTemplates         bool     `json:"hasTemplates"`
	Depth                int      `json:"depth"`
	EstimatedMemoryUsage int64    `json:"estimatedMemoryUsage"`
}

ParsedExpression contains parsed AST with metadata

type ProcessedExpression

type ProcessedExpression struct {
	Original   string      `json:"original"`
	Evaluated  interface{} `json:"evaluated"`
	StartIndex int         `json:"startIndex"`
	EndIndex   int         `json:"endIndex"`
}

ProcessedExpression represents a processed template expression

type SafeFunction

type SafeFunction struct {
	Name        string                                    `json:"name"`
	Description string                                    `json:"description"`
	Category    string                                    `json:"category"`
	MinArgs     int                                       `json:"minArgs"`
	MaxArgs     int                                       `json:"maxArgs"` // -1 for unlimited
	IsAsync     bool                                      `json:"isAsync"`
	ReturnType  string                                    `json:"returnType,omitempty"`
	Examples    []string                                  `json:"examples,omitempty"`
	Since       string                                    `json:"since,omitempty"`
	Deprecated  bool                                      `json:"deprecated"`
	Fn          func(...interface{}) (interface{}, error) `json:"-"` // Not serializable
}

SafeFunction represents a registered safe function

type TemplateMatch

type TemplateMatch struct {
	FullMatch  string `json:"fullMatch"`
	Expression string `json:"expression"`
	StartIndex int    `json:"startIndex"`
	EndIndex   int    `json:"endIndex"`
	Multiline  bool   `json:"multiline"`
}

TemplateMatch represents a matched template expression

type TemplateResult

type TemplateResult struct {
	Success              bool                  `json:"success"`
	Result               string                `json:"result,omitempty"`
	Error                string                `json:"error,omitempty"`
	ProcessedExpressions []ProcessedExpression `json:"processedExpressions,omitempty"`
}

TemplateResult represents template evaluation result

type ValueConverter

type ValueConverter struct {
	// contains filtered or unexported fields
}

ValueConverter provides centralized type conversion between JavaScript and Go types This implements the ECMAScript specification for type conversions with full production-ready semantics

func NewValueConverter

func NewValueConverter() *ValueConverter

NewValueConverter creates a new value converter

func (*ValueConverter) CompareValues

func (vc *ValueConverter) CompareValues(left, right interface{}, operator string) (bool, error)

CompareValues compares two values with proper ECMAScript comparison semantics

func (*ValueConverter) GetJavaScriptType

func (vc *ValueConverter) GetJavaScriptType(v interface{}) string

GetJavaScriptType returns the JavaScript typeof result for a value Ref: https://tc39.es/ecma262/#sec-typeof-operator

func (*ValueConverter) IsEmpty

func (vc *ValueConverter) IsEmpty(v interface{}) bool

IsEmpty checks if a value is considered empty in JavaScript context

func (*ValueConverter) LooseEquals

func (vc *ValueConverter) LooseEquals(left, right interface{}) bool

LooseEquals implements ECMAScript Abstract Equality Comparison (==) Ref: https://tc39.es/ecma262/#sec-abstract-equality-comparison

func (*ValueConverter) NormalizeValue

func (vc *ValueConverter) NormalizeValue(v interface{}) interface{}

NormalizeValue converts JavaScript types (especially unistring.String) to Go types This ensures consistent representation across the system

func (*ValueConverter) StrictEquals

func (vc *ValueConverter) StrictEquals(left, right interface{}) bool

StrictEquals implements ECMAScript Strict Equality Comparison (===) Ref: https://tc39.es/ecma262/#sec-strict-equality-comparison

func (*ValueConverter) ToArray

func (vc *ValueConverter) ToArray(v interface{}) []interface{}

ToArray converts a value to an array (slice)

func (*ValueConverter) ToArrayIndex

func (vc *ValueConverter) ToArrayIndex(v interface{}) int

ToArrayIndex converts a value to a safe array index, returning -1 for invalid indices This is used for array/string indexing where we need to handle invalid cases gracefully

func (*ValueConverter) ToBool

func (vc *ValueConverter) ToBool(v interface{}) bool

ToBool implements ECMAScript ToBoolean() conversion Ref: https://tc39.es/ecma262/#sec-toboolean

func (*ValueConverter) ToInt

func (vc *ValueConverter) ToInt(v interface{}) int

ToInt converts a value to an integer (for general use, not array indexing) This differs from ToArrayIndex which returns -1 for invalid indices

func (*ValueConverter) ToMap

func (vc *ValueConverter) ToMap(v interface{}) map[string]interface{}

ToMap converts a value to a map

func (*ValueConverter) ToNumber

func (vc *ValueConverter) ToNumber(v interface{}) (float64, error)

ToNumber implements ECMAScript ToNumber() conversion Ref: https://tc39.es/ecma262/#sec-tonumber

func (*ValueConverter) ToString

func (vc *ValueConverter) ToString(v interface{}) string

ToString implements ECMAScript ToString() conversion Ref: https://tc39.es/ecma262/#sec-tostring