Stringifying

stringify() converts an RRuleOptions object back to a canonical RRULE string. It always includes the RRULE: prefix and emits parts in a fixed canonical order.

Function signature

function stringify(options: RRuleOptions): string

Canonical output format

The output always:

• Starts with RRULE: (or a DTSTART line followed by RRULE: when dtstart is set)
• Emits RRULE parts in this fixed order: FREQ, UNTIL, COUNT, INTERVAL, WKST, BYSECOND, BYMINUTE, BYHOUR, BYDAY, BYMONTHDAY, BYYEARDAY, BYWEEKNO, BYMONTH, BYSETPOS
• Omits any part whose value is undefined in the options object

Example:

import { stringify } from 'rrule-ts'

stringify({
  freq: 'WEEKLY',
  byDay: [
    { weekday: 'MO', ordinal: undefined },
    { weekday: 'WE', ordinal: undefined },
    { weekday: 'FR', ordinal: undefined },
  ],
  count: 10,
})
// 'RRULE:FREQ=WEEKLY;COUNT=10;BYDAY=MO,WE,FR'

COUNT appears before BYDAY in the output regardless of the order the fields appear in the options object: stringify always uses the canonical order.

BYDAY serialization

Plain weekdays (no ordinal) serialize as their two-letter abbreviation. Ordinal weekdays include the ordinal prefix:

stringify({
  freq: 'MONTHLY',
  byDay: [
    { weekday: 'MO', ordinal: 2 }, // 2nd Monday
    { weekday: 'FR', ordinal: -1 }, // last Friday
  ],
})
// 'RRULE:FREQ=MONTHLY;BYDAY=2MO,-1FR'

DTSTART output

When dtstart is present in the options, stringify() prepends a DTSTART content line. The RRULE: line follows on the next line. This layout matches the iCalendar multiline format and ensures parse(stringify(x)) deep-equals x for all valid x.

import { getTemporal } from 'rrule-ts'

const T = getTemporal()

// Date-only DTSTART
stringify({
  freq: 'DAILY',
  count: 5,
  dtstart: T.PlainDate.from('2024-01-01'),
})
// 'DTSTART:20240101\nRRULE:FREQ=DAILY;COUNT=5'

// UTC datetime DTSTART
stringify({
  freq: 'WEEKLY',
  dtstart: T.Instant.from('2024-01-01T09:00:00Z'),
})
// 'DTSTART:20240101T090000Z\nRRULE:FREQ=WEEKLY'

For timezone-aware starts, the TZID= parameter is included:

stringify({
  freq: 'WEEKLY',
  dtstart: T.ZonedDateTime.from('2024-01-01T09:00:00[America/New_York]'),
  tzid: 'America/New_York',
})
// 'DTSTART;TZID=America/New_York:20240101T090000\nRRULE:FREQ=WEEKLY'

tzid and dtstart

The tzid field in RRuleOptions is the IANA timezone identifier string extracted from the DTSTART;TZID= content line. When dtstart is a Temporal.ZonedDateTime, the timezone is already embedded in the value. stringify() reads options.tzid to emit the TZID= parameter on the DTSTART line. If you build RRuleOptions by hand with a ZonedDateTime dtstart, set tzid to the same timezone identifier so the round-trip is preserved.

Round-trip guarantee

For all valid RRuleOptions:

parse(stringify(x)).value deep-equals x

And for all valid RRULE strings that parse() accepts:

stringify(parse(s).value!) === stringify(parse(stringify(parse(s).value!)).value!)

Stringifying is idempotent: once a value has been parsed and stringified, stringifying the result again produces the same string.

stringify vs toText

	stringify()	toText()
Output	RRULE:FREQ=WEEKLY;COUNT=10;BYDAY=MO,WE,FR	every week on Monday, Wednesday, and Friday, 10 times
Purpose	Storage, wire format, iCalendar	User-facing display
Round-trip	Yes	No (natural language loses information)
Locale support	No	Yes (EN and DE built in)

Use stringify() when storing or transmitting the RRULE. Use toText() when displaying it to a user. See the toText and fromText guide.