calendaryjs 0.2.2 → 0.2.3

package/dist/builder/index.cjs

@@ -0,0 +1,338 @@
+'use strict';
+
+// src/builder/builder.ts
+function date(month, day) {
+  return { type: "const", fields: { month, day } };
+}
+var WEEKDAYS = {
+  sunday: 0,
+  monday: 1,
+  tuesday: 2,
+  wednesday: 3,
+  thursday: 4,
+  friday: 5,
+  saturday: 6
+};
+var MONTHS = {
+  jan: 1,
+  feb: 2,
+  mar: 3,
+  apr: 4,
+  may: 5,
+  jun: 6,
+  jul: 7,
+  aug: 8,
+  sep: 9,
+  oct: 10,
+  nov: 11,
+  dec: 12
+};
+function nth(n, weekday, month) {
+  const m = typeof month === "number" ? month : MONTHS[month];
+  if (!m) throw new Error(`unknown month "${month}"`);
+  return { type: "nth-weekday", fields: { nth: n, dayOfWeek: WEEKDAYS[weekday], month: m } };
+}
+var PLURAL = {
+  days: "day",
+  weeks: "week",
+  months: "month",
+  years: "year"
+};
+var BaseBuilder = class {
+  payload = {};
+  explicitId;
+  title(value) {
+    this.payload.title = value;
+    return this;
+  }
+  id(value) {
+    this.explicitId = value;
+    return this;
+  }
+  priority(value) {
+    this.payload.priority = value;
+    return this;
+  }
+  description(value) {
+    this.payload.description = value;
+    return this;
+  }
+  location(value) {
+    this.payload.location = value;
+    return this;
+  }
+  url(value) {
+    this.payload.url = value;
+    return this;
+  }
+  color(value) {
+    this.payload.color = value;
+    return this;
+  }
+  icon(value) {
+    this.payload.icon = value;
+    return this;
+  }
+  source(value) {
+    this.payload.source = value;
+    return this;
+  }
+  status(value) {
+    this.payload.status = value;
+    return this;
+  }
+  allDay(value = true) {
+    this.payload.allDay = value;
+    return this;
+  }
+  /** Clock time(s): `.at("09:00")` or `.at("09:00", "10:30")`. */
+  at(start, end) {
+    this.payload.startTime = start;
+    if (end) this.payload.endTime = end;
+    return this;
+  }
+  /** Duration in minutes. */
+  duration(minutes) {
+    this.payload.duration = minutes;
+    return this;
+  }
+  keywords(...values) {
+    this.payload.keywords = values;
+    return this;
+  }
+  categories(...values) {
+    this.payload.categories = values;
+    return this;
+  }
+  /** Merge arbitrary metadata (later calls override earlier keys). */
+  metadata(data) {
+    const prev = this.payload.metadata ?? {};
+    this.payload.metadata = { ...prev, ...data };
+    return this;
+  }
+  /** A lead-time reminder before the occurrence. Accumulates. */
+  remind(before, opts) {
+    const trigger = (before.minutes ?? 0) + (before.hours ?? 0) * 60 + (before.days ?? 0) * 1440;
+    const reminders = this.payload.reminders ?? [];
+    reminders.push({
+      type: opts?.type ?? "notification",
+      trigger,
+      ...opts?.message ? { message: opts.message } : {}
+    });
+    this.payload.reminders = reminders;
+    return this;
+  }
+  /** Drop one occurrence (by its original date) → ICS EXDATE. */
+  skip(date2) {
+    this.exceptions()[date2] = { skip: true };
+    return this;
+  }
+  /** Replace properties for one occurrence → ICS RECURRENCE-ID. */
+  override(date2, props) {
+    this.exceptions()[date2] = { override: props };
+    return this;
+  }
+  /** Force-move one occurrence to another date. */
+  reschedule(fromDate, toDate) {
+    const map = this.payload.overrideDates ?? {};
+    map[fromDate] = toDate;
+    this.payload.overrideDates = map;
+    return this;
+  }
+  exceptions() {
+    const map = this.payload.exceptions ?? {};
+    this.payload.exceptions = map;
+    return map;
+  }
+  /** Explicit id, else a slug of the title, else throw. */
+  resolveId() {
+    const title = this.payload.title;
+    const id = this.explicitId ?? (title ? slug(title) : void 0);
+    if (!id) {
+      throw new Error("an event needs an .id(...), or a .title(...) to derive its id from");
+    }
+    return id;
+  }
+};
+var EventBuilder = class extends BaseBuilder {
+  constructor(unit, interval) {
+    super();
+    this.unit = unit;
+    this.interval = interval;
+  }
+  unit;
+  interval;
+  selectorType;
+  fields = {};
+  on(...selectors) {
+    if (selectors.length > 1 || typeof selectors[0] === "string") {
+      if (!selectors.every((s) => typeof s === "string")) {
+        throw new Error(`.on(...) lists weekdays together with non-weekday selectors`);
+      }
+      if (this.unit !== "week") {
+        throw new Error(`.on("${selectors[0]}") (a weekday) needs every("week")`);
+      }
+      const indices = selectors.map((w) => {
+        if (!(w in WEEKDAYS)) throw new Error(`unknown weekday "${w}"`);
+        return WEEKDAYS[w];
+      });
+      const unique = [...new Set(indices)].sort((a, b) => a - b);
+      this.selectorType = "weekly";
+      this.fields.dayOfWeek = unique.length === 1 ? unique[0] : unique;
+      return this;
+    }
+    const selector = selectors[0];
+    if (typeof selector === "number") {
+      if (this.unit !== "month") {
+        throw new Error(`.on(${selector}) (a day of month) needs every("month")`);
+      }
+      this.selectorType = "monthly";
+      this.fields.day = selector;
+      return this;
+    }
+    const sel = selector;
+    if (this.unit !== "year") throw new Error(`.on(<selector>) needs every("year")`);
+    this.selectorType = sel.type;
+    Object.assign(this.fields, sel.fields);
+    return this;
+  }
+  /** Bound the recurrence: numbers → year range, date strings → date range. */
+  between(start, end) {
+    if (typeof start === "number") {
+      this.fields.startYear = start;
+      this.fields.endYear = end;
+    } else {
+      this.fields.startDate = start;
+      this.fields.endDate = end;
+    }
+    return this;
+  }
+  /** Upper bound only: a number → endYear, a date string → endDate. */
+  until(end) {
+    if (typeof end === "number") this.fields.endYear = end;
+    else this.fields.endDate = end;
+    return this;
+  }
+  exceptYears(...years) {
+    this.fields.excludeYears = years;
+    return this;
+  }
+  exceptMonths(...months) {
+    this.fields.excludeMonths = months;
+    return this;
+  }
+  exceptDates(...dates) {
+    this.fields.excludeDates = dates;
+    return this;
+  }
+  build() {
+    if (!this.selectorType) {
+      throw new Error(`every("${this.unit}") needs a position \u2014 call .on(...)`);
+    }
+    const config = {
+      type: this.selectorType,
+      id: this.resolveId(),
+      ...this.fields,
+      ...this.payload
+    };
+    if (this.interval > 1) {
+      if (this.selectorType !== "weekly" && this.selectorType !== "monthly") {
+        throw new Error(
+          `every(${this.interval}, \u2026) is not supported for "${this.selectorType}" yet`
+        );
+      }
+      config.interval = this.interval;
+    }
+    return config;
+  }
+};
+var RelativeBuilder = class extends BaseBuilder {
+  constructor(anchor) {
+    super();
+    this.anchor = anchor;
+  }
+  anchor;
+  days = 0;
+  weeks = 0;
+  plus(offset) {
+    this.days += offset.days ?? 0;
+    this.weeks += offset.weeks ?? 0;
+    return this;
+  }
+  minus(offset) {
+    this.days -= offset.days ?? 0;
+    this.weeks -= offset.weeks ?? 0;
+    return this;
+  }
+  build() {
+    const offset = {};
+    if (this.days) offset.days = this.days;
+    if (this.weeks) offset.weeks = this.weeks;
+    return {
+      type: "relative",
+      id: this.resolveId(),
+      anchor: this.anchor,
+      offset,
+      ...this.payload
+    };
+  }
+};
+var FixedBuilder = class extends BaseBuilder {
+  constructor(dateStr) {
+    super();
+    this.dateStr = dateStr;
+  }
+  dateStr;
+  build() {
+    const [year, month, day] = this.dateStr.split("-").map(Number);
+    if (!year || !month || !day) {
+      throw new Error(`once("${this.dateStr}") needs a YYYY-MM-DD date`);
+    }
+    return {
+      type: "fixed",
+      id: this.resolveId(),
+      year,
+      month,
+      day,
+      ...this.payload
+    };
+  }
+};
+function every(a, b) {
+  if (typeof a === "number") {
+    const unit = PLURAL[b];
+    if (!unit) throw new Error(`unknown unit "${b}"`);
+    return new EventBuilder(unit, a);
+  }
+  return new EventBuilder(a, 1);
+}
+function from(anchor) {
+  return new RelativeBuilder(anchor);
+}
+function once(dateStr) {
+  return new FixedBuilder(dateStr);
+}
+function weekly(weekday, ...moreWeekdays) {
+  return every("week").on(weekday, ...moreWeekdays);
+}
+function monthly(day) {
+  return every("month").on(day);
+}
+function yearly(month, day) {
+  return every("year").on(date(month, day));
+}
+function slug(value) {
+  return value.toLowerCase().replace(/đ/g, "d").normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "event";
+}
+
+exports.EventBuilder = EventBuilder;
+exports.FixedBuilder = FixedBuilder;
+exports.RelativeBuilder = RelativeBuilder;
+exports.date = date;
+exports.every = every;
+exports.from = from;
+exports.monthly = monthly;
+exports.nth = nth;
+exports.once = once;
+exports.weekly = weekly;
+exports.yearly = yearly;

package/dist/builder/index.d.cts

@@ -0,0 +1,153 @@
+import { E as EventConfig } from '../events-Bm7R9XFB.cjs';
+
+/**
+ * A position selector — passed to {@link EventBuilder.on}. It contributes the
+ * event `type` and its position fields. A plugin extends the `.on()` vocabulary
+ * simply by exporting a function that returns one (e.g. `pluginThing(a, b)` →
+ * `{ type: "plugin-type", fields: { ... } }`), so the builder hard-codes no
+ * calendar system.
+ */
+interface Selector {
+    type: string;
+    fields: Record<string, unknown>;
+}
+/** Annual position → a `const` event. `date(12, 25)` = December 25th. */
+declare function date(month: number, day: number): Selector;
+declare const WEEKDAYS: {
+    readonly sunday: 0;
+    readonly monday: 1;
+    readonly tuesday: 2;
+    readonly wednesday: 3;
+    readonly thursday: 4;
+    readonly friday: 5;
+    readonly saturday: 6;
+};
+type Weekday = keyof typeof WEEKDAYS;
+declare const MONTHS: {
+    readonly jan: 1;
+    readonly feb: 2;
+    readonly mar: 3;
+    readonly apr: 4;
+    readonly may: 5;
+    readonly jun: 6;
+    readonly jul: 7;
+    readonly aug: 8;
+    readonly sep: 9;
+    readonly oct: 10;
+    readonly nov: 11;
+    readonly dec: 12;
+};
+type MonthName = keyof typeof MONTHS;
+/** Annual position → an `nth-weekday` event: `nth(2, "sunday", "may")`. */
+declare function nth(n: 1 | 2 | 3 | 4 | -1, weekday: Weekday, month: MonthName | number): Selector;
+type Unit = "day" | "week" | "month" | "year";
+declare const PLURAL: Record<string, Unit>;
+/** Shared payload + id tail for every builder. */
+declare abstract class BaseBuilder {
+    protected readonly payload: Record<string, unknown>;
+    protected explicitId?: string;
+    title(value: string): this;
+    id(value: string): this;
+    priority(value: number): this;
+    description(value: string): this;
+    location(value: string): this;
+    url(value: string): this;
+    color(value: string): this;
+    icon(value: string): this;
+    source(value: string): this;
+    status(value: "confirmed" | "tentative" | "cancelled"): this;
+    allDay(value?: boolean): this;
+    /** Clock time(s): `.at("09:00")` or `.at("09:00", "10:30")`. */
+    at(start: string, end?: string): this;
+    /** Duration in minutes. */
+    duration(minutes: number): this;
+    keywords(...values: string[]): this;
+    categories(...values: string[]): this;
+    /** Merge arbitrary metadata (later calls override earlier keys). */
+    metadata(data: Record<string, unknown>): this;
+    /** A lead-time reminder before the occurrence. Accumulates. */
+    remind(before: {
+        minutes?: number;
+        hours?: number;
+        days?: number;
+    }, opts?: {
+        type?: "notification" | "email";
+        message?: string;
+    }): this;
+    /** Drop one occurrence (by its original date) → ICS EXDATE. */
+    skip(date: string): this;
+    /** Replace properties for one occurrence → ICS RECURRENCE-ID. */
+    override(date: string, props: Record<string, unknown>): this;
+    /** Force-move one occurrence to another date. */
+    reschedule(fromDate: string, toDate: string): this;
+    private exceptions;
+    /** Explicit id, else a slug of the title, else throw. */
+    protected resolveId(): string;
+    abstract build(): EventConfig;
+}
+/**
+ * Recurring/positional builder. The clause order mirrors the engine pipeline:
+ * cadence (`every`) → position (`.on`) → payload (`.title`/`.id`/…) → `build()`.
+ */
+declare class EventBuilder extends BaseBuilder {
+    private readonly unit;
+    private readonly interval;
+    private selectorType?;
+    private readonly fields;
+    constructor(unit: Unit, interval: number);
+    /**
+     * Position within the cadence: a weekday name (or several), a day-of-month, or
+     * a selector. Several weekdays make a multi-day weekly — `every("week").on(
+     * "monday","wednesday","friday")` — fired on each, like an alarm's "Repeat".
+     */
+    on(weekday: Weekday, ...moreWeekdays: Weekday[]): this;
+    on(selector: Selector | number): this;
+    /** Bound the recurrence: numbers → year range, date strings → date range. */
+    between(start: number | string, end: number | string): this;
+    /** Upper bound only: a number → endYear, a date string → endDate. */
+    until(end: number | string): this;
+    exceptYears(...years: number[]): this;
+    exceptMonths(...months: number[]): this;
+    exceptDates(...dates: string[]): this;
+    build(): EventConfig;
+}
+/** Anchored builder: a date computed as an offset from a named anchor. */
+declare class RelativeBuilder extends BaseBuilder {
+    private readonly anchor;
+    private days;
+    private weeks;
+    constructor(anchor: string);
+    plus(offset: {
+        days?: number;
+        weeks?: number;
+    }): this;
+    minus(offset: {
+        days?: number;
+        weeks?: number;
+    }): this;
+    build(): EventConfig;
+}
+/** One-time builder: a single fixed date. */
+declare class FixedBuilder extends BaseBuilder {
+    private readonly dateStr;
+    constructor(dateStr: string);
+    build(): EventConfig;
+}
+/** Start a recurring event: `every("year")` or `every(2, "weeks")`. */
+declare function every(unit: Unit): EventBuilder;
+declare function every(interval: number, unit: keyof typeof PLURAL): EventBuilder;
+/** Start a date relative to a registered anchor: `from("anchor").plus({ days: 49 })`. */
+declare function from(anchor: string): RelativeBuilder;
+/** A single fixed date: `once("2025-06-15")`. */
+declare function once(dateStr: string): FixedBuilder;
+/**
+ * `weekly("tuesday")` = `every("week").on("tuesday")`. Pass several weekdays for
+ * a multi-day weekly: `weekly("monday","wednesday","friday")`.
+ */
+declare function weekly(weekday: Weekday, ...moreWeekdays: Weekday[]): EventBuilder;
+/** `monthly(15)` = `every("month").on(15)`. */
+declare function monthly(day: number): EventBuilder;
+/** `yearly(12, 25)` = `every("year").on(date(12, 25))`. */
+declare function yearly(month: number, day: number): EventBuilder;
+
+export { EventBuilder, FixedBuilder, type MonthName, RelativeBuilder, type Selector, type Weekday, date, every, from, monthly, nth, once, weekly, yearly };

package/dist/builder/index.d.ts

@@ -0,0 +1,153 @@
+import { E as EventConfig } from '../events-Bm7R9XFB.js';
+
+/**
+ * A position selector — passed to {@link EventBuilder.on}. It contributes the
+ * event `type` and its position fields. A plugin extends the `.on()` vocabulary
+ * simply by exporting a function that returns one (e.g. `pluginThing(a, b)` →
+ * `{ type: "plugin-type", fields: { ... } }`), so the builder hard-codes no
+ * calendar system.
+ */
+interface Selector {
+    type: string;
+    fields: Record<string, unknown>;
+}
+/** Annual position → a `const` event. `date(12, 25)` = December 25th. */
+declare function date(month: number, day: number): Selector;
+declare const WEEKDAYS: {
+    readonly sunday: 0;
+    readonly monday: 1;
+    readonly tuesday: 2;
+    readonly wednesday: 3;
+    readonly thursday: 4;
+    readonly friday: 5;
+    readonly saturday: 6;
+};
+type Weekday = keyof typeof WEEKDAYS;
+declare const MONTHS: {
+    readonly jan: 1;
+    readonly feb: 2;
+    readonly mar: 3;
+    readonly apr: 4;
+    readonly may: 5;
+    readonly jun: 6;
+    readonly jul: 7;
+    readonly aug: 8;
+    readonly sep: 9;
+    readonly oct: 10;
+    readonly nov: 11;
+    readonly dec: 12;
+};
+type MonthName = keyof typeof MONTHS;
+/** Annual position → an `nth-weekday` event: `nth(2, "sunday", "may")`. */
+declare function nth(n: 1 | 2 | 3 | 4 | -1, weekday: Weekday, month: MonthName | number): Selector;
+type Unit = "day" | "week" | "month" | "year";
+declare const PLURAL: Record<string, Unit>;
+/** Shared payload + id tail for every builder. */
+declare abstract class BaseBuilder {
+    protected readonly payload: Record<string, unknown>;
+    protected explicitId?: string;
+    title(value: string): this;
+    id(value: string): this;
+    priority(value: number): this;
+    description(value: string): this;
+    location(value: string): this;
+    url(value: string): this;
+    color(value: string): this;
+    icon(value: string): this;
+    source(value: string): this;
+    status(value: "confirmed" | "tentative" | "cancelled"): this;
+    allDay(value?: boolean): this;
+    /** Clock time(s): `.at("09:00")` or `.at("09:00", "10:30")`. */
+    at(start: string, end?: string): this;
+    /** Duration in minutes. */
+    duration(minutes: number): this;
+    keywords(...values: string[]): this;
+    categories(...values: string[]): this;
+    /** Merge arbitrary metadata (later calls override earlier keys). */
+    metadata(data: Record<string, unknown>): this;
+    /** A lead-time reminder before the occurrence. Accumulates. */
+    remind(before: {
+        minutes?: number;
+        hours?: number;
+        days?: number;
+    }, opts?: {
+        type?: "notification" | "email";
+        message?: string;
+    }): this;
+    /** Drop one occurrence (by its original date) → ICS EXDATE. */
+    skip(date: string): this;
+    /** Replace properties for one occurrence → ICS RECURRENCE-ID. */
+    override(date: string, props: Record<string, unknown>): this;
+    /** Force-move one occurrence to another date. */
+    reschedule(fromDate: string, toDate: string): this;
+    private exceptions;
+    /** Explicit id, else a slug of the title, else throw. */
+    protected resolveId(): string;
+    abstract build(): EventConfig;
+}
+/**
+ * Recurring/positional builder. The clause order mirrors the engine pipeline:
+ * cadence (`every`) → position (`.on`) → payload (`.title`/`.id`/…) → `build()`.
+ */
+declare class EventBuilder extends BaseBuilder {
+    private readonly unit;
+    private readonly interval;
+    private selectorType?;
+    private readonly fields;
+    constructor(unit: Unit, interval: number);
+    /**
+     * Position within the cadence: a weekday name (or several), a day-of-month, or
+     * a selector. Several weekdays make a multi-day weekly — `every("week").on(
+     * "monday","wednesday","friday")` — fired on each, like an alarm's "Repeat".
+     */
+    on(weekday: Weekday, ...moreWeekdays: Weekday[]): this;
+    on(selector: Selector | number): this;
+    /** Bound the recurrence: numbers → year range, date strings → date range. */
+    between(start: number | string, end: number | string): this;
+    /** Upper bound only: a number → endYear, a date string → endDate. */
+    until(end: number | string): this;
+    exceptYears(...years: number[]): this;
+    exceptMonths(...months: number[]): this;
+    exceptDates(...dates: string[]): this;
+    build(): EventConfig;
+}
+/** Anchored builder: a date computed as an offset from a named anchor. */
+declare class RelativeBuilder extends BaseBuilder {
+    private readonly anchor;
+    private days;
+    private weeks;
+    constructor(anchor: string);
+    plus(offset: {
+        days?: number;
+        weeks?: number;
+    }): this;
+    minus(offset: {
+        days?: number;
+        weeks?: number;
+    }): this;
+    build(): EventConfig;
+}
+/** One-time builder: a single fixed date. */
+declare class FixedBuilder extends BaseBuilder {
+    private readonly dateStr;
+    constructor(dateStr: string);
+    build(): EventConfig;
+}
+/** Start a recurring event: `every("year")` or `every(2, "weeks")`. */
+declare function every(unit: Unit): EventBuilder;
+declare function every(interval: number, unit: keyof typeof PLURAL): EventBuilder;
+/** Start a date relative to a registered anchor: `from("anchor").plus({ days: 49 })`. */
+declare function from(anchor: string): RelativeBuilder;
+/** A single fixed date: `once("2025-06-15")`. */
+declare function once(dateStr: string): FixedBuilder;
+/**
+ * `weekly("tuesday")` = `every("week").on("tuesday")`. Pass several weekdays for
+ * a multi-day weekly: `weekly("monday","wednesday","friday")`.
+ */
+declare function weekly(weekday: Weekday, ...moreWeekdays: Weekday[]): EventBuilder;
+/** `monthly(15)` = `every("month").on(15)`. */
+declare function monthly(day: number): EventBuilder;
+/** `yearly(12, 25)` = `every("year").on(date(12, 25))`. */
+declare function yearly(month: number, day: number): EventBuilder;
+
+export { EventBuilder, FixedBuilder, type MonthName, RelativeBuilder, type Selector, type Weekday, date, every, from, monthly, nth, once, weekly, yearly };