From 08dbad47bc60e276fcab1de706229cf7cc63a8c5 Mon Sep 17 00:00:00 2001 From: Juergen Kunz Date: Mon, 24 Nov 2025 13:27:10 +0000 Subject: [PATCH] BREAKING CHANGE(DockerHost): Rename array-returning get* methods to list* on DockerHost and related resource classes; update docs, tests and changelog --- changelog.md | 29 ++++++++++++++++++++++++++++- package.json | 2 +- readme.hints.md | 4 ++-- readme.md | 18 +++++++++--------- test/test.nonci.node+deno.ts | 8 ++++---- ts/00_commitinfo_data.ts | 2 +- ts/classes.container.ts | 2 +- ts/classes.host.ts | 20 ++++++++++---------- ts/classes.image.ts | 2 +- ts/classes.network.ts | 4 ++-- ts/classes.secret.ts | 2 +- ts/classes.service.ts | 2 +- 12 files changed, 61 insertions(+), 34 deletions(-) diff --git a/changelog.md b/changelog.md index 7b1b955..a80ad44 100644 --- a/changelog.md +++ b/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. diff --git a/package.json b/package.json index 9558e50..c33b5b0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@apiclient.xyz/docker", - "version": "3.0.2", + "version": "4.0.0", "description": "Provides easy communication with Docker remote API from Node.js, with TypeScript support.", "private": false, "main": "dist_ts/index.js", diff --git a/readme.hints.md b/readme.hints.md index 799239b..e481870 100644 --- a/readme.hints.md +++ b/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(...)` diff --git a/readme.md b/readme.md index 34585b8..6781294 100644 --- a/readme.md +++ b/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 { ```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(', ') : ''}`); @@ -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) { diff --git a/test/test.nonci.node+deno.ts b/test/test.nonci.node+deno.ts index 4ed0217..4da6e57 100644 --- a/test/test.nonci.node+deno.ts +++ b/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'); diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 7095cf7..9df4d5c 100644 --- a/ts/00_commitinfo_data.ts +++ b/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.' } diff --git a/ts/classes.container.ts b/ts/classes.container.ts index 8993ab8..619cf43 100644 --- a/ts/classes.container.ts +++ b/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, diff --git a/ts/classes.host.ts b/ts/classes.host.ts index b509f04..c27e84c 100644 --- a/ts/classes.host.ts +++ b/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); } diff --git a/ts/classes.image.ts b/ts/classes.image.ts index 0f2ef21..0526e1d 100644 --- a/ts/classes.image.ts +++ b/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[] = []; diff --git a/ts/classes.network.ts b/ts/classes.network.ts index 8025f44..b13a301 100644 --- a/ts/classes.network.ts +++ b/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); }); diff --git a/ts/classes.secret.ts b/ts/classes.secret.ts index f3a90cb..6a31db9 100644 --- a/ts/classes.secret.ts +++ b/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'); diff --git a/ts/classes.service.ts b/ts/classes.service.ts index c2db7a6..4f4087c 100644 --- a/ts/classes.service.ts +++ b/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[] = [];