@futdevpro/fsm-dynamo 1.20.92 → 1.20.93

package/build-esm/_modules/state-machine/_models/state-machine.control-model.js

@@ -0,0 +1,262 @@
+import { BehaviorSubject, Subject } from 'rxjs';
+/**
+ * Generic finite state machine (FR-006, BL-20260518-004).
+ *
+ * Konfiguralhato `initial` state-tel + `transitions[]` listaval. Reaktiv
+ * (`state$` BehaviorSubject + `events$` Subject), single-instance mutex-szel
+ * vedett, opcionalis aszinkron `persist` callback-kel.
+ *
+ * **Hasznalat (CCAP MP1-D RAG ingest minta):**
+ * ```typescript
+ * enum RagIngestState { Idle='idle', Ingesting='ingesting', Embedding='embedding',
+ *   Ready='ready', Degraded='degraded', Reingesting='reingesting' }
+ *
+ * const ragFsm = new DyFM_StateMachine_ControlModel<RagIngestState>({
+ *   initial: RagIngestState.Idle,
+ *   transitions: [
+ *     { from: RagIngestState.Idle, to: RagIngestState.Ingesting },
+ *     { from: RagIngestState.Ingesting, to: RagIngestState.Embedding,
+ *       guard: ctx => ctx?.pendingChunks === 0 },
+ *     { from: RagIngestState.Embedding, to: RagIngestState.Ready,
+ *       onEnter: () => persistCorpusVersion() },
+ *     { from: RagIngestState.Ready, to: RagIngestState.Degraded },
+ *     { from: RagIngestState.Degraded, to: RagIngestState.Reingesting },
+ *     // Wildcard array: barmely "futasi" allapotbol degraded-re
+ *     { from: [RagIngestState.Ingesting, RagIngestState.Embedding,
+ *              RagIngestState.Reingesting], to: RagIngestState.Degraded },
+ *   ],
+ *   persist: async event => await mongoCollection.updateOne(
+ *     { _id: 'rag-status', stateVersion: event.stateVersion - 1 },
+ *     { $set: { state: event.to, stateVersion: event.stateVersion } },
+ *   ),
+ * });
+ *
+ * const result = await ragFsm.transition(RagIngestState.Ingesting);
+ * if (result.ok) { console.log('Now in:', result.to, 'v:', result.stateVersion); }
+ * ```
+ *
+ * **Atomicity:** Az `onEnter` vagy `persist` callback throw-ja eseten a state
+ * automatikusan visszaall a from-ra (revert). Ha az `onLeave` throw-ol, a
+ * state-valtas mar el sem kezdodik (early-return).
+ *
+ * **Mutex:** Egy-instance-en belul a `transition()` hivasok sorosak (in-memory
+ * Promise-queue). Tobb-instance / tobb-folyamatos race-condition-re az
+ * opcionalis `persist` callback `stateVersion`-t hasznalja optimistic-locking-hez.
+ */
+export class DyFM_StateMachine_ControlModel {
+    /** Aktualis state. */
+    _state;
+    /** Aktualis state-version (0 = initial; minden sikeres atmenet utan +1). */
+    _stateVersion = 0;
+    /** Reactive state-source. */
+    _state_BS;
+    /** Public reactive state observable. */
+    state$;
+    /** Reactive event-stream — minden sikeres atmenet utan emittal. */
+    _events_S;
+    /** Public reactive event observable. */
+    events$;
+    /** Config snapshot. */
+    _config;
+    /** Mutex tail — soros transition() hivasokhoz. */
+    _mutexTail = Promise.resolve();
+    constructor(config) {
+        if (!config || typeof config !== 'object') {
+            throw new Error('DyFM_StateMachine_ControlModel: config object required');
+        }
+        if (typeof config.initial !== 'string') {
+            throw new Error('DyFM_StateMachine_ControlModel: config.initial must be a string state value');
+        }
+        if (!Array.isArray(config.transitions) || config.transitions.length === 0) {
+            throw new Error('DyFM_StateMachine_ControlModel: config.transitions must be a non-empty array');
+        }
+        this._config = config;
+        this._state = config.initial;
+        this._state_BS = new BehaviorSubject(this._state);
+        this.state$ = this._state_BS.asObservable();
+        this._events_S = new Subject();
+        this.events$ = this._events_S.asObservable();
+    }
+    /**
+     * Sync getter — az aktualis state.
+     */
+    state() {
+        return this._state;
+    }
+    /**
+     * Sync getter — az aktualis state-version.
+     */
+    stateVersion() {
+        return this._stateVersion;
+    }
+    /**
+     * Megnezi hogy van-e olyan transition ami a jelenlegi state-bol a kert
+     * `to`-ba vezet, ES (ha van guard) a guard `true`-t adna a kontextusra.
+     *
+     * NEM fut le onLeave / onEnter / persist callback.
+     */
+    async canTransition(to, ctx) {
+        const transition = this._findTransition(this._state, to);
+        if (!transition) {
+            return false;
+        }
+        if (transition.guard) {
+            try {
+                const guardResult = await transition.guard(ctx);
+                return guardResult === true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Atmenet vegrehajtasa a kert `to` state-re.
+     *
+     * Flow:
+     *  1. Mutex-acquire — soros vegrehajtas egy instance-en
+     *  2. Transition-keres (`_findTransition`); ha nincs → `invalid-transition`
+     *  3. `guard(ctx)` — ha false → `guard-rejected`
+     *  4. `onLeave(ctx)` — throw → `on-leave-failed` (state meg NEM valtozott)
+     *  5. State + version frissites, `state$.next()` emit
+     *  6. `onEnter(ctx)` — throw → revert state + `on-enter-failed`
+     *  7. `persist(event)` if configured — throw → revert state + `persist-failed`
+     *  8. `events$.next(event)` emit
+     *  9. Mutex-release, return ok
+     */
+    async transition(to, ctx) {
+        const release = { resolve: () => { } };
+        const myTurn = new Promise((res) => {
+            release.resolve = res;
+        });
+        const prevTail = this._mutexTail;
+        this._mutexTail = myTurn;
+        try {
+            await prevTail;
+            return await this._transitionInternal(to, ctx);
+        }
+        finally {
+            release.resolve();
+        }
+    }
+    /** Mutex-protected belso transition logika. */
+    async _transitionInternal(to, ctx) {
+        const from = this._state;
+        // 1. Transition lookup
+        const transition = this._findTransition(from, to);
+        if (!transition) {
+            return this._failure(from, to, 'invalid-transition');
+        }
+        // 2. Guard check
+        if (transition.guard) {
+            let guardResult;
+            try {
+                guardResult = await transition.guard(ctx);
+            }
+            catch (err) {
+                return this._failure(from, to, 'guard-rejected', err);
+            }
+            if (guardResult !== true) {
+                return this._failure(from, to, 'guard-rejected');
+            }
+        }
+        // 3. onLeave (pre-change)
+        if (transition.onLeave) {
+            try {
+                await transition.onLeave(ctx);
+            }
+            catch (err) {
+                return this._failure(from, to, 'on-leave-failed', err);
+            }
+        }
+        // 4. State + version transition (the actual change)
+        const newVersion = this._stateVersion + 1;
+        this._state = to;
+        this._stateVersion = newVersion;
+        this._state_BS.next(this._state);
+        // 5. onEnter (post-change, pre-persist)
+        if (transition.onEnter) {
+            try {
+                await transition.onEnter(ctx);
+            }
+            catch (err) {
+                // Revert
+                this._state = from;
+                this._stateVersion = newVersion - 1;
+                this._state_BS.next(this._state);
+                return this._failure(from, to, 'on-enter-failed', err);
+            }
+        }
+        // 6. Persist (post-state-change, post-onEnter)
+        const event = {
+            from: from,
+            to: to,
+            stateVersion: newVersion,
+            context: ctx,
+            timestamp: Date.now(),
+        };
+        if (this._config.persist) {
+            try {
+                await this._config.persist(event);
+            }
+            catch (err) {
+                // Revert
+                this._state = from;
+                this._stateVersion = newVersion - 1;
+                this._state_BS.next(this._state);
+                return this._failure(from, to, 'persist-failed', err);
+            }
+        }
+        // 7. Emit event
+        this._events_S.next(event);
+        return {
+            ok: true,
+            from: from,
+            to: to,
+            stateVersion: newVersion,
+        };
+    }
+    /**
+     * Lookup: a `transitions[]` listaban olyat keres, aminek `from` matchel a
+     * `current`-tel (vagy `'*'` wildcard), ES `to` matchel a `target`-tel.
+     *
+     * Az elso talalatot adja vissza (a kepes ezert a config-ban a specifikusabb
+     * jojjon eloszor a wildcardnel — de a peldakban a wildcard tartalmazza az
+     * 'invalidat' is, igy az ordering MUST nem szigoru a tipikus eseteknel).
+     */
+    _findTransition(current, target) {
+        for (const t of this._config.transitions) {
+            if (t.to !== target) {
+                continue;
+            }
+            if (t.from === '*') {
+                return t;
+            }
+            if (Array.isArray(t.from)) {
+                if (t.from.includes(current)) {
+                    return t;
+                }
+            }
+            else if (t.from === current) {
+                return t;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Belso helper a sikertelen result epitesere.
+     */
+    _failure(from, attemptedTo, reason, error) {
+        return {
+            ok: false,
+            reason: reason,
+            currentState: this._state,
+            attemptedTo: attemptedTo,
+            error: error,
+        };
+    }
+}
+Object.defineProperty(DyFM_StateMachine_ControlModel, 'name', { value: 'DyFM_StateMachine' });
+/** @deprecated Use DyFM_StateMachine_ControlModel. Same constructor; no API removal. */
+export { DyFM_StateMachine_ControlModel as DyFM_StateMachine };

package/build-esm/_modules/state-machine/_models/state-transition-result.interface.js

@@ -0,0 +1 @@
+export {};

package/build-esm/_modules/state-machine/_models/state-transition.interface.js

@@ -0,0 +1 @@
+export {};

package/build-esm/_modules/state-machine/index.js

@@ -0,0 +1,6 @@
+// MODELS
+export * from './_models/state-machine.control-model';
+export * from './_models/state-machine-config.interface';
+export * from './_models/state-machine-event.interface';
+export * from './_models/state-transition.interface';
+export * from './_models/state-transition-result.interface';

package/build-esm/_modules/test/_collections/tst-module-settings.const.js

@@ -0,0 +1,38 @@
+/**
+ * Routes used by the test module.
+ */
+export var DyFM_TestRoute;
+(function (DyFM_TestRoute) {
+    DyFM_TestRoute["testGet"] = "test-get";
+    DyFM_TestRoute["testPost"] = "test-post";
+    DyFM_TestRoute["testPut"] = "test-put";
+    DyFM_TestRoute["testPatch"] = "test-patch";
+    DyFM_TestRoute["testDelete"] = "test-delete";
+    DyFM_TestRoute["getServerStatus"] = "get-server-status";
+})(DyFM_TestRoute || (DyFM_TestRoute = {}));
+/**
+ * Default route settings for the test module.
+ */
+export const DyFM_testModule_settings = {
+    mainRoute: '/test',
+    endPoints: {
+        ...Object.fromEntries(Object.values(DyFM_TestRoute).map((route) => [route, `/${route}`])),
+    },
+};
+/**
+ * Map of routes with their full path.
+ */
+export const DyFM_fullTestRoute = {
+    [DyFM_TestRoute.testGet]: DyFM_testModule_settings.mainRoute +
+        DyFM_testModule_settings.endPoints[DyFM_TestRoute.testGet],
+    [DyFM_TestRoute.testPost]: DyFM_testModule_settings.mainRoute +
+        DyFM_testModule_settings.endPoints[DyFM_TestRoute.testPost],
+    [DyFM_TestRoute.testPut]: DyFM_testModule_settings.mainRoute +
+        DyFM_testModule_settings.endPoints[DyFM_TestRoute.testPut],
+    [DyFM_TestRoute.testPatch]: DyFM_testModule_settings.mainRoute +
+        DyFM_testModule_settings.endPoints[DyFM_TestRoute.testPatch],
+    [DyFM_TestRoute.testDelete]: DyFM_testModule_settings.mainRoute +
+        DyFM_testModule_settings.endPoints[DyFM_TestRoute.testDelete],
+    [DyFM_TestRoute.getServerStatus]: DyFM_testModule_settings.mainRoute +
+        DyFM_testModule_settings.endPoints[DyFM_TestRoute.getServerStatus],
+};

package/build-esm/_modules/test/index.js

@@ -0,0 +1,2 @@
+// COLLECTIONS
+export * from './_collections/tst-module-settings.const';

package/build-esm/_modules/usage/_collections/usg-module-settings.const.js

@@ -0,0 +1,16 @@
+export var DyFM_UsageRoute;
+(function (DyFM_UsageRoute) {
+    DyFM_UsageRoute["newSession"] = "newSession";
+    DyFM_UsageRoute["closeSession"] = "closeSession";
+    DyFM_UsageRoute["updateUsage"] = "updateUsage";
+    DyFM_UsageRoute["getUsageData"] = "getUsageData";
+})(DyFM_UsageRoute || (DyFM_UsageRoute = {}));
+export const DyFM_usageModule_settings = {
+    mainRoute: '/usage',
+    endPoints: {
+        [DyFM_UsageRoute.newSession]: '/new-session',
+        [DyFM_UsageRoute.closeSession]: '/close-session/:sessionId',
+        [DyFM_UsageRoute.updateUsage]: '/update/:sessionId',
+        [DyFM_UsageRoute.getUsageData]: '/get/:range',
+    },
+};

package/build-esm/_modules/usage/_models/usg-action.control-model.js

@@ -0,0 +1,25 @@
+/**
+ * Represents a single user action during a session.
+ *
+ * @example
+ * ```ts
+ * const action = new DyFM_UsgAction_ControlModel({
+ *   action: 'click',
+ *   time: new Date()
+ * });
+ * ```
+ */
+export class DyFM_UsgAction_ControlModel {
+    /** Type of the action performed */
+    action;
+    /** Timestamp of when the action happened */
+    time;
+    constructor(set) {
+        if (set) {
+            Object.assign(this, set);
+        }
+    }
+}
+Object.defineProperty(DyFM_UsgAction_ControlModel, 'name', { value: 'DyFM_UsageAction' });
+/** @deprecated Use DyFM_UsgAction_ControlModel. Same constructor; no API removal. */
+export { DyFM_UsgAction_ControlModel as DyFM_UsageAction };

package/build-esm/_modules/usage/_models/usg-daily-usage-data.control-model.js

@@ -0,0 +1,30 @@
+/**
+ * Aggregated usage information for a specific day.
+ *
+ * @example
+ * ```ts
+ * const daily = new DyFM_UsgDailyUsageData_ControlModel({ date: '2024-07-20' });
+ * ```
+ */
+export class DyFM_UsgDailyUsageData_ControlModel {
+    /** ISO date string of the day */
+    date;
+    /** Total time spent on the site that day */
+    totalVisitTime = 0;
+    /** Average time of a single visit */
+    averageVisitTime = 0;
+    /** Number of visitors from Hungary */
+    visitorsHun = 0;
+    /** Number of visitors from other countries */
+    visitorsElse = 0;
+    /** Sessions belonging to the day */
+    visitations = [];
+    constructor(set) {
+        if (set) {
+            Object.assign(this, set);
+        }
+    }
+}
+Object.defineProperty(DyFM_UsgDailyUsageData_ControlModel, 'name', { value: 'DyFM_DailyUsageData' });
+/** @deprecated Use DyFM_UsgDailyUsageData_ControlModel. Same constructor; no API removal. */
+export { DyFM_UsgDailyUsageData_ControlModel as DyFM_DailyUsageData };

package/build-esm/_modules/usage/_models/usg-data.control-model.js

@@ -0,0 +1,30 @@
+/**
+ * Detailed usage information for a single page visit.
+ *
+ * @example
+ * ```ts
+ * const data = new DyFM_UsgData_ControlModel({
+ *   page: '/home',
+ *   opened: new Date(),
+ *   timeSpentOnPage: 120
+ * });
+ * ```
+ */
+export class DyFM_UsgData_ControlModel {
+    /** URL or identifier of the visited page */
+    page;
+    /** When the page was opened */
+    opened;
+    /** Time spent on the page in seconds */
+    timeSpentOnPage;
+    /** List of actions performed on the page */
+    actions = [];
+    constructor(set) {
+        if (set) {
+            Object.assign(this, set);
+        }
+    }
+}
+Object.defineProperty(DyFM_UsgData_ControlModel, 'name', { value: 'DyFM_UsageData' });
+/** @deprecated Use DyFM_UsgData_ControlModel. Same constructor; no API removal. */
+export { DyFM_UsgData_ControlModel as DyFM_UsageData };

package/build-esm/_modules/usage/_models/usg-session.data-model.js

@@ -0,0 +1,60 @@
+import { DyFM_DataModel_Params } from '../../../_models/control-models/data-model-params.control-model';
+import { DyFM_Metadata } from '../../../_models/data-models/metadata.data-model';
+/**
+ * Represents a user session including all tracked data.
+ *
+ * @example
+ * ```ts
+ * const session = new DyFM_UsgSession_DataModel({ sessionStart: new Date() });
+ * ```
+ */
+export class DyFM_UsgSession_DataModel extends DyFM_Metadata {
+    /** ISO date string of the session */
+    date;
+    /** Start time of the session */
+    sessionStart;
+    /** End time of the session */
+    sessionEnd;
+    /** IP address or identifier */
+    address;
+    /** Issuer of the session (e.g., user agent) */
+    issuer;
+    /** Geolocation data if available */
+    locationData;
+    /** Actions performed within the session */
+    usageData = [];
+    /** Total session time in seconds */
+    totalSessionTime;
+    /** Identifier of the logged in user */
+    loggedInAs;
+    constructor(set) {
+        super(set);
+        if (set) {
+            if (!set.date && set.sessionStart) {
+                set.date = set.sessionStart.toISOString().substring(0, 10);
+            }
+            Object.assign(this, set);
+        }
+    }
+}
+export const DyFM_usageSession_dataParams = new DyFM_DataModel_Params({
+    dataName: 'usage_session',
+    properties: {
+        date: { key: 'date', type: 'string',
+            required: true, index: true,
+        },
+        sessionStart: { key: 'sessionStart', type: 'Date',
+            required: true, index: true,
+        },
+        sessionEnd: { key: 'sessionEnd', type: 'Date' },
+        address: { key: 'address', type: 'string' },
+        issuer: { key: 'issuer', type: 'string' },
+        locationData: { key: 'locationData', type: 'IpApiLocation' },
+        usageData: { key: 'usageData', type: 'UsageData[]' },
+        totalSessionTime: { key: 'totalSessionTime', type: 'number' },
+        loggedInAs: { key: 'loggedInAs', type: 'string' },
+    },
+});
+Object.defineProperty(DyFM_UsgSession_DataModel, 'name', { value: 'DyFM_UsageSession' });
+/** @deprecated Use DyFM_UsgSession_DataModel. Same constructor; no API removal. */
+export { DyFM_UsgSession_DataModel as DyFM_UsageSession };

package/build-esm/_modules/usage/index.js

@@ -0,0 +1,7 @@
+// COLLECTIONS
+export * from './_collections/usg-module-settings.const';
+// MODELS
+export * from './_models/usg-session.data-model';
+export * from './_models/usg-data.control-model';
+export * from './_models/usg-daily-usage-data.control-model';
+export * from './_models/usg-action.control-model';

package/build-esm/index.js

@@ -0,0 +1,108 @@
+// COLLECTIONS
+// collections/CONSTANTS
+export * from './_collections/constants/data-sizes.const';
+export * from './_collections/constants/error-defaults.const';
+export * from './_collections/constants/global-settings.const';
+export * from './_collections/constants/numbers.const';
+export * from './_collections/constants/times.const';
+// collections/UTILS
+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/secret-mask.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';
+export * from './_collections/utils/time.util';
+export * from './_collections/utils/type-cloning-facility.util';
+export * from './_collections/utils/utilities.util';
+export * from './_collections/utils/operation-authz.util';
+export * from './_collections/utils/operation-guardrails.util';
+export * from './_collections/utils/operation-run.util';
+export * from './_collections/utils/operation-schema.util';
+export * from './_collections/utils/uuid.util';
+// collections/utils/MATH
+export * from './_collections/utils/math/box-bounds.util';
+export * from './_collections/utils/math/math.util';
+export * from './_collections/utils/math/random.util';
+export * from './_collections/utils/math/trigonometry.util';
+export * from './_collections/utils/math/vector2.util';
+//  collections/utils/REGEX
+export * from './_collections/utils/regex/password-regex.util';
+export * from './_collections/utils/regex/regex.util';
+export * from './_collections/utils/regex/username-regex.util';
+// ENUMS
+export * from './_enums/basic-property-type.enum';
+export * from './_enums/data-model-type.enum';
+export * from './_enums/environment-flag.enum';
+export * from './_enums/error-level.enum';
+export * from './_enums/error-status.enum';
+export * from './_enums/log-style.enum';
+export * from './_enums/operation-auth.type-enum';
+export * from './_enums/operation-if-match.type-enum';
+export * from './_enums/operation-patch-field.type-enum';
+export * from './_enums/server-connection-status.enum';
+// enums/HTTP
+export * from './_enums/http/http-call-type.enum';
+export * from './_enums/http/http-event-type.enum';
+export * from './_enums/http/http-response-type.enum';
+// enums/PIPE
+export * from './_enums/time/day-of-week.enum';
+export * from './_enums/time/month.enum';
+export * from './_enums/time/relative-date.enum';
+// MODELS
+// models/CONTROL MODELS
+export * from './_models/control-models/data-model-params.control-model';
+export * from './_models/control-models/data-model-settings.control-model';
+export * from './_models/control-models/data-property-params.control-model';
+export * from './_models/control-models/data-property-settings.control-model';
+export * from './_models/control-models/error.control-model';
+export * from './_models/control-models/operation-context.control-model';
+export * from './_models/control-models/operation-settings.control-model';
+export * from './_models/control-models/poll.control-model';
+export * from './_models/interfaces/poll-handle.interface';
+export * from './_models/control-models/range-value.control-model';
+export * from './_models/control-models/server-status.control-model';
+export * from './_models/control-models/service-endpoint-settings-base.control-model';
+export * from './_models/control-models/server-route-settings-base.control-model';
+// models/control-models/HTTP
+export * from './_models/control-models/http/http-error-response.control-model';
+export * from './_models/control-models/http/http-headers.control-model';
+export * from './_models/control-models/http/http-response.model-base';
+// models/DATA MODELS
+export * from './_models/data-models/errors.data-model';
+export * from './_models/data-models/metadata.data-model';
+// models/INTERFACES
+export * from './_models/interfaces/box-bounds.interface';
+export * from './_models/interfaces/error-defaults.interface';
+export * from './_models/interfaces/operation-authz-result.interface';
+export * from './_models/interfaces/operation-authz.interface';
+export * from './_models/interfaces/operation-run-result.interface';
+export * from './_models/interfaces/operation-exposure.interface';
+export * from './_models/interfaces/operation-guardrails.interface';
+export * from './_models/interfaces/operation-patch-field.interface';
+export * from './_models/interfaces/operation-patch-violation.interface';
+export * from './_models/interfaces/operation-input-settings.interface';
+export * from './_models/interfaces/operation-json-schema.interface';
+export * from './_models/interfaces/operation-patch-result.interface';
+export * from './_models/interfaces/paged.interface';
+export * from './_models/interfaces/random-weight.interface';
+export * from './_models/interfaces/route-settings.interface';
+export * from './_models/interfaces/search-query.interface';
+export * from './_models/interfaces/search-result.interface';
+export * from './_models/interfaces/server-error-statistics.interface';
+export * from './_models/interfaces/vector2.interface';
+// models/interfaces/ENVIRONMENT
+export * from './_models/interfaces/environment/global-log-settings.interface';
+export * from './_models/interfaces/environment/global-settings.interface';
+// models/TYPES
+export * from './_models/types/db-filter.type';
+export * from './_models/types/db-sort.type';
+export * from './_models/types/ds-filter.type';
+export * from './_models/types/ds-sort.type';