or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdjob-management.mdrecurrence-rules.md
tile.json

tessl/npm-node-schedule

A cron-like and not-cron-like job scheduler for Node.js with flexible recurrence rules and time-based scheduling.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/node-schedule@2.1.x

To install, run

npx @tessl/cli install tessl/npm-node-schedule@2.1.0

index.mddocs/

Node Schedule

Node Schedule is a flexible cron-like and not-cron-like job scheduler for Node.js that enables precise time-based scheduling. It allows you to schedule jobs (arbitrary functions) for execution at specific dates with optional recurrence rules, using a single timer architecture for efficiency.

Package Information

  • Package Name: node-schedule
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install node-schedule

Core Imports

const schedule = require('node-schedule');

For ES modules:

import * as schedule from 'node-schedule';

Individual imports:

const { scheduleJob, cancelJob, rescheduleJob, gracefulShutdown, Job, RecurrenceRule, Range, Invocation } = require('node-schedule');

Basic Usage

const schedule = require('node-schedule');

// Schedule with cron syntax
const job = schedule.scheduleJob("42 * * * *", function() {
  console.log('The answer to life, the universe, and everything!');
});

// Schedule for specific date
const date = new Date(2024, 11, 21, 5, 30, 0);
const job2 = schedule.scheduleJob(date, function() {
  console.log('This will run on December 21st 2024 at 5:30am');
});

// Cancel a job
schedule.cancelJob(job);

// Access all scheduled jobs
console.log('Scheduled jobs:', Object.keys(schedule.scheduledJobs));

// Graceful shutdown (cancels all jobs and waits for completion)
await schedule.gracefulShutdown();

Architecture

Node Schedule is built around several key components:

  • Job Scheduling: Core scheduleJob() function and Job class for creating and managing scheduled tasks
  • Timing Specifications: Multiple formats including cron strings, Date objects, and RecurrenceRule objects
  • Single Timer System: Efficient architecture that uses only one timer at any given time
  • Event-Driven Model: Jobs extend EventEmitter and emit lifecycle events (run, scheduled, canceled, error, success)
  • Promise Support: Automatic handling of job functions that return Promises with proper success/error events
  • Generator Function Support: Automatic detection and handling of JavaScript generator functions
  • Timezone Support: Full timezone support for scheduling across different time zones
  • Graceful Shutdown: Built-in support for cleanly stopping all jobs and waiting for running tasks to complete

Capabilities

Job Scheduling

Core job scheduling functionality for creating, managing, and executing time-based tasks with multiple scheduling formats.

/**
 * Schedule a job to run at specified times
 * @param {string|Date|object} spec - Schedule specification (cron, date, or recurrence rule)
 * @param {function} method - Function to execute
 * @returns {Job|null} Job instance or null if scheduling failed
 */
function scheduleJob(spec, method);

/**
 * Schedule a named job to run at specified times
 * @param {string} name - Job name for later reference
 * @param {string|Date|object} spec - Schedule specification
 * @param {function} method - Function to execute
 * @param {function} [callback] - Optional callback function
 * @returns {Job|null} Job instance or null if scheduling failed
 */
function scheduleJob(name, spec, method, callback);

/**
 * Reschedule an existing job with new timing
 * @param {Job|string} job - Job instance or job name
 * @param {string|Date|object} spec - New schedule specification
 * @returns {Job|null} Job instance or null if rescheduling failed
 */
function rescheduleJob(job, spec);

/**
 * Cancel a scheduled job
 * @param {Job|string} job - Job instance or job name
 * @returns {boolean} True if job was successfully canceled
 */
function cancelJob(job);

/**
 * Gracefully shutdown all jobs and wait for completion
 * @returns {Promise<void>} Promise that resolves when all jobs are stopped
 */
function gracefulShutdown();

Job Management

Advanced job management capabilities including manual execution, lifecycle control, and state inspection.

class Job extends EventEmitter {
  constructor(name, job, callback);
  
  /** Job name (readonly) */
  readonly name: string;
  /** Job function to execute */
  job: function;
  /** Optional callback function */
  callback: function | false;
  /** Number of currently running invocations */
  running: number;
  /** Array of pending invocation objects */
  pendingInvocations: Invocation[];
  /** Whether this is a one-time job */
  isOneTimeJob: boolean;
}

Job Management

Recurrence Rules

Flexible recurrence rule system for defining complex scheduling patterns with precise control over timing components.

/**
 * Create a recurrence rule for complex scheduling patterns
 * @param {number|number[]|Range} [year] - Year specification
 * @param {number|number[]|Range} [month] - Month specification (0-11)
 * @param {number|number[]|Range} [date] - Day of month specification (1-31)
 * @param {number|number[]|Range} [dayOfWeek] - Day of week specification (0-6, Sunday=0)
 * @param {number|number[]|Range} [hour] - Hour specification (0-23)
 * @param {number|number[]|Range} [minute] - Minute specification (0-59)
 * @param {number|number[]|Range} [second] - Second specification (0-59, defaults to 0)
 */
function RecurrenceRule(year?, month?, date?, dayOfWeek?, hour?, minute?, second?);

/**
 * Create a range for use in recurrence rules
 * @param {number} [start=0] - Range start value
 * @param {number} [end=60] - Range end value
 * @param {number} [step=1] - Range step value
 */
function Range(start?, end?, step?);

Recurrence Rules

Scheduled Jobs Registry

Global registry for accessing and managing named scheduled jobs.

/**
 * Global object containing all named scheduled jobs
 * Key is the job name, value is the Job instance
 */
const scheduledJobs: {[key: string]: Job};

Types

/** Schedule specification object with timing constraints */
interface ScheduleSpec {
  /** Recurrence rule or cron string */
  rule: RecurrenceRule | string;
  /** Optional start date */
  start?: Date;
  /** Optional end date */
  end?: Date;
  /** Optional timezone identifier */
  tz?: string;
}

/** Object-literal recurrence specification */
interface RecurrenceSpec {
  /** Year specification */
  year?: number | number[] | Range;
  /** Month specification (0-11) */
  month?: number | number[] | Range;
  /** Day of month specification (1-31) */
  date?: number | number[] | Range;
  /** Day of week specification (0-6, Sunday=0) */
  dayOfWeek?: number | number[] | Range;
  /** Hour specification (0-23) */
  hour?: number | number[] | Range;
  /** Minute specification (0-59) */
  minute?: number | number[] | Range;
  /** Second specification (0-59) */
  second?: number | number[] | Range;
}

/** Internal invocation object (primarily for internal use) */
class Invocation {
  constructor(job, fireDate, recurrenceRule, endDate);
  
  /** Associated job instance */
  job: Job;
  /** When invocation should fire */
  fireDate: Date;
  /** Associated recurrence rule */
  recurrenceRule: RecurrenceRule;
  /** Optional end date for recurring jobs */
  endDate?: Date;
  /** Internal timer identifier */
  timerID: number | null;
}