@futdevpro/fsm-dynamo 1.16.38 → 1.16.40

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

@@ -1,138 +1,138 @@
-import { DyFM_Error } from '../../_models/control-models/error.control-model';
-import { DyFM_global_settings } from '../constants/global-settings.const';
-
-
-/**
- * Options for `DyFM_requireEnv`. See the helper's JSDoc for usage.
- */
-export interface DyFM_RequireEnv_Options {
-  /**
-   * Stable error code emitted on the DyFM_Error when the env-var is missing
-   * and no fallback is configured. Convention: `<PACKAGE>-ENV-MISSING-<KEY>`,
-   * e.g. `DyNM-ENV-MISSING-STORAGE-KEY`, `FDP-ENV-MISSING-CORE-FE-AUTH-KEY`.
-   */
-  errorCode: string;
-
-  /**
-   * Short-code name of the package responsible for the env-var. Used as the
-   * DyFM_Error `___issuerService` for downstream filtering / dashboards.
-   */
-  issuerService: string;
-
-  /**
-   * Transition fallback. When set, returned if BOTH `process.env[name]` AND
-   * `DyFM_global_settings.envOverrides[name]` are missing.
-   *
-   * Use only during the additive phase of an env-var migration to keep the
-   * package backward-compatible while every deploy target rolls the new
-   * env-var out. Remove the `fallback` argument once the rollout is verified
-   * everywhere — then a missing env-var fail-fast crashes the consumer at
-   * first access with a structured DyFM_Error.
-   */
-  fallback?: string;
-
-  /**
-   * Admin-actionable user-facing message attached to the DyFM_Error. Defaults
-   * to a generic config-missing string referencing the env-var name.
-   */
-  userMessage?: string;
-}
-
-
-/**
- * FR-015 Phase 2 — isomorphic env-var requirement helper.
- *
- * Universal source of truth for "read this configuration key from an env-var
- * across Node and browser". Replaces per-package `requireEnv` helpers (the
- * Phase 1 local implementation in fdp-templates-nts is being refactored to
- * delegate here).
- *
- * Lookup order:
- *   1. `process.env[envVarName]` — Node-side (server const files at module load).
- *   2. `DyFM_global_settings.envOverrides[envVarName]` — browser-side, populated
- *      by the consumer at app bootstrap from its `environment.ts`. See
- *      DyFM_Global_Settings.envOverrides docs for the pattern.
- *   3. `options.fallback` if provided — used during migration's additive phase.
- *   4. throw a structured DyFM_Error with the full deploy-target checklist.
- *
- * The throw shape is rich on purpose (per the rich-error rule):
- *   - `___status` = 500 (configuration error)
- *   - `_errorCode` = caller-supplied stable code
- *   - `_message` = debug-level description with the env-var name + deploy-target
- *     checklist (host .env, docker-compose env-block, Overseer secrets-store,
- *     client environment.ts → bootstrap envOverrides)
- *   - `__userMessage` = admin-actionable message
- *   - `___issuerService` = caller-supplied package short-code
- *
- * @example Node server const file (module load):
- * ```ts
- * import { DyFM_requireEnv } from '@futdevpro/fsm-dynamo';
- *
- * export const FDP_keysEnv_settingsBase = {
- *   authKey: DyFM_requireEnv('FDP_CORE_FE_AUTH_KEY', {
- *     errorCode: 'FDP-ENV-MISSING-CORE-FE-AUTH-KEY',
- *     issuerService: 'fdp-templates',
- *     fallback: '<inherit literal>',   // remove for Wave 3
- *   }),
- * };
- * ```
- *
- * @example Browser-side lazy getter (deferred to first access, after consumer
- * bootstrap has populated DyFM_global_settings.envOverrides):
- * ```ts
- * let _cached: string | undefined;
- * function _resolveKey(): string {
- *   if (_cached !== undefined) return _cached;
- *   _cached = DyFM_requireEnv('DyNM_STORAGE_ENCRYPTION_KEY', { ... });
- *   return _cached;
- * }
- * export const DyNM_global_settings = {
- *   get storageEncryptionKey(): string { return _resolveKey(); },
- * };
- * ```
- */
-export function DyFM_requireEnv(
-  envVarName: string,
-  options: DyFM_RequireEnv_Options,
-): string {
-  // Node path: process.env at module-load time. Guarded for browser bundles
-  // where `process` may be undefined or shimmed without runtime values.
-  if (typeof process !== 'undefined' && process.env && process.env[envVarName]) {
-    return process.env[envVarName] as string;
-  }
-
-  // Browser path: consumer-populated envOverrides map. Populated at app
-  // bootstrap from environment.ts — see DyFM_Global_Settings.envOverrides.
-  const override: string | undefined =
-    DyFM_global_settings.envOverrides?.[envVarName];
-  if (override) {
-    return override;
-  }
-
-  // Transition fallback (Wave 1 of an FR-015-style migration).
-  if (options.fallback !== undefined) {
-    return options.fallback;
-  }
-
-  // Missing — fail fast with a rich, debug-friendly DyFM_Error.
-  throw new DyFM_Error({
-    status: 500,
-    errorCode: options.errorCode,
-    message:
-      `Environment variable '${envVarName}' is required but was not found. ` +
-      `Checked: process.env.${envVarName} (Node) and ` +
-      `DyFM_global_settings.envOverrides['${envVarName}'] (browser). ` +
-      `Both unset, and no transition fallback configured. ` +
-      `Set '${envVarName}' on every deploy target before deploying this ` +
-      `package version: (1) host .env on every host running a backend, ` +
-      `(2) docker-compose env-block on every consumer service, ` +
-      `(3) Overseer secrets-store entry for CI builds, ` +
-      `(4) client environment.ts plus app-bootstrap copy into ` +
-      `DyFM_global_settings.envOverrides for any browser consumer.`,
-    userMessage:
-      options.userMessage
-      ?? `Configuration error — environment variable '${envVarName}' is missing. `
-         + `Contact the responsible operator to set it on this deploy target.`,
-    issuerService: options.issuerService,
-  });
-}
+import { DyFM_Error } from '../../_models/control-models/error.control-model';
+import { DyFM_global_settings } from '../constants/global-settings.const';
+
+
+/**
+ * Options for `DyFM_requireEnv`. See the helper's JSDoc for usage.
+ */
+export interface DyFM_RequireEnv_Options {
+  /**
+   * Stable error code emitted on the DyFM_Error when the env-var is missing
+   * and no fallback is configured. Convention: `<PACKAGE>-ENV-MISSING-<KEY>`,
+   * e.g. `DyNM-ENV-MISSING-STORAGE-KEY`, `FDP-ENV-MISSING-CORE-FE-AUTH-KEY`.
+   */
+  errorCode: string;
+
+  /**
+   * Short-code name of the package responsible for the env-var. Used as the
+   * DyFM_Error `___issuerService` for downstream filtering / dashboards.
+   */
+  issuerService: string;
+
+  /**
+   * Transition fallback. When set, returned if BOTH `process.env[name]` AND
+   * `DyFM_global_settings.envOverrides[name]` are missing.
+   *
+   * Use only during the additive phase of an env-var migration to keep the
+   * package backward-compatible while every deploy target rolls the new
+   * env-var out. Remove the `fallback` argument once the rollout is verified
+   * everywhere — then a missing env-var fail-fast crashes the consumer at
+   * first access with a structured DyFM_Error.
+   */
+  fallback?: string;
+
+  /**
+   * Admin-actionable user-facing message attached to the DyFM_Error. Defaults
+   * to a generic config-missing string referencing the env-var name.
+   */
+  userMessage?: string;
+}
+
+
+/**
+ * FR-015 Phase 2 — isomorphic env-var requirement helper.
+ *
+ * Universal source of truth for "read this configuration key from an env-var
+ * across Node and browser". Replaces per-package `requireEnv` helpers (the
+ * Phase 1 local implementation in fdp-templates-nts is being refactored to
+ * delegate here).
+ *
+ * Lookup order:
+ *   1. `process.env[envVarName]` — Node-side (server const files at module load).
+ *   2. `DyFM_global_settings.envOverrides[envVarName]` — browser-side, populated
+ *      by the consumer at app bootstrap from its `environment.ts`. See
+ *      DyFM_Global_Settings.envOverrides docs for the pattern.
+ *   3. `options.fallback` if provided — used during migration's additive phase.
+ *   4. throw a structured DyFM_Error with the full deploy-target checklist.
+ *
+ * The throw shape is rich on purpose (per the rich-error rule):
+ *   - `___status` = 500 (configuration error)
+ *   - `_errorCode` = caller-supplied stable code
+ *   - `_message` = debug-level description with the env-var name + deploy-target
+ *     checklist (host .env, docker-compose env-block, Overseer secrets-store,
+ *     client environment.ts → bootstrap envOverrides)
+ *   - `__userMessage` = admin-actionable message
+ *   - `___issuerService` = caller-supplied package short-code
+ *
+ * @example Node server const file (module load):
+ * ```ts
+ * import { DyFM_requireEnv } from '@futdevpro/fsm-dynamo';
+ *
+ * export const FDP_keysEnv_settingsBase = {
+ *   authKey: DyFM_requireEnv('FDP_CORE_FE_AUTH_KEY', {
+ *     errorCode: 'FDP-ENV-MISSING-CORE-FE-AUTH-KEY',
+ *     issuerService: 'fdp-templates',
+ *     fallback: '<inherit literal>',   // remove for Wave 3
+ *   }),
+ * };
+ * ```
+ *
+ * @example Browser-side lazy getter (deferred to first access, after consumer
+ * bootstrap has populated DyFM_global_settings.envOverrides):
+ * ```ts
+ * let _cached: string | undefined;
+ * function _resolveKey(): string {
+ *   if (_cached !== undefined) return _cached;
+ *   _cached = DyFM_requireEnv('DyNM_STORAGE_ENCRYPTION_KEY', { ... });
+ *   return _cached;
+ * }
+ * export const DyNM_global_settings = {
+ *   get storageEncryptionKey(): string { return _resolveKey(); },
+ * };
+ * ```
+ */
+export function DyFM_requireEnv(
+  envVarName: string,
+  options: DyFM_RequireEnv_Options,
+): string {
+  // Node path: process.env at module-load time. Guarded for browser bundles
+  // where `process` may be undefined or shimmed without runtime values.
+  if (typeof process !== 'undefined' && process.env && process.env[envVarName]) {
+    return process.env[envVarName] as string;
+  }
+
+  // Browser path: consumer-populated envOverrides map. Populated at app
+  // bootstrap from environment.ts — see DyFM_Global_Settings.envOverrides.
+  const override: string | undefined =
+    DyFM_global_settings.envOverrides?.[envVarName];
+  if (override) {
+    return override;
+  }
+
+  // Transition fallback (Wave 1 of an FR-015-style migration).
+  if (options.fallback !== undefined) {
+    return options.fallback;
+  }
+
+  // Missing — fail fast with a rich, debug-friendly DyFM_Error.
+  throw new DyFM_Error({
+    status: 500,
+    errorCode: options.errorCode,
+    message:
+      `Environment variable '${envVarName}' is required but was not found. ` +
+      `Checked: process.env.${envVarName} (Node) and ` +
+      `DyFM_global_settings.envOverrides['${envVarName}'] (browser). ` +
+      `Both unset, and no transition fallback configured. ` +
+      `Set '${envVarName}' on every deploy target before deploying this ` +
+      `package version: (1) host .env on every host running a backend, ` +
+      `(2) docker-compose env-block on every consumer service, ` +
+      `(3) Overseer secrets-store entry for CI builds, ` +
+      `(4) client environment.ts plus app-bootstrap copy into ` +
+      `DyFM_global_settings.envOverrides for any browser consumer.`,
+    userMessage:
+      options.userMessage
+      ?? `Configuration error — environment variable '${envVarName}' is missing. `
+         + `Contact the responsible operator to set it on this deploy target.`,
+    issuerService: options.issuerService,
+  });
+}

package/src/_collections/utils/round-list.util.spec.ts

@@ -1,79 +1,79 @@
-
-import { DyFM_RoundList } from './round-list.util';
-
-describe('| DyFM_RoundList', () => {
-
-  describe('| getOutboundedIndex', () => {
-    it('| should throw an error if listLength is 0', () => {
-      expect(() => DyFM_RoundList.getOutboundedIndex(0, 5)).toThrowError('roundListPlusIndex failed. list is empty!');
-    });
-
-    it('| should return correct index for positive outboundIndex within bounds', () => {
-      expect(DyFM_RoundList.getOutboundedIndex(5, 3)).toBe(3);
-    });
-
-    it('| should return correct index for positive outboundIndex out of bounds', () => {
-      expect(DyFM_RoundList.getOutboundedIndex(5, 7)).toBe(2);
-    });
-
-    it('| should return correct index for negative outboundIndex', () => {
-      expect(DyFM_RoundList.getOutboundedIndex(5, -2)).toBe(3);
-    });
-  });
-
-  describe('| getIndexOpposite', () => {
-    it('| should return the opposite index in a circular manner', () => {
-      expect(DyFM_RoundList.getIndexOpposite(8, 7)).toBe(3);
-    });
-
-    it('| should handle even length arrays correctly', () => {
-      expect(DyFM_RoundList.getIndexOpposite(4, 1)).toBe(3);
-    });
-
-    it('| should handle odd length arrays correctly', () => {
-      expect(DyFM_RoundList.getIndexOpposite(5, 2)).toBe(0);
-    });
-  });
-
-  describe('| getListIndex', () => {
-    it('| should return the correct element for a given outboundIndex', () => {
-      const list = ['a', 'b', 'c', 'd'];
-      expect(DyFM_RoundList.getListIndex(list, 5)).toBe('b');
-    });
-
-    it('| should handle negative outboundIndex', () => {
-      const list = ['a', 'b', 'c', 'd'];
-      expect(DyFM_RoundList.getListIndex(list, -1)).toBe('d');
-    });
-  });
-
-  describe('| getListOpposite', () => {
-    it('| should return the opposite element in a circular manner', () => {
-      const list = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'];
-      expect(DyFM_RoundList.getListOpposite(list, 'h')).toBe('d');
-    });
-
-    it('| should handle even length lists correctly', () => {
-      const list = ['a', 'b', 'c', 'd'];
-      expect(DyFM_RoundList.getListOpposite(list, 'b')).toBe('d');
-    });
-
-    it('| should handle odd length lists correctly', () => {
-      const list = ['a', 'b', 'c', 'd', 'e'];
-      expect(DyFM_RoundList.getListOpposite(list, 'c')).toBe('a');
-    });
-  });
-
-  describe('| getLast', () => {
-    it('| should return the last element of the list', () => {
-      const list = ['a', 'b', 'c'];
-      expect(DyFM_RoundList.getLast(list)).toBe('c');
-    });
-
-    it('| should return null for an empty list', () => {
-      const list: string[] = [];
-      expect(DyFM_RoundList.getLast(list)).toBeNull();
-    });
-  });
-
-});
+
+import { DyFM_RoundList } from './round-list.util';
+
+describe('| DyFM_RoundList', () => {
+
+  describe('| getOutboundedIndex', () => {
+    it('| should throw an error if listLength is 0', () => {
+      expect(() => DyFM_RoundList.getOutboundedIndex(0, 5)).toThrowError('roundListPlusIndex failed. list is empty!');
+    });
+
+    it('| should return correct index for positive outboundIndex within bounds', () => {
+      expect(DyFM_RoundList.getOutboundedIndex(5, 3)).toBe(3);
+    });
+
+    it('| should return correct index for positive outboundIndex out of bounds', () => {
+      expect(DyFM_RoundList.getOutboundedIndex(5, 7)).toBe(2);
+    });
+
+    it('| should return correct index for negative outboundIndex', () => {
+      expect(DyFM_RoundList.getOutboundedIndex(5, -2)).toBe(3);
+    });
+  });
+
+  describe('| getIndexOpposite', () => {
+    it('| should return the opposite index in a circular manner', () => {
+      expect(DyFM_RoundList.getIndexOpposite(8, 7)).toBe(3);
+    });
+
+    it('| should handle even length arrays correctly', () => {
+      expect(DyFM_RoundList.getIndexOpposite(4, 1)).toBe(3);
+    });
+
+    it('| should handle odd length arrays correctly', () => {
+      expect(DyFM_RoundList.getIndexOpposite(5, 2)).toBe(0);
+    });
+  });
+
+  describe('| getListIndex', () => {
+    it('| should return the correct element for a given outboundIndex', () => {
+      const list = ['a', 'b', 'c', 'd'];
+      expect(DyFM_RoundList.getListIndex(list, 5)).toBe('b');
+    });
+
+    it('| should handle negative outboundIndex', () => {
+      const list = ['a', 'b', 'c', 'd'];
+      expect(DyFM_RoundList.getListIndex(list, -1)).toBe('d');
+    });
+  });
+
+  describe('| getListOpposite', () => {
+    it('| should return the opposite element in a circular manner', () => {
+      const list = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'];
+      expect(DyFM_RoundList.getListOpposite(list, 'h')).toBe('d');
+    });
+
+    it('| should handle even length lists correctly', () => {
+      const list = ['a', 'b', 'c', 'd'];
+      expect(DyFM_RoundList.getListOpposite(list, 'b')).toBe('d');
+    });
+
+    it('| should handle odd length lists correctly', () => {
+      const list = ['a', 'b', 'c', 'd', 'e'];
+      expect(DyFM_RoundList.getListOpposite(list, 'c')).toBe('a');
+    });
+  });
+
+  describe('| getLast', () => {
+    it('| should return the last element of the list', () => {
+      const list = ['a', 'b', 'c'];
+      expect(DyFM_RoundList.getLast(list)).toBe('c');
+    });
+
+    it('| should return null for an empty list', () => {
+      const list: string[] = [];
+      expect(DyFM_RoundList.getLast(list)).toBeNull();
+    });
+  });
+
+});