or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdjob-management.mdtime-calculations.md
tile.json

tessl/npm-cron

Cron jobs for Node.js applications that enables developers to execute functions or system commands on schedules defined using standard cron syntax

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cron@4.3.x

To install, run

npx @tessl/cli install tessl/npm-cron@4.3.0

index.mddocs/

Cron

Cron is a robust tool for running jobs (functions or commands) on schedules defined using the cron syntax. It provides a comprehensive API through the CronJob and CronTime classes for creating, managing, and controlling scheduled tasks, with advanced scheduling features including Date and Luxon DateTime objects as triggers, optional seconds precision beyond standard Unix cron behavior, and built-in timezone handling and child process execution capabilities.

Package Information

  • Package Name: cron
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install cron

Core Imports

import { 
  CronJob, 
  CronTime, 
  sendAt, 
  timeout, 
  validateCronExpression,
  type CronJobParams,
  type CronCallback,
  type CronCommand,
  type CronContext,
  type CronOnCompleteCallback,
  type CronOnCompleteCommand,
  type Ranges,
  type TimeUnit
} from "cron";

For CommonJS:

const { CronJob, CronTime, sendAt, timeout, validateCronExpression } = require("cron");

Basic Usage

import { CronJob } from "cron";

// Create a cron job that runs every second
const job = new CronJob(
  '* * * * * *', // cronTime - every second
  function () {
    console.log('You will see this message every second');
  }, // onTick
  null, // onComplete
  true, // start
  'America/Los_Angeles' // timeZone
);

// Alternative: using the from static method with object parameters
const job2 = CronJob.from({
  cronTime: '0 0 * * *', // every day at midnight
  onTick: function () {
    console.log('Daily backup starting...');
  },
  start: true,
  timeZone: 'America/Los_Angeles'
});

// Manual job control
const manualJob = new CronJob('0 0 * * *', () => {
  console.log('Manual job executed');
});
manualJob.start();
// manualJob.stop();

Architecture

Cron is built around several key components:

  • CronJob Class: Main class for creating and managing scheduled jobs with full lifecycle control
  • CronTime Class: Handles cron expression parsing, validation, and next execution time calculations
  • Utility Functions: Standalone functions for quick time calculations and validation
  • Type System: Full TypeScript integration with generics for callback contexts and completion handlers
  • Timezone Support: Built on Luxon DateTime for robust timezone and DST handling
  • Error Handling: Comprehensive error handling with custom error classes and configurable error handlers

Capabilities

Job Management

Core job scheduling and lifecycle management functionality for creating, starting, stopping, and monitoring cron jobs.

class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
  constructor(
    cronTime: string | Date | DateTime,
    onTick: CronCommand<C, WithOnComplete<OC>>,
    onComplete?: OC,
    start?: boolean | null,
    timeZone?: string | null,
    context?: C,
    runOnInit?: boolean | null,
    utcOffset?: number | null,
    unrefTimeout?: boolean | null,
    waitForCompletion?: boolean | null,
    errorHandler?: ((error: unknown) => void) | null,
    name?: string | null,
    threshold?: number | null
  );

  static from<OC extends CronOnCompleteCommand | null = null, C = null>(
    params: CronJobParams<OC, C>
  ): CronJob<OC, C>;
}

Job Management

Time Calculations

Cron time parsing, validation, and calculation utilities for working with cron expressions and scheduling.

class CronTime {
  constructor(
    source: string | Date | DateTime,
    timeZone?: string | null,
    utcOffset?: number | null
  );

  static validateCronExpression(cronExpression: string): {
    valid: boolean;
    error?: CronError;
  };
}

function sendAt(cronTime: string | Date | DateTime): DateTime;
function timeout(cronTime: string | Date | DateTime): number;
function validateCronExpression(cronExpression: string): {
  valid: boolean;
  error?: CronError;
};

Time Calculations

Types

import { SpawnOptions } from 'child_process';
import { DateTime } from 'luxon';

interface CronJobParams<
  OC extends CronOnCompleteCommand | null = null,
  C = null
> {
  cronTime: string | Date | DateTime;
  onTick: CronCommand<C, WithOnComplete<OC>>;
  onComplete?: OC;
  start?: boolean | null;
  context?: C;
  runOnInit?: boolean | null;
  unrefTimeout?: boolean | null;
  waitForCompletion?: boolean | null;
  errorHandler?: ((error: unknown) => void) | null;
  threshold?: number | null;
  name?: string | null;
  timeZone?: string | null;
  utcOffset?: number | null;
}

type CronCallback<C, WithOnCompleteBool extends boolean = false> = (
  this: CronContext<C>,
  onComplete: WithOnCompleteBool extends true ? CronOnCompleteCallback : never
) => void | Promise<void>;

type CronOnCompleteCallback = () => void | Promise<void>;

type CronSystemCommand = 
  | string
  | {
      command: string;
      args?: readonly string[] | null;
      options?: SpawnOptions | null;
    };

type CronCommand<C, WithOnCompleteBool extends boolean = false> =
  | CronCallback<C, WithOnCompleteBool>
  | CronSystemCommand;

type CronOnCompleteCommand = CronOnCompleteCallback | CronSystemCommand;

type CronContext<C> = C extends null ? CronJob : NonNullable<C>;

type WithOnComplete<OC> = OC extends null ? false : true;

class CronError extends Error {}

class ExclusiveParametersError extends CronError {
  constructor(param1: string, param2: string);
}

type TimeUnit = 'second' | 'minute' | 'hour' | 'dayOfMonth' | 'month' | 'dayOfWeek';

interface Ranges {
  second: SecondRange;      // 0-59
  minute: MinuteRange;      // 0-59  
  hour: HourRange;          // 0-23
  dayOfMonth: DayOfMonthRange; // 1-31
  month: MonthRange;        // 1-12
  dayOfWeek: DayOfWeekRange;   // 0-7 (0 and 7 are Sunday)
}

// Range types providing type-safe cron field values
type SecondRange = number; // 0-59
type MinuteRange = number; // 0-59
type HourRange = number;   // 0-23
type DayOfMonthRange = number; // 1-31
type MonthRange = number;  // 1-12
type DayOfWeekRange = number; // 0-7