Data - Recurrence

Type identifier: data:recurrence Category: Data Operations

Description

Works with the value of a recurrence field, such as "weekly on Monday, Wednesday and Friday at 5:00 PM". Depending on its mode, the node lists the occurrences in a date range, finds the next or previous occurrence, or checks whether a date/time falls on an occurrence.

Use it to turn a schedule into concrete date-times, for example to create one Delivery per run of a truck in a given week.

Input Handles

The input handles depend on the mode.

Handle	Data Type	Required	Mode	Description
`recurrence`	`recurrence`	Yes	All	The recurrence to work with
`start`	`date`	Yes	`between`	Start of the range, inclusive
`end`	`date`	Yes	`between`	End of the range, inclusive
`after`	`date`	No	`next`	Find the first occurrence at or after this date/time. Defaults to now
`before`	`date`	No	`previous`	Find the last occurrence at or before this date/time. Defaults to now
`dateTime`	`date`	Yes	`includes`	The date/time to check

Input Handle Details

`recurrence`

Type: recurrence
Notes:
- Connect a recurrence field from a Record, a Flow trigger input, or any other recurrence value
- A value that is not a valid recurrence fails the node

Date/time inputs (`start`, `end`, `after`, `before`, `dateTime`)

Type: date, with or without a time
Notes:
- Read in the recurrence's time zone: its start date's zone, or for a rule without a start date, its stored time zone (UTC if it has none)
- A date without a time is midnight at the start of that day in the recurrence's time zone. Because end is inclusive, a start of 2026-10-12 and an end of 2026-10-18 cover 12 October to the start of 18 October; use 2026-10-18T23:59:59 to include all of the 18th
- A date/time with a time zone or offset keeps its exact instant
- A value that is not a date/time fails the node

Output Handles

Handle	Data Type	Mode	Description
`occurrences`	`date[]`	`between`	The occurrences from `start` to `end`, in order
`occurrence`	`date`	`next`, `previous`	The occurrence found, or `null` when there is none
`includes`	`boolean`	`includes`	Whether `dateTime` is an occurrence, or falls within one

Output Handle Details

`occurrences`

Type: list of date-times
Notes:
- Each occurrence is a date-time in the recurrence's time zone, with the time of day the recurrence sets
- Connect it to List - Map to act once per occurrence
- An empty list when nothing occurs in the range

`occurrence`

Type: date-time, or null
Notes: null when the recurrence has ended (by count or until) before the bound, or has not started by it

`includes`

Type: boolean
Notes:
- For a recurrence without a duration, true only at the exact occurrence date-time
- For a recurrence with a duration, true from the start of an occurrence up to, but not including, its end

Configuration Options

Property	Type	Required	Default	Description
`label`	`string`	Yes	`"Data - Recurrence"`	Display label for the node
`mode`	`"between"` \| `"next"` \| `"previous"` \| `"includes"`	No	`"between"`	What to compute. Shown as Find in Studio

Configuration Details

`mode`

Value	Studio label	Inputs	Output
`between`	Occurrences between	`start`, `end`	`occurrences`
`next`	Next occurrence	`after`	`occurrence`
`previous`	Previous occurrence	`before`	`occurrence`
`includes`	Includes date/time	`dateTime`	`includes`

Changing the mode changes the node's handles; connections to handles that no longer exist are removed.

Behaviour

Execution Flow

Resolves the recurrence input and checks that it is a valid recurrence
Resolves the date/time inputs for the mode and reads them in the recurrence's time zone
Computes the output for the mode

The node is computed when a connected node needs its output.

Time Zones and Daylight Saving

Occurrences keep the recurrence's wall-clock time across daylight-saving changes: a rule at 5:00 PM in Australia/Melbourne is 5:00 PM local time on both sides of a change. For a rule without a start date, see Rules without a start date.

Error Handling

Scenario	Behaviour
A required input is not connected	Fails with `No incoming edges for <node>:<handle>.`
`recurrence` is empty	Fails with `data:recurrence:<node> recurrence is required`
`recurrence` is not a valid recurrence	Fails with `data:recurrence:<node> recurrence is not a valid recurrence: …` and the reason
`recurrence` has no start date and does not name its own days (see Rules without a start date)	Fails with `data:recurrence:<node> recurrence cannot be expanded: …` and the reason, for example `A yearly recurrence needs a start date`
A required date/time input is empty	Fails with `data:recurrence:<node> <handle> is required`
A date/time input is not a date/time	Fails with `data:recurrence:<node> <handle> is not a date/time`
The range needs more than 10,000 expansion steps (for example, a minutely rule over several years)	Fails with "The recurrence has too many occurrences to expand here; narrow the date range"

Examples

Occurrences in a Week

{
  "type": "data:recurrence",
  "data": {
    "label": "This Week's Runs",
    "mode": "between"
  }
}

Connect a Truck Schedule Record's Schedule field to recurrence, and the start and end of the week to start and end (for example 2026-10-12 and 2026-10-18T23:59:59). For a schedule of "weekly on Monday, Wednesday, Friday at 5:00 PM" in Australia/Melbourne and the week of 12 October 2026, occurrences is:

[
  "2026-10-12T17:00:00+11:00[Australia/Melbourne]",
  "2026-10-14T17:00:00+11:00[Australia/Melbourne]",
  "2026-10-16T17:00:00+11:00[Australia/Melbourne]"
]

Connect occurrences to a List - Map node and create one Record per occurrence inside it.

Next Occurrence

{
  "type": "data:recurrence",
  "data": {
    "label": "Next Run",
    "mode": "next"
  }
}

Leave after unconnected to find the next occurrence from now.

Check Opening Hours

{
  "type": "data:recurrence",
  "data": {
    "label": "Is Open",
    "mode": "includes"
  }
}

For a recurrence such as "weekdays at 9:00 AM" with a duration of PT8H, includes is true from 9:00 AM until 5:00 PM on weekdays. Connect it to Control - If to branch.