@tahminator/pipeline 1.0.62 → 1.0.64

package/README.md

@@ -252,6 +252,7 @@ await frontendClient.uploadTestCoverage();
 Assorted helper class used by clients and useful as an exported class to pipelines.
 
 ```ts
+// ----- strings -----
 const githubPrivateKey = await Utils.decodeBase64EncodedString(
   process.env.GH_PRIVATE_KEY_B64!,
 );
@@ -262,9 +263,42 @@ if (await Utils.isCmdAvailable("gh")) {
   console.log(Utils.Colors.green(`gh is installed (${shortId})`));
 }
 
-if (!Utils.SemVer.validate("1.2.3")) throw new Error("invalid version");
+// ----- required -----
+const token = Utils.required(process.env.GITHUB_TOKEN); // will throw if null or undefined
+
+// ----- wait / polling -----
+const reachable = await Utils.waitUntil({
+  predicate: async () => await Utils.isCmdAvailable("docker"),
+  attempts: 10,
+  intervalMs: 500,
+});
+
+if (!reachable) throw new Error("docker unavailable");
+
+// ----- debug -----
+if (Utils.Log.isDebug) {
+  console.log(Utils.Colors.dim("debug logging enabled"));
+}
 ```
 
+Available Utils APIs:
+
+- `Utils.decodeBase64EncodedString(s: string): string`
+- `Utils.generateShortId(len = 7): string`
+- `Utils.isCmdAvailable(cmd: string): Promise<boolean>`
+- `Utils.waitUntil({ predicate, attempts?, intervalMs? }): Promise<boolean>`
+- `Utils.required<T>(value: T | null | undefined): T`
+- `Utils.SemVer.validate(version: string | semver.SemVer): boolean`
+- `Utils.Log.isDebug: boolean` (`true` when `DEBUG=true`)
+- `Utils.Colors.<formatter>(s: string): string`
+
+`Utils.Colors` formatters:
+
+- `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`
+- `brightRed`, `brightGreen`, `brightYellow`, `brightBlue`, `brightMagenta`, `brightCyan`, `brightWhite`
+- `pink`, `orange`
+- `bold`, `dim`, `italic`, `underline`
+
 ### `EnvClient`
 
 Load environment variables from encrypted files and automatically mask them in GitHub Actions logs.

package/dist/env/client.d.ts

@@ -1,8 +1,17 @@
 import { EnvClientStrategy, type EnvClientReadOpts } from "./types";
+export type EnvClientOpts = {
+    /**
+     * Skip GitHub Actions secret masking. Defaults to `false`.
+     *
+     * **NOTE**: Be very careful if you set this to `true`!
+     */
+    skipMasking?: boolean;
+};
 export declare class EnvClient {
     private readonly strategy;
+    private readonly opts;
     private constructor();
-    static create(strategy: EnvClientStrategy): EnvClient;
+    static create(strategy: EnvClientStrategy, opts?: EnvClientOpts): EnvClient;
     readFromEnv(fileName: string, opts?: EnvClientReadOpts): Promise<Record<string, string>>;
     private maskAndReturnEnv;
 }

package/dist/env/client.js

@@ -2,23 +2,28 @@ import { SopsEnvClientStrategy, GitCryptEnvClientStrategy, } from "./strategy";
 import { EnvClientStrategy } from "./types";
 export class EnvClient {
     strategy;
-    constructor(strategy) {
+    opts;
+    constructor(strategy, opts) {
         this.strategy = strategy;
+        this.opts = opts;
     }
-    static create(strategy) {
+    static create(strategy, opts = {
+        skipMasking: false,
+    }) {
         switch (strategy) {
             case EnvClientStrategy.SOPS:
-                return new this(new SopsEnvClientStrategy());
+                return new this(new SopsEnvClientStrategy(), opts);
             case EnvClientStrategy.GIT_CRYPT:
-                return new this(new GitCryptEnvClientStrategy());
+                return new this(new GitCryptEnvClientStrategy(), opts);
         }
     }
     async readFromEnv(fileName, opts) {
         return this.maskAndReturnEnv(await this.strategy.readFromEnv(fileName, opts));
     }
     maskAndReturnEnv(envs) {
-        if (process.env.CI !== "true") {
-            return Object.fromEntries(envs);
+        const r = Object.fromEntries(envs);
+        if (this.opts.skipMasking) {
+            return r;
         }
         for (const [varName, value] of envs.entries()) {
             if (value === "true" || value === "false" || value === "") {
@@ -38,6 +43,6 @@ export class EnvClient {
                 }
             }
         }
-        return Object.fromEntries(envs);
+        return r;
     }
 }

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 { required } from "./string";
 import { waitUntil } from "./wait";
 export declare class Utils {
     static Colors: typeof Colors;
@@ -13,4 +14,5 @@ export declare class Utils {
     static isCmdAvailable(...args: Parameters<typeof isCmdAvailable>): Promise<boolean>;
     static decodeBase64EncodedString(...args: Parameters<typeof decodeBase64EncodedString>): Promise<string>;
     static waitUntil(...args: Parameters<typeof waitUntil>): Promise<boolean>;
+    static required<T>(...args: Parameters<typeof required<T>>): T;
 }

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 { required } from "./string";
 import { waitUntil } from "./wait";
 export class Utils {
     // hoist
@@ -22,4 +23,7 @@ export class Utils {
     static async waitUntil(...args) {
         return waitUntil(...args);
     }
+    static required(...args) {
+        return required(...args);
+    }
 }

package/dist/utils/string.d.ts

@@ -0,0 +1 @@
+export declare function required<T>(value: T | null | undefined): T;

package/dist/utils/string.js

@@ -0,0 +1,6 @@
+export function required(value) {
+    if (value == null) {
+        throw new Error("Expected a value but received null or undefined");
+    }
+    return value;
+}

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