@contalert/duedates 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ContAlert Sistemas Ltda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# duedates
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Recurring deadlines that respect weekends, holidays and month boundaries.**
+
+`duedates` answers the questions every billing, payroll, compliance and reminder system eventually has to answer:
+
+- *"Invoices are due on the 20th — but what if the 20th is a Sunday?"*
+- *"When is the 5th business day of next month?"*
+- *"Which dates should we send reminders on, 7, 3 and 1 business days before?"*
+
+[![CI](https://github.com/contalert/duedates/actions/workflows/ci.yml/badge.svg)](https://github.com/contalert/duedates/actions/workflows/ci.yml)
+![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+![license MIT](https://img.shields.io/badge/license-MIT-blue)
+
+## Why
+
+- **Time-zone safe.** Dates are plain `YYYY-MM-DD` strings and all math is integer day arithmetic. No `Date` object can shift your deadline by a day because of a time zone or daylight saving time.
+- **Real-world conventions.** Following, preceding, *modified following* and *modified preceding* — the same business-day conventions used in finance.
+- **Any country.** Choose your weekend (e.g. Friday–Saturday) and bring your own holidays: a list of dates or a function.
+- **Zero dependencies**, fully typed, ESM, tiny.
+
+## Install
+
+```sh
+npm install @contalert/duedates
+```
+
+Requires Node.js 20 or later (or any modern browser or runtime).
+
+## Quick start
+
+```ts
+import { createCalendar, occurrences, reminderDates } from '@contalert/duedates';
+
+const calendar = createCalendar({
+  holidays: ['2026-12-25', '2027-01-01'],
+});
+
+// "Due on the 20th of every month; if that's not a business day, the next one."
+const deadlines = occurrences(
+  { type: 'dayOfMonth', day: 20, adjust: 'following' },
+  { from: '2026-11-03', count: 3, calendar },
+);
+// [
+//   { nominal: '2026-11-20', due: '2026-11-20' },
+//   { nominal: '2026-12-20', due: '2026-12-21' },  ← Sunday moved to Monday
+//   { nominal: '2027-01-20', due: '2027-01-20' },
+// ]
+
+reminderDates('2026-12-21', [7, 3, 1], { calendar });
+// ['2026-12-10', '2026-12-16', '2026-12-18']
+```
+
+## Rules
+
+Every rule produces a **nominal** date (what the rule says) and a **due** date (after adjusting for non-business days).
+
+| Rule | Example | Meaning |
+|---|---|---|
+| `dayOfMonth` | `{ type: 'dayOfMonth', day: 20 }` | The 20th of every month. Days past the end of a month use its last day (31 → 28/29 Feb). |
+| | `{ type: 'dayOfMonth', day: 'last' }` | The last day of every month. |
+| `weekdayOfMonth` | `{ type: 'weekdayOfMonth', weekday: 2, nth: 2 }` | The second Tuesday of every month. |
+| | `{ type: 'weekdayOfMonth', weekday: 5, nth: -1 }` | The last Friday of every month. |
+| `businessDayOfMonth` | `{ type: 'businessDayOfMonth', n: 5 }` | The 5th business day of every month. |
+| | `{ type: 'businessDayOfMonth', n: -1 }` | The last business day of every month. |
+| `weekly` | `{ type: 'weekly', weekday: 1 }` | Every Monday. |
+
+Weekdays follow ISO 8601: `1` = Monday … `7` = Sunday.
+
+Monthly rules accept `months` to run only in some months:
+
+```ts
+// Quarterly: last day of March, June, September and December
+{ type: 'dayOfMonth', day: 'last', months: [3, 6, 9, 12] }
+
+// Yearly: April 15th
+{ type: 'dayOfMonth', day: 15, months: [4] }
+```
+
+### Adjustments
+
+All rules except `businessDayOfMonth` (which is always a business day) accept `adjust`:
+
+| `adjust` | When the date is not a business day… |
+|---|---|
+| `'none'` *(default)* | keep it. |
+| `'following'` | move to the next business day. |
+| `'preceding'` | move to the previous business day. |
+| `'modifiedFollowing'` | move forward, unless that crosses into the next month — then move back. |
+| `'modifiedPreceding'` | move back, unless that crosses into the previous month — then move forward. |
+
+## API
+
+### `occurrences(rule, { from, to?, count?, calendar? })`
+
+Returns `{ nominal, due }[]` for every occurrence whose due date is on or after `from`, stopping at `to` (inclusive), after `count` results, or both. At least one of `to` and `count` is required.
+
+### `nextDue(rule, { from, calendar? })`
+
+The first occurrence due on or after `from`.
+
+### `createCalendar({ weekend?, holidays? })`
+
+- `weekend` — weekdays that are never business days. Default `[6, 7]` (Saturday, Sunday).
+- `holidays` — an iterable of `YYYY-MM-DD` strings, or a function `(date) => boolean`.
+
+The calendar has:
+
+| Method | |
+|---|---|
+| `isBusinessDay(date)` / `isWeekend(date)` / `isHoliday(date)` | Checks a date. |
+| `adjust(date, adjustment)` | Applies one of the adjustments above. |
+| `addBusinessDays(date, n)` | Moves `n` business days forward (or back, if negative). |
+| `businessDaysBetween(start, end)` | Business days after `start` up to and including `end`. |
+
+### `reminderDates(due, offsets, { unit?, calendar? })`
+
+The dates to send reminders on, `offsets` days before `due`, sorted and de-duplicated. `unit` is `'businessDays'` (default) or `'calendarDays'`.
+
+### Date helpers
+
+`addDays(date, n)`, `weekdayOf(date)`, `daysInMonth(year, month)`, `isLeapYear(year)`, `isValidDate(value)` and `today(timeZone?)` — for example `today('America/New_York')`.
+
+Invalid input (a date that doesn't exist, an unknown rule, …) throws a `RangeError` with a clear message.
+
+## Holidays for your country
+
+`duedates` doesn't ship holiday data — holiday rules change, and you know which ones apply to you. Pass a list, or plug in any holiday library. For example, with [`date-holidays`](https://www.npmjs.com/package/date-holidays):
+
+```ts
+import Holidays from 'date-holidays';
+import { createCalendar } from '@contalert/duedates';
+
+const us = new Holidays('US');
+
+const calendar = createCalendar({
+  holidays: (date) => {
+    const found = us.isHoliday(new Date(`${date}T12:00:00`));
+    return Array.isArray(found) && found.some((holiday) => holiday.type === 'public');
+  },
+});
+```
+
+## Contributing
+
+Issues and pull requests are welcome. Run `npm test` and `npm run typecheck` before opening a pull request. Please report security issues privately — see [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © ContAlert Sistemas Ltda

package/dist/calendar.d.ts

@@ -0,0 +1,31 @@
+import { type DateString, type Weekday } from './date.js';
+/**
+ * How a date that falls on a non-business day is moved.
+ *
+ * - `none` — keep the date as is.
+ * - `following` — move forward to the next business day.
+ * - `preceding` — move back to the previous business day.
+ * - `modifiedFollowing` — move forward, unless that changes the month; then move back.
+ * - `modifiedPreceding` — move back, unless that changes the month; then move forward.
+ */
+export type Adjustment = 'none' | 'following' | 'preceding' | 'modifiedFollowing' | 'modifiedPreceding';
+export declare const ADJUSTMENTS: readonly Adjustment[];
+export interface CalendarOptions {
+    /** Weekdays that are never business days (1 = Monday … 7 = Sunday). Defaults to `[6, 7]`. */
+    weekend?: readonly Weekday[];
+    /** Holidays, as a list of dates or a function that returns `true` for a holiday. */
+    holidays?: Iterable<DateString> | ((date: DateString) => boolean);
+}
+export interface Calendar {
+    isWeekend(date: DateString): boolean;
+    isHoliday(date: DateString): boolean;
+    /** Neither a weekend day nor a holiday. */
+    isBusinessDay(date: DateString): boolean;
+    /** Moves a date that is not a business day, following the given convention. */
+    adjust(date: DateString, adjustment: Adjustment): DateString;
+    /** Adds (or, with a negative `days`, subtracts) business days. `0` returns the date unchanged. */
+    addBusinessDays(date: DateString, days: number): DateString;
+    /** Business days after `start` up to and including `end`; negative when `end` is before `start`. */
+    businessDaysBetween(start: DateString, end: DateString): number;
+}
+export declare function createCalendar(options?: CalendarOptions): Calendar;

package/dist/calendar.js

@@ -0,0 +1,98 @@
+import { addDays, parseDate, weekdayOf } from './date.js';
+export const ADJUSTMENTS = [
+    'none',
+    'following',
+    'preceding',
+    'modifiedFollowing',
+    'modifiedPreceding',
+];
+/** A calendar with no business day within this many days is treated as broken. */
+const MAX_SEARCH_DAYS = 3660;
+export function createCalendar(options = {}) {
+    const weekend = new Set(options.weekend ?? [6, 7]);
+    for (const day of weekend) {
+        if (!Number.isInteger(day) || day < 1 || day > 7) {
+            throw new RangeError(`Invalid weekday ${day}: expected 1 (Monday) to 7 (Sunday)`);
+        }
+    }
+    if (weekend.size === 7)
+        throw new RangeError('A calendar needs at least one weekday that is not a weekend day');
+    const { holidays } = options;
+    let holidayCheck;
+    if (typeof holidays === 'function') {
+        holidayCheck = holidays;
+    }
+    else {
+        const dates = new Set();
+        for (const date of holidays ?? []) {
+            parseDate(date);
+            dates.add(date);
+        }
+        holidayCheck = (date) => dates.has(date);
+    }
+    const isWeekend = (date) => weekend.has(weekdayOf(date));
+    const isHoliday = (date) => {
+        parseDate(date);
+        return holidayCheck(date);
+    };
+    const isBusinessDay = (date) => !isWeekend(date) && !isHoliday(date);
+    /** The date itself if it is a business day, otherwise the nearest one in `direction`. */
+    function seek(date, direction) {
+        let current = date;
+        for (let i = 0; i <= MAX_SEARCH_DAYS; i++) {
+            if (isBusinessDay(current))
+                return current;
+            current = addDays(current, direction);
+        }
+        throw new RangeError(`No business day found within ${MAX_SEARCH_DAYS} days of ${date}`);
+    }
+    const sameMonth = (a, b) => a.slice(0, 7) === b.slice(0, 7);
+    return {
+        isWeekend,
+        isHoliday,
+        isBusinessDay,
+        adjust(date, adjustment) {
+            switch (adjustment) {
+                case 'none':
+                    parseDate(date);
+                    return date;
+                case 'following':
+                    return seek(date, 1);
+                case 'preceding':
+                    return seek(date, -1);
+                case 'modifiedFollowing': {
+                    const next = seek(date, 1);
+                    return sameMonth(next, date) ? next : seek(date, -1);
+                }
+                case 'modifiedPreceding': {
+                    const previous = seek(date, -1);
+                    return sameMonth(previous, date) ? previous : seek(date, 1);
+                }
+                default:
+                    throw new RangeError(`Unknown adjustment ${JSON.stringify(adjustment)}: expected one of ${ADJUSTMENTS.join(', ')}`);
+            }
+        },
+        addBusinessDays(date, days) {
+            if (!Number.isInteger(days))
+                throw new RangeError(`Invalid number of days ${days}: expected an integer`);
+            parseDate(date);
+            const direction = days < 0 ? -1 : 1;
+            let current = date;
+            for (let remaining = Math.abs(days); remaining > 0; remaining--) {
+                current = seek(addDays(current, direction), direction);
+            }
+            return current;
+        },
+        businessDaysBetween(start, end) {
+            parseDate(start);
+            parseDate(end);
+            const [first, last] = start <= end ? [start, end] : [end, start];
+            let count = 0;
+            for (let date = addDays(first, 1); date <= last; date = addDays(date, 1)) {
+                if (isBusinessDay(date))
+                    count++;
+            }
+            return start <= end || count === 0 ? count : -count;
+        },
+    };
+}

package/dist/date.d.ts

@@ -0,0 +1,25 @@
+/** A calendar date in ISO 8601 format, `YYYY-MM-DD`. No time of day, no time zone. */
+export type DateString = string;
+/** ISO 8601 weekday: 1 = Monday … 7 = Sunday. */
+export type Weekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+export declare function isLeapYear(year: number): boolean;
+/** Number of days in a month (`month` is 1–12). */
+export declare function daysInMonth(year: number, month: number): number;
+/** Splits a date string into its parts. Throws `RangeError` unless it is a real date in `YYYY-MM-DD` format. */
+export declare function parseDate(date: DateString): {
+    year: number;
+    month: number;
+    day: number;
+};
+/** `true` when `value` is a real calendar date in `YYYY-MM-DD` format. */
+export declare function isValidDate(value: unknown): value is DateString;
+export declare function makeDate(year: number, month: number, day: number): DateString;
+/** Adds (or, with a negative `days`, subtracts) calendar days. */
+export declare function addDays(date: DateString, days: number): DateString;
+/** ISO weekday of a date: 1 = Monday … 7 = Sunday. */
+export declare function weekdayOf(date: DateString): Weekday;
+/**
+ * Today's date in a time zone, e.g. `today('America/New_York')`.
+ * Defaults to the time zone of the running environment.
+ */
+export declare function today(timeZone?: string, now?: Date): DateString;

package/dist/date.js

@@ -0,0 +1,76 @@
+const MS_PER_DAY = 86_400_000;
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const pad2 = (value) => String(value).padStart(2, '0');
+export function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+/** Number of days in a month (`month` is 1–12). */
+export function daysInMonth(year, month) {
+    if (month === 2)
+        return isLeapYear(year) ? 29 : 28;
+    return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;
+}
+/** Splits a date string into its parts. Throws `RangeError` unless it is a real date in `YYYY-MM-DD` format. */
+export function parseDate(date) {
+    const match = typeof date === 'string' ? ISO_DATE.exec(date) : null;
+    if (match) {
+        const year = Number(match[1]);
+        const month = Number(match[2]);
+        const day = Number(match[3]);
+        if (month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth(year, month)) {
+            return { year, month, day };
+        }
+    }
+    throw new RangeError(`Invalid date ${JSON.stringify(date)}: expected a real date in YYYY-MM-DD format`);
+}
+/** `true` when `value` is a real calendar date in `YYYY-MM-DD` format. */
+export function isValidDate(value) {
+    try {
+        parseDate(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function makeDate(year, month, day) {
+    const date = `${String(year).padStart(4, '0')}-${pad2(month)}-${pad2(day)}`;
+    parseDate(date);
+    return date;
+}
+/** Days since 1970-01-01. Plain integer math, so no time zone or DST can shift a date. */
+function toDayNumber(date) {
+    const { year, month, day } = parseDate(date);
+    const time = new Date(0);
+    time.setUTCFullYear(year, month - 1, day);
+    return Math.round(time.getTime() / MS_PER_DAY);
+}
+function fromDayNumber(dayNumber) {
+    const time = new Date(dayNumber * MS_PER_DAY);
+    return makeDate(time.getUTCFullYear(), time.getUTCMonth() + 1, time.getUTCDate());
+}
+/** Adds (or, with a negative `days`, subtracts) calendar days. */
+export function addDays(date, days) {
+    if (!Number.isInteger(days))
+        throw new RangeError(`Invalid number of days ${days}: expected an integer`);
+    return fromDayNumber(toDayNumber(date) + days);
+}
+/** ISO weekday of a date: 1 = Monday … 7 = Sunday. */
+export function weekdayOf(date) {
+    // 1970-01-01 was a Thursday (ISO weekday 4).
+    return ((((toDayNumber(date) + 3) % 7) + 7) % 7) + 1;
+}
+/**
+ * Today's date in a time zone, e.g. `today('America/New_York')`.
+ * Defaults to the time zone of the running environment.
+ */
+export function today(timeZone, now = new Date()) {
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(now);
+    const part = (type) => parts.find((p) => p.type === type)?.value ?? '';
+    return `${part('year')}-${part('month')}-${part('day')}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { addDays, daysInMonth, isLeapYear, isValidDate, today, weekdayOf } from './date.js';
+export type { DateString, Weekday } from './date.js';
+export { createCalendar } from './calendar.js';
+export type { Adjustment, Calendar, CalendarOptions } from './calendar.js';
+export { nextDue, occurrences } from './rules.js';
+export type { BusinessDayOfMonthRule, DayOfMonthRule, Occurrence, OccurrenceOptions, Rule, WeekdayOfMonthRule, WeeklyRule, } from './rules.js';
+export { reminderDates } from './reminders.js';
+export type { ReminderOptions } from './reminders.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { addDays, daysInMonth, isLeapYear, isValidDate, today, weekdayOf } from './date.js';
+export { createCalendar } from './calendar.js';
+export { nextDue, occurrences } from './rules.js';
+export { reminderDates } from './reminders.js';

package/dist/reminders.d.ts

@@ -0,0 +1,13 @@
+import { type Calendar } from './calendar.js';
+import { type DateString } from './date.js';
+export interface ReminderOptions {
+    /** `'businessDays'` (default) skips weekends and holidays when counting back; `'calendarDays'` counts every day. */
+    unit?: 'businessDays' | 'calendarDays';
+    /** Defaults to a calendar with Saturday and Sunday as weekend days and no holidays. */
+    calendar?: Calendar;
+}
+/**
+ * The dates on which to remind someone of a deadline, sorted and without duplicates.
+ * Each offset is how many days before `due` a reminder goes out; `0` is the due date itself.
+ */
+export declare function reminderDates(due: DateString, offsets: readonly number[], options?: ReminderOptions): DateString[];

package/dist/reminders.js

@@ -0,0 +1,22 @@
+import { createCalendar } from './calendar.js';
+import { addDays, parseDate } from './date.js';
+/**
+ * The dates on which to remind someone of a deadline, sorted and without duplicates.
+ * Each offset is how many days before `due` a reminder goes out; `0` is the due date itself.
+ */
+export function reminderDates(due, offsets, options = {}) {
+    parseDate(due);
+    const unit = options.unit ?? 'businessDays';
+    if (unit !== 'businessDays' && unit !== 'calendarDays') {
+        throw new RangeError(`Unknown unit ${JSON.stringify(unit)}: expected "businessDays" or "calendarDays"`);
+    }
+    const calendar = options.calendar ?? createCalendar();
+    const dates = new Set();
+    for (const offset of offsets) {
+        if (!Number.isInteger(offset) || offset < 0) {
+            throw new RangeError(`Invalid offset ${offset}: expected a non-negative integer`);
+        }
+        dates.add(unit === 'businessDays' ? calendar.addBusinessDays(due, -offset) : addDays(due, -offset));
+    }
+    return [...dates].sort();
+}

package/dist/rules.d.ts

@@ -0,0 +1,57 @@
+import { type Adjustment, type Calendar } from './calendar.js';
+import { type DateString, type Weekday } from './date.js';
+interface MonthlyRuleBase {
+    /** Only these months (1–12). Use `[3, 6, 9, 12]` for quarterly or `[4]` for yearly deadlines. */
+    months?: readonly number[];
+}
+/** A fixed day of the month, e.g. "every 20th". Days past the end of a month use its last day. */
+export interface DayOfMonthRule extends MonthlyRuleBase {
+    type: 'dayOfMonth';
+    day: number | 'last';
+    adjust?: Adjustment;
+}
+/** The nth weekday of the month, e.g. "second Tuesday" (`nth: 2`) or "last Friday" (`nth: -1`). */
+export interface WeekdayOfMonthRule extends MonthlyRuleBase {
+    type: 'weekdayOfMonth';
+    weekday: Weekday;
+    /** 1 to 5 counts from the start of the month, -1 to -5 from the end. Months without it are skipped. */
+    nth: number;
+    adjust?: Adjustment;
+}
+/** The nth business day of the month, e.g. "5th business day" (`n: 5`) or "last business day" (`n: -1`). */
+export interface BusinessDayOfMonthRule extends MonthlyRuleBase {
+    type: 'businessDayOfMonth';
+    /** Positive counts from the start of the month, negative from the end. */
+    n: number;
+}
+/** Every week on the same weekday. */
+export interface WeeklyRule {
+    type: 'weekly';
+    weekday: Weekday;
+    adjust?: Adjustment;
+}
+export type Rule = DayOfMonthRule | WeekdayOfMonthRule | BusinessDayOfMonthRule | WeeklyRule;
+export interface Occurrence {
+    /** The date the rule names, before any business-day adjustment. */
+    nominal: DateString;
+    /** The date the deadline actually falls on. */
+    due: DateString;
+}
+export interface OccurrenceOptions {
+    /** First date to include (compared against `due`). */
+    from: DateString;
+    /** Last date to include (compared against `due`). */
+    to?: DateString;
+    /** Maximum number of occurrences to return. */
+    count?: number;
+    /** Defaults to a calendar with Saturday and Sunday as weekend days and no holidays. */
+    calendar?: Calendar;
+}
+/** Due dates of a rule from `from` on, until `to` or `count` is reached (at least one of them is required). */
+export declare function occurrences(rule: Rule, options: OccurrenceOptions): Occurrence[];
+/** The first occurrence due on or after `from`, or `undefined` if there is none within 100 years. */
+export declare function nextDue(rule: Rule, options: {
+    from: DateString;
+    calendar?: Calendar;
+}): Occurrence | undefined;
+export {};

package/dist/rules.js

@@ -0,0 +1,141 @@
+import { ADJUSTMENTS, createCalendar } from './calendar.js';
+import { addDays, daysInMonth, makeDate, parseDate, weekdayOf } from './date.js';
+/** Generation stops after this many months (or weeks) so a rule that rarely matches cannot loop forever. */
+const MAX_MONTHS = 1200;
+const MAX_WEEKS = 5220;
+/** Due dates of a rule from `from` on, until `to` or `count` is reached (at least one of them is required). */
+export function occurrences(rule, options) {
+    const { from, to, count } = options;
+    parseDate(from);
+    if (to !== undefined)
+        parseDate(to);
+    if (to === undefined && count === undefined)
+        throw new RangeError('Pass `to`, `count`, or both');
+    if (count !== undefined && (!Number.isInteger(count) || count < 0)) {
+        throw new RangeError(`Invalid count ${count}: expected a non-negative integer`);
+    }
+    validateRule(rule);
+    const calendar = options.calendar ?? createCalendar();
+    const result = [];
+    if (count === 0)
+        return result;
+    const nominals = rule.type === 'weekly' ? weeklyNominals(rule, from) : monthlyNominals(rule, from, calendar);
+    for (const nominal of nominals) {
+        const due = rule.type === 'businessDayOfMonth' ? nominal : calendar.adjust(nominal, rule.adjust ?? 'none');
+        // Adjustments never reorder dates, so the first due date past `to` ends the search.
+        if (to !== undefined && due > to)
+            break;
+        if (due < from)
+            continue;
+        result.push({ nominal, due });
+        if (result.length === count)
+            break;
+    }
+    return result;
+}
+/** The first occurrence due on or after `from`, or `undefined` if there is none within 100 years. */
+export function nextDue(rule, options) {
+    return occurrences(rule, { ...options, count: 1 })[0];
+}
+function* monthlyNominals(rule, from, calendar) {
+    const months = rule.months ? new Set(rule.months) : undefined;
+    // Start a month early: a date late last month may be adjusted forward into range.
+    let { year, month } = parseDate(from);
+    month -= 1;
+    if (month === 0) {
+        month = 12;
+        year -= 1;
+    }
+    for (let i = 0; i < MAX_MONTHS; i++) {
+        if (!months || months.has(month)) {
+            const nominal = nominalInMonth(rule, year, month, calendar);
+            if (nominal)
+                yield nominal;
+        }
+        month += 1;
+        if (month === 13) {
+            month = 1;
+            year += 1;
+        }
+    }
+}
+function* weeklyNominals(rule, from) {
+    // Start a week early: a date late last week may be adjusted forward into range.
+    const daysSinceWeekday = (weekdayOf(from) - rule.weekday + 7) % 7;
+    let nominal = addDays(from, -daysSinceWeekday - 7);
+    for (let i = 0; i < MAX_WEEKS; i++) {
+        yield nominal;
+        nominal = addDays(nominal, 7);
+    }
+}
+function nominalInMonth(rule, year, month, calendar) {
+    const lastDay = daysInMonth(year, month);
+    switch (rule.type) {
+        case 'dayOfMonth':
+            return makeDate(year, month, rule.day === 'last' ? lastDay : Math.min(rule.day, lastDay));
+        case 'weekdayOfMonth': {
+            let day;
+            if (rule.nth > 0) {
+                const firstWeekday = weekdayOf(makeDate(year, month, 1));
+                day = 1 + ((rule.weekday - firstWeekday + 7) % 7) + 7 * (rule.nth - 1);
+            }
+            else {
+                const lastWeekday = weekdayOf(makeDate(year, month, lastDay));
+                day = lastDay - ((lastWeekday - rule.weekday + 7) % 7) + 7 * (rule.nth + 1);
+            }
+            return day >= 1 && day <= lastDay ? makeDate(year, month, day) : undefined;
+        }
+        case 'businessDayOfMonth': {
+            const step = rule.n > 0 ? 1 : -1;
+            let seen = 0;
+            for (let day = step > 0 ? 1 : lastDay; day >= 1 && day <= lastDay; day += step) {
+                const date = makeDate(year, month, day);
+                if (calendar.isBusinessDay(date) && ++seen === Math.abs(rule.n))
+                    return date;
+            }
+            return undefined;
+        }
+    }
+}
+function validateRule(rule) {
+    const fail = (message) => {
+        throw new RangeError(`Invalid ${rule?.type ?? 'rule'} rule: ${message}`);
+    };
+    const isWeekday = (value) => Number.isInteger(value) && value >= 1 && value <= 7;
+    if ('months' in rule && rule.months !== undefined) {
+        if (rule.months.length === 0)
+            fail('`months` must not be empty');
+        for (const month of rule.months) {
+            if (!Number.isInteger(month) || month < 1 || month > 12)
+                fail(`month ${month} is not 1–12`);
+        }
+    }
+    if ('adjust' in rule && rule.adjust !== undefined && !ADJUSTMENTS.includes(rule.adjust)) {
+        fail(`unknown adjustment ${JSON.stringify(rule.adjust)}`);
+    }
+    switch (rule?.type) {
+        case 'dayOfMonth':
+            if (rule.day !== 'last' && !(Number.isInteger(rule.day) && rule.day >= 1 && rule.day <= 31)) {
+                fail('`day` must be 1–31 or "last"');
+            }
+            return;
+        case 'weekdayOfMonth':
+            if (!isWeekday(rule.weekday))
+                fail('`weekday` must be 1 (Monday) to 7 (Sunday)');
+            if (!Number.isInteger(rule.nth) || rule.nth === 0 || rule.nth < -5 || rule.nth > 5) {
+                fail('`nth` must be 1 to 5 or -1 to -5');
+            }
+            return;
+        case 'businessDayOfMonth':
+            if (!Number.isInteger(rule.n) || rule.n === 0 || Math.abs(rule.n) > 23) {
+                fail('`n` must be 1 to 23 or -1 to -23');
+            }
+            return;
+        case 'weekly':
+            if (!isWeekday(rule.weekday))
+                fail('`weekday` must be 1 (Monday) to 7 (Sunday)');
+            return;
+        default:
+            throw new RangeError(`Unknown rule type ${JSON.stringify(rule?.type)}`);
+    }
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@contalert/duedates",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Recurring deadlines with business days, holidays and reminders. Zero dependencies, time-zone safe.",
+  "keywords": [
+    "deadline",
+    "due-date",
+    "business-days",
+    "working-days",
+    "holidays",
+    "recurring",
+    "schedule",
+    "reminders",
+    "calendar",
+    "modified-following"
+  ],
+  "license": "MIT",
+  "author": "ContAlert Sistemas Ltda <contato@contalert.com.br> (https://contalert.com.br)",
+  "homepage": "https://github.com/contalert/duedates#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contalert/duedates.git"
+  },
+  "bugs": "https://github.com/contalert/duedates/issues",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  }
+}