dateme

Dates and intervals.

dateme is a recurrence and scheduling engine. Given a schedule JSON object, it computes occurrence instants with timezone handling, calendar overlays, makeup rules, bounds, traces, and bindings for Python and JavaScript.

{
  "freq": { "type": "weekly", "days": ["mon"], "time": "17:30" },
  "timezone": "America/New_York",
  "overlays": [{ "calendar": "nyse_holiday", "rule": "exclude" }],
  "makeup": "after"
}

Install

pip install dateme

For JavaScript development from this repository:

cd js
pnpm install
pnpm build

Quick Python Example

from datetime import datetime, timezone
from dateme import Schedule

schedule = Schedule({
    "freq": {"type": "weekly", "days": ["mon"], "time": "17:30"},
    "timezone": "America/New_York",
    "overlays": [{"calendar": "nyse_holiday", "rule": "exclude"}],
    "makeup": "after",
})

after = datetime(2026, 1, 13, tzinfo=timezone.utc)
schedule.next(after)
# datetime.datetime(2026, 1, 20, 22, 30, tzinfo=datetime.timezone.utc)

Quick JavaScript Example

import init, { Schedule } from "dateme";

await init();

const schedule = new Schedule({
  freq: { type: "weekly", days: ["mon"], time: "17:30" },
  timezone: "America/New_York",
  overlays: [{ calendar: "nyse_holiday", rule: "exclude" }],
  makeup: "after",
});

schedule.next(new Date("2026-01-13T00:00:00Z"));
// 2026-01-20T22:30:00.000Z

Documentation

• Getting started: a first working schedule.
• How-to guides: recipes for market calendars, makeup, custom calendars, traces, iteration, and persistence.
• Schedule model: complete JSON reference.
• Python API: constructors, query methods, typed builders, providers, traces, and iteration.
• JavaScript API: WebAssembly initialization, methods, TypeScript types, providers, traces, and iteration.
• How the engine works: background on recurrence generation, overlays, makeup, DST, bounds, and termination.

Supported Schedule Features

• Frequencies: hourly, daily, weekly, every_n_days, every_n_weeks, monthly_by_day, monthly_by_weekday, yearly, quarterly, custom_cron.
• Calendars: US federal holidays/business days, NYSE holidays/trading days, inline date sets, unions, differences, and custom providers.
• Makeup rules: none, before, after, nearest, weekday maps, cascades, hop limits, failure modes, weekday constraints, same-week constraints, weekend exclusion, and next-occurrence bounds.
• Queries: next, previous, until, since, upcoming, trace variants, occurrence membership, counts, descriptions, and bounded iteration.