@futdevpro/fsm-dynamo 1.16.38 → 1.16.40

package/src/_collections/utils/require-env.util.spec.ts

@@ -1,231 +1,231 @@
-import { DyFM_global_settings } from '../constants/global-settings.const';
-import { DyFM_Error } from '../../_models/control-models/error.control-model';
-import { DyFM_requireEnv } from './require-env.util';
-
-
-/**
- * FR-015 Phase 2 Wave 0 — DyFM_requireEnv specs.
- *
- * Coverage:
- *   - Node path: returns process.env value when set
- *   - Browser path: returns DyFM_global_settings.envOverrides value when
- *     process.env is unset
- *   - Fallback path: returns options.fallback when both above unset
- *   - Throw path: structured DyFM_Error when nothing resolves and no
- *     fallback. Verifies errorCode, message contains the env-var name +
- *     deploy-target checklist, userMessage is admin-actionable,
- *     issuerService matches.
- *   - Override priority: process.env wins over envOverrides; envOverrides
- *     wins over fallback.
- */
-
-
-/**
- * Cleans the test fixture between specs so leak-state from one test doesn't
- * pollute another. We touch the live `DyFM_global_settings.envOverrides`
- * because the spec exercises the same surface the production code reads.
- */
-function clearOverrides(): void {
-  DyFM_global_settings.envOverrides = undefined;
-}
-
-
-describe('| DyFM_requireEnv', (): void => {
-
-  afterEach((): void => {
-    clearOverrides();
-    delete process.env['DyFM_TEST_REQUIRE_ENV_KEY'];
-    delete process.env['DyFM_TEST_REQUIRE_ENV_OTHER'];
-  });
-
-
-  describe('| Node path (process.env)', (): void => {
-    it('| returns process.env value when set', (): void => {
-      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = 'node-value';
-      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-        errorCode: 'TEST-001',
-        issuerService: 'spec',
-      });
-      expect(value).toBe('node-value');
-    });
-
-    it('| empty-string process.env value is treated as unset', (): void => {
-      // Truthy guard — empty string means "not configured".
-      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = '';
-      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'browser-value' };
-      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-        errorCode: 'TEST-002',
-        issuerService: 'spec',
-      });
-      expect(value).toBe('browser-value');
-    });
-  });
-
-
-  describe('| browser path (envOverrides)', (): void => {
-    it('| returns envOverrides value when process.env unset', (): void => {
-      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'browser-value' };
-      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-        errorCode: 'TEST-003',
-        issuerService: 'spec',
-      });
-      expect(value).toBe('browser-value');
-    });
-
-    it('| handles other entries in the same map without interference', (): void => {
-      DyFM_global_settings.envOverrides = {
-        'DyFM_TEST_REQUIRE_ENV_KEY':   'value-a',
-        'DyFM_TEST_REQUIRE_ENV_OTHER': 'value-b',
-      };
-      expect(DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', { errorCode: 'X', issuerService: 's' }))
-        .toBe('value-a');
-      expect(DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_OTHER', { errorCode: 'X', issuerService: 's' }))
-        .toBe('value-b');
-    });
-  });
-
-
-  describe('| fallback path', (): void => {
-    it('| returns fallback when neither process.env nor envOverrides resolves', (): void => {
-      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-        errorCode: 'TEST-004',
-        issuerService: 'spec',
-        fallback: 'fallback-value',
-      });
-      expect(value).toBe('fallback-value');
-    });
-
-    it('| empty-string fallback is honored (explicit empty intent)', (): void => {
-      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-        errorCode: 'TEST-005',
-        issuerService: 'spec',
-        fallback: '',
-      });
-      expect(value).toBe('');
-    });
-  });
-
-
-  describe('| throw path — rich DyFM_Error', (): void => {
-    it('| throws DyFM_Error when nothing resolves and no fallback', (): void => {
-      let caught: unknown = null;
-      try {
-        DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-          errorCode: 'TEST-MISSING-001',
-          issuerService: 'dynamo-fsm-spec',
-        });
-      } catch (error: unknown) {
-        caught = error;
-      }
-      expect(caught).toBeInstanceOf(DyFM_Error);
-    });
-
-    it('| error has the caller-supplied errorCode', (): void => {
-      try {
-        DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-          errorCode: 'CUSTOM-CODE-XYZ',
-          issuerService: 's',
-        });
-        fail('should have thrown');
-      } catch (error: unknown) {
-        const err: DyFM_Error = error as DyFM_Error;
-        expect(err._errorCode).toBe('CUSTOM-CODE-XYZ');
-        // Also present in the aggregated _errorCodes list.
-        expect(err._errorCodes).toContain('CUSTOM-CODE-XYZ');
-      }
-    });
-
-    it('| error has status 500 (config error)', (): void => {
-      try {
-        DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-          errorCode: 'C', issuerService: 's',
-        });
-        fail('should have thrown');
-      } catch (error: unknown) {
-        const err: DyFM_Error = error as DyFM_Error;
-        expect(err.___status).toBe(500);
-      }
-    });
-
-    it('| error message names the env-var + lists deploy targets', (): void => {
-      try {
-        DyFM_requireEnv('SOME_SPECIFIC_VAR_NAME', {
-          errorCode: 'C', issuerService: 's',
-        });
-        fail('should have thrown');
-      } catch (error: unknown) {
-        const err: DyFM_Error = error as DyFM_Error;
-        const msg: string = err._message || '';
-        // Names the specific var
-        expect(msg).toContain('SOME_SPECIFIC_VAR_NAME');
-        // Lists each deploy target so an operator knows where to look
-        expect(msg).toContain('host .env');
-        expect(msg).toContain('docker-compose');
-        expect(msg).toContain('Overseer');
-        expect(msg).toContain('environment.ts');
-      }
-    });
-
-    it('| error has admin-actionable userMessage (custom or default)', (): void => {
-      // Default userMessage
-      try {
-        DyFM_requireEnv('DEFAULT_MSG_VAR', { errorCode: 'C', issuerService: 's' });
-        fail('should have thrown');
-      } catch (error: unknown) {
-        const err: DyFM_Error = error as DyFM_Error;
-        expect(err.__userMessage).toContain('DEFAULT_MSG_VAR');
-        expect(err.__userMessage).toContain('operator');
-      }
-      // Custom userMessage
-      try {
-        DyFM_requireEnv('CUSTOM_MSG_VAR', {
-          errorCode: 'C',
-          issuerService: 's',
-          userMessage: 'My custom admin instruction',
-        });
-        fail('should have thrown');
-      } catch (error: unknown) {
-        const err: DyFM_Error = error as DyFM_Error;
-        expect(err.__userMessage).toBe('My custom admin instruction');
-      }
-    });
-
-    it('| error has issuerService set', (): void => {
-      try {
-        DyFM_requireEnv('V', { errorCode: 'C', issuerService: 'my-package' });
-        fail('should have thrown');
-      } catch (error: unknown) {
-        const err: DyFM_Error = error as DyFM_Error;
-        expect(err.___issuerService).toBe('my-package');
-      }
-    });
-  });
-
-
-  describe('| lookup priority', (): void => {
-    it('| process.env wins over envOverrides', (): void => {
-      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = 'from-process';
-      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'from-overrides' };
-      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-        errorCode: 'C', issuerService: 's',
-      });
-      expect(value).toBe('from-process');
-    });
-
-    it('| envOverrides wins over fallback', (): void => {
-      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'from-overrides' };
-      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-        errorCode: 'C', issuerService: 's', fallback: 'from-fallback',
-      });
-      expect(value).toBe('from-overrides');
-    });
-
-    it('| process.env wins over fallback', (): void => {
-      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = 'from-process';
-      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
-        errorCode: 'C', issuerService: 's', fallback: 'from-fallback',
-      });
-      expect(value).toBe('from-process');
-    });
-  });
-});
+import { DyFM_global_settings } from '../constants/global-settings.const';
+import { DyFM_Error } from '../../_models/control-models/error.control-model';
+import { DyFM_requireEnv } from './require-env.util';
+
+
+/**
+ * FR-015 Phase 2 Wave 0 — DyFM_requireEnv specs.
+ *
+ * Coverage:
+ *   - Node path: returns process.env value when set
+ *   - Browser path: returns DyFM_global_settings.envOverrides value when
+ *     process.env is unset
+ *   - Fallback path: returns options.fallback when both above unset
+ *   - Throw path: structured DyFM_Error when nothing resolves and no
+ *     fallback. Verifies errorCode, message contains the env-var name +
+ *     deploy-target checklist, userMessage is admin-actionable,
+ *     issuerService matches.
+ *   - Override priority: process.env wins over envOverrides; envOverrides
+ *     wins over fallback.
+ */
+
+
+/**
+ * Cleans the test fixture between specs so leak-state from one test doesn't
+ * pollute another. We touch the live `DyFM_global_settings.envOverrides`
+ * because the spec exercises the same surface the production code reads.
+ */
+function clearOverrides(): void {
+  DyFM_global_settings.envOverrides = undefined;
+}
+
+
+describe('| DyFM_requireEnv', (): void => {
+
+  afterEach((): void => {
+    clearOverrides();
+    delete process.env['DyFM_TEST_REQUIRE_ENV_KEY'];
+    delete process.env['DyFM_TEST_REQUIRE_ENV_OTHER'];
+  });
+
+
+  describe('| Node path (process.env)', (): void => {
+    it('| returns process.env value when set', (): void => {
+      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = 'node-value';
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'TEST-001',
+        issuerService: 'spec',
+      });
+      expect(value).toBe('node-value');
+    });
+
+    it('| empty-string process.env value is treated as unset', (): void => {
+      // Truthy guard — empty string means "not configured".
+      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = '';
+      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'browser-value' };
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'TEST-002',
+        issuerService: 'spec',
+      });
+      expect(value).toBe('browser-value');
+    });
+  });
+
+
+  describe('| browser path (envOverrides)', (): void => {
+    it('| returns envOverrides value when process.env unset', (): void => {
+      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'browser-value' };
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'TEST-003',
+        issuerService: 'spec',
+      });
+      expect(value).toBe('browser-value');
+    });
+
+    it('| handles other entries in the same map without interference', (): void => {
+      DyFM_global_settings.envOverrides = {
+        'DyFM_TEST_REQUIRE_ENV_KEY':   'value-a',
+        'DyFM_TEST_REQUIRE_ENV_OTHER': 'value-b',
+      };
+      expect(DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', { errorCode: 'X', issuerService: 's' }))
+        .toBe('value-a');
+      expect(DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_OTHER', { errorCode: 'X', issuerService: 's' }))
+        .toBe('value-b');
+    });
+  });
+
+
+  describe('| fallback path', (): void => {
+    it('| returns fallback when neither process.env nor envOverrides resolves', (): void => {
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'TEST-004',
+        issuerService: 'spec',
+        fallback: 'fallback-value',
+      });
+      expect(value).toBe('fallback-value');
+    });
+
+    it('| empty-string fallback is honored (explicit empty intent)', (): void => {
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'TEST-005',
+        issuerService: 'spec',
+        fallback: '',
+      });
+      expect(value).toBe('');
+    });
+  });
+
+
+  describe('| throw path — rich DyFM_Error', (): void => {
+    it('| throws DyFM_Error when nothing resolves and no fallback', (): void => {
+      let caught: unknown = null;
+      try {
+        DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+          errorCode: 'TEST-MISSING-001',
+          issuerService: 'dynamo-fsm-spec',
+        });
+      } catch (error: unknown) {
+        caught = error;
+      }
+      expect(caught).toBeInstanceOf(DyFM_Error);
+    });
+
+    it('| error has the caller-supplied errorCode', (): void => {
+      try {
+        DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+          errorCode: 'CUSTOM-CODE-XYZ',
+          issuerService: 's',
+        });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        expect(err._errorCode).toBe('CUSTOM-CODE-XYZ');
+        // Also present in the aggregated _errorCodes list.
+        expect(err._errorCodes).toContain('CUSTOM-CODE-XYZ');
+      }
+    });
+
+    it('| error has status 500 (config error)', (): void => {
+      try {
+        DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+          errorCode: 'C', issuerService: 's',
+        });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        expect(err.___status).toBe(500);
+      }
+    });
+
+    it('| error message names the env-var + lists deploy targets', (): void => {
+      try {
+        DyFM_requireEnv('SOME_SPECIFIC_VAR_NAME', {
+          errorCode: 'C', issuerService: 's',
+        });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        const msg: string = err._message || '';
+        // Names the specific var
+        expect(msg).toContain('SOME_SPECIFIC_VAR_NAME');
+        // Lists each deploy target so an operator knows where to look
+        expect(msg).toContain('host .env');
+        expect(msg).toContain('docker-compose');
+        expect(msg).toContain('Overseer');
+        expect(msg).toContain('environment.ts');
+      }
+    });
+
+    it('| error has admin-actionable userMessage (custom or default)', (): void => {
+      // Default userMessage
+      try {
+        DyFM_requireEnv('DEFAULT_MSG_VAR', { errorCode: 'C', issuerService: 's' });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        expect(err.__userMessage).toContain('DEFAULT_MSG_VAR');
+        expect(err.__userMessage).toContain('operator');
+      }
+      // Custom userMessage
+      try {
+        DyFM_requireEnv('CUSTOM_MSG_VAR', {
+          errorCode: 'C',
+          issuerService: 's',
+          userMessage: 'My custom admin instruction',
+        });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        expect(err.__userMessage).toBe('My custom admin instruction');
+      }
+    });
+
+    it('| error has issuerService set', (): void => {
+      try {
+        DyFM_requireEnv('V', { errorCode: 'C', issuerService: 'my-package' });
+        fail('should have thrown');
+      } catch (error: unknown) {
+        const err: DyFM_Error = error as DyFM_Error;
+        expect(err.___issuerService).toBe('my-package');
+      }
+    });
+  });
+
+
+  describe('| lookup priority', (): void => {
+    it('| process.env wins over envOverrides', (): void => {
+      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = 'from-process';
+      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'from-overrides' };
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'C', issuerService: 's',
+      });
+      expect(value).toBe('from-process');
+    });
+
+    it('| envOverrides wins over fallback', (): void => {
+      DyFM_global_settings.envOverrides = { 'DyFM_TEST_REQUIRE_ENV_KEY': 'from-overrides' };
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'C', issuerService: 's', fallback: 'from-fallback',
+      });
+      expect(value).toBe('from-overrides');
+    });
+
+    it('| process.env wins over fallback', (): void => {
+      process.env['DyFM_TEST_REQUIRE_ENV_KEY'] = 'from-process';
+      const value: string = DyFM_requireEnv('DyFM_TEST_REQUIRE_ENV_KEY', {
+        errorCode: 'C', issuerService: 's', fallback: 'from-fallback',
+      });
+      expect(value).toBe('from-process');
+    });
+  });
+});