@holo-js/schedule 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Holo-JS contributors
+
+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/dist/.holo-build-fingerprint

@@ -0,0 +1 @@
+f30ad13d2d7cb3e68f51eb3c29939783513dbcefc33be1231018bb2bf624a76c

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+type ScheduleCallback = () => unknown;
+interface SchedulableJob<TPayload> {
+    dispatch(payload: TPayload): PromiseLike<unknown>;
+}
+type ScheduledTaskAction = {
+    readonly kind: 'command';
+    readonly command: string;
+    readonly argv: readonly string[];
+} | {
+    readonly kind: 'job';
+    readonly job: SchedulableJob<never>;
+    readonly dispatch: () => PromiseLike<unknown>;
+} | {
+    readonly kind: 'call';
+    readonly callback: ScheduleCallback;
+};
+type ScheduledTaskState = {
+    readonly action: ScheduledTaskAction;
+    readonly expression: string;
+    readonly timezone?: string;
+    readonly description?: string;
+    readonly withoutOverlapping: boolean;
+    readonly expiresAtMinutes: number;
+    readonly onOneServer: boolean;
+};
+declare const SCHEDULED_TASK_STATE: unique symbol;
+type CronValue = number | string;
+type CronValues = number | readonly number[];
+declare class ScheduledTask {
+    #private;
+    constructor(action: ScheduledTaskAction);
+    get [SCHEDULED_TASK_STATE](): ScheduledTaskState;
+    cron(expression: string): this;
+    timezone(timezone: string): this;
+    name(description: string): this;
+    withoutOverlapping(expiresAtMinutes?: number): this;
+    onOneServer(): this;
+    everyMinute(): this;
+    everyTwoMinutes(): this;
+    everyThreeMinutes(): this;
+    everyFourMinutes(): this;
+    everyFiveMinutes(): this;
+    everyTenMinutes(): this;
+    everyFifteenMinutes(): this;
+    everyThirtyMinutes(): this;
+    hourly(): this;
+    hourlyAt(offset: CronValues): this;
+    everyOddHour(offset?: CronValues): this;
+    everyTwoHours(offset?: CronValues): this;
+    everyThreeHours(offset?: CronValues): this;
+    everyFourHours(offset?: CronValues): this;
+    everySixHours(offset?: CronValues): this;
+    daily(): this;
+    at(time: string): this;
+    dailyAt(time: string): this;
+    twiceDaily(first?: number, second?: number): this;
+    twiceDailyAt(first?: number, second?: number, offset?: number): this;
+    weekdays(): this;
+    weekends(): this;
+    mondays(): this;
+    tuesdays(): this;
+    wednesdays(): this;
+    thursdays(): this;
+    fridays(): this;
+    saturdays(): this;
+    sundays(): this;
+    days(...days: ReadonlyArray<CronValue | readonly number[]>): this;
+    weekly(): this;
+    weeklyOn(dayOfWeek: CronValues, time?: string): this;
+    monthly(): this;
+    monthlyOn(dayOfMonth?: number, time?: string): this;
+    twiceMonthly(first?: number, second?: number, time?: string): this;
+    quarterly(): this;
+    quarterlyOn(dayOfQuarter?: number, time?: string): this;
+    yearly(): this;
+    yearlyOn(month?: number, dayOfMonth?: number, time?: string): this;
+    private hourBasedSchedule;
+    private spliceIntoPosition;
+}
+
+declare const SCHEDULE_DEFINITION: unique symbol;
+interface ScheduleDefinition {
+    readonly [SCHEDULE_DEFINITION]: true;
+    readonly tasks: readonly ScheduledTask[];
+}
+declare class Schedule {
+    #private;
+    command(command: string): ScheduledTask;
+    job<TPayload>(job: SchedulableJob<TPayload>, payload: NoInfer<TPayload>): ScheduledTask;
+    call(callback: ScheduleCallback): ScheduledTask;
+    get tasks(): readonly ScheduledTask[];
+    private add;
+}
+declare function defineSchedule(define: (schedule: Schedule) => void): ScheduleDefinition;
+declare function isScheduleDefinition(value: unknown): value is ScheduleDefinition;
+
+declare class CronExpressionError extends Error {
+    constructor(expression: string, reason: string);
+}
+
+type ScheduledTaskOutcome = 'ran' | 'failed' | 'skipped-overlapping' | 'skipped-other-server';
+interface ScheduledTaskReport {
+    readonly summary: string;
+    readonly outcome: ScheduledTaskOutcome;
+    readonly error?: Error;
+}
+interface ScheduleRunOptions {
+    readonly now: Date;
+    readonly timezone: string;
+    readonly signal?: AbortSignal;
+    runCommand(argv: readonly string[]): Promise<number>;
+    onTaskFinished?(report: ScheduledTaskReport): void;
+}
+interface ScheduledTaskListing {
+    readonly expression: string;
+    readonly summary: string;
+    readonly timezone: string;
+    readonly nextDueAt: Date;
+}
+declare function runDueScheduledTasks(definition: ScheduleDefinition, options: ScheduleRunOptions): Promise<readonly ScheduledTaskReport[]>;
+declare function listScheduledTasks(definition: ScheduleDefinition, options: {
+    readonly now: Date;
+    readonly timezone: string;
+}): Promise<readonly ScheduledTaskListing[]>;
+
+export { CronExpressionError, Schedule, ScheduledTask, defineSchedule, isScheduleDefinition, listScheduledTasks, runDueScheduledTasks };
+export type { SchedulableJob, ScheduleCallback, ScheduleDefinition, ScheduleRunOptions, ScheduledTaskListing, ScheduledTaskOutcome, ScheduledTaskReport };

package/dist/index.mjs

@@ -0,0 +1,660 @@
+// src/cron.ts
+var MINUTE_MS = 6e4;
+var HOUR_MS = 60 * MINUTE_MS;
+var MAX_SEARCH_DAYS = 366 * 9;
+var MACROS = {
+  "@yearly": "0 0 1 1 *",
+  "@annually": "0 0 1 1 *",
+  "@monthly": "0 0 1 * *",
+  "@weekly": "0 0 * * 0",
+  "@daily": "0 0 * * *",
+  "@midnight": "0 0 * * *",
+  "@hourly": "0 * * * *"
+};
+var MONTH_NAMES = ["JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"];
+var WEEKDAY_NAMES = ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"];
+var ISO_WEEKDAY_NAMES = ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"];
+var FIELD_SPECS = [
+  { label: "minute", min: 0, max: 59 },
+  { label: "hour", min: 0, max: 23 },
+  { label: "day of month", min: 1, max: 31 },
+  { label: "month", min: 1, max: 12, names: MONTH_NAMES, nameOffset: 1 },
+  { label: "day of week", min: 0, max: 7, names: ISO_WEEKDAY_NAMES, nameOffset: 1 }
+];
+var CronExpressionError = class extends Error {
+  constructor(expression, reason) {
+    super(`[@holo-js/schedule] Invalid cron expression "${expression}": ${reason}`);
+    this.name = "CronExpressionError";
+  }
+};
+function parseValue(token, spec, expression) {
+  const nameIndex = spec.names?.indexOf(token.toUpperCase()) ?? -1;
+  if (nameIndex >= 0) return nameIndex + (spec.nameOffset ?? 0);
+  if (!/^\d+$/.test(token)) throw new CronExpressionError(expression, `"${token}" is not a valid ${spec.label}.`);
+  const value = Number(token);
+  if (value < spec.min || value > spec.max) {
+    throw new CronExpressionError(expression, `${spec.label} ${value} is outside ${spec.min}-${spec.max}.`);
+  }
+  return value;
+}
+function leadingInteger(token) {
+  return Number(/^\d+/.exec(token)?.[0] ?? 0);
+}
+function parsePart(part, spec, expression) {
+  const [range = "", stepToken, ...extra] = part.split("/");
+  if (extra.length > 0 || range === "") throw new CronExpressionError(expression, `"${part}" is not a valid ${spec.label}.`);
+  const step = stepToken === void 0 ? 1 : Number(stepToken);
+  if (!Number.isInteger(step) || step < 1 || stepToken !== void 0 && !/^\d+$/.test(stepToken)) {
+    throw new CronExpressionError(expression, `"${part}" has an invalid step.`);
+  }
+  if (stepToken !== void 0 && range !== "*" && !range.includes("-")) {
+    throw new CronExpressionError(expression, `"${part}" steps over a single value; use a range such as "${range}-${spec.max}/${stepToken}".`);
+  }
+  let start = spec.min;
+  let end = spec.max;
+  if (range !== "*") {
+    const [startToken = "", endToken, ...rest] = range.split("-");
+    if (rest.length > 0) throw new CronExpressionError(expression, `"${part}" is not a valid ${spec.label}.`);
+    start = parseValue(startToken, spec, expression);
+    end = endToken === void 0 ? stepToken === void 0 ? start : spec.max : parseValue(endToken, spec, expression);
+    if (stepToken !== void 0) {
+      start = leadingInteger(startToken);
+      end = leadingInteger(endToken ?? startToken);
+      if (start < spec.min || end > spec.max) {
+        throw new CronExpressionError(expression, `"${part}" reads as ${start}-${end}, outside ${spec.min}-${spec.max}; use numbers in stepped ranges.`);
+      }
+    }
+    if (end < start) throw new CronExpressionError(expression, `"${part}" is a descending range.`);
+  }
+  if (step > spec.max) return [spec.min + step % (spec.max - spec.min + 1)];
+  const values = [];
+  for (let value = start; value <= end; value += step) values.push(value);
+  return values;
+}
+function daysInMonth(year, month) {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+function isWeekday(date) {
+  const weekday = date.getUTCDay();
+  return weekday >= 1 && weekday <= 5;
+}
+function nearestWeekday(year, month, target) {
+  const rolledOver = new Date(Date.UTC(year, month - 1, target));
+  if (isWeekday(rolledOver)) return rolledOver.getUTCDate();
+  const lastDay = daysInMonth(rolledOver.getUTCFullYear(), rolledOver.getUTCMonth() + 1);
+  for (const offset of [-1, 1, -2, 2]) {
+    const day = target + offset;
+    if (day < 1 || day > lastDay) continue;
+    const candidate = new Date(Date.UTC(year, month - 1, day));
+    if (isWeekday(candidate) && candidate.getUTCMonth() + 1 === month) return candidate.getUTCDate();
+  }
+  return void 0;
+}
+function parseDayOfMonthRule(part, source, spec, expression) {
+  const special = part === "L" || part.endsWith("W");
+  if (!special) return void 0;
+  if (source.includes(",")) throw new CronExpressionError(expression, `"${part}" can't be combined with other days of the month.`);
+  if (part === "L") return (clock) => clock.day === daysInMonth(clock.year, clock.month);
+  const prefix = part.slice(0, -1);
+  const target = prefix === "L" ? 0 : parseValue(prefix, spec, expression);
+  return (clock) => nearestWeekday(clock.year, clock.month, target) === clock.day;
+}
+function parseDayOfWeekRule(part, spec, expression) {
+  const last = /^(\w+)L$/i.exec(part);
+  if (last) {
+    const weekday2 = parseValue(last[1], spec, expression) % 7;
+    return (clock) => clock.weekday === weekday2 && daysInMonth(clock.year, clock.month) - clock.day < 7;
+  }
+  const nth = /^(\w+)#(\d+)$/.exec(part);
+  if (!nth) return void 0;
+  const weekday = parseValue(nth[1], spec, expression) % 7;
+  const occurrence = Number(nth[2]);
+  if (occurrence < 1 || occurrence > 5) throw new CronExpressionError(expression, `"${part}" must name the 1st to 5th weekday of the month.`);
+  return (clock) => clock.weekday === weekday && Math.ceil(clock.day / 7) === occurrence;
+}
+function parseRule(part, source, spec, expression) {
+  if (spec.label === "day of month") return parseDayOfMonthRule(part, source, spec, expression);
+  if (spec.label === "day of week") return parseDayOfWeekRule(part, spec, expression);
+  return void 0;
+}
+function parseDayOfWeekPart(part, spec, expression) {
+  const literal = spec.names?.indexOf(part.toUpperCase()) ?? -1;
+  const bounds = (literal >= 0 ? String(literal + (spec.nameOffset ?? 0)) : part).split("-");
+  if (bounds[0] === "7") bounds[0] = "0";
+  else if (bounds[1] === "0") bounds[1] = "7";
+  const normalized = bounds.join("-");
+  const sundayIsSeven = normalized.includes("7");
+  return parsePart(normalized, spec, expression).flatMap((value) => {
+    if (sundayIsSeven) return value === 0 ? [] : [value % 7];
+    return value === 7 ? [] : [value];
+  });
+}
+function parseField(source, spec, expression) {
+  if (source === "?") return { values: new Set(parsePart("*", spec, expression)), rules: [], restricted: false };
+  const values = /* @__PURE__ */ new Set();
+  const rules = [];
+  for (const part of source.split(",")) {
+    const rule = parseRule(part, source, spec, expression);
+    if (rule) {
+      rules.push(rule);
+      continue;
+    }
+    const parsed = spec.label === "day of week" ? parseDayOfWeekPart(part, spec, expression) : parsePart(part, spec, expression);
+    for (const value of parsed) values.add(value);
+  }
+  return { values, rules, restricted: source !== "*" };
+}
+function normalizeCronExpression(expression) {
+  return MACROS[expression.trim().toLowerCase()] ?? expression.trim();
+}
+function parseCronExpression(expression) {
+  const fields = normalizeCronExpression(expression).split(/\s+/);
+  if (fields.length !== 5) throw new CronExpressionError(expression, "expected 5 fields.");
+  if ([fields[0], fields[1], fields[3]].includes("?") || fields[2] === "?" && fields[4] === "?") {
+    throw new CronExpressionError(expression, '"?" is only allowed in one of the day-of-month and day-of-week fields.');
+  }
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = fields.map((field, index) => parseField(field, FIELD_SPECS[index], expression));
+  return { minute, hour, dayOfMonth, month, dayOfWeek };
+}
+var formatters = /* @__PURE__ */ new Map();
+function wallClock(date, timezone) {
+  let formatter = formatters.get(timezone);
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat("en-US", {
+      timeZone: timezone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      hour: "numeric",
+      minute: "numeric",
+      weekday: "short"
+    });
+    formatters.set(timezone, formatter);
+  }
+  const parts = Object.fromEntries(formatter.formatToParts(date).map((part) => [part.type, part.value]));
+  return {
+    year: Number(parts.year),
+    month: Number(parts.month),
+    day: Number(parts.day),
+    hour: Number(parts.hour),
+    minute: Number(parts.minute),
+    weekday: WEEKDAY_NAMES.indexOf(String(parts.weekday).toUpperCase())
+  };
+}
+function dayMatches(schedule, clock) {
+  if (!schedule.month.values.has(clock.month)) return false;
+  const dayOfMonth = schedule.dayOfMonth.values.has(clock.day) || schedule.dayOfMonth.rules.some((rule) => rule(clock));
+  const dayOfWeek = schedule.dayOfWeek.values.has(clock.weekday) || schedule.dayOfWeek.rules.some((rule) => rule(clock));
+  if (schedule.dayOfMonth.restricted && schedule.dayOfWeek.restricted) return dayOfMonth || dayOfWeek;
+  return dayOfMonth && dayOfWeek;
+}
+function assertTimezone(timezone) {
+  try {
+    return new Intl.DateTimeFormat("en-US", { timeZone: timezone }).resolvedOptions().timeZone;
+  } catch {
+    throw new RangeError(`[@holo-js/schedule] Invalid timezone: ${timezone}`);
+  }
+}
+function formatHourMinute(date, timezone) {
+  const clock = wallClock(date, timezone);
+  return `${String(clock.hour).padStart(2, "0")}${String(clock.minute).padStart(2, "0")}`;
+}
+function transitionHourShift(time, timezone) {
+  const before = offsetAt(time - HOUR_MS, timezone);
+  if (before === offsetAt(time, timezone)) return void 0;
+  const change = offsetAt(time + HOUR_MS, timezone) - before;
+  if (change >= HOUR_MS) return -1;
+  if (change <= -HOUR_MS) return 1;
+  return void 0;
+}
+function hourMatches(schedule, time, clock, timezone) {
+  if (schedule.hour.values.has(clock.hour)) return true;
+  const shift = transitionHourShift(time, timezone);
+  return shift !== void 0 && schedule.hour.values.has(clock.hour + shift);
+}
+function cronMatches(schedule, date, timezone) {
+  const clock = wallClock(date, timezone);
+  return dayMatches(schedule, clock) && schedule.minute.values.has(clock.minute) && hourMatches(schedule, date.getTime(), clock, timezone);
+}
+function offsetAt(time, timezone) {
+  const clock = wallClock(new Date(time), timezone);
+  return Date.UTC(clock.year, clock.month - 1, clock.day, clock.hour, clock.minute) - Math.floor(time / MINUTE_MS) * MINUTE_MS;
+}
+function nextLocalMidnight(time, clock, timezone) {
+  const midnight = Date.UTC(clock.year, clock.month - 1, clock.day + 1);
+  const estimate = midnight - offsetAt(midnight, timezone);
+  const candidate = Math.min(estimate, midnight - offsetAt(estimate, timezone));
+  return Math.max(time + MINUTE_MS, candidate);
+}
+function nextCronDate(schedule, after, timezone, expression) {
+  let time = Math.floor(after.getTime() / MINUTE_MS) * MINUTE_MS + MINUTE_MS;
+  const limit = time + MAX_SEARCH_DAYS * 24 * 60 * MINUTE_MS;
+  while (time <= limit) {
+    const clock = wallClock(new Date(time), timezone);
+    if (!dayMatches(schedule, clock)) {
+      time = nextLocalMidnight(time, clock, timezone);
+      continue;
+    }
+    if (!hourMatches(schedule, time, clock, timezone)) {
+      time += transitionHourShift(time, timezone) === void 0 ? (60 - clock.minute) * MINUTE_MS : MINUTE_MS;
+      continue;
+    }
+    if (schedule.minute.values.has(clock.minute)) return new Date(time);
+    time += MINUTE_MS;
+  }
+  throw new CronExpressionError(expression, "it never matches a date.");
+}
+
+// src/task.ts
+var SCHEDULED_TASK_STATE = /* @__PURE__ */ Symbol.for("holo-js.schedule.task-state");
+var MONDAY = 1;
+var FRIDAY = 5;
+var SATURDAY = 6;
+var SUNDAY = 0;
+function joinValues(values) {
+  return typeof values === "number" ? String(values) : values.join(",");
+}
+function parseTime(time) {
+  const match = /^(\d{1,2})(?::(\d{1,2}))?$/.exec(time.trim());
+  const hour = Number(match?.[1]);
+  const minute = Number(match?.[2] ?? 0);
+  if (!match || hour > 23 || minute > 59) {
+    throw new RangeError(`[@holo-js/schedule] Invalid time "${time}". Expected HH:MM.`);
+  }
+  return { hour, minute };
+}
+var ScheduledTask = class {
+  #state;
+  constructor(action) {
+    this.#state = {
+      action,
+      expression: "* * * * *",
+      withoutOverlapping: false,
+      expiresAtMinutes: 1440,
+      onOneServer: false
+    };
+  }
+  get [SCHEDULED_TASK_STATE]() {
+    return this.#state;
+  }
+  cron(expression) {
+    parseCronExpression(expression);
+    this.#state = { ...this.#state, expression: normalizeCronExpression(expression) };
+    return this;
+  }
+  timezone(timezone) {
+    this.#state = { ...this.#state, timezone: assertTimezone(timezone) };
+    return this;
+  }
+  name(description) {
+    if (!description.trim()) throw new Error("[@holo-js/schedule] Scheduled task names must not be empty.");
+    this.#state = { ...this.#state, description };
+    return this;
+  }
+  withoutOverlapping(expiresAtMinutes = 1440) {
+    if (!Number.isInteger(expiresAtMinutes) || expiresAtMinutes < 1) {
+      throw new RangeError("[@holo-js/schedule] withoutOverlapping() expects a positive whole number of minutes.");
+    }
+    this.#state = { ...this.#state, withoutOverlapping: true, expiresAtMinutes };
+    return this;
+  }
+  onOneServer() {
+    this.#state = { ...this.#state, onOneServer: true };
+    return this;
+  }
+  everyMinute() {
+    return this.spliceIntoPosition(1, "*");
+  }
+  everyTwoMinutes() {
+    return this.spliceIntoPosition(1, "*/2");
+  }
+  everyThreeMinutes() {
+    return this.spliceIntoPosition(1, "*/3");
+  }
+  everyFourMinutes() {
+    return this.spliceIntoPosition(1, "*/4");
+  }
+  everyFiveMinutes() {
+    return this.spliceIntoPosition(1, "*/5");
+  }
+  everyTenMinutes() {
+    return this.spliceIntoPosition(1, "*/10");
+  }
+  everyFifteenMinutes() {
+    return this.spliceIntoPosition(1, "*/15");
+  }
+  everyThirtyMinutes() {
+    return this.spliceIntoPosition(1, "*/30");
+  }
+  hourly() {
+    return this.spliceIntoPosition(1, 0);
+  }
+  hourlyAt(offset) {
+    return this.hourBasedSchedule(joinValues(offset), "*");
+  }
+  everyOddHour(offset = 0) {
+    return this.hourBasedSchedule(joinValues(offset), "1-23/2");
+  }
+  everyTwoHours(offset = 0) {
+    return this.hourBasedSchedule(joinValues(offset), "*/2");
+  }
+  everyThreeHours(offset = 0) {
+    return this.hourBasedSchedule(joinValues(offset), "*/3");
+  }
+  everyFourHours(offset = 0) {
+    return this.hourBasedSchedule(joinValues(offset), "*/4");
+  }
+  everySixHours(offset = 0) {
+    return this.hourBasedSchedule(joinValues(offset), "*/6");
+  }
+  daily() {
+    return this.hourBasedSchedule(0, 0);
+  }
+  at(time) {
+    return this.dailyAt(time);
+  }
+  dailyAt(time) {
+    const { hour, minute } = parseTime(time);
+    return this.hourBasedSchedule(minute, hour);
+  }
+  twiceDaily(first = 1, second = 13) {
+    return this.twiceDailyAt(first, second, 0);
+  }
+  twiceDailyAt(first = 1, second = 13, offset = 0) {
+    return this.hourBasedSchedule(offset, `${first},${second}`);
+  }
+  weekdays() {
+    return this.days(`${MONDAY}-${FRIDAY}`);
+  }
+  weekends() {
+    return this.days(`${SATURDAY},${SUNDAY}`);
+  }
+  mondays() {
+    return this.days(1);
+  }
+  tuesdays() {
+    return this.days(2);
+  }
+  wednesdays() {
+    return this.days(3);
+  }
+  thursdays() {
+    return this.days(4);
+  }
+  fridays() {
+    return this.days(5);
+  }
+  saturdays() {
+    return this.days(6);
+  }
+  sundays() {
+    return this.days(0);
+  }
+  days(...days) {
+    return this.spliceIntoPosition(5, days.flat().join(","));
+  }
+  weekly() {
+    return this.spliceIntoPosition(1, 0).spliceIntoPosition(2, 0).spliceIntoPosition(5, 0);
+  }
+  weeklyOn(dayOfWeek, time = "0:0") {
+    return this.dailyAt(time).days(joinValues(dayOfWeek));
+  }
+  monthly() {
+    return this.spliceIntoPosition(1, 0).spliceIntoPosition(2, 0).spliceIntoPosition(3, 1);
+  }
+  monthlyOn(dayOfMonth = 1, time = "0:0") {
+    return this.dailyAt(time).spliceIntoPosition(3, dayOfMonth);
+  }
+  twiceMonthly(first = 1, second = 16, time = "0:0") {
+    return this.dailyAt(time).spliceIntoPosition(3, `${first},${second}`);
+  }
+  quarterly() {
+    return this.monthly().spliceIntoPosition(4, "1-12/3");
+  }
+  quarterlyOn(dayOfQuarter = 1, time = "0:0") {
+    return this.dailyAt(time).spliceIntoPosition(3, dayOfQuarter).spliceIntoPosition(4, "1-12/3");
+  }
+  yearly() {
+    return this.monthly().spliceIntoPosition(4, 1);
+  }
+  yearlyOn(month = 1, dayOfMonth = 1, time = "0:0") {
+    return this.dailyAt(time).spliceIntoPosition(3, dayOfMonth).spliceIntoPosition(4, month);
+  }
+  hourBasedSchedule(minutes, hours) {
+    return this.spliceIntoPosition(1, minutes).spliceIntoPosition(2, hours);
+  }
+  spliceIntoPosition(position, value) {
+    const segments = this.#state.expression.split(/\s+/);
+    segments[position - 1] = String(value);
+    return this.cron(segments.join(" "));
+  }
+};
+
+// src/schedule.ts
+var SCHEDULE_DEFINITION = /* @__PURE__ */ Symbol.for("holo-js.schedule.definition");
+var DOUBLE_QUOTE_ESCAPES = /* @__PURE__ */ new Set(["$", "`", '"', "\\", "\n"]);
+function tokenizeCommand(command) {
+  const tokens = [];
+  let token;
+  let quote;
+  for (let index = 0; index < command.length; index += 1) {
+    const character = command[index];
+    const next = command[index + 1];
+    if (quote === "'") {
+      if (character === quote) quote = void 0;
+      else token += character;
+      continue;
+    }
+    if (character === "\\" && next !== void 0 && (quote === void 0 || DOUBLE_QUOTE_ESCAPES.has(next))) {
+      index += 1;
+      if (next !== "\n") token = (token ?? "") + next;
+      continue;
+    }
+    if (quote === '"') {
+      if (character === quote) quote = void 0;
+      else token += character;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      if (token !== void 0) tokens.push(token);
+      token = void 0;
+      continue;
+    }
+    token ??= "";
+    if (character === '"' || character === "'") quote = character;
+    else token += character;
+  }
+  if (quote) throw new Error(`[@holo-js/schedule] Scheduled command has an unterminated ${quote} quote: ${command}`);
+  if (token !== void 0) tokens.push(token);
+  return tokens;
+}
+var Schedule = class {
+  #tasks = [];
+  command(command) {
+    const argv = tokenizeCommand(command);
+    if (argv.length === 0) throw new Error("[@holo-js/schedule] Scheduled commands must name a command.");
+    return this.add(new ScheduledTask({ kind: "command", command: command.trim(), argv }));
+  }
+  job(job, payload) {
+    return this.add(new ScheduledTask({ kind: "job", job, dispatch: () => job.dispatch(payload) }));
+  }
+  call(callback) {
+    return this.add(new ScheduledTask({ kind: "call", callback }));
+  }
+  get tasks() {
+    return [...this.#tasks];
+  }
+  add(task) {
+    this.#tasks.push(task);
+    return task;
+  }
+};
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && typeof value.then === "function";
+}
+function defineSchedule(define) {
+  let tasks;
+  return Object.freeze({
+    [SCHEDULE_DEFINITION]: true,
+    get tasks() {
+      if (!tasks) {
+        const schedule = new Schedule();
+        const result = define(schedule);
+        if (isPromiseLike(result)) {
+          Promise.resolve(result).catch(() => void 0);
+          throw new Error("[@holo-js/schedule] defineSchedule() callbacks must define tasks synchronously.");
+        }
+        tasks = Object.freeze(schedule.tasks);
+      }
+      return tasks;
+    }
+  });
+}
+function isScheduleDefinition(value) {
+  if (typeof value !== "object" || value === null || value[SCHEDULE_DEFINITION] !== true) return false;
+  const tasks = Object.getOwnPropertyDescriptor(value, "tasks");
+  return typeof tasks?.get === "function" || Array.isArray(tasks?.value);
+}
+
+// src/runner.ts
+import { createHash } from "crypto";
+var ONE_SERVER_LOCK_SECONDS = 3600;
+function sha1(value) {
+  return createHash("sha1").update(value).digest("hex");
+}
+function stateOf(task) {
+  return task[SCHEDULED_TASK_STATE];
+}
+async function resolveJobName(job) {
+  try {
+    const { queueJobInternals } = await import("@holo-js/queue");
+    return queueJobInternals.resolveQueueJobDefinitionName(job);
+  } catch {
+    return void 0;
+  }
+}
+async function requireJobName(state, job) {
+  const name = state.description ?? await resolveJobName(job);
+  if (name === void 0) {
+    throw new Error("[@holo-js/schedule] Name this job with name() to use withoutOverlapping() or onOneServer(); it has no registered job name.");
+  }
+  return name;
+}
+async function describeTask(state) {
+  if (state.description) return state.description;
+  switch (state.action.kind) {
+    case "command":
+      return `holo ${state.action.command}`;
+    case "job":
+      return await resolveJobName(state.action.job) ?? "Job";
+    case "call":
+      return "Closure";
+  }
+}
+async function mutexName(state) {
+  switch (state.action.kind) {
+    case "command":
+      return `framework/schedule-${sha1(state.expression + state.action.command)}`;
+    case "job":
+      return `framework/schedule-${sha1(await requireJobName(state, state.action.job))}`;
+    case "call":
+      return `framework/schedule-${sha1(state.description ?? state.expression + state.action.callback.toString())}`;
+  }
+}
+async function cacheLock(name, seconds) {
+  const { cacheFacade } = await import("@holo-js/cache");
+  return cacheFacade.lock(name, seconds);
+}
+async function execute(state, summary, options) {
+  switch (state.action.kind) {
+    case "command": {
+      const exitCode = await options.runCommand(state.action.argv);
+      if (exitCode !== 0) throw new Error(`Scheduled command [${summary}] failed with exit code [${exitCode}].`);
+      return;
+    }
+    case "job":
+      await state.action.dispatch();
+      return;
+    case "call":
+      if (await state.action.callback() === false) {
+        throw new Error(`Scheduled task [${summary}] failed with exit code [1].`);
+      }
+  }
+}
+async function isLockFree(name, seconds) {
+  const probe = await cacheLock(name, seconds);
+  return await probe.get(() => true) === true;
+}
+async function acquireServer(name, options, decisions) {
+  let decision = decisions.get(name);
+  if (!decision) {
+    decision = cacheLock(`${name}${formatHourMinute(options.now, options.timezone)}`, ONE_SERVER_LOCK_SECONDS).then(async (lock) => await lock.get() === true);
+    decisions.set(name, decision);
+  }
+  return await decision;
+}
+async function runTask(state, options, serverDecisions) {
+  const summary = await describeTask(state);
+  if (!state.withoutOverlapping && !state.onOneServer) {
+    if (options.signal?.aborted) return void 0;
+    await execute(state, summary, options);
+    return { summary, outcome: "ran" };
+  }
+  const name = await mutexName(state);
+  if (state.withoutOverlapping && !await isLockFree(name, state.expiresAtMinutes * 60)) {
+    return { summary, outcome: "skipped-overlapping" };
+  }
+  if (state.onOneServer && !await acquireServer(name, options, serverDecisions)) {
+    return { summary, outcome: "skipped-other-server" };
+  }
+  const overlapLock = state.withoutOverlapping ? await cacheLock(name, state.expiresAtMinutes * 60) : void 0;
+  if (overlapLock && await overlapLock.get() !== true) return { summary, outcome: "skipped-overlapping" };
+  try {
+    if (options.signal?.aborted) return void 0;
+    await execute(state, summary, options);
+    return { summary, outcome: "ran" };
+  } finally {
+    await overlapLock?.release();
+  }
+}
+function isDue(state, now, timezone) {
+  return cronMatches(parseCronExpression(state.expression), now, state.timezone ?? timezone);
+}
+async function runDueScheduledTasks(definition, options) {
+  const due = definition.tasks.map(stateOf).filter((state) => isDue(state, options.now, options.timezone));
+  const reports = [];
+  const serverDecisions = /* @__PURE__ */ new Map();
+  for (const state of due) {
+    if (options.signal?.aborted) break;
+    const report = await runTask(state, options, serverDecisions).catch(async (error) => ({
+      summary: await describeTask(state).catch(() => state.action.kind),
+      outcome: "failed",
+      error: error instanceof Error ? error : new Error(String(error))
+    }));
+    if (!report) break;
+    reports.push(report);
+    options.onTaskFinished?.(report);
+  }
+  return reports;
+}
+async function listScheduledTasks(definition, options) {
+  return await Promise.all(definition.tasks.map(stateOf).map(async (state) => {
+    const timezone = state.timezone ?? options.timezone;
+    return {
+      expression: state.expression,
+      summary: await describeTask(state),
+      timezone,
+      nextDueAt: nextCronDate(parseCronExpression(state.expression), options.now, timezone, state.expression)
+    };
+  }));
+}
+export {
+  CronExpressionError,
+  Schedule,
+  ScheduledTask,
+  defineSchedule,
+  isScheduleDefinition,
+  listScheduledTasks,
+  runDueScheduledTasks
+};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@holo-js/schedule",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Holo-JS Framework - task scheduling",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cobraprojects/holo-js.git",
+    "directory": "packages/schedule"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "stub": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest --run"
+  },
+  "peerDependencies": {
+    "@holo-js/cache": ">=0.4.0",
+    "@holo-js/queue": ">=0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@holo-js/cache": {
+      "optional": true
+    },
+    "@holo-js/queue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@holo-js/cache": "^0.5.0",
+    "@holo-js/queue": "^0.5.0",
+    "@types/node": "^22.20.5",
+    "tsup": "^9.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.5"
+  },
+  "engines": {
+    "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.