script

type Config ¶

type Config struct {
	FS       fs.FS   // A filesystem to load resources fs.
	MainPath string  // A path, relative to FS that holds the entrypoint.
	Options  Options // The target for calls to api.setOptions().

	// An external filesystem path. This will be cleared after Preflight
	// has been called. This symbol is exported for testing.
	UserScriptPath string
}

Config drives UserScript behavior.

func (c *Config) Bind(f *pflag.FlagSet)

func (c *Config) Preflight() error

type DeleteKey ¶

type DeleteKey func(ctx context.Context, mut types.Mutation) (types.Mutation, bool, error)

DeleteKey is similar to Map in that it has the opportunity to modify or filter a mutation before subsequent processing. Rather than operating on types.Mutation.Data, it should instead base its behavior on types.Mutation.Key. DeleteKey functions are internally synchronized to ensure single-threaded access to the underlying JS VM.

type Dispatch ¶

type Dispatch func(ctx context.Context, mutation types.Mutation) (*ident.TableMap[[]types.Mutation], error)

A Dispatch function receives a source mutation and assigns mutations to some number of downstream tables. Dispatch functions are internally synchronized to ensure single-threaded access to the underlying JS VM.

type FlagOptions ¶

type FlagOptions struct {
	Flags *pflag.FlagSet
}

FlagOptions adapts a pflag.FlagSet to the Options interface.

func (o *FlagOptions) Set(key, value string) error

type Loader ¶

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

Loader is responsible for the first-pass execution of the user script. It will load all required resources, parse, and execute the top-level API calls. It should be noted that a Loader is a global resource which is independent of any particular target schema. In order to resolve the various table names against a specific target schema, call Loader.Bind to return a UserScript that operates within the given target schema.

func ProvideLoader(
	ctx context.Context, applyConfigs *applycfg.Configs, cfg *Config, diags *diag.Diagnostics,
) (*Loader, error)

func (l *Loader) Bind(
	ctx *stopper.Context,
	target ident.Schematic,
	targetAcceptor types.TableAcceptor,
	watchers types.Watchers,
) (*UserScript, error)

type Map ¶

type Map func(ctx context.Context, mut types.Mutation) (types.Mutation, bool, error)

A Map function may modify the mutations that are applied to a specific table. The boolean value will be false if the input mutation should be discarded. Map functions are internally synchronized to ensure single-threaded access to the underlying JS VM.

type Options ¶

type Options interface{ Set(key, value string) error }

Options is an injection point for a value that will receive any additional configuration from api.setOptions.

var NoOptions Options = &noOptions{}

type Source ¶

type Source struct {
	// The table to apply incoming deletes to; this assumes that the
	// target schema is using FK's with ON DELETE CASCADE.
	DeletesTo ident.Table
	// A user-provided function that routes mutations to zero or more
	// tables.
	Dispatch Dispatch `json:"-"`
	// Enable recursion in sources which support nested sources.
	Recurse bool
}

A Source holds user-provided configuration options for a generic data-source.

type Target ¶

type Target struct {
	applycfg.Config
	// A user-provided function to modify of filter mutations that
	// delete a row in the target table.
	DeleteKey DeleteKey `json:"-"`
	// A user-provided function to modify or filter mutations bound for
	// the target table.
	Map Map `json:"-"`
	// A user-defined TableAcceptor that may execute arbitrary SQL or
	// call [UserScript.Delegate].
	UserAcceptor types.TableAcceptor `json:"-"`
}

A Target holds user-provided configuration options for a target table.

type UserScript ¶

type UserScript struct {
	Delegate types.TableAcceptor
	Sources  *ident.Map[*Source]
	Targets  *ident.TableMap[*Target]
	// contains filtered or unexported fields
}

UserScript encapsulates a user-provided configuration expressed as a JavaScript program.

NB: The single-threaded nature of JavaScript means that only a single goroutine may execute JS code at any given point in time. These critical sections are coordinated through the execJS method. It's also the case that the JS user code is tightly coupled to the particular goja.Runtime that loaded the script (e.g. JS global variables). Should contention on the runtime become problematic, the correct solution would be to create multiple Loaders that each evaluate a separate UserScript. The tradedoff here is that each instance of the userscript would then have distinct global variables.

func (s *UserScript) Diagnostic(_ context.Context) any

func (s *UserScript) Exited()

func (s *UserScript) Grab() any

func (s *UserScript) Resumed(obj any)