modules

Documentation

Overview

Package modules defines interfaces used for developing k6's JavaScript modules.

Index

• func Register(name string, mod interface{})
• type Exports
• type FileLoader
• type Instance
• type LegacyRequireImpl
  • func NewLegacyRequireImpl(vu VU, ms *ModuleSystem, pwd url.URL) *LegacyRequireImpl
  • func (r *LegacyRequireImpl) CurrentlyRequiredModule() url.URL
  • func (r *LegacyRequireImpl) Require(specifier string) (*goja.Object, error)
• type Module
• type ModuleResolver
  • func NewModuleResolver(goModules map[string]interface{}, loadCJS FileLoader, c *compiler.Compiler) *ModuleResolver
  • func (mr *ModuleResolver) Imported() []string
• type ModuleSystem
  • func NewModuleSystem(resolver *ModuleResolver, vu VU) *ModuleSystem
  • func (ms *ModuleSystem) Require(pwd *url.URL, arg string) (*goja.Object, error)
  • func (ms *ModuleSystem) RunSourceData(source *loader.SourceData) (goja.Value, error)
• type VU

Functions

func Register

func Register(name string, mod interface{})

Register the given mod as an external JavaScript module that can be imported by name. The name must be unique across all registered modules and must be prefixed with "k6/x/", otherwise this function will panic.

Types

type Exports

type Exports struct {
	// Default is what will be the `default` export of a module
	Default interface{}
	// Named is the named exports of a module
	Named map[string]interface{}
}

Exports is representation of ESM exports of a module

type FileLoader

type FileLoader func(specifier *url.URL, name string) ([]byte, error)

FileLoader is a type alias for a function that returns the contents of the referenced file.

type Instance

type Instance interface {
	Exports() Exports
}

Instance is what a module needs to return

type LegacyRequireImpl

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

LegacyRequireImpl is a legacy implementation of `require()` that is not compatible with CommonJS as it loads modules relative to the currently required file, instead of relative to the file the `require()` is written in. See https://github.com/grafana/k6/issues/2674

func NewLegacyRequireImpl

func NewLegacyRequireImpl(vu VU, ms *ModuleSystem, pwd url.URL) *LegacyRequireImpl

NewLegacyRequireImpl creates a new LegacyRequireImpl

func (*LegacyRequireImpl) CurrentlyRequiredModule

func (r *LegacyRequireImpl) CurrentlyRequiredModule() url.URL

CurrentlyRequiredModule returns the module that is currently being required. It is mostly used for old and somewhat buggy behaviour of the `open` call

func (*LegacyRequireImpl) Require

func (r *LegacyRequireImpl) Require(specifier string) (*goja.Object, error)

Require is the actual call that implements require

type Module

type Module interface {
	// NewModuleInstance will get modules.VU that should provide the module with a way to interact with the VU
	// This method will be called for *each* require/import and should return an unique instance for each call
	NewModuleInstance(VU) Instance
}

Module is the interface js modules should implement in order to get access to the VU

type ModuleResolver

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

ModuleResolver knows how to get base Module that can be initialized

func NewModuleResolver

func NewModuleResolver(goModules map[string]interface{}, loadCJS FileLoader, c *compiler.Compiler) *ModuleResolver

NewModuleResolver returns a new module resolution instance that will resolve. goModules is map of import file to a go module loadCJS is used to load commonjs files

func (*ModuleResolver) Imported

func (mr *ModuleResolver) Imported() []string

Imported returns the list of imported and resolved modules. Each string represents the path as used for importing.

type ModuleSystem

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

ModuleSystem is implementing an ESM like module system to resolve js modules for k6 usage

func NewModuleSystem

func NewModuleSystem(resolver *ModuleResolver, vu VU) *ModuleSystem

NewModuleSystem returns a new ModuleSystem for the provide VU using the provided resoluter

func (*ModuleSystem) Require

func (ms *ModuleSystem) Require(pwd *url.URL, arg string) (*goja.Object, error)

Require is called when a module/file needs to be loaded by a script

func (*ModuleSystem) RunSourceData

func (ms *ModuleSystem) RunSourceData(source *loader.SourceData) (goja.Value, error)

RunSourceData runs the provided sourceData and adds it to the cache. If a module with the same specifier as the source is already cached it will be used instead of reevaluating the source from the provided SourceData.

TODO: this API will likely change as native ESM support will likely not let us have the exports as one big goja.Value that we can manipulate

type VU

type VU interface {
	// Context return the context.Context about the current VU
	Context() context.Context

	// Events allows subscribing to global k6 execution events, such as Init and
	// Exit, and to local (per-VU) events, such as IterStart and IterEnd.
	// NOTE: This API is EXPERIMENTAL and may be changed, renamed or
	// completely removed in a later k6 release.
	// FIXME: Subscribing to global events shouldn't be part of this VU (local)
	// interface.
	Events() common.Events

	// InitEnv returns common.InitEnvironment instance if present
	InitEnv() *common.InitEnvironment

	// State returns lib.State if any is present
	State() *lib.State

	// Runtime returns the goja.Runtime for the current VU
	Runtime() *goja.Runtime

	// RegisterCallback lets a JS module declare that it wants to run a function
	// on the event loop *at a later point in time*. See the documentation for
	// `EventLoop.RegisterCallback()` in the `k6/js/eventloop` Go module for
	// the very important details on its usage and restrictions.
	RegisterCallback() (enqueueCallback func(func() error))
}

VU gives access to the currently executing VU to a module Instance