@rschedule/rule-tools

The optional package @rschedule/rule-tools contains utility functions for manipulating rSchedule Rule and Schedule objects and working with common recurrence rule patterns. Even if you don't use it, it can provide a useful example of how to manipulate and build up immutable rSchedule objects.

Example:

import { addSchedulePattern } from '@rschedule/rule-tools';

let schedule = new Schedule();

schedule = addSchedulePattern('every [WEEKDAY]', new Date(), schedule);

// Assume the day is "Tuesday" so `new Date().getDay() === 2`

schedule.rrules[0].options; // { start: new Date(), frequency: 'WEEKLY', byDayOfWeek: ['TU']}

schedule.occursOn({ weekday: 'TU' }); // true

Installation

yarn add @rschedule/rule-tools

# or

npm install @rschedule/rule-tools

Usage

@rschedule/rule-tools provides utility functions for working with common occurrence and recurrence patterns which I've identified.

Currently, @rschedule/rule-tools defines four common recurrence patterns and one common occurrence pattern. A RecurrencePattern is a common combination of rule options for defining a recurring schedule. An OccurrencePattern is a common singleton occurrence definition.

The rule-tools package is meant to make it easier to add these common rule options to Schedule objects, remove these common rule options, check if a schedule has a specific one of these common rule options on a given day, or update one of these common rule options to "stop" on a given day.

In practical terms, here is an example workflow:

1. A user clicks on a day on the calendar.
2. The validRecurrencePatternsOnDate() function can be used to find what common recurrence patterns can be added for the clicked date.
3. The scheduleHasPattern() function can be used to see if a specific Schedule object already has a specific occurrence pattern on the given date.
   • For all the rules existing in the Schedule for the given date, you can provide an option to the user to end that rule on that date, or remove the rule altogether.
     1. endScheduleRecurrencePattern()
     2. removeSchedulePattern()
   • For all the common rule patterns which the Schedule doesn't have on the given date, you can provide an option to the user to add a rule matching that pattern starting on the given date.
     1. addSchedulePattern()
4. If you have a Rule or rule options object, you can use isRecurrencePattern() to see if the rule options match a given recurrence pattern.
5. If you want to make a new Rule from scratch, you can use buildRecurrencePattern() to generate an options object matching the given recurrence pattern.

RecurrencePattern type

The RecurrencePattern type defines four common recurrence patterns. Where a recurrence pattern is a common set of rule options defining a schedule's repeating occurrences.

type RecurrencePattern =
  | 'every [WEEKDAY]'
  | 'the [MONTH_WEEKNO] [WEEKDAY] of every month'
  | 'the [MONTH_DAYNO] of every month'
  | 'the last [WEEKDAY] of every month';

Examples:

1. 'every [WEEKDAY]'
   • "Every Tuesday"
   • "Every Friday"
2. 'the [MONTH_WEEKNO] [WEEKDAY] of every month'
   • "The 1st Monday of every month"
   • "The 5th Sunday of every month"
3. 'the [MONTH_DAYNO] of every month'
   • "The 15th of every month"
   • "The 1st of every month"
4. 'the last [WEEKDAY] of every month';
   • "The last Friday of every month"
   • "The last Saturday of every month"

OccurrencePattern type

The OccurrencePattern type defines one common definition for singleton occurrences.

export type OccurrencePattern = 'date';

Examples:

1. 'date'
   • "2019/05/04"
   • January 1st, 2019

Schedule functions

@rschedule/rule-tools provides utility functions for working with Schedule objects.

scheduleHasPattern()

Checks to see if a schedule contains the OccurrencePattern or RecurrencePattern on the given date.

• Pass the ignoreStart: true option to ignore the start time of the rules being checked (this means that the provided date can be before the rule's start time).

• Pass the ignoreEnd: true option to ignore the end time of the rules being checked (this means that the provided date can be after the rule's end time).

function scheduleHasPattern(args: {
  pattern: Pattern;
  date: DateInput;
  schedule: Schedule<any>;
  ignoreStart?: boolean | undefined;
  ignoreEnd?: boolean | undefined;
}): boolean;

addSchedulePattern()

Adds the OccurrencePattern or RecurrencePattern to the schedule on the provided date.

function addSchedulePattern<S extends Schedule>(pattern: Pattern, date: DateInput, schedule: S): S;

endScheduleRecurrencePattern()

End any matching RecurrencePatterns the schedule has on the provided date.

function endScheduleRecurrencePattern<S extends Schedule>(args: {
  pattern: RecurrencePattern;
  date: DateInput;
  schedule: S;
  cleanEXDates?: boolean;
}): S;

removeSchedulePattern()

Remove any matching OccurrencePatterns or RecurrencePatterns the schedule has on the provided date.

function removeSchedulePattern<S extends Schedule>(args: {
  pattern: Pattern;
  date: DateInput;
  schedule: S;
  cleanEXDates?: boolean;
}): S;

cleanScheduleEXDates()

Remove all of the schedule's exdates which do not intersect the schedule's occurrences.

function cleanScheduleEXDates<S extends Schedule>(schedule: S): S;

Rule functions

isRecurrencePattern()

Checks to see if the provided rule/rule options match the given RecurrencePattern.

function isRecurrencePattern(args: {
  pattern: RecurrencePattern;
  date: DateInput;
  rule: Rule | IRuleOptions;
  ignoreStart?: boolean;
  ignoreEnd?: boolean;
}): boolean;

validRecurrencePatternsOnDate()

Returns an array containing all the RecurrencePatterns which are valid on a given date.

function validRecurrencePatternsOnDate(date: DateInput): RecurrencePattern[];

buildRecurrencePattern()

Builds a rule options object matching the given RecurrencePattern with the given start date.

function buildRecurrencePattern(pattern: RecurrencePattern, start: DateInput): IRuleOptions;