@zuke/docker-compose
`@zuke/docker-compose` — typed Docker Compose task wrappers for Zuke builds.
@zuke/docker-compose on JSR ↗ 43 symbols
Symbols
type ComposeProbe = unknown Probes whether a candidate Compose invocation is runnable on this host. Receives the binary-and-prefix argv (["docker", "compose"] or ["docker-compose"]) and resolves to true when it works. Injectable so detection can be unit-tested without a real Docker install.
async function defaultComposeProbe(argv: unknown): Promise<boolean> The default ComposeProbe: run the candidate's version subcommand quietly and treat a zero exit as success. A missing binary resolves to false rather than throwing, so detection can fall through to the next candidate.
class DockerComposeBuildSettings extends DockerComposeSettings Settings for compose build.
| Member | Signature | Doc |
|---|---|---|
noCache | noCache(): this | Do not use the layer cache (--no-cache). |
pull | pull(): this | Always attempt to pull newer base images (--pull). |
buildArg | buildArg(key: string, value: string): this | Pass a build-time variable (--build-arg KEY=value); repeatable. |
services | services(...names: string[]): this | Restrict to specific services (positional); optional. |
class DockerComposeCommitSettings extends DockerComposeSettings Settings for compose commit.
| Member | Signature | Doc |
|---|---|---|
service | service(name: string): this | The service whose container to commit (required). |
reference | reference(value: string): this | The image reference to create, e.g. my-app:test. |
author | author(value: string): this | Image author (--author). |
message | message(value: string): this | Commit message (--message). |
change | change(...instructions: string[]): this | Apply a Dockerfile instruction to the created image (--change). |
index | index(value: number): this | Pick the replica to commit when the service has several (--index). |
noPause | noPause(): this | Leave the container running during the commit (--pause=false). Compose pauses it by default so the filesystem cannot change mid-capture; turning that off trades a consistent image for uninterrupted service. |
class DockerComposeConfigSettings extends DockerComposeSettings Settings for compose config.
| Member | Signature | Doc |
|---|---|---|
quietOutput | quietOutput(): this | Only validate, printing nothing (-q). |
servicesOnly | servicesOnly(): this | Print the service names only (--services). |
volumesOnly | volumesOnly(): this | Print the volume names only (--volumes). |
format | format(value: string): this | Output format (--format), e.g. yaml or json. |
class DockerComposeCpSettings extends DockerComposeSettings Settings for compose cp.
Compose copies between a service container and the local filesystem, so exactly one side names a service. Naming both or neither is refused rather than handed to Compose as a path it cannot resolve.
| Member | Signature | Doc |
|---|---|---|
fromService | fromService(service: string, path: PathLike): this | Copy out of service at path (SERVICE:PATH). |
fromLocal | fromLocal(path: PathLike): this | Copy out of a local path. |
toService | toService(service: string, path: PathLike): this | Copy into service at path (SERVICE:PATH). |
toLocal | toLocal(path: PathLike): this | Copy into a local path. |
index | index(value: number): this | Pick the replica to copy from when the service has several (--index). |
all | all(): this | Include containers created by compose run (--all). |
archive | archive(): this | Preserve uid/gid information (--archive). |
followLink | followLink(): this | Follow symbolic links in the source path (--follow-link). |
class DockerComposeCreateSettings extends DockerComposeSettings Settings for compose create.
| Member | Signature | Doc |
|---|---|---|
services | services(...names: string[]): this | Restrict creation to these services. |
build | build(): this | Build images before creating containers (--build). |
noBuild | noBuild(): this | Never build, whatever the policy says (--no-build). |
forceRecreate | forceRecreate(): this | Recreate containers even when their configuration has not changed (--force-recreate). |
noRecreate | noRecreate(): this | Leave existing containers in place (--no-recreate). |
removeOrphans | removeOrphans(): this | Remove containers for services no longer in the file (--remove-orphans). |
quietPull | quietPull(): this | Pull without progress output (--quiet-pull). |
pull | pull(policy: DockerComposePullPolicy): this | When to pull images before creating (--pull). |
scale | scale(service: string, replicas: number): this | Create replicas containers for service (--scale). |
yes | yes(): this | Answer every prompt affirmatively (--yes), so an unattended run cannot stall. |
class DockerComposeDownSettings extends DockerComposeSettings Settings for compose down.
| Member | Signature | Doc |
|---|---|---|
volumes | volumes(): this | Also remove named and anonymous volumes (-v). |
removeOrphans | removeOrphans(): this | Remove containers for services no longer defined (--remove-orphans). |
rmi | rmi(type: string): this | Remove images of the given type (--rmi), e.g. all or local. |
timeout | timeout(seconds: number): this | Shutdown timeout in seconds (-t). |
class DockerComposeEventsSettings extends DockerComposeSettings Settings for compose events.
| Member | Signature | Doc |
|---|---|---|
services | services(...names: string[]): this | Restrict the stream to these services. |
json | json(): this | Emit each event as a JSON object (--json). |
since | since(timestamp: string): this | Include events since a timestamp (--since). |
until | until(timestamp: string): this | Stop streaming at a timestamp (--until). Without it the command streams until interrupted, so a build target that awaits it blocks — bound the run with this or with .killAfter(ms). |
class DockerComposeExecSettings extends DockerComposeSettings Settings for compose exec.
| Member | Signature | Doc |
|---|---|---|
service | service(name: string): this | The service whose container to exec into (required). |
detach | detach(): this | Run in the background (-d). |
noTty | noTty(): this | Disable pseudo-TTY allocation (-T). |
workdir | workdir(path: PathLike): this | Working directory inside the container (-w). |
envVar | envVar(key: string, value: string): this | Set an environment variable (-e KEY=value); repeatable. |
commandArgs | commandArgs(...args: Array<string | number>): this | The command and arguments to execute. |
class DockerComposeExportSettings extends DockerComposeSettings Settings for compose export.
| Member | Signature | Doc |
|---|---|---|
service | service(name: string): this | The service whose container filesystem to export (required). |
output | output(path: PathLike): this | Write the tar archive to a file (--output) instead of stdout. Prefer it: a tar stream captured as the command's stdout goes through Zuke's output buffer, which is text-shaped and size-capped. |
index | index(value: number): this | Pick the replica to export when the service has several (--index). |
class DockerComposeImagesSettings extends DockerComposeListingSettings Settings for compose images.
| Member | Signature | Doc |
|---|---|---|
services | services(...names: string[]): this | Restrict the listing to these services. |
class DockerComposeKillSettings extends DockerComposeSettings Settings for compose kill.
| Member | Signature | Doc |
|---|---|---|
services | services(...names: string[]): this | Restrict the kill to these services. |
signal | signal(name: string): this | The signal to send (--signal), SIGKILL by default. Send SIGTERM to let a service run its shutdown path — kill skips the grace period stop gives it. |
removeOrphans | removeOrphans(): this | Remove containers for services no longer in the file (--remove-orphans). |
class DockerComposeListingSettings extends DockerComposeSettings Shared by the listing subcommands that accept --format and --quiet.
--format json is what makes these readable by a build rather than by a person, so the convenience json spells it rather than leaving the caller to remember the value.
| Member | Signature | Doc |
|---|---|---|
format | format(value: string): this | Format the output (--format), e.g. table or json. |
json | json(): this | Emit JSON (--format json). |
quietOutput | quietOutput(): this | Print only identifiers or names (--quiet). |
class DockerComposeLogsSettings extends DockerComposeSettings Settings for compose logs.
| Member | Signature | Doc |
|---|---|---|
follow | follow(): this | Stream new log output (-f). |
timestamps | timestamps(): this | Prefix each line with a timestamp (-t). |
tail | tail(lines: number | all): this | Show only the last N lines, or all (--tail). |
services | services(...names: string[]): this | Restrict to specific services (positional); optional. |
class DockerComposeLsSettings extends DockerComposeListingSettings Settings for compose ls, which lists Compose projects rather than services.
| Member | Signature | Doc |
|---|---|---|
all | all(): this | Include stopped projects (--all). |
filter | filter(expression: string): this | Filter the listing (--filter), e.g. name=my-project. |
class DockerComposePauseSettings extends DockerComposeServiceListSettings Settings for compose pause.
class DockerComposePortSettings extends DockerComposeSettings Settings for compose port, which prints the host address a service's container port was published on.
| Member | Signature | Doc |
|---|---|---|
service | service(name: string): this | The service to ask about (required). |
privatePort | privatePort(port: number): this | The container-side port to look up (required). |
protocol | protocol(value: tcp | udp): this | The protocol of the binding (--protocol), tcp by default. |
index | index(value: number): this | Pick the replica to ask when the service has several (--index). |
class DockerComposePsSettings extends DockerComposeSettings Settings for compose ps.
| Member | Signature | Doc |
|---|---|---|
all | all(): this | Show stopped containers too (-a). |
quietOutput | quietOutput(): this | Only show container IDs (-q). |
servicesOnly | servicesOnly(): this | Display services instead of containers (--services). |
services | services(...names: string[]): this | Restrict to specific services (positional); optional. |
type DockerComposePullPolicy = always | missing | never When compose up fetches images before starting: always on every start, missing only when the image is absent locally, never at all.
class DockerComposePullSettings extends DockerComposeSettings Settings for compose pull.
| Member | Signature | Doc |
|---|---|---|
ignorePullFailures | ignorePullFailures(): this | Continue past services whose pull fails (--ignore-pull-failures). |
quietOutput | quietOutput(): this | Pull without printing progress (-q). |
services | services(...names: string[]): this | Restrict to specific services (positional); optional. |
class DockerComposePushSettings extends DockerComposeSettings Settings for compose push.
| Member | Signature | Doc |
|---|---|---|
ignorePushFailures | ignorePushFailures(): this | Continue past services whose push fails (--ignore-push-failures). |
services | services(...names: string[]): this | Restrict to specific services (positional); optional. |
class DockerComposeRestartSettings extends DockerComposeSettings Settings for compose restart.
| Member | Signature | Doc |
|---|---|---|
timeout | timeout(seconds: number): this | Restart timeout in seconds (-t). |
services | services(...names: string[]): this | Restrict to specific services (positional); optional. |
class DockerComposeRmSettings extends DockerComposeSettings Settings for compose rm.
| Member | Signature | Doc |
|---|---|---|
force | force(): this | Do not prompt for confirmation (-f). |
stop | stop(): this | Stop the containers first if needed (-s). |
volumes | volumes(): this | Also remove anonymous volumes (-v). |
services | services(...names: string[]): this | Restrict to specific services (positional); optional. |
class DockerComposeRunSettings extends DockerComposeSettings Settings for compose run.
| Member | Signature | Doc |
|---|---|---|
service | service(name: string): this | The service to run (required). |
rm | rm(): this | Remove the container after it exits (--rm). |
detach | detach(): this | Run in the background (-d). |
noDeps | noDeps(): this | Do not start linked services (--no-deps). |
name | name(value: string): this | Assign a container name (--name). |
envVar | envVar(key: string, value: string): this | Set an environment variable (-e KEY=value); repeatable. |
commandArgs | commandArgs(...args: Array<string | number>): this | The command and arguments to run inside the container. |
class DockerComposeScaleSettings extends DockerComposeSettings Settings for compose scale.
| Member | Signature | Doc |
|---|---|---|
scale | scale(service: string, replicas: number): this | Scale service to replicas instances; repeatable (required). |
noDeps | noDeps(): this | Do not start linked services (--no-deps). |
class DockerComposeServiceListSettings extends DockerComposeSettings Settings shared by compose pause and compose unpause, which take only a service list.
| Member | Signature | Doc |
|---|---|---|
services | services(...names: string[]): this | Restrict the command to these services. |
class DockerComposeSettings extends ToolSettings Base for all Compose subcommand settings. Holds the invocation prefix (docker compose vs docker-compose) and the global options that precede every subcommand (-f, -p, --profile, …), and resolves the prefix at run time unless it was pinned with usePlugin/useStandalone.
| Member | Signature | Doc |
|---|---|---|
file | file(path: PathLike): this | Add a Compose file (-f); repeatable, order-significant. |
projectName | projectName(name: string): this | Set the project name (-p). |
profile | profile(name: string): this | Enable a service profile (--profile); repeatable. |
projectDirectory | projectDirectory(path: PathLike): this | Set the project working directory (--project-directory). |
envFile | envFile(path: PathLike): this | Load environment from a file (--env-file). |
usePlugin | usePlugin(): this | Force the v2 plugin form (docker compose) and skip detection. |
useStandalone | useStandalone(): this | Force the v1 standalone form (docker-compose) and skip detection. |
run | run(): Promise<CommandOutput> | Resolve the invocation prefix (unless pinned) and run, so the same build works against either the v2 plugin or the v1 standalone binary. |
class DockerComposeStartSettings extends DockerComposeSettings Settings for compose start.
| Member | Signature | Doc |
|---|---|---|
services | services(...names: string[]): this | Restrict to specific services (positional); optional. |
class DockerComposeStopSettings extends DockerComposeSettings Settings for compose stop.
| Member | Signature | Doc |
|---|---|---|
timeout | timeout(seconds: number): this | Shutdown timeout in seconds (-t). |
services | services(...names: string[]): this | Restrict to specific services (positional); optional. |
const DockerComposeTasks: DockerComposeTasksApi Typed task functions for Docker Compose (docker compose/docker-compose).
interface DockerComposeTasksApi The shape of DockerComposeTasks.
| Member | Signature | Doc |
|---|---|---|
up | up(configure?: Configure<DockerComposeUpSettings>): Promise<CommandOutput> | Create and start services: compose up. |
down | down(configure?: Configure<DockerComposeDownSettings>): Promise<CommandOutput> | Stop and remove services: compose down. |
build | build(configure?: Configure<DockerComposeBuildSettings>): Promise<CommandOutput> | Build service images: compose build. |
pull | pull(configure?: Configure<DockerComposePullSettings>): Promise<CommandOutput> | Pull service images: compose pull. |
push | push(configure?: Configure<DockerComposePushSettings>): Promise<CommandOutput> | Push service images: compose push. |
run | run(configure?: Configure<DockerComposeRunSettings>): Promise<CommandOutput> | Run a one-off command: compose run. |
exec | exec(configure?: Configure<DockerComposeExecSettings>): Promise<CommandOutput> | Exec into a running service: compose exec. |
logs | logs(configure?: Configure<DockerComposeLogsSettings>): Promise<CommandOutput> | View service logs: compose logs. |
ps | ps(configure?: Configure<DockerComposePsSettings>): Promise<CommandOutput> | List containers: compose ps. |
config | config(configure?: Configure<DockerComposeConfigSettings>): Promise<CommandOutput> | Render the resolved configuration: compose config. |
start | start(configure?: Configure<DockerComposeStartSettings>): Promise<CommandOutput> | Start existing services: compose start. |
stop | stop(configure?: Configure<DockerComposeStopSettings>): Promise<CommandOutput> | Stop running services: compose stop. |
restart | restart(configure?: Configure<DockerComposeRestartSettings>): Promise<CommandOutput> | Restart services: compose restart. |
rm | rm(configure?: Configure<DockerComposeRmSettings>): Promise<CommandOutput> | Remove stopped service containers: compose rm. |
create | create(configure?: Configure<DockerComposeCreateSettings>): Promise<CommandOutput> | Create containers without starting them: compose create. |
kill | kill(configure?: Configure<DockerComposeKillSettings>): Promise<CommandOutput> | Force-stop service containers: compose kill. |
pause | pause(configure?: Configure<DockerComposePauseSettings>): Promise<CommandOutput> | Pause services: compose pause. |
unpause | unpause(configure?: Configure<DockerComposeUnpauseSettings>): Promise<CommandOutput> | Resume paused services: compose unpause. |
scale | scale(configure?: Configure<DockerComposeScaleSettings>): Promise<CommandOutput> | Set service replica counts: compose scale. |
wait | wait(configure?: Configure<DockerComposeWaitSettings>): Promise<CommandOutput> | Block until services stop: compose wait. Keeps the ordinary contract — a non-zero container status fails the target. Use DockerComposeTasksApi.waitExitCode when the status is the answer rather than a failure. |
cp | cp(configure?: Configure<DockerComposeCpSettings>): Promise<CommandOutput> | Copy between a service container and the local filesystem: compose cp. |
top | top(configure?: Configure<DockerComposeTopSettings>): Promise<CommandOutput> | Show running processes: compose top. |
export | export(configure?: Configure<DockerComposeExportSettings>): Promise<CommandOutput> | Export a container filesystem as a tar archive: compose export. |
commit | commit(configure?: Configure<DockerComposeCommitSettings>): Promise<CommandOutput> | Create an image from a container: compose commit. |
images | images(configure?: Configure<DockerComposeImagesSettings>): Promise<CommandOutput> | List the images the containers use: compose images. |
volumes | volumes(configure?: Configure<DockerComposeVolumesSettings>): Promise<CommandOutput> | List the project's volumes: compose volumes. |
ls | ls(configure?: Configure<DockerComposeLsSettings>): Promise<CommandOutput> | List Compose projects: compose ls. |
version | version(configure?: Configure<DockerComposeVersionSettings>): Promise<CommandOutput> | Report the Compose version: compose version. |
port | port(configure?: Configure<DockerComposePortSettings>): Promise<CommandOutput> | Print a published port binding: compose port. |
events | events(configure?: Configure<DockerComposeEventsSettings>): Promise<CommandOutput> | Stream container events: compose events. |
waitExitCode | waitExitCode(configure?: Configure<DockerComposeWaitSettings>): Promise<number> | The exit status the waited-on container stopped with. compose wait exits with the container's own status, so every code is a legitimate answer and none is left to mean "compose broke". This hands the code back rather than failing the target, and still fails when compose never reached a container at all. |
servicePort | servicePort(configure?: Configure<DockerComposePortSettings>): Promise<number> | The host port a service's container port was published on. The point of letting Compose pick an ephemeral port is asking which one it picked, which is what this returns. |
composeVersion | composeVersion(configure?: Configure<DockerComposeVersionSettings>): Promise<DockerComposeVersion> | The installed Compose version, parsed from compose version --format json. |
class DockerComposeTopSettings extends DockerComposeSettings Settings for compose top.
| Member | Signature | Doc |
|---|---|---|
services | services(...names: string[]): this | Restrict the report to these services. |
class DockerComposeUnpauseSettings extends DockerComposeServiceListSettings Settings for compose unpause.
class DockerComposeUpSettings extends DockerComposeSettings Settings for compose up.
| Member | Signature | Doc |
|---|---|---|
detach | detach(): this | Run in the background (-d). |
build | build(): this | Build images before starting (--build). |
forceRecreate | forceRecreate(): this | Recreate containers even if unchanged (--force-recreate). |
removeOrphans | removeOrphans(): this | Remove containers for services no longer defined (--remove-orphans). |
wait | wait(): this | Wait until services are running/healthy (--wait). |
abortOnContainerExit | abortOnContainerExit(): this | Stop all containers if any container stops (--abort-on-container-exit). |
noDeps | noDeps(): this | Start only the named services, leaving their dependencies alone (--no-deps). Without it compose starts or recreates a dependency that is stopped or whose configuration changed. With an already-healthy stack the two agree, so the difference shows up only on the runs where a dependency was not ready — which is where a target that meant "just this service" wants to be explicit. |
pull | pull(policy: DockerComposePullPolicy): this | When to fetch images before starting (--pull). always keeps a stack on the current published images rather than whatever was pulled last; missing fetches only what is absent locally; never uses what is there. Distinct from DockerComposeBuildSettings.pull, which is build --pull, and from the pull task, which is the subcommand — each mirrors its own command. |
exitCodeFrom | exitCodeFrom(service: string): this | Exit with this service's container's exit code (--exit-code-from). |
scale | scale(service: string, instances: number): this | Scale a service to N instances (--scale service=N); repeatable. |
services | services(...names: string[]): this | Restrict to specific services (positional); optional. |
interface DockerComposeVersion The version report compose version --format json emits.
| Member | Signature | Doc |
|---|---|---|
version | version: string | The Compose version string, e.g. v5.1.1. |
class DockerComposeVersionSettings extends DockerComposeSettings Settings for compose version.
| Member | Signature | Doc |
|---|---|---|
format | format(value: string): this | Format the output (--format), pretty or json. |
json | json(): this | Emit JSON (--format json). |
short | short(): this | Print only the version number (--short). |
class DockerComposeVolumesSettings extends DockerComposeListingSettings Settings for compose volumes.
| Member | Signature | Doc |
|---|---|---|
services | services(...names: string[]): this | Restrict the listing to the volumes these services use. |
class DockerComposeWaitSettings extends DockerComposeSettings Settings for compose wait.
The command blocks until the named services' containers stop, then exits with the first container's own exit status. That makes its exit code a result rather than a failure — see DockerComposeTasks.waitExitCode, which hands the code back instead of failing the target.
| Member | Signature | Doc |
|---|---|---|
services | services(...names: string[]): this | The services to wait on (required). |
downProject | downProject(): this | Tear the project down once the first container stops (--down-project), so a test run cleans up after itself without a second command. |
class ReplicaIndex The --index flag that picks one replica of a scaled service.
cp, export, commit and port all take it with the same meaning and the same rendering, so they hold one of these rather than four copies of the field and the argv.push that goes with it. Each still exposes its own setter, because the public surface is per-command.
| Member | Signature | Doc |
|---|---|---|
set | set(value: number): void | Record the replica to act on. |
render | render(): string[] | The flag, if one was set. |
function resetComposeInvocationCache_(): void Clear the cached Compose invocation so the next resolveComposeInvocation re-detects. Internal test seam — the trailing underscore signals it is not part of the stable public API.
function resolveComposeInvocation(probe?: ComposeProbe): Promise<string[]> Resolve how Docker Compose is invoked on this host: ["docker", "compose"] for the v2 plugin or ["docker-compose"] for the v1 standalone binary. The v2 plugin is preferred; if neither is runnable a ToolNotFoundError is raised. The result is cached after the first successful detection (a failed detection is not cached, so a later call retries). Pass a custom ComposeProbe to override how candidates are tested.
class ServiceList The trailing service-name operands most Compose subcommands accept.
Same reasoning as ReplicaIndex: the list and the way it is appended are identical wherever it appears, so it lives here once. Each settings class still exposes its own services() setter, because which subcommands take the operand — and what it means for each — is part of the public surface.
| Member | Signature | Doc |
|---|---|---|
add | add(names: unknown): void | Add service names to the list. |
isEmpty | isEmpty(): boolean | Whether any service was named. |
render | render(): string[] | The names, in the order they were added. |