Date window checker

Operations (1)

• Check dates against today

  dates.window

  Compute, for each tracked item, how many whole civil days remain until its date in the given IANA timezone. daysUntil is a pure calendar-day difference (negative = past), immune to daylight-saving shifts because no hour math is involved. Each returned item carries daysUntil, overdue (daysUntil < 0), dueToday (daysUntil = 0), remindToday (daysUntil equals one of the item's remindDaysBefore numbers), and inWindow (0 <= daysUntil <= windowDays). Items come back deterministically sorted: soonest (most overdue) first, ties by label. Unknown timezones, impossible dates like 2026-02-30, malformed JSON, out-of-bounds numbers, and oversized lists are rejected - the op never guesses.

  Inputs

  • timezone (string, required) - The IANA timezone id whose civil calendar defines today, e.g. Europe/Berlin. Unknown or invalid zones are rejected.
  • items (string, required) - A JSON array of 0-50 tracked items, e.g. [{"label":"Passport renewal","date":"2027-03-01","remindDaysBefore":[30,7,1]}]. Each item: label (optional text; a long label is kept, truncated for presentation with a trailing ellipsis, and flagged labelTruncated - never rejected), date (required, a REAL calendar date as YYYY-MM-DD), remindDaysBefore (optional, up to 8 unique whole numbers 0-366 meaning days before the date to remind). Datastore-list entries ({key, value, updatedAtMillis}) are accepted verbatim: each entry's stored value is checked as the record, and a broken stored record is skipped and reported instead of failing the batch. An empty array is a valid zero-count check. Pass stored items VERBATIM - directly authored invalid dates are rejected, never repaired.
  • windowDays (number) - Forward horizon in whole days for inWindow membership: 0-366, default 30.

  Returns

  • today (string) - Today's civil date in the given timezone, as YYYY-MM-DD.
  • weekday (string) - Today's weekday in that timezone: mon, tue, wed, thu, fri, sat, or sun.
  • timezone (string) - The validated IANA timezone the calendar math used.
  • items (object) - The checked items sorted soonest-first: each carries label, labelTruncated (true when a long label was shortened for display), date, daysUntil (whole civil days, negative = past), overdue, dueToday, remindToday, and inWindow. Copy these flags VERBATIM.
  • skipped (object) - Stored datastore entries that could not be checked: each carries the record's key (bounded) and a fixed reason. Report skipped entries as broken records to fix - their absence never blocks the checked items.
  • counts (object) - Totals across the returned items: overdue, dueToday, remindToday, inWindow, and skipped.
  • summary (string) - A short human-readable line describing the check.

  Safety rules

  • This op is the ONLY date-math authority: never add, subtract, or compare dates yourself, and never re-derive today.
  • Pass stored dates verbatim. Fail-closed rejections (unknown zone, impossible directly-authored date, malformed JSON, out-of-bounds numbers, oversized lists) mean fix the input or refuse - never guess a date. Broken STORED records come back as skipped entries to report, not errors.
  • Copy daysUntil, overdue, dueToday, remindToday, and inWindow VERBATIM into anything you store, say, or send.