nvent 0.4.5 → 0.5.0

package/dist/runtime/scheduler/index.js

@@ -0,0 +1,38 @@
+import { Scheduler } from "./scheduler.js";
+import { useRuntimeConfig } from "#imports";
+let schedulerInstance = null;
+export function createScheduler(store) {
+  const config = useRuntimeConfig();
+  const prefix = config.nvent.store?.prefix || "nvent";
+  const useIndexLocking = !!(store.indexAdd && store.index.get);
+  return new Scheduler({
+    store,
+    keyPrefix: `${prefix}:scheduler`,
+    lockTTL: 3e5,
+    // 5 minutes
+    useIndexLocking
+  });
+}
+export function useScheduler() {
+  if (!schedulerInstance) {
+    throw new Error("Scheduler not initialized. Call initializeScheduler() first.");
+  }
+  return schedulerInstance;
+}
+export async function initializeScheduler(store) {
+  if (schedulerInstance) {
+    return schedulerInstance;
+  }
+  schedulerInstance = createScheduler(store);
+  await schedulerInstance.start();
+  return schedulerInstance;
+}
+export async function shutdownScheduler() {
+  if (schedulerInstance) {
+    await schedulerInstance.stop();
+    schedulerInstance = null;
+  }
+}
+export function resetScheduler() {
+  schedulerInstance = null;
+}

package/dist/runtime/scheduler/scheduler.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Scheduler
+ *
+ * Store-based scheduler with distributed locking for horizontal scaling.
+ * Ensures only one instance executes each scheduled job.
+ */
+import type { ScheduledJob, SchedulerAdapter } from './types.js';
+import type { StoreAdapter } from '../adapters/interfaces/store.js';
+export interface SchedulerOptions {
+    /**
+     * Store adapter for locking (Redis recommended)
+     */
+    store: StoreAdapter;
+    /**
+     * Key prefix for locks and job data
+     * Uses configured store prefix + ':scheduler'
+     * @default '{prefix}:scheduler' (e.g., 'nvent:scheduler')
+     */
+    keyPrefix?: string;
+    /**
+     * Lock TTL in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    lockTTL?: number;
+    /**
+     * Unique instance identifier
+     * @default Auto-generated
+     */
+    instanceId?: string;
+    /**
+     * Use store indexes for locking (more robust) vs simple KV
+     * @default true
+     */
+    useIndexLocking?: boolean;
+}
+export declare class Scheduler implements SchedulerAdapter {
+    private store;
+    private keyPrefix;
+    private lockTTL;
+    private instanceId;
+    private useIndexLocking;
+    private jobs;
+    private jobConfigs;
+    private lockRenewalTimers;
+    private started;
+    private logger;
+    constructor(options: SchedulerOptions);
+    schedule(job: ScheduledJob): Promise<string>;
+    /**
+     * Execute job with distributed lock
+     * Prevents multiple instances from running the same job
+     */
+    private executeWithLock;
+    private executeJob;
+    /**
+     * Acquire distributed lock using store adapter
+     */
+    private acquireLock;
+    /**
+     * Release distributed lock
+     */
+    private releaseLock;
+    /**
+     * Start periodic lock renewal (for long-running jobs)
+     */
+    private startLockRenewal;
+    /**
+     * Stop lock renewal
+     */
+    private stopLockRenewal;
+    /**
+     * Persist job configuration
+     */
+    private persistJob;
+    /**
+     * Update job statistics
+     */
+    private updateJobStats;
+    unschedule(jobId: string): Promise<boolean>;
+    /**
+     * Recover jobs from store on startup
+     * Critical for:
+     * - Restarts: Re-create in-memory schedulers
+     * - Horizontal scaling: New instances pick up existing jobs
+     * - Orphaned awaits: Resume flows waiting on schedules
+     */
+    private recoverJobs;
+    /**
+     * Recover a single job from persisted data
+     *
+     * IMPORTANT: This method reconstructs in-memory schedulers (CronJob/setInterval)
+     * WITHOUT calling schedule() to avoid re-persisting handler functions (which
+     * cannot be serialized). Handlers are reconstructed from metadata where possible.
+     */
+    private recoverJob;
+    /**
+     * Recover well-known job patterns when index scan is not available
+     * This includes:
+     * - stall-detection (always exists)
+     * - await-time-* (flows waiting on time delays)
+     * - await-schedule-* (flows waiting on cron schedules)
+     */
+    private recoverWellKnownJobs;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getScheduledJobs(): Promise<ScheduledJob[]>;
+    /**
+     * Get all persisted jobs from store (for debugging/monitoring)
+     * This shows ALL jobs across ALL instances with their runtime stats
+     */
+    getAllPersistedJobs(): Promise<ScheduledJob[]>;
+    isHealthy(): Promise<boolean>;
+}