@futdevpro/fsm-dynamo 1.20.8 → 1.20.10

package/src/_collections/utils/regex/password-regex.util.spec.ts

@@ -1,51 +0,0 @@
-
-import { DyFM_getPasswordErrors } from './password-regex.util';
-
-describe('| DyFM_getPasswordErrors', () => {
-
-  it('| should return an empty array for a valid password', () => {
-    const password = 'Valid1!';
-    const result = DyFM_getPasswordErrors(password);
-    expect(result).toEqual([]);
-  });
-
-  it('| should return an error for missing lowercase letter', () => {
-    const password = 'INVALID1!';
-    const result = DyFM_getPasswordErrors(password);
-    expect(result).toContain('Password must include at least one lowercase letter.');
-  });
-
-  it('| should return an error for missing uppercase letter', () => {
-    const password = 'invalid1!';
-    const result = DyFM_getPasswordErrors(password);
-    expect(result).toContain('Password must include at least one uppercase letter.');
-  });
-
-  it('| should return an error for missing digit', () => {
-    const password = 'Invalid!';
-    const result = DyFM_getPasswordErrors(password);
-    expect(result).toContain('Password must include at least one digit.');
-  });
-
-  it('| should return an error for missing special character', () => {
-    const password = 'Invalid1';
-    const result = DyFM_getPasswordErrors(password);
-    expect(result).toContain('Password must include at least one of the !@#$%^&* characters.');
-  });
-
-  it('| should return an error for password length less than 6', () => {
-    const password = 'Inv1!';
-    const result = DyFM_getPasswordErrors(password);
-    expect(result).toContain('Password must be at least 6 characters long.');
-  });
-
-  it('| should return multiple errors for a completely invalid password', () => {
-    const password = 'inv';
-    const result = DyFM_getPasswordErrors(password);
-    expect(result).toContain('Password must include at least one uppercase letter.');
-    expect(result).toContain('Password must include at least one digit.');
-    expect(result).toContain('Password must include at least one of the !@#$%^&* characters.');
-    expect(result).toContain('Password must be at least 6 characters long.');
-  });
-
-});

package/src/_collections/utils/regex/password-regex.util.ts

@@ -1,66 +0,0 @@
-
-export const DyFM_passwordRegex: RegExp = new RegExp(
-  '^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.*[!@#$%^&*]){6,}'
-);
-
-
-/* export const DyFM_ALLPasswordRegexUserMessages: string = 
-  'Password must include at least one lowercase letter. ' +
-  'Password must include at least one uppercase letter.' +
-  'Password must include at least one digit.' +
-  'Password must include at least one of the !@#$%^&* characters.' +
-  'Password must be at least 6 characters long.'; */
-
-/**
-  * returns an array of errors for a given password if it not match all the requirements
-  * 
-  * @example 
-  * ```ts
-  * const errors = DyFM_getPasswordErrors('Invalid1');
-  * console.log(errors); // ['Password must include at least one of the !@#$%^&* characters.']
-  * 
-  * const errors = DyFM_getPasswordErrors('ValidPassword1!');
-  * console.log(errors); // []
-  * ```
-  */
-export function DyFM_getPasswordErrors(password: string): string[] {
-  const errors: string[] = [];
-
-  DyFM_passwordErrorsOneByOne.forEach((error): void => {
-    if (!error.regex.test(password)) {
-      errors.push(error.message);
-    }
-  });
-
-  return errors;
-}
-
-const DyFM_passwordErrorsOneByOne = [
-  {
-    regex: new RegExp('^(?=.*[a-z])'),
-    code: 'pwErrorLowercase',
-    message: 'Password must include at least one lowercase letter.'
-  },
-  {
-    regex: new RegExp('^(?=.*[A-Z])'),
-    code: 'pwErrorUppercase',
-    message: 'Password must include at least one uppercase letter.'
-  },
-  {
-    regex: new RegExp('^(?=.*[0-9])'),
-    code: 'pwErrorDigit',
-    message: 'Password must include at least one digit.'
-  },
-  {
-    regex: new RegExp('^(?=.*[!@#$%^&*])'),
-    code: 'pwErrorSpecialChar',
-    message: 'Password must include at least one of the !@#$%^&* characters.'
-  },
-  {
-    regex: new RegExp('^(?=.{6,})'),
-    code: 'pwErrorLength',
-    message: 'Password must be at least 6 characters long.'
-  },
-];
-
-//'!@#$%^&*+-_<>?.,;:|~'

package/src/_collections/utils/regex/regex.util.spec.ts

@@ -1,42 +0,0 @@
-
-import { DyFM_emailRegex } from './regex.util';
-
-describe('| DyFM_emailRegex', () => {
-  it('| should match valid email addresses', () => {
-    const validEmails: string[] = [
-      'test@example.com',
-      'user.name+tag+sorting@example.com',
-      'user_name@example.co.uk',
-      'user-name@example.org',
-      'user123@example.museum',
-      'user@example.travel',
-      'user@example.mobi',
-      'user@example.info',
-      'user@example.jobs'
-    ];
-
-    validEmails.forEach(email => {
-      expect(DyFM_emailRegex.test(email)).toBeTrue();
-    });
-  });
-
-  xit('should not match invalid email addresses', () => {
-    const invalidEmails: string[] = [
-      'plainaddress',
-      '@missingusername.com',
-      'username@.com',
-      'username@com',
-      'username@.com.',
-      'username@-example.com',
-      'username@example..com',
-      'username@example.c',
-      'username@.example.com',
-      'username@.example.com.',
-      'username@.example..com'
-    ];
-
-    invalidEmails.forEach(email => {
-      expect(DyFM_emailRegex.test(email)).toBeFalse();
-    });
-  });
-});

package/src/_collections/utils/regex/regex.util.ts

@@ -1,6 +0,0 @@
-
-
-export const DyFM_emailRegex: RegExp = new RegExp(
-  '^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$'
-);
-

package/src/_collections/utils/regex/username-regex.util.spec.ts

@@ -1,61 +0,0 @@
-
-import { DyFM_usernameRegex } from './username-regex.util';
-
-describe('| DyFM_usernameRegex', () => {
-  it('| should match valid usernames', () => {
-    const validUsernames: string[] = [
-      'abcdef',
-      '123456',
-      'abc123',
-      'abc-123',
-      'abc_123',
-      'abc#123',
-      'abc$123',
-      'abc%123',
-      'abc&123',
-      'abc^123',
-      'abc|123',
-      'abc*123',
-      'abc-_$#%&^|*'
-    ];
-
-    validUsernames.forEach(username => {
-      expect(DyFM_usernameRegex.test(username)).toBeTrue();
-    });
-  });
-
-  it('| should not match invalid usernames', () => {
-    const invalidUsernames: string[] = [
-      'abc',          // less than 6 characters
-      'abc!',         // invalid special character
-      'abc@123',      // invalid special character
-      'abc 123',      // space is not allowed
-      'abc/123',      // invalid special character
-      'abc\\123',     // invalid special character
-      'abc+123',      // invalid special character
-      'abc=123',      // invalid special character
-      'abc,123',      // invalid special character
-      'abc.123',      // invalid special character
-      'abc:123',      // invalid special character
-      'abc;123',      // invalid special character
-      'abc<123',      // invalid special character
-      'abc>123',      // invalid special character
-      'abc?123',      // invalid special character
-      'abc@123',      // invalid special character
-      'abc[123',      // invalid special character
-      'abc]123',      // invalid special character
-      'abc{123',      // invalid special character
-      'abc}123',      // invalid special character
-      'abc(123',      // invalid special character
-      'abc)123',      // invalid special character
-      'abc~123',      // invalid special character
-      'abc`123',      // invalid special character
-      'abc"123',      // invalid special character
-      'abc\'123',     // invalid special character
-    ];
-
-    invalidUsernames.forEach(username => {
-      expect(DyFM_usernameRegex.test(username)).toBeFalse();
-    });
-  });
-});

package/src/_collections/utils/regex/username-regex.util.ts

@@ -1,35 +0,0 @@
-
-export const DyFM_usernameRegex: RegExp = new RegExp('^[a-zA-Z0-9-_#$%&^|*]{6,}$');
-
-
-/* export const FDP_usernameRegexUserMessage: string =
-  'Username must be at least 6 characters long and can only contain letters, ' +
-  'numbers, and the following special characters: -_#$%&^|*'; */
-
-/* export function getUsernameErrors(username: string): string[] {
-  const errors: string[] = [];
-
-  usernameErrorsOneByOne.forEach((error) => {
-    if (!error.regex.test(username)) {
-      errors.push(error.message);
-    }
-  });
-
-  return errors;
-} */
-
-const DyFM_usernameErrorsOneByOne = [
-  {
-    regex: new RegExp('^(?=.{6,})'),
-    code: 'usernameErrorLength',
-    /* message: 'Username must be at least 6 characters long.' */
-  },
-  {
-    regex: new RegExp('^(?=.*[a-zA-Z0-9-_#$%&^|*])'),
-    code: 'usernameErrorSpecialChar',
-    /* message: 
-      'Username can only contain letters, numbers, and the following special characters: -_#$%&^|*' */
-  },
-];
-
-

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

@@ -1,231 +0,0 @@
-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');
-    });
-  });
-});

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

@@ -1,138 +0,0 @@
-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,
-  });
-}