@futdevpro/fsm-dynamo 1.12.10 → 1.12.11

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

@@ -1,5 +1,7 @@
 import { Observable } from 'rxjs';
-
+import { second, hour, minute, week, day } from '../constants/times.const';
+import { DyFM_Time } from './time.util';
+import { DyFM_Log } from './log.util';
 
 
 export class DyFM_Async {
@@ -9,11 +11,11 @@ export class DyFM_Async {
    * @param ms 
    * @returns 
    */
-  static delay(ms: number): Promise<void> {
+  static wait(ms: number): Promise<void> {
     return new Promise((resolve): any => setTimeout(resolve, ms));
   }
-  static readonly sleep: typeof this.delay = this.delay;
-  static readonly wait: typeof this.delay = this.delay;
+  static readonly sleep: typeof this.wait = this.wait;
+  static readonly delay: typeof this.wait = this.wait;
 
   /** 
    * WARNING: This function is recommended to use ONLY for limited instances,
@@ -94,4 +96,63 @@ export class DyFM_Async {
       );
     });
   }
+
+  static async waitWithCountdownLogging(
+    totalWaitTimeMs: number,
+    context: string = 'Countdown'
+  ): Promise<void> {
+    const startTime = Date.now();
+    const endTime = startTime + totalWaitTimeMs;
+    
+    // Define logging intervals based on total duration
+    const getLogInterval = (totalMs: number): number => {
+      const totalSeconds = totalMs / second;
+      const totalMinutes = totalSeconds / 60;
+      const totalHours = totalMinutes / 60;
+      const totalDays = totalHours / 24;
+      const totalWeeks = totalDays / 7;
+      
+      if (totalWeeks >= 4) return week; // Every week
+      if (totalDays >= 7) return day; // Every day
+      if (totalDays >= 3) return 12 * hour; // Every 12 hours
+      if (totalDays >= 1) return 6 * hour; // Every 6 hours
+      if (totalHours >= 12) return 3 * hour; // Every 3 hours
+      if (totalHours >= 6) return hour; // Every hour
+      if (totalHours >= 3) return 30 * minute; // Every 30 minutes
+      if (totalHours >= 1) return 10 * minute; // Every 10 minutes
+      if (totalMinutes >= 30) return 5 * minute; // Every 5 minutes
+      if (totalMinutes >= 10) return minute; // Every minute
+      if (totalMinutes >= 5) return 30 * second; // Every 30 seconds
+      if (totalMinutes >= 1) return 10 * second; // Every 10 seconds
+      if (totalSeconds >= 30) return 5 * second; // Every 5 seconds
+      return second; // Every second
+    };
+    
+    const logInterval = getLogInterval(totalWaitTimeMs);
+    let lastLogTime = startTime;
+    
+    // Format remaining time for display using DyFM_Time utility
+    const formatRemainingTime = (remainingMs: number): string => DyFM_Time.getTimeInShortestString(remainingMs) as string;
+    
+    // Log initial countdown start
+    DyFM_Log.info(`⏳ ${context} started - Total duration: ${formatRemainingTime(totalWaitTimeMs)}`);
+    
+    while (Date.now() < endTime) {
+      const now = Date.now();
+      const remainingMs = endTime - now;
+      
+      // Check if it's time to log
+      if (now - lastLogTime >= logInterval) {
+        const remainingTime = formatRemainingTime(remainingMs);
+        DyFM_Log.info(`⏳ ${context} - ${remainingTime} remaining`);
+        lastLogTime = now;
+      }
+      
+      // Wait for a short interval before checking again
+      await DyFM_Async.wait(Math.min(DyFM_Time.second, remainingMs));
+    }
+    
+    // Log completion
+    DyFM_Log.success(`✅ ${context} completed`);
+  }
 }

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

@@ -258,19 +258,19 @@ export class DyFM_Time {
     } else if (duration < second) {
       return `${duration}ms`;
     } else if (duration < minute) {
-      return `${DyFM_Math.round(duration / second)}s ${duration % second}ms`;
+      return `${DyFM_Math.round(duration / second, 0)}s ${duration % second}ms`;
     } else if (duration < hour) {
-      return `${DyFM_Math.round(duration / minute)}m ${DyFM_Math.round(duration % minute)}s`;
+      return `${DyFM_Math.round(duration / minute, 0)}m ${DyFM_Math.round(duration % minute)}s`;
     } else if (duration < day) {
-      return `${DyFM_Math.round(duration / hour)}h ${DyFM_Math.round(duration % hour)}m`;
+      return `${DyFM_Math.round(duration / hour, 0)}h ${DyFM_Math.round(duration % hour)}m`;
     } else if (duration < week) {
-      return `${DyFM_Math.round(duration / day)}d ${DyFM_Math.round(duration % day)}h`;
+      return `${DyFM_Math.round(duration / day, 0)}d ${DyFM_Math.round(duration % day)}h`;
     } else if (duration < month) {
-      return `${DyFM_Math.round(duration / week)}w ${DyFM_Math.round(duration % week)}d`;
+      return `${DyFM_Math.round(duration / week, 0)}w ${DyFM_Math.round(duration % week)}d`;
     } else if (duration < year) {
-      return `${DyFM_Math.round(duration / month)}m ${DyFM_Math.round(duration % month)}w`;
+      return `${DyFM_Math.round(duration / month, 0)}m ${DyFM_Math.round(duration % month)}w`;
     } else {
-      return `${DyFM_Math.round(duration / year)}y ${DyFM_Math.round(duration % year)}m`;
+      return `${DyFM_Math.round(duration / year, 0)}y ${DyFM_Math.round(duration % year)}m`;
     }
   }
 

package/src/_models/interfaces/search-query.interface.ts

@@ -5,8 +5,19 @@ import { DyFM_DBĐSort } from '../types/db-đsort.type';
 
 export interface DyFM_SearchQuery<T> {
   filterBy?: DyFM_DBĐFilter<T>; //DyFM_DBFilterSimple<T>; //DyFM_DBFilter<T>;
+  /**
+   * The sort order to load.
+   * The last sort will apply last, so it will be the strongest sort.
+   */
   sortBy?: DyFM_DBĐSort[];
+  /**
+   * The page index number to load.
+   * 0-indexed.
+   */
   page?: number;
+  /**
+   * The page size to load.
+   */
   pageSize?: number;
 }
 

package/src/_models/types/db-/304/221filter.type.ts

@@ -9,12 +9,13 @@ import { DyFM_RangeValue } from '../control-models/range-value.control-model';
  * it should be the value, a range or an array of the searching values
  */
 export type DyFM_DBĐFilter<T> = {
-  [K in keyof T]?:  T[K] | 
-                    T[K][] | 
-                    DyFM_RangeValue<T[K]> | 
-                    DyFM_SpecialSearch<T[K]> |
-                    DyFM_SpecialNestSearch;
+  [K in keyof T]?:  DyFM_DBĐFilterProperty<T, K>;
 };
+export type DyFM_DBĐFilterProperty<T, K extends keyof T> =  T[K] | 
+                                                            T[K][] | 
+                                                            DyFM_RangeValue<T[K]> | 
+                                                            DyFM_SpecialSearch<T[K]> | 
+                                                            DyFM_SpecialNestSearch;
 
 export interface DyFM_SpecialSearch<T> {
   isSpecialSearch: true;

package/src/_modules/crypto/_collections/crypto-old.util.ts

@@ -0,0 +1,323 @@
+import * as CryptoJS from 'crypto-js';
+import { 
+  DyFM_Error, 
+  DyFM_Error_Settings 
+} from '../../../_models/control-models/error.control-model';
+import { DyFM_Object } from '../../../_collections/utils/object.util';
+
+
+/**
+ * Configuration options for encryption/decryption
+ */
+export interface CryptoConfig {
+  ivLength?: number;
+  saltLength?: number;
+  keyIterations?: number;
+  keySize?: number;
+}
+
+// Compact: about 60–80 character tokens, not 200+
+// Non-standard: hard to reverse-engineer
+// Usable in cookies, headers, URLs
+
+/**
+ * A utility class for stable encryption and decryption of data
+ * Uses AES-256-CBC with deterministic IV and salt for consistent results across systems
+ * Prioritizes reliability and cross-platform compatibility over security
+ * 
+ * @important DETERMINISTIC ENCRYPTION: This implementation produces identical encrypted 
+ * output for identical input data and key across different systems and multiple calls.
+ * The same input will ALWAYS generate the same encrypted string on any platform.
+ * 
+ * @warning SECURITY NOTICE: This deterministic behavior is intentional for cross-platform
+ * compatibility but reduces security. Identical inputs produce identical outputs, which
+ * can be exploited for pattern analysis attacks. Use only when consistency across
+ * systems is more important than cryptographic security.
+ */
+export class DyFM_Crypto {
+  private static readonly DEFAULT_CONFIG: Required<CryptoConfig> = {
+    ivLength: 16, // 128 bits
+    saltLength: 16, // 128 bits
+    keyIterations: 1000, // Reduced for better performance and stability
+    keySize: 8 // 256 bits (8 * 32)
+  };
+  private static readonly defaultErrorUserMsg = 
+    `We encountered an unhandled Authentication Error, ` +
+    `\nplease contact the responsible development team.`;
+
+  /**
+   * Validates the input data and key
+   * @throws {DyFM_Error} if validation fails
+   */
+  private static validateInput(data: any, key: string): void {
+    if (!key || typeof key !== 'string' || key.trim().length === 0) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('validateInput'),
+        errorCode: 'DyFM-CRY-IKY',
+        message: 'Invalid encryption key'
+      });
+    }
+
+    // Allow null values but not undefined
+    if (data === undefined) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('validateInput'),
+        errorCode: 'DyFM-CRY-IDT',
+        message: `Invalid data to encrypt/decrypt (is "${data}")`
+      });
+    }
+  }
+
+  /**
+   * Generates a deterministic IV based on the input data and key
+   * Uses MD5 for better stability across different CryptoJS versions
+   * 
+   * @important DETERMINISTIC: Same data + key will ALWAYS produce the same IV
+   * across all systems and CryptoJS versions for consistent encryption results
+   */
+  private static generateIV(data: string, key: string, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
+    // Use MD5 for better stability - simpler hash algorithm, more consistent across versions
+    const combined = data + key;
+    const hash = CryptoJS.MD5(combined);
+    // Use slice(0, 4) for 16 bytes - more stable than division operations
+    return CryptoJS.lib.WordArray.create(hash.words.slice(0, 4));
+  }
+
+  /**
+   * Generates a deterministic salt based on the input data and key
+   * Uses MD5 for better stability across different CryptoJS versions
+   * 
+   * @important DETERMINISTIC: Same data + key will ALWAYS produce the same salt
+   * across all systems and CryptoJS versions for consistent encryption results
+   */
+  private static generateSalt(data: string, key: string, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
+    // Use MD5 for better stability - simpler hash algorithm, more consistent across versions
+    const combined = key + data;
+    const hash = CryptoJS.MD5(combined);
+    // Use slice(0, 4) for 16 bytes - more stable than division operations
+    return CryptoJS.lib.WordArray.create(hash.words.slice(0, 4));
+  }
+
+  /**
+   * Derives a key using PBKDF2 with reduced iterations for stability
+   */
+  private static deriveKey(key: string, salt: CryptoJS.lib.WordArray, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
+    return CryptoJS.PBKDF2(key, salt, {
+      keySize: config.keySize,
+      iterations: config.keyIterations
+    });
+  }
+
+  /**
+   * Safely serializes data to JSON
+   */
+  private static safeSerialize<T>(data: T): string {
+    try {
+      // Always use JSON.stringify to ensure proper serialization/deserialization
+      return JSON.stringify(data);
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('safeSerialize', error),
+        errorCode: 'DyFM-CRY-SER',
+        message: 'Failed to serialize data'
+      });
+    }
+  }
+
+  /**
+   * Safely deserializes JSON data
+   */
+  private static safeDeserialize<T>(data: string): T {
+    try {
+      //let parsed = JSON.parse(data);
+      let parsed = DyFM_Object.failableSafeParseJSON(data);
+      
+      // Handle double-stringified JSON (or more levels of stringification)
+      let maxAttempts = 3; // Prevent infinite loops
+      while (typeof parsed === 'string' && maxAttempts > 0) {
+        try {
+          //const nextParsed = JSON.parse(parsed);
+          const nextParsed = DyFM_Object.failableSafeParseJSON(parsed);
+          // Only continue if parsing actually changed the result
+          if (nextParsed !== parsed) {
+            parsed = nextParsed;
+            maxAttempts--;
+          } else {
+            break;
+          }
+        } catch {
+          // If parse fails, return current state
+          break;
+        }
+      }
+
+      // Handle primitive values
+      /* if (typeof parsed === 'string' || typeof parsed === 'number' || typeof parsed === 'boolean') {
+        return parsed as T;
+      } */
+
+      return parsed as T;
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('safeDeserialize', error),
+        errorCode: 'DyFM-CRY-DES',
+        message: 'Failed to deserialize data'
+      });
+    }
+  }
+
+  /**
+   * Encrypts data using AES-256-CBC with deterministic IV and salt
+   * 
+   * @important DETERMINISTIC BEHAVIOR: This method will produce identical encrypted
+   * output for identical input parameters across different systems, Node.js versions,
+   * and multiple function calls. The same data + key combination will ALWAYS generate
+   * the same encrypted string.
+   * 
+   * @param data The data to encrypt
+   * @param key The encryption key
+   * @param config Optional configuration
+   * @returns URL-safe encrypted string that is identical across systems for same input
+   * @throws {DyFM_Error} if encryption fails
+   * 
+   * @example
+   * // These will produce identical results on any system:
+   * const result1 = DyFM_Crypto.encrypt({id: 1}, "mykey");
+   * const result2 = DyFM_Crypto.encrypt({id: 1}, "mykey");
+   * console.log(result1 === result2); // Always true
+   */
+  static encrypt<T>(data: T, key: string, config?: CryptoConfig): string {
+    try {
+      this.validateInput(data, key);
+      const finalConfig = { ...this.DEFAULT_CONFIG, ...config };
+
+      // Convert data to string
+      const dataStr = this.safeSerialize(data);
+
+      // Generate deterministic IV and salt based on data and key
+      const iv = this.generateIV(dataStr, key, finalConfig);
+      const salt = this.generateSalt(dataStr, key, finalConfig);
+
+      // Derive key using PBKDF2
+      const derivedKey = this.deriveKey(key, salt, finalConfig);
+
+      // Encrypt the data
+      const encrypted = CryptoJS.AES.encrypt(dataStr, derivedKey, {
+        iv: iv,
+        mode: CryptoJS.mode.CBC,
+        padding: CryptoJS.pad.Pkcs7
+      });
+
+      // Combine IV + Salt + Ciphertext
+      const combined = iv.concat(salt).concat(encrypted.ciphertext);
+
+      // Convert to URL-safe base64
+      return CryptoJS.enc.Base64.stringify(combined)
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('encrypt', error),
+        errorCode: 'DyFM-CRY-ENC',
+      });
+    }
+  }
+
+  /**
+   * Decrypts data that was encrypted using encrypt()
+   * @param encryptedData The encrypted data
+   * @param key The decryption key
+   * @param config Optional configuration
+   * @returns The decrypted data
+   * @throws {DyFM_Error} if decryption fails
+   */
+  static decrypt<T>(encryptedData: string, key: string, config?: CryptoConfig): T {
+    try {
+      this.validateInput(encryptedData, key);
+      const finalConfig = { ...this.DEFAULT_CONFIG, ...config };
+
+      // Convert from URL-safe base64
+      const base64 = encryptedData
+        .replace(/-/g, '+')
+        .replace(/_/g, '/');
+
+      // Parse the combined data
+      const combined = CryptoJS.enc.Base64.parse(base64);
+
+      // Validate minimum length (IV + Salt + minimum ciphertext)
+      const minLength = (finalConfig.ivLength + finalConfig.saltLength + 16) / 4; // 16 bytes minimum for ciphertext
+      if (combined.words.length < minLength) {
+        throw new Error('Invalid encrypted data length');
+      }
+
+      // Extract IV, salt, and ciphertext
+      const iv = CryptoJS.lib.WordArray.create(combined.words.slice(0, finalConfig.ivLength / 4));
+      const salt = CryptoJS.lib.WordArray.create(
+        combined.words.slice(
+          finalConfig.ivLength / 4,
+          (finalConfig.ivLength + finalConfig.saltLength) / 4
+        )
+      );
+      const ciphertext = CryptoJS.lib.WordArray.create(
+        combined.words.slice((finalConfig.ivLength + finalConfig.saltLength) / 4)
+      );
+
+      // Derive key using PBKDF2
+      const derivedKey = this.deriveKey(key, salt, finalConfig);
+
+      // Decrypt the data
+      const decrypted = CryptoJS.AES.decrypt(
+        { ciphertext: ciphertext },
+        derivedKey,
+        {
+          iv: iv,
+          mode: CryptoJS.mode.CBC,
+          padding: CryptoJS.pad.Pkcs7
+        }
+      );
+
+      // Parse JSON
+      const decryptedStr = decrypted.toString(CryptoJS.enc.Utf8);
+      return this.safeDeserialize<T>(decryptedStr);
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('decrypt', error),
+        errorCode: 'DyFM-CRY-DRY',
+      });
+    }
+  }
+
+  /**
+   * Generates a secure random key
+   * @param length Length of the key in bytes (default: 32)
+   * @returns A secure random key
+   */
+  static generateKey(length: number = 32): string {
+    return CryptoJS.lib.WordArray.random(length).toString();
+  }
+
+  /**
+   * Validates if a string is a valid encrypted data
+   * @param encryptedData The data to validate
+   * @returns true if the data appears to be valid encrypted data
+   */
+  static isValidEncryptedData(encryptedData: string): boolean {
+    if (!encryptedData || typeof encryptedData !== 'string') {
+      return false;
+    }
+    return /^[A-Za-z0-9\-_]+$/.test(encryptedData);
+  }
+
+  /**
+   * Gets default error settings
+   */
+  private static getDefaultErrorSettings(operation: string, error?: any): DyFM_Error_Settings {
+    return {
+      status: (error as DyFM_Error)?.___status ?? (error as any)?.status ?? 401,
+      message: `Crypto operation "${operation}" failed`,
+      error: error,
+      errorCode: 'DyFM-CRY-ERR'
+    };
+  }
+}