v2.1.0

changelog.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2025-11-18 - 2.1.0 - feat(DockerHost)
+Add DockerHost.ping() to check Docker daemon availability and document health-check usage
+
+- Add DockerHost.ping() method that issues a GET to /_ping and throws an error if the response status is not 200
+- Update README: show ping() in Quick Start, add health check examples (isDockerHealthy, waitForDocker) and mention Health Checks in Key Concepts
+
 ## 2025-11-18 - 2.0.0 - BREAKING CHANGE(DockerHost)
 Rename DockerHost constructor option 'dockerSockPath' to 'socketPath' and update internal socket path handling
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apiclient.xyz/docker",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Provides easy communication with Docker remote API from Node.js, with TypeScript support.",
   "private": false,
   "main": "dist_ts/index.js",

readme.md

@@ -38,11 +38,9 @@ import { DockerHost } from '@apiclient.xyz/docker';
 const docker = new DockerHost({});
 await docker.start();
 
-// Or connect to remote Docker host via TCP
+// Check if Docker is accessible
-const remoteDocker = new DockerHost({
+await docker.ping();
-  socketPath: 'tcp://192.168.1.100:2375',
+console.log('✅ Docker is running');
-});
-await remoteDocker.start();
 
 // List all containers
 const containers = await docker.getContainers();
@@ -100,6 +98,48 @@ await docker.start();
 await docker.stop();
 ```
 
+#### Health Check / Ping Docker
+
+Check if the Docker daemon is running and accessible:
+
+```typescript
+// Ping Docker daemon
+try {
+  await docker.ping();
+  console.log('✅ Docker is running and accessible');
+} catch (error) {
+  console.error('❌ Docker is not accessible:', error.message);
+}
+
+// Use in health check function
+async function isDockerHealthy(): Promise<boolean> {
+  try {
+    await docker.ping();
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+// Example: Wait for Docker to be ready
+async function waitForDocker(timeoutMs = 10000): Promise<void> {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeoutMs) {
+    try {
+      await docker.ping();
+      console.log('✅ Docker is ready');
+      return;
+    } catch (error) {
+      console.log('⏳ Waiting for Docker...');
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+  }
+
+  throw new Error('Docker did not become available within timeout');
+}
+```
+
 ### 📦 Container Management
 
 #### List All Containers
@@ -681,6 +721,7 @@ if (webService && webService.Spec.Mode.Replicated) {
 ## 🔑 Key Concepts
 
 - **DockerHost**: Main entry point for Docker API communication
+- **Health Checks**: Use `ping()` method to verify Docker daemon accessibility
 - **Socket Path Priority**: Constructor option → `DOCKER_HOST` env → CI mode → default socket
 - **Swarm Mode Required**: Services and secrets require Docker Swarm to be activated
 - **Type Safety**: Full TypeScript support with comprehensive interfaces

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@apiclient.xyz/docker',
-  version: '2.0.0',
+  version: '2.1.0',
   description: 'Provides easy communication with Docker remote API from Node.js, with TypeScript support.'
 }

ts/classes.host.ts

@@ -74,6 +74,18 @@ export class DockerHost {
     await this.imageStore.stop();
   }
 
+  /**
+   * Ping the Docker daemon to check if it's running and accessible
+   * @returns Promise that resolves if Docker is available, rejects otherwise
+   * @throws Error if Docker ping fails
+   */
+  public async ping(): Promise<void> {
+    const response = await this.request('GET', '/_ping');
+    if (response.statusCode !== 200) {
+      throw new Error(`Docker ping failed with status ${response.statusCode}`);
+    }
+  }
+
   /**
    * authenticate against a registry
    * @param userArg