tessl/npm-node-schedule

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Node Schedule

Name: tessl/npm-node-schedule
Author: tessl

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;
}