cron-safe

A robust wrapper around node-cron with automatic retries, overlap prevention, distributed locking, concurrency control, execution timeout, history tracking, metrics, persistent storage, and structured error handling.

Why cron-safe?

Standard node-cron jobs are vulnerable to:

• ❌ Silent failures — A network glitch fails a task, and it won't retry until the next schedule (potentially hours later)
• ❌ Overlapping executions — Long-running tasks stack up, causing memory leaks or data corruption
• ❌ Zombie tasks — Hanging tasks that never complete block all future executions
• ❌ No visibility — No way to see when tasks last ran or if they're currently running
• ❌ Unhandled rejections — Async errors crash your process or go unnoticed
• ❌ Duplicate runs — In multi-instance deployments, the same job runs on every server
• ❌ No persistence — History and retry state lost after restart

cron-safe wraps your tasks with a protective layer:

• ✅ Automatic retries with configurable delays
• ✅ Exponential/linear backoff — smart retry delays that grow over time
• ✅ Overlap prevention — ensures only one instance runs at a time
• ✅ Distributed locking — ensures only one instance runs across multiple servers (Redis, etc.)
• ✅ Concurrency control — allow N parallel executions with maxConcurrency
• ✅ Execution timeout — kills zombie tasks that run too long
• ✅ Execution history — audit log of past runs with status and duration
• ✅ Persistent storage — save history to database, survive restarts
• ✅ Metrics & observability — track runs, failures, avg duration, export to Prometheus/OpenTelemetry
• ✅ Dynamic schedule update — change cron expression at runtime without restart
• ✅ Next run predictor — know exactly when your job runs next
• ✅ Async trigger — manually trigger tasks and await results
• ✅ Notification hooks — integrate with Slack, email, or any notification system
• ✅ Lifecycle hooks — onStart, onSuccess, onRetry, onError, onTimeout

Installation

npm install cron-safe node-cron

Note: node-cron is a peer dependency. You must install it separately.

Quick Start

import { schedule } from 'cron-safe';

// Simple scheduled task
const task = schedule('*/5 * * * *', async () => {
  const data = await fetchDataFromAPI();
  await saveToDatabase(data);
  return data; // Return value available via trigger()
});

// Stop when needed
task.stop();

Features

Automatic Retries

import { schedule } from 'cron-safe';

const task = schedule('0 * * * *', async () => {
  await unreliableApiCall();
}, {
  retries: 3,        // Retry up to 3 times
  retryDelay: 5000,  // Wait 5 seconds between retries
  
  onRetry: (error, attempt) => {
    console.log(`Attempt ${attempt} failed:`, error.message);
  },
  
  onError: (error) => {
    // Called after all retries are exhausted
    alertOpsTeam('Critical task failed!', error);
  },
});

Exponential & Linear Backoff

Smart retry delays that grow over time, preventing thundering herd problems:

import { schedule } from 'cron-safe';

const task = schedule('0 * * * *', async () => {
  await unreliableApiCall();
}, {
  retries: 5,
  retryDelay: 1000,           // Base delay: 1 second
  backoffStrategy: 'exponential',  // 2s, 4s, 8s, 16s, 32s
  maxRetryDelay: 30000,       // Cap at 30 seconds
  
  onRetry: (error, attempt) => {
    console.log(`Retry ${attempt}, next delay will be longer...`);
  },
});

// Available strategies:
// - 'fixed': Same delay every time (default)
// - 'linear': delay * attempt (1s, 2s, 3s, 4s, 5s)
// - 'exponential': delay * 2^attempt (2s, 4s, 8s, 16s, 32s)

Overlap Prevention

import { schedule } from 'cron-safe';

// This task runs every minute but might take 90 seconds
const task = schedule('* * * * *', async () => {
  await longRunningDataSync();  // Takes ~90 seconds
}, {
  preventOverlap: true,  // Skip if previous run still executing
  
  onOverlapSkip: () => {
    console.log('Skipped: previous execution still running');
  },
});

Concurrency Control

Allow limited parallel executions instead of binary overlap prevention:

import { schedule } from 'cron-safe';

// Allow up to 3 concurrent executions
const task = schedule('* * * * *', async () => {
  await processQueue();
}, {
  maxConcurrency: 3,  // Allow 3 parallel runs

  onOverlapSkip: () => {
    console.log('Max concurrency reached, skipping');
  },
});

When both preventOverlap and maxConcurrency are set, maxConcurrency takes priority. Setting maxConcurrency: 1 is equivalent to preventOverlap: true.

Distributed Locking

Ensure only one instance runs across multiple servers (Docker, PM2 cluster, auto-scaling):

import { schedule, LockProvider } from 'cron-safe';

// Implement the LockProvider interface for your lock backend
const redisLockProvider: LockProvider = {
  async acquire(key: string, ttl: number): Promise<string | null> {
    // SET key uniqueId NX PX ttl
    const lockId = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
    const result = await redis.set(key, lockId, 'PX', ttl, 'NX');
    return result === 'OK' ? lockId : null;
  },

  async release(key: string, lockId: string): Promise<void> {
    // Only release if we still own the lock
    const currentId = await redis.get(key);
    if (currentId === lockId) {
      await redis.del(key);
    }
  },

  async extend(key: string, lockId: string, ttl: number): Promise<boolean> {
    const currentId = await redis.get(key);
    if (currentId === lockId) {
      await redis.pexpire(key, ttl);
      return true;
    }
    return false;
  },
};

const task = schedule('0 * * * *', async () => {
  await processOrders();
}, {
  name: 'order-processor',
  distributedLock: {
    provider: redisLockProvider,
    ttl: 120000,        // Lock expires after 2 minutes
    autoExtend: true,   // Auto-extend lock for long-running tasks
    extendInterval: 60000, // Extend every 60 seconds
  },
});

The lock is automatically released after task completion (success or failure). If the process crashes, the TTL ensures the lock eventually expires as a safety net.

Persistent Storage

Save execution history to a database so data survives restarts and crashes:

import { schedule, StorageAdapter, StoredRunRecord } from 'cron-safe';

// Implement the StorageAdapter interface for your database
const postgresAdapter: StorageAdapter = {
  async saveRun(record: StoredRunRecord) {
    await db.query('INSERT INTO cron_runs ...', record);
  },

  async updateRun(taskName: string, startedAt: string, updates: Partial<StoredRunRecord>) {
    await db.query('UPDATE cron_runs SET ... WHERE task_name = $1 AND started_at = $2', ...);
  },

  async getRuns(taskName: string, limit: number) {
    return db.query('SELECT * FROM cron_runs WHERE task_name = $1 ORDER BY started_at DESC LIMIT $2', taskName, limit);
  },

  async getLastIncompleteRun(taskName: string) {
    return db.query("SELECT * FROM cron_runs WHERE task_name = $1 AND status = 'running' ORDER BY started_at DESC LIMIT 1", taskName);
  },
};

const task = schedule('0 * * * *', async () => {
  await generateReport();
}, {
  name: 'hourly-report',
  storage: postgresAdapter,
  historyLimit: 100,
});

On startup, cron-safe automatically loads the last N history records from storage, preserving your audit trail across restarts.

Metrics & Observability

Track task performance in real-time:

import { schedule } from 'cron-safe';

const task = schedule('* * * * *', async () => {
  await processData();
}, {
  name: 'data-processor',
});

// Get metrics snapshot
const metrics = task.getMetrics();
console.log(metrics);
// {
//   totalRuns: 150,
//   totalSuccess: 145,
//   totalFailures: 3,
//   totalTimeouts: 2,
//   totalRetries: 10,
//   totalOverlapSkips: 5,
//   currentRunning: 1,
//   avgDuration: 2340,    // ms
//   lastRunAt: Date,
//   lastStatus: 'success'
// }

Export to Prometheus / OpenTelemetry

import { schedule, MetricsProvider } from 'cron-safe';

const prometheusMetrics: MetricsProvider = {
  recordEvent(taskName, event, duration) {
    // Forward to your metrics system
    cronRunsTotal.labels(taskName, event).inc();
    if (duration) {
      cronDurationHistogram.labels(taskName).observe(duration / 1000);
    }
  },
};

const task = schedule('* * * * *', processData, {
  name: 'data-processor',
  metricsProvider: prometheusMetrics,
});

Dynamic Schedule Update

Change the cron expression at runtime without losing state:

import { schedule } from 'cron-safe';

const task = schedule('*/5 * * * *', async () => {
  await syncData();
}, {
  name: 'data-sync',
});

// Later, update schedule via admin dashboard or feature flag
task.updateSchedule('*/30 * * * *');  // Slow down to every 30 minutes

// All history, metrics, and state are preserved
console.log(task.getHistory().length);  // Still has previous history
console.log(task.getMetrics());         // Still has accumulated metrics

Throws an error if the new cron expression is invalid. The task must not be stopped when updating.

Execution Timeout (Safety Valve)

Prevent zombie tasks from blocking future executions:

import { schedule, TimeoutError } from 'cron-safe';

const task = schedule('*/5 * * * *', async () => {
  await potentiallyHangingOperation();
}, {
  executionTimeout: 30000,  // 30 second timeout
  
  onTimeout: (error) => {
    console.error('Task timed out!', error.message);
    // error instanceof TimeoutError === true
  },
});

Execution History (Audit Log)

Track past executions with status, duration, and errors:

import { schedule } from 'cron-safe';

const task = schedule('0 * * * *', async () => {
  return await generateReport();
}, {
  historyLimit: 20,  // Keep last 20 executions (default: 10)
});

// Check execution history
const history = task.getHistory();
console.log(history);
// [
//   {
//     startedAt: Date,
//     endedAt: Date,
//     duration: 1234,  // ms
//     status: 'success' | 'failed' | 'timeout',
//     error?: Error,
//     triggeredBy: 'schedule' | 'manual'
//   },
//   ...
// ]

// Find failed executions
const failures = history.filter(h => h.status === 'failed');

Next Run Predictor

Know exactly when your job runs next:

import { schedule } from 'cron-safe';

const task = schedule('0 9 * * *', async () => {
  await sendDailyDigest();
});

const nextRun = task.nextRun();
console.log(`Next run: ${nextRun}`);  // Date object or null if stopped

// Show in UI
const timeUntilNext = nextRun.getTime() - Date.now();
console.log(`Next backup in ${Math.round(timeUntilNext / 60000)} minutes`);

Async Trigger with Results

Manually trigger tasks and get results (great for testing):

import { schedule } from 'cron-safe';

const task = schedule('0 0 * * *', async () => {
  const report = await generateDailyReport();
  return report;  // Return the result
});

// Manual trigger returns the result
const result = await task.trigger();
console.log('Report:', result);

// Respects overlap prevention
// If preventOverlap is true and task is running, returns undefined

Notification Hooks

Integrate with Slack, email, or any notification system. The notifier callback receives structured payloads when events occur:

import { schedule, NotificationPayload } from 'cron-safe';

const task = schedule('0 * * * *', async () => {
  await processData();
}, {
  name: 'hourly-processor',
  notifier: (payload: NotificationPayload) => {
    console.log(`[${payload.taskName}] ${payload.event} at ${payload.timestamp}`);
    // payload.result - for success events
    // payload.error - for error/timeout events
    // payload.duration - execution time in ms
    // payload.attemptsMade - number of attempts
  },
  notifyOn: {
    success: true,      // default: true
    error: true,        // default: true
    timeout: true,      // default: true
    overlapSkip: false,  // default: false
    lockFailed: false,   // default: false
  },
});

Slack Webhook Adapter

import { schedule, NotificationPayload } from 'cron-safe';

const slackNotifier = async (payload: NotificationPayload) => {
  const color = payload.event === 'success' ? 'good' : 'danger';
  
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      attachments: [{
        color,
        title: `Cron Job: ${payload.taskName}`,
        text: `Event: ${payload.event.toUpperCase()}`,
        fields: [
          { title: 'Duration', value: `${payload.duration}ms`, short: true },
          { title: 'Attempts', value: payload.attemptsMade, short: true },
        ],
        ts: Math.floor(payload.timestamp.getTime() / 1000),
      }],
    }),
  });
};

const task = schedule('0 6 * * *', dailyBackup, {
  name: 'daily-backup',
  notifier: slackNotifier,
  notifyOn: { success: false, error: true }, // Only notify on failures
});

Email Adapter (using nodemailer)

import { schedule, NotificationPayload } from 'cron-safe';
import nodemailer from 'nodemailer';

const transporter = nodemailer.createTransport({
  host: 'smtp.example.com',
  auth: { user: 'user', pass: 'pass' },
});

const emailNotifier = async (payload: NotificationPayload) => {
  if (payload.event !== 'error' && payload.event !== 'timeout') return;
  
  await transporter.sendMail({
    from: '[email protected]',
    to: '[email protected]',
    subject: `[ALERT] ${payload.taskName} ${payload.event}`,
    text: `
Task: ${payload.taskName}
Event: ${payload.event}
Time: ${payload.timestamp}
Duration: ${payload.duration}ms
Error: ${payload.error?.message ?? 'N/A'}
Attempts: ${payload.attemptsMade}
    `,
  });
};

const task = schedule('0 0 * * *', nightlyCleanup, {
  name: 'nightly-cleanup',
  notifier: emailNotifier,
});

Full Lifecycle Hooks

import { schedule } from 'cron-safe';

const task = schedule('0 9 * * *', async () => {
  return await generateDailyReport();
}, {
  name: 'daily-report',
  retries: 2,
  retryDelay: 10000,
  preventOverlap: true,
  executionTimeout: 60000,
  historyLimit: 50,
  
  onStart: () => {
    console.log('[daily-report] Starting execution');
  },
  
  onSuccess: (result) => {
    console.log('[daily-report] Completed:', result);
  },
  
  onRetry: (error, attempt) => {
    console.warn(`[daily-report] Retry ${attempt}:`, error.message);
  },
  
  onError: (error) => {
    console.error('[daily-report] Failed permanently:', error);
    sendSlackAlert('Daily report generation failed!');
  },
  
  onTimeout: (error) => {
    console.error('[daily-report] Timed out:', error.message);
  },
  
  onOverlapSkip: () => {
    console.warn('[daily-report] Skipped due to overlap');
  },
});

API

schedule(cronExpression, task, options?)

Schedules a task with automatic retries, timeout, and overlap prevention.

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | cronExpression | string | A valid cron expression (e.g., '* * * * *') | | task | () => T \| Promise<T> | The function to execute | | options | CronSafeOptions<T> | Configuration options (see below) |

Returns: CronSafeTask<T>

CronSafeOptions<T>

| Option | Type | Default | Description | |--------|------|---------|-------------| | name | string | undefined | Identifier for logging/debugging | | retries | number | 0 | Number of retry attempts after failure | | retryDelay | number | 0 | Base delay in ms between retries | | backoffStrategy | 'fixed' \| 'linear' \| 'exponential' | 'fixed' | How delay grows between retries | | maxRetryDelay | number | undefined | Maximum delay cap for backoff | | preventOverlap | boolean | false | Skip execution if previous run is active | | maxConcurrency | number | undefined | Max concurrent executions allowed | | executionTimeout | number | undefined | Max execution time in ms before timeout | | historyLimit | number | 10 | Max number of history entries to keep | | distributedLock | DistributedLockConfig | — | Distributed locking configuration | | storage | StorageAdapter | — | Persistent storage adapter | | metricsProvider | MetricsProvider | — | External metrics export provider | | onStart | () => void | — | Called when task starts | | onSuccess | (result: T) => void | — | Called with result on success | | onRetry | (error, attempt) => void | — | Called before each retry | | onError | (error) => void | — | Called when all retries exhausted | | onTimeout | (error: Error) => void | — | Called when task times out | | onOverlapSkip | () => void | — | Called when execution is skipped | | notifier | Notifier<T> | — | Callback for Slack/email/custom notifications | | notifyOn | NotifyOn | { success: true, error: true, timeout: true, overlapSkip: false, lockFailed: false } | Which events trigger notifications | | timezone | string | — | Timezone for cron schedule | | scheduled | boolean | true | Start immediately or wait for .start() | | runOnInit | boolean | false | Run task immediately on creation |

DistributedLockConfig

| Option | Type | Default | Description | |--------|------|---------|-------------| | provider | LockProvider | — | Lock provider implementation (required) | | ttl | number | 60000 | Lock time-to-live in ms | | autoExtend | boolean | false | Auto-extend lock while task is running | | extendInterval | number | ttl / 2 | Interval in ms for auto-extending |

LockProvider

Interface to implement for your distributed lock backend:

| Method | Signature | Description | |--------|-----------|-------------| | acquire | (key: string, ttl: number) => Promise<string \| null> | Acquire lock, return lock ID or null | | release | (key: string, lockId: string) => Promise<void> | Release the lock | | extend? | (key: string, lockId: string, ttl: number) => Promise<boolean> | Extend lock TTL (optional) |

StorageAdapter

Interface to implement for persistent storage:

| Method | Signature | Description | |--------|-----------|-------------| | saveRun | (record: StoredRunRecord) => Promise<void> | Save a new run record | | updateRun | (taskName, startedAt, updates) => Promise<void> | Update an existing run | | getRuns | (taskName, limit) => Promise<StoredRunRecord[]> | Get recent runs | | getLastIncompleteRun? | (taskName) => Promise<StoredRunRecord \| null> | Get crashed run (optional) |

MetricsProvider

Interface for metrics export:

| Method | Signature | Description | |--------|-----------|-------------| | recordEvent | (taskName, event, duration?) => void | Record a task event |

Events: 'start', 'success', 'failure', 'timeout', 'retry', 'overlapSkip'

CronSafeTask<T>

The object returned by schedule():

| Method | Returns | Description | |--------|---------|-------------| | start() | void | Start the scheduled task | | stop() | void | Stop the scheduled task | | getStatus() | 'scheduled' \| 'running' \| 'stopped' | Current status | | trigger() | Promise<T \| undefined> | Execute immediately, returns result | | getHistory() | RunHistory[] | Get execution history (newest first) | | nextRun() | Date \| null | Next scheduled run time | | getMetrics() | TaskMetrics | Get real-time metrics snapshot | | updateSchedule(expr) | void | Change cron expression at runtime |

TaskMetrics

| Property | Type | Description | |----------|------|-------------| | totalRuns | number | Total number of runs started | | totalSuccess | number | Number of successful completions | | totalFailures | number | Number of failed runs | | totalTimeouts | number | Number of timed out runs | | totalRetries | number | Total retry attempts across all runs | | totalOverlapSkips | number | Number of runs skipped due to overlap | | currentRunning | number | Number of currently executing runs | | avgDuration | number | Average execution duration in ms | | lastRunAt | Date \| undefined | When the last run completed | | lastStatus | string \| undefined | Status of the last completed run |

RunHistory

| Property | Type | Description | |----------|------|-------------| | startedAt | Date | When execution started | | endedAt | Date \| undefined | When execution ended | | duration | number \| undefined | Duration in milliseconds | | status | 'running' \| 'success' \| 'failed' \| 'timeout' | Execution status | | error | Error \| undefined | Error if failed/timeout | | triggeredBy | 'schedule' \| 'manual' | How the run was triggered |

validate(expression)

Validates a cron expression. Re-exported from node-cron.

import { validate } from 'cron-safe';

console.log(validate('* * * * *'));     // true
console.log(validate('invalid'));       // false

TimeoutError

Error class thrown when a task exceeds its execution timeout.

import { TimeoutError } from 'cron-safe';

// In your onError handler
onError: (error) => {
  if (error instanceof TimeoutError) {
    console.log('Task timed out');
  }
}

Migration from node-cron

Before:

import cron from 'node-cron';

cron.schedule('* * * * *', async () => {
  await myTask();  // Errors go unhandled!
});

After:

import { schedule } from 'cron-safe';

schedule('* * * * *', async () => {
  await myTask();
}, {
  retries: 3,
  executionTimeout: 30000,
  onError: (err) => console.error('Task failed:', err),
});

TypeScript

Full TypeScript support with strict types:

import { schedule, CronSafeOptions, CronSafeTask, RunHistory, TaskMetrics } from 'cron-safe';

interface ReportResult {
  rowsProcessed: number;
  duration: number;
}

const options: CronSafeOptions<ReportResult> = {
  retries: 2,
  executionTimeout: 60000,
  historyLimit: 100,
  onSuccess: (result) => {
    // result is typed as ReportResult
    console.log(`Processed ${result.rowsProcessed} rows`);
  },
};

const task: CronSafeTask<ReportResult> = schedule('0 * * * *', async (): Promise<ReportResult> => {
  return { rowsProcessed: 1000, duration: 5000 };
}, options);

// Trigger returns typed result
const result = await task.trigger();
if (result) {
  console.log(result.rowsProcessed);  // TypeScript knows this is a number
}

// History is also typed
const history: RunHistory[] = task.getHistory();

// Metrics snapshot
const metrics: TaskMetrics = task.getMetrics();
console.log(`Success rate: ${(metrics.totalSuccess / metrics.totalRuns * 100).toFixed(1)}%`);