generateRecurringDates

The core function that generates recurring dates based on a configuration object. This is the main API of the library.

Signature

function generateRecurringDates(config: RecurringDatesConfig): RecurringDatesResult

Parameters

config— A configuration object. See Config Reference for all options.

Return Value

Success

{
  text: string;   // Human-readable description
  dates: string[]; // Sorted array of date strings
}

Validation Error

{
  dates: [];       // Always empty on error
  error: string;   // Descriptive error message
}

Examples

All Frequency Examples

import { generateRecurringDates } from "recurring-dates";

// Daily
const daily = generateRecurringDates({
  STARTS_ON: "01-01-2025",
  ENDS_ON: "05-01-2025",
  FREQUENCY: "D",
});
// { text: "Every day", dates: ["01-01-2025", ..., "05-01-2025"] }

// Weekly
const weekly = generateRecurringDates({
  STARTS_ON: "01-01-2025",
  ENDS_ON: "31-01-2025",
  FREQUENCY: "W",
  WEEK_DAYS: ["MON", "THU"],
});
// { text: "Every week on Monday and Thursday", dates: [...] }

// Monthly
const monthly = generateRecurringDates({
  STARTS_ON: "01-01-2025",
  ENDS_ON: "31-12-2025",
  FREQUENCY: "M",
  MONTH_DATES: [1, 15],
});
// { text: "Every month on 1st and 15th", dates: [...] }

// Yearly
const yearly = generateRecurringDates({
  STARTS_ON: "01-01-2025",
  ENDS_ON: "31-12-2030",
  FREQUENCY: "Y",
  WEEK_ORDINALS: ["SECOND"],
  WEEK_DAYS: ["MON"],
  MONTH_NAMES: ["JAN"],
});
// { text: "Every year on Second Monday of January", dates: [...] }

Error Handling

Validation Error

const result = generateRecurringDates({
  STARTS_ON: "01-01-2025",
  // ENDS_ON missing!
  FREQUENCY: "D",
});

console.log(result);
// { dates: [], error: "End Date is required ..." }