@lakutata/docker 3.0.0-beta.0

package/dist/types/docker/interfaces/IDockerHttpsConnectionOptions.d.ts

@@ -0,0 +1,16 @@
+import { IDockerConnectionOptions } from './IDockerConnectionOptions.js';
+/**
+ * The options of {@link buildDockerHttpsConnectionOptions}: a daemon reached over HTTPS at `host` and `port`, with the
+ * `ca`, `cert` and `key` (PEM contents), the headers, the timeout and the API version of
+ * {@link IDockerConnectionOptions} (its `protocol` is replaced by `'https'`).
+ */
+export interface IDockerHttpsConnectionOptions extends Omit<IDockerConnectionOptions, 'socketPath' | 'sshAuthAgent'> {
+    /**
+     * The host name or IP address of the daemon, as its certificate names it.
+     */
+    host: string;
+    /**
+     * The TCP port of the daemon (2376 by convention).
+     */
+    port: number | string;
+}

package/dist/types/docker/interfaces/IDockerKeyObject.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A private key of the HTTPS connections to the daemon, with its passphrase (the `key` option of {@link Docker}).
+ */
+export interface IDockerKeyObject {
+    /**
+     * The private key: its PEM contents, not its file path.
+     */
+    pem: string | Buffer;
+    /**
+     * The passphrase decrypting the key.
+     * @default undefined (an unencrypted key)
+     */
+    passphrase?: string | undefined;
+}

package/dist/types/docker/interfaces/IDockerSSHConnectionOptions.d.ts

@@ -0,0 +1,16 @@
+import { IDockerConnectionOptions } from './IDockerConnectionOptions.js';
+/**
+ * The options of {@link buildDockerSSHConnectionOptions}: a remote host reached over SSH at `host` and `port`, as
+ * `username`, authenticated by the SSH agent (`sshAuthAgent`), with the timeout and the API version of
+ * {@link IDockerConnectionOptions} (its `protocol` is replaced by `'ssh'`).
+ */
+export interface IDockerSSHConnectionOptions extends Omit<IDockerConnectionOptions, 'socketPath'> {
+    /**
+     * The host name or IP address of the remote host running the daemon.
+     */
+    host: string;
+    /**
+     * The SSH port of the remote host (usually 22).
+     */
+    port: number | string;
+}

package/dist/types/docker/interfaces/IDockerSocketConnectionOptions.d.ts

@@ -0,0 +1,7 @@
+import { IDockerConnectionOptions } from './IDockerConnectionOptions.js';
+/**
+ * The options of {@link buildDockerSocketConnectionOptions}: the daemon's Unix socket or named pipe (`socketPath`), with
+ * the authorities (`ca`), the timeout and the API version of {@link IDockerConnectionOptions}.
+ */
+export interface IDockerSocketConnectionOptions extends Omit<IDockerConnectionOptions, 'sshAuthAgent' | 'key' | 'protocol' | 'cert' | 'headers' | 'username' | 'port' | 'host'> {
+}

package/dist/types/docker/lib/DockerContainer.d.ts

@@ -0,0 +1,315 @@
+import { Provider } from '@lakutata/core';
+import type { DockerClient } from '../../client/DockerClient.js';
+import { Time } from '@lakutata/utils/Time';
+import { ContainerState } from '../types/ContainerState.js';
+import { type Docker } from '../Docker.js';
+import { type DockerImage } from './DockerImage.js';
+import { ContainerNetwork } from '../types/ContainerNetwork.js';
+import { ContainerPort } from '../types/ContainerPort.js';
+import { ContainerBind } from '../types/ContainerBind.js';
+import { ContainerDevice } from '../types/ContainerDevice.js';
+import { ContainerStopOptions } from '../options/container/ContainerStopOptions.js';
+import { ContainerRemoveOptions } from '../options/container/ContainerRemoveOptions.js';
+import { ContainerSettingOptions } from '../options/container/ContainerSettingOptions.js';
+import { ContainerRestartPolicy } from '../types/ContainerRestartPolicy.js';
+import { type ContainerExecResult } from '../types/ContainerExecResult.js';
+import { ContainerKillOptions } from '../options/container/ContainerKillOptions.js';
+import { ContainerCommitOptions } from '../options/container/ContainerCommitOptions.js';
+import { ContainerCapability } from '../types/ContainerCapability.js';
+import { DockerContainerTTY } from './DockerContainerTTY.js';
+import { ContainerCreateTTYOptions } from '../options/container/ContainerCreateTTYOptions.js';
+import { ContainerLogsOptions } from '../options/container/ContainerLogsOptions.js';
+import { ContainerStats } from '../types/ContainerStats.js';
+import { ContainerExecOptions } from '../options/container/ContainerExecOptions.js';
+import { ContainerExportDirectoryOptions } from '../options/container/ContainerExportDirectoryOptions.js';
+/**
+ * A container of the Docker daemon, with its settings and its state as inspected, and its operations: start, stop,
+ * restart, pause, kill, remove, update, commit, exec, TTYs, logs, stats and the export of its files. It is not created
+ * with `new`: {@link Docker.getContainer}, {@link Docker.listContainers}, {@link Docker.createContainer} and
+ * {@link DockerImage.run} return it.
+ *
+ * Its properties are a snapshot, taken when it is obtained and refreshed by its own operations (`start()`, `stop()`,
+ * `restart()`, `pause()`, `unpause()`, `kill()`, `update()`): the changes made by others (the container exiting,
+ * `docker stop`) are seen by getting it again. Its operations reject with {@link DockerContainerNotFoundException} when
+ * the container was removed, with {@link DockerRequestException} when the daemon refuses them otherwise (not running:
+ * HTTP 409), and with the network error of Node.js when the daemon cannot be reached.
+ * @example
+ * ```typescript
+ * import {type Docker, type DockerContainer, type DockerImage} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const image: DockerImage = await docker.getImage('alpine:3.20')
+ * const container: DockerContainer = await docker.createContainer(image.id, {
+ *     name: 'worker',
+ *     cmd: ['sh', '-c', 'echo started; sleep 3600'],
+ *     env: {MODE: 'production'},
+ *     ports: [{port: 8080, type: 'tcp', hostPorts: [18080]}],
+ *     binds: [{hostPath: '/srv/data', containerPath: '/data', rw: true}],
+ *     restartPolicy: 'unless-stopped'
+ * })
+ * await container.start()
+ * console.log(container.state.status, container.ports)
+ * //The exit code, stdout and stderr
+ * const {exitCode, stdout} = await container.exec({cmd: ['ls', '/data']})
+ * console.log(exitCode, stdout)
+ * await container.stop({timeout: 10})
+ * await container.remove()
+ * ```
+ */
+export declare class DockerContainer extends Provider {
+    #private;
+    /**
+     * Give the client of the Engine API: set by the {@link Docker} component creating the object.
+     */
+    protected readonly getClient: () => DockerClient;
+    /**
+     * Give the {@link Docker} component which created the object.
+     */
+    protected readonly getDocker: () => Docker;
+    /**
+     * The full ID of the container (64 hexadecimal characters). It changes when {@link DockerContainer.update}
+     * recreates the container.
+     */
+    id: string;
+    /**
+     * The name of the container, without the leading `/` of the Engine API.
+     */
+    name: string;
+    /**
+     * The host name of the container (its short ID unless set when it was created).
+     */
+    hostname: string;
+    /**
+     * The image the container was created from; `undefined` when it no longer exists (removed with force while the
+     * container was stopped).
+     */
+    image: DockerImage | undefined;
+    /**
+     * How many times the daemon restarted the container, by its restart policy.
+     */
+    restartCount: number;
+    /**
+     * Whether the container has full access to the host (`--privileged`).
+     */
+    privileged: boolean;
+    /**
+     * Whether the container's main process has a TTY: its logs are then raw, not split into stdout and stderr.
+     */
+    tty: boolean;
+    /**
+     * The environment variables of the container, the image's included, by name.
+     */
+    env: Record<string, string>;
+    /**
+     * The memory limit of the container, in bytes; `0` for no limit.
+     */
+    memoryLimit: number;
+    /**
+     * The indexes of the CPUs the container may run on, sorted; empty for all of them.
+     */
+    cpuSet: number[];
+    /**
+     * When the daemon restarts the container after it exits (`'no'` by default; `'on-failure:3'` for 3 retries at
+     * most).
+     */
+    restartPolicy: ContainerRestartPolicy;
+    /**
+     * Whether the OOM killer is disabled for the container.
+     */
+    OOMKillDisable: boolean;
+    /**
+     * The kernel capabilities added to the container (`--cap-add`).
+     */
+    capabilities: ContainerCapability[];
+    /**
+     * The state of the container: its status (`'created'`, `'running'`, `'exited'`…), its process ID, its exit code
+     * and its start and finish times.
+     */
+    state: ContainerState;
+    /**
+     * The ports of the container, exposed by its image or published: one entry per IP address of the container, port
+     * and protocol, with the ports of the host published to it, each one once (empty when not published).
+     */
+    ports: ContainerPort[];
+    /**
+     * The directories and files of the host mounted in the container (the bind mounts; not the volumes).
+     */
+    binds: ContainerBind[];
+    /**
+     * The devices of the host added to the container.
+     */
+    devices: ContainerDevice[];
+    /**
+     * The networks the container is connected to, with its addresses in each.
+     */
+    networks: ContainerNetwork[];
+    /**
+     * The cgroup the container joins (`container:<name|id>`), as the daemon reports it (an empty string by default).
+     */
+    cgroup: string | undefined;
+    /**
+     * The parent cgroup under which the container's cgroup is created (an empty string by default).
+     */
+    cgroupParent: string | undefined;
+    /**
+     * The PID namespace mode of the container: `'host'`, `'container:<name|id>'`, or an empty string for its own.
+     */
+    pidMode: string | undefined;
+    /**
+     * When the container was created.
+     */
+    createdAt: Time;
+    /**
+     * Inspect the container.
+     * @throws {DockerContainerNotFoundException} When the container does not exist.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Abort the requests in progress of the object (the container itself is left as it is).
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Refresh the properties from the daemon's inspection of the container, and its image (`undefined` when it no longer
+     * exists).
+     * @throws {DockerContainerNotFoundException} When the container does not exist.
+     * @protected
+     */
+    protected syncContainerInfo(): Promise<void>;
+    /**
+     * Start the container, as `docker start`, then refresh its properties. A container already running is left as it is
+     * (as the Docker CLI does).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When it fails to start (HTTP 500: a command not found, a port already used).
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the container, as `docker stop`: send its stop signal, wait for it to exit, kill it after the timeout; then
+     * refresh its properties.
+     * @param options The signal sent (the container's stop signal, `SIGTERM` by default) and the timeout before the kill,
+     * in seconds (the container's, 10 by default). A container already stopped is left as it is (as the Docker CLI does).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    stop(options?: ContainerStopOptions): Promise<void>;
+    /**
+     * Suspend the processes of the container, as `docker pause`, then refresh its properties.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When it is not running or already paused (HTTP 409).
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume the processes of a paused container, as `docker unpause`, then refresh its properties.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When it is not paused (HTTP 409).
+     */
+    unpause(): Promise<void>;
+    /**
+     * Restart the container, as `docker restart`: stop it as {@link DockerContainer.stop} does (when it runs), then start
+     * it; then refresh its properties.
+     * @param options The signal sent (the container's stop signal, `SIGTERM` by default) and the timeout before the kill,
+     * in seconds (the container's, 10 by default).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When it fails to start (HTTP 500).
+     */
+    restart(options?: ContainerStopOptions): Promise<void>;
+    /**
+     * Remove the container, as `docker rm -v`: its anonymous volumes are removed with it. The object is not refreshed:
+     * its other operations then fail with {@link DockerContainerNotFoundException}.
+     * @param options `force` kills a running container first (`false` by default).
+     * @throws {DockerContainerNotFoundException} When the container was already removed.
+     * @throws {DockerRequestException} When it is running and `force` is not set (HTTP 409).
+     */
+    remove(options?: ContainerRemoveOptions): Promise<void>;
+    /**
+     * Change the settings of the container, keeping the others. The memory limit, the CPUs and the restart policy are
+     * changed live, as `docker update` does, and the name by renaming it, the container running on. The other
+     * settings (and removing the memory limit or the CPU set, which Docker cannot do live) recreate the container: a new
+     * one is created from the old one's whole configuration (its image, command, entrypoint, environment, mounts,
+     * networks and their static addresses, the addresses Docker assigned being assigned again), with the settings
+     * changed, under a temporary name. Once created (and, when the old one was running, the old one stopped and the new
+     * one started), the old one is removed without its volumes and the new one takes its name (and its anonymous
+     * volumes, mounted again). The object follows the new container: its `id` changes.
+     * @remarks The old container is kept when the creation or the start of the new one fails (invalid settings, the
+     * image removed, a network missing): the new one is removed, the old one started again when it was running, and the
+     * call rejects. Its files outside the volumes are not kept by a recreation (commit them first, see
+     * {@link DockerContainer.commit}). A container removed by Docker when it stops (`AutoRemove`) cannot be kept.
+     * @param options The settings changed: `memoryLimit`, `cpuSet` and `restartPolicy` live (the swap limit set to
+     * Docker's default with the memory), `name` by a renaming; `hostname`, `env` (replacing the container's variables;
+     * the image's are added again), `cmd`, `entrypoint`, `tty`, `privileged`, `ports`, `binds` (replacing the bind
+     * mounts, the volumes kept), `devices`, `networks` (replacing the networks), `capabilities`, `OOMKillDisable`,
+     * `cgroup`, `cgroupParent` and `pidMode` by a recreation. The settings absent are kept.
+     * @throws {InvalidMethodAcceptException} When the settings are invalid.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerImageNotFoundException} When the container must be recreated and its image no longer exists.
+     * @throws {DockerNetworkNotFoundException} When a network of the settings is not found.
+     * @throws {DockerRequestException} When the daemon refuses the changes: a limit refused (HTTP 400), the name
+     * already used (HTTP 409), the new container failing to start (HTTP 500).
+     */
+    update(options: ContainerSettingOptions): Promise<void>;
+    /**
+     * Create an image from the container's current files, as `docker commit`.
+     * @param options The name of the image (`repoTag`, `repo:tag`; none by default) and whether the container is paused
+     * while it is committed (`pauseBeforeCommitting`, `true` by default).
+     * @returns The image created.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    commit(options?: ContainerCommitOptions): Promise<DockerImage>;
+    /**
+     * Start an interactive command with a TTY in the running container, as `docker exec -it`. The command runs until it
+     * exits (or its stream is closed): see {@link DockerContainerTTY}.
+     * @param options The command (`['/bin/sh']` by default; the program and its arguments, run as they are, or a command
+     * line, run by `/bin/sh -c`) and the initial console size.
+     * @returns The TTY, its command started.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the container is not running (HTTP 409).
+     */
+    createTTY(options?: ContainerCreateTTYOptions): Promise<DockerContainerTTY>;
+    /**
+     * Read the logs of the container's main process, as `docker logs`: stdout and stderr in one stream, in their order
+     * (split from Docker's multiplexed format unless the container has a TTY).
+     * @remarks The logs are followed by default: the stream does not end while the container runs. Pass `follow: false`
+     * for the logs written so far.
+     * @param options `follow` (`true` by default), `since` and `until` (UNIX timestamps in seconds; `0`, no bound, by
+     * default), `timestamps` (`false` by default) and `tail` (a number of lines from the end; all by default).
+     * @returns The readable stream of the logs.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    logs(options?: ContainerLogsOptions): Promise<NodeJS.ReadableStream>;
+    /**
+     * Read the resource usage of the container once, as `docker stats --no-stream`: CPU, memory, network, block I/O and
+     * processes, as the Engine API reports them.
+     * @returns The statistics.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    stats(): Promise<ContainerStats>;
+    /**
+     * Run a command in the running container, as `docker exec` (no TTY, no stdin), and wait for it to exit. As the
+     * containerd component's, a command exiting with a non-zero code resolves too: check its `exitCode`.
+     * @param options The command: a program and its arguments (`['ls', '-l']`), run as they are, or a command line
+     * (`'ls /data | wc -l'`), run by `/bin/sh -c`.
+     * @returns The exit code of the command, its stdout and its stderr (a program not found: exit code `127` or `126`,
+     * the error in the output).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the container is not running or paused (HTTP 409).
+     */
+    exec(options: ContainerExecOptions): Promise<ContainerExecResult>;
+    /**
+     * Send a signal to the container's main process, as `docker kill` (`SIGKILL` by default), then refresh its properties.
+     * @param options The signal sent: a name (`'SIGHUP'`) or a number (`1`); `SIGKILL` by default.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the container is not running (HTTP 409), or the signal is unknown.
+     */
+    kill(options?: ContainerKillOptions): Promise<void>;
+    /**
+     * Copy a file or a directory out of the container as a tar archive, as `docker cp container:path -`. The container
+     * may be stopped.
+     * @param options The path in the container, and the `destination` of the archive: a file path (created or
+     * overwritten) or a writable stream (ended after the archive).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the path is not found in the container (HTTP 404).
+     * @throws {Error} The error of the destination.
+     */
+    exportDirectory(options: ContainerExportDirectoryOptions): Promise<void>;
+}

package/dist/types/docker/lib/DockerContainerTTY.d.ts

@@ -0,0 +1,99 @@
+import { Provider } from '@lakutata/core';
+import stream from 'stream';
+import type { DockerClient } from '../../client/DockerClient.js';
+import { ContainerTTYConsoleSizeOptions } from '../options/container/ContainerTTYConsoleSizeOptions.js';
+/**
+ * An interactive command running with a TTY in a container, as `docker exec -it`: what is written to it is the
+ * command's input, its output (stdout and stderr together, with the terminal's control sequences) is read from it. It is
+ * not created with `new`: {@link DockerContainer.createTTY} returns it, its command started.
+ *
+ * The command runs until it exits (`exit` written to a shell), or until the stream is closed (`tty.raw.end()`,
+ * `tty.raw.destroy()`); the stream then ends. A command which cannot be started (not found in the image) does not fail
+ * the creation: its error message is the output, then the stream ends. The write failures are logged by the
+ * application's `log` component, else by the console.
+ * @example
+ * ```typescript
+ * import {type DockerContainer, type DockerContainerTTY} from 'lakutata/com/docker'
+ *
+ * declare const container: DockerContainer
+ *
+ * //A shell: /bin/sh by default
+ * const tty: DockerContainerTTY = await container.createTTY({consoleSize: {cols: 120, rows: 40}})
+ * tty.onData((chunk: Buffer): void => {
+ *     process.stdout.write(chunk)
+ * })
+ * tty.raw.once('end', (): void => console.log('The shell exited'))
+ * tty.write('ls -l /\n')
+ * await tty.resize({cols: 160, rows: 50})
+ * tty.write('exit\n')
+ * ```
+ */
+export declare class DockerContainerTTY extends Provider {
+    #private;
+    /**
+     * Give the client of the Engine API: set by the {@link DockerContainer} creating the object.
+     */
+    protected readonly getClient: () => DockerClient;
+    /**
+     * The full ID of the container running the command.
+     */
+    protected readonly containerId: string;
+    /**
+     * The command run: the program and its arguments (a program name alone as a string).
+     */
+    protected readonly cmd: string | string[];
+    /**
+     * The size of the console when the command starts.
+     * @default undefined (chosen by the daemon)
+     */
+    protected readonly initialConsoleSize?: ContainerTTYConsoleSizeOptions;
+    /**
+     * Create the execution of the command and start it, attached to its TTY.
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     * @throws {DockerRequestException} When the container is not running (HTTP 409).
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Close the stream of the TTY, which ends the command's input.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * The stream of the TTY, both ways: written, the command's input; read, its output. Its `end` event tells that the
+     * command exited, once its output is read (with {@link DockerContainerTTY.onData} or a `data` listener).
+     */
+    get raw(): stream.Duplex;
+    /**
+     * The stream of the TTY, typed as its writable side: the command's input.
+     */
+    get writable(): stream.Writable;
+    /**
+     * The stream of the TTY, typed as its readable side: the command's output.
+     */
+    get readable(): stream.Readable;
+    /**
+     * Change the size of the TTY's console, as a terminal window resized does (the command gets `SIGWINCH`).
+     * @param options The number of columns (`cols`) and rows (`rows`).
+     * @throws {DockerRequestException} When the command has exited (HTTP 404, no such exec; HTTP 500).
+     * @throws {DockerContainerNotFoundException} When the container was removed.
+     */
+    resize(options: ContainerTTYConsoleSizeOptions): Promise<void>;
+    /**
+     * Receive the command's output as it comes. Each call adds a handler.
+     * @param handler Called with each chunk of the output: raw bytes, the terminal's control sequences included.
+     */
+    onData(handler: (chunk: Buffer) => void): void;
+    /**
+     * Write text to the command's input, as typed on its terminal (`'ls\n'` runs `ls` in a shell). A write failure is
+     * not thrown: it is logged as a warning by the `log` component (by the console without it).
+     * @param data The text written, UTF-8 encoded.
+     */
+    write(data: string): void;
+    /**
+     * Write bytes to the command's input, as typed on its terminal. A write failure is not thrown: it is logged as a
+     * warning by the `log` component (by the console without it).
+     * @param data The bytes written.
+     */
+    write(data: Buffer): void;
+}

package/dist/types/docker/lib/DockerImage.d.ts

@@ -0,0 +1,153 @@
+import { Provider } from '@lakutata/core';
+import type { DockerClient } from '../../client/DockerClient.js';
+import { Time } from '@lakutata/utils/Time';
+import { ImageConfig } from '../types/ImageConfig.js';
+import { ImageTagOptions } from '../options/image/ImageTagOptions.js';
+import { ImageExportOptions } from '../options/image/ImageExportOptions.js';
+import { ImageRemoveOptions } from '../options/image/ImageRemoveOptions.js';
+import { ImagePushOptions } from '../options/image/ImagePushOptions.js';
+import type { Docker } from '../Docker.js';
+import { ContainerSettingOptions } from '../options/container/ContainerSettingOptions.js';
+import { type DockerContainer } from './DockerContainer.js';
+/**
+ * An image of the Docker daemon, with its tags, platform, size and configuration as inspected, and its operations: tag,
+ * export, push, remove, and run a container. It is not created with `new`: {@link Docker.getImage},
+ * {@link Docker.listImages}, {@link Docker.pullImage}, {@link Docker.buildImage}, {@link Docker.importImage} and
+ * {@link DockerContainer.commit} return it.
+ *
+ * Its properties are a snapshot, taken when it is obtained and refreshed by `tag()` and `push()`. Its operations reject
+ * with {@link DockerImageNotFoundException} when the image was removed, with {@link DockerRequestException} when the
+ * daemon refuses them otherwise (used by a container: HTTP 409), and with the network error of Node.js when the daemon
+ * cannot be reached.
+ * @example
+ * ```typescript
+ * import {type Docker, type DockerContainer, type DockerImage} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const image: DockerImage = await docker.buildImage({workdir: '/srv/app', files: ['Dockerfile', 'src', 'package.json'], repoTag: 'app:1.0.0'})
+ * console.log(image.id, image.platform, image.size, image.config.ports)
+ * await image.tag({repo: 'registry.example.com/team/app', tag: '1.0.0'})
+ * await image.push({
+ *     repo: 'registry.example.com/team/app',
+ *     tag: '1.0.0',
+ *     auth: {serverAddress: 'registry.example.com', username: 'ci', password: 'secret'}
+ * })
+ * await image.export({destination: '/tmp/app-1.0.0.tar', repoTag: 'app:1.0.0'})
+ * const container: DockerContainer = await image.run({name: 'app', ports: [{port: 3000, type: 'tcp', hostPorts: [3000]}]})
+ * console.log(container.state.status)
+ * ```
+ */
+export declare class DockerImage extends Provider {
+    #private;
+    /**
+     * Give the client of the Engine API: set by the {@link Docker} component creating the object.
+     */
+    protected readonly getClient: () => DockerClient;
+    /**
+     * Give the {@link Docker} component which created the object.
+     */
+    protected readonly getDocker: () => Docker;
+    /**
+     * The full ID of the image (`sha256:…`).
+     */
+    id: string;
+    /**
+     * The tags of the image (`['alpine:3.20', 'alpine:latest']`); empty for an untagged image.
+     */
+    repoTags: string[];
+    /**
+     * When the image was built.
+     */
+    createdAt: Time;
+    /**
+     * The CPU architecture of the image (`amd64`, `arm64`).
+     */
+    arch: string;
+    /**
+     * The operating system of the image (`linux`).
+     */
+    os: string;
+    /**
+     * The platform of the image, `os/arch` (`linux/arm64`): the one its containers are created for by
+     * {@link DockerImage.run}.
+     */
+    platform: string;
+    /**
+     * The size of the image, in bytes.
+     */
+    size: number;
+    /**
+     * The configuration of the image: its default host name, user, environment, command, entrypoint, volumes and exposed
+     * ports.
+     */
+    config: ImageConfig;
+    /**
+     * Inspect the image.
+     * @throws {DockerImageNotFoundException} When the image does not exist.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Abort the export in progress of the object (the image itself is left as it is).
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Refresh the properties from the daemon's inspection of the image.
+     * @throws {DockerImageNotFoundException} When the image does not exist.
+     * @protected
+     */
+    protected syncImageInfo(): Promise<void>;
+    /**
+     * Add a tag to the image, as `docker tag`, then refresh its properties. A tag already given to another image moves to
+     * this one.
+     * @param options The repository (`registry.example.com/team/app`) and the tag (`latest` by default).
+     * @throws {DockerImageNotFoundException} When the image was removed.
+     * @throws {DockerRequestException} When the name is invalid (HTTP 400).
+     */
+    tag(options: ImageTagOptions): Promise<void>;
+    /**
+     * Save the image as a tar archive, as `docker save`, which {@link Docker.importImage} loads. With `repoTag`, the
+     * archive holds that tag (restored when it is loaded); without it, the image is saved by ID, without its tags.
+     * @param options The `destination` (a file path, created or overwritten, or a writable stream, ended after the
+     * archive), the tag saved (`repoTag`), and `createRepoTagIfNotExists` (`true` by default) to add that tag to the image
+     * when it does not have it.
+     * @throws {DockerImageRepoTagNotFoundException} When the image does not have `repoTag` and
+     * `createRepoTagIfNotExists` is `false`.
+     * @throws {DockerImageNotFoundException} When the image was removed.
+     * @throws {Error} The error of the destination.
+     */
+    export(options: ImageExportOptions): Promise<void>;
+    /**
+     * Push the image to its registry, as `docker push`, and wait for its end. The image is first tagged `repo:tag` (the
+     * tag is kept afterwards).
+     * @param options The repository, with its registry (`registry.example.com/team/app`); the tag (`latest` by default);
+     * the registry credentials; and a callback receiving each progress message.
+     * @throws {DockerImagePushException} When the registry refuses the push (refused credentials, a repository not
+     * found).
+     * @throws {DockerImageNotFoundException} When the image was removed.
+     * @throws {DockerRequestException} When the daemon refuses to push it.
+     */
+    push(options: ImagePushOptions): Promise<void>;
+    /**
+     * Remove the image, as `docker rmi -f` by default: forced, it is removed with all its tags, even when a stopped
+     * container uses it.
+     * @param options `force` (`true` by default; `false` refuses an image with several tags or used by a container) and
+     * `noprune` (keeps its untagged parent images; `false` by default).
+     * @throws {DockerImageNotFoundException} When the image was already removed.
+     * @throws {DockerRequestException} When it is used by a running container or, without `force`, by any container or
+     * with several tags (HTTP 409).
+     */
+    remove(options?: ImageRemoveOptions): Promise<void>;
+    /**
+     * Create a container from the image, for its platform, then start it, as `docker run -d`.
+     * @param options The container's settings: name, command, environment, ports, binds, devices, networks, limits…
+     * @returns The container, started.
+     * @throws {DockerRequestException} When the name is already used (HTTP 409), or the start fails (HTTP 500: a command
+     * not found, a port already used); the container then stays created.
+     * @throws {DockerNetworkNotFoundException} When a network of the settings is not found.
+     * @throws {InvalidMethodAcceptException} When the settings are invalid.
+     */
+    run(options: ContainerSettingOptions): Promise<DockerContainer>;
+}

package/dist/types/docker/lib/EngineSettings.d.ts

@@ -0,0 +1,41 @@
+import { type ContainerSettingOptions } from '../options/container/ContainerSettingOptions.js';
+import { type ContainerRestartPolicy } from '../types/ContainerRestartPolicy.js';
+import { type DeviceMapping } from '../../client/types/DeviceMapping.js';
+import { type PortBinding } from '../../client/types/PortBinding.js';
+/**
+ * The restart policy of the Engine API: "on-failure:3" is the policy on-failure with 3 retries at most
+ * @param restartPolicy
+ */
+export declare function engineRestartPolicy(restartPolicy: ContainerRestartPolicy): {
+    Name: string;
+    MaximumRetryCount?: number;
+};
+/**
+ * The restart policy of a container, from the one of the Engine API
+ * @param restartPolicy
+ */
+export declare function parseRestartPolicy(restartPolicy?: {
+    Name?: string;
+    MaximumRetryCount?: number;
+} | null): ContainerRestartPolicy;
+/**
+ * The port bindings of the Engine API ("80/tcp": [{HostPort: "8080"}]): each host port once, null for a port published
+ * on no host port
+ * @param ports
+ */
+export declare function enginePortBindings(ports: NonNullable<ContainerSettingOptions['ports']>): Record<string, PortBinding[] | null>;
+/**
+ * The bind mounts of the Engine API ("hostPath:containerPath:rw")
+ * @param binds
+ */
+export declare function engineBinds(binds: NonNullable<ContainerSettingOptions['binds']>): string[];
+/**
+ * The devices of the Engine API
+ * @param devices
+ */
+export declare function engineDevices(devices: NonNullable<ContainerSettingOptions['devices']>): DeviceMapping[];
+/**
+ * The endpoints of the Engine API, by network: the static addresses given, none on the reserved networks
+ * @param networks
+ */
+export declare function engineEndpoints(networks: NonNullable<ContainerSettingOptions['networks']>): Record<string, Record<string, unknown>>;