@futdevpro/fsm-dynamo 1.15.13 → 1.15.15

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

@@ -0,0 +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-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_AUTH_KEY', {
+ *     errorCode: 'FDP-ENV-MISSING-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/_models/interfaces/environment/global-settings.interface.ts

@@ -21,4 +21,27 @@ export interface DyFM_Global_Settings {
    * this setting will set which logs will be shown
    */
   log_settings: DyFM_GlobalLog_Settings;
+
+  /**
+   * FR-015 Phase 2 — isomorphic env-var overrides surface.
+   *
+   * On Node, `DyFM_requireEnv(name, ...)` reads `process.env[name]` directly.
+   * On browser there is no `process.env` at runtime, so consumers populate
+   * this map at app bootstrap from `environment.ts`:
+   *
+   * ```ts
+   * import { DyFM_global_settings } from '@futdevpro/fsm-dynamo';
+   * import { environment } from './environments/environment';
+   *
+   * DyFM_global_settings.envOverrides = {
+   *   FDP_AUTH_KEY: environment.authKey,
+   *   FDP_EXTRA_AUTH_STORAGE_KEY: environment.extraAuthStorageKey,
+   *   DyNM_STORAGE_ENCRYPTION_KEY: environment.storageEncryptionKey,
+   * };
+   * ```
+   *
+   * `DyFM_requireEnv` checks `process.env` first, then this map, then
+   * the caller's optional `fallback`, then throws a structured DyFM_Error.
+   */
+  envOverrides?: Record<string, string>;
 }

package/src/index.ts

@@ -11,10 +11,12 @@ export * from './_collections/constants/times.const';
 export * from './_collections/utils/array.util';
 export * from './_collections/utils/async.util';
 export * from './_collections/utils/data.util';
+export * from './_collections/utils/extract-error-message.util';
 export * from './_collections/utils/json-error-helper.util';
 export * from './_collections/utils/log.util';
 export * from './_collections/utils/round-list.util';
 export * from './_collections/utils/object.util';
+export * from './_collections/utils/require-env.util';
 export * from './_collections/utils/stack.util';
 export * from './_collections/utils/string.util';
 export * from './_collections/utils/string-case.util';

package/src/_collections/utils/math/box-bounds.util.spec.ts

@@ -1,124 +0,0 @@
-import { DyFM_Vector2 } from '../../../_models/interfaces/vector2.interface';
-import { DyFM_BoxBounds_Util } from './box-bounds.util';
-import { DyFM_Vector2_Util } from './vector2.util';
-
-xdescribe('| DyFM_BoxBounds', () => {
-  let boxBounds: DyFM_BoxBounds_Util;
-  const mockPosition = new DyFM_Vector2_Util({ x: 0, y: 0 });
-  const mockSize = new DyFM_Vector2_Util({ x: 10, y: 10 });
-
-  beforeEach(() => {
-    boxBounds = new DyFM_BoxBounds_Util(mockPosition, mockSize);
-  });
-
-  it('| should set position correctly ()', () => {
-    const newPosition = new DyFM_Vector2_Util({ x: 5, y: 5 });
-
-    boxBounds.pos = newPosition;
-    expect(boxBounds.pos).toEqual(newPosition);
-  });
-
-  it('| should get position correctly', () => {
-    const expectedPosition = new DyFM_Vector2_Util({ x: 5, y: 5 });
-
-    expect(boxBounds.pos).toEqual(expectedPosition);
-  });
-
-  it('| should set size correctly', () => {
-    const newSize = new DyFM_Vector2_Util({ x: 20, y: 20 });
-
-    boxBounds.size = newSize;
-    expect(boxBounds.size).toEqual(newSize);
-  });
-
-  it('| should get size correctly', () => {
-    const expectedSize = new DyFM_Vector2_Util({ x: 20, y: 20 });
-
-    expect(boxBounds.size).toEqual(expectedSize);
-  });
-
-  xit('| should calculate center correctly', () => {
-    const expectedCenter = new DyFM_Vector2_Util({ x: 10, y: 10 });
-    expect(boxBounds.center).toEqual(expectedCenter);
-  });
-
-  it('| should calculate center margin correctly', () => {
-    const expectedCenterMargin = new DyFM_Vector2_Util({ x: -5, y: -5 });
-    expect(boxBounds.centerMargin).toEqual(expectedCenterMargin);
-  });
-
-  it('| should return true for constructed method', () => {
-    expect(boxBounds.constructed()).toBe(true);
-  });
-
-  it('| should throw error when newValues has undefined position', () => {
-    expect(() => {
-      boxBounds.newValues(undefined as any, { x: 10, y: 10 });
-    }).toThrow(Error);
-  });
-
-  it('| should throw error when newValues has undefined size', () => {
-    expect(() => {
-      boxBounds.newValues({ x: 0, y: 0 }, undefined as any);
-    }).toThrow(Error);
-  });
-
-  it('| should clone and return a new instance', () => {
-    const clonedBoxBounds = boxBounds.clone();
-
-    expect(clonedBoxBounds).toBeInstanceOf(DyFM_BoxBounds_Util);
-    expect(clonedBoxBounds).toEqual(boxBounds);
-  });
-  
-
-  it('| should initialize with given position and size', () => {
-    expect(boxBounds.pos.x).toBe(mockPosition.x);
-    expect(boxBounds.pos.y).toBe(mockPosition.y);
-    expect(boxBounds.size.x).toBe(mockSize.x);
-    expect(boxBounds.size.y).toBe(mockSize.y);
-  });
-
-  it('| should calculate center correctly', () => {
-    const expectedCenter = DyFM_Vector2_Util.plus(mockPosition, DyFM_Vector2_Util.divide(mockSize, 2));
-    expect(boxBounds.center.x).toBe(expectedCenter.x);
-    expect(boxBounds.center.y).toBe(expectedCenter.y);
-  });
-
-  it('| should update position and size with newValues method', () => {
-    const newPosition: DyFM_Vector2 = { x: 50, y: 60 };
-    const newSize: DyFM_Vector2 = { x: 70, y: 80 };
-    boxBounds.newValues(newPosition, newSize);
-
-    expect(boxBounds.pos.x).toBe(newPosition.x);
-    expect(boxBounds.pos.y).toBe(newPosition.y);
-    expect(boxBounds.size.x).toBe(newSize.x);
-    expect(boxBounds.size.y).toBe(newSize.y);
-  });
-
-  it('| should throw error if newValues is called with undefined position', () => {
-    expect(() => boxBounds.newValues(undefined as any, mockSize)).toThrowError('new position is undefined!');
-  });
-
-  it('| should throw error if newValues is called with undefined size', () => {
-    expect(() => boxBounds.newValues(mockPosition, undefined as any)).toThrowError('new size is undefined!');
-  });
-
-  it('| should correctly determine if a position is within bounds', () => {
-    const insidePosition: DyFM_Vector2 = { x: 20, y: 30 };
-    const outsidePosition: DyFM_Vector2 = { x: 100, y: 100 };
-
-    expect(boxBounds.bounds(insidePosition)).toBeTrue();
-    expect(boxBounds.bounds(outsidePosition)).toBeFalse();
-  });
-
-  it('| should clone itself correctly', () => {
-    const clone = boxBounds.clone();
-    expect(clone.pos.x).toBe(boxBounds.pos.x);
-    expect(clone.pos.y).toBe(boxBounds.pos.y);
-    expect(clone.size.x).toBe(boxBounds.size.x);
-    expect(clone.size.y).toBe(boxBounds.size.y);
-    expect(clone).not.toBe(boxBounds);
-  });
-  
-
-});