bldr

The core build API: artifacts, pods, images, scopes and targets.

Import from bldr in a .bldr.ts. Generated from the module's TypeScript.

Contents

Types

Each has its own page.

AllOfPipelineCondition

class

Conjunction of conditions.

.constructor(conditions: PipelineCondition[])

constructor

constructor(conditions: PipelineCondition[]): AllOfPipelineCondition

See PipelineCondition.

conditions: readonly PipelineCondition[]

property

See PipelineCondition.

.allOf(...conditions: PipelineCondition[])

static method

Holds when every one of conditions holds (none: always holds).

allOf(...conditions: PipelineCondition[]): AllOfPipelineCondition

See PipelineCondition.

.anyOf(...conditions: PipelineCondition[])

static method

Holds when at least one of conditions holds (none: never holds).

anyOf(...conditions: PipelineCondition[]): AnyOfPipelineCondition

See AnyOfPipelineCondition, PipelineCondition.

.noneOf(...conditions: PipelineCondition[])

static method

Holds when none of conditions hold — not(anyOf(…)), spelled the way a reader thinks it.

noneOf(...conditions: PipelineCondition[]): NotPipelineCondition

See NotPipelineCondition, PipelineCondition.

.not(condition: PipelineCondition)

static method

Holds when condition does not.

not(condition: PipelineCondition): NotPipelineCondition

See NotPipelineCondition, PipelineCondition.

AnyOfPipelineCondition

class

Disjunction of conditions.

.constructor(conditions: PipelineCondition[])

constructor

constructor(conditions: PipelineCondition[]): AnyOfPipelineCondition

See PipelineCondition.

conditions: readonly PipelineCondition[]

property

See PipelineCondition.

.allOf(...conditions: PipelineCondition[])

static method

Holds when every one of conditions holds (none: always holds).

allOf(...conditions: PipelineCondition[]): AllOfPipelineCondition

See AllOfPipelineCondition, PipelineCondition.

.anyOf(...conditions: PipelineCondition[])

static method

Holds when at least one of conditions holds (none: never holds).

anyOf(...conditions: PipelineCondition[]): AnyOfPipelineCondition

See PipelineCondition.

.noneOf(...conditions: PipelineCondition[])

static method

Holds when none of conditions hold — not(anyOf(…)), spelled the way a reader thinks it.

noneOf(...conditions: PipelineCondition[]): NotPipelineCondition

See NotPipelineCondition, PipelineCondition.

.not(condition: PipelineCondition)

static method

Holds when condition does not.

not(condition: PipelineCondition): NotPipelineCondition

See NotPipelineCondition, PipelineCondition.

Artifact

class

A content-addressed build artifact: a lazy, memoized computation of a CID.

Composition on the subclasses is synchronous and builds a graph; nothing runs until the artifact is forced. Force with cid (or the inherited get(), which it aliases).

.constructor(source: ArtifactSource, labelHint?: string)

constructor

constructor(source: ArtifactSource, labelHint?: string): Artifact

See ArtifactSource.

nodeLabel

accessor

shape

accessor

valueScope

accessor

.cid(inherited?: TaskSlot)

method

Force and return this artifact's CID. Alias of the inherited get(), kept because .cid() reads better at a build's call sites. inherited is passed by a consuming composition step — see Lazy.get.

cid(inherited?: TaskSlot): Promise<string>

.dependsOn(...deps: unknown[])

method

Record what this value is waiting on.

Only values that are somewhere in the tree count — something with no node and no scope is nothing a reader could go and look at. Accepts anything so callers can pass a mixed bag of inputs (a CID string, a member) without filtering.

dependsOn(...deps: unknown[]): this

.get(inherited?: TaskSlot)

method

Force the computation (memoized — subsequent calls reuse the result).

inherited is the node of the value being computed from this one. An intermediate step of a composition — the resolve in dir.resolve(…).filterGlob(…).in(scope) — has no scope of its own and is private to that chain, so it belongs wherever its consumer went. A value with its own scope ignores the offer and stays where it was placed.

Since the result is memoised, a shared unscoped value keeps whichever parent forced it first. That is the ambiguity Scope exists to resolve: give a value used in two places its own scope and it stops floating.

get(inherited?: TaskSlot): Promise<string>

.in(scope: Scope)

method

Place this value's work in scope.

Fixed at declaration time, so a value shared by several consumers appears once, where its owner put it — not under whichever consumer forced it first. Derived values (map, artifact composition) inherit it.

in(scope: Scope): this

See Scope.

.map(f: (…) => …)

method

Derive a new lazy value from this one without forcing it now. Inherits this value's scope, so composition stays in the subtree that owns it.

map(f: (…) => …): Lazy<U>

.dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …)

static method

A dynamic artifact: one whose subgraph cannot be known until deps have resolved, because deciding what to build requires reading them.

Called on the concrete class, which is what types the result:

const crates = Directory.dynamic("compile each crate", [src], async () =>
    Directory.merge(...(await src.entries()).map(([n, e]) => compile(n, e))))
    .in(scope);

label is what this node is called in the build tree — the one thing a dynamic node cannot derive, since it runs no node function of its own. Where it goes is [in][Lazy.in]'s business, like every other value; a dynamic artifact with no scope groups its expansion under whichever consumer forces it.

This is the only asynchronous surface in the API: everything else composes synchronously. The graph has a hole inside a dynamic node, but every edge around it is static — the returned handle is an ordinary artifact, so downstream work is declared normally.

deps are forced before expand runs, and are the node's declared dependency edges.

dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …): T

See ArtifactSource.

.expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …)

static method

A value whose subgraph is decided once deps have resolved: expand is called with their values and returns the value this one stands for. label names the node, since it runs no node function of its own.

expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …): Lazy<T>

.node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …)

static method

The output of node function fn on the input input builds from the resolved deps. The value is the output block's CID; read a field of it with map.

node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …): Lazy<string>

.of(value: T)

static method

Already-resolved value.

of(value: T): Lazy<T>

buildArchitecture()

function

The architecture this build's own pods run on: the node's, as published in the build's options, or amd64 under a daemon that does not fill it in.

What a tool defaults to when it must pick one platform of a multi-architecture image to run: an image for another architecture does not start (exec format error). A tool that produces something for another architecture names it instead.

buildArchitecture(): string

cacheVolume(name: string, opts?: CacheVolumeOptions)

function

Declare a cache volume named name, namespaced by opts.scope if given.

Two calls with the same resulting name are the same volume — that is the point, and it is why the namespacing is explicit rather than automatic: a volume shared on purpose and one shared by accident look identical afterwards.

cacheVolume(name: string, opts?: CacheVolumeOptions): CacheVolume

See CacheVolume, CacheVolumeOptions.

CacheVolume

class

A named cache volume, mountable into a pod with Pod.cache.

const downloads = cacheVolume("npm-cache");                       // global
const target = cacheVolume("target", { scope, mode: "exclusive" }); // per-crate
pod.cache(downloads, "/tmp/.npm-cache").cache(target, "/work/target");

.constructor(name: string, mode: CacheMode, perImage: boolean)

constructor

constructor(name: string, mode: CacheMode, perImage: boolean): CacheVolume

See CacheMode.

mode: CacheMode

property

See CacheMode.

name: string

property

The volume's full name — what the daemon keys the workspace's cache on.

perImage: boolean

property

Whether each rootfs image gets its own copy — see CacheVolumeOptions.perImage.

exclusive

accessor

claim(path: string, kind: string)

function

Claim path for one kind of registration, or say who already has it.

Names are checked across every kind, not per-kind: bldr/daemon/docs as both an output and a test would be two different things reachable by one name, and which one a caller got would depend on which map was searched first. One name, one thing.

claim(path: string, kind: string): void

Compression: { … }

variable

Constructors for the supported codecs.

ContainerImage

class

A content-addressed build artifact: a lazy, memoized computation of a CID.

Composition on the subclasses is synchronous and builds a graph; nothing runs until the artifact is forced. Force with cid (or the inherited get(), which it aliases).

.constructor(image: string | Lazy<string>, arch?: string, overrides?: Overrides)

constructor

image is a manifest CID (or a lazy one). arch selects the platform for a multi-arch image and is fixed for this image and all images derived from it. overrides is internal (carried through the chain).

constructor(image: string | Lazy<string>, arch?: string, overrides?: Overrides): ContainerImage

architecture

accessor

nodeLabel

accessor

shape

accessor

valueScope

accessor

.add(src: Directory, dest: string)

method

ADD — like copy for a local tree. (URL sources and tar auto-extraction are not supported; use copy + run tar.)

add(src: Directory, dest: string): ContainerImage

See Directory.

.arg(key: string, value?: string)

method

ARG — a build-time variable (available to mapConfig callbacks via buildArgs; not persisted to the image).

arg(key: string, value?: string): ContainerImage

.buildArgs()

method

The build-time args set so far (for use in derived logic).

buildArgs(): Record<string, string>

.cid(inherited?: TaskSlot)

method

Force and return this artifact's CID. Alias of the inherited get(), kept because .cid() reads better at a build's call sites. inherited is passed by a consuming composition step — see Lazy.get.

cid(inherited?: TaskSlot): Promise<string>

.cmd(argv: string[])

method

CMD (exec form).

cmd(argv: string[]): ContainerImage

.config()

method

The effective config (base image config with this image's overrides merged).

Memoized and placed, which is the only combination that is honest. The value is read once and shared by every consumer (pod, run, layers, build code), so an unplaced one would be attributed to whichever of them won the race to force it — the very mis-attribution ContainerImage.fromMember places the image to avoid. Placing it in the image's scope makes the winner irrelevant: a Lazy with a scope of its own ignores the slot a consumer offers. An image with no scope keeps the old behaviour, because there is nothing better to say.

config(): Value<ImageConfigInfo>

See ImageConfigInfo, Value.

.copy(src: Directory, dest: string)

method

COPY — the tree src becomes a new layer at dest (its contents land under dest). Lazy.

A content-level graft (fs.at), not a pod: the layer is src placed under dest, with its modes and symlinks as they are. No process runs, which is what lets an image for another architecture be assembled on this one — a cp inside an arm64 rootfs would need an arm64 CPU.

copy(src: Directory, dest: string): ContainerImage

See Directory.

.dependsOn(...deps: unknown[])

method

Record what this value is waiting on.

Only values that are somewhere in the tree count — something with no node and no scope is nothing a reader could go and look at. Accepts anything so callers can pass a mixed bag of inputs (a CID string, a member) without filtering.

dependsOn(...deps: unknown[]): this

.entrypoint(argv: string[])

method

ENTRYPOINT (exec form).

entrypoint(argv: string[]): ContainerImage

.env(key: string, value: string)

method

ENV KEY VALUE.

env(key: string, value: string): ContainerImage

.envAll(vars: Record<string, string>)

method

ENV for several variables at once.

envAll(vars: Record<string, string>): ContainerImage

.expose(...ports: string[])

method

EXPOSE — document a port ("8080" or "8080/tcp").

expose(...ports: string[]): ContainerImage

.fromOci()

method

Convert to bldr's native layer form: every .tar blob layer is untarred into an FsNode (cheap to build on / diff / hot-swap). The inverse of toOci. (oci.image.from-oci.)

fromOci(): ContainerImage

.get(inherited?: TaskSlot)

method

Force the computation (memoized — subsequent calls reuse the result).

inherited is the node of the value being computed from this one. An intermediate step of a composition — the resolve in dir.resolve(…).filterGlob(…).in(scope) — has no scope of its own and is private to that chain, so it belongs wherever its consumer went. A value with its own scope ignores the offer and stays where it was placed.

Since the result is memoised, a shared unscoped value keeps whichever parent forced it first. That is the ambiguity Scope exists to resolve: give a value used in two places its own scope and it stops floating.

get(inherited?: TaskSlot): Promise<string>

.in(scope: Scope)

method

Place this value's work in scope.

Fixed at declaration time, so a value shared by several consumers appears once, where its owner put it — not under whichever consumer forced it first. Derived values (map, artifact composition) inherit it.

in(scope: Scope): this

See Scope.

.label(key: string, value: string)

method

LABEL key=value.

label(key: string, value: string): ContainerImage

.labels(map: Record<string, string>)

method

LABEL for several labels at once.

labels(map: Record<string, string>): ContainerImage

.layers()

method

The ordered layer list (base-first).

layers(): Value<LayerInfo[]>

See LayerInfo, Value.

.map(f: (…) => …)

method

Derive a new lazy value from this one without forcing it now. Inherits this value's scope, so composition stays in the subtree that owns it.

map(f: (…) => …): Lazy<U>

.mapConfig(fn: (…) => …)

method

Read this image's effective config, transform it in the fn callback (running lazily), and write the returned patch back as the image's config. The new image carries the result baked in.

const bumped = img.mapConfig((cfg) => ({
    labels: { ...cfg.labels, "build.n": String(Number(cfg.labels["build.n"] ?? 0) + 1) },
}));

mapConfig(fn: (…) => …): ContainerImage

See ConfigPatch, ImageConfigInfo.

.mapLabels(fn: (…) => …)

method

Read all labels, transform the map in fn, and write the result back. A convenience over mapConfig for the common label case.

const img2 = img.mapLabels((labels) => ({
    ...labels,
    "org.opencontainers.image.revision": gitSha,
}));

mapLabels(fn: (…) => …): ContainerImage

.pod()

method

A Pod over this image's rootfs, pre-seeded with the image's effective env (so PATH etc. apply) and its WORKDIR/USER/SHELL. Set the command and take outputs as usual.

pod(): Pod

See Pod.

.root()

method

The merged root filesystem of the image (layers). (Config does not affect the rootfs.) Placed in this image's scope, like every other derivation of it: materializing a shared base image's rootfs is that image's own work, not the work of the first pod to ask for it.

root(): Directory

See Directory.

.run(command: Command, opts?: RunOptions)

method

RUN — run command over this image's rootfs and append the resulting overlay diff as a new layer. A shell string runs through the image's SHELL/WORKDIR/USER with its ENV applied; an argv runs directly (exec form). Lazy.

The layer's pod has no network unless { internet: true } approves it — see RunOptions.

run(command: Command, opts?: RunOptions): ContainerImage

See Command, RunOptions.

.shell(argv: string[])

method

SHELL — the shell used for run shell-form commands. Build-time.

shell(argv: string[]): ContainerImage

.stopSignal(signal: string)

method

STOPSIGNAL.

stopSignal(signal: string): ContainerImage

.toOci()

method

Convert to the OCI layer form: every native layer (an FsNode overlay diff, as run/copy produce) is tarred + gzipped into a blob with real content digests, and the config's rootfs.diff_ids are rebuilt — a standard, registry-pushable image. (oci.image.to-oci.)

toOci(): ContainerImage

.user(user: string)

method

USER — default user for run (shell form) and the image.

user(user: string): ContainerImage

.volume(...paths: string[])

method

VOLUME — declare a mount point as a volume.

volume(...paths: string[]): ContainerImage

.workdir(dir: string)

method

WORKDIR — default directory for run (shell form) and the image.

workdir(dir: string): ContainerImage

.dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …)

static method

A dynamic artifact: one whose subgraph cannot be known until deps have resolved, because deciding what to build requires reading them.

Called on the concrete class, which is what types the result:

const crates = Directory.dynamic("compile each crate", [src], async () =>
    Directory.merge(...(await src.entries()).map(([n, e]) => compile(n, e))))
    .in(scope);

label is what this node is called in the build tree — the one thing a dynamic node cannot derive, since it runs no node function of its own. Where it goes is [in][Lazy.in]'s business, like every other value; a dynamic artifact with no scope groups its expansion under whichever consumer forces it.

This is the only asynchronous surface in the API: everything else composes synchronously. The graph has a hole inside a dynamic node, but every edge around it is static — the returned handle is an ordinary artifact, so downstream work is declared normally.

deps are forced before expand runs, and are the node's declared dependency edges.

dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …): T

See Artifact, ArtifactSource.

.expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …)

static method

A value whose subgraph is decided once deps have resolved: expand is called with their values and returns the value this one stands for. label names the node, since it runs no node function of its own.

expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …): Lazy<T>

.from(image: string | Lazy<string>, arch?: string)

static method

FROM — start from a base image manifest CID at architecture arch.

from(image: string | Lazy<string>, arch?: string): ContainerImage

.fromMember(member: ImageMemberRef, arch?: string)

static method

FROM an image member — the form to prefer when the base is a workspace member (import rust from "rust").

The image is placed in that member's own scope, so everything derived from it (an apt-get, a copy, the pods those run) lands in the member's subtree. A shared base image has no other honest home: placing it in a consumer's scope would attribute it to whichever member forced it first, and leaving it unplaced strands its work at the tree root.

fromMember(member: ImageMemberRef, arch?: string): ContainerImage

.node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …)

static method

The output of node function fn on the input input builds from the resolved deps. The value is the output block's CID; read a field of it with map.

node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …): Lazy<string>

.of(value: T)

static method

Already-resolved value.

of(value: T): Lazy<T>

Coverage

class

A content-addressed build artifact: a lazy, memoized computation of a CID.

Composition on the subclasses is synchronous and builds a graph; nothing runs until the artifact is forced. Force with cid (or the inherited get(), which it aliases).

.constructor(source: ArtifactSource, labelHint?: string)

constructor

constructor(source: ArtifactSource, labelHint?: string): Coverage

See ArtifactSource.

nodeLabel

accessor

shape

accessor

valueScope

accessor

.cid(inherited?: TaskSlot)

method

Force and return this artifact's CID. Alias of the inherited get(), kept because .cid() reads better at a build's call sites. inherited is passed by a consuming composition step — see Lazy.get.

cid(inherited?: TaskSlot): Promise<string>

.dependsOn(...deps: unknown[])

method

Record what this value is waiting on.

Only values that are somewhere in the tree count — something with no node and no scope is nothing a reader could go and look at. Accepts anything so callers can pass a mixed bag of inputs (a CID string, a member) without filtering.

dependsOn(...deps: unknown[]): this

.get(inherited?: TaskSlot)

method

Force the computation (memoized — subsequent calls reuse the result).

inherited is the node of the value being computed from this one. An intermediate step of a composition — the resolve in dir.resolve(…).filterGlob(…).in(scope) — has no scope of its own and is private to that chain, so it belongs wherever its consumer went. A value with its own scope ignores the offer and stays where it was placed.

Since the result is memoised, a shared unscoped value keeps whichever parent forced it first. That is the ambiguity Scope exists to resolve: give a value used in two places its own scope and it stops floating.

get(inherited?: TaskSlot): Promise<string>

.in(scope: Scope)

method

Place this value's work in scope.

Fixed at declaration time, so a value shared by several consumers appears once, where its owner put it — not under whichever consumer forced it first. Derived values (map, artifact composition) inherit it.

in(scope: Scope): this

See Scope.

.map(f: (…) => …)

method

Derive a new lazy value from this one without forcing it now. Inherits this value's scope, so composition stays in the subtree that owns it.

map(f: (…) => …): Lazy<U>

.dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …)

static method

A dynamic artifact: one whose subgraph cannot be known until deps have resolved, because deciding what to build requires reading them.

Called on the concrete class, which is what types the result:

const crates = Directory.dynamic("compile each crate", [src], async () =>
    Directory.merge(...(await src.entries()).map(([n, e]) => compile(n, e))))
    .in(scope);

label is what this node is called in the build tree — the one thing a dynamic node cannot derive, since it runs no node function of its own. Where it goes is [in][Lazy.in]'s business, like every other value; a dynamic artifact with no scope groups its expansion under whichever consumer forces it.

This is the only asynchronous surface in the API: everything else composes synchronously. The graph has a hole inside a dynamic node, but every edge around it is static — the returned handle is an ordinary artifact, so downstream work is declared normally.

deps are forced before expand runs, and are the node's declared dependency edges.

dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …): T

See Artifact, ArtifactSource.

.expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …)

static method

A value whose subgraph is decided once deps have resolved: expand is called with their values and returns the value this one stands for. label names the node, since it runs no node function of its own.

expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …): Lazy<T>

.fromCid(cid: string)

static method

A Coverage from an existing DataType::CoverageReport CID.

fromCid(cid: string): Coverage

.node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …)

static method

The output of node function fn on the input input builds from the resolved deps. The value is the output block's CID; read a field of it with map.

node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …): Lazy<string>

.of(value: T)

static method

Already-resolved value.

of(value: T): Lazy<T>

DebianContainerImage

class

A Debian/Ubuntu base image, with apt-get spelled once.

Every callsite of apt-get in a build has to remember the same three things: refresh the lists first, refuse recommends, and delete the lists in the same layer — a separate cleanup .run() writes a new layer over the old one and the bytes stay in the image. Writing that by hand at each callsite is how one of them ends up missing a piece.

new DebianContainerImage(ContainerImage.from(DEBIAN))
    .aptInstall(["curl", "ca-certificates"])

Nothing else about the image changes: this is ContainerImage with one extra verb, so .run(), .copy(), .env() and the rest behave exactly as they do on the base class.

.constructor(image: ContainerImage)

constructor

Wrap image — its baked manifest becomes this image's base, so the config it carries (env, workdir, user, shell) comes along.

constructor(image: ContainerImage): DebianContainerImage

See ContainerImage.

architecture

accessor

nodeLabel

accessor

shape

accessor

valueScope

accessor

.add(src: Directory, dest: string)

method

ADD — like copy for a local tree. (URL sources and tar auto-extraction are not supported; use copy + run tar.)

add(src: Directory, dest: string): ContainerImage

See ContainerImage, Directory.

.aptInstall(packageNames: string | string[], opts?: AptInstallOptions)

method

apt-get install as one layer: update, install, and drop the package lists, joined with && so a failure anywhere fails the layer.

The layer's pod is approved for the internet: installing packages is fetching them.

Returns a DebianContainerImage, so installs chain.

aptInstall(packageNames: string | string[], opts?: AptInstallOptions): DebianContainerImage

See AptInstallOptions.

.arg(key: string, value?: string)

method

ARG — a build-time variable (available to mapConfig callbacks via buildArgs; not persisted to the image).

arg(key: string, value?: string): ContainerImage

See ContainerImage.

.buildArgs()

method

The build-time args set so far (for use in derived logic).

buildArgs(): Record<string, string>

.cid(inherited?: TaskSlot)

method

Force and return this artifact's CID. Alias of the inherited get(), kept because .cid() reads better at a build's call sites. inherited is passed by a consuming composition step — see Lazy.get.

cid(inherited?: TaskSlot): Promise<string>

.cmd(argv: string[])

method

CMD (exec form).

cmd(argv: string[]): ContainerImage

See ContainerImage.

.config()

method

The effective config (base image config with this image's overrides merged).

Memoized and placed, which is the only combination that is honest. The value is read once and shared by every consumer (pod, run, layers, build code), so an unplaced one would be attributed to whichever of them won the race to force it — the very mis-attribution ContainerImage.fromMember places the image to avoid. Placing it in the image's scope makes the winner irrelevant: a Lazy with a scope of its own ignores the slot a consumer offers. An image with no scope keeps the old behaviour, because there is nothing better to say.

config(): Value<ImageConfigInfo>

See ImageConfigInfo, Value.

.copy(src: Directory, dest: string)

method

COPY — the tree src becomes a new layer at dest (its contents land under dest). Lazy.

A content-level graft (fs.at), not a pod: the layer is src placed under dest, with its modes and symlinks as they are. No process runs, which is what lets an image for another architecture be assembled on this one — a cp inside an arm64 rootfs would need an arm64 CPU.

copy(src: Directory, dest: string): ContainerImage

See ContainerImage, Directory.

.dependsOn(...deps: unknown[])

method

Record what this value is waiting on.

Only values that are somewhere in the tree count — something with no node and no scope is nothing a reader could go and look at. Accepts anything so callers can pass a mixed bag of inputs (a CID string, a member) without filtering.

dependsOn(...deps: unknown[]): this

.entrypoint(argv: string[])

method

ENTRYPOINT (exec form).

entrypoint(argv: string[]): ContainerImage

See ContainerImage.

.env(key: string, value: string)

method

ENV KEY VALUE.

env(key: string, value: string): ContainerImage

See ContainerImage.

.envAll(vars: Record<string, string>)

method

ENV for several variables at once.

envAll(vars: Record<string, string>): ContainerImage

See ContainerImage.

.expose(...ports: string[])

method

EXPOSE — document a port ("8080" or "8080/tcp").

expose(...ports: string[]): ContainerImage

See ContainerImage.

.fromOci()

method

Convert to bldr's native layer form: every .tar blob layer is untarred into an FsNode (cheap to build on / diff / hot-swap). The inverse of toOci. (oci.image.from-oci.)

fromOci(): ContainerImage

See ContainerImage.

.get(inherited?: TaskSlot)

method

Force the computation (memoized — subsequent calls reuse the result).

inherited is the node of the value being computed from this one. An intermediate step of a composition — the resolve in dir.resolve(…).filterGlob(…).in(scope) — has no scope of its own and is private to that chain, so it belongs wherever its consumer went. A value with its own scope ignores the offer and stays where it was placed.

Since the result is memoised, a shared unscoped value keeps whichever parent forced it first. That is the ambiguity Scope exists to resolve: give a value used in two places its own scope and it stops floating.

get(inherited?: TaskSlot): Promise<string>

.in(scope: Scope)

method

Place this value's work in scope.

Fixed at declaration time, so a value shared by several consumers appears once, where its owner put it — not under whichever consumer forced it first. Derived values (map, artifact composition) inherit it.

in(scope: Scope): this

See Scope.

.label(key: string, value: string)

method

LABEL key=value.

label(key: string, value: string): ContainerImage

See ContainerImage.

.labels(map: Record<string, string>)

method

LABEL for several labels at once.

labels(map: Record<string, string>): ContainerImage

See ContainerImage.

.layers()

method

The ordered layer list (base-first).

layers(): Value<LayerInfo[]>

See LayerInfo, Value.

.map(f: (…) => …)

method

Derive a new lazy value from this one without forcing it now. Inherits this value's scope, so composition stays in the subtree that owns it.

map(f: (…) => …): Lazy<U>

.mapConfig(fn: (…) => …)

method

Read this image's effective config, transform it in the fn callback (running lazily), and write the returned patch back as the image's config. The new image carries the result baked in.

const bumped = img.mapConfig((cfg) => ({
    labels: { ...cfg.labels, "build.n": String(Number(cfg.labels["build.n"] ?? 0) + 1) },
}));

mapConfig(fn: (…) => …): ContainerImage

See ConfigPatch, ContainerImage, ImageConfigInfo.

.mapLabels(fn: (…) => …)

method

Read all labels, transform the map in fn, and write the result back. A convenience over mapConfig for the common label case.

const img2 = img.mapLabels((labels) => ({
    ...labels,
    "org.opencontainers.image.revision": gitSha,
}));

mapLabels(fn: (…) => …): ContainerImage

See ContainerImage.

.pod()

method

A Pod over this image's rootfs, pre-seeded with the image's effective env (so PATH etc. apply) and its WORKDIR/USER/SHELL. Set the command and take outputs as usual.

pod(): Pod

See Pod.

.root()

method

The merged root filesystem of the image (layers). (Config does not affect the rootfs.) Placed in this image's scope, like every other derivation of it: materializing a shared base image's rootfs is that image's own work, not the work of the first pod to ask for it.

root(): Directory

See Directory.

.run(command: Command, opts?: RunOptions)

method

RUN — run command over this image's rootfs and append the resulting overlay diff as a new layer. A shell string runs through the image's SHELL/WORKDIR/USER with its ENV applied; an argv runs directly (exec form). Lazy.

The layer's pod has no network unless { internet: true } approves it — see RunOptions.

run(command: Command, opts?: RunOptions): ContainerImage

See Command, ContainerImage, RunOptions.

.shell(argv: string[])

method

SHELL — the shell used for run shell-form commands. Build-time.

shell(argv: string[]): ContainerImage

See ContainerImage.

.stopSignal(signal: string)

method

STOPSIGNAL.

stopSignal(signal: string): ContainerImage

See ContainerImage.

.toOci()

method

Convert to the OCI layer form: every native layer (an FsNode overlay diff, as run/copy produce) is tarred + gzipped into a blob with real content digests, and the config's rootfs.diff_ids are rebuilt — a standard, registry-pushable image. (oci.image.to-oci.)

toOci(): ContainerImage

See ContainerImage.

.user(user: string)

method

USER — default user for run (shell form) and the image.

user(user: string): ContainerImage

See ContainerImage.

.volume(...paths: string[])

method

VOLUME — declare a mount point as a volume.

volume(...paths: string[]): ContainerImage

See ContainerImage.

.workdir(dir: string)

method

WORKDIR — default directory for run (shell form) and the image.

workdir(dir: string): ContainerImage

See ContainerImage.

.aptInstallScript(packageNames: string | string[], opts?: AptInstallOptions)

static method

The same shell one-liner aptInstall runs, for the callsites that cannot take it as a layer of its own.

Some images install packages in the middle of a longer script — after writing an apt.conf.d fragment the install depends on, or with a tolerated failure the surrounding steps recover from. Splitting those into three layers to use the method would cost two extra pods and change what is cached, so they compose the string instead and keep one .run() — which has to pass { internet: true } itself, since the script fetches.

aptInstallScript(packageNames: string | string[], opts?: AptInstallOptions): string

See AptInstallOptions.

.dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …)

static method

A dynamic artifact: one whose subgraph cannot be known until deps have resolved, because deciding what to build requires reading them.

Called on the concrete class, which is what types the result:

const crates = Directory.dynamic("compile each crate", [src], async () =>
    Directory.merge(...(await src.entries()).map(([n, e]) => compile(n, e))))
    .in(scope);

label is what this node is called in the build tree — the one thing a dynamic node cannot derive, since it runs no node function of its own. Where it goes is [in][Lazy.in]'s business, like every other value; a dynamic artifact with no scope groups its expansion under whichever consumer forces it.

This is the only asynchronous surface in the API: everything else composes synchronously. The graph has a hole inside a dynamic node, but every edge around it is static — the returned handle is an ordinary artifact, so downstream work is declared normally.

deps are forced before expand runs, and are the node's declared dependency edges.

dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …): T

See Artifact, ArtifactSource.

.expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …)

static method

A value whose subgraph is decided once deps have resolved: expand is called with their values and returns the value this one stands for. label names the node, since it runs no node function of its own.

expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …): Lazy<T>

.from(image: string | Lazy<string>, arch?: string)

static method

FROM — start from a base image manifest CID at architecture arch.

from(image: string | Lazy<string>, arch?: string): ContainerImage

See ContainerImage.

.fromMember(member: ImageMemberRef, arch?: string)

static method

FROM an image member — the form to prefer when the base is a workspace member (import rust from "rust").

The image is placed in that member's own scope, so everything derived from it (an apt-get, a copy, the pods those run) lands in the member's subtree. A shared base image has no other honest home: placing it in a consumer's scope would attribute it to whichever member forced it first, and leaving it unplaced strands its work at the tree root.

fromMember(member: ImageMemberRef, arch?: string): ContainerImage

See ContainerImage.

.node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …)

static method

The output of node function fn on the input input builds from the resolved deps. The value is the output block's CID; read a field of it with map.

node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …): Lazy<string>

.of(value: T)

static method

Already-resolved value.

of(value: T): Lazy<T>

DEFAULT_ARCHITECTURE_OPTION: "bldr.default-architecture"

variable

The workspace option the node fills in with its host architecture.

defaultArchitecture(options: unknown)

function

The architecture this build is for, in OCI spelling ("amd64", "arm64").

const arch = defaultArchitecture(input.options);
const img = new ContainerImage(base, arch);

undefined when the build runs against a daemon old enough not to fill the option in — treat that as "unknown", and fall back to whatever the build assumed before it could ask.

defaultArchitecture(options: unknown): string

Deployment

class

A content-addressed build artifact: a lazy, memoized computation of a CID.

Composition on the subclasses is synchronous and builds a graph; nothing runs until the artifact is forced. Force with cid (or the inherited get(), which it aliases).

.constructor(source: ArtifactSource | DeploymentSpec, labelHint?: string)

constructor

A deployment authored in place — new Deployment({ function: "deployment/local.shell/v0.0.0", … }).

The ArtifactSource form is what fromCid and Artifact.dynamic use to wrap an existing CID; build code writes the spec form.

constructor(source: ArtifactSource | DeploymentSpec, labelHint?: string): Deployment

See ArtifactSource, DeploymentSpec.

COMPOSITE_FUNCTION: "deployment/composite/v0.0.0"

static property

The composite deployment function: runs other deployments as one.

nodeLabel

accessor

shape

accessor

valueScope

accessor

.cid(inherited?: TaskSlot)

method

Force and return this artifact's CID. Alias of the inherited get(), kept because .cid() reads better at a build's call sites. inherited is passed by a consuming composition step — see Lazy.get.

cid(inherited?: TaskSlot): Promise<string>

.dependsOn(...deps: unknown[])

method

Record what this value is waiting on.

Only values that are somewhere in the tree count — something with no node and no scope is nothing a reader could go and look at. Accepts anything so callers can pass a mixed bag of inputs (a CID string, a member) without filtering.

dependsOn(...deps: unknown[]): this

.get(inherited?: TaskSlot)

method

Force the computation (memoized — subsequent calls reuse the result).

inherited is the node of the value being computed from this one. An intermediate step of a composition — the resolve in dir.resolve(…).filterGlob(…).in(scope) — has no scope of its own and is private to that chain, so it belongs wherever its consumer went. A value with its own scope ignores the offer and stays where it was placed.

Since the result is memoised, a shared unscoped value keeps whichever parent forced it first. That is the ambiguity Scope exists to resolve: give a value used in two places its own scope and it stops floating.

get(inherited?: TaskSlot): Promise<string>

.in(scope: Scope)

method

Place this value's work in scope.

Fixed at declaration time, so a value shared by several consumers appears once, where its owner put it — not under whichever consumer forced it first. Derived values (map, artifact composition) inherit it.

in(scope: Scope): this

See Scope.

.map(f: (…) => …)

method

Derive a new lazy value from this one without forcing it now. Inherits this value's scope, so composition stays in the subtree that owns it.

map(f: (…) => …): Lazy<U>

.composite(block: CompositeBlock, labels?: Record<string, string>)

static method

A composite deployment authored in place: block as the options of Deployment.COMPOSITE_FUNCTION.

composite(block: CompositeBlock, labels?: Record<string, string>): Deployment

See CompositeBlock.

.dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …)

static method

A dynamic artifact: one whose subgraph cannot be known until deps have resolved, because deciding what to build requires reading them.

Called on the concrete class, which is what types the result:

const crates = Directory.dynamic("compile each crate", [src], async () =>
    Directory.merge(...(await src.entries()).map(([n, e]) => compile(n, e))))
    .in(scope);

label is what this node is called in the build tree — the one thing a dynamic node cannot derive, since it runs no node function of its own. Where it goes is [in][Lazy.in]'s business, like every other value; a dynamic artifact with no scope groups its expansion under whichever consumer forces it.

This is the only asynchronous surface in the API: everything else composes synchronously. The graph has a hole inside a dynamic node, but every edge around it is static — the returned handle is an ordinary artifact, so downstream work is declared normally.

deps are forced before expand runs, and are the node's declared dependency edges.

dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …): T

See Artifact, ArtifactSource.

.expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …)

static method

A value whose subgraph is decided once deps have resolved: expand is called with their values and returns the value this one stands for. label names the node, since it runs no node function of its own.

expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …): Lazy<T>

.fromCid(cid: string)

static method

A Deployment from an existing DataType::Deployment CID.

fromCid(cid: string): Deployment

.node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …)

static method

The output of node function fn on the input input builds from the resolved deps. The value is the output block's CID; read a field of it with map.

node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …): Lazy<string>

.of(value: T)

static method

Already-resolved value.

of(value: T): Lazy<T>

.parallel(steps: CompositeStep[])

static method

A block whose steps run concurrently — see CompositeParallel.

parallel(steps: CompositeStep[]): CompositeParallel

See CompositeParallel, CompositeStep.

.sequence(steps: CompositeStep[])

static method

A block whose steps run one after another — see CompositeSequence.

sequence(steps: CompositeStep[]): CompositeSequence

See CompositeSequence, CompositeStep.

.tryCatch(block: CompositeTry)

static method

A try/catch/finally block — see CompositeTry for the outcome rules. An absent catch or finally is left out of the block, so the stored options carry only the phases that exist.

tryCatch(block: CompositeTry): CompositeTry

See CompositeTry.

DeploymentPipelineAction

class

Run a deployment into an environment.

The deployment is stored as a CID link (Ref<Deployment> on the Rust side): the pipeline references the deployment block, it does not embed it — so several steps can share one deployment, and the block stays inspectable on its own. Forcing the pipeline forces the deployment first, since a link needs a CID to point at.

.constructor(environment: Environment, deployment: Deployment)

constructor

constructor(environment: Environment, deployment: Deployment): DeploymentPipelineAction

See Deployment, Environment.

deployment: Deployment

property

See Deployment.

environment: Environment

property

See Environment.

Diagnostics

class

A content-addressed build artifact: a lazy, memoized computation of a CID.

Composition on the subclasses is synchronous and builds a graph; nothing runs until the artifact is forced. Force with cid (or the inherited get(), which it aliases).

.constructor(source: ArtifactSource, labelHint?: string)

constructor

constructor(source: ArtifactSource, labelHint?: string): Diagnostics

See ArtifactSource.

nodeLabel

accessor

shape

accessor

valueScope

accessor

.cid(inherited?: TaskSlot)

method

Force and return this artifact's CID. Alias of the inherited get(), kept because .cid() reads better at a build's call sites. inherited is passed by a consuming composition step — see Lazy.get.

cid(inherited?: TaskSlot): Promise<string>

.dependsOn(...deps: unknown[])

method

Record what this value is waiting on.

Only values that are somewhere in the tree count — something with no node and no scope is nothing a reader could go and look at. Accepts anything so callers can pass a mixed bag of inputs (a CID string, a member) without filtering.

dependsOn(...deps: unknown[]): this

.get(inherited?: TaskSlot)

method

Force the computation (memoized — subsequent calls reuse the result).

inherited is the node of the value being computed from this one. An intermediate step of a composition — the resolve in dir.resolve(…).filterGlob(…).in(scope) — has no scope of its own and is private to that chain, so it belongs wherever its consumer went. A value with its own scope ignores the offer and stays where it was placed.

Since the result is memoised, a shared unscoped value keeps whichever parent forced it first. That is the ambiguity Scope exists to resolve: give a value used in two places its own scope and it stops floating.

get(inherited?: TaskSlot): Promise<string>

.in(scope: Scope)

method

Place this value's work in scope.

Fixed at declaration time, so a value shared by several consumers appears once, where its owner put it — not under whichever consumer forced it first. Derived values (map, artifact composition) inherit it.

in(scope: Scope): this

See Scope.

.map(f: (…) => …)

method

Derive a new lazy value from this one without forcing it now. Inherits this value's scope, so composition stays in the subtree that owns it.

map(f: (…) => …): Lazy<U>

.dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …)

static method

A dynamic artifact: one whose subgraph cannot be known until deps have resolved, because deciding what to build requires reading them.

Called on the concrete class, which is what types the result:

const crates = Directory.dynamic("compile each crate", [src], async () =>
    Directory.merge(...(await src.entries()).map(([n, e]) => compile(n, e))))
    .in(scope);

label is what this node is called in the build tree — the one thing a dynamic node cannot derive, since it runs no node function of its own. Where it goes is [in][Lazy.in]'s business, like every other value; a dynamic artifact with no scope groups its expansion under whichever consumer forces it.

This is the only asynchronous surface in the API: everything else composes synchronously. The graph has a hole inside a dynamic node, but every edge around it is static — the returned handle is an ordinary artifact, so downstream work is declared normally.

deps are forced before expand runs, and are the node's declared dependency edges.

dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …): T

See Artifact, ArtifactSource.

.expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …)

static method

A value whose subgraph is decided once deps have resolved: expand is called with their values and returns the value this one stands for. label names the node, since it runs no node function of its own.

expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …): Lazy<T>

.fromCid(cid: string)

static method

A Diagnostics from an existing DataType::Diagnostics CID.

fromCid(cid: string): Diagnostics

.node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …)

static method

The output of node function fn on the input input builds from the resolved deps. The value is the output block's CID; read a field of it with map.

node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …): Lazy<string>

.of(value: T)

static method

Already-resolved value.

of(value: T): Lazy<T>

Directory

class

A content-addressed build artifact: a lazy, memoized computation of a CID.

Composition on the subclasses is synchronous and builds a graph; nothing runs until the artifact is forced. Force with cid (or the inherited get(), which it aliases).

.constructor(source: ArtifactSource, labelHint?: string)

constructor

constructor(source: ArtifactSource, labelHint?: string): Directory

See ArtifactSource.

nodeLabel

accessor

shape

accessor

valueScope

accessor

.at(path: string)

method

This tree placed under directory path (empty intermediate dirs created) — the inverse of resolve. Pair with merge to graft a subtree into another at a subpath, at the content level (no copies): Directory.merge(client.at("src/gen"), project).

at(path: string): Directory

.cid(inherited?: TaskSlot)

method

Force and return this artifact's CID. Alias of the inherited get(), kept because .cid() reads better at a build's call sites. inherited is passed by a consuming composition step — see Lazy.get.

cid(inherited?: TaskSlot): Promise<string>

.dependsOn(...deps: unknown[])

method

Record what this value is waiting on.

Only values that are somewhere in the tree count — something with no node and no scope is nothing a reader could go and look at. Accepts anything so callers can pass a mixed bag of inputs (a CID string, a member) without filtering.

dependsOn(...deps: unknown[]): this

.diff(other: Directory)

method

Path-level diff against another tree.

diff(other: Directory): Promise<DiffResult>

See DiffResult.

.entries()

method

The direct entries of this directory as [name, Directory], sorted by name. Genuinely async: it reads the directory node. Use it to fan out — e.g. trigger a child build per entry, then Directory.merge(...results).

entries(): Promise<[string, Directory][]>

.file(path: string, opts?: { … })

method

The payload of the file at path, as a File (content not read).

file(path: string, opts?: { … }): File

See File.

.filterGlob(...patterns: string[])

method

This tree filtered to the paths matching any of the glob patterns.

filterGlob(...patterns: string[]): Directory

.get(inherited?: TaskSlot)

method

Force the computation (memoized — subsequent calls reuse the result).

inherited is the node of the value being computed from this one. An intermediate step of a composition — the resolve in dir.resolve(…).filterGlob(…).in(scope) — has no scope of its own and is private to that chain, so it belongs wherever its consumer went. A value with its own scope ignores the offer and stays where it was placed.

Since the result is memoised, a shared unscoped value keeps whichever parent forced it first. That is the ambiguity Scope exists to resolve: give a value used in two places its own scope and it stops floating.

get(inherited?: TaskSlot): Promise<string>

.in(scope: Scope)

method

Place this value's work in scope.

Fixed at declaration time, so a value shared by several consumers appears once, where its owner put it — not under whichever consumer forced it first. Derived values (map, artifact composition) inherit it.

in(scope: Scope): this

See Scope.

.map(f: (…) => …)

method

Derive a new lazy value from this one without forcing it now. Inherits this value's scope, so composition stays in the subtree that owns it.

map(f: (…) => …): Lazy<U>

.resolve(path: string, opts?: { … })

method

The subtree at path (a directory or file node).

resolve(path: string, opts?: { … }): Directory

.setMetadata(path: string, meta: Metadata)

method

This tree with metadata changed at path.

setMetadata(path: string, meta: Metadata): Directory

See Metadata.

.sources()

method

How this tree was assembled, as (prefix → origin) entries.

A tool that ran over this tree reports paths in its coordinates; these entries are what turns one back into a path inside the member it came from. See locate.

sources(): SourceOrigin[]

See SourceOrigin.

.tar(compression?: Compression)

method

This tree as a (optionally compressed) tar archive File.

tar(compression?: Compression): File

See Compression, File.

.dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …)

static method

A dynamic artifact: one whose subgraph cannot be known until deps have resolved, because deciding what to build requires reading them.

Called on the concrete class, which is what types the result:

const crates = Directory.dynamic("compile each crate", [src], async () =>
    Directory.merge(...(await src.entries()).map(([n, e]) => compile(n, e))))
    .in(scope);

label is what this node is called in the build tree — the one thing a dynamic node cannot derive, since it runs no node function of its own. Where it goes is [in][Lazy.in]'s business, like every other value; a dynamic artifact with no scope groups its expansion under whichever consumer forces it.

This is the only asynchronous surface in the API: everything else composes synchronously. The graph has a hole inside a dynamic node, but every edge around it is static — the returned handle is an ordinary artifact, so downstream work is declared normally.

deps are forced before expand runs, and are the node's declared dependency edges.

dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …): T

See Artifact, ArtifactSource.

.expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …)

static method

A value whose subgraph is decided once deps have resolved: expand is called with their values and returns the value this one stands for. label names the node, since it runs no node function of its own.

expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …): Lazy<T>

.fromCid(cid: string)

static method

A Directory from an existing CID (e.g. a member's root).

fromCid(cid: string): Directory

.merge(...layers: Directory[])

static method

Overlay-merge trees left→right (later layers win).

The source maps concatenate in the same order, so a lookup that finds two entries for one path prefers the later — the layer whose bytes actually survived the merge.

merge(...layers: Directory[]): Directory

.node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …)

static method

The output of node function fn on the input input builds from the resolved deps. The value is the output block's CID; read a field of it with map.

node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …): Lazy<string>

.of(value: T)

static method

Already-resolved value.

of(value: T): Lazy<T>

.textFile(text: string, options?: { … })

static method

A single-file tree holding text — the root is the file, so it goes straight to a function that reads one file (k8s.apply's root), or under a name with at: Directory.textFile(yaml).at("job.yaml").

The text is stored as a blob and fs.file wraps it as a regular file (mode defaults to 0o644): the node writes the FsNode in the store's own encoding, typed fs-node, so bldr inspect and the console show a file rather than a bare map. No process runs, and the CID is a function of the text and the mode alone.

textFile(text: string, options?: { … }): Directory

encodeUtf8(text: string)

function

The UTF-8 bytes of text. A lone surrogate encodes as U+FFFD, as TextEncoder does.

encodeUtf8(text: string): number[]

Environment

class

A deployment environment: a name plus free-form labels.

.constructor(props: EnvironmentProps)

constructor

constructor(props: EnvironmentProps): Environment

See EnvironmentProps.

labels: Readonly<Record<string, string>>

property

name: string

property

exitedWith(what: string, code: number, log: string, maxLines?: number)

function

<what> exited with code <code>, followed by the end of its log.

The error a build shows for a failed command. The end of the log is where a command says why it stopped — cargo's error: blocks, a test harness's summary — and bounding it keeps a log of thousands of Compiling lines from becoming an error of thousands of lines.

exitedWith(what: string, code: number, log: string, maxLines?: number): string

File

class

A content-addressed build artifact: a lazy, memoized computation of a CID.

Composition on the subclasses is synchronous and builds a graph; nothing runs until the artifact is forced. Force with cid (or the inherited get(), which it aliases).

.constructor(source: ArtifactSource, labelHint?: string)

constructor

constructor(source: ArtifactSource, labelHint?: string): File

See ArtifactSource.

nodeLabel

accessor

shape

accessor

valueScope

accessor

.bytes()

method

The full byte content.

bytes(): Promise<Uint8Array<ArrayBufferLike>>

.cid(inherited?: TaskSlot)

method

Force and return this artifact's CID. Alias of the inherited get(), kept because .cid() reads better at a build's call sites. inherited is passed by a consuming composition step — see Lazy.get.

cid(inherited?: TaskSlot): Promise<string>

.compress(compression?: Compression)

method

This file, compressed (default: gzip).

compress(compression?: Compression): File

See Compression.

.decompress(compression: Compression)

method

This file, decompressed with the given codec.

decompress(compression: Compression): File

See Compression.

.dependsOn(...deps: unknown[])

method

Record what this value is waiting on.

Only values that are somewhere in the tree count — something with no node and no scope is nothing a reader could go and look at. Accepts anything so callers can pass a mixed bag of inputs (a CID string, a member) without filtering.

dependsOn(...deps: unknown[]): this

.get(inherited?: TaskSlot)

method

Force the computation (memoized — subsequent calls reuse the result).

inherited is the node of the value being computed from this one. An intermediate step of a composition — the resolve in dir.resolve(…).filterGlob(…).in(scope) — has no scope of its own and is private to that chain, so it belongs wherever its consumer went. A value with its own scope ignores the offer and stays where it was placed.

Since the result is memoised, a shared unscoped value keeps whichever parent forced it first. That is the ambiguity Scope exists to resolve: give a value used in two places its own scope and it stops floating.

get(inherited?: TaskSlot): Promise<string>

.in(scope: Scope)

method

Place this value's work in scope.

Fixed at declaration time, so a value shared by several consumers appears once, where its owner put it — not under whichever consumer forced it first. Derived values (map, artifact composition) inherit it.

in(scope: Scope): this

See Scope.

.length()

method

The total byte length — reads only the file's part list, not its data.

length(): Promise<number>

.map(f: (…) => …)

method

Derive a new lazy value from this one without forcing it now. Inherits this value's scope, so composition stays in the subtree that owns it.

map(f: (…) => …): Lazy<U>

.read(from: number, until?: number)

method

The bytes of the range [from, until).

read(from: number, until?: number): Promise<Uint8Array<ArrayBufferLike>>

.slice(from: number, until?: number)

method

A byte range [from, until) of this file (without reading content).

slice(from: number, until?: number): File

.text()

method

The full content as UTF-8 text.

Here rather than at each call site because the build runtime is hardened: TextDecoder is not among the globals it keeps, so decoding bytes in build code fails at the point of use with a ReferenceError that says nothing about why. The host already knows how to hand back text.

text(): Promise<string>

.untar(compression?: Compression)

method

Extract this file as a tar archive into a directory tree.

untar(compression?: Compression): Directory

See Compression, Directory.

.dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …)

static method

A dynamic artifact: one whose subgraph cannot be known until deps have resolved, because deciding what to build requires reading them.

Called on the concrete class, which is what types the result:

const crates = Directory.dynamic("compile each crate", [src], async () =>
    Directory.merge(...(await src.entries()).map(([n, e]) => compile(n, e))))
    .in(scope);

label is what this node is called in the build tree — the one thing a dynamic node cannot derive, since it runs no node function of its own. Where it goes is [in][Lazy.in]'s business, like every other value; a dynamic artifact with no scope groups its expansion under whichever consumer forces it.

This is the only asynchronous surface in the API: everything else composes synchronously. The graph has a hole inside a dynamic node, but every edge around it is static — the returned handle is an ordinary artifact, so downstream work is declared normally.

deps are forced before expand runs, and are the node's declared dependency edges.

dynamic(this: (…) => …, label: string, deps: readonly Artifact[], expand: (…) => …): T

See Artifact, ArtifactSource.

.expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …)

static method

A value whose subgraph is decided once deps have resolved: expand is called with their values and returns the value this one stands for. label names the node, since it runs no node function of its own.

expansion(label: string, deps: readonly Lazy<unknown>[], expand: (…) => …): Lazy<T>

.fromCid(cid: string)

static method

A File from an existing CID.

fromCid(cid: string): File

.node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …)

static method

The output of node function fn on the input input builds from the resolved deps. The value is the output block's CID; read a field of it with map.

node(fn: string, deps: readonly Lazy<unknown>[], input: (…) => …): Lazy<string>

.of(value: T)

static method

Already-resolved value.

of(value: T): Lazy<T>

fromBiomeJson(source: Directory, paths: string | string[], opts?: DiagnosticsOptions)

function

Postprocess Biome's JSON report (biome ci --reporter=json --reporter-file=…) into a Diagnostics. paths are glob(s) matched against source (a tree holding the report file(s)), so a project that lints in several passes is collected in one call.

Its output type is DataType::Diagnostics, which is what tells a consumer there are findings to rank, group and jump to rather than a file to browse.

fromBiomeJson(source: Directory, paths: string | string[], opts?: DiagnosticsOptions): Diagnostics

See Diagnostics, DiagnosticsOptions, Directory.

fromCargoJson(source: Directory, paths: string | string[], opts?: DiagnosticsOptions)

function

Postprocess cargo's newline-delimited JSON (cargo check --message-format=json, and the same from clippy) into a Diagnostics. paths are glob(s) matched against source.

The richest of the converters, because rustc is the most forthcoming tool: the offending span with byte offsets and the source line it came from, the secondary spans that explain it, the notes beneath, and the suggested replacement with rustc's own word for how safe it is. Clippy's findings arrive on the same stream and are told apart by their clippy:: code.

fromCargoJson(source: Directory, paths: string | string[], opts?: DiagnosticsOptions): Diagnostics

See Diagnostics, DiagnosticsOptions, Directory.

fromJestJson(source: Directory, paths: string | string[])

function

Postprocess Jest/Vitest JSON (vitest run --reporter=json --outputFile=…, or jest --json) into a Report. paths are glob(s) matched against source (a tree holding the report file(s)). Its output type is DataType::TestResults, which is what tells bldr test to inspect the cases.

fromJestJson(source: Directory, paths: string | string[]): Report

See Directory, Report.

fromLcov(source: Directory, paths: string | string[], opts?: CoverageConvertOptions)

function

Convert LCOV (cargo llvm-cov --lcov, grcov, gcov's own output) into a Coverage.

LCOV has no region counters, so a report converted from it has line and function coverage and nothing finer. Same options as fromLlvmJson.

fromLcov(source: Directory, paths: string | string[], opts?: CoverageConvertOptions): Coverage

See Coverage, CoverageConvertOptions, Directory.

fromLibtestJson(source: Directory, paths: string | string[])

function

Postprocess cargo test's libtest JSON into a Report. paths are glob(s) matched against source (a tree holding the report file(s)), so a project with several test binaries — hence several .jsons — is collected and merged in one call. Its output type is DataType::TestResults, which is what tells bldr test to inspect the cases.

fromLibtestJson(source: Directory, paths: string | string[]): Report

See Directory, Report.

fromLlvmJson(source: Directory, paths: string | string[], opts?: CoverageConvertOptions)

function

Convert LLVM's own JSON export — what cargo llvm-cov --json writes — into a Coverage. paths are glob(s) matched against source, a tree holding the report file(s).

This is the lossless one: it carries regions, which is the only counter that can tell two branches on one line apart. Prefer it to LCOV unless something downstream demands LCOV.

fromLlvmJson(source: Directory, paths: string | string[], opts?: CoverageConvertOptions): Coverage

See Coverage, CoverageConvertOptions, Directory.

httpGet(url: string, opts?: HttpOptions)

function

httpGet(url: string, opts?: HttpOptions): Promise<HttpResponse>

See HttpOptions, HttpResponse.

httpPost(url: string, body?: File, opts?: HttpOptions)

function

httpPost(url: string, body?: File, opts?: HttpOptions): Promise<HttpResponse>

See File, HttpOptions, HttpResponse.

httpPut(url: string, body?: File, opts?: HttpOptions)

function

httpPut(url: string, body?: File, opts?: HttpOptions): Promise<HttpResponse>

See File, HttpOptions, HttpResponse.

invoke(fn: string, input: Record<string, unknown>, slot?: TaskSlot)

function

Run a node function with a structured input now; resolves to the output CID. slot is the tree node the work appears under. For a truly-async read, not for composition — that is op.

invoke(fn: string, input: Record<string, unknown>, slot?: TaskSlot): Promise<string>

invokeJson(fn: string, input: Record<string, unknown>, slot?: TaskSlot)

function

Run a node function now and read its output block as JSON.

invokeJson(fn: string, input: Record<string, unknown>, slot?: TaskSlot): Promise<T>

isArtifact(value: unknown)

function

Whether a value is a build Artifact (a Directory, File, ContainerImage or Report).