Skip to content

api-javascript.md

Latest commit

 

History

History
322 lines (234 loc) · 8.63 KB

api-javascript.md

File metadata and controls

322 lines (234 loc) · 8.63 KB
Raw

JavaScript API

Reference for the JavaScript and TypeScript package.

The JavaScript package wraps the same Rust engine through WebAssembly. Public methods take and return Date objects. Schedule specs use the same JSON shape as every other binding.

Exports

Name Description
init WebAssembly initialization function.
Schedule Query engine class.
wasm Raw generated WebAssembly module exports.
Weekday Runtime weekday enum object.
Nth Runtime nth-weekday enum object.
Makeup Runtime makeup enum object.
MakeupFailure Runtime makeup-failure enum object.
OverlayRule Runtime overlay-rule enum object.
CalendarId Runtime built-in calendar enum object.
ScheduleSpec TypeScript schedule model type.
Frequency TypeScript frequency union type.
CalendarSpec TypeScript calendar spec union type.
Overlay, AnyOverlay TypeScript overlay types.
OccurrenceTrace { instant: Date, reason: string }.

Initialization

import init, { Schedule } from "dateme";

await init();

init() must resolve before constructing Schedule.

Schedule

Constructor

new Schedule(spec: ScheduleSpec | string, calendarProvider?: CalendarProvider)

Parameters:

Parameter Type Description
spec ScheduleSpec or JSON string Schedule model.
calendarProvider function or object, optional Provider for { custom: "name" } calendars.

The constructor validates the schedule. Malformed JSON, invalid enum values, invalid timezone names, and structural validation failures throw.

const schedule = new Schedule({
  freq: { type: "daily", time: "09:00" },
  timezone: "UTC",
});

Custom Calendar Providers

Custom calendars are referenced in a schedule with { custom: "name" }. Providers receive (name, date) where date is a YYYY-MM-DD string.

A function provider:

const schedule = new Schedule(
  {
    freq: { type: "daily", time: "09:00" },
    timezone: "UTC",
    overlays: [{ calendar: { custom: "shutdown" }, rule: "exclude" }],
  },
  (name, date) => name === "shutdown" && date === "2026-08-14",
);

An object provider:

const provider = {
  contains(name, date) {
    return name === "shutdown" && date === "2026-08-14";
  },
};

const schedule = new Schedule(spec, provider);

Missing custom calendar values are treated as absent from the set.

Date Handling

Rule Behavior
Input dates JavaScript Date objects.
Returned values JavaScript Date objects.
Optional anchors Default to new Date().
Query bounds Strict: occurrences exactly at after or before are excluded.
WASM bridge The wrapper converts Date values to epoch milliseconds.

Methods

validate

schedule.validate(): void

Re-runs structural validation. Throws on failure.

schedule.validate();

toObject

schedule.toObject(): ScheduleSpec

Returns the schedule as a plain object.

const spec = schedule.toObject();

toJSON

schedule.toJSON(): ScheduleSpec

Returns the schedule as a plain object for JSON.stringify.

JSON.stringify(schedule);

next

schedule.next(after = new Date()): Date | null

Returns the first occurrence strictly after after.

const after = new Date("2026-01-13T00:00:00Z");
schedule.next(after);

previous

schedule.previous(before = new Date()): Date | null

Returns the last occurrence strictly before before.

schedule.previous(new Date("2026-01-13T00:00:00Z"));

until

schedule.until(before: Date, after = new Date()): Date[]

Returns occurrences in (after, before), ascending.

schedule.until(new Date("2026-02-01T00:00:00Z"), after);

since

schedule.since(after: Date, before = new Date()): Date[]

Returns occurrences in (after, before), descending.

schedule.since(new Date("2026-01-01T00:00:00Z"));

upcoming

schedule.upcoming(n: number, after = new Date()): Date[]

Returns the next n occurrences strictly after after, ascending.

schedule.upcoming(5, after);

Trace Methods

Trace methods return OccurrenceTrace values.

Method Return type Order
nextTrace(after = new Date()) OccurrenceTrace | null —
previousTrace(before = new Date()) OccurrenceTrace | null —
untilTrace(before, after = new Date()) OccurrenceTrace[] ascending
sinceTrace(after, before = new Date()) OccurrenceTrace[] descending
upcomingTrace(n, after = new Date()) OccurrenceTrace[] ascending

Reason strings include:

Reason form Meaning
base Base occurrence was kept.
makeup_from(YYYY-MM-DD) Occurrence was moved from the local date.
base,shifted_dst Base occurrence was shifted through DST gap.
makeup_from(...),shifted_dst Made-up occurrence was shifted through DST gap. 
const trace = schedule.nextTrace(after);
// { instant: Date, reason: "base" }

isOccurrence

schedule.isOccurrence(instant: Date): boolean

Returns whether instant is an occurrence of the schedule.

schedule.isOccurrence(new Date("2026-01-20T22:30:00Z"));

countBetween

schedule.countBetween(after: Date, before: Date): number

Returns the number of occurrences strictly in (after, before).

schedule.countBetween(after, new Date("2026-02-01T00:00:00Z"));

describe

schedule.describe(): string

Returns a human-readable summary of the base recurrence, timezone, overlay count, and makeup presence.

schedule.describe();
// "Every Monday at 17:30 America/New_York, with 1 overlay(s), with makeup"

Iteration

schedule[Symbol.iterator](): IterableIterator<Date>
schedule.iterBetween(after: Date, before: Date): IterableIterator<Date>
schedule.iterUpcoming(n: number, after = new Date()): IterableIterator<Date>

for...of requires the schedule to have an end bound. It starts from start, or from the current time when start is absent.

for (const instant of boundedSchedule) {
  console.log(instant.toISOString());
}

Array.from(schedule.iterBetween(after, new Date("2026-02-01T00:00:00Z")));
Array.from(schedule.iterUpcoming(3, after));

TypeScript Model

The package exports TypeScript types that mirror the Schedule model.

import init, {
  Schedule,
  Weekday,
  CalendarId,
  OverlayRule,
  Makeup,
} from "dateme";
import type { ScheduleSpec } from "dateme";

const spec: ScheduleSpec = {
  freq: { type: "weekly", days: [Weekday.Mon], time: "17:30" },
  timezone: "America/New_York",
  overlays: [{ calendar: CalendarId.NyseHoliday, rule: OverlayRule.Exclude }],
  makeup: Makeup.After,
};

await init();
const schedule = new Schedule(spec);

Type families:

Family Types or values
Frequencies Frequency union with all schedule frequency variants.
Calendar specs CalendarSpec, CalendarId.
Overlays Overlay, AnyOverlay, OverlayRule.
Makeup Makeup, MakeupFailure, MakeupStep, WeekdayMakeup.
Date helpers MonthDay, NthWeekday, Nth, Weekday.