@tahminator/pipeline 1.0.59 → 1.0.60

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/index.d.ts

@@ -5,5 +5,7 @@ export * from "./sonar";
 export * from "./pulumi";
 export * from "./types";
 export * from "./env";
+export * from "./postgres";
+export * from "./redis";
 export * from "./utils";
 export * from "./versioning";

package/dist/index.js

@@ -5,5 +5,7 @@ export * from "./sonar";
 export * from "./pulumi";
 export * from "./types";
 export * from "./env";
+export * from "./postgres";
+export * from "./redis";
 export * from "./utils";
 export * from "./versioning";

package/dist/internal/upload-npm/beta/index.js

@@ -42,7 +42,7 @@ async function main() {
         message: `
 ## Test Version Uploaded
 
-Uploaded \`${betaVersion}\` to NPM. View version on NPM registry [here](https://www.npmjs.com/package/@tahminator/pipeline/v/${betaVersion}).
+Uploaded \`@tahminator/pipeline@${betaVersion}\` to NPM. View version on NPM registry [here](https://www.npmjs.com/package/@tahminator/pipeline/v/${betaVersion}).
 `,
     });
 }

package/dist/postgres/client.d.ts

@@ -0,0 +1,37 @@
+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;
+    get state(): PostgresInternalState;
+    [Symbol.asyncDispose](): Promise<void>;
+    cleanup(): Promise<void>;
+}

package/dist/postgres/client.js

@@ -0,0 +1,107 @@
+import { $, randomUUIDv7 } from "bun";
+import { Utils } from "../utils";
+export class LocalPostgresClient {
+    iState;
+    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,
+            user: "postgres",
+            password: "postgres",
+            port: 5432,
+            host: "127.0.0.1",
+            dockerName: `local-db-${randomUUIDv7()}`,
+        };
+        const hostPort = await this.launch(iState);
+        iState.port = hostPort;
+        await this.waitUntilReady(iState);
+        return new this(iState);
+    }
+    static async launch(iState) {
+        await $ `docker run -d \
+        --name ${iState.dockerName} \
+        -e POSTGRES_USER=${iState.user} \
+        -e POSTGRES_PASSWORD=${iState.password} \
+        -e POSTGRES_DB=${iState.database} \
+        -p 5432 \
+        mirror.gcr.io/library/postgres:16-alpine`;
+        const raw = (await $ `docker port ${iState.dockerName} 5432/tcp`.text()).trim();
+        const match = raw.match(/:(\d+)/);
+        if (!match) {
+            throw new Error(`Could not parse host port from: ${raw}`);
+        }
+        return Number(match[1]);
+    }
+    static async waitUntilReady(iState) {
+        console.log(`Waiting for ${iState.dockerName} to become ready.`);
+        const attempts = 30;
+        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);
+        }
+        console.log(`${iState.dockerName} is ready`);
+    }
+    get state() {
+        return this.iState;
+    }
+    async [Symbol.asyncDispose]() {
+        await this.cleanup();
+    }
+    async cleanup() {
+        console.log(`Stopping and removing ${this.iState.dockerName} container...`);
+        if (Utils.Log.isDebug) {
+            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(`=== ${this.iState.dockerName} LOGS END ===`));
+        }
+        await $ `docker stop ${this.iState.dockerName}`.quiet().nothrow();
+        await $ `docker rm ${this.iState.dockerName}`.quiet().nothrow();
+    }
+}

package/dist/postgres/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./types";

package/dist/postgres/index.js

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./types";

package/dist/postgres/types.d.ts

@@ -0,0 +1,10 @@
+export interface PostgresState {
+    database: string;
+}
+export interface PostgresInternalState extends PostgresState {
+    port: number;
+    host: string;
+    user: string;
+    password: string;
+    dockerName: string;
+}

package/dist/redis/client.d.ts

@@ -0,0 +1,37 @@
+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;
+    get state(): RedisInternalState;
+    [Symbol.asyncDispose](): Promise<void>;
+    cleanup(): Promise<void>;
+}

package/dist/redis/client.js

@@ -0,0 +1,104 @@
+import { $, randomUUIDv7 } from "bun";
+import { Utils } from "../utils";
+export class LocalRedisClient {
+    iState;
+    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,
+            password: "redis",
+            port: 6379,
+            host: "127.0.0.1",
+            dockerName: `local-redis-${randomUUIDv7()}`,
+        };
+        const hostPort = await this.launch(iState);
+        iState.port = hostPort;
+        await this.waitUntilReady(iState);
+        return new this(iState);
+    }
+    static async launch(iState) {
+        await $ `docker run -d \
+        --name ${iState.dockerName} \
+        -p 6379 \
+        mirror.gcr.io/library/redis:7-alpine \
+        redis-server --requirepass ${iState.password}`;
+        const raw = (await $ `docker port ${iState.dockerName} 6379/tcp`.text()).trim();
+        const match = raw.match(/:(\d+)/);
+        if (!match) {
+            throw new Error(`Could not parse host port from: ${raw}`);
+        }
+        return Number(match[1]);
+    }
+    static async waitUntilReady(iState) {
+        console.log(`Waiting for ${iState.dockerName} to become ready.`);
+        const attempts = 30;
+        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);
+        }
+        console.log(`${iState.dockerName} is ready`);
+    }
+    get state() {
+        return this.iState;
+    }
+    async [Symbol.asyncDispose]() {
+        await this.cleanup();
+    }
+    async cleanup() {
+        console.log(`Stopping and removing ${this.iState.dockerName} container...`);
+        if (Utils.Log.isDebug) {
+            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(`=== ${this.iState.dockerName} LOGS END ===`));
+        }
+        await $ `docker stop ${this.iState.dockerName}`.quiet().nothrow();
+        await $ `docker rm ${this.iState.dockerName}`.quiet().nothrow();
+    }
+}

package/dist/redis/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./types";

package/dist/redis/index.js

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./types";

package/dist/redis/types.d.ts

@@ -0,0 +1,8 @@
+export interface RedisState {
+}
+export interface RedisInternalState extends RedisState {
+    port: number;
+    host: string;
+    password: string;
+    dockerName: string;
+}

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",
+  "version": "1.0.60",
   "repository": {
     "url": "git+https://github.com/tahminator/pipeline.git"
   },