transform

Documentation

Overview

Package transform runs MIMIRO transform scripts (TypeScript or JavaScript) against a hub via esbuild + goja.

Index

• type LogEntry
• type Logger
• type Options
• type OverlayResolver
• type QueryRecord
• type QueryRecorder
• type Result
  • func Run(ctx context.Context, source string, entities []*api.Entity, opts Options) (*Result, error)
• type SyntheticProvider

Types

type LogEntry

type LogEntry struct {
	Level     string    `json:"level"`
	Message   string    `json:"message"`
	Timestamp time.Time `json:"ts"`
}

type Logger

type Logger interface {
	Log(entry LogEntry)
}

type Options

type Options struct {
	HubURL  string
	Bearer  string
	Logger  Logger
	Timeout time.Duration

	// All three nil in production. The operator UI uses QueryRecorder to
	// discover what a transform pulled in via Query/FindById, OverlayResolver
	// to substitute mocked entity fields before user code observes them, and
	// SyntheticProvider to inject user-authored mock entities into FindById /
	// Query results when the hub itself wouldn't surface them.
	QueryRecorder     QueryRecorder
	OverlayResolver   OverlayResolver
	SyntheticProvider SyntheticProvider
}

type OverlayResolver

type OverlayResolver interface {
	ResolveOverlay(e *api.Entity) *api.Entity
}

OverlayResolver gets a shot at every entity emerging from Query / FindById before it reaches user code. Implementations return the entity to hand on — either the original or a (cloned and) mutated version. Returning nil signals "no overlay; use the original".

type QueryRecord

type QueryRecord struct {
	Kind        string // "query" | "findById"
	StartingIds []string
	Predicate   string
	Inverse     bool
	Datasets    []string
	Entities    []*api.Entity
}

type QueryRecorder

type QueryRecorder interface {
	RecordQuery(record QueryRecord)
}

QueryRecorder observes the entities surfaced through Query / FindById, in the order they reach user code (i.e. after OverlayResolver has run).

type Result

type Result struct {
	Entities   []*api.Entity `json:"entities"`
	Logs       []LogEntry    `json:"logs"`
	DurationMs int64         `json:"durationMs"`
}

Compile and runtime errors surface as level=error entries on Logs with empty Entities; the error return is reserved for cancellation / timeout.

func Run

func Run(ctx context.Context, source string, entities []*api.Entity, opts Options) (*Result, error)

type SyntheticProvider

type SyntheticProvider interface {
	Lookup(id string, datasets []string) *api.Entity
	All(datasets []string) []*api.Entity
}

SyntheticProvider injects user-authored mock entities into the runtime.

Lookup is called by tf.ById and the cli's Query-augmentation path to resolve a specific id against the operator's authored mocks. If a synthetic exists with that id (and a matching dataset, when the call passes a non-empty datasets filter), it stands in for any hub result. The synthetic is then run through OverlayResolver just like a hub entity would be, so pinned overrides still apply.

All returns every synthetic that passes the datasets filter — used by the cli's Query augmentation to walk the candidate pool for inverse lookups (entities whose refs[predicate] points at one of the startingIds) and as the fallback target pool when the hub returns no tuples.

The datasets slice is honoured in both methods: when non-empty, the synthetic's dataset must appear in the slice to participate.