@zuke/node

`@zuke/node` — typed Node.js task wrappers for Zuke builds.

Symbols

NodeEvalSettings

class

class NodeEvalSettings extends NodeSettings

Settings for node [options] --eval <code>.

Member	Signature	Doc
`code`	`code(source: string): this`	The JavaScript source to evaluate (required).
`requireModule`	`requireModule(...modules: string[]): this`	Preload a CommonJS module before evaluating (`--require <m>`); repeatable.
`importModule`	`importModule(...modules: string[]): this`	Preload an ES module before evaluating (`--import <m>`); repeatable.
`print`	`print(): this`	Print the result of the evaluated code (`--print` instead of `--eval`).

NodeEvaluateSettings

class

class NodeEvaluateSettings extends NodeSettings

Settings for "./node.ts".NodeTasks.evaluate — which export of the module to take, and what to call it with.

Member	Signature	Doc
`export`	`export(name: string): this`	The named export to take, instead of the default one. The export is awaited; when it is a function it is called first, with `callWith`'s arguments.
`callWith`	`callWith(...values: JsonValue[]): this`	Arguments for the exported function, in order. Each must be JSON-serialisable — they cross a process boundary as JSON. Named `callWith` rather than `args` because `ToolSettings.args` already means "append raw arguments to the `node` command line", which is a different thing.
`exitAfterResult`	`exitAfterResult(): this`	End the Node process as soon as the result has been written, instead of waiting for the module to let Node exit on its own. A module that leaves a live handle on the event loop — an HTTP server, a database pool, a timer — never exits, and the evaluation then blocks forever on a value it has already produced and written. This makes the driver exit once that write has flushed, so such a module can be evaluated as it is, without a `process.exit` of its own. What the module does after handing back its value does not happen. The process ends at the write, so anything it would still print is cut off, anything it would still do — a `beforeExit` handler, a teardown scheduled on the next tick, a flush that has not been awaited — does not run, and its own exit code is no longer observed (the driver exits `0`). That is the trade the option makes, and why it is opt-in rather than the default: choose it for a module whose value is the whole point of running it, and whose remaining work is process teardown the operating system is about to do anyway. A module whose after-the-value work matters — one that writes a file, commits a transaction, or reports its own failure through an exit code — should keep the default and be given a way to exit on its own. Two shapes are unaffected either way: a module that throws before producing a result still rejects the evaluation, since the driver never reaches its final write, and a module that exits on its own never notices the option.
`module`	`module(): string`	The module being evaluated, for error messages.

NodeRunSettings

class

class NodeRunSettings extends NodeSettings

Settings for node [options] <script> [args].

Member	Signature	Doc
`script`	`script(path: PathLike): this`	The script to execute (required).
`scriptArgs`	`scriptArgs(...args: Array<string \| number>): this`	Arguments passed to the script (after the script path).
`requireModule`	`requireModule(...modules: string[]): this`	Preload a CommonJS module before the script (`--require <m>`); repeatable.
`importModule`	`importModule(...modules: string[]): this`	Preload an ES module before the script (`--import <m>`); repeatable.
`conditions`	`conditions(...names: string[]): this`	Custom export conditions to resolve (`--conditions <c>`); repeatable.
`envFile`	`envFile(path: PathLike): this`	Load environment variables from a file (`--env-file=<p>`).
`watch`	`watch(): this`	Restart the process on file changes (`--watch`).
`watchPath`	`watchPath(...paths: PathLike[]): this`	Additional paths to watch (`--watch-path <p>`); repeatable.
`enableSourceMaps`	`enableSourceMaps(): this`	Enable Source Map V3 support for stack traces (`--enable-source-maps`).
`inspect`	`inspect(): this`	Activate the inspector (`--inspect`).
`inspectBrk`	`inspectBrk(): this`	Activate the inspector and break before user code starts (`--inspect-brk`).
`maxOldSpaceSize`	`maxOldSpaceSize(megabytes: number): this`	Set the V8 old-space memory limit in MiB (`--max-old-space-size=<n>`).

NodeSettings

class

class NodeSettings extends ToolSettings

Shared base for every node task: it pins the binary to node.

NodeTasks

const

const NodeTasks: NodeTasksApi

Typed task functions for the Node.js runtime node.

NodeTasksApi

interface

interface NodeTasksApi

The shape of NodeTasks.

Member	Signature	Doc
`run`	`run(configure?: Configure<NodeRunSettings>): Promise<CommandOutput>`	Run a script: `node [options] <script> [args]`.
`eval`	`eval(configure?: Configure<NodeEvalSettings>): Promise<CommandOutput>`	Evaluate inline code: `node --eval <code>`.
`test`	`test(configure?: Configure<NodeTestSettings>): Promise<CommandOutput>`	Run the built-in test runner: `node --test`.
`evaluate`	`evaluate(module: PathLike, configure?: Configure<NodeEvaluateSettings>): Promise<JsonValue>`	Import a Node module and resolve to one of its exports' JSON value — the way a target reads something out of the Node side of a project (an OpenAPI document, a resolved config) instead of shelling out to a script that has to write it somewhere first. `module` is a path, resolved against the working directory. The export (`default` unless `NodeEvaluateSettings.export` names another) is awaited; when it is a function it is called with `NodeEvaluateSettings.callWith`'s arguments first. ```ts // tools/openapi.mjs: export default async () => document const spec = await NodeTasks.evaluate("tools/openapi.mjs");` ` The evaluation waits for the Node process to exit, so a module that leaves a live handle on the event loop (a server, a pool, a timer) would block on a value it has already produced. NodeEvaluateSettings.exitAfterResult ends the process as soon as the result has been written, for modules in that shape. The module runs as a real Node process with the build's own permissions — the same trust level as a script handed to NodeTasks.run, and the reason this is a build-authoring API rather than an input-processing one. module` is code: build it from a literal or from the project's own layout, never from an untrusted source (a pull request title, a webhook payload), exactly as for every other command a build spawns. Values passed through `NodeEvaluateSettings.callWith` cannot inject into the driver — they are embedded as JSON literals — but they do reach the module, so whatever the module does with them is the module's contract to uphold.

NodeTestSettings

class

class NodeTestSettings extends NodeSettings

Settings for node --test [paths] [flags].

Member	Signature	Doc
`paths`	`paths(...values: PathLike[]): this`	Test files or directories to run (positional); repeatable.
`testNamePattern`	`testNamePattern(value: string): this`	Run only tests whose name matches the pattern (`--test-name-pattern <v>`).
`testReporter`	`testReporter(value: string): this`	Select the test reporter (`--test-reporter <v>`).
`testConcurrency`	`testConcurrency(value: number): this`	Maximum number of test files to run concurrently (`--test-concurrency <n>`).
`only`	`only(): this`	Run only tests marked with the `only` option (`--test-only`).
`watch`	`watch(): this`	Re-run tests on file changes (`--watch`).
`experimentalTestCoverage`	`experimentalTestCoverage(): this`	Collect and report test coverage (`--experimental-test-coverage`).