/**
 * Core type definitions for the cronxt package.
 */
/** Names of the five standard cron fields in order. */
export type CronFieldName = 'minute' | 'hour' | 'dayOfMonth' | 'month' | 'dayOfWeek';
/** A tuple representing the five standard cron fields in order. */
export type CronTuple = readonly [minute: string, hour: string, dayOfMonth: string, month: string, dayOfWeek: string];
/** Special cron alias names. */
export type SpecialAlias = '@yearly' | '@annually' | '@monthly' | '@weekly' | '@daily' | '@midnight' | '@hourly';
/** A parsed cron expression represented as an object with named fields. */
export interface CronObject {
  /** Minute field (0-59) */
  minute: string;
  /** Hour field (0-23) */
  hour: string;
  /** Day of month field (1-31) */
  dayOfMonth: string;
  /** Month field (1-12 or JAN-DEC) */
  month: string;
  /** Day of week field (0-6 or MON-SUN, 0 = Sunday) */
  dayOfWeek: string;
}
/** Options for creating a cron expression from structured values. */
export interface CronOptions extends Partial<CronObject> {}
/** Options for next/previous run calculations. */
export interface RunOptions {
  /** Number of runs to return. Defaults to 1. */
  count?: number;
  /** IANA timezone string (e.g. 'America/New_York'). Defaults to UTC. */
  timezone?: string;
  /** Reference date after which to find the next run. Defaults to now. */
  after?: Date;
  /** Reference date before which to find the previous run. Defaults to now. */
  before?: Date;
}
/** Options for the schedule method. */
export interface ScheduleOptions {
  /** IANA timezone string (e.g. 'UTC'). Defaults to local system timezone. */
  timezone?: string;
}
/** Events emitted by a ScheduleController. */
export type ScheduleEvent = 'tick' | 'error' | 'stopped';
/** Controller returned by schedule() for managing a scheduled job. */
export interface ScheduleController {
  /** Stop the scheduled job. No further callbacks will fire. */
  stop(): void;
  /** Register an event handler. */
  on(event: ScheduleEvent, handler: EventHandler): ScheduleController;
  /** Remove an event handler. */
  off(event: ScheduleEvent, handler: EventHandler): ScheduleController;
}
/** A parsed range or value with an optional step size. */
export interface ParsedFieldComponent {
  /** First value in the range (inclusive). */
  start: number;
  /** Last value in the range (inclusive). */
  end: number;
  /** Step interval between values. */
  step: number;
}
/** A parsed cron field with pre-computed metadata. */
export interface ParsedField {
  /** Name of the cron field. */
  name: CronFieldName;
  /** Parsed ranges and step definitions. */
  components: ReadonlyArray<ParsedFieldComponent>;
  /** All matching values for this field. */
  values: ReadonlySet<number>;
  /** Sorted matching values in ascending order. */
  sorted: ReadonlyArray<number>;
  /** Smallest matching value. */
  min: number;
  /** Largest matching value. */
  max: number;
  /** Whether all possible values of this field are allowed. */
  wildcard: boolean;
}
/** A fully parsed cron expression. */
export interface ParsedCronExpression {
  /** Parsed data for each cron field. */
  fields: Record<CronFieldName, ParsedField>;
  /** Original cron expression passed to the parser. */
  source: string;
}
/** A cron expression string or a pre-parsed expression. */
export type CronInput = string | ParsedCronExpression;
/** @internal Metadata for a single cron field definition. */
export interface FieldDefinition {
  readonly name: CronFieldName;
  readonly min: number;
  readonly max: number;
  readonly aliases: Record<string, number>;
}
/** @internal Cron-relevant components from a Date. */
export interface DateParts {
  year: number;
  month: number;
  day: number;
  hour: number;
  minute: number;
}
/** @internal Scheduler event handler function. */
export type EventHandler = (...args: any[]) => void;