JavaScript / TypeScript API

The programmatic surface of the guchho package.

import { build, transform, pack, serve, watch } from 'guchho'

The package runs the same native engine as the command line, over a long-lived service process. Everything is asynchronous; there are deliberately no …Sync functions, because each would have to block the thread until a child process answers.

Functions

Function	Page	Does
`build(options)`	#build	Builds a project.
`transform(code, options)`	#transform	Transforms one piece of source.
`pack(options)`	#pack	Writes an archive from files on disk.
`context(options)`	#context	Sets up a build that can be repeated.
`analyze(options)`	#analyze	Analyses a build without writing it.
`analyzeMetafile(metafile)`	#analyzemetafile	Pretty-prints a metafile.
`watch(options)`	#watch	Starts watching a build.
`serve(options)`	#serve	Starts a dev server on a build.
`stop()`	#stop	Ends the service process.
`version`	#version	The package version, as a string.

The compiler API

Function	Does
`lexer(input, options)`	Runs the engine's lexer.
`parse(input, options)`	Runs the engine's parser, returning a handle.
`print(ast, options)`	Prints a parsed tree back to source.

Classes

Class	Page
`BuildFailure`	A build that failed.
`ServiceError`	The service could not be reached or answered.
`BuildContext`	A repeatable build.
`Watcher`	A running watcher.
`DevServer`	A running dev server.

build

function build(options: BuildOptions): Promise<BuildResult>
function build(options: BuildOptions[]): Promise<BuildResult[]>

An array builds each configuration and answers with one result per configuration, in the order given. Throws a BuildFailure when a build failed.

transform

function transform(
  code: string | Uint8Array,
  options?: TransformOptions
): Promise<TransformResult>

pack

function pack(options: PackOptions): Promise<PackResult>

Everything the command line's guchho pack does, reached as a function: the same entry naming, symlink policy and collision refusal - but a path and a size come back as data rather than a line on a terminal.

context

function context(options: BuildOptions): Promise<BuildContext>

Holds everything the engine learned reading the project, which makes the second build cheaper than the first.

analyze

function analyze(options?: BuildOptions | BuildOptionsNested): Promise<AnalysisReport>

Runs the build with write: false and leaves the project as it found it. The numbers come from the metafile the engine already writes, so this is the bundler's own graph rather than a second opinion from a scanner.

analyzeMetafile

function analyzeMetafile(metafile: Metafile | string): Promise<string>

watch

function watch(options?: BuildOptions): Promise<Watcher>

The opening build has already run by the time this resolves. The events are not a push: a changed file is not reported until something asks for a rebuild. See the Watcher class.

serve

function serve(options?: BuildOptions): Promise<DevServer>

Resolves once the server is listening over a finished build. Uses the engine's own HTTP server - the one guchho serve gets.

stop

function stop(): Promise<void>

Await this before removing a build's output directory: while the process is alive it has those files open, and on Windows removing them fails.

version

const version: string

Read once from the manifest the package was installed as.

Generated reference

The generated reference is produced from package/npm/guchho/index.d.ts and covers every option and type exactly.