@futdevpro/fsm-dynamo 1.20.88 → 1.20.93

package/build-esm/_collections/utils/async.util.js

@@ -0,0 +1,183 @@
+import { second, hour, minute, week, day } from '../constants/times.const';
+import { DyFM_Log } from './log.util';
+import { DyFM_Time } from './time.util';
+export class DyFM_Async {
+    /**
+     * delays the execution of a function
+     * @param ms
+     * @returns
+     *
+     * @example
+     * ```ts
+     * await DyFM_Async.wait(1000);
+     * ```
+     */
+    static wait(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    static sleep = this.wait;
+    static delay = this.wait;
+    /**
+     * WARNING: This function is recommended to use ONLY for limited instances,
+     * because it can cause performance issues.
+     *
+     * @example
+     * ```ts
+     * await DyFM_Async.waitUntil(() => check(), 100, 10000);
+     * ```
+     */
+    static waitUntil(check, interval = 100, timeout = 10_000) {
+        const timeoutError = new Error('waitUntil timeout');
+        return new Promise((resolve, reject) => {
+            const startTime = Date.now();
+            const intervalId = setInterval(() => {
+                if (check()) {
+                    clearInterval(intervalId);
+                    resolve();
+                }
+                else if (Date.now() - startTime > timeout) {
+                    clearInterval(intervalId);
+                    reject(timeoutError);
+                }
+            }, interval);
+        });
+    }
+    /**
+     * WARNING: This function is recommended to use ONLY for limited instances,
+     * because it can cause performance issues.
+     *
+     * @example
+     * const result = await DyFM_Async.waitUntilAsync(
+     *   () => check(),
+     *   30 * second,
+     *   5 * minute,
+     * );
+     */
+    static waitUntilAsync(check, interval = 100, timeout = 10000) {
+        const timeoutError = new Error('waitUntilAsync timeout');
+        return new Promise((resolve, reject) => {
+            const startTime = Date.now();
+            const intervalId = setInterval(async () => {
+                if (await check()) {
+                    clearInterval(intervalId);
+                    resolve();
+                }
+                else if (Date.now() - startTime > timeout) {
+                    clearInterval(intervalId);
+                    reject(timeoutError);
+                }
+            }, interval);
+        });
+    }
+    /**
+     * Creates a promise that resolves when the observable emits a value that passes the check function
+     *
+     * @example
+     * ```ts
+     * const observable = new Observable<number>(observer => {
+     *   setInterval(() => observer.next(Math.random()), 100);
+     * });
+     * const result = await DyFM_Async.takeUntil(observable, (value?: number) => value && value > 0.5);
+     * ```
+     */
+    static takeUntil(observable, check) {
+        return new Promise((resolve) => {
+            // BFR-FDPTOKENSERVICE-024: szinkron emissziónál (BehaviorSubject / of) a callback még a
+            // subscribe visszatérte ELŐTT fut — `const sub` ekkor TDZ-ben lenne (ReferenceError, és a
+            // Promise sosem oldana fel). `let` + resolved-jelző; a leiratkozás ilyenkor utólag történik.
+            let resolved = false;
+            let sub;
+            sub = observable.subscribe((value) => {
+                if (!resolved && check(value)) {
+                    resolved = true;
+                    sub?.unsubscribe();
+                    resolve(value);
+                }
+            });
+            if (resolved) {
+                sub.unsubscribe();
+            }
+        });
+    }
+    /**
+     * Waits for a given amount of time and logs the remaining time.
+     * @param totalWaitTimeMs - The total amount of time to wait.
+     * @param context - The context of the countdown.
+     * @returns A promise that resolves when the countdown is complete.
+     *
+     * @example
+     * ```ts
+     * await DyFM_Async.waitWithCountdownLogging(1000, 'Countdown');
+     * ```
+     */
+    static async waitWithCountdownLogging(totalWaitTimeMs, context = 'Countdown') {
+        const startTime = Date.now();
+        const endTime = startTime + totalWaitTimeMs;
+        // Define logging intervals based on total duration
+        /**
+         * Gets the logging interval based on the total duration.
+         * @param totalMs - The total duration in milliseconds.
+         * @returns The logging interval in milliseconds.
+         *
+         * @example
+         * ```ts
+         * const logInterval = getLogInterval(1000);
+         * console.log(logInterval); // 1000
+         * ```
+         */
+        const getLogInterval = (totalMs) => {
+            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) => DyFM_Time.getTimeInShortestString(remainingMs);
+        // 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/build-esm/_collections/utils/data.util.js

@@ -0,0 +1,203 @@
+import { kilobyte, megabyte, gigabyte, terabyte, petabyte, exabyte, zettabyte, yottabyte } from '../constants/data-sizes.const';
+import { DyFM_Math } from './math/math.util';
+/**
+ * Data utility class
+ *
+ * Hungarian documentation (Hunglish):
+ * - Ez a utility data-size konverziókra fókuszál, ember-barát string formátummal
+ * - A számítás 1024-es alapot használ (KB/MB/GB/TB)
+ * - A `getSizeString` adja vissza a rövidített formátumot, pl.: `1.5KB`, `12MB`, `1GB 256MB`
+ */
+export class DyFM_Data {
+    /**
+     * A kilobyte (1024 B) egység
+     */
+    static kilobyte = kilobyte;
+    /**
+     * A megabyte (1024 KB) egység
+     */
+    static megabyte = megabyte;
+    /**
+     * A gigabyte (1024 MB) egység
+     */
+    static gigabyte = gigabyte;
+    /**
+     * A terabyte (1024 GB) egység
+     */
+    static terabyte = terabyte;
+    /**
+     * A petabyte (1024 TB) egység
+     */
+    static petabyte = petabyte;
+    /**
+     * A exabyte (1024 PB) egység
+     */
+    static exabyte = exabyte;
+    /**
+     * A zettabyte (1024 EB) egység
+     */
+    static zettabyte = zettabyte;
+    /**
+     * A yottabyte (1024 ZB) egység
+     */
+    static yottabyte = yottabyte;
+    /**
+     * Size-et ad vissza ember-barát string-ként.
+     * - 1024-es váltószámot használunk (KB/MB/GB/TB)
+     * - Negatív értékeknél `-` jel kerül az elejére (abszolút értékkel számolunk)
+     * - `full=true` esetén a következő kisebb egység maradéka is megjelenik (pl. `1GB 256MB`)
+     *
+     * Példák:
+     * ```ts
+     * DyFM_Data.getSizeString(0);               // '0B'
+     * DyFM_Data.getSizeString(1536);            // '1.5KB'
+     * DyFM_Data.getSizeString(1536, 0, true);   // '2KB 0B'
+     * DyFM_Data.getSizeString(1_234_567);       // '1.18MB'
+     * DyFM_Data.getSizeString(1_234_567, 0);    // '1MB'
+     * DyFM_Data.getSizeString(1_500_000_000);   // '1.4GB'
+     * ```
+     */
+    static getSizeString(size, decimals, full) {
+        // Edge case: 0 → rögtön visszaadjuk
+        if (size === 0) {
+            return '0B';
+        }
+        if (!size) {
+            return 'N/A';
+        }
+        // Negatív jel kezelése, számítás abszolút értékkel
+        const isNegative = size < 0;
+        let remaining = Math.abs(size);
+        // < 1KB → B (decimals nélkül)
+        if (remaining < this.kilobyte) {
+            const sign = isNegative ? '-' : '';
+            return `${sign}${Math.floor(remaining)}B`;
+        }
+        // KB
+        if (remaining < this.megabyte) {
+            const kb = remaining / this.kilobyte;
+            if (full) {
+                const kbWhole = Math.floor(kb);
+                const remainderAfterKb = remaining - (kbWhole * this.kilobyte);
+                const bRemainder = Math.floor(remainderAfterKb);
+                const sign = isNegative ? '-' : '';
+                if (bRemainder > 0) {
+                    return `${sign}${kbWhole}KB ${bRemainder}B`;
+                }
+                return `${sign}${kbWhole}KB`;
+            }
+            const str = `${DyFM_Math.round(kb, decimals ?? (Number.isInteger(kb) ? 0 : 2))}KB`;
+            return isNegative ? `-${str}` : str;
+        }
+        // MB
+        if (remaining < this.gigabyte) {
+            const mb = remaining / this.megabyte;
+            if (full) {
+                const mbWhole = Math.floor(mb);
+                const remainderAfterMb = remaining - (mbWhole * this.megabyte);
+                const kbRemainder = Math.floor(remainderAfterMb / this.kilobyte);
+                const sign = isNegative ? '-' : '';
+                if (kbRemainder > 0) {
+                    return `${sign}${mbWhole}MB ${kbRemainder}KB`;
+                }
+                return `${sign}${mbWhole}MB`;
+            }
+            const str = `${DyFM_Math.round(mb, decimals ?? (Number.isInteger(mb) ? 0 : 2))}MB`;
+            return isNegative ? `-${str}` : str;
+        }
+        // GB
+        if (remaining < this.terabyte) {
+            const gb = remaining / this.gigabyte;
+            if (full) {
+                const gbWhole = Math.floor(gb);
+                const remainderAfterGb = remaining - (gbWhole * this.gigabyte);
+                const mbRemainder = Math.floor(remainderAfterGb / this.megabyte);
+                const sign = isNegative ? '-' : '';
+                if (mbRemainder > 0) {
+                    return `${sign}${gbWhole}GB ${mbRemainder}MB`;
+                }
+                return `${sign}${gbWhole}GB`;
+            }
+            const str = `${DyFM_Math.round(gb, decimals ?? (Number.isInteger(gb) ? 0 : 2))}GB`;
+            return isNegative ? `-${str}` : str;
+        }
+        // TB
+        if (remaining < this.petabyte) {
+            const tb = remaining / this.terabyte;
+            if (full) {
+                const tbWhole = Math.floor(tb);
+                const remainderAfterTb = remaining - (tbWhole * this.terabyte);
+                const gbRemainder = Math.floor(remainderAfterTb / this.gigabyte);
+                const sign = isNegative ? '-' : '';
+                if (gbRemainder > 0) {
+                    return `${sign}${tbWhole}TB ${gbRemainder}GB`;
+                }
+                return `${sign}${tbWhole}TB`;
+            }
+            const str = `${DyFM_Math.round(tb, decimals ?? (Number.isInteger(tb) ? 0 : 2))}TB`;
+            return isNegative ? `-${str}` : str;
+        }
+        // PB
+        if (remaining < this.exabyte) {
+            const pb = remaining / this.petabyte;
+            if (full) {
+                const pbWhole = Math.floor(pb);
+                const remainderAfterPb = remaining - (pbWhole * this.petabyte);
+                const tbRemainder = Math.floor(remainderAfterPb / this.terabyte);
+                const sign = isNegative ? '-' : '';
+                if (tbRemainder > 0) {
+                    return `${sign}${pbWhole}PB ${tbRemainder}TB`;
+                }
+                return `${sign}${pbWhole}PB`;
+            }
+            const str = `${DyFM_Math.round(pb, decimals ?? (Number.isInteger(pb) ? 0 : 2))}PB`;
+            return isNegative ? `-${str}` : str;
+        }
+        // EB
+        if (remaining < this.zettabyte) {
+            const eb = remaining / this.exabyte;
+            if (full) {
+                const ebWhole = Math.floor(eb);
+                const remainderAfterEb = remaining - (ebWhole * this.exabyte);
+                const pbRemainder = Math.floor(remainderAfterEb / this.petabyte);
+                const sign = isNegative ? '-' : '';
+                if (pbRemainder > 0) {
+                    return `${sign}${ebWhole}EB ${pbRemainder}PB`;
+                }
+                return `${sign}${ebWhole}EB`;
+            }
+            const str = `${DyFM_Math.round(eb, decimals ?? (Number.isInteger(eb) ? 0 : 2))}EB`;
+            return isNegative ? `-${str}` : str;
+        }
+        // ZB
+        if (remaining < this.yottabyte) {
+            const zb = remaining / this.zettabyte;
+            if (full) {
+                const zbWhole = Math.floor(zb);
+                const remainderAfterZb = remaining - (zbWhole * this.zettabyte);
+                const ebRemainder = Math.floor(remainderAfterZb / this.exabyte);
+                const sign = isNegative ? '-' : '';
+                if (ebRemainder > 0) {
+                    return `${sign}${zbWhole}ZB ${ebRemainder}EB`;
+                }
+                return `${sign}${zbWhole}ZB`;
+            }
+            const str = `${DyFM_Math.round(zb, decimals ?? (Number.isInteger(zb) ? 0 : 2))}ZB`;
+            return isNegative ? `-${str}` : str;
+        }
+        // YB
+        const yb = remaining / this.yottabyte;
+        if (full) {
+            const ybWhole = Math.floor(yb);
+            const remainderAfterYb = remaining - (ybWhole * this.yottabyte);
+            const zbRemainder = Math.floor(remainderAfterYb / this.zettabyte);
+            const sign = isNegative ? '-' : '';
+            if (zbRemainder > 0) {
+                return `${sign}${ybWhole}YB ${zbRemainder}ZB`;
+            }
+            return `${sign}${ybWhole}YB`;
+        }
+        const str = `${DyFM_Math.round(yb, decimals ?? (Number.isInteger(yb) ? 0 : 2))}YB`;
+        return isNegative ? `-${str}` : str;
+    }
+}

package/build-esm/_collections/utils/extract-error-message.util.js

@@ -0,0 +1,183 @@
+/**
+ * Universal error → human-readable string extractor. **Never** returns the
+ * literal string `'undefined'` (or `'undefined undefined'`), `'[object Object]'`,
+ * or any other JS-rendering artifact. Walks the full DyFM_Error pipeline plus
+ * common Angular HttpErrorResponse + plain Error shapes, falling back to a
+ * meaningful diagnostic string when the input is malformed.
+ *
+ * Order of attempts (first non-empty wins) — USER-FACING fields only by default:
+ *   0. If `err` itself is a string, use as-is (the caller meant it as the text)
+ *   1. `err.__userMessage` (DyFM_Error user message)
+ *   2. `err.userMessage` (deprecated DyFM_Error_Settings field, still seen on some payloads)
+ *   3. `err.error.__userMessage` (HttpErrorResponse wrapping a DyFM_Error in its body — beats the outer technical
+ *      `message`)
+ *   4. `err.error.userMessage`
+ *   5. ONLY with `includeTechnicalMessage: true`: `err._message` · `err.message` · `err.error._message` ·
+ *      `err.error.message` (debug / transport texts — never a user message by default)
+ *   6. ONLY with `includeRawPayload: true`: the JSON-stringified payload (circular-safe; first 200 chars),
+ *      prefixed with 'Malformed error: ' (default: skipped — raw JSON is not a user message)
+ *   7. `options.fallback` (or its default)
+ *
+ * Only when `includeHttpStatus: true` (opt-in, default `false`) and the input
+ * looks like a HttpErrorResponse, the status + statusText are appended in
+ * parens: e.g. `'Bad credentials (HTTP 401 Unauthorized)'`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await auth_CS.login(account);
+ * } catch (err) {
+ *   this.formError = DyFM_extractErrorMessage(err, { prefix: 'Login' });
+ *   // → 'Login: Bad credentials'   (the raw `err` keeps the status for the log / copy chain)
+ *   //   OR
+ *   // → 'Login: Network unreachable — check connection. Server logs may have detail.'
+ *   //   never 'Login: undefined undefined'
+ * }
+ * ```
+ */
+export function DyFM_extractErrorMessage(err, options) {
+    const includeHttpStatus = options?.includeHttpStatus === true;
+    const fallback = options?.fallback
+        ?? 'Unexpected error (no detail in payload — check server logs).';
+    const prefix = options?.prefix ? `${options.prefix}: ` : '';
+    // Null/undefined/empty
+    if (err === null || err === undefined) {
+        return `${prefix}${fallback}`;
+    }
+    // String → use as-is
+    if (typeof err === 'string') {
+        return `${prefix}${err}`;
+    }
+    // Walk the candidate fields in order. Cast to any to access optional
+    // properties without forcing each branch into a separate type guard.
+    const e = err;
+    const innerError = e?.error;
+    // user-facing fields first (outer, then the body of a wrapping HttpErrorResponse)
+    const userCandidate = _nonEmptyString(e?.__userMessage)
+        ?? _nonEmptyString(e?.userMessage)
+        ?? _nonEmptyString(innerError?.__userMessage)
+        ?? _nonEmptyString(innerError?.userMessage);
+    // technical fields (debug / transport) only on opt-in — see `includeTechnicalMessage`
+    const candidate = userCandidate ?? (options?.includeTechnicalMessage === true
+        ? _nonEmptyString(e?._message)
+            ?? _nonEmptyString(e?.message)
+            ?? _nonEmptyString(innerError?._message)
+            ?? _nonEmptyString(innerError?.message)
+        : undefined);
+    // HTTP status suffix (always-on by default)
+    const status = e?.___status
+        ?? e?.status
+        ?? innerError?.___status
+        ?? innerError?.status;
+    const statusText = _nonEmptyString(e?.statusText)
+        ?? _nonEmptyString(innerError?.statusText);
+    const httpSuffix = (includeHttpStatus && (status !== undefined || statusText !== undefined))
+        ? ` (HTTP ${status ?? '?'}${statusText ? ' ' + statusText : ''})`
+        : '';
+    if (candidate !== undefined) {
+        return `${prefix}${candidate}${httpSuffix}`;
+    }
+    // No usable text field. The raw payload only on opt-in (diagnostic) — the user gets the fallback.
+    const jsonAttempt = options?.includeRawPayload === true ? _safeJsonStringify(err) : undefined;
+    if (jsonAttempt !== undefined && jsonAttempt !== '{}' && jsonAttempt !== '[]') {
+        const trimmed = jsonAttempt.length > 200
+            ? jsonAttempt.slice(0, 200) + '…'
+            : jsonAttempt;
+        return `${prefix}Malformed error: ${trimmed}${httpSuffix}`;
+    }
+    // Total fallback.
+    return `${prefix}${fallback}${httpSuffix}`;
+}
+/**
+ * Returns the value if it's a non-empty string, else undefined.
+ * Trims and treats whitespace-only as empty. Internal helper.
+ */
+function _nonEmptyString(v) {
+    if (typeof v !== 'string') {
+        return undefined;
+    }
+    const trimmed = v.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * JSON.stringify wrapper that survives circular references + non-serializable
+ * values. Returns undefined if even the safe fallback fails (e.g. a Proxy
+ * whose getter throws).
+ */
+function _safeJsonStringify(v) {
+    try {
+        const seen = new WeakSet();
+        return JSON.stringify(v, (_key, value) => {
+            if (typeof value === 'object' && value !== null) {
+                if (seen.has(value)) {
+                    return '[Circular]';
+                }
+                seen.add(value);
+            }
+            if (typeof value === 'function') {
+                return '[Function]';
+            }
+            if (typeof value === 'undefined') {
+                return '[undefined]';
+            }
+            return value;
+        });
+    }
+    catch {
+        try {
+            return String(v);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * Convenience: same as DyFM_extractErrorMessage but always includes a default
+ * prefix derived from the calling context, useful for adding diagnostic
+ * breadcrumbs without per-call boilerplate. Diagnostic ⇒ it keeps the HTTP
+ * status, the technical message and the raw payload (`includeHttpStatus` + `includeTechnicalMessage` +
+ * `includeRawPayload`) — do not show its result to users.
+ */
+export function DyFM_formatError(err, prefix) {
+    return DyFM_extractErrorMessage(err, {
+        prefix: prefix, includeHttpStatus: true, includeTechnicalMessage: true, includeRawPayload: true,
+    });
+}
+/**
+ * Reports a raw error payload via the universal client-error capture system
+ * (FR-029-style). Implementation is delegated to a consumer-registered
+ * handler so dynamo-fsm stays Angular-agnostic; if no handler is registered
+ * the error is logged via `DyFM_Log.error` (which is the default no-op-safe
+ * sink). Consumers (e.g. A_ErrorHandler_ControlService) call
+ * `DyFM_registerMalformedErrorSink(fn)` once at bootstrap.
+ *
+ * The intent: when DyFM_extractErrorMessage falls back to 'Malformed error:'
+ * or the generic fallback, the raw payload should also be captured for
+ * post-mortem analysis (server error-log via FR-029 pipeline).
+ */
+let _malformedErrorSink;
+export function DyFM_registerMalformedErrorSink(fn) {
+    _malformedErrorSink = fn;
+}
+export function DyFM_reportMalformedError(err, context) {
+    if (_malformedErrorSink !== undefined) {
+        try {
+            _malformedErrorSink(err, context);
+            return;
+        }
+        catch {
+            /* sink threw — fall through to default */
+        }
+    }
+    // Default: best-effort console.error wrapped in DyFM_Error for stack capture.
+    try {
+        // Lazy require to avoid a hard cycle through error.control-model -> log.util.
+        const { DyFM_Log } = require('./log.util');
+        DyFM_Log.error(`[DyFM_reportMalformedError] ${context ?? 'unknown context'}`, err);
+    }
+    catch {
+        // Last-ditch — should never happen since log.util has no further deps.
+        /* swallow */
+    }
+}