common

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 1, 2026 License: MIT Imports: 13 Imported by: 0

README

Common Package

The common package contains shared fact, path, argument, sorting, and execution values.

It is not the production execution engine. Use runtime.Engine for durable checked execution.

Facts

BasicFacts provides path-based access to a copied data snapshot and its type system.

facts, err := common.TryNewBasicFacts(data, typeSystem)
if err != nil {
    return err
}
value, exists := facts.Get("order.customer.id")

WithData creates another fact value. Callers must not depend on mutable input maps after construction.

Paths

Use the shared path parser for structured access:

parsed, err := common.ParseString("app.users[0].name")

The parser supports named fields, list indexes, and map keys. The schema type system validates rule paths during compilation.

Arguments

Argument helpers normalize literals, fact paths, and result references for compatibility executors.

The checked compiler uses distinct protobuf variants for these sources. Do not collapse them into an untyped map before checking.

Ordering

Shared sorting helpers preserve source order for equal priorities.

Stable ordering is part of checked plan selection. It does not make external operations deterministic.

Execution values

The package includes compatibility execution types used by list and flow libraries.

Production transports use checked IR and runtime.Engine.Execute. Legacy Go continuations cannot enter a production generation.

Test

go test ./common

Documentation

Overview

Package common provides shared execution interfaces and utilities

Package common provides shared utilities and data structures

Package common contains shared type definitions used across Effectus packages

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CompileArgs

func CompileArgs(args []*ast.StepArg, bindings map[string]interface{}) (map[string]interface{}, error)

CompileArgs resolves any variable references and fact paths in arguments

func CompileLiteral

func CompileLiteral(lit *ast.Literal) interface{}

CompileLiteral converts an AST literal to a runtime value

func SortByPriority

func SortByPriority[T Prioritized](items []T)

SortByPriority sorts a slice of Prioritized items by priority (higher priority first)

func SortByPriorityFunc

func SortByPriorityFunc[T any](items []T, getPriority func(T) int)

SortByPriorityFunc sorts a slice using a priority extraction function

func SortByPriorityFuncStable

func SortByPriorityFuncStable[T any](items []T, getPriority func(T) int)

SortByPriorityFuncStable sorts a slice using a priority function with stable sort

func SortByPriorityStable

func SortByPriorityStable[T Prioritized](items []T)

SortByPriorityStable sorts a slice by priority using stable sort (preserves order of equal elements)

func ValidateVerbArgs

func ValidateVerbArgs(spec *verb.Spec, args map[string]interface{}, registry VerbRegistry) error

ValidateVerbArgs enforces runtime argument validation based on strict settings.

func ValidateVerbReturn

func ValidateVerbReturn(spec *verb.Spec, result interface{}, registry VerbRegistry) error

ValidateVerbReturn enforces runtime return validation based on strict settings.

Types

type BasicFacts

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

BasicFacts provides an immutable facts implementation using gjson

func NewBasicFacts

func NewBasicFacts(data map[string]interface{}, schema SchemaInfo) *BasicFacts

NewBasicFacts creates a new facts instance from data and schema. Deprecated: use TryNewBasicFacts. This compatibility constructor panics when data is not JSON encodable.

func TryNewBasicFacts

func TryNewBasicFacts(data map[string]interface{}, schema SchemaInfo) (*BasicFacts, error)

TryNewBasicFacts creates a facts instance and reports values that JSON cannot represent (for example channels, functions, and cyclic maps).

func (*BasicFacts) Get

func (f *BasicFacts) Get(path string) (interface{}, bool)

Get implements Facts interface

func (*BasicFacts) GetWithContext

func (f *BasicFacts) GetWithContext(path string) (interface{}, *ResolutionResult)

GetWithContext implements Facts interface

func (*BasicFacts) HasPath

func (f *BasicFacts) HasPath(path string) bool

HasPath checks if a path exists in the facts

func (*BasicFacts) Schema

func (f *BasicFacts) Schema() SchemaInfo

Schema implements Facts interface

func (*BasicFacts) TryWithData

func (f *BasicFacts) TryWithData(updatedData map[string]interface{}) (*BasicFacts, error)

TryWithData creates a new facts value with updated data.

func (*BasicFacts) WithData

func (f *BasicFacts) WithData(updatedData map[string]interface{}) *BasicFacts

WithData creates a new Facts instance with updated data. Deprecated: use TryWithData.

type BasicSchema

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

BasicSchema provides a simple schema implementation

func NewBasicSchema

func NewBasicSchema() *BasicSchema

NewBasicSchema creates a new basic schema

func (*BasicSchema) GetPathType

func (s *BasicSchema) GetPathType(path string) *types.Type

GetPathType implements SchemaInfo interface

func (*BasicSchema) RegisterPathType

func (s *BasicSchema) RegisterPathType(path string, typ *types.Type)

RegisterPathType implements SchemaInfo interface

func (*BasicSchema) ValidatePath

func (s *BasicSchema) ValidatePath(path string) bool

ValidatePath validates a path

type ExecutorAdapter

type ExecutorAdapter struct {
	VerbRegistry VerbRegistry
	Facts        Facts
}

ExecutorAdapter implements effectus.Executor using shared interfaces This eliminates duplication between list and flow packages

func NewExecutorAdapter

func NewExecutorAdapter(verbRegistry VerbRegistry, facts Facts) *ExecutorAdapter

NewExecutorAdapter creates a new shared executor adapter

func (*ExecutorAdapter) Do

func (ea *ExecutorAdapter) Do(effect eff.Effect) (interface{}, error)

Do implements the legacy context-free executor API.

func (*ExecutorAdapter) DoContext

func (ea *ExecutorAdapter) DoContext(ctx context.Context, effect eff.Effect) (interface{}, error)

DoContext executes a verb with the caller's cancellation and deadline.

type FactRef

type FactRef string

FactRef marks an argument value as a fact path reference.

type Facts

type Facts interface {
	// Get gets a value by path
	Get(path string) (interface{}, bool)

	// GetWithContext gets a value with resolution information
	GetWithContext(path string) (interface{}, *ResolutionResult)

	// Schema gets the schema information
	Schema() SchemaInfo

	// HasPath checks if a path exists
	HasPath(path string) bool
}

Facts defines the interface for immutable fact providers

type FactsExt

type FactsExt interface {
	Facts

	// GetByPath gets a value by structured path (deprecated)
	GetByPath(path string) (interface{}, bool)
}

FactsExt extends the Facts interface with structured path methods

type Predicate

type Predicate struct {
	Path pathutil.Path // The path in the facts to check
	Op   string        // The operator (==, !=, >, <, >=, <=, in, contains)
	Lit  interface{}   // The literal value to compare against
}

Predicate represents a compiled condition on facts

type Prioritized

type Prioritized interface {
	GetPriority() int
}

Prioritized represents an item with a priority for sorting

type ResolutionResult

type ResolutionResult struct {
	// Path is the path that was resolved
	Path string

	// Value is the resolved value
	Value interface{}

	// Exists indicates if the path exists in the data
	Exists bool

	// Error is any error encountered during resolution
	Error error

	// Type is the type information for the resolved value
	Type *types.Type
}

ResolutionResult contains the result of path resolution

type ResultRef

type ResultRef string

ResultRef marks an argument value as a checked flow result-slot reference.

type SchemaInfo

type SchemaInfo interface {
	// ValidatePath validates a path
	ValidatePath(path string) bool

	// GetPathType gets the type for a path
	GetPathType(path string) *types.Type

	// RegisterPathType registers a type for a path
	RegisterPathType(path string, typ *types.Type)
}

SchemaInfo defines the interface for schema information providers

type VerbRegistry

type VerbRegistry interface {
	GetVerb(name string) (*verb.Spec, bool)
}

VerbRegistry defines the interface for verb registry access This is shared between list and flow execution systems

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL