Documentation
¶
Overview ¶
Package jsenv bundles a TypeScript entrypoint with esbuild and evaluates it in a goja VM to produce the JSON IR (SPEC.md §5.1).
Index ¶
- func Discover(dir string) ([]string, error)
- type Bundler
- type CommandInfo
- type EsbuildBundler
- type Evaluator
- type ExecFunc
- type GojaEvaluator
- func (g *GojaEvaluator) Evaluate(ctx context.Context, script string, env map[string]string) ([]byte, error)
- func (g *GojaEvaluator) ListCommands(ctx context.Context, script string, env map[string]string) ([]CommandInfo, error)
- func (g *GojaEvaluator) RunCommand(ctx context.Context, script string, env map[string]string, name string, ...) (int, error)
- type Synthesizer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Discover ¶
Discover returns the project's TypeScript entry files in bundle order: dex.config.ts first, then every dex/services/**/*.ts and dex/commands/**/*.ts below dir as slash-separated paths relative to dir, sorted. dex.config.ts must exist — its absence is the "not a dex project" error, reported here rather than as an opaque esbuild resolve failure. A missing dex/services/ or dex/commands/ directory is fine (contributes nothing), and *.d.ts files and dot-prefixed directories (e.g. .git, .dex) are skipped. The registry and buildIR sort internally, so file order only makes the first error deterministic.
Types ¶
type Bundler ¶
Bundler transpiles and bundles a project's TypeScript entry files into a single script runnable by an Evaluator.
type CommandInfo ¶
CommandInfo describes one registered command for `dex run` listing.
type EsbuildBundler ¶
type EsbuildBundler struct{}
EsbuildBundler bundles with esbuild, resolving the bare "@dex/iac" specifier to the SDK embedded in the binary.
func NewEsbuildBundler ¶
func NewEsbuildBundler() *EsbuildBundler
NewEsbuildBundler returns a Bundler backed by esbuild.
func (*EsbuildBundler) Bundle ¶
func (b *EsbuildBundler) Bundle(dir string, files []string) (string, error)
Bundle transpiles and bundles files (slash paths relative to dir) into a single IIFE script. Any bare import other than "@dex/iac" stays unresolvable and surfaces as an esbuild error — correct, since no package manager exists on the user machine.
type Evaluator ¶
type Evaluator interface {
Evaluate(ctx context.Context, script string, env map[string]string) ([]byte, error)
}
Evaluator runs a bundled script and returns the JSON IR produced by calling __dex_synth().
type ExecFunc ¶
ExecFunc runs argv as a host process with stdio attached and returns its exit code. It must return an error only when the process could not be started; a process that ran and exited non-zero is a code, not an error.
type GojaEvaluator ¶
type GojaEvaluator struct {
// contains filtered or unexported fields
}
GojaEvaluator runs scripts in a goja ECMAScript VM.
func NewGojaEvaluator ¶
func NewGojaEvaluator() *GojaEvaluator
NewGojaEvaluator returns an Evaluator with a 10s run budget.
func NewGojaEvaluatorWithTimeout ¶
func NewGojaEvaluatorWithTimeout(d time.Duration) *GojaEvaluator
NewGojaEvaluatorWithTimeout returns an Evaluator with a custom run budget; a zero duration means no budget, so only ctx cancellation interrupts.
func (*GojaEvaluator) Evaluate ¶
func (g *GojaEvaluator) Evaluate(ctx context.Context, script string, env map[string]string) ([]byte, error)
Evaluate runs script with env exposed as globalThis.__dex_env and returns the JSON string produced by calling globalThis.__dex_synth().
func (*GojaEvaluator) ListCommands ¶
func (g *GojaEvaluator) ListCommands(ctx context.Context, script string, env map[string]string) ([]CommandInfo, error)
ListCommands evaluates script (env exposed as __dex_env) and returns the commands registered via the SDK's defineCommand, in registry order.
func (*GojaEvaluator) RunCommand ¶
func (g *GojaEvaluator) RunCommand(ctx context.Context, script string, env map[string]string, name string, args []string, resources map[string]any, execFn ExecFunc) (int, error)
RunCommand evaluates script and calls the run() of the command named name with a ctx exposing args, env(key), resources (state exactly as persisted, secrets still hashed), secret(key) (plaintext from the same env map), and exec(argv) (a host process, via execFn), returning the command's numeric result as an exit code (0 when run returns undefined).
type Synthesizer ¶
type Synthesizer struct {
// contains filtered or unexported fields
}
Synthesizer turns a TypeScript entrypoint into raw IR JSON. Parsing and validating that JSON is the engine's job (SPEC.md §4 Step 2.1), not this TS-execution wrapper's: keeping it here would make pkg/jsenv depend on pkg/engine/ir while pkg/engine depends on pkg/jsenv, a loop back into the engine.
func NewSynthesizer ¶
func NewSynthesizer(b Bundler, e Evaluator) *Synthesizer
NewSynthesizer wires a Bundler and Evaluator into a Synthesizer.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package sdk embeds the pre-bundled @dex/iac JavaScript so it ships inside the dex binary; the user has no Node.js and no node_modules.
|
Package sdk embeds the pre-bundled @dex/iac JavaScript so it ships inside the dex binary; the user has no Node.js and no node_modules. |
|
gen
command
Command gen bundles packages/sdk/dist (tsc output) into a single ESM file embedded into the dex binary as pkg/jsenv/sdk/iac.js.
|
Command gen bundles packages/sdk/dist (tsc output) into a single ESM file embedded into the dex binary as pkg/jsenv/sdk/iac.js. |