v5.0.0

changelog.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 2025-11-24 - 5.0.0 - BREAKING CHANGE(DockerHost)
+Rename array-returning get* methods to list* on DockerHost and related resource classes; update docs, tests and changelog
+
+- Renamed public DockerHost methods: getContainers → listContainers, getNetworks → listNetworks, getServices → listServices, getImages → listImages, getSecrets → listSecrets.
+- Renamed DockerNetwork.getContainersOnNetwork → DockerNetwork.listContainersOnNetwork and updated usages (e.g. getContainersOnNetworkForService).
+- Updated internal/static method docs/comments to recommend dockerHost.list*() usage and adjusted implementations accordingly.
+- Updated README, readme.hints.md, tests (test.nonci.node+deno.ts) and changelog to reflect the new list* method names.
+- Bumped package version to 4.0.0.
+- Migration note: replace calls to get*() with list*() for methods that return multiple items (arrays). Single-item getters such as getContainerById or getNetworkByName remain unchanged.
+
+## 2025-11-24 - 4.0.0 - BREAKING CHANGE: Rename list methods for consistency
+
+**Breaking Changes:**
+- Renamed all "get*" methods that return arrays to "list*" methods for better clarity:
+  - `getContainers()` → `listContainers()`
+  - `getNetworks()` → `listNetworks()`
+  - `getServices()` → `listServices()`
+  - `getImages()` → `listImages()`
+  - `getSecrets()` → `listSecrets()`
+  - `getContainersOnNetwork()` → `listContainersOnNetwork()` (on DockerNetwork class)
+
+**Migration Guide:**
+Update all method calls from `get*()` to `list*()` where the method returns an array of resources. Single-item getters like `getContainerById()`, `getNetworkByName()`, etc. remain unchanged.
+
+**Rationale:**
+The `list*` naming convention more clearly indicates that these methods return multiple items (arrays), while `get*` methods are reserved for retrieving single items by ID or name. This follows standard API design patterns and improves code readability.
+
 ## 2025-11-24 - 3.0.2 - fix(readme)
 Update README to document 3.0.0+ changes: architecture refactor, streaming improvements, health check and circular dependency fixes
 
@@ -29,7 +56,7 @@ Refactor public API to DockerHost facade; introduce DockerResource base; make re
 - Streaming compatibility: updated requestStreaming to convert web ReadableStreams (smartrequest v5+) to Node.js streams via smartstream.nodewebhelpers, preserving backward compatibility for existing streaming APIs (container logs, attach, exec, image import/export, events).
 - Container enhancements: added full lifecycle and streaming/interactive APIs on DockerContainer: refresh(), inspect(), start(), stop(), remove(), logs(), stats(), streamLogs(), attach(), exec().
 - Service creation updated: resolves image/network/secret descriptors (strings or instances); adds labels.version from image; improved resource handling and port/secret/network resolution.
-- Network and Secret classes updated to extend DockerResource and to expose refresh(), remove() and lookup methods via DockerHost (createNetwork/getNetworks/getNetworkByName, createSecret/getSecrets/getSecretByName/getSecretById).
+- Network and Secret classes updated to extend DockerResource and to expose refresh(), remove() and lookup methods via DockerHost (createNetwork/listNetworks/getNetworkByName, createSecret/listSecrets/getSecretByName/getSecretById).
 - Tests and docs updated: migration guide and examples added (readme.hints.md, README); test timeout reduced from 600s to 300s in package.json.
 - BREAKING: Public API changes require consumers to migrate away from direct resource static calls and direct imageStore access to the new DockerHost-based factory methods and storeImage/retrieveImage APIs.
 

package.json

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

readme.hints.md

@@ -19,7 +19,7 @@ The module has been restructured to follow a clean OOP Facade pattern:
   const network = await DockerNetwork.createNetwork(dockerHost, descriptor);
 
   // New (clean API):
-  const containers = await dockerHost.getContainers();
+  const containers = await dockerHost.listContainers();
   const network = await dockerHost.createNetwork(descriptor);
   ```
 
@@ -113,7 +113,7 @@ await dockerHost.createService({
 
 ### Migration Guide
 Replace all static method calls with dockerHost methods:
-- `DockerContainer.getContainers(host)` → `dockerHost.getContainers()`
+- `DockerContainer.getContainers(host)` → `dockerHost.listContainers()`
 - `DockerImage.createFromRegistry(host, opts)` → `dockerHost.createImageFromRegistry(opts)`
 - `DockerService.createService(host, desc)` → `dockerHost.createService(desc)`
 - `dockerHost.imageStore.storeImage(...)` → `dockerHost.storeImage(...)`

readme.md

@@ -48,7 +48,7 @@ await docker.ping();
 console.log('✅ Docker is running');
 
 // List all containers
-const containers = await docker.getContainers();
+const containers = await docker.listContainers();
 console.log(`Found ${containers.length} containers`);
 
 // Get a specific container and interact with it
@@ -71,7 +71,7 @@ The module follows a **Facade pattern** with `DockerHost` as the single entry po
 const docker = new DockerHost({});
 
 // All operations go through DockerHost
-const containers = await docker.getContainers();        // List containers
+const containers = await docker.listContainers();       // List containers
 const container = await docker.getContainerById('id');  // Get specific container
 const network = await docker.createNetwork({ Name: 'my-net' });  // Create network
 const service = await docker.createService(descriptor); // Deploy service
@@ -181,7 +181,7 @@ async function waitForDocker(timeoutMs = 10000): Promise<void> {
 
 ```typescript
 // Get all containers (running and stopped)
-const containers = await docker.getContainers();
+const containers = await docker.listContainers();
 
 containers.forEach((container) => {
   console.log(`Container: ${container.Names[0]}`);
@@ -406,7 +406,7 @@ writeStream.on('finish', () => {
 #### List All Images
 
 ```typescript
-const images = await docker.getImages();
+const images = await docker.listImages();
 
 images.forEach((img) => {
   console.log(`Image: ${img.RepoTags ? img.RepoTags.join(', ') : '<none>'}`);
@@ -444,7 +444,7 @@ console.log(`Network created: ${network.Name} (${network.Id})`);
 
 ```typescript
 // Get all networks
-const networks = await docker.getNetworks();
+const networks = await docker.listNetworks();
 
 networks.forEach((net) => {
   console.log(`Network: ${net.Name} (${net.Driver})`);
@@ -456,7 +456,7 @@ networks.forEach((net) => {
 const appNetwork = await docker.getNetworkByName('my-app-network');
 
 // Get containers connected to this network
-const containers = await appNetwork.getContainersOnNetwork();
+const containers = await appNetwork.listContainersOnNetwork();
 console.log(`Containers on network: ${containers.length}`);
 ```
 
@@ -523,7 +523,7 @@ console.log(`Service deployed: ${service.ID}`);
 
 ```typescript
 // List all services
-const services = await docker.getServices();
+const services = await docker.listServices();
 
 services.forEach((service) => {
   console.log(`Service: ${service.Spec.Name}`);
@@ -566,7 +566,7 @@ const secret = await docker.createSecret({
 console.log(`Secret created: ${secret.ID}`);
 
 // List all secrets
-const secrets = await docker.getSecrets();
+const secrets = await docker.listSecrets();
 secrets.forEach((s) => {
   console.log(`Secret: ${s.Spec.Name}`);
   console.log(`  Labels:`, s.Spec.Labels);
@@ -868,7 +868,7 @@ async function healthCheckService() {
 
   try {
     await docker.ping();
-    const containers = await docker.getContainers();
+    const containers = await docker.listContainers();
 
     const unhealthy = containers.filter(c => c.State !== 'running');
     if (unhealthy.length > 0) {

test/test.nonci.node+deno.ts

@@ -22,13 +22,13 @@ tap.test('should create a docker swarm', async () => {
 
 // Containers
 tap.test('should list containers', async () => {
-  const containers = await testDockerHost.getContainers();
+  const containers = await testDockerHost.listContainers();
   console.log(containers);
 });
 
 // Networks
 tap.test('should list networks', async () => {
-  const networks = await testDockerHost.getNetworks();
+  const networks = await testDockerHost.listNetworks();
   console.log(networks);
 });
 
@@ -86,7 +86,7 @@ tap.test('should activate swarm mode', async () => {
 });
 
 tap.test('should list all services', async (tools) => {
-  const services = await testDockerHost.getServices();
+  const services = await testDockerHost.listServices();
   console.log(services);
 });
 
@@ -169,7 +169,7 @@ tap.test('should expose a working DockerImageStore', async () => {
 let testContainer: docker.DockerContainer;
 
 tap.test('should get an existing container for streaming tests', async () => {
-  const containers = await testDockerHost.getContainers();
+  const containers = await testDockerHost.listContainers();
 
   // Use the first running container we find
   testContainer = containers.find((c) => c.State === 'running');

ts/00_commitinfo_data.ts

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

ts/classes.container.ts

@@ -10,7 +10,7 @@ export class DockerContainer extends DockerResource {
 
   /**
    * Internal: Get all containers
-   * Public API: Use dockerHost.getContainers() instead
+   * Public API: Use dockerHost.listContainers() instead
    */
   public static async _list(
     dockerHostArg: DockerHost,

ts/classes.host.ts

@@ -129,9 +129,9 @@ export class DockerHost {
   // ==============
 
   /**
-   * Gets all networks
+   * Lists all networks
    */
-  public async getNetworks() {
+  public async listNetworks() {
     return await DockerNetwork._list(this);
   }
 
@@ -156,9 +156,9 @@ export class DockerHost {
   // ==============
 
   /**
-   * Gets all containers
+   * Lists all containers
    */
-  public async getContainers() {
+  public async listContainers() {
     return await DockerContainer._list(this);
   }
 
@@ -183,9 +183,9 @@ export class DockerHost {
   // ==============
 
   /**
-   * Gets all services
+   * Lists all services
    */
-  public async getServices() {
+  public async listServices() {
     return await DockerService._list(this);
   }
 
@@ -210,9 +210,9 @@ export class DockerHost {
   // ==============
 
   /**
-   * Gets all images
+   * Lists all images
    */
-  public async getImages() {
+  public async listImages() {
     return await DockerImage._list(this);
   }
 
@@ -259,9 +259,9 @@ export class DockerHost {
   // ==============
 
   /**
-   * Gets all secrets
+   * Lists all secrets
    */
-  public async getSecrets() {
+  public async listSecrets() {
     return await DockerSecret._list(this);
   }
 

ts/classes.image.ts

@@ -12,7 +12,7 @@ export class DockerImage extends DockerResource {
 
   /**
    * Internal: Get all images
-   * Public API: Use dockerHost.getImages() instead
+   * Public API: Use dockerHost.listImages() instead
    */
   public static async _list(dockerHost: DockerHost) {
     const images: DockerImage[] = [];

ts/classes.network.ts

@@ -129,7 +129,7 @@ export class DockerNetwork extends DockerResource {
     );
   }
 
-  public async getContainersOnNetwork(): Promise<
+  public async listContainersOnNetwork(): Promise<
     Array<{
       Name: string;
       EndpointID: string;
@@ -151,7 +151,7 @@ export class DockerNetwork extends DockerResource {
   }
 
   public async getContainersOnNetworkForService(serviceArg: DockerService) {
-    const containersOnNetwork = await this.getContainersOnNetwork();
+    const containersOnNetwork = await this.listContainersOnNetwork();
     const containersOfService = containersOnNetwork.filter((container) => {
       return container.Name.startsWith(serviceArg.Spec.Name);
     });

ts/classes.secret.ts

@@ -10,7 +10,7 @@ export class DockerSecret extends DockerResource {
 
   /**
    * Internal: Get all secrets
-   * Public API: Use dockerHost.getSecrets() instead
+   * Public API: Use dockerHost.listSecrets() instead
    */
   public static async _list(dockerHostArg: DockerHost) {
     const response = await dockerHostArg.request('GET', '/secrets');

ts/classes.service.ts

@@ -12,7 +12,7 @@ export class DockerService extends DockerResource {
 
   /**
    * Internal: Get all services
-   * Public API: Use dockerHost.getServices() instead
+   * Public API: Use dockerHost.listServices() instead
    */
   public static async _list(dockerHost: DockerHost) {
     const services: DockerService[] = [];