module

package
v0.0.0-...-e62627f Latest Latest
Warning

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

Go to latest
Published: Aug 31, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package module contains memory-backed ESM module registration for QuickJS.

Index

Constants

This section is empty.

Variables

View Source
var ErrInvalidModule = errors.New("invalid module")

ErrInvalidModule reports malformed module source or package metadata.

View Source
var ErrModuleNotFound = errors.New("module file does not exist")

ErrModuleNotFound tells the resolver to continue probing another candidate.

View Source
var ErrNoSuchBuiltin = errors.New("no such built-in module")

ErrNoSuchBuiltin reports an unknown native module.

Functions

func DefaultPathResolver

func DefaultPathResolver(base, specifier string) string

DefaultPathResolver joins a canonical base directory and a slash-separated module specifier, resolving symlinks when the target exists.

func DefaultSourceLoader

func DefaultSourceLoader(filename string) ([]byte, error)

DefaultSourceLoader reads a regular file from the host filesystem. It is an explicit helper; Registry never selects it implicitly.

Types

type Definition

type Definition struct {
	Name    string
	Aliases []string
	Exports []Export
}

Definition describes one canonical module and its optional node: aliases.

type Export

type Export struct {
	Name string
	Spec quickjs.ValueSpec
}

Export describes one named ESM export.

type NativeLoader

type NativeLoader func(ctx *quickjs.Context, module *quickjs.Value) error

NativeLoader initializes module.exports for a native module.

type PathResolver

type PathResolver func(base, specifier string) string

PathResolver canonicalizes a module specifier relative to an already canonical base directory.

type Registry

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

Registry stores immutable module definitions and materializes them per Context.

func NewRegistry

func NewRegistry(options ...RegistryOption) *Registry

NewRegistry creates an empty module registry.

func (*Registry) Add

func (r *Registry) Add(def Definition) error

Add adds a canonical module and all of its aliases.

func (*Registry) AddSource

func (r *Registry) AddSource(filename, source string) error

AddSource registers an in-memory CommonJS source using the registry's path normalization rules. It is useful for tests and embedded plugin stores.

func (*Registry) ClearContext

func (r *Registry) ClearContext(ctx *quickjs.Context)

ClearContext releases registry-owned bookkeeping. QuickJS cache values are held by the Context and are released by Context.Close; this method exists so hosts can clear any future provider state before closing a Context.

func (*Registry) Enable

func (r *Registry) Enable(ctx *quickjs.Context) *RequireModule

Enable installs globalThis.require and returns a context-bound facade. It is a convenience wrapper around EnableRequire for hosts that prefer the Goja-style explicit enable step.

func (*Registry) EnableRequire

func (r *Registry) EnableRequire(ctx *quickjs.Context) error

EnableRequire installs globalThis.require for this registry. It does not enable any native module unless the host registered it or added its ESM Definition explicitly.

func (*Registry) LoadMain

func (r *Registry) LoadMain(ctx *quickjs.Context, filename, source string) (*quickjs.Value, error)

LoadMain evaluates an entry CommonJS source with the supplied canonical filename. It is the bridge used by hosts that already read a plugin file.

func (*Registry) Names

func (r *Registry) Names() []string

Names returns all registered canonical names and aliases in stable order.

func (*Registry) Register

func (r *Registry) Register(ctx *quickjs.Context) error

Register builds every registered ESM module in ctx. CommonJS is enabled separately with EnableRequire and never changes ESM import behavior.

func (*Registry) RegisterModule

func (r *Registry) RegisterModule(ctx *quickjs.Context, name string) error

RegisterModule builds one canonical module or alias in ctx.

func (*Registry) RegisterNativeModule

func (r *Registry) RegisterNativeModule(name string, loader NativeLoader) error

RegisterNativeModule maps a native CommonJS module to a host loader. Names without a node: prefix automatically receive the corresponding node: alias.

func (*Registry) Require

func (r *Registry) Require(ctx *quickjs.Context, parent, specifier string) (*quickjs.Value, error)

Require resolves and loads a module from a CommonJS parent filename. The returned Value is owned by the caller and must be freed on the owner thread.

type RegistryOption

type RegistryOption func(*Registry)

RegistryOption configures source and native module behavior.

func WithBaseDir

func WithBaseDir(base string) RegistryOption

WithBaseDir sets the base directory for top-level relative requires.

func WithGlobalFolders

func WithGlobalFolders(folders ...string) RegistryOption

WithGlobalFolders appends package search roots used after local node_modules lookup.

func WithPathResolver

func WithPathResolver(resolver PathResolver) RegistryOption

WithPathResolver installs the canonical path resolver used by CommonJS.

func WithSourceLoader

func WithSourceLoader(loader SourceLoader) RegistryOption

WithSourceLoader installs the host-controlled source reader used by CommonJS. A nil loader disables path-backed source loading.

type RequireModule

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

RequireModule is a context-bound CommonJS facade returned by Enable. Values returned by Require are owned by the caller and must be released on the owner goroutine.

func (*RequireModule) Require

func (m *RequireModule) Require(specifier string) (*quickjs.Value, error)

Require resolves a module from this facade's top-level base directory.

type SourceLoader

type SourceLoader func(filename string) ([]byte, error)

SourceLoader returns source bytes for a canonical module path. Hosts should return ErrModuleNotFound for paths that are not readable modules.

Jump to

Keyboard shortcuts

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