#3: Associate variable to CLI flag

.github/workflows/main.yml

@@ -1,34 +1,34 @@
 name: "CI: Test, Build, and Publish Package to npmjs"
 
 on:
-  release:
-    types: [published]
+    release:
+        types: [published]
 
 jobs:
-  build-and-publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
+    build-and-publish:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            id-token: write
 
-    steps:
-      - uses: actions/checkout@v4
+        steps:
+            - uses: actions/checkout@v4
 
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20.x"
-          registry-url: "https://registry.npmjs.org"
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: "20.x"
+                  registry-url: "https://registry.npmjs.org"
 
-      - name: Install dependencies
-        run: npm ci
+            - name: Install dependencies
+              run: npm ci
 
-      - name: Run tests
-        run: npm test
+            - name: Run tests
+              run: npm test
 
-      - name: Build package
-        run: npm run build
+            - name: Build package
+              run: npm run build
 
-      - name: Publish to npm
-        run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+            - name: Publish to npm
+              run: npm publish --provenance --access public
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/test-node.yml

@@ -0,0 +1,38 @@
+# Test package across all maintained/active/current versions of Node.js
+
+name: "CI: Test (Node.js)"
+
+on:
+    push:
+        branches:
+            - "main"
+    pull_request:
+
+concurrency:
+    group: node-build-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+
+        strategy:
+            fail-fast: false
+            matrix:
+                node-version: [20, 22, 24, 25]
+
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: ${{ matrix.node-version }}
+                  cache: npm
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Test
+              run: npm test

README.md

@@ -1,7 +1,9 @@
 # ManagedEnv
 
+[![CI: Test (Node.js)](https://github.com/GalvinPython/managedenv/actions/workflows/test-node.yml/badge.svg)](https://github.com/GalvinPython/managedenv/actions/workflows/test-node.yml)
 [![Publish Package to npmjs](https://github.com/GalvinPython/managedenv/actions/workflows/main.yml/badge.svg)](https://github.com/GalvinPython/managedenv/actions/workflows/main.yml)
 [![NPM Version](https://img.shields.io/npm/v/managedenv)](https://www.npmjs.com/package/managedenv)
+[![Supported NodeJS Versions](https://img.shields.io/badge/NodeJS%20Versions-20,22,24,25-blue)](https://www.npmjs.com/package/managedenv)
 
 Notice: ManagedEnv is currently in beta
 
@@ -60,6 +62,11 @@ API_KEY: test
 
 ## Preview
 
+### 0.2.0
+
+- Removed `flag` property in favour of `useFlagInstead`
+- Added new `useWithFlag` property to load an environment variable when an associated flag is passed into the arguments
+
 ### 0.1.0
 
 - Added documentation

SECURITY.md

@@ -8,9 +8,6 @@ Only the latest major version is actively maintained and receives security updat
 | ------- | --------- |
 | 0.x     | ✅        |
 
-<!-- For future reference -->
-<!-- | 0.x     | ❌        | -->
-
 ## Reporting a Vulnerability
 
 If you discover a security vulnerability in this project, please report it responsibly using one of the two listed methods. Do **not** create an issue about any vulnerabilities.
@@ -27,4 +24,4 @@ I prefer it if you [opened a GitHub security advisory](https://github.com/galvin
 
 ### Alternative Contact
 
-If you do not wish to use GitHub, you may send an email to `imgalvin@pm.me` with the details of the issue
+If you do not wish to use GitHub, you may send an email to `contact@socialstats.app` with the details of the issue

package.json

@@ -1,6 +1,6 @@
 {
   "name": "managedenv",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Manage your environment variables with ease",
   "repository": {
     "type": "git",
@@ -60,4 +60,4 @@
     "ts-jest": "^29.4.0",
     "typescript": "^5.8.3"
   }
-}
+}

src/index.ts

@@ -28,7 +28,12 @@ export interface VariableDefinition<T = unknown> {
     /**
      * Optional CLI flag (e.g., --token) that can be used instead of ENV.
      */
-    flag?: string;
+    useFlagInstead?: string;
+
+    /**
+     * Only load the variable if this CLI flag is present.
+     */
+    useWithFlag?: string;
 
     /**
      * Whether to quit the process if a required variable is missing.
@@ -88,20 +93,25 @@ export class EnvManager<T extends ProjectVars = {}> {
                 required = false,
                 default: defVal,
                 type = (v => v) as (val: string) => any,
-                flag,
+                useFlagInstead,
+                useWithFlag,
                 quitOnMissing,
             } = def;
 
             if (!result[project]) result[project] = {};
 
+            if (useWithFlag && !process.argv.includes(useWithFlag)) {
+                continue;
+            }
+
             // First try CLI flag, then fallback to env var
-            const raw = (flag && this.getFlagValue(flag)) || process.env[name];
+            const raw = (useFlagInstead && this.getFlagValue(useFlagInstead)) || process.env[name];
 
             if (raw === undefined || raw === "") {
                 if (defVal !== undefined) {
                     result[project][name] = defVal;
                 } else if (required) {
-                    const msg = `Missing required variable/flag: ${name}${flag ? ` (flag: ${flag})` : ""}`;
+                    const msg = `Missing required variable/flag: ${name}${useFlagInstead ? ` (flag: ${useFlagInstead})` : ""}`;
                     if (quitOnMissing !== false) throw new Error(msg);
                     else console.warn(msg);
                 }

tests/index.test.ts

@@ -13,7 +13,7 @@ describe("EnvManager", () => {
         const manager = new EnvManager()
             .add({
                 name: "DISCORD_TOKEN",
-                flag: "--discord-token",
+                useFlagInstead: "--discord-token",
                 type: String,
                 project: "discordBot",
                 required: true,
@@ -28,7 +28,7 @@ describe("EnvManager", () => {
         const manager = new EnvManager()
             .add({
                 name: "PORT",
-                flag: "--port",
+                useFlagInstead: "--port",
                 type: Number,
                 project: "apiServer",
                 default: 3000,
@@ -47,7 +47,7 @@ describe("EnvManager", () => {
         const manager = new EnvManager()
             .add({
                 name: "PORT",
-                flag: "--port",
+                useFlagInstead: "--port",
                 type: Number,
                 project: "apiServer",
                 required: false
@@ -58,6 +58,95 @@ describe("EnvManager", () => {
         expect(env.apiServer.PORT).toBe(8080);
     });
 
+    it("should load variable only when useWithFlag is present", () => {
+        process.env.POSTGRES_DEV_URL = "postgres://user:pass@localhost:5432/devdb";
+        process.argv.push("--dev");
+
+        const manager = new EnvManager().add({
+            name: "POSTGRES_DEV_URL",
+            type: String,
+            required: true,
+            useWithFlag: "--dev",
+        });
+
+        const env = manager.load();
+
+        expect(env.env.POSTGRES_DEV_URL).toBe("postgres://user:pass@localhost:5432/devdb");
+    });
+
+    it("should ignore variable when useWithFlag flag is not present", () => {
+        process.env.POSTGRES_DEV_URL = "postgres://user:pass@localhost:5432/devdb";
+
+        const manager = new EnvManager().add({
+            name: "POSTGRES_DEV_URL",
+            type: String,
+            required: true,
+            useWithFlag: "--dev",
+        });
+
+        const env = manager.load();
+
+        expect(env.env.POSTGRES_DEV_URL).toBeUndefined();
+    });
+
+    it("should not throw required error when useWithFlag is missing", () => {
+        const manager = new EnvManager().add({
+            name: "POSTGRES_DEV_URL",
+            required: true,
+            useWithFlag: "--dev",
+        });
+
+        expect(() => manager.load()).not.toThrow();
+    });
+
+    it("should throw when useWithFlag is present but variable is missing", () => {
+        process.argv.push("--dev");
+
+        const manager = new EnvManager().add({
+            name: "POSTGRES_DEV_URL",
+            required: true,
+            useWithFlag: "--dev",
+        });
+
+        expect(() => manager.load()).toThrow(
+            "Missing required variable/flag: POSTGRES_DEV_URL"
+        );
+    });
+
+    it("should only apply default when useWithFlag is present", () => {
+        const manager = new EnvManager().add({
+            name: "OPTIONAL_DEV_ONLY",
+            default: "dev-default",
+            useWithFlag: "--dev",
+            required: false,
+        });
+
+        // flag not present
+        let env = manager.load();
+        expect(env.env.OPTIONAL_DEV_ONLY).toBeUndefined();
+
+        // flag present
+        process.argv.push("--dev");
+        env = manager.load();
+        expect(env.env.OPTIONAL_DEV_ONLY).toBe("dev-default");
+    });
+
+    it("should combine useWithFlag and useFlagInstead correctly", () => {
+        process.argv.push("--dev", "--db-url", "postgres://flag");
+
+        const manager = new EnvManager().add({
+            name: "POSTGRES_DEV_URL",
+            useWithFlag: "--dev",
+            useFlagInstead: "--db-url",
+            type: String,
+            required: true,
+        });
+
+        const env = manager.load();
+
+        expect(env.env.POSTGRES_DEV_URL).toBe("postgres://flag");
+    });
+
     it("should throw for missing required variable", () => {
         const manager = new EnvManager()
             .add({