transformer

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Jul 20, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package transformer provides file-level and directory-level HTML transformation, walking HTML files on disk and expanding custom elements using the QJS rendering engine.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RenderFragment

func RenderFragment(input string, registry *jsengine.Registry, opts ...RenderOpts) (string, error)

RenderFragment renders an HTML fragment.

func RenderFragmentWithEngine

func RenderFragmentWithEngine(input string, engine ElementRenderer, registry *jsengine.Registry, ignored map[string]bool, quiet ...bool) (string, error)

RenderFragmentWithEngine renders an HTML fragment using a caller-provided engine, avoiding engine creation overhead.

func RenderHTML

func RenderHTML(input string, registry *jsengine.Registry, opts ...RenderOpts) (string, error)

RenderHTML takes an HTML string, finds custom elements, and returns the transformed HTML with Declarative Shadow DOM.

func RenderHTMLWithEngine

func RenderHTMLWithEngine(input string, engine ElementRenderer, registry *jsengine.Registry, ignored map[string]bool, quiet ...bool) (string, error)

RenderHTMLWithEngine transforms HTML using a caller-provided engine, avoiding engine creation overhead. Use this when you have a long-lived engine (e.g. in a Renderer).

Types

type ElementRenderer

type ElementRenderer interface {
	LoadBundleForTag(tagName string, registry *jsengine.Registry) (bool, error)
	RenderBatch(requests []jsengine.BatchRequest) ([]jsengine.BatchResult, error)
	IsRegistered(tagName string) bool
}

ElementRenderer is the interface the transformer uses to load and render custom elements. *jsengine.Engine satisfies this interface. Defining it here decouples the HTML expansion logic from the concrete QJS runtime, allowing mock implementations in tests.

type Options

type Options struct {
	// DefsDir is the directory containing .golit.bundle.js files (Mode 1).
	DefsDir string

	// CompiledFile is a path to a single .golit.compiled.js artifact
	// containing all bundles and a tag registry manifest.
	CompiledFile string

	// SourcesDir is a directory of component .js/.ts source files to bundle
	// on-demand (Mode 2).
	SourcesDir string

	// ImportMapFile is a path to an import map JSON file (Mode 3).
	ImportMapFile string

	// AutoDiscover enables HTML auto-discovery of <script type="importmap">
	// and <script type="module"> tags (Mode 4). Enabled by default when
	// no other discovery mode is specified.
	AutoDiscover bool

	// Ignored is a set of custom element tag names to skip during SSR.
	// These elements will be left as-is for client-side rendering only.
	Ignored map[string]bool

	// Preload is a list of extra JS modules to bundle and load into the
	// QJS engine before component rendering. Each entry is a bare module
	// specifier (e.g. "prism-esm") or a file path.
	Preload []string

	// Verbose prints progress information to stderr.
	Verbose bool

	// Quiet suppresses warnings to stderr (e.g. unregistered elements,
	// render failures). Only errors are emitted.
	Quiet bool

	// DryRun reads and transforms files but does not write them back.
	DryRun bool

	// Concurrency is the number of parallel workers for file processing.
	// 0 or 1 means sequential (default). Set to runtime.NumCPU() or
	// a specific value for parallel processing of large sites.
	Concurrency int

	// OutDir is an optional output directory. When set, transformed files
	// are written here instead of modifying the input files in-place.
	OutDir string

	// Isolate creates a fresh QJS context per HTML file, clearing all
	// global state between files. Slower but safer for untrusted components.
	Isolate bool

	// Registry is an optional pre-populated bundle registry. When set,
	// TransformDir uses it instead of creating a new one. Additional
	// discovery modes (DefsDir, SourcesDir, etc.) still layer onto it.
	Registry *jsengine.Registry
}

Options configures the transformer.

type RenderError

type RenderError struct {
	TagName string
	File    string
	Err     error
}

RenderError records a custom element that failed to render during SSR.

func (RenderError) Error

func (e RenderError) Error() string

type RenderOpts

type RenderOpts struct {
	Ignored map[string]bool
	Quiet   bool
}

RenderOpts configures optional behavior for RenderHTML and RenderFragment.

type Result

type Result struct {
	FilesProcessed int
	FilesModified  int
	Errors         []error
	RenderErrors   []RenderError
	Unregistered   []string
}

Result holds stats from a transform run.

func TransformDir

func TransformDir(dir string, opts Options) (*Result, error)

TransformDir processes all HTML files in a directory tree.

Processing happens in two passes:

  1. Discovery (sequential): read every HTML file and run component auto-discovery so the registry is fully populated.
  2. Render (parallel when Concurrency > 1): transform files using a pool of QJS engines, one engine per worker goroutine.

Jump to

Keyboard shortcuts

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