```{toctree}
---
maxdepth: 2
hidden: true
---



docs/src/tutorial.md

docs/src/how-to.md

docs/src/schedule-model.md

docs/src/api-python.md

docs/src/api-javascript.md

docs/src/explanation.md


```

# dateme

Dates and intervals.

[![Build Status](https://github.com/1kbgz/dateme/actions/workflows/build.yaml/badge.svg?branch=main&event=push)](https://github.com/1kbgz/dateme/actions/workflows/build.yaml)
[![codecov](https://codecov.io/gh/1kbgz/dateme/branch/main/graph/badge.svg)](https://codecov.io/gh/1kbgz/dateme)
[![License](https://img.shields.io/github/license/1kbgz/dateme)](https://github.com/1kbgz/dateme)
[![PyPI](https://img.shields.io/pypi/v/dateme.svg)](https://pypi.python.org/pypi/dateme)

`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.

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

## Install

```bash
pip install dateme
```

For JavaScript development from this repository:

```bash
cd js
pnpm install
pnpm build
```

## Quick Python Example

```python
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

```js
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](docs/src/tutorial.md): a first working schedule.
- [How-to guides](docs/src/how-to.md): recipes for market calendars, makeup,
  custom calendars, traces, iteration, and persistence.
- [Schedule model](docs/src/schedule-model.md): complete JSON reference.
- [Python API](docs/src/api-python.md): constructors, query methods, typed
  builders, providers, traces, and iteration.
- [JavaScript API](docs/src/api-javascript.md): WebAssembly initialization,
  methods, TypeScript types, providers, traces, and iteration.
- [How the engine works](docs/src/explanation.md): 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.

> [!NOTE]
> This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).