@emmvish/stable-request 2.5.0 → 2.6.1

package/README.md

@@ -12,6 +12,8 @@ A stability-first production-grade TypeScript framework for resilient API integr
   - [stableApiGateway](#stableapigateway)
   - [stableWorkflow](#stableworkflow)
   - [stableWorkflowGraph](#stableworkflowgraph)
+  - [StableScheduler](#stablescheduler)
+- [Stable Runner](#stable-runner)
 - [Resilience Mechanisms](#resilience-mechanisms)
   - [Retry Strategies](#retry-strategies)
   - [Circuit Breaker](#circuit-breaker)
@@ -53,8 +55,9 @@ A stability-first production-grade TypeScript framework for resilient API integr
 2. **Phased workflows** via `stableWorkflow` for array-based multi-phase execution with dynamic control flow
 3. **Graph-based workflows** via `stableWorkflowGraph` for DAG execution with higher parallelism
 4. **Generic function execution** via `stableFunction`, inheriting all resilience guards
+5. **Queue based scheduling** via `StableScheduler`, with option to preserve scheduler state and recover from saved state
 
-All five execution modes support the same resilience stack: retries, jitter, circuit breaking, caching, rate/concurrency limits, config cascading, shared buffers, trial mode, comprehensive hooks, and metrics. This uniformity makes it trivial to compose requests and functions in any topology.
+All six core modules support the same resilience stack: retries, jitter, circuit breaking, caching, rate/concurrency limits, config cascading, shared buffers, trial mode, comprehensive hooks, and metrics. This uniformity makes it trivial to compose requests and functions in any topology. Finally, `Stable Runner` executes jobs from config.
 
 ---
 
@@ -484,6 +487,21 @@ console.log(`Graph workflow success: ${result.success}`);
 - Provide deterministic execution order
 - Offer higher parallelism than phased workflows for complex topologies
 
+### StableScheduler
+
+Queue-based scheduler for cron/interval/timestamp execution with concurrency limits and recoverable state via custom persistence handlers.
+
+**Key responsibilities:**
+- Enforce max-parallel job execution
+- Schedule jobs with cron, interval, or timestamp(s)
+- Persist and restore scheduler state via user-provided handlers
+
+---
+
+## Stable Runner
+
+Config-driven runner that executes core module jobs from JSON/ESM configs and can use StableScheduler for scheduled jobs.
+
 ---
 
 ## Resilience Mechanisms

package/dist/core/index.d.ts

@@ -3,4 +3,5 @@ export { stableFunction } from './stable-function.js';
 export { stableApiGateway } from './stable-api-gateway.js';
 export { stableWorkflow } from './stable-workflow.js';
 export { stableWorkflowGraph } from './stable-workflow-graph.js';
+export { StableScheduler } from './stable-scheduler.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/core/index.js

@@ -3,4 +3,5 @@ export { stableFunction } from './stable-function.js';
 export { stableApiGateway } from './stable-api-gateway.js';
 export { stableWorkflow } from './stable-workflow.js';
 export { stableWorkflowGraph } from './stable-workflow-graph.js';
+export { StableScheduler } from './stable-scheduler.js';
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/core/stable-scheduler.d.ts

@@ -0,0 +1,54 @@
+import type { SchedulerConfig, SchedulerRetryConfig, SchedulerSchedule, SchedulerState, SchedulerJobHandler } from '../types/index.js';
+export declare class StableScheduler<TJob extends {
+    id?: string;
+    schedule?: SchedulerSchedule;
+    retry?: SchedulerRetryConfig;
+    executionTimeoutMs?: number;
+}> {
+    private readonly config;
+    private readonly handler;
+    private readonly jobs;
+    private readonly queue;
+    private readonly queued;
+    private timer;
+    private persistTimer;
+    private persistQueued;
+    private runningCount;
+    private completed;
+    private failed;
+    private dropped;
+    private sequence;
+    constructor(config: SchedulerConfig, handler: SchedulerJobHandler<TJob>);
+    addJobs(jobs: TJob[]): void;
+    setJobs(jobs: TJob[]): void;
+    addJob(job: TJob): string;
+    start(): void;
+    stop(): void;
+    tick(): void;
+    getStats(): {
+        queued: number;
+        running: number;
+        completed: number;
+        failed: number;
+        dropped: number;
+        totalJobs: number;
+    };
+    getState(): SchedulerState<TJob>;
+    restoreState(state?: SchedulerState<TJob>): Promise<boolean>;
+    private dispatch;
+    private getRetryConfig;
+    private getExecutionTimeoutMs;
+    private scheduleRetryIfEnabled;
+    private withTimeout;
+    private initializeSchedule;
+    private updateNextRun;
+    private parseTimestamp;
+    private getNextCronTime;
+    private parseCronField;
+    private isValidInteger;
+    private getCronDateParts;
+    private createId;
+    private generateUuid;
+    private persistStateIfEnabled;
+}
+//# sourceMappingURL=stable-scheduler.d.ts.map

package/dist/core/stable-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-scheduler.d.ts","sourceRoot":"","sources":["../../src/core/stable-scheduler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EAEpB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EAEpB,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,eAAe,CAC1B,IAAI,SAAS;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAAC,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE;IAErH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAarB;IACF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAK;gBAET,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC;IAkBvE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI;IAK3B,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI;IAc3B,MAAM,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM;IAqBzB,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;IAOZ,IAAI,IAAI,IAAI;IAiCZ,QAAQ;;;;;;;;IAWR,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC;IAuB1B,YAAY,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IA+ClE,OAAO,CAAC,QAAQ;IA8ChB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,sBAAsB;IAwB9B,OAAO,CAAC,WAAW;IAsBnB,OAAO,CAAC,kBAAkB;IAoC1B,OAAO,CAAC,aAAa;IA8BrB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,eAAe;IA+CvB,OAAO,CAAC,cAAc;IA6DtB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,gBAAgB;IAuExB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,YAAY;YAuBN,qBAAqB;CA0BpC"}

package/dist/core/stable-scheduler.js

@@ -0,0 +1,536 @@
+import { ScheduleTypes } from '../enums/index.js';
+export class StableScheduler {
+    config;
+    handler;
+    jobs = new Map();
+    queue = [];
+    queued = new Set();
+    timer = null;
+    persistTimer = null;
+    persistQueued = false;
+    runningCount = 0;
+    completed = 0;
+    failed = 0;
+    dropped = 0;
+    sequence = 0;
+    constructor(config, handler) {
+        this.config = {
+            maxParallel: config.maxParallel ?? 2,
+            tickIntervalMs: config.tickIntervalMs ?? 500,
+            queueLimit: config.queueLimit ?? 1000,
+            timezone: config.timezone,
+            persistence: {
+                enabled: config.persistence?.enabled ?? false,
+                saveState: config.persistence?.saveState,
+                loadState: config.persistence?.loadState
+            },
+            retry: config.retry,
+            executionTimeoutMs: config.executionTimeoutMs ?? 86400000,
+            persistenceDebounceMs: config.persistenceDebounceMs ?? 1000
+        };
+        this.handler = handler;
+    }
+    addJobs(jobs) {
+        jobs.forEach((job) => this.addJob(job));
+        void this.persistStateIfEnabled();
+    }
+    setJobs(jobs) {
+        this.stop();
+        this.jobs.clear();
+        this.queue.length = 0;
+        this.queued.clear();
+        this.runningCount = 0;
+        this.completed = 0;
+        this.failed = 0;
+        this.dropped = 0;
+        this.addJobs(jobs);
+        this.start();
+        void this.persistStateIfEnabled();
+    }
+    addJob(job) {
+        const id = job.id ?? this.createId('job');
+        const schedule = job.schedule;
+        const now = Date.now();
+        const { nextRunAt, runOnce, remainingTimestamps } = this.initializeSchedule(schedule, now);
+        const scheduledJob = {
+            id,
+            job: { ...job, id },
+            schedule,
+            nextRunAt,
+            lastRunAt: null,
+            remainingTimestamps,
+            runOnce,
+            isRunning: false,
+            retryAttempts: 0
+        };
+        this.jobs.set(id, scheduledJob);
+        void this.persistStateIfEnabled();
+        return id;
+    }
+    start() {
+        if (this.timer) {
+            return;
+        }
+        this.timer = setInterval(() => this.tick(), Math.max(50, this.config.tickIntervalMs));
+        this.tick();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    tick() {
+        const now = Date.now();
+        let stateChanged = false;
+        for (const [id, job] of this.jobs.entries()) {
+            if (job.isRunning || this.queued.has(id) || job.nextRunAt === null) {
+                continue;
+            }
+            if (job.nextRunAt <= now) {
+                if (this.queue.length >= this.config.queueLimit) {
+                    this.dropped += 1;
+                    continue;
+                }
+                this.queue.push(id);
+                this.queued.add(id);
+                stateChanged = true;
+            }
+        }
+        while (this.runningCount < this.config.maxParallel && this.queue.length > 0) {
+            const id = this.queue.shift();
+            if (!id)
+                break;
+            this.queued.delete(id);
+            const job = this.jobs.get(id);
+            if (!job)
+                continue;
+            this.dispatch(job);
+            stateChanged = true;
+        }
+        if (stateChanged) {
+            void this.persistStateIfEnabled();
+        }
+    }
+    getStats() {
+        return {
+            queued: this.queue.length,
+            running: this.runningCount,
+            completed: this.completed,
+            failed: this.failed,
+            dropped: this.dropped,
+            totalJobs: this.jobs.size
+        };
+    }
+    getState() {
+        return {
+            jobs: Array.from(this.jobs.values()).map((job) => ({
+                id: job.id,
+                job: job.job,
+                schedule: job.schedule,
+                nextRunAt: job.nextRunAt,
+                lastRunAt: job.lastRunAt,
+                remainingTimestamps: job.remainingTimestamps ? [...job.remainingTimestamps] : null,
+                runOnce: job.runOnce,
+                isRunning: job.isRunning,
+                retryAttempts: job.retryAttempts
+            })),
+            queue: [...this.queue],
+            stats: {
+                completed: this.completed,
+                failed: this.failed,
+                dropped: this.dropped,
+                sequence: this.sequence
+            }
+        };
+    }
+    async restoreState(state) {
+        let resolvedState = state;
+        if (!resolvedState && this.config.persistence.loadState) {
+            resolvedState = await this.config.persistence.loadState();
+        }
+        if (!resolvedState) {
+            return false;
+        }
+        this.stop();
+        this.jobs.clear();
+        this.queue.length = 0;
+        this.queued.clear();
+        this.runningCount = 0;
+        this.completed = resolvedState.stats.completed;
+        this.failed = resolvedState.stats.failed;
+        this.dropped = resolvedState.stats.dropped;
+        this.sequence = resolvedState.stats.sequence;
+        resolvedState.jobs.forEach((jobState) => {
+            const restored = {
+                id: jobState.id,
+                job: jobState.job,
+                schedule: jobState.schedule,
+                nextRunAt: jobState.nextRunAt,
+                lastRunAt: jobState.lastRunAt,
+                remainingTimestamps: jobState.remainingTimestamps ? [...jobState.remainingTimestamps] : null,
+                runOnce: jobState.runOnce,
+                isRunning: false,
+                retryAttempts: jobState.retryAttempts ?? 0
+            };
+            this.jobs.set(jobState.id, restored);
+        });
+        resolvedState.queue.forEach((id) => {
+            if (this.jobs.has(id)) {
+                this.queue.push(id);
+                this.queued.add(id);
+            }
+        });
+        this.tick();
+        void this.persistStateIfEnabled();
+        return true;
+    }
+    dispatch(job) {
+        this.runningCount += 1;
+        job.isRunning = true;
+        void this.persistStateIfEnabled();
+        const startedAt = Date.now();
+        const context = {
+            runId: this.createId('run'),
+            jobId: job.id,
+            scheduledAt: new Date(job.nextRunAt ?? startedAt).toISOString(),
+            startedAt: new Date(startedAt).toISOString(),
+            schedule: job.schedule
+        };
+        const retryConfig = this.getRetryConfig(job);
+        if (retryConfig) {
+            job.retryAttempts += 1;
+        }
+        let jobError = null;
+        const handlerPromise = this.handler(job.job, context);
+        const executionPromise = this.withTimeout(handlerPromise, this.getExecutionTimeoutMs(job));
+        void executionPromise
+            .then(() => {
+            this.completed += 1;
+            job.retryAttempts = 0;
+        })
+            .catch((error) => {
+            this.failed += 1;
+            jobError = error;
+        })
+            .finally(() => {
+            const scheduledRetry = this.scheduleRetryIfEnabled(job, startedAt, jobError);
+            job.isRunning = false;
+            job.lastRunAt = startedAt;
+            this.runningCount -= 1;
+            if (!scheduledRetry) {
+                job.retryAttempts = 0;
+                this.updateNextRun(job, startedAt);
+            }
+            this.tick();
+            void this.persistStateIfEnabled();
+        });
+    }
+    getRetryConfig(job) {
+        return job.job.retry ?? this.config.retry;
+    }
+    getExecutionTimeoutMs(job) {
+        return job.job.executionTimeoutMs ?? this.config.executionTimeoutMs;
+    }
+    scheduleRetryIfEnabled(job, startedAt, error) {
+        if (!error) {
+            return false;
+        }
+        const retryConfig = this.getRetryConfig(job);
+        if (!retryConfig) {
+            return false;
+        }
+        const maxAttempts = retryConfig.maxAttempts ?? 1;
+        if (maxAttempts <= 1 || job.retryAttempts >= maxAttempts) {
+            return false;
+        }
+        const baseDelay = retryConfig.delayMs ?? 1000;
+        const backoff = retryConfig.backoffMultiplier ?? 1;
+        const calculatedDelay = baseDelay * Math.pow(backoff, Math.max(job.retryAttempts - 1, 0));
+        const delay = retryConfig.maxDelayMs ? Math.min(calculatedDelay, retryConfig.maxDelayMs) : calculatedDelay;
+        job.nextRunAt = startedAt + Math.max(0, delay);
+        return true;
+    }
+    withTimeout(promise, timeoutMs) {
+        if (!timeoutMs || timeoutMs <= 0) {
+            return promise;
+        }
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new Error(`Scheduler job timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            promise
+                .then((value) => {
+                clearTimeout(timeoutId);
+                resolve(value);
+            })
+                .catch((error) => {
+                clearTimeout(timeoutId);
+                reject(error);
+            });
+        });
+    }
+    initializeSchedule(schedule, now) {
+        if (!schedule) {
+            return { nextRunAt: now, runOnce: true, remainingTimestamps: null };
+        }
+        if (schedule.type === ScheduleTypes.INTERVAL) {
+            const startAt = this.parseTimestamp(schedule.startAt);
+            if (startAt !== null && startAt > now) {
+                return { nextRunAt: startAt, runOnce: false, remainingTimestamps: null };
+            }
+            return { nextRunAt: now, runOnce: false, remainingTimestamps: null };
+        }
+        if (schedule.type === ScheduleTypes.CRON) {
+            const nextRunAt = this.getNextCronTime(schedule.expression, now, schedule.timezone);
+            return { nextRunAt, runOnce: false, remainingTimestamps: null };
+        }
+        if (schedule.type === ScheduleTypes.TIMESTAMP) {
+            const at = this.parseTimestamp(schedule.at);
+            return { nextRunAt: at, runOnce: true, remainingTimestamps: null };
+        }
+        const timestamps = schedule.at
+            .map((value) => this.parseTimestamp(value))
+            .filter((value) => value !== null)
+            .sort((a, b) => a - b);
+        const nextRunAt = timestamps.length > 0 ? timestamps[0] : null;
+        return { nextRunAt, runOnce: false, remainingTimestamps: timestamps };
+    }
+    updateNextRun(job, lastRunAt) {
+        const schedule = job.schedule;
+        if (!schedule) {
+            job.nextRunAt = job.runOnce ? null : lastRunAt;
+            return;
+        }
+        if (schedule.type === ScheduleTypes.INTERVAL) {
+            job.nextRunAt = lastRunAt + schedule.everyMs;
+            return;
+        }
+        if (schedule.type === ScheduleTypes.CRON) {
+            job.nextRunAt = this.getNextCronTime(schedule.expression, lastRunAt, schedule.timezone);
+            return;
+        }
+        if (schedule.type === ScheduleTypes.TIMESTAMP) {
+            job.nextRunAt = null;
+            return;
+        }
+        const remaining = job.remainingTimestamps ?? [];
+        while (remaining.length > 0 && remaining[0] <= lastRunAt) {
+            remaining.shift();
+        }
+        job.remainingTimestamps = remaining;
+        job.nextRunAt = remaining.length > 0 ? remaining[0] : null;
+    }
+    parseTimestamp(value) {
+        if (typeof value === 'number') {
+            return Number.isFinite(value) ? value : null;
+        }
+        if (typeof value === 'string') {
+            const parsed = Date.parse(value);
+            return Number.isNaN(parsed) ? null : parsed;
+        }
+        return null;
+    }
+    getNextCronTime(expression, fromMs, timezone) {
+        const fields = expression.trim().split(/\s+/);
+        if (fields.length < 5 || fields.length > 6) {
+            return null;
+        }
+        const hasSeconds = fields.length === 6;
+        const [secField, minField, hourField, dayField, monthField, dowField] = hasSeconds
+            ? fields
+            : ['0', ...fields];
+        const seconds = this.parseCronField(secField, 0, 59, true);
+        const minutes = this.parseCronField(minField, 0, 59, true);
+        const hours = this.parseCronField(hourField, 0, 23, true);
+        const days = this.parseCronField(dayField, 1, 31, true);
+        const months = this.parseCronField(monthField, 1, 12, true);
+        const dows = this.parseCronField(dowField, 0, 6, true);
+        if (!seconds || !minutes || !hours || !days || !months || !dows) {
+            return null;
+        }
+        const maxIterations = 366 * 24 * 60 * 60;
+        let candidate = new Date(fromMs + 1000);
+        for (let i = 0; i < maxIterations; i += 1) {
+            const candidateDate = candidate;
+            const parts = this.getCronDateParts(candidateDate, timezone);
+            if (!parts) {
+                return null;
+            }
+            const match = seconds.has(parts.second) &&
+                minutes.has(parts.minute) &&
+                hours.has(parts.hour) &&
+                days.has(parts.day) &&
+                months.has(parts.month) &&
+                dows.has(parts.dow);
+            if (match) {
+                return candidateDate.getTime();
+            }
+            candidate = new Date(candidateDate.getTime() + 1000);
+        }
+        return null;
+    }
+    parseCronField(field, min, max, strict) {
+        const values = new Set();
+        const segments = field.split(',');
+        let hasValidSegment = false;
+        segments.forEach((segment) => {
+            const trimmed = segment.trim();
+            if (!trimmed)
+                return;
+            const [rangePart, stepPart] = trimmed.split('/');
+            if (stepPart !== undefined && !this.isValidInteger(stepPart)) {
+                return;
+            }
+            const step = stepPart ? Number(stepPart) : 1;
+            const safeStep = Number.isFinite(step) && step > 0 ? step : null;
+            if (!safeStep) {
+                return;
+            }
+            let rangeStart;
+            let rangeEnd;
+            if (rangePart === '*') {
+                rangeStart = min;
+                rangeEnd = max;
+            }
+            else if (rangePart.includes('-')) {
+                const [startRaw, endRaw] = rangePart.split('-');
+                if (!this.isValidInteger(startRaw) || !this.isValidInteger(endRaw)) {
+                    return;
+                }
+                rangeStart = Number(startRaw);
+                rangeEnd = Number(endRaw);
+            }
+            else {
+                if (!this.isValidInteger(rangePart)) {
+                    return;
+                }
+                rangeStart = Number(rangePart);
+                rangeEnd = rangeStart;
+            }
+            if (rangeStart < min || rangeEnd > max || rangeStart > rangeEnd) {
+                return;
+            }
+            for (let value = rangeStart; value <= rangeEnd; value += safeStep) {
+                values.add(value);
+            }
+            hasValidSegment = true;
+        });
+        if (values.size === 0) {
+            if (strict) {
+                return null;
+            }
+            for (let value = min; value <= max; value += 1) {
+                values.add(value);
+            }
+        }
+        return values;
+    }
+    isValidInteger(value) {
+        return /^\d+$/.test(value);
+    }
+    getCronDateParts(date, timezone) {
+        if (!timezone) {
+            return {
+                second: date.getSeconds(),
+                minute: date.getMinutes(),
+                hour: date.getHours(),
+                day: date.getDate(),
+                month: date.getMonth() + 1,
+                dow: date.getDay()
+            };
+        }
+        try {
+            const formatter = new Intl.DateTimeFormat('en-US', {
+                timeZone: timezone,
+                hour12: false,
+                weekday: 'short',
+                year: 'numeric',
+                month: '2-digit',
+                day: '2-digit',
+                hour: '2-digit',
+                minute: '2-digit',
+                second: '2-digit'
+            });
+            const parts = formatter.formatToParts(date);
+            const partMap = new Map(parts.map((part) => [part.type, part.value]));
+            const month = Number(partMap.get('month'));
+            const day = Number(partMap.get('day'));
+            const hour = Number(partMap.get('hour'));
+            const minute = Number(partMap.get('minute'));
+            const second = Number(partMap.get('second'));
+            const weekday = partMap.get('weekday');
+            if (Number.isNaN(month) ||
+                Number.isNaN(day) ||
+                Number.isNaN(hour) ||
+                Number.isNaN(minute) ||
+                Number.isNaN(second) ||
+                !weekday) {
+                return null;
+            }
+            const weekdayIndex = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(weekday);
+            if (weekdayIndex === -1) {
+                return null;
+            }
+            return {
+                second,
+                minute,
+                hour,
+                day,
+                month,
+                dow: weekdayIndex
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    createId(prefix) {
+        return `${prefix}-${this.generateUuid()}-${Date.now()}`;
+    }
+    generateUuid() {
+        if (typeof globalThis.crypto?.randomUUID === 'function') {
+            return globalThis.crypto.randomUUID();
+        }
+        const bytes = new Uint8Array(16);
+        if (typeof globalThis.crypto?.getRandomValues === 'function') {
+            globalThis.crypto.getRandomValues(bytes);
+        }
+        else {
+            for (let i = 0; i < bytes.length; i += 1) {
+                bytes[i] = Math.floor(Math.random() * 256);
+            }
+        }
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0'));
+        return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex
+            .slice(6, 8)
+            .join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10, 16).join('')}`;
+    }
+    async persistStateIfEnabled() {
+        if (!this.config.persistence.enabled || !this.config.persistence.saveState) {
+            return;
+        }
+        const debounceMs = this.config.persistenceDebounceMs ?? 0;
+        if (debounceMs > 0) {
+            if (this.persistTimer) {
+                this.persistQueued = true;
+                return;
+            }
+            this.persistQueued = false;
+            this.persistTimer = setTimeout(async () => {
+                this.persistTimer = null;
+                const state = this.getState();
+                await this.config.persistence.saveState?.(state);
+                if (this.persistQueued) {
+                    void this.persistStateIfEnabled();
+                }
+            }, debounceMs);
+            return;
+        }
+        const state = this.getState();
+        await this.config.persistence.saveState(state);
+    }
+}
+//# sourceMappingURL=stable-scheduler.js.map