@tahminator/pipeline 1.0.59-beta.4cc29c8c → 1.0.59-beta.7832b36f

package/README.md

@@ -42,9 +42,30 @@ import {
   SonarScannerClient,
   Utils,
   VersioningClient,
+  LocalPostgresClient,
+  LocalRedisClient,
 } from "@tahminator/pipeline";
 ```
 
+Jump to client documentation
+
+<!-- toc -->
+
+- [`GitHubClient`](#githubclient)
+- [`DockerClient`](#dockerclient)
+- [`NPMClient`](#npmclient)
+- [`SonarScannerClient`](#sonarscannerclient)
+- [`Utils`](#utils)
+- [`EnvClient`](#envclient)
+- [`PulumiClient`](#pulumiclient)
+- [`VersioningClient`](#versioningclient)
+- [`LocalPostgresClient`](#localpostgresclient)
+- [`LocalRedisClient`](#localredisclient)
+
+<!-- tocstop -->
+
+<!-- if toc does not update automatically, `markdown-toc -i README.md` -->
+
 > [!NOTE]
 > While there is documentation below, each API should be relatively well commented and be more up to date than what is seen below.
 
@@ -328,3 +349,65 @@ if (!Utils.SemVer.validate(beta)) throw new Error("invalid beta version");
 
 await versioning.update(beta);
 ```
+
+### `LocalPostgresClient`
+
+Spin up a disposable local Postgres instance via Docker. Useful for running migrations or acceptance tests against a real database in CI / local dev.
+
+Each call to `create()` gets a unique container name and a Docker-assigned host port, so multiple instances can coexist without conflict.
+
+```ts
+import { $ } from "bun";
+
+async function main() {
+  await using pgClient = await LocalPostgresClient.create({
+    database: "instalock-server-acceptance",
+  });
+
+  // get credentials
+  const { database, host, port, password, user } = pgClient.state;
+
+  await $.env({
+    ...process.env,
+    DB_HOST: host,
+    DB_PORT: String(port),
+    DB_NAME: database,
+    DB_USERNAME: user,
+    DB_PASSWORD: password,
+  })`just migrate`;
+
+  // `pgClient` will automatically be cleaned up when `main` returns.
+  // Set DEBUG=true in the env to dump container logs on cleanup.
+}
+
+await main();
+```
+
+### `LocalRedisClient`
+
+Spin up a disposable local Redis instance via Docker.
+
+Each call to `create()` gets a unique container name and a Docker-assigned host port, so multiple instances can coexist without conflict.
+
+```ts
+import { $ } from "bun";
+
+async function main() {
+  await using redisClient = await LocalRedisClient.create();
+
+  // get credentials
+  const { port, password, host } = redisClient.state;
+
+  await $.env({
+    ...process.env,
+    REDIS_HOST: host,
+    REDIS_PORT: String(port),
+    REDIS_PASSWORD: password,
+  })`./gradlew bootRun`;
+
+  // `redisClient` will automatically be cleaned up when `main` returns.
+  // Set DEBUG=true in the env to dump container logs on cleanup.
+}
+
+await main();
+```

package/dist/postgres/client.d.ts

@@ -2,6 +2,32 @@ import type { PostgresInternalState, PostgresState } from "./types";
 export declare class LocalPostgresClient {
     private readonly iState;
     private constructor();
+    /**
+     * Spin up a local Postgres instance via Docker.
+     *
+     * @example
+     * ```ts
+        async function main() {
+          await using pgClient = await LocalPostgresClient.create({
+            database: "instalock-server-acceptance",
+          });
+  
+          // get credentials
+          const { database, host, port, password, user } = pgClient.state;
+  
+          $.env({
+            ...process.env,
+            DB_HOST: host,
+            DB_PORT: String(port),
+            DB_NAME: database,
+            DB_USERNAME: user,
+            DB_PASSWORD: password,
+          })`just migrate`
+  
+          // `pgClient` will be automatically cleaned up at the end of the scope.
+        }
+     * ```
+     */
     static create(state: PostgresState): Promise<LocalPostgresClient>;
     private static launch;
     private static waitUntilReady;

package/dist/postgres/client.js

@@ -5,6 +5,32 @@ export class LocalPostgresClient {
     constructor(iState) {
         this.iState = iState;
     }
+    /**
+     * Spin up a local Postgres instance via Docker.
+     *
+     * @example
+     * ```ts
+        async function main() {
+          await using pgClient = await LocalPostgresClient.create({
+            database: "instalock-server-acceptance",
+          });
+  
+          // get credentials
+          const { database, host, port, password, user } = pgClient.state;
+  
+          $.env({
+            ...process.env,
+            DB_HOST: host,
+            DB_PORT: String(port),
+            DB_NAME: database,
+            DB_USERNAME: user,
+            DB_PASSWORD: password,
+          })`just migrate`
+  
+          // `pgClient` will be automatically cleaned up at the end of the scope.
+        }
+     * ```
+     */
     static async create(state) {
         const iState = {
             ...state,
@@ -37,20 +63,26 @@ export class LocalPostgresClient {
     static async waitUntilReady(iState) {
         console.log(`Waiting for ${iState.dockerName} to become ready.`);
         const attempts = 30;
-        for (let i = 1; i <= attempts; i++) {
-            const check = await $ `docker exec ${iState.dockerName} pg_isready -U ${iState.user}`
-                .quiet()
-                .nothrow();
-            if (check.exitCode === 0) {
-                console.log(`${iState.dockerName} is ready`);
-                return;
-            }
-            console.log(`Waiting for ${iState.dockerName}... (${i}/${attempts})`);
-            await Bun.sleep(2000);
+        const ready = await Utils.waitUntil({
+            attempts,
+            intervalMs: 2000,
+            predicate: async (attempt) => {
+                const check = await $ `docker exec ${iState.dockerName} pg_isready -U ${iState.user}`
+                    .quiet()
+                    .nothrow();
+                if (check.exitCode === 0) {
+                    return true;
+                }
+                console.log(`Waiting for ${iState.dockerName}... (${attempt}/${attempts})`);
+                return false;
+            },
+        });
+        if (!ready) {
+            const msg = `${iState.dockerName} failed to launch`;
+            console.error(msg);
+            throw new Error(msg);
         }
-        const msg = `${iState.dockerName} failed to launch`;
-        console.error(msg);
-        throw new Error(msg);
+        console.log(`${iState.dockerName} is ready`);
     }
     get state() {
         return this.iState;
@@ -61,13 +93,13 @@ export class LocalPostgresClient {
     async cleanup() {
         console.log(`Stopping and removing ${this.iState.dockerName} container...`);
         if (Utils.Log.isDebug) {
-            console.log(Utils.Colors.brightMagenta("=== DB LOGS ==="));
+            console.log(Utils.Colors.brightMagenta(`=== ${this.iState.dockerName} LOGS ===`));
             const logs = await $ `docker logs ${this.iState.dockerName}`.text();
             logs
                 .split("\n")
                 .filter((s) => s.length > 0)
                 .forEach((line) => console.log(Utils.Colors.brightMagenta(line)));
-            console.log(Utils.Colors.brightMagenta("=== DB LOGS END ==="));
+            console.log(Utils.Colors.brightMagenta(`=== ${this.iState.dockerName} LOGS END ===`));
         }
         await $ `docker stop ${this.iState.dockerName}`.quiet().nothrow();
         await $ `docker rm ${this.iState.dockerName}`.quiet().nothrow();

package/dist/redis/client.d.ts

@@ -2,6 +2,32 @@ import type { RedisInternalState, RedisState } from "./types";
 export declare class LocalRedisClient {
     private readonly iState;
     private constructor();
+    /**
+     * Spin up a local Redis instance via Docker.
+     *
+     * @example
+     * ```ts
+        async function main() {
+          await using redisClient = await LocalRedisClient.create();
+  
+          // get credentials
+          const {
+            port,
+            password,
+            host,
+          } = redisClient.state;
+  
+          $.env({
+            ...process.env,
+            REDISHOST: host,
+            REDIS_PORT: String(port),
+            REDIS_PASSWORD: password,
+          })`./gradlew bootRun`
+  
+          // `redisClient` will be automatically cleaned up at the end of the scope.
+        }
+     * ```
+     */
     static create(state?: RedisState): Promise<LocalRedisClient>;
     private static launch;
     private static waitUntilReady;

package/dist/redis/client.js

@@ -5,6 +5,32 @@ export class LocalRedisClient {
     constructor(iState) {
         this.iState = iState;
     }
+    /**
+     * Spin up a local Redis instance via Docker.
+     *
+     * @example
+     * ```ts
+        async function main() {
+          await using redisClient = await LocalRedisClient.create();
+  
+          // get credentials
+          const {
+            port,
+            password,
+            host,
+          } = redisClient.state;
+  
+          $.env({
+            ...process.env,
+            REDISHOST: host,
+            REDIS_PORT: String(port),
+            REDIS_PASSWORD: password,
+          })`./gradlew bootRun`
+  
+          // `redisClient` will be automatically cleaned up at the end of the scope.
+        }
+     * ```
+     */
     static async create(state = {}) {
         const iState = {
             ...state,
@@ -34,20 +60,26 @@ export class LocalRedisClient {
     static async waitUntilReady(iState) {
         console.log(`Waiting for ${iState.dockerName} to become ready.`);
         const attempts = 30;
-        for (let i = 1; i <= attempts; i++) {
-            const check = await $ `docker exec ${iState.dockerName} redis-cli -a ${iState.password} ping`
-                .quiet()
-                .nothrow();
-            if (check.exitCode === 0) {
-                console.log(`${iState.dockerName} is ready`);
-                return;
-            }
-            console.log(`Waiting for ${iState.dockerName}... (${i}/${attempts})`);
-            await Bun.sleep(2000);
+        const ready = await Utils.waitUntil({
+            attempts,
+            intervalMs: 2000,
+            predicate: async (attempt) => {
+                const check = await $ `docker exec ${iState.dockerName} redis-cli -a ${iState.password} ping`
+                    .quiet()
+                    .nothrow();
+                if (check.exitCode === 0) {
+                    return true;
+                }
+                console.log(`Waiting for ${iState.dockerName}... (${attempt}/${attempts})`);
+                return false;
+            },
+        });
+        if (!ready) {
+            const msg = `${iState.dockerName} failed to launch`;
+            console.error(msg);
+            throw new Error(msg);
         }
-        const msg = `${iState.dockerName} failed to launch`;
-        console.error(msg);
-        throw new Error(msg);
+        console.log(`${iState.dockerName} is ready`);
     }
     get state() {
         return this.iState;
@@ -58,13 +90,13 @@ export class LocalRedisClient {
     async cleanup() {
         console.log(`Stopping and removing ${this.iState.dockerName} container...`);
         if (Utils.Log.isDebug) {
-            console.log(Utils.Colors.brightMagenta("=== REDIS LOGS ==="));
+            console.log(Utils.Colors.brightMagenta(`=== ${this.iState.dockerName} LOGS ===`));
             const logs = await $ `docker logs ${this.iState.dockerName}`.text();
             logs
                 .split("\n")
                 .filter((s) => s.length > 0)
                 .forEach((line) => console.log(Utils.Colors.brightMagenta(line)));
-            console.log(Utils.Colors.brightMagenta("=== REDIS LOGS END ==="));
+            console.log(Utils.Colors.brightMagenta(`=== ${this.iState.dockerName} LOGS END ===`));
         }
         await $ `docker stop ${this.iState.dockerName}`.quiet().nothrow();
         await $ `docker rm ${this.iState.dockerName}`.quiet().nothrow();

package/dist/utils/client.d.ts

@@ -4,6 +4,7 @@ import { Colors } from "./colors";
 import { Log } from "./log";
 import { SemVer } from "./semver";
 import { generateShortId } from "./short";
+import { waitUntil } from "./wait";
 export declare class Utils {
     static Colors: typeof Colors;
     static Log: typeof Log;
@@ -11,4 +12,5 @@ export declare class Utils {
     static generateShortId(...args: Parameters<typeof generateShortId>): string;
     static isCmdAvailable(...args: Parameters<typeof isCmdAvailable>): Promise<boolean>;
     static decodeBase64EncodedString(...args: Parameters<typeof decodeBase64EncodedString>): Promise<string>;
+    static waitUntil(...args: Parameters<typeof waitUntil>): Promise<boolean>;
 }

package/dist/utils/client.js

@@ -4,6 +4,7 @@ import { Colors } from "./colors";
 import { Log } from "./log";
 import { SemVer } from "./semver";
 import { generateShortId } from "./short";
+import { waitUntil } from "./wait";
 export class Utils {
     // hoist
     static Colors = Colors;
@@ -18,4 +19,7 @@ export class Utils {
     static async decodeBase64EncodedString(...args) {
         return decodeBase64EncodedString(...args);
     }
+    static async waitUntil(...args) {
+        return waitUntil(...args);
+    }
 }

package/dist/utils/wait.d.ts

@@ -0,0 +1,5 @@
+export declare function waitUntil({ predicate, attempts, intervalMs, }: {
+    predicate: (attempt: number) => boolean | Promise<boolean>;
+    attempts?: number;
+    intervalMs?: number;
+}): Promise<boolean>;

package/dist/utils/wait.js

@@ -0,0 +1,9 @@
+export async function waitUntil({ predicate, attempts = 30, intervalMs = 2000, }) {
+    for (let i = 1; i <= attempts; i++) {
+        if (await predicate(i)) {
+            return true;
+        }
+        await Bun.sleep(intervalMs);
+    }
+    return false;
+}

package/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "author": "Tahmid Ahmed",
   "description": "A collection of Bun shell scripts that can be re-used in various CICD pipelines.",
-  "version": "1.0.59-beta.4cc29c8c",
+  "version": "1.0.59-beta.7832b36f",
   "repository": {
     "url": "git+https://github.com/tahminator/pipeline.git"
   },