@zerothrow/docker

🧠 ZeroThrow Layers
• ZT – primitives (try, tryAsync, ok, err)
• Result – combinators (map, andThen, match)
• ZeroThrow – utilities (collect, enhanceAsync)
• @zerothrow/* – ecosystem packages (resilience, jest, etc)

ZeroThrow Ecosystem · Packages ⇢

Zero-throw Docker utilities for testing and container management, with automatic error handling and recovery suggestions.

Installation

npm install @zerothrow/docker @zerothrow/core
# or: pnpm add @zerothrow/docker @zerothrow/core

Quick Start

import { checkDockerStatus, startDocker, isContainerRunning } from '@zerothrow/docker';

// Check if Docker is installed and running
const status = await checkDockerStatus();
if (status.ok) {
  console.log('Docker version:', status.value.version);
  console.log('Docker running:', status.value.running);
}

// Start Docker if not running
if (!status.value.running) {
  const startResult = await startDocker();
  if (startResult.ok) {
    console.log('Docker started successfully');
  }
}

// Check if a container is running
const running = await isContainerRunning('my-postgres');
if (running.ok && running.value) {
  console.log('Container is running');
}

CLI Tool

The package includes a CLI tool zt-docker for common Docker operations:

# Check Docker status
zt-docker status

# Start Docker daemon
zt-docker start

# Check disk usage
zt-docker disk

# Clean up Docker resources
zt-docker prune --all --volumes --force

# Stop a container
zt-docker stop my-container

# Remove a container
zt-docker remove my-container

# Run interactive Docker-based tests
zt-docker test

API

Docker Status Functions

checkDockerStatus(): Promise<Result<DockerStatus, ZeroError>>

Checks if Docker is installed, running, and if Docker Compose is available.

interface DockerStatus {
  installed: boolean;
  running: boolean;
  version?: string;
  composeInstalled: boolean;
  composeVersion?: string;
  error?: ZeroError;
}

isRunningInDocker(): boolean

Detects if the current process is running inside a Docker container.

startDocker(): Promise<Result<void, ZeroError>>

Attempts to start the Docker daemon. Platform-specific:

• macOS: Opens Docker Desktop app and waits up to 30 seconds
• Linux: Uses systemctl to start the Docker service (requires sudo)
• Windows: Returns an error asking user to start Docker Desktop manually

Container Management

isContainerRunning(name: string): Promise<Result<boolean, ZeroError>>

Checks if a container with the given name is currently running.

stopContainer(name: string): Promise<Result<void, ZeroError>>

Stops a running container by name.

removeContainer(name: string): Promise<Result<void, ZeroError>>

Forcefully removes a container by name (equivalent to docker rm -f).

Disk Management

checkDiskSpace(): Promise<Result<string, ZeroError>>

Returns Docker disk usage information (equivalent to docker system df).

pruneDocker(options?: DockerPruneOptions): Promise<Result<string, ZeroError>>

Cleans up Docker resources with various options:

interface DockerPruneOptions {
  all?: boolean;      // Remove all unused images, not just dangling
  volumes?: boolean;  // Also prune volumes
  force?: boolean;    // Skip confirmation prompts
}

Utility Functions

getDockerInstallCommand(): string

Returns the platform-specific Docker installation command:

• macOS: brew install --cask docker
• Linux: curl -fsSL https://get.docker.com | sh
• Windows: winget install Docker.DockerDesktop
• Other: Returns Docker documentation URL

handleDockerError(error: ZeroError): Promise<Result<void, ZeroError>>

Analyzes Docker-related errors and provides actionable suggestions:

• Disk space issues: Suggests pruning commands
• Daemon not running: Attempts to start Docker
• Permission issues: Provides platform-specific fix instructions

execCmdInteractive(cmd: string): Promise<Result<void, ZeroError>>

Executes a shell command with inherited stdio, useful for interactive commands that need user input.

Examples

Running Integration Tests with Docker

The test-docker.ts script provides an interactive way to ensure Docker is ready before running integration tests:

import runTests from '@zerothrow/docker/test-docker';

// Checks Docker status, offers to start it if needed,
// and runs integration tests when ready
await runTests();

Error Handling with Recovery

import { checkDockerStatus, handleDockerError, pruneDocker } from '@zerothrow/docker';

const status = await checkDockerStatus();
if (!status.ok) {
  // handleDockerError provides smart recovery suggestions
  const handled = await handleDockerError(status.error);
  if (!handled.ok) {
    console.error('Could not recover:', handled.error.message);
  }
}

// Handle disk space issues
const result = await someDockerOperation();
if (!result.ok && result.error.message.includes('no space left')) {
  console.log('Running out of disk space, cleaning up...');
  await pruneDocker({ all: true, volumes: true, force: true });
}

Platform Detection

import { isRunningInDocker, getDockerInstallCommand } from '@zerothrow/docker';

if (isRunningInDocker()) {
  console.log('Already in Docker, skipping container operations');
} else {
  console.log('To install Docker:', getDockerInstallCommand());
}

Contributing

See the main repository for contribution guidelines.

License

MIT