@futdevpro/fsm-dynamo 1.20.88 → 1.20.93

package/build-esm/_models/control-models/http/http-error-response.control-model.js

@@ -0,0 +1,48 @@
+import { DyFM_HttpResponseBase } from './http-response.model-base';
+export const DyFM_httpErrorResponse_name = 'HttpErrorResponse';
+/**
+ * A class that represents an HTTP error response.
+ *
+ * @example
+ * ```ts
+ * const errorResponse: DyFM_HttpErrorResponse_ControlModel = new DyFM_HttpErrorResponse_ControlModel({
+ *   status: 500,
+ *   statusText: 'Internal Server Error',
+ *   url: 'https://example.com/api/error',
+ *   error: new Error('Internal Server Error'),
+ * });
+ * ```
+ */
+export class DyFM_HttpErrorResponse_ControlModel extends DyFM_HttpResponseBase {
+    name = DyFM_httpErrorResponse_name;
+    message;
+    error;
+    /**
+     * Errors are never okay, even when the status code is in the 2xx success range.
+     */
+    ok = false;
+    constructor(set) {
+        super(set);
+        if (set) {
+            Object.assign(this, set);
+        }
+    }
+    /**
+     * Checks if the error is an HTTP error response.
+     * @param error - The error to check.
+     * @returns True if the error is an HTTP error response, false otherwise.
+     *
+     * @example
+     * ```ts
+     * const error: DyFM_AnyError = new Error('Internal Server Error');
+     * const isHttpErrorResponse: boolean = DyFM_HttpErrorResponse_ControlModel.isHttpErrorResponse(error);
+     * console.log(isHttpErrorResponse); // true
+     * ```
+     */
+    static isHttpErrorResponse(error) {
+        return error?.name === DyFM_httpErrorResponse_name;
+    }
+}
+Object.defineProperty(DyFM_HttpErrorResponse_ControlModel, 'name', { value: 'DyFM_HttpErrorResponse' });
+/** @deprecated Use DyFM_HttpErrorResponse_ControlModel. Same constructor; no API removal. */
+export { DyFM_HttpErrorResponse_ControlModel as DyFM_HttpErrorResponse };

package/build-esm/_models/control-models/http/http-headers.control-model.js

@@ -0,0 +1,43 @@
+/**
+ * Represents the header configuration options for an HTTP request.
+ * Instances are immutable. Modifying methods return a cloned
+ * instance with the change. The original object is never changed.
+ *
+ * @publicApi
+ *
+ * @example
+ * ```ts
+ * const headers: DyFM_HttpHeaders_ControlModel = new DyFM_HttpHeaders_ControlModel({
+ *   'Content-Type': 'application/json',
+ *   'Authorization': 'Bearer 1234567890',
+ * });
+ * ```
+ */
+export class DyFM_HttpHeaders_ControlModel {
+    /**
+     * Internal map of lowercase header names to values.
+     */
+    headers = {};
+    /**
+     * Internal map of lowercased header names to the normalized
+     * form of the name (the form seen first).
+     */
+    normalizedNames;
+    /**
+     * Complete the lazy initialization of this object (needed before reading).
+     */
+    lazyInit;
+    /**
+     * Queued updates to be materialized the next initialization.
+     */
+    lazyUpdate;
+    /**  Constructs a new HTTP header object with the given values.*/
+    constructor(setHeaders) {
+        if (setHeaders) {
+            this.headers = setHeaders;
+        }
+    }
+}
+Object.defineProperty(DyFM_HttpHeaders_ControlModel, 'name', { value: 'DyFM_HttpHeaders' });
+/** @deprecated Use DyFM_HttpHeaders_ControlModel. Same constructor; no API removal. */
+export { DyFM_HttpHeaders_ControlModel as DyFM_HttpHeaders };

package/build-esm/_models/control-models/http/http-response.model-base.js

@@ -0,0 +1,62 @@
+import { DyFM_HttpHeaders } from './http-headers.control-model';
+/**
+ * Base class for both `HttpResponse` and `HttpHeaderResponse`.
+ *
+ * @publicApi
+ *
+ * @example
+ * ```ts
+ * const response: DyFM_HttpResponseBase = new DyFM_HttpResponseBase({
+ *   status: 200,
+ *   statusText: 'OK',
+ *   url: 'https://example.com/api/response',
+ * });
+ * ```
+ */
+export class DyFM_HttpResponseBase {
+    /**
+     * All response headers.
+     */
+    headers = new DyFM_HttpHeaders();
+    /**
+     * Response status code.
+     */
+    status = 200;
+    /**
+     * Textual description of response status code, defaults to OK.
+     *
+     * Do not depend on this.
+     */
+    statusText = 'OK';
+    /**
+     * URL of the resource retrieved, or null if not available.
+     */
+    url;
+    /**
+     * Whether the status code falls in the 2xx range.
+     */
+    /** @deprecated Use isOk; ok remains the serialized compatibility key. */
+    ok;
+    /**
+     * Type of the response, narrowed to either the full response or the header.
+     */
+    type;
+    /**
+     * Super-constructor for all responses.
+     *
+     * The single parameter accepted is an initialization hash. Any properties
+     * of the response passed there will override the default values.
+     */
+    constructor(set) {
+        if (set) {
+            Object.assign(this, set);
+        }
+    }
+}
+Object.defineProperty(DyFM_HttpResponseBase.prototype, 'isOk', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.ok;
+    },
+});

package/build-esm/_models/control-models/operation-context.control-model.js

@@ -0,0 +1,110 @@
+import { DyFM_getConstructionStackLocation } from '../../_collections/utils/stack.util';
+import { DyFM_UUID } from '../../_collections/utils/uuid.util';
+import { DyFM_OperationAuth_Type } from '../../_enums/operation-auth.type-enum';
+import { DyFM_Error } from './error.control-model';
+/**
+ * Transport-independent context of ONE operation call (HP-DOPL MP-1.3).
+ *
+ * The REST, MCP and CLI adapters build this object from their own request shape, so the operation's
+ * `run(ctx, ...inputs)` never sees Express, JSON-RPC or commander objects.
+ *
+ * 🔴 `issuer` is ALWAYS the accountId, NEVER a user id (`fdp-issuer-is-account-id`). The service's own
+ * user id — the content-ownership identity — travels separately in `clientUserId`.
+ *
+ * @example
+ * ```ts
+ * const ctx: DyFM_Operation_Context = new DyFM_Operation_Context({
+ *   transport: 'mcp',
+ *   authKind: DyFM_OperationAuth_Type.apiKey,
+ *   issuer: accountId,
+ *   clientUserId: userId,
+ *   apiKeyScopes: [ 'task:read' ],
+ * });
+ * ```
+ */
+export class DyFM_OperationContext_ControlModel {
+    static {
+        Object.defineProperty(this, 'name', { value: 'DyFM_Operation_Context' });
+    }
+    /** Transport the call arrived on. */
+    transport;
+    /** How the caller authenticated (default: `none`). */
+    authKind;
+    /** The authenticated FDP accountId — never a user id. Required unless `authKind` is `none`. */
+    issuer;
+    /** The service's own user id of the caller (content ownership); resolved server-side, never from input. */
+    clientUserId;
+    /**
+     * Scopes granted to the API key. Only valid with `authKind: apiKey`.
+     * `undefined` marks a LEGACY key without scopes (full access with a warning, decision D-6);
+     * an empty array means the key grants nothing.
+     */
+    apiKeyScopes;
+    /** When `true`, the operation must validate and report, but not persist anything (default: `false`). */
+    dryRun;
+    /** Optimistic-concurrency token (etag) the caller expects the target to still have. */
+    ifMatch;
+    /** Correlation id of the call; generated when not given. */
+    requestId;
+    /**
+     * Validates the identity combination and applies the defaults.
+     * @param input - the call context; throws a coded `DyFM_Error` when the identity combination is invalid
+     */
+    constructor(input) {
+        const set = input ?? {};
+        // the construction location identifies the faulty adapter in the error
+        const stackLocation = DyFM_getConstructionStackLocation();
+        const authKind = set.authKind ?? DyFM_OperationAuth_Type.none;
+        // authKind must be a known value
+        if (!Object.values(DyFM_OperationAuth_Type).includes(authKind)) {
+            throw DyFM_OperationContext_ControlModel.invalid('DyFM-OPC-AUT', `unknown authKind (got: ${JSON.stringify(set.authKind)})`, stackLocation);
+        }
+        // transport must be one of the exposure keys
+        if (set.transport !== undefined && !['rest', 'mcp', 'cli'].includes(set.transport)) {
+            throw DyFM_OperationContext_ControlModel.invalid('DyFM-OPC-TRN', `unknown transport (got: ${JSON.stringify(set.transport)})`, stackLocation);
+        }
+        const authenticated = authKind !== DyFM_OperationAuth_Type.none;
+        // an authenticated call without an accountId is an adapter defect, not an anonymous call
+        if (authenticated && !DyFM_OperationContext_ControlModel.isFilled(set.issuer)) {
+            throw DyFM_OperationContext_ControlModel.invalid('DyFM-OPC-ISS', `authKind "${authKind}" requires the issuer (accountId)`, stackLocation);
+        }
+        // an anonymous call must not carry an identity
+        if (!authenticated && (set.issuer !== undefined || set.clientUserId !== undefined)) {
+            throw DyFM_OperationContext_ControlModel.invalid('DyFM-OPC-ANO', 'authKind "none" can not carry an issuer or a clientUserId', stackLocation);
+        }
+        // scopes belong to API keys only; every scope must be a non-empty string
+        if (set.apiKeyScopes !== undefined) {
+            if (authKind !== DyFM_OperationAuth_Type.apiKey) {
+                throw DyFM_OperationContext_ControlModel.invalid('DyFM-OPC-SCP', `apiKeyScopes are only valid with authKind "api-key" (got: "${authKind}")`, stackLocation);
+            }
+            if (!Array.isArray(set.apiKeyScopes) ||
+                !set.apiKeyScopes.every((scope) => DyFM_OperationContext_ControlModel.isFilled(scope))) {
+                throw DyFM_OperationContext_ControlModel.invalid('DyFM-OPC-SCP', 'apiKeyScopes must be an array of non-empty strings', stackLocation);
+            }
+        }
+        Object.assign(this, set);
+        this.authKind = authKind;
+        this.dryRun = set.dryRun === true;
+        this.requestId = DyFM_OperationContext_ControlModel.isFilled(set.requestId) ?
+            set.requestId : DyFM_UUID.generate();
+        // a copy, so a later mutation of the adapter's array can not widen the granted scopes
+        this.apiKeyScopes = set.apiKeyScopes ? [...set.apiKeyScopes] : undefined;
+    }
+    /** `true` when the call uses an API key created before scopes existed (legacy full access, D-6). */
+    static isLegacyApiKey(ctx) {
+        return ctx?.authKind === DyFM_OperationAuth_Type.apiKey && ctx.apiKeyScopes === undefined;
+    }
+    /** Checks for a non-blank string. */
+    static isFilled(value) {
+        return typeof value === 'string' && !!value.trim();
+    }
+    /** Builds the construction error with a stable error code and the construction location. */
+    static invalid(errorCode, reason, stackLocation) {
+        return new DyFM_Error({
+            errorCode: errorCode,
+            message: `DyFM_Operation_Context construction failed: ${reason}`,
+            additionalContent: { stackLocation: stackLocation },
+        });
+    }
+}
+export { DyFM_OperationContext_ControlModel as DyFM_Operation_Context };

package/build-esm/_models/control-models/operation-settings.control-model.js

@@ -0,0 +1,184 @@
+import { DyFM_getConstructionStackLocation } from '../../_collections/utils/stack.util';
+import { DyFM_BasicProperty_Type } from '../../_enums/basic-property-type.enum';
+import { DyFM_OperationIfMatch_Type } from '../../_enums/operation-if-match.type-enum';
+import { DyFM_OperationPatchField_Type } from '../../_enums/operation-patch-field.type-enum';
+import { DyFM_Error } from './error.control-model';
+/** Kebab-case segment: lowercase letters/digits, separated by single dashes. */
+const DyFM_operationKebabSegment = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** Input names must be usable as a route param, a JSON-schema key and a CLI option alike. */
+const DyFM_operationInputName = /^[a-zA-Z][a-zA-Z0-9]*$/;
+/**
+ * Validates ONE `guardrails.patchWhitelist` entry, in either accepted form.
+ *
+ * A plain string is the original form (changeable field, value not checked). A typed entry must carry a
+ * usable field name, a KNOWN type when it declares one, and a boolean `nullable` when it declares one —
+ * a misspelled type would otherwise silently disable the very check it was added for.
+ * @param entry - the whitelist entry as declared by the operation author
+ * @returns whether the entry is usable
+ */
+function DyFM_isValidPatchWhitelistEntry(entry) {
+    if (typeof entry === 'string')
+        return DyFM_operationInputName.test(entry);
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return false;
+    return (typeof entry.field === 'string' &&
+        DyFM_operationInputName.test(entry.field) &&
+        (entry.type === undefined || Object.values(DyFM_OperationPatchField_Type).includes(entry.type)) &&
+        (entry.nullable === undefined || typeof entry.nullable === 'boolean'));
+}
+/**
+ * Transport-independent description of ONE operation — the single source from which the REST
+ * endpoint, the MCP tool and the CLI command are derived (HP-DOPL, decision B+C).
+ *
+ * The class follows the Dynamo settings pattern (`DyFM_ServiceEndpointSettingsBase_ControlModel`):
+ * a `set` constructor, defaults applied in the constructor, and construction-time validation that
+ * fails fast with a debuggable `DyFM_Error`.
+ *
+ * ⚠️ Not related to the `operation-control` sub-module (durable operation leases): that module
+ * tracks the RUNTIME state of long-running work, this class DESCRIBES a callable operation.
+ *
+ * @example
+ * ```ts
+ * const setSchedule: DyFM_Operation_Settings<Task, [string], TaskSchedule> = new DyFM_Operation_Settings({
+ *   domain: 'task-views',
+ *   action: 'schedule.set',
+ *   description: 'Sets the schedule of a task view',
+ *   inputs: { taskId: { type: DyFM_BasicProperty_Type.string, required: true } },
+ *   expose: { cli: false },
+ * });
+ * // setSchedule.name === 'task-views.schedule.set'
+ * ```
+ */
+export class DyFM_OperationSettings_ControlModel {
+    static {
+        Object.defineProperty(this, 'name', { value: 'DyFM_Operation_Settings' });
+    }
+    /** Unique operation name; defaults to `${domain}.${action}`. */
+    name;
+    /** Owning domain, kebab-case (e.g. `task-views`). */
+    domain;
+    /** Action inside the domain: kebab-case segments joined by dots (e.g. `schedule.set`). */
+    action;
+    /** Required, human-readable description (CLI help, MCP tool description, REST docs). */
+    description;
+    /** Named inputs of the operation (default: none). */
+    inputs = {};
+    /** Data model of the request body, when the operation takes one. */
+    bodyParams;
+    /**
+     * The operation takes a request body WITHOUT a data model (e.g. the legacy default CRUD endpoints, whose
+     * data service owns the model). No input schema can be generated for such a body, so the operation must
+     * stay off the schema-driven transports: `expose.mcp` and `expose.cli` have to be `false`.
+     * Prefer `bodyParams` for new operations.
+     */
+    isBodyUntyped;
+    /** Transports the operation is exposed on; missing flags default to `true`. */
+    expose;
+    /** Declarative authorization; `issuerRequired` defaults to `true`. */
+    authz;
+    /** Write-safety guardrails; defaults: `ifMatch: none`, `dryRun: false`, `unknownPatchFields: drop`. */
+    guardrails;
+    /** Source location of the construction, for debugging duplicated or misconfigured operations. */
+    stackLocation;
+    /**
+     * Validates the settings, applies the defaults and records the construction location.
+     * @param set - the operation description; throws a coded `DyFM_Error` when it is invalid
+     */
+    constructor(set) {
+        // the construction location identifies the faulty definition in the error
+        const stackLocation = set?.stackLocation ?? DyFM_getConstructionStackLocation();
+        if (!set) {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-SET', 'settings object is missing', stackLocation);
+        }
+        const label = set.name ?? `${set.domain}.${set.action}`;
+        // domain: a single kebab-case segment
+        if (typeof set.domain !== 'string' || !DyFM_operationKebabSegment.test(set.domain)) {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-DOM', `domain must be a kebab-case segment (got: ${JSON.stringify(set.domain)}) (${label})`, stackLocation);
+        }
+        // action: dot-separated kebab-case segments
+        if (typeof set.action !== 'string' ||
+            !set.action.split('.').every((segment) => DyFM_operationKebabSegment.test(segment))) {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-ACT', `action must be dot-separated kebab-case segments (got: ${JSON.stringify(set.action)}) (${label})`, stackLocation);
+        }
+        // description: required, it becomes the CLI help and the MCP tool description
+        if (typeof set.description !== 'string' || !set.description.trim()) {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-DSC', `description is required (${label})`, stackLocation);
+        }
+        // name: when given, it must follow the same format as the generated default
+        if (set.name !== undefined && !DyFM_OperationSettings_ControlModel.isValidName(set.name)) {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-NAM', `name must be dot-separated kebab-case segments (got: ${JSON.stringify(set.name)})`, stackLocation);
+        }
+        // inputs: name and type validation
+        const inputs = set.inputs ?? {};
+        Object.entries(inputs).forEach(([inputName, input]) => {
+            if (!DyFM_operationInputName.test(inputName)) {
+                throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-INN', `input name must be alphanumeric camelCase (got: ${JSON.stringify(inputName)}) (${label})`, stackLocation);
+            }
+            if (!input ||
+                !Object.values(DyFM_BasicProperty_Type).includes(input.type) ||
+                input.type === DyFM_BasicProperty_Type.function) {
+                throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-INT', `input "${inputName}" has an invalid type (got: ${JSON.stringify(input?.type)}) (${label})`, stackLocation);
+            }
+        });
+        // authz: the declared fields must be usable, and ownership needs an authenticated caller
+        const authz = { issuerRequired: true, ...set.authz };
+        if ((authz.ownership !== undefined && !DyFM_operationInputName.test(authz.ownership)) ||
+            (authz.apiKeyScope !== undefined && (typeof authz.apiKeyScope !== 'string' || !authz.apiKeyScope.trim()))) {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-AZF', `authz.ownership must be a field name and authz.apiKeyScope a non-empty string (${label})`, stackLocation);
+        }
+        if (authz.ownership !== undefined && authz.issuerRequired === false) {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-AZO', `authz.ownership can not be combined with issuerRequired: false (${label})`, stackLocation);
+        }
+        // guardrails: known modes, and a whitelist of usable field names
+        const guardrails = {
+            ifMatch: DyFM_OperationIfMatch_Type.none, dryRun: false, unknownPatchFields: 'drop', ...set.guardrails,
+        };
+        if (!Object.values(DyFM_OperationIfMatch_Type).includes(guardrails.ifMatch ?? DyFM_OperationIfMatch_Type.none) ||
+            !['drop', 'reject'].includes(guardrails.unknownPatchFields ?? 'drop') ||
+            typeof guardrails.dryRun !== 'boolean' ||
+            (guardrails.patchWhitelist !== undefined && (!Array.isArray(guardrails.patchWhitelist) ||
+                !guardrails.patchWhitelist.length ||
+                !guardrails.patchWhitelist.every((entry) => DyFM_isValidPatchWhitelistEntry(entry))))) {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-GRD', `guardrails has an unknown mode or an invalid patchWhitelist (${label})`, stackLocation);
+        }
+        // isBodyUntyped: an alternative to bodyParams, and without a schema it can not be an MCP tool or CLI command
+        if (set.isBodyUntyped !== undefined && typeof set.isBodyUntyped !== 'boolean') {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-UBT', `isBodyUntyped must be a boolean (${label})`, stackLocation);
+        }
+        if (set.isBodyUntyped && set.bodyParams) {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-UBD', `an untyped body can not be combined with bodyParams (${label})`, stackLocation);
+        }
+        if (set.isBodyUntyped && (set.expose?.mcp !== false || set.expose?.cli !== false)) {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-UBX', `an operation with an untyped body has no input schema: set expose.mcp and expose.cli to false (${label})`, stackLocation);
+        }
+        // run: when given, it must be callable
+        if (set.run !== undefined && typeof set.run !== 'function') {
+            throw DyFM_OperationSettings_ControlModel.invalid('DyFM-OPS-RUN', `run must be a function (${label})`, stackLocation);
+        }
+        Object.assign(this, set);
+        this.domain = set.domain;
+        this.action = set.action;
+        this.description = set.description;
+        this.name = set.name ?? `${set.domain}.${set.action}`;
+        this.inputs = inputs;
+        // a missing expose flag means: exposed on that transport
+        this.expose = { rest: true, mcp: true, cli: true, ...set.expose };
+        this.authz = authz;
+        this.guardrails = guardrails;
+        this.stackLocation = stackLocation;
+    }
+    /** Checks the `name` format: dot-separated kebab-case segments. */
+    static isValidName(name) {
+        return typeof name === 'string' &&
+            name.split('.').every((segment) => DyFM_operationKebabSegment.test(segment));
+    }
+    /** Builds the construction error with a stable error code and the construction location. */
+    static invalid(errorCode, reason, stackLocation) {
+        return new DyFM_Error({
+            errorCode: errorCode,
+            message: `DyFM_Operation_Settings construction failed: ${reason}`,
+            additionalContent: { stackLocation: stackLocation },
+        });
+    }
+}
+export { DyFM_OperationSettings_ControlModel as DyFM_Operation_Settings };

package/build-esm/_models/control-models/poll.control-model.js

@@ -0,0 +1,202 @@
+import { second } from '../../_collections/constants/times.const';
+import { DyFM_Async } from '../../_collections/utils/async.util';
+import { DyFM_Error } from './error.control-model';
+/**
+ * DynamoFSM_Poll is a predefined class is
+ * for polling a specific endpoint
+ * waiting a specific result
+ *
+ * @example
+ * ```ts
+ * const poll: DyFM_Poll_ControlModel<string> = new DyFM_Poll_ControlModel({
+ *   name: 'My Poll',
+ *   pollDo: async () => {
+ *     return 'Poll result';
+ *   },
+ * });
+ * ```
+ */
+export class DyFM_Poll_ControlModel {
+    name;
+    /** The running poll (BFR-AM-019: a plain timer handle — no rxjs at runtime). */
+    poll;
+    /** @deprecated Use isRunning; running remains the serialized compatibility key. */
+    running;
+    /**
+     * The function that will be called to poll the endpoint,
+     * it will be called every pollPeriod
+     */
+    pollDo;
+    /**
+     * The function that will be called to check if the poll should continue,
+     * if this returns false, the poll will end
+     */
+    pollWhile;
+    /**
+     * The function that will be called to end the poll
+     */
+    pollEnd;
+    /**
+     * The function that will be called to handle the error
+     */
+    pollDoError;
+    args;
+    pollDelay = 0;
+    pollPeriod = 3 * second;
+    /** @deprecated Use isStopOnFail; stopOnFail remains the serialized compatibility key. */
+    stopOnFail = false;
+    /** @deprecated Use isDelayFirst; delayFirst remains the serialized compatibility key. */
+    delayFirst = false;
+    constructor(set) {
+        try {
+            Object.assign(this, set);
+            if (set.pollPeriod === 0) {
+                console.error('DYNAMO ERROR: creating polls with 0ms period is not supported! ' +
+                    '(it will reset to 1000ms (1s))');
+                this.pollPeriod = 1 * second;
+            }
+            if (this.pollPeriod < 300) {
+                console.warn('DYNAMO WARNING: creating polls with less than 300ms period is not recommended!');
+            }
+            this.name = set.name ?? 'Unnamed DyFM_Poll_ControlModel';
+            this.stopOnFail = set.stopOnFail;
+            this.startPoll(this.args);
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                message: 'DyFM_Poll_ControlModel construcion failed.'
+            });
+        }
+    }
+    /**
+     * The former `rxjs.timer(delay, period).subscribe(tick)`: the first tick after `delay` ms, then every `period` ms;
+     * a non-positive / missing period means ONE tick (as with `timer(delay)`). The tick is not awaited, as before.
+     */
+    static schedule(delay, period, tick) {
+        let timeout;
+        let interval;
+        let closed = false;
+        /** Runs one tick — a stopped poll never ticks again. */
+        const run = () => {
+            if (!closed) {
+                void tick();
+            }
+        };
+        timeout = setTimeout(() => {
+            timeout = undefined;
+            run();
+            if (!closed && typeof period === 'number' && period > 0) {
+                interval = setInterval(run, period);
+            }
+        }, delay ?? 0);
+        return {
+            get closed() {
+                return closed;
+            },
+            unsubscribe: () => {
+                closed = true;
+                if (timeout) {
+                    clearTimeout(timeout);
+                }
+                if (interval) {
+                    clearInterval(interval);
+                }
+            },
+        };
+    }
+    /**
+     * Starts the poll
+     * @param args - The arguments to pass to the pollDo function
+     */
+    async startPoll(...args) {
+        try {
+            if (this.delayFirst) {
+                await DyFM_Async.wait(this.pollDelay);
+            }
+            this.poll = DyFM_Poll_ControlModel.schedule(this.pollDelay, this.pollPeriod, async () => {
+                await this.pollDo(...args).then((res) => {
+                    if (!this.pollWhile(res)) {
+                        this.end(res);
+                    }
+                }).catch((error) => {
+                    if (this.stopOnFail) {
+                        this.stop();
+                    }
+                    if (this.pollDoError) {
+                        this.pollDoError(error);
+                    }
+                    else {
+                        throw new DyFM_Error({
+                            message: `DYNAMO ERROR: ` +
+                                `\nDynamoPoll: "${this.name}" pollDo was UNSUCCESSFUL`,
+                            error: error,
+                        });
+                    }
+                });
+            });
+            this.running = true;
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                message: 'DYNAMO ERROR: \nDynamoPoll: startPoll was UNSUCCESSFUL',
+                error: error,
+            });
+        }
+    }
+    /**
+     * Restarts the poll
+     * @param args - The arguments to pass to the pollDo function
+     */
+    restartPoll(args) {
+        try {
+            if (args) {
+                this.startPoll(args);
+            }
+            else {
+                this.startPoll(this.args);
+            }
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                message: 'DYNAMO ERROR: \nDynamoPoll: restartPoll was UNSUCCESSFUL',
+                error: error,
+            });
+        }
+    }
+    stop() {
+        this.poll.unsubscribe();
+        this.running = false;
+    }
+    end(result) {
+        this.poll.unsubscribe();
+        this.pollEnd?.(result);
+        this.running = false;
+    }
+}
+Object.defineProperty(DyFM_Poll_ControlModel, 'name', { value: 'DyFM_Poll' });
+/** @deprecated Use DyFM_Poll_ControlModel. Same constructor; no API removal. */
+export { DyFM_Poll_ControlModel as DyFM_Poll };
+Object.defineProperty(DyFM_Poll_ControlModel.prototype, 'isRunning', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.running;
+    },
+    set: function (isValue) {
+        this.running = isValue;
+    },
+});
+Object.defineProperty(DyFM_Poll_ControlModel.prototype, 'isStopOnFail', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.stopOnFail;
+    },
+});
+Object.defineProperty(DyFM_Poll_ControlModel.prototype, 'isDelayFirst', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.delayFirst;
+    },
+});